Convenções

Veja também: Autenticação · Catálogo e pedidos · README

#Requisições

• URL base: https://b2b.cardv.net/api/v1 (Live) ou https://sandbox.cardv.net/api/v1 (Sandbox).
• Os caminhos não terminam com barra. Use /api/v1/orders, e não /api/v1/orders/.
• Envie corpos JSON em UTF-8, com Content-Type: application/json.
• Envie valores como texto, por exemplo "9.2500". Assim não há erro de arredondamento.
• Defina um User-Agent claro, por exemplo AcmeShop-CardV/1.4.

#Valores e horários

• Valores são texto com 4 casas decimais, por exemplo "merchant_price": "9.2500".
• Leia com um tipo decimal, nunca com número de ponto flutuante.
• Você paga na moeda da sua carteira (default_currency em GET/account, hoje USD).
• face_currency é a moeda impressa no cartão. Ela pode ser diferente da moeda da sua carteira.
• Use sempre merchant_price para calcular os seus custos. Campos como price_label servem só para exibição.
• Todos os horários estão em UTC, no formato ISO 8601, por exemplo 2026-09-29T08:15:30.123456Z.
• Use um parser ISO 8601 de verdade. A quantidade de casas decimais nos segundos pode variar.
• O X-Timestamp da assinatura é o horário Unix em segundos.

#Identificadores

• Guarde os IDs como texto e não tente interpretá-los. Eles podem ficar mais longos.
• Os pedidos também têm um id numérico. Não use esse campo. Use order_id.
• No seu número de pedido, use só A–Z a–z 0–9 - _ ..

#Paginação

Só GET/skus é paginado. Envie limit e offset:

GET /api/v1/skus?limit=100&offset=200

{"count": 1234, "limit": 100, "results": ["..."], "filter_options": {}}

• O padrão de limit é 100 e o máximo é 500. Valores maiores viram 500.
• count é o total de resultados. Continue pedindo até offset chegar a count.
• Um limit ou offset negativo ou que não seja número retorna HTTP 400.
• Um valor de filtro desconhecido retorna uma lista vazia, e não um erro.

#Limite de requisições

• O padrão é 60 requisições por minuto para a conta inteira. Todas as suas chaves e usuários do Portal dividem esse limite. O seu plano pode ter outro número.

• O minuto começa no :00 do relógio. Requisições recusadas também contam.

• Acima do limite, você recebe HTTP 429 e um cabeçalho Retry-After (segundos de espera):

  JSONCopy

  {"detail": "Merchant API rate limit exceeded. Expected available in 23 seconds."}

• Para ficar dentro do limite: guarde a lista de SKUs em cache, use webhooks em vez de consultar o tempo todo e espere um pouco mais a cada 429.

#Erros

Confira sempre o status HTTP primeiro. Depois leia o corpo JSON. A chave no corpo diz o que deu errado. Não dependa do texto da mensagem.

Erros de autenticação, permissão, item não encontrado e limite de requisições usam detail:

{"detail": "Order not found."}

Erros de pedido e de preço indicam o campo:

{"balance": "Insufficient available balance."}

Um item de pedido mal formado é informado item por item, na mesma posição dos seus items:

{"items": [{}, {"quantity": ["Ensure this value is greater than or equal to 1."]}]}

Alguns erros não vêm em JSON:

• HTTP 403 com texto simples, como error code: 1010, vem da borda de rede da CardV. A sua requisição nem chegou à CardV. Envie à CardV o IP do seu servidor e o User-Agent.
• Um caminho desconhecido (404) ou um erro de proxy (5xx) pode retornar HTML.

Ao registrar erros em log, nunca inclua chaves de API, assinaturas ou códigos.

#Códigos de status HTTP

Em POST/orders, só tente de novo com o mesmo corpo e o mesmo número de pedido. Veja como reenviar com segurança.

#Respostas

• brand_logo_url e image_url são URLs completas de imagens hospedadas pela CardV, ou "". Elas são públicas e podem ficar em cache.
• Os campos invoice_url e delivery_file_url do pedido são caminhos como /orders/O-00001234/invoice, ou "" quando ainda não há nada. Eles só funcionam no Portal: com chave de API, retornam HTTP 403. Abra faturas e arquivos CSV de códigos pelo Portal.

#Compatibilidade

• Ignore os campos que você não conhece. A CardV adiciona campos sem lançar uma nova versão da API.
• Podem aparecer novos status. Trate um status desconhecido como "ainda não terminou".
• Não dependa da ordem das chaves no JSON nem do texto das mensagens.