Criar uma cobrança
Cria a cobrança de um produto e devolve o que o comprador precisa para pagar. O valor sai do produto, nunca do corpo.
POSThttps://api.navenaut.com/checkout/
Autenticação
Rota pública: não exige credencial. A ausência é declarada, não omissão.
Esta rota não exige autenticação. Ela é chamada pelo comprador, que não tem sessão: a identidade do vendedor vem da referência do produto, nunca do chamador.
Parâmetros
Cabeçalho
| Nome | Tipo | Descrição |
|---|---|---|
idempotency-keyobrigatório | texto | OBRIGATÓRIA. Sem ela a chamada é recusada com 400 antes de qualquer escrita. Aceita no máximo 64 caracteres; a maior também é recusada com 400 antes de qualquer escrita. Numa página pública, um duplo clique sem chave viraria duas compras. O MESMO valor com o MESMO corpo devolve a MESMA cobrança; com corpo diferente, recusa. |
Corpo da requisição
application/json.
| Campo | Tipo | Descrição |
|---|---|---|
adSignals | objeto | Os sinais do navegador para o envio da compra ao provedor de anúncio (cookies _fbp, _fbc, _ttp, ids de clique e a visita). Opcional; valor fora do formato é descartado sem recusar a compra. |
affiliateClick | texto | — |
bumps | arranjo de texto (uuid) | — |
buyerobrigatório | objeto | Quem está comprando. O documento é guardado para conciliação e nunca volta inteiro em nenhuma resposta. |
card | objeto | Os dados do cartão, só quando o método é cartão. Eles atravessam para o meio de pagamento e não são persistidos aqui. |
currency | um de: `BRL`, `USD`, `EUR` | A moeda da cobrança. Precisa ser a mesma do produto. |
installments | inteiro | Quantidade de parcelas, só para cartão. Os juros do parcelamento são sempre do comprador e entram no total cobrado. |
methodobrigatório | um de: `pix`, `card`, `boleto`, `wallet` | Como o comprador vai pagar. O produto declara os métodos que aceita, e um método fora dessa lista recusa. |
origin | objeto | A origem e o dispositivo do comprador: todos os parâmetros da URL de entrada, o referenciador, os cookies de anúncio, o aparelho e a visita. O vendedor os vê no detalhe da venda. Opcional; valor fora do formato é descartado sem recusar a compra, e nada com cara de cartão é guardado. |
popupDiscountAccepted | booleano | — |
productRefobrigatório | texto | A referência pública do produto a cobrar. |
tracking | objeto | Os parâmetros de origem da visita, se você os tiver. Servem à atribuição e não afetam o valor. |
{
"adSignals": {
"fbc": "exemplo",
"fbclid": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06",
"fbp": "exemplo",
"gclid": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06",
"optedOut": true,
"ttclid": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06",
"ttp": "exemplo",
"visitorId": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06"
},
"affiliateClick": "exemplo",
"bumps": [
"0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06"
],
"buyer": {
"document": "000.000.000-00",
"email": "comprador@exemplo.com.br",
"name": "Loja Exemplo",
"phone": "+55 11 90000-0000"
},
"card": {
"authenticationId": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06",
"brand": "exemplo",
"encrypted": "exemplo"
},
"currency": "BRL",
"installments": 1,
"method": "pix",
"origin": {
"cookies": {},
"device": {
"canvasHash": "exemplo",
"clientHints": {
"architecture": "exemplo",
"bitness": "exemplo",
"brands": [
"exemplo"
],
"fullVersionList": [
"exemplo"
],
"mobile": true,
"model": "exemplo",
"platform": "exemplo",
"platformVersion": "exemplo"
},
"colorDepth": 1,
"connectionType": "exemplo",
"cookieEnabled": true,
"deviceMemoryMegabytes": 1,
"doNotTrack": true,
"globalPrivacyControl": true,
"hardwareConcurrency": 1,
"languages": [
"exemplo"
],
"maxTouchPoints": 1,
"pixelRatioHundredths": 1,
"platform": "exemplo",
"screenHeight": 1,
"screenWidth": 1,
"timeZone": "exemplo",
"userAgent": "exemplo",
"utcOffsetMinutes": 1,
"vendor": "exemplo",
"viewportHeight": 1,
"viewportWidth": 1,
"webglRenderer": "exemplo",
"webglVendor": "exemplo"
},
"fingerprint": "exemplo",
"landingUrl": "https://loja.exemplo.com.br/webhooks",
"referrer": "exemplo",
"storage": {},
"urlParams": {},
"visit": {
"firstSeenAt": "exemplo",
"returning": true,
"visitCount": 1
}
},
"popupDiscountAccepted": true,
"productRef": "referencia-de-exemplo",
"tracking": {
"s1": "exemplo",
"s2": "exemplo",
"s3": "exemplo",
"sck": "exemplo",
"src": "exemplo",
"utm_campaign": "exemplo",
"utm_content": "exemplo",
"utm_medium": "exemplo",
"utm_source": "exemplo",
"utm_term": "exemplo"
}
}Respostas
200 · sucesso
{
"acquirer": "exemplo",
"chargeRef": "referencia-de-exemplo",
"currency": "BRL",
"method": "pix",
"payable": {
"emv": "exemplo",
"kind": "pix",
"qrImageUrl": "https://loja.exemplo.com.br/webhooks"
},
"paymentId": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06",
"priceCents": 129900,
"saleTransactionId": "0f2a4e6c-91c4-4e1b-9a3d-5b7c2e8f4a06",
"watchToken": "valor-de-exemplo-nao-use"
}Cobrança criada.
400 · requisição inválida
Algo que o comprador consegue corrigir e reenviar: falta o header idempotency-key ou ele passa de 64 caracteres, o documento ou os dados dele não passaram, o método não é aceito, faltou o dado do cartão, ou a quantidade de parcelas pedida não está disponível.
404 · não encontrado
A referência não resolve a um produto vendável: inexistente, arquivada ou fora de publicação.
409 · conflito
A compra não pode seguir agora: a mesma chave de idempotência já foi usada com um corpo diferente, a mesma chave ainda está em andamento, ou o meio de pagamento escolhido não está disponível para este produto.
503 · indisponível
Falta configuração do nosso lado para esta venda. Não é o comprador; reporte a ocorrência em vez de reenviar.
Erros desta rota
| Status | Código | Quando | O que fazer |
|---|---|---|---|
| 400 | CHECKOUT_IDEMPOTENCY_KEY_REQUIRED | A chamada chegou sem o cabeçalho idempotency-key, ou com ele em branco. A recusa vem antes de qualquer escrita: nada foi reservado e nenhuma cobrança existe. | Gere um valor novo por tentativa de compra, envie no cabeçalho e reenvie. Repetir sem a chave devolve o mesmo 400. |
| 400 | CHECKOUT_IDEMPOTENCY_KEY_TOO_LONG | O cabeçalho idempotency-key passa de 64 caracteres, o máximo que cabe na referência do pedido no adquirente. A recusa vem antes de qualquer escrita. | Reenvie com uma chave de até 64 caracteres. Um UUID cabe. |
| 400 | CHECKOUT_IDEMPOTENCY_KEY_RESERVED | O cabeçalho idempotency-key começa por um início que a Naut reserva. Nada foi gravado. | Reenvie com outra chave. Um UUID por tentativa serve. |
| 400 | CHECKOUT_BUYER_DOCUMENT_INVALID | O documento do comprador não é um CPF nem um CNPJ válido. A recusa acontece antes da reserva de propósito: o documento não entra no corpo canônico, então um dígito errado não deixa a chave presa. | Corrija o documento e reenvie com a MESMA idempotency-key. Cunhar uma chave nova aqui abriria uma segunda compra. |
| 400 | CHECKOUT_BUYER_DETAILS_INVALID | Nome, telefone ou e-mail do comprador não cabem no que a venda armazena: campo em branco, texto longo demais, ou telefone sem dígitos suficientes. | Corrija o campo e reenvie com a MESMA idempotency-key. Nada foi reservado. |
| 400 | CHECKOUT_METHOD_NOT_SERVED | O método de pagamento enviado não pertence ao conjunto que esta superfície cobra. | Escolha um dos métodos que a página do produto publica e reenvie. Repetir o mesmo método devolve sempre 400. |
| 400 | CHECKOUT_CARD_PAYMENT_DATA_MISSING | O método escolhido é cartão e o dado de pagamento não veio no corpo. A recusa não vem do validador de esquema: é código estável, como toda outra recusa desta superfície. | Reenvie o MESMO pedido, com a mesma idempotency-key, agora com o dado que o SDK do navegador produz. A reserva já foi liberada, então essa segunda tentativa é atendida como a compra que ela é. |
| 400 | CHECKOUT_INSTALLMENTS_NOT_AVAILABLE | A quantidade de parcelas pedida não está disponível para esta venda. É distinta de CHECKOUT_INSTALLMENT_MARKUP_BELOW_COST: aqui a escolha do comprador ainda resolve. | Ofereça as quantidades que a página do produto publica e reenvie com uma delas. |
| 404 | CHECKOUT_PRODUCT_NOT_FOUND | A productRef não resolve a um produto vendável: inexistente, arquivado, fora de publicação, ou nunca foi um produto. Referência malformada cai aqui também. | Confira a referência com quem gerou o link. Repetir não muda o resultado enquanto o produto não voltar a ser vendável. |
| 409 | CHECKOUT_IDEMPOTENCY_CONFLICT | A mesma idempotency-key já foi apresentada nesta conta com um pedido DIFERENTE. Nem o corpo anterior nem a assinatura dele voltam na resposta. | Se o pedido mudou, use uma chave nova. Se o pedido é o mesmo, reenvie byte a byte igual; repetir com o corpo alterado devolve sempre 409. |
| 409 | CHECKOUT_IN_PROGRESS | A mesma chave já foi reivindicada e a compra ainda não concluiu. É a janela entre as duas fases da reserva, e devolver um corpo pela metade seria pior do que recusar. | Espere alguns instantes e repita a MESMA requisição com a MESMA chave. Nunca cunhe outra: a chave nova abriria uma segunda compra. |
| 409 | CHECKOUT_METHOD_NOT_AVAILABLE | O método existe, mas a conta que vende ainda não está habilitada a recebê-lo na origem. É pendência de cadastro dela, não configuração daqui. | Não é o comprador, e reenviar não resolve. Ofereça outro método enquanto o vendedor conclui o cadastro. |
| 409 | CHECKOUT_ACQUIRER_MAPPING_MISSING | Falta configuração do nosso lado para cobrar esse método por essa conta. Nada quebrou: o caminho simplesmente não está montado. | Reporte a ocorrência com a productRef e o método. Reenviar o mesmo pedido devolve o mesmo código. |
| 409 | CHECKOUT_PLATFORM_SHARE_BELOW_FLOOR | A divisão fecha, mas a fatia da plataforma não alcança o piso daquele par de método e valor. A recusa chega antes de qualquer ida à rede: nenhuma cobrança foi criada. | Nenhuma escolha do comprador resolve. O preço do produto ou a taxa daquele vendedor precisa mudar; até lá, esse método não vende esse produto. |
| 409 | CHECKOUT_INSTALLMENT_MARKUP_BELOW_COST | Os juros mínimos da plataforma não cobrem o custo desta venda parcelada, medido contra as tarifas do dia. | Nenhuma quantidade de parcelas que o comprador escolha resolve, e o vendedor também não: a plataforma precisa recalibrar a taxa. Até lá, esta venda parcelada não passa. |
| 409 | CHECKOUT_POPUP_DISCOUNT_NOT_AVAILABLE | O pedido marcou popupDiscountAccepted, mas o produto não tem desconto de pop ligado agora. O vendedor o desligou depois de a página abrir. Nada foi gravado. | Leia o produto de novo e mostre o preço atual. Reenvie sem popupDiscountAccepted. |
| 409 | CHECKOUT_ORDER_BUMP_UNAVAILABLE | O pedido marcou em bumps uma oferta adicional que não está mais à venda, ou o meio escolhido não serve a um dos produtos marcados. Nada foi gravado. | Leia o produto de novo, mostre só os orderBumps que ele devolve e reenvie com eles. |
| 503 | CHECKOUT_PRIMARY_SELLER_POLICY_MISSING | A política do vendedor principal, que é a parte que sustenta disputa e estorno, não está configurada. É deployment nosso, e o comprador não podia ter causado isso. | Reporte a ocorrência. Reenviar não resolve, e nenhuma correção no corpo muda o resultado. |
Os códigos são estáveis e fazem parte do contrato. A lista completa, com todos os vocabulários, está na tabela de erros.