API 및 웹후크

영수증 및 문서의 읽기와 업로드는 REST API를 통해 가능합니다. 계정, 파일 폴더, 태그 및 연결 관리 기능은 애플리케이션 내에서 계속 사용할 수 있습니다.

키

설정 → 개발자에서 생성합니다. 키는 한 번만 표시되며, 생성 시에만 제공되고 이후에는 그 해시만 저장됩니다. 분실된 키는 복구할 수 없으며, 새로 생성해야 하며, 이전 키는 삭제됩니다. 최대 다섯 개의 키를 가질 수 있으며, 각 키는 최대 두 해까지 유효합니다.

키는 X-API-Key 헤더에 포함되어 전송됩니다.

API의 기능

Excel 및 PDF는 결과적으로 Base64 형식으로 처리됩니다. 결과가 필요 없는 경우 includeResult=false로 설정하여 서버에서 변환을 절약할 수 있습니다.

OpenAPI 형식의 인터페이스 설명은 /api/docs에서 확인할 수 있으며, 키 설정에서 링크가 제공됩니다. 설명은 실행 중인 코드를 기반으로生成되므로 API가 수행하는 작업과 일치합니다.

API 영수증의 검증

발송 전에 검증은 기본적으로 키로 업로드된 영수증에도 적용됩니다: 영수증은 애플리케이션에서 확인을 기다리며, 웹후크는 확인 후에 전송됩니다. 화면 앞에 사람이 없도록 통합을 구축하는 경우, 설정 → 발송 전 검증에서 API 채널을 제거하거나 검증을 비활성화할 수 있습니다.

MCP

AI 에이전트를 위한 /api/mcp 서버는 동일한 키를 가지고 있습니다. 영수증을 읽고 검색할 수 있지만, 업로드는 지원하지 않습니다. 업로드는 완료된 주문으로 반환되며, 에이전트가 직접 실행해야 합니다.

웹후크

상태를 쿼리하는 대신 결과가 준비되면 알림을 받을 수 있습니다. 주소는 설정 → 개발자에서 전체 계정에 대해 설정하거나 각각의 업로드 시 targetWebhookUrl 매개변수를 통해 설정할 수 있습니다. 설정의 버튼을 클릭하면 테스트 메시지가 전송됩니다.

POST 요청이 JSON으로 전송됩니다: 영수증 식별자, 파일 이름, 형식, 및 결과를 지정 형식으로 포함합니다. 영수증이 검증을 통과하거나 다시 처리되면, 수정 플래그(IsCorrection)와 함께 두 번째 웹후크가 전송됩니다.

메시지는 서명되지 않습니다. 주소에 개인 비밀 토큰을 추가하여 발신자를 확인하세요. 사설 네트워크 주소는 거부됩니다.

전송 실패는 증가하는 지연과 함께 재시도되며, 약 4시간 30분 동안 11회의 시도가 이루어집니다. 각 시도는 활성화 내역과 귀측의 응답과 함께 기록됩니다. 영수증 목록에서 전송 결과 아이콘이 표시됩니다.

한계

API는 분당 호출 수에 대한 자체 한도가 없습니다; 업로드는 크레딧, 요금제에 따른 파일 크기 및 영수증당 20페이지로 제한됩니다. 거부 시에는 400 오류와 함께 사유 코드가 반환됩니다. MCP 서버는 초당 10개의 쿼리로 제한됩니다.