Respostas e Convenções da API

Como interpretar uma resposta

Considere o código HTTP junto com o corpo e o estado do recurso. HTTP 200 ou 201 informa o resultado da requisição previsto pelo endpoint. Para confirmar a aprovação do pagamento, confira os campos da Venda e da Transação retornadas.

Na resposta de uma Venda, status descreve a situação consolidada da Venda. Em transactions[], status resume cada Transação e detailed_status informa sua etapa de processamento. Uma Transação paga pode coexistir com uma Venda parcialmente paga. Consulte Venda e Transação e Status da Transação.

Quando houver corpo JSON, interprete-o conforme o schema da operação. Uma resposta 204 No Content não tem corpo; não tente interpretá-la como JSON.

Códigos HTTP

Esta tabela reúne respostas documentadas nos endpoints consultados e erros confirmados nos fluxos implementados. Cada código se aplica às operações indicadas; não presuma que todas as rotas retornem todos eles.

HTTP	Significado	Quando ocorre	Ação recomendada
`200`	Requisição concluída	Consultas e operações como pagamento de Venda em aberto.	Leia o corpo e confira o estado financeiro quando houver pagamento.
`201`	Recurso criado	Criação de Venda.	Armazene o UUID e acompanhe a Venda e suas Transações.
`204`	Operação concluída sem conteúdo	Documentado em captura de cartão e invalidação de Pix/Boleto.	Não tente ler JSON; consulte a Transação quando precisar confirmar seu estado.
`400`	Solicitação rejeitada pelo fluxo	Validação de campos, estado incompatível e determinados erros de processamento ou comunicação.	Leia `parameter` ou `errors[]`. Não presuma que toda resposta 400 é apenas erro de preenchimento.
`401`	Autenticação ou habilitação rejeitada	Chave ausente/inválida, empresa inativa e algumas verificações de habilitação de Split.	Confira credencial, ambiente e o identificador do erro.
`403`	Acesso ou operação bloqueados	Restrição de IP ou configuração que impede múltiplos pagamentos.	Revise a regra indicada antes de reenviar.
`404`	Recurso não encontrado	Consultas e operações cujo fluxo não encontra a Venda, Transação, Checkout ou Vendedor.	Confira identificador, empresa e ambiente.
`409`	Conflito	Idempotência, captura/cancelamento já realizado e Split já existente, conforme a operação.	Consulte o estado atual antes de decidir por outra tentativa.
`429`	Limite de tentativas atingido	Limite da sessão de SmartForm no fluxo de Checkout.	Interrompa as tentativas e investigue o resultado.
`500`	Falha interna	Tratamento comum de erro interno do Gateway.	Registre a correlação e consulte o recurso antes de repetir uma ação financeira.
`503`	Falha de comunicação com serviço externo	Confirmado no fluxo implementado de criação de Transação de cartão.	Consulte a Venda e as Transações antes de decidir por outro envio.

Estrutura das respostas de erro

O tratamento comum de erros de domínio utiliza esta estrutura. O exemplo corresponde à condição de Venda não encontrada; o UUID de correlação é fictício.

{
  "message": "charge not found",
  "parameter": "charge.not_found",
  "correlation_uuid": "11111111-1111-4111-8111-111111111111"
}

Campo	Responsabilidade
`message`	Descrição da condição para diagnóstico. O texto pode variar; evite usá-lo como chave de decisão.
`parameter`	Identificador técnico do erro tratado, como `charge.not_found`. Use-o junto ao HTTP e à operação.
`correlation_uuid`	Identificador que permite relacionar a requisição ao diagnóstico do Gateway. Registre-o quando presente.
`error`	Detalhe adicional opcional de diagnóstico. O tratamento comum o omite em produção e Sandbox; a integração não deve depender dele.

O nome parameter não significa necessariamente um campo inválido. Ele também identifica erros de autenticação, estado de recurso, configuração e processamento.

Consulte Códigos de erros para interpretar cada identificador. Não presuma um envelope único: validação de campos e algumas respostas do Checkout usam formatos diferentes.

Erros de validação

A criação de Venda valida campos como order_id. Quando ele está ausente e os demais dados exigidos são válidos, a validação pode retornar HTTP 400 com o seguinte item:

{
  "errors": [
    {
      "field": "order_id",
      "message": "cannot be blank"
    }
  ]
}

field aponta o campo rejeitado e message descreve a falha. Uma mesma resposta pode conter vários itens. Corrija os campos indicados, confira os tipos e regras do endpoint e valide a solicitação novamente. Esse formato não inclui necessariamente parameter ou correlation_uuid; capture também os headers de diagnóstico disponíveis.

Resposta específica do SmartForm

