개발자를 위한 Invoice Radar 플러그인 핸드북에 오신 것을 환영합니다!
이 가이드는 다양한 플랫폼에서 송장과 영수증을 가져오는 맞춤형 플러그인을 만드는 데 도움이 됩니다.
Invoice Radar는 다양한 플랫폼에서 송장과 영수증을 가져오고, 다운로드하고, 정리하는 데 도움이 되는 문서 자동화 도구입니다.
송장 레이더에 대해 자세히 알아보기
소개
시작하기
플러그인 구조
첫 번째 플러그인 작성
유용한 패턴
단계 참조
JSON, HTML, CSS 및 JavaScript에 대한 기본 지식.
텍스트 편집기 또는 IDE(예: VSCode, Sublime Text).
macOS 또는 Windows에 설치된 Invoice Radar.
송장 레이더 다운로드 및 설치 :
송장 레이더에 대한 액세스 요청
빈 플러그인 다운로드 :
블랭크 플러그인을 로컬 컴퓨터에 다운로드하세요.
파일 이름을 your-plugin-name.json 으로 바꿉니다.
원하는 폴더에 넣어주세요.
송장 레이더에 플러그인 추가 :
송장 레이더를 엽니다.
설정으로 이동하여 Available Plugins 탭을 선택하세요.
Choose Plugin Directory 선택하고 플러그인을 저장한 폴더를 선택합니다.
이제 귀하의 플러그인이 사용 가능한 플러그인 목록에 나타날 것입니다.
Invoice Radar용 플러그인은 JSON으로 작성되었으며 특정 구조를 따릅니다. 각 플러그인은 다음 섹션으로 구성됩니다.
플러그인 설명 :
메타데이터 : 이름, 설명, 홈페이지 URL 등 플러그인에 대한 기본 정보입니다.
configSchema : 플러그인에 필요할 수 있는 구성 속성입니다.
긁는 단계 :
checkAuth : 사용자가 이미 인증되었는지 확인하는 단계입니다.
startAuth : 인증 프로세스를 시작하는 단계입니다.
getDocuments : 문서를 가져오고 다운로드하는 단계입니다.
{ "$schema": "https://raw.githubusercontent.com/invoiceradar/plugins/main/schema.json", "id": "example", "name": "예제 플랫폼", "description": " 서비스에 대한 간단한 설명.", "homepage": "https://example.com", "checkAuth": [
{ "action": "탐색", "url": "https://example.com/dashboard"
},
{ "action": "checkElementExists", "selector": "#logout-button"
}
], "startAuth": [
{ "action": "탐색", "url": "https://example.com/login"
},
{ "action": "waitForElement", "selector": "#account-summary", "timeout": 120000
}
], "getDocuments": [
{ "action": "탐색", "url": "https://example.com/billing"
},
{ "action": "extractAll", "selector": ".invoice-row", "variable": "invoice", "fields": { "id": { "selector": ".invoice-id"
}, "date": { "selector": ".invoice-date"
}, "총계": { "선택기": ".invoice-total"
}, "url": { "selector": ".invoice-download", "attribute": "href"
}
}, "forEach": [
{ "action": "downloadPdf", "url": "{{invoice.url}}", "document": "{{invoice}}"
}
]
}
]
}전체 스키마는 여기에서 찾을 수 있습니다.
가상의 서비스에서 송장을 가져오는 간단한 플러그인을 만들어 보겠습니다.
메타데이터 정의 :
이 정보는 Invoice Radar에서 플러그인을 식별하고 표시하는 데 사용됩니다. 홈페이지 URL은 서비스의 파비콘을 가져오는 데 사용됩니다.
id 는 고유해야 하며 소문자여야 합니다.
{ "id": "example-service", "name": "예제 서비스", "description": "서비스에 대한 간단한 설명.", "homepage": "https://example.com"}메타데이터 필드에 대해 자세히 알아보세요.
구성 스키마 정의 (선택 사항):
구성 스키마는 플러그인이 작동하는 데 필요한 필드를 정의합니다. 이 예에서는 인증을 위해 teamID 와 password 필요합니다.
이 필드는 Invoice Radar에 플러그인을 추가할 때 사용자에게 표시됩니다.
"configSchema": { "teamID": { "type": "string", "title": "Team ID", "description": "인보이스를 가져올 팀 또는 계정의 ID입니다.", "required": true
}
}구성 스키마 필드에 대해 자세히 알아보세요.
인증 확인 :
checkAuth 에는 사용자가 인증되었는지 확인하는 단계가 포함되어 있습니다. 이는 URL이나 요소 존재 여부를 확인하여 수행할 수 있습니다. checkAuth 내부의 마지막 단계는 확인 단계여야 합니다.
이러한 단계는 실행이 시작될 때 실행됩니다. 사용자가 이미 인증된 경우 플러그인은 인증 프로세스를 건너뛰고 바로 문서 가져오기로 이동합니다.
"확인 인증": [
{ "action": "탐색", "url": "https://example.com/dashboard"
},
{ "action": "checkElementExists", "selector": "#logout-button"
}
]인증 시작 :
startAuth 인증 프로세스를 시작하는 단계가 포함되어 있습니다. 여기에는 로그인 페이지로 이동하고 성공적인 로그인 표시를 기다리는 것이 포함될 수 있습니다.
인증 프로세스 중에 브라우저가 표시되어 사용자가 로그인 양식과 상호 작용할 수 있습니다.
"startAuth": [
{ "action": "탐색", "url": "https://example.com/login"
},
{ "action": "waitForElement", "selector": "#account-summary", "timeout": 120000
}
]문서 스크랩 :
getDocuments 에는 문서를 가져오고 다운로드하는 단계가 포함되어 있습니다. 여기에는 청구 페이지로 이동하고 송장 세부정보를 추출하고 PDF를 다운로드하는 작업이 포함될 수 있습니다.
"getDocuments": [
{ "action": "탐색", "url": "https://example.com/billing"
},
{ "action": "extractAll", "selector": ".invoice-row", "variable": "invoice", "fields": { "id": { "selector": ".invoice-id"
}, "date": { "selector": ".invoice-date"
}, "총계": { "선택기": ".invoice-total"
}, "url": { "selector": ".invoice-download", "attribute": "href"
}
}, "forEach": [
{ "action": "downloadPdf", "url": "{{invoice.url}}", "document": { "type": "invoice", "id": "{{invoice.id}}", "date": "{{invoice.date}}", "total": "{{invoice.total}}"
}
}
]
}
]이제 끝났습니다! :
파일을 저장하고 Invoice Radar에 추가하세요. 이제 플러그인을 실행하여 서비스에서 송장을 가져올 수 있습니다.
checkAuth )사용자가 인증되지 않으면 많은 서비스가 자동으로 로그인 페이지로 리디렉션됩니다. 이 동작을 사용하여 사용자가 인증되었는지 확인할 수 있습니다.
{ "action": "탐색", "url": "https://example.com/login"},
{ "작업": "checkURL", "url": "https://example.com/account",
} 서비스에 따라 인증되지 않은 경우 대시보드에서 로그인 페이지로 리디렉션될 수 있습니다. 이 경우 checkURL 단계를 사용하여 대시보드를 방문한 후에도 URL이 여전히 일치하는지 확인할 수 있습니다.
{ "action": "탐색", "url": "https://example.com/dashboard"},
{ "작업": "checkURL", "url": "https://example.com/dashboard",
} glob 패턴을 사용하여 동적 URL( https://example.com/dashboard/** 과 일치시킬 수 있습니다.
인증된 상태에 고유한 선택기를 사용하여 사용자가 인증되었는지 확인할 수 있습니다(예: 로그아웃 버튼 또는 프로필 링크).
{ "action": "탐색", "url": "https://example.com/home"},
{ "action": "waitForElement", "selector": "#logout-button"} checkElementExists 단계가 실행될 때 웹사이트가 완전히 로드되지 않는 경우도 있습니다. 이를 방지하려면 waitForNetworkIdle 속성을 사용하여 페이지가 완전히 로드될 때까지 기다릴 수 있습니다.
{ "action": "navigate", "url": "https://example.com/home", "waitForNetworkIdle": true},
{ "action": "checkElementExists", "selector": "#logout-button"}startAuth )대부분의 인증 프로세스는 로그인 페이지로 이동하여 로그인 성공 후 특정 요소가 나타날 때까지 기다리는 것으로 시작됩니다.
인증 프로세스 중에 브라우저가 표시되어 사용자가 로그인 양식과 상호 작용할 수 있다는 점을 기억하십시오. 인증 흐름 자체는 자동화할 수 있지만 필수는 아닙니다.
{ "action": "탐색", "url": "https://example.com/login"},
{ "action": "waitForElement", "selector": "#logout-button", "timeout": 120000}사용자에게 로그인할 수 있는 충분한 시간을 제공하려면 대기 단계에 긴 제한 시간(기본값 120초)을 제공하는 것이 좋습니다.
이 섹션에서는 Invoice Radar용 플러그인을 생성하는 데 사용할 수 있는 단계에 대한 개요를 제공합니다. 각 단계는 자동화 프로세스 중에 수행할 수 있는 특정 작업을 나타냅니다.
탐색 단계
탐색( navigate )
URL 대기( waitForURL )
요소 대기( waitForElement )
탐색 대기( waitForNavigation )
네트워크 유휴 대기( waitForNetworkIdle )
상호작용 단계
요소 클릭( click )
텍스트 입력( type )
드롭다운 선택( dropdownSelect )
JavaScript 실행( runJs )
확인 단계
요소 존재 확인( checkElementExists )
URL 확인( checkURL )
JavaScript 실행( runJs )
데이터 추출 단계
추출( extract )
모두 추출( extractAll )
문서 검색 단계
PDF 다운로드( downloadPdf )
PDF 다운로드 대기( waitForPdfDownload )
페이지를 PDF로 인쇄( printPdf )
Base64 PDF 다운로드( downloadBase64Pdf )
조건부 논리 단계
만약 ( if )
기타 단계
잠( sleep )
짧은 발췌
Stripe URL에서 송장 가져오기( getInvoiceFromStripeUrl )
Stripe 고객 포털에서 송장 받기( getInvoicesFromStripeBillingPortal )
navigate )지정된 URL로 이동하고 페이지가 로드될 때까지 기다립니다. 기본적으로 후속 AJAX 요청이 아닌 초기 페이지 로드만 기다립니다.
{ "action": "탐색", "url": "https://example.com"} 계속하기 전에 페이지가 완전히 로드되도록 waitForNetworkIdle true 로 설정할 수 있습니다.
{ "action": "navigate", "url": "https://example.com/dashboard", "waitForNetworkIdle": true}알아두면 좋은 점 :
상대 URL이 지원되며 현재 페이지를 기반으로 해결됩니다.
탐색 작업은 후속 AJAX 요청이 아닌 초기 페이지 로드만 기다립니다.
waitForURL )현재 URL이 주어진 URL과 일치할 때까지 기다립니다. 선택적으로 시간 제한이 적용됩니다. 와일드카드를 지원합니다.
{ "action": "waitForURL", "url": "https://example.com/profile/**", "timeout": 3000}waitForElement )선택적으로 시간 초과와 함께 지정된 선택기가 페이지에 나타날 때까지 기다립니다.
{ "action": "waitForElement", "selector": "#example", "timeout": 3000}waitForNavigation )페이지 탐색이 발생할 때까지 기다립니다. 이 단계는 페이지가 완전히 로드될 때까지 기다리지 않습니다. 해당 목적으로 waitForNetworkIdle 단계를 사용하십시오. 시간 초과는 선택 사항이며 기본값은 10초입니다.
{ "action": "waitForNavigation", "timeout": 10000}waitForNetworkIdle )네트워크가 유휴 상태가 될 때까지 기다립니다. 이는 페이지에서 모든 리소스 로드가 완료되었는지 확인하려는 경우에 유용합니다. 500ms 동안 더 이상 네트워크 요청이 없으면 단계가 완료됩니다. 시간 초과는 선택 사항이며 기본값은 15초입니다.
navigate 단계에는 동일한 동작을 얻기 위해 true 로 설정할 수 있는 waitForNetworkIdle 옵션이 있습니다.
{ "action": "waitForNetworkIdle", "timeout": 10000}click )페이지에서 지정된 선택기로 지정된 요소를 클릭합니다.
{ "작업": "클릭", "선택기": "#버튼"}type )페이지의 지정된 선택기에 의해 지정된 요소에 지정된 텍스트를 입력합니다.
{ "action": "type", "selector": "#input", "value": "Hello World"}dropdownSelect ) 페이지의 지정된 선택기에 의해 지정된 드롭다운에서 지정된 값을 선택합니다. 선택은 옵션의 value 속성을 기반으로 이루어집니다.
{ "action": "dropdownSelect", "selector": "#dropdown", "value": "옵션 1"}runJs )페이지 컨텍스트에서 지정된 JavaScript를 실행합니다. Promise가 반환되면 대기하게 됩니다.
후속 단계에서 스크립트 결과를 사용하려면 대신 추출 단계를 사용하세요.
{ "action": "runJs", "script": "document.querySelector('#example').click();"} 이러한 단계는 사용자가 인증되었는지 확인하기 위해 checkAuth 내에서 사용됩니다.
checkElementExists )해당 선택기가 페이지에 존재하는지 확인합니다. 일반적으로 인증 확인에 사용됩니다.
{ "action": "checkElementExists", "selector": "#example"}checkURL ) 현재 URL이 주어진 URL과 일치하는지 확인합니다. https://example.com/dashboard/** 와 같은 와일드카드 패턴을 지원합니다.
{ "작업": "checkURL", "url": "https://example.com"}runJs ) runJs 단계는 검증 단계로도 사용될 수 있습니다. 진실 또는 거짓 값을 반환하는 스크립트를 실행하면 사용자가 인증되었는지 확인할 수 있습니다.
{ "action": "runJs", "script": "document.cookie.includes('authToken');"}이러한 단계는 페이지에서 항목 목록이나 단일 값과 같은 데이터를 로드하고 후속 단계에서 사용하는 데 사용됩니다.
extract )페이지에서 단일 데이터 조각을 추출하여 변수에 저장합니다.
CSS 필드 사용:
{ "action": "extract", "variable": "account", "fields": { "id": "#team-id", "name": "#team-name", "url": { " selector": "#team-link", "attribute": "href"
}
}
} 이 예제에서는 account 변수 이름으로 사용되며 id , name 및 url 필드는 CSS 선택기를 사용하여 추출됩니다. {{account.id}} , {{account.name}} 및 {{account.url}} 자리 표시자를 사용하여 후속 단계에서 사용할 수 있습니다.
자바스크립트 사용:
{ "작업": "추출", "변수": "토큰", "스크립트": "localStorage.getItem('authToken')"} 이 예에서는 JavaScript를 사용하여 추출되는 token 변수를 생성합니다. 값은 {{token}} 자리 표시자를 사용하여 액세스할 수 있습니다. 객체를 반환하는 것도 가능합니다.
extractAll )페이지에서 데이터 목록을 추출하고 각 항목에 대해 지정된 단계를 실행합니다. 이는 일반적으로 송장 목록을 반복하고 다운로드하는 데 사용됩니다.
selector 와 일치하는 각 요소에 대해 필드가 추출되어 forEach 단계에서 사용 가능한 variable 에 저장됩니다.
알아두면 좋은 점 :
fields 객체 내부의 각 선택기 범위는 자동으로 일치하는 요소로 지정됩니다.
variable 필드는 선택 사항입니다. 제공하지 않을 경우 추출된 데이터는 기본 변수 item 에 저장됩니다.
현재 색인은 {{index}} 자리 표시자를 사용하여 액세스할 수 있습니다. 0부터 시작하여 각 항목마다 증가합니다.
CSS 필드 사용:
{ "action": "extractAll", "selector": ".invoice-list .invoice-item", "variable": "invoice", "fields": { "id": "td.invoice-id", " 날짜": "td.invoice-date", "total": "td.invoice-total", "url": { "selector": "a.invoice-link", "attribute": "href"
}
}, "forEach": [
{ "action": "탐색", "url": "{{invoice.url}}"
},
{ "action": "downloadPdf", "invoice": "{{invoice}}"
}
]
}자바스크립트를 사용하면:
JavaScript를 사용할 때 결과는 객체 또는 값의 배열이어야 합니다. 결과가 약속이라면 기다릴 것입니다.
{ "action": "extractAll", "script": "Array.from(document.querySelectorAll('#year-selector option')).map(option => option.value);", "변수": "연도 ", "forEach": [
{ "action": "dropdownSelect", "selector": "#year-selector", "value": "{{year}}"
}
]
}쪽수 매기기
아직 문서화되지 않은 실험적 지원입니다.
이 단계는 문서를 다운로드하고 송장 레이더에서 처리하는 데 사용됩니다. 모든 단계에서는 문서의 메타데이터가 포함된 document 개체를 인수로 전달해야 합니다.
document 인수에는 다음 필드가 있습니다.
필수의
id : 고유한 문서 ID
예: INV-123 또는 123456
date : 송장 날짜(문자열)
예: 2022-01-01 , 01/01/2022 또는 January 1, 2022
추천
total : 통화를 포함한 송장 총액입니다.
예: $100.00 또는 €100.00 또는 100 EUR 또는 100,00€
내장된 파서는 문자열에서 금액과 통화를 추출하려고 시도합니다.
선택 과목
type : 문서 유형 (선택 사항. 기본값은 auto )
auto , invoice , receipt , refund 또는 other 로 설정할 수 있습니다.
metadata : 문서에 대한 추가 메타데이터 (선택 사항)
예 { "orderNumber": "12345" }
모든 필드를 개별적으로 전달할 수도 있고 모든 필수 필드가 포함된 경우 전체 개체를 전달할 수도 있습니다.
예를 들어 별도의 필드를 사용하는 경우:
"document": { "id": "{{item.invoiceId}}", "date": "{{item.date}}", "total": "{{item.amount}} {{item.currency }}", "type": "송장"}예를 들어 객체에 모든 필수 필드가 포함되어 있으면 직접 전달할 수 있습니다.
"문서": "{{항목}}"downloadPdf )지정된 URL에서 PDF를 다운로드합니다.
{ "action": "downloadPdf", "url": "https://example.com/invoice.pdf", "document": { "id": "{{item.invoiceId}}", "date": "{{item.date}}", "전체": "{{item.total}}"
}
}waitForPdfDownload )PDF 다운로드를 기다립니다. 시간 초과의 기본값은 15초입니다.
{ "action": "waitForPdfDownload", "timeout": 10000, "document": { "id": "{{item.invoiceId}}", "date": "{{item.date}}", "total ": "{{item.total}}"
}
}printPdf )현재 페이지를 PDF 파일로 인쇄합니다.
{ "action": "printPdf", "document": { "id": "{{item.invoiceId}}", "date": "{{item.date}}", "total": "{{item .총}}"
}
}downloadBase64Pdf )base64로 인코딩된 문자열에서 PDF를 다운로드합니다.
{ "action": "downloadBase64Pdf", "base64": "{{item.base64String}}", "document": { "id": "{{item.invoiceId}}", "date": "{{item .date}}", "total": "{{item.total}}"
}
}if ) 조건이 true인 경우 지정된 단계를 실행합니다. 조건이 거짓이면 else 단계가 실행됩니다.
{ "action": "if", "script": "'{{invoice.url}}'.includes('pdf')", "then": [
{ "action": "클릭", "selector": "#예"
}
], "또 다른": [
{ "action": "탐색", "url": "https://example.com/fallback"
}
]
}sleep )밀리초 단위로 지정된 시간 동안 기다립니다. 이는 일반적으로 권장되지 않습니다. 대부분의 경우 waitForElement, waitForURL 또는 waitForNetworkIdle 단계를 사용하는 것이 더 좋습니다.
{ "작업": "수면", "기간": 1000}스니펫은 일반적인 작업을 단순화하는 사전 구축된 단계 세트입니다. 특정 스니펫에 대한 단계는 개발자 도구 내부에 표시됩니다.
현재는 사용자 정의 스니펫을 생성할 수 없습니다. 스니펫으로 유용할 것이라고 생각되는 일반적인 작업이 있는 경우 GitHub에서 이슈를 생성하세요.
getInvoiceFromStripeUrl )Stripe 송장 URL에서 송장을 추출합니다.
{ "action": "runSnippet", "snippet": "getInvoiceFromStripeUrl", "args": { "url": "https://invoice.stripe.com/i/inv_123"
}
}getInvoicesFromStripeBillingPortal )Stripe 청구 포털에서 사용 가능한 송장을 추출합니다.
{ "action": "runSnippet", "snippet": "getInvoicesFromStripeBillingPortal", "args": { "url": "https://stripe-portal.example.com/billing"
}
} 때로는 API에서 데이터를 가져오기 위해 단계 내에서 가져오기 요청을 실행해야 할 수도 있습니다. 이렇게 하려면 extractAll 작업을 사용할 수 있습니다.
{ "action": "extractAll", "variable": "invoice", "script": "fetch('https://example.com/api/invoices').then(res => res.json()) " "forEach": [
{ "action": "downloadPdf", "url": "{{invoice.url}}", "document": { "id": "{{invoice.id}}", "date": "{{invoice .date}}", "total": "{{invoice.total}}"
}
}
]
}그러면 가져오기 요청이 실행되고 결과가 JavaScript 개체로 반환됩니다.
<iframe/> 내에서 단계 실행 일부 시나리오에서는 <iframe/> 요소 내에서 단계를 실행해야 할 수도 있습니다. 이를 위해 단계에서 iframe 속성을 사용할 수 있습니다.
{ "action": "클릭", "selector": "#button-inside-iframe", "iframe": true}, iframe true 로 설정하면 Invoice Radar는 페이지에서 첫 번째 <iframe/> 요소를 찾아 그 내부의 단계를 실행합니다.
iframe의 src 속성 내에 포함된 문자열을 사용하여 특정 iframe을 타겟팅할 수도 있습니다.
{ "action": "클릭", "selector": "#button-inside-iframe", "iframe": "iframe.example.com"}, 
