API e webhooks
O upload e leitura de documentos está disponível através da API REST. A gestão de conta, pastas, etiquetas e conexões permanece no aplicativo.
Chave
Ela é criada em Configurações → Para desenvolvedores. A chave é exibida uma vez, ao ser criada — depois não é mais, pois apenas seu hash é salvo. Uma chave perdida não pode ser recuperada, uma nova deve ser criada e a antiga será excluída. É possível ter até cinco chaves, cada uma com um prazo de validade opcional de até dois anos.
A chave é enviada no cabeçalho X-API-Key.
O que a API pode fazer
| Operação | Descrição |
|---|---|
POST /api/upload | Upload de arquivo com opções: formato, direção, tipo, moeda, esquema, pasta, webhook |
POST /api/upload/url | O mesmo de um endereço público; faremos o download do arquivo nós mesmos |
GET /api/jobs | Listagem de documentos com filtros e paginação |
GET /api/jobs/{id} | Status, dados lidos, achados e resultado no formato de destino |
GET /api/jobs/{id}/original | Arquivo enviado |
DELETE /api/jobs/{id} | Exclusão para a lixeira |
Excel e PDF aparecem no resultado como Base64. Quem não precisa do resultado pode enviar includeResult=false, economizando assim a conversão no servidor.
A descrição da interface no formato OpenAPI pode ser encontrada em /api/docs; o link está nas configurações nas chaves. A descrição é gerada a partir do código em execução, então corresponde ao que a API faz.
Verificação em documentos da API
A verificação antes do envio é válida por padrão também para documentos enviados com a chave: o documento aguarda confirmação no aplicativo e o webhook será enviado somente após isso. Quem está construindo uma integração onde ninguém fica na tela pode desmarcar o canal da API em Configurações → Verificação antes do envio, ou desativar a verificação.
MCP
Para agentes de IA, está disponível em /api/mcp, servidor MCP com a mesma chave. Ele pode ler e buscar documentos, não pode fazer upload; o upload retornará como um comando finalizado, que o agente executará por conta própria.
Webhooks
Em vez de consultar o status, deixe que o resultado seja enviado quando estiver pronto. O endereço é configurado para toda a conta em Configurações → Para desenvolvedores, ou para cada upload individual pelo parâmetro targetWebhookUrl. O botão nas configurações enviará uma mensagem de teste.
Será enviado um POST com JSON: identificador do documento, nome do arquivo, formato e resultado no formato de destino. Quando o documento passar pela verificação ou for processado novamente, o webhook será enviado novamente com a sinalização de correção (IsCorrection).
A mensagem não é assinada. Verifique o remetente ao adicionar seu próprio token secreto ao endereço. Endereços para redes privadas serão rejeitados.
Entregas malsucedidas são repetidas com um intervalo crescente, totalizando onze tentativas durante cerca de quatro horas e meia. Cada tentativa é registrada nas atividades, junto com a resposta do seu lado; para o documento na listagem, há um ícone com o resultado da entrega.
Limites
A API não tem um limite próprio de chamadas por minuto; o upload é limitado por créditos, o tamanho do arquivo de acordo com o plano e vinte páginas por documento. A rejeição virá como um erro 400 com um código que explica o motivo. O servidor MCP é limitado a dez consultas por segundo.