Ao atingir o limite de tentativas da sessão, o fluxo de Checkout responde HTTP 429 com uma serialização própria:

{
  "Message": "maximum number of attempts reached for checkout smartform",
  "Param": "checkout.smartform_limit_exceeded"
}

Observe as maiúsculas em Message e Param. Nesse caso, o identificador está em Param; não exija parameter para reconhecer a condição. O prazo de liberação e o procedimento de recuperação da sessão permanecem A confirmar.

Convenções de dados e requisições

Tema	Como interpretar
JSON	Envie o corpo no formato aceito pelo endpoint, normalmente `application/json`, com os nomes de campos exatamente como documentados. Leia JSON somente quando houver corpo.
UUID	Venda e Transação têm UUIDs próprios. Um `charge_uuid` identifica a Venda; `transaction_uuid` identifica uma Transação. Não troque um pelo outro.
Outros identificadores	`order_id` é a referência do pedido enviada pela integração. `gateway_id` e `external_id` são identificadores distintos retornados em Transações; não os use como UUID de caminho sem previsão no endpoint.
Valores monetários	As consultas de Vendas e Transações documentam valores inteiros em centavos: `1000` corresponde a R$ 10,00. Confira a unidade do campo; valores percentuais de Split seguem o contrato próprio.
Datas e horários	Há timestamps nos exemplos de resposta com `Z`, datas sem horário e formatos específicos por campo. Preserve o fuso recebido e siga a regra do endpoint para envio e filtros; não aplique uma conversão global.
Campos opcionais	Omitir um campo, enviar `null`, `""`, `0` ou `false` pode ter efeitos diferentes. Confira obrigatoriedade, tipos e regras; opcional não significa que qualquer valor vazio seja aceito.
Valores nulos	Alguns dados de autorização e datas podem vir como `null`. Trate a ausência de informação sem converter automaticamente para zero ou texto vazio.
Arrays	Respeite a estrutura de itens. Uma Venda pode retornar `transactions: []` sem que isso represente erro de JSON; listas paginadas usam estruturas próprias.
Parâmetros de URL	Substitua os parâmetros de caminho pelo identificador correto. Use apenas os filtros documentados para aquela consulta e codifique valores de query conforme a URL.

As consultas de Vendas e Transações têm paginação e regras próprias para filtros de data, incluindo ajustes em alguns campos. Essas regras não se aplicam automaticamente a outras operações.

Headers relevantes

Header	Uso
`api_key`	Credencial da empresa nas chamadas autenticadas. Use a chave do ambiente correspondente.
`Content-Type: application/json`	Identifica o formato do corpo nas operações que recebem JSON.
`Correlation-Id`	Correlação reconhecida pelo middleware do Gateway, conforme a seção seguinte.
`Idempotency-Key`	UUID opcional nas rotas de criação de Venda, pagamento de Venda em aberto e simulação de pagamento no Sandbox.

Use o host correto de Live ou Sandbox. Consulte Chaves e Autenticação da API para obter e proteger a credencial.

Idempotência

O header opcional Idempotency-Key aceita UUID nas seguintes operações:

Operação	Resposta de uma repetição concluída
Criar venda — `POST /v1/charges`	`201` com a Venda em seu estado atual.
Pagar venda em aberto — `POST /v1/charges/{charge_uuid}/pay`	`200` com a Venda em seu estado atual.
Simular pagamento Pix/Boleto — `POST /v1/transactions/{transaction_uuid}/pay`	`204`, sem corpo. Disponível somente no Sandbox.

A chave identifica uma solicitação de criação, pagamento ou simulação, conforme a rota. Se a resposta ficar inconclusiva e for necessário repetir a mesma operação, mantenha a chave e o corpo. Use outra chave somente para uma nova operação, depois de verificar o resultado da anterior.

No fluxo implementado:

A chave é associada à empresa, à operação e ao recurso.
Uma repetição concluída usa o retorno da operação indicado na tabela; não há garantia de repetir os mesmos bytes da resposta original. Na criação de Venda, dados transitórios de 3DS ou SmartForm da primeira resposta podem não ser reconstituídos.
Payload diferente produz 409 idempotency_key.payload_mismatch.
Uma solicitação ainda em processamento produz 409 idempotency_key.processing.
Uma tentativa registrada como falha produz 409 idempotency_key.failed; a mesma chave não reinicia esse processamento.
Resultado indisponível produz 409 idempotency_key.result_not_found.

Não contorne um conflito enviando imediatamente outra chave para o mesmo pagamento. Consulte o estado da Venda e das Transações. O prazo de retenção da chave e uma política de retry automático permanecem A confirmar.

Para timeout, recusa ou resposta inesperada, consulte Solução de Problemas e Boas Práticas.