API para comercios de CardV

#Documentación

#Entornos

Sandbox es una copia de CardV separada, solo para pruebas, con dinero de prueba. Las claves, los saldos, los pedidos y los IDs de producto son distintos en cada entorno.

#Primeros pasos

1. Solicita una cuenta de comercio en el Portal y confirma tu correo.

2. Espera la aprobación. CardV revisa los datos de tu empresa. Luego recibes tu Merchant ID (número de comercio), por ejemplo M00000001.

3. Entra a Sandbox. Inicia sesión en el Portal y elige Sandbox en la parte superior. Recibes 1,000 USD de dinero de prueba.

4. Crea una clave de API. En el Portal, ve a Integrations → API keys. Crea una clave y muéstrala con el código que CardV te envía por correo. Guárdala en tu gestor de secretos.

5. Consulta tu 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. Busca un producto:

   ShellCopy

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

   Elige uno con "availability": "available" y anota su sku_id.

7. Consulta el precio:

   ShellCopy

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

   Anota merchant_price. Es lo que pagas por unidad.

8. Haz el pedido. Esta llamada tiene que ir firmada. Usa uno de los ejemplos de Autenticación con este cuerpo:

   JSONCopy

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

   Recibes HTTP 201 con un ID de pedido de CardV, como O-00001234.

9. Lee los códigos. Llama a GET/api/v1/orders/O-00001234 hasta que el estado sea succeeded. Los códigos están en items[].deliveries[].display_fields. También puedes recibir un webhook cuando el pedido termine.

10. Sal a producción después de completar la lista de verificación de Sandbox.

Los IDs y precios de arriba son ejemplos. Usa los valores que te devuelva tu propio catálogo.

#La API en resumen

Hay siete endpoints. Todas las rutas empiezan con /api/v1.

Cualquier otro endpoint responde HTTP 403 si lo llamas con una clave de API:

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

Las recargas de saldo de celular (tiempo aire) no están disponibles por la API.

#IDs

Guarda los IDs como texto. No intentes interpretarlos. Consulta Convenciones.

#Lo que se hace en el Merchant Portal

• Agregar fondos a tu billetera y la alerta por correo de saldo bajo
• Historial de pedidos, búsqueda y exportación a CSV
• Facturas de pedidos
• Movimientos de la billetera y conciliación
• Configuración de webhooks, historial de envíos y reenvíos
• Claves de API
• Lista de IPs permitidas
• Miembros del equipo y roles
• Registro de auditoría
• Verificación en dos pasos (2FA)
• Cambio entre Live y Sandbox

#Compatibilidad y soporte

Podemos agregar campos nuevos a las respuestas y nuevos valores de estado sin previo aviso. Ignora los campos que no conozcas. Si un pedido tiene un estado desconocido, trátalo como "todavía no terminado". No dependas del texto exacto de los mensajes de error.

Escribe a [email protected] con tu Merchant ID, el entorno, los IDs de pedido, la hora (UTC) y el código HTTP. Nunca envíes claves de API, firmas, secretos de webhook ni códigos de tarjetas.