API HTTP

Rotas, autenticação Bearer, cota diária, entrada estrita, erros e revisão do motor de cálculo trabalhista.

O acesso à API é liberado mediante contato com o Fontejus.

A API de cálculo trabalhista recebe a mesma entrada JSON do comando peticao e devolve o mesmo JSON de resultado. O contrato de entrada está em Entrada e a leitura dos valores em Saída.

Rotas

Método e rota	Função	Chave
`GET /v1/saude`	Estado e revisão do motor	Sem chave
`GET /v1/esquema`	Árvore de campos aceitos, com nome, tipo e subcampos, gerada da estrutura de entrada	Sem chave
`POST /v1/calculos/trabalhista`	Recebe a entrada JSON e devolve o resultado do cálculo	Bearer
`POST /v1/calculos/trabalhista/validar`	Executa o cálculo e devolve somente `valido: true` e `avisos`, sem os valores, ou um erro	Bearer

A rota de validação executa o cálculo. Sua resposta de sucesso é resumida, sem as verbas e os totais.

Autenticação

As rotas de cálculo exigem uma chave no cabeçalho Authorization, no formato Bearer .... Chave ausente, inválida ou fora desse formato devolve 401, com codigo: "NAO_AUTORIZADO".

A configuração do servidor guarda o hash SHA-256 da chave, em vez da chave em si. Esta documentação não recebe nem fornece chaves de acesso.

Cada chave tem uma cota diária configurada. Esta página não fixa um número definitivo de pedidos. Quando a cota acaba, a resposta é 429, com codigo: "COTA_ESGOTADA". A resposta de cota esgotada traz os cabeçalhos X-Cota-Limite e X-Cota-Restante.

A contagem atual fica em memória: reinicia com o servidor e na virada do dia, no fuso de Brasília. A persistência da contagem ainda falta. A confirmar: números definitivos e regras de concessão de cota.

Além da cota diária por chave, um limite de velocidade por IP atua antes de o pedido chegar à API; se excedido, essa camada devolve 429, sem o JSON com codigo.

Modo estrito e avisos

Por padrão, campo desconhecido no JSON devolve 422, com codigo: "CAMPO_DESCONHECIDO", a lista campos_desconhecidos e a sugestão do nome correto.

Com ?modo=permissivo, o servidor ignora os campos desconhecidos e indica cada um em avisos. A escolha permissiva deve ser expressa. Os detalhes do comportamento da CLI estão em Entrada.

Erros documentados

HTTP	`codigo`	Situação
400	`JSON_INVALIDO`, `CORPO_ILEGIVEL`	JSON malformado
401	`NAO_AUTORIZADO`	Chave ausente, inválida ou fora do formato Bearer
404	`ROTA_NAO_ENCONTRADA`	Rota que não existe
405	`METODO_NAO_PERMITIDO`	Método HTTP errado para a rota; cabeçalho `Allow` com os métodos aceitos
413	`CORPO_GRANDE_DEMAIS`	Corpo maior que 1 MiB
422	`CAMPO_DESCONHECIDO`, `INDICE_SEM_TAXA`, `JUROS_FORA_DE_ALCANCE`, `LIQUIDACAO_ANTES_DO_VENCIMENTO`, `ERRO_INTERNO`	Entrada que o motor não consegue calcular
429	`COTA_ESGOTADA`	Cota diária da chave esgotada

A resposta 404 usa JSON:

{ "erro": "rota não encontrada", "codigo": "ROTA_NAO_ENCONTRADA" }

A resposta 405 usa JSON:

{ "erro": "método não permitido nesta rota", "codigo": "METODO_NAO_PERMITIDO" }

No erro 405, o cabeçalho Allow é GET, HEAD nas rotas de saúde e de esquema, e POST nas rotas de cálculo e de validação.

O código ERRO_INTERNO também cobre erros de validação, como data inválida, conforme o contrato atual. Leia o código e o conteúdo do erro antes de interpretar a resposta como resultado de cálculo.

Revisão do motor e armazenamento

Toda resposta traz X-Fontejus-Motor, com a revisão do código, e Cache-Control: no-store. O cabeçalho de revisão permite identificar qual versão respondeu ao pedido.

A API descrita não guarda os casos recebidos. Isso descreve o serviço de cálculo sem estado, sem estender essa característica a outros produtos ou a uma futura área logada.

Limites

Ainda faltam persistência da cota, painel de uso por chave, registro de uso para cobrança, CORS e a rota de jurisprudência neste serviço. A API descrita é destinada a chamadas entre servidores; não oferece integração pelo navegador.

A confirmar: critérios de acesso e data de abertura geral. Esta página não antecipa esses compromissos.

O uso atual pela linha de comando está em Usar com IA.