Skip to main content

​
Formato de erro

Toda resposta de erro segue o padrão RFC 7807 (Problem Details), com os campos em português:

erros vs. detalhe

O campo erros aparece apenas em erros de validação de payload (um ou mais campos inválidos, detalhados por nome). Erros de regra de negócio (ex.: pedido em status incompatível, saldo indisponível) não preenchem erros — a explicação vem apenas em detalhe.

​
Rastreamento com CorrelationId

Toda requisição pode enviar um cabeçalho CorrelationId com um identificador de sua escolha. Se você não enviar um, a API gera um automaticamente. O valor é sempre devolvido:
  • No cabeçalho de resposta CorrelationId.
  • No campo correlationId do corpo, em respostas de erro.
Guarde esse valor nos seus logs — é o identificador que o suporte da Parcele+ usa para localizar rapidamente uma requisição específica.

​
Reenvio seguro com Idempotency-Key

Endpoints de criação (POST) aceitam o cabeçalho opcional Idempotency-Key. Ele permite reenviar a mesma operação com segurança após um timeout, erro de rede ou qualquer situação em que você não teve certeza se a requisição original foi processada.
1

Gere uma chave única por operação

Antes de chamar a API, gere um identificador único (recomendamos um UUID) para aquela tentativa lógica de operação — por exemplo, uma venda específica que seu sistema está tentando criar.
2

Envie a chave no cabeçalho

Inclua Idempotency-Key: <sua-chave> na requisição.
3

Reenvie com a mesma chave se precisar tentar novamente

Se a chamada falhar por timeout ou erro de rede, repita a requisição com a mesma chave e o mesmo corpo. A API retorna a resposta da tentativa original, sem repetir a operação.

Chave reutilizada com corpo diferente

Retorna 409 Conflict. Uma mesma Idempotency-Key está atrelada ao corpo exato da primeira requisição.

Requisição concorrente em processamento

Se uma segunda requisição chegar com a mesma chave enquanto a primeira ainda está sendo processada, também retorna 409 Conflict.
A resposta de uma Idempotency-Key fica disponível para reenvio por 24 horas. Após esse período, uma nova requisição com a mesma chave é tratada como uma operação nova.
Endpoints recomendados para uso de Idempotency-Key: POST /v1/order, POST /v1/order/invoice e POST /v1/order/start-cdc-sale.