API

A API de PL/Cota fornece mecanismos para envio externo de informações e consulta de solicitações/recibos.

Base URL

Os endpoints externos de PL/Cota são expostos pela URL pública da API:

• Base URL: https://<host>

Os caminhos públicos dos endpoints estão descritos nas páginas de envio e consulta.

Autenticação

Todos os endpoints são protegidos e requerem autenticação via Bearer Token.

• Header Obrigatório: Authorization: Bearer <seu_token_jwt>

Caso o token não seja fornecido ou seja inválido, a API retornará 401 Unauthorized. Caso o token seja válido mas não possua as permissões necessárias, a API retornará 403 Forbidden.

Observabilidade e Rastreabilidade

Para facilitar o rastreamento de requisições, recomenda-se o envio do header de correlação:

• Header Recomendado: X-Correlation-ID: <uuid-v4>

Este ID será propagado nos logs da aplicação, facilitando a análise de problemas.

Formato de Dados

• Envio JSON: Content-Type: application/json.
• Consulta: parâmetros via query string ou body JSON, conforme o endpoint.
• Download de recibo: retorno em CSV.
• Encoding: UTF-8.

Códigos de Erro Comuns

Código	Descrição
201	Criado com sucesso (solicitação recebida para processamento)
400	Requisição Inválida (Erro de validação de schema ou regras de negócio)
401	Não autorizado (Token ausente ou inválido)
403	Proibido (Sem permissão de acesso)
413	Payload Too Large (Arquivo ou JSON muito grande)
429	Too Many Requests (Rate limit excedido)
500	Erro Interno do Servidor