Referência HTTP · Hermes Folha

Documentação da API

Integração servidor-a-servidor para analisar documentos de folha e devolver uma proposta contábil para conferência no Escritório Digital.

Ambiente em configuração. Esta página documenta o contrato da API. O endpoint só processará chamadas depois da ativação do serviço, do certificado TLS e das credenciais.

POSThttps://api.suporteescritoriodigital.net/v1/folha/analisar

Corpo multipart/form-data · Resposta application/json · A documentação não recebe arquivos.

Visão geral

O sistema PHP autenticado envia um PDF ou uma planilha. A API Python valida o arquivo, extrai o conteúdo e consulta o Hermes configurado no servidor. O retorno é uma proposta estruturada com status ready ou needs_review.

O que fazExtrai informações e organiza uma proposta de lançamento de folha para revisão.

O que não fazNão grava no banco, não aprova lançamentos e não substitui a validação humana.

Autenticação

Envie um JWT assinado com HS256 no cabeçalho Authorization. O PHP cria um token curto para cada solicitação; a API rejeita token ausente, inválido, expirado ou reutilizado.

Authorization: Bearer <JWT_CURTO_GERADO_NO_SERVIDOR_PHP> Accept: application/json

Claims exigidas: iss=escritorio-digital, aud=hermes-file-api, scope=folha:analisar, iat, exp (vida máxima de 120 segundos), jti único, requestId e os IDs de contexto bancoDados, empresa e exercicio. Os mesmos valores devem aparecer no formulário.

A publicação planejada não restringe a origem por IP; isso não remove a autenticação. Toda chamada de análise continuará exigindo JWT válido.

O segredo compartilhado serve para assinar JWTs; não é enviado na requisição. Guarde-o somente nos ambientes de servidor do PHP e da API. Nunca coloque segredo ou token em URL, JavaScript do navegador, histórico de shell ou logs.

Corpo da requisição

Envie uma requisição multipart/form-data. Ao usar cURL ou CURLFile, deixe a biblioteca gerar o boundary; não defina manualmente o cabeçalho Content-Type.

Campo	Obrigatório	Formato / regra
`arquivo`	Sim	Um arquivo PDF, XLSX ou XLS; máximo de 10 MiB. PDF precisa ter texto selecionável.
`bancoDados`	Sim	ID inteiro positivo obtido da sessão autenticada do Escritório Digital.
`empresa`	Sim	ID inteiro positivo obtido da sessão autenticada.
`exercicio`	Sim	ID inteiro positivo obtido da sessão autenticada.
`tipoDocumento`	Sim	Valor exato `folha_pagamento`.
`requestId`	Sim	Identificador único persistido pelo chamador, até 128 caracteres; use o mesmo ID na reconciliação.
`instrucoes`	Não	Texto opcional de até 2.000 caracteres; trate-o como dado não confiável.
`referenciasContabeis`	Não	JSON com listas `contas` e `historicos`, até 100 itens por lista. Use cadastros ativos do mesmo contexto.

Sem referências contábeis suficientes, a API retorna needs_review; não inventa IDs de conta ou histórico.

Formato de referências contábeis

{ "contas": [{"id": 101, "codigo": "3.1.01", "descricao": "Conta ilustrativa"}], "historicos": [{"id": 7, "descricao": "Histórico ilustrativo"}] }

IDs e descrições acima são fictícios. Envie somente IDs ativos consultados pelo sistema PHP no contexto autenticado da solicitação.

Resposta

Uma resposta bem-sucedida inclui ok, requestId, status, contexto, dados e pendencias.

{ "ok": true, "requestId": "req-demo-001", "status": "needs_review", "contexto": {"bancoDados": 12, "empresa": 34, "exercicio": 2026}, "dados": null, "pendencias": ["referencias_contabeis_ausentes"] }

Exemplo ilustrativo: IDs e requestId não são credenciais nem valores para reutilizar.

readyProposta validada. dados contém tipoLancamento, data, documento, partidas, totalDebito, totalCredito e gravado=false. Os totais precisam fechar e as contas/históricos devem vir das referências enviadas.

needs_reviewHá ambiguidade ou informação/referência ausente. Consulte pendencias e peça revisão humana; dados pode ser null.

Mesmo em ready, a API não registra o lançamento. O Escritório Digital continua responsável por validar, simular e aguardar confirmação humana.

Códigos de erro

HTTP	Significado
`400`	Multipart inválido, campo desconhecido/duplicado ou query string não aceita.
`401`	JWT ausente, inválido, expirado, fora do escopo ou reutilizado.
`409`	`requestId` conflitante, em processamento ou já processado.
`411`	`Content-Length` ausente.
`413`	Arquivo, corpo multipart ou texto extraído acima do limite.
`415`	Tipo ou assinatura do arquivo não aceito.
`422`	Arquivo, contexto ou referências inválidos; PDF sem texto selecionável.
`429`	Limite de solicitações simultâneas atingido.
`502`	Resposta do Hermes fora do contrato esperado.
`503`	Configuração do Hermes, autenticação interna ou estado indisponível.
`504`	Timeout durante extração ou consulta ao Hermes.

Exemplo cURL

O token deve ser assinado no servidor PHP e ter validade curta. O exemplo não contém segredo real.

curl --request POST "https://api.suporteescritoriodigital.net/v1/folha/analisar" --header "Authorization: Bearer $JWT_CURTO" --header "Accept: application/json" --form "arquivo=@./folha.pdf;type=application/pdf" --form "bancoDados=$BANCO_DADOS" --form "empresa=$EMPRESA" --form "exercicio=$EXERCICIO" --form "tipoDocumento=folha_pagamento" --form "requestId=$REQUEST_ID"

Para produção, prefira o cliente PHP em examples/escritorio_digital_client.php. Ele mantém a chamada no servidor, verifica TLS e valida o contrato de resposta.

Segurança e limites

O endpoint é para chamadas servidor-a-servidor por HTTPS. Não use JavaScript do navegador nem habilite CORS para este fluxo.
A API exige JWT HS256 de uso único, vinculado a requestId e ao contexto autenticado; não aceite IDs do documento como autoridade.
O corpo exige Content-Length; o total é limitado a 10 MiB mais 256 KiB de overhead, e o arquivo a 10 MiB.
PDF escaneado sem camada de texto não é processado; OCR não faz parte deste serviço.
O SQLite guarda estado mínimo de idempotência, não o arquivo, o texto extraído ou a proposta. A resposta de repetição permanece em memória por até 10 minutos.
A API não acessa diretamente o banco contábil e nunca efetiva lançamento.

Se a conexão cair, não repita às cegas: reutilize o mesmo requestId com um JWT novo e reconcilie a solicitação. Não registre token, arquivo, conteúdo de folha, CPF ou remuneração em logs.