API 및 웹훅

문서의 업로드 및 읽기는 REST API를 통해 가능합니다. 계정, 폴더, 라벨 및 연결 관리는 애플리케이션 내에서 이루어집니다.

키

설정 → 개발자를 선택하여 생성합니다. 키는 한 번만 표시되며, 생성 시에만 나타납니다 — 그 이후에는 키의 해시만 저장됩니다. 잃어버린 키는 복구할 수 없으며, 새로 생성하고 이전 키는 삭제해야 합니다. 최대 다섯 개의 키를 가질 수 있으며, 각 키는 최대 2년까지 유효 기간을 설정할 수 있습니다.

새로운 키가 생성될 때마다 계정 소유자에게 이메일이 전송되며, 키가 만료되기 2주 전에 알림도 옵니다. 이메일 알림을 참조하세요.

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

API의 기능

Excel 및 PDF는 결과로 Base64 형식으로 전송됩니다. 결과가 필요하지 않다면 includeResult=false를 보내 서버에서의 변환을 절약할 수 있습니다.

OpenAPI 형식의 인터페이스 설명은 /api/docs에서 확인할 수 있으며, 키 설정에서 링크를 찾을 수 있습니다. 설명은 실행 중인 코드에서 생성되며, API의 현재 동작을 반영합니다.

API 문서 검증

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

MCP

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

웹훅

상태를 확인하는 대신 작업이 완료되면 결과를 보내도록 설정하세요. 주소는 설정 → 개발자에서 전체 계정에 대해 설정하거나 개별 업로드에 대해 targetWebhookUrl 매개변수를 통해 설정할 수 있습니다. 설정의 버튼은 테스트 메시지를 전송합니다.

POST 요청이 JSON 형식으로 전송됩니다: 문서 식별자, 파일 이름, 형식 및 결과를 목표 형식으로 포함합니다. 문서가 검증을 통과하거나 다시 처리될 경우, 웹훅이 다시 전송되며 수정 표시(IsCorrection)가 포함됩니다.

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

웹훅이 모든 시도 후에도 도달하지 않으면 약 4시간 반 후에 이메일이 전송됩니다. 장애가 한 번 발생하면 한 번만 전송되며, 이후의 실패는 활동 로그에 기록됩니다. 다른 사람이 webhook 주소를 변경한 경우에도 이메일이 발송됩니다.

실패한 배달은 증가하는 간격으로 반복되며, 약 4시간 반 동안 11회의 시도가 이루어집니다. 각 시도는 활동 로그에 응답과 함께 기록됩니다; 문서 목록에서는 배달 결과 아이콘이 표시됩니다.

제한 사항

API는 분당 호출 수에 대한 자체 제한이 없으며; 업로드는 크레딧, 요금제에 따른 파일 크기 및 문서당 20페이지로 제한됩니다. 거부되는 경우 400 오류 코드로 이유를 알려줍니다. MCP 서버는 초당 10개의 요청으로 제한됩니다.