Pular para o conteúdo principal

Convenções da plataforma

Envelope de resposta​

Toda resposta usa o mesmo envelope, em sucesso e em erro.

{
  "success": true,
  "message": "",
  "timestamp": "2026-07-23T14:32:10.412Z",
  "requestId": "7f3c1e8a-2b44-4d19-9f0e-51a2c8d7b6e3",
  "data": {},
  "error": null
}
CampoDescrição
successResultado técnico da chamada. Não é decisão de crédito.
messageTexto apto a ser exibido ao vendedor. Pode ser vazio.
timestampISO 8601 em UTC, com milissegundos.
requestIdEco do X-Request-Id. Informe ao suporte.
dataCarga útil. null em erro.
errorObjeto de erro. null em sucesso.

O tempo de processamento vai no header X-Processing-Time-Ms, não no corpo — metadado de transporte não é dado de negócio, e no corpo quebraria o cache de respostas idênticas.

Valores monetários​

Todo valor é um objeto Money com inteiro em centavos.

{ "amount": 129900, "currency": "BRL" }

Ponto flutuante é proibido em toda a plataforma. 1299.90 em JSON é IEEE 754: somar trinta parcelas de 43.33 não devolve 1299.90. Em sistema de crédito isso vira divergência de reconciliação, e ela aparece no fechamento, meses depois.

Apenas BRL é aceito. Outro valor retorna unsupported_currency.

Datas e horas​

ISO 8601 em UTC, com milissegundos e sufixo Z:

2026-07-23T14:32:10.412Z

Nunca envie horário local sem fuso. A conversão fica a cargo da camada de apresentação.

Versionamento​

Prefixo de path: /v1/.

Mudanças compatíveis — novo campo opcional na resposta, novo valor em enum não crítico, novo endpoint — entram na v1 sem aviso prévio. O seu cliente deve ignorar campos desconhecidos.

Mudanças incompatíveis — remover campo, tornar campo opcional em obrigatório, mudar tipo, mudar semântica — geram nova versão de path. A versão anterior fica disponível por no mínimo 12 meses após o anúncio de depreciação.

Paginação​

GET /v1/products?storeId=ST-0042&planId=PL-CTRL-25&page=1&pageSize=50

pageSize padrão 50, máximo 200.

Dados pessoais​

Nenhum dado pessoal em query string. Nunca.

Query string é persistida em access log, load balancer, cache de CDN, proxy corporativo, histórico de navegador e header Referer. Colocar CPF ali significa espalhá-lo por seis sistemas que não têm política de retenção compatível com a LGPD.

Por isso a consulta de venda é POST /sales/search, com o CPF no corpo, e não GET com parâmetro.

A mesma regra vale para os seus logs de aplicação: CPF, IMEI e credencial não vão para log estruturado sem mascaramento.

Rate limiting​

EscopoLimite padrão
Emissão de token60/min por client_id
Leitura (catálogo, estoque)600/min por client_id
Escrita (autorização)120/min por client_id

Excedido, a resposta é 429 com rate_limit_exceeded e header Retry-After em segundos. Implemente backoff exponencial com jitter — retry em intervalo fixo sincroniza todos os seus PDVs e reproduz o problema.

Limites são ajustáveis por contrato.

Idempotência​

Idempotency-Key é obrigatório em toda operação de escrita. Gere um UUID v4 por intenção de negócio, não por tentativa: o retry de um timeout reusa a mesma chave, é isso que impede a dupla execução.

  • Mesma chave, mesmo corpo, dentro de 24 h → resposta original, sem reprocessar.
  • Mesma chave, corpo diferente → 409 idempotency_key_conflict.
Última atualização em