API e webhooks
O envio e leitura de documentos está disponível através da API REST. A gestão de contas, pastas, etiquetas e conexões permanece no aplicativo.
Chave
A chave é criada em Configurações → Para Desenvolvedores. A chave é exibida uma vez, ao ser criada — depois disso, não aparece mais, pois apenas seu hash é salvo. Chaves perdidas não são recuperadas, cria-se uma nova e a antiga é excluída. É possível ter até cinco chaves, cada uma com um prazo de validade opcional de até dois anos.
O proprietário da conta receberá um e-mail sobre cada nova chave, assim como duas semanas antes de a chave expirar. Consulte Notificações por e-mail.
A chave é enviada no cabeçalho X-API-Key.
O que a API pode fazer
| Operação | Descrição |
|---|---|
POST /api/upload | Envio de arquivo com opções: formato, direção, tipo, moeda, esquema, pasta, webhook |
POST /api/upload/url | O mesmo a partir de um endereço público; baixamos o arquivo nós mesmos |
GET /api/jobs | Listagem de documentos com filtros e paginação |
GET /api/jobs/{id} | Estado, dados lidos, achados e resultado no formato alvo |
GET /api/jobs/{id}/original | Arquivo enviado |
DELETE /api/jobs/{id} | Excluir para a lixeira |
Excel e PDF vêm no resultado como Base64. Quem não precisa do resultado, pode enviar includeResult=false, economizando a conversão no servidor.
A descrição da interface no formato OpenAPI está em /api/docs; o link está nas configurações junto às chaves. A descrição é gerada a partir do código em execução, portanto, corresponde ao que a API faz.
Verificação de documentos da API
A verificação antes do envio se aplica por padrão também a documentos enviados pela chave: o documento aguarda confirmação no aplicativo e o webhook será enviado somente após isso. Quem está construindo uma integração na qual ninguém está sentado na tela pode remover o canal API em Configurações → Verificação antes do envio, ou desativar a verificação.
MCP
Para agentes de IA, o servidor MCP está em /api/mcp com a mesma chave. Ele pode ler e pesquisar documentos, mas não enviá-los; o envio retornará como um comando pronto para que o agente execute-o por conta própria.
Webhooks
Em vez de consultar o estado, solicite que o resultado seja enviado assim que estiver pronto. O endereço é configurado para toda a conta em Configurações → Para Desenvolvedores, ou em cada envio individual através do parâmetro targetWebhookUrl. O botão nas configurações enviará uma mensagem de teste.
Um POST é enviado com JSON: identificador do documento, nome do arquivo, formato e resultado no formato alvo. Quando o documento passar na verificação ou for reprocessado, o webhook será enviado novamente com a marcação de correção (IsCorrection).
A mensagem não é assinada. Verifique o remetente incluindo seu próprio token secreto no endereço. Endereços para redes privadas são rejeitados.
Se o webhook não chegar após todas as tentativas, aproximadamente após quatro horas e meia, um e-mail será enviado. Durante uma única falha, isso ocorrerá apenas uma vez; falhas subsequentes estarão no registro de atividades. O e-mail também será enviado após cada mudança no endereço do webhook, caso tenha sido alterado por alguém além de você.
As entregas malsucedidas são repetidas com aumento de atraso, totalizando onze tentativas durante aproximadamente quatro horas e meia. Cada tentativa é registrada na atividade, juntamente com a resposta do seu lado; para o documento na lista, há um ícone com o resultado da entrega.
Limites
A API não tem um limite próprio para o número de chamadas por minuto; o envio é limitado por créditos, tamanho do arquivo conforme o plano e vinte páginas por documento. A rejeição será retornada como um erro 400 com um código que explica o motivo. O servidor MCP é limitado a dez consultas por segundo.