Valores, datas e identificadores

Valores nas respostas: reais, como número

Nas respostas da API, todo valor em dinheiro vem em reais, como número:

{
  "total_amount": 197.9,
  "items": [
    { "amount": 197.9, "original_amount": 219.9, "discount_value": 22 }
  ]
}

197.9 significa R$ 197,90.

Valores que você envia: centavos, como número inteiro

Todo valor em dinheiro que você envia à API vai em centavos, como número inteiro. A unidade é a mesma em todos os campos:

Nas quatro rotas, um price com casas decimais, como 49.9, é recusado com 400. Envie 4990.

offer.value tem um valor mínimo. Por padrão, é 500 (R$ 5,00). Abaixo disso, a resposta é 400. price não tem esse mínimo: a validação aceita qualquer inteiro a partir de 0. Quem limita na prática, na oferta avulsa, é a parcela mínima.

A API converte para reais ao gravar. Por isso a oferta volta com price em reais na resposta.

Parcela mínima

Numa oferta avulsa, cada parcela no cartão precisa valer pelo menos R$ 5,00 (valor padrão), senão a criação responde 400 com o valor da parcela e o mínimo em vigor na message. A conta, os exemplos e o que fazer estão em A regra da parcela mínima.

Datas

• Datas nas respostas vêm em ISO 8601, em UTC: 2026-09-15T14:30:00.000Z.
• Datas que ficam vazias vêm null. Exemplo: paid_at enquanto a venda não foi paga.
• Nos filtros, envie data e hora em ISO 8601 com fuso: 2026-09-15T23:59:59-03:00.

Identificadores

A API usa quatro tipos de identificador:

Códigos com prefixo

Todo código é um prefixo seguido de 10 dígitos, que podem começar com zero. Nas respostas da API e no webhook, o código sai sempre com o prefixo. É o mesmo código que aparece no painel.

Guarde e compare o código como ele chega, com o prefixo. Para ligar registros entre a API e o webhook, prefira o id.

Na entrada, o código funciona com ou sem o prefixo, em toda rota da tabela abaixo que aceita código. PPP1234567890 e 1234567890 encontram a mesma oferta, e PPO9876543210 e 9876543210 encontram a mesma venda.

Qual identificador cada rota aceita

Onde a rota aceita código, você também pode enviar o link com o código no final: a API lê o último pedaço do link. Para a oferta, ela usa só os números desse pedaço. Para a venda, o pedaço precisa ter o formato do código da venda, descrito abaixo.

Como a venda é encontrada

GET /sales/{identifier} testa o valor nesta ordem e para no primeiro que encontrar:

1. Se o valor é um uuid, procura pelo id da venda.
2. Se o valor tem o formato do código da venda, procura pelo código. O formato é: o prefixo seguido de 10 dígitos, sem diferenciar maiúsculas de minúsculas (PPO0087103960 ou ppo0087103960); exatamente 10 dígitos, sem o prefixo (0087103960); ou um link cujo último pedaço é um desses dois.
3. Procura pela external_reference, com o texto exato. Se a mesma referência foi usada em mais de uma venda, devolve a mais recente.

Se nada for encontrado, a resposta é 404 com Venda não encontrada.

Documento e telefone

A API confere o formato do documento e do telefone antes de criar qualquer coisa. A regra vale para estes campos:

• customer.document e customer.phone, nas cobranças (POST /payments/pix, POST /payments/boleto e POST /payments/credit-card) e na criação de assinatura (POST /plans/offer/{id}/subscribe);
• holder_document, o documento do titular do cartão, na cobrança no cartão, na criação de assinatura, na troca de cartão (PATCH /subscriptions/{id}/card) e em card na troca de plano (POST /subscriptions/{id}/plan-change).

Pontuação é aceita e removida: no telefone, isso inclui espaços, parênteses e +. A API grava só os dígitos. 123.456.789-09 é gravado como 12345678909, e +55 11 99999-8888 como 5511999998888.

Fora do formato, a resposta é 400 invalid_request e nada é criado:

Dados pessoais mascarados

Nas respostas da API, o documento e o telefone do cliente vêm mascarados:

O nome e o e-mail vêm completos.

Nos eventos de webhook esses dados chegam sem máscara. Veja Dados pessoais no webhook.