Padrão de requisições da API

Manual da API de Pedido de Vendas

01. Guia de implantação  |  02. Pré-requisitos  |  03. Porta do srvmegapetro.exe  |  04. Autenticação e autorização  |  05. Padrão de requisições

Objetivo

Este artigo define o padrão geral de chamadas da API de Pedido de Vendas: formação de URL, métodos HTTP, headers, JSON, idempotência, respostas e tratamento de erros.

Importante: Use este artigo como referência de padrão de consumo. Para contratos atualizados de endpoints, schemas, propriedades obrigatórias e exemplos oficiais de payload, consulte o Swagger em http://<host>:<httpPort>/swagger. Exemplo local: http://localhost:9194/swagger.

URL base

A URL base deve ser montada com o host do serviço e a porta HTTP vigente do srvmegapetro.exe.

http://<host>:<httpPort>/api/v1

Exemplo local com porta 9194:

http://localhost:9194/api/v1

Estrutura de endpoint

http://<host>:<httpPort>/api/v1/<recurso>/<operacao>

Exemplo de endpoint para simulação de pedido:

POST http://localhost:9194/api/v1/pedidos-venda/simulacoes

Métodos HTTP

Método	Uso esperado	Exemplo
GET	Consulta ou teste de conectividade.	/api/v1/ping
POST	Login, renovação, revogação, simulação ou inclusão.	/api/v1/auth/login
PUT	Edição de recurso existente.	/api/v1/pedidos-venda/{pedidoId}

Headers gerais

Header	Obrigatoriedade	Exemplo	Descrição
Content-Type	Obrigatório em requisições com corpo JSON.	application/json	Indica que o corpo da requisição está em JSON.
Authorization	Obrigatório em endpoints protegidos.	Bearer eyJhbGc...	Token de autenticação recebido no login.
X-Correlation-Id	Recomendado/obrigatório conforme endpoint.	550e8400-e29b-41d4-a716-446655440000	Identificador único para rastreamento da requisição.
X-Consumer-App	Recomendado/obrigatório conforme endpoint.	integracao-pedidos	Nome da aplicação consumidora.
X-Idempotency-Key	Obrigatório quando exigido em operações de persistência.	pedido-externo-123	Evita duplicidade em reenvios da mesma operação.
X-Response-Mode	Opcional.	default	Uso técnico conforme necessidade do endpoint.

Idempotência

Operações de persistência podem exigir o header X-Idempotency-Key. Essa chave deve identificar de forma única a tentativa de gravação, permitindo que reenvios por timeout ou falha de rede não gerem duplicidade.

X-Idempotency-Key: pedido-externo-123

Formato geral de resposta

As respostas seguem uma estrutura padronizada com indicação de sucesso, status, identificador de correlação, dados, erros e avisos.

Exemplo de sucesso:

{
  "success": true,
  "status": "OK",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "resultado": "..."
  },
  "errors": [],
  "warnings": []
}

Exemplo de erro:

{
  "success": false,
  "status": "BAD_REQUEST",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "code": "PED-API-BODY-INVALID",
      "message": "Corpo da requisição é inválido",
      "field": "cliente.clienteCodigo",
      "severity": "error"
    }
  ],
  "warnings": []
}

Códigos HTTP mais comuns

HTTP	Significado	Causa comum
200 OK	Operação concluída com sucesso.	Requisição processada corretamente.
400 Bad Request	Erro de formato ou validação técnica.	JSON inválido, campo ausente ou tipo incompatível.
401 Unauthorized	Falha de autenticação.	Token ausente, expirado ou inválido.
403 Forbidden	Falha de autorização.	Token sem escopo necessário.
405 Method Not Allowed	Método HTTP incorreto.	Uso de GET em endpoint que espera POST, por exemplo.
422 Unprocessable Entity	Erro de regra de negócio.	Cliente, produto, condição ou regra operacional inválida.
500 Internal Server Error	Erro interno.	Falha inesperada no processamento.
501 Not Implemented	Funcionalidade não implementada.	Endpoint ou operação ainda não disponível na versão.

Exemplo de chamada para simulação de pedido

Atenção: O payload abaixo é um exemplo didático. Antes de publicar ou consumir em produção, valide o schema atualizado no Swagger da versão instalada.

curl -X POST http://localhost:9194/api/v1/pedidos-venda/simulacoes \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Consumer-App: integracao-pedidos" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "identificacaoDocumento": {
      "filialCodigo": 1,
      "tipoDocumentoCodigo": "1",
      "serie": "A",
      "dataEmissao": "2026-06-24"
    },
    "cliente": {
      "clienteCodigo": 123
    },
    "transporte": {
      "freteCodigo": 1,
      "tipoFreteCodigo": "D",
      "modalidadeTrechoCodigo": "S"
    },
    "opcoesFiscais": {
      "notaFiscalPorProduto": false,
      "notaFiscalPorEntrega": true
    },
    "condicoesVenda": {
      "condicaoPagamentoCodigo": "AV"
    },
    "itens": [
      {
        "produtoCodigo": 456,
        "quantidade": 100.0,
        "unidadePedidoCodigo": "LT",
        "valorNegociado": 10.50
      }
    ]
  }'

Boas práticas de consumo

• Gerar um X-Correlation-Id único por requisição.
• Identificar a aplicação consumidora com X-Consumer-App.
• Usar X-Idempotency-Key em operações de persistência quando exigido.
• Tratar erros HTTP e erros de negócio retornados no array errors.
• Registrar nos logs internos apenas dados necessários para diagnóstico, evitando expor tokens e senhas.
• Consultar o Swagger sempre que houver atualização de versão ou dúvida sobre schema.