API para lojistas CardV

#Documentação

#Ambientes

O Sandbox é uma cópia de testes da CardV, separada e com dinheiro de teste. Chaves, saldos, pedidos e IDs de produto são diferentes em cada ambiente.

#Primeiros passos

1. Cadastre-se. Solicite uma conta de lojista no Portal e confirme o seu e-mail.

2. Aguarde a aprovação. A CardV analisa a sua empresa. Depois você recebe um Merchant ID (seu código de lojista), por exemplo M00000001.

3. Abra o Sandbox. Entre no Portal e escolha Sandbox no topo da página. Você ganha 1.000 USD em dinheiro de teste.

4. Crie uma chave de API. No Portal, vá em Integrations → API keys. Crie a chave e depois exiba o valor completo com o código que a CardV envia por e-mail. Guarde a chave no seu cofre de segredos.

5. Consulte o saldo:

   ShellCopy

   export CARDV_BASE=https://sandbox.cardv.net
   export CARDV_MERCHANT_ID=M00000001     # yours
   export CARDV_API_KEY=cvb2b_...         # from your secret store
   AUTH=(-H "X-Merchant-Id: $CARDV_MERCHANT_ID" -H "X-Api-Key: $CARDV_API_KEY")
   
   curl -sS "$CARDV_BASE/api/v1/balance" "${AUTH[@]}"

6. Encontre um produto:

   ShellCopy

   curl -sS "$CARDV_BASE/api/v1/skus?search=steam&limit=20" "${AUTH[@]}"

   Escolha um com "availability": "available" e anote o sku_id.

7. Veja o preço:

   ShellCopy

   curl -sS "$CARDV_BASE/api/v1/skus/S000001/quote?quantity=1" "${AUTH[@]}"

   Anote o merchant_price. É quanto você paga por unidade.

8. Faça o pedido. Esta chamada precisa ser assinada. Use um dos exemplos de Autenticação com este corpo:

   JSONCopy

   {
     "external_order_id": "TEST-0001",
     "items": [
       {"sku_id": "S000001", "quantity": 1, "expected_unit_price": "9.2500"}
     ]
   }

   A resposta é HTTP 201, com um número de pedido da CardV, como O-00001234.

9. Busque os códigos. Chame GET/api/v1/orders/O-00001234 até o status ser succeeded. Os códigos ficam em items[].deliveries[].display_fields. Você também pode receber um webhook quando o pedido terminar.

10. Entre em produção depois de passar pelo checklist do Sandbox.

Os IDs e preços acima são só exemplos. Use os valores que o seu catálogo retornar.

#Visão geral da API

São sete endpoints. Todos os caminhos começam com /api/v1.

Qualquer outro endpoint chamado com chave de API retorna HTTP 403:

{"detail": "This operation is only available in the Merchant Portal."}

Recarga de celular não está disponível pela API.

#IDs

Guarde os IDs como texto e não tente interpretá-los. Veja Convenções.

#O que fica no Portal

• Adicionar saldo à carteira e o alerta de saldo baixo por e-mail
• Histórico de pedidos, busca e exportação em CSV
• Faturas dos pedidos
• Movimentações da carteira e conciliação
• Configuração de webhooks, histórico de envios e reenvio
• Chaves de API
• Lista de IPs permitidos
• Usuários da equipe e perfis de acesso
• Registro de auditoria
• Verificação em duas etapas (2FA)
• Troca entre Live e Sandbox

#Compatibilidade e suporte

Podemos adicionar novos campos e novos status nas respostas sem aviso prévio. Ignore os campos que você não conhece. Trate um status de pedido desconhecido como "ainda não terminou". Não dependa do texto das mensagens de erro.

Escreva para [email protected] informando o seu Merchant ID, o ambiente, os números dos pedidos, o horário (UTC) e o status HTTP. Nunca envie chaves de API, assinaturas, segredos de webhook nem códigos de cartão.