Desarrolladorv1

CargaCell API

El mismo backend que usa la aplicación web está disponible por HTTP. Crea una clave de API desde tu perfil y autentica las solicitudes servidor a servidor con la cabecera x-api-key.

URL basehttps://www.cargacell.com/api/v1

Obtener clave API →

Inicio rápido

Autenticación con clave API

Envía tu clave en la cabecera x-api-key en cada solicitud. Las sesiones JWT del navegador siguen funcionando en paralelo para clientes web.

curl -X GET \
  https://www.cargacell.com/api/v1/auth/me \
  -H "x-api-key: cc_live_your_key"

Comportamiento de la lista blanca IP

0Cualquier IP está permitida — valor por defecto para claves nuevas.
≥1Solo esas direcciones exactas son aceptadas.
RevocarLa clave deja de funcionar inmediatamente; crea una nueva.

Referencia de endpoints

Todas las rutas son relativas a la URL base indicada arriba.

Los endpoints etiquetados como Solo web requieren un token de sesión del navegador y rechazan la autenticación con x-api-key.

Autenticación

Valida la clave y lee o actualiza el perfil de la cuenta actual.

Método	Ruta	Descripción
POST	/auth/login	Inicio de sesión con email y contraseña
GET	/auth/me	Obtener usuario autenticado actual
PATCH	/auth/me	Actualizar perfil y datos de facturación

Catálogo y carrito

Explora operadores y productos, y crea pedidos antes del pago.

Método	Ruta	Descripción
GET	/catalog/countries	Listar países disponibles
GET	/catalog/operators	Listar operadores disponibles
GET	/catalog/recharge-products	Catálogo de recargas con filtros
GET	/cart	Obtener carrito actual
POST	/cart/items	Añadir un artículo al carrito
DELETE	/cart/items/:itemId	Eliminar un artículo del carrito

Pagos y monedero

Calcula precios y despacha recargas con saldo del monedero. El checkout externo es solo para sesiones web.

Método	Ruta	Descripción	Etiquetas
POST	/payments/quote	Obtener presupuesto de precio
POST	/payments/prepare	Validar entradas del checkout web	Solo web
POST	/payments/checkout	Completar checkout web externo	Solo web
GET	/payments/history	Historial de pagos
GET	/wallet/balance	Saldo actual del monedero
POST	/wallet/checkout	Despachar recargas financiadas con monedero
POST	/api-access/b2b/recharges	Recarga B2B dedicada con monedero	B2B

Administración

Las cuentas de administrador pueden usar el mismo mecanismo de clave API para todos los endpoints del back-office.

Método	Ruta	Descripción	Etiquetas
GET	/admin/summary	Resumen del panel	Admin
GET	/admin/users	Gestión de usuarios	Admin
GET	/admin/recharges	Operaciones de recarga	Admin
GET	/admin/payments	Operaciones de pago	Admin
GET	/admin/products	Operaciones del catálogo	Admin

Ejemplos de código

Ejemplos en vivo que reflejan el comportamiento actual del backend. Alterna entre Solicitud y Respuesta en cada tarjeta.

Verificar tu clave

Envía una solicitud GET para confirmar que la autenticación funciona e inspeccionar la cuenta asociada a la clave.

curl -X GET \
  https://www.cargacell.com/api/v1/auth/me \
  -H "x-api-key: cc_live_your_generated_key" \
  -H "Accept-Language: en"

Listar productos con detalles de promoción

Obtén el catálogo de recargas. Los productos con promociones activas o programadas incluyen los detalles completos de la promo (nombre, descripción y términos opcionales).

curl -X GET \
  "https://www.cargacell.com/api/v1/catalog/recharge-products?country=ES&limit=5" \
  -H "x-api-key: cc_live_your_generated_key" \
  -H "Accept-Language: en"

Añadir un artículo al carrito

Agrega una línea de destinatario al carrito. Primero obtén el catálogo de productos para resolver un productId válido.

curl -X POST \
  https://www.cargacell.com/api/v1/cart/items \
  -H "Content-Type: application/json" \
  -H "x-api-key: cc_live_your_generated_key" \
  -d '{
    "sessionId": "agent-session-001",
    "productId": "12345",
    "recipientNumber": "+5355512345",
    "quantity": 2
  }'

Recarga B2B por monedero

Endpoint B2B dedicado — omite MONEI completamente y despacha inmediatamente con saldo aprobado del monedero.

curl -X POST \
  https://www.cargacell.com/api/v1/api-access/b2b/recharges \
  -H "Content-Type: application/json" \
  -H "x-api-key: cc_live_your_generated_key" \
  -d '{
    "items": [
      {
        "productId": "12345",
        "recipientNumber": "+5355512345",
        "quantity": 2
      }
    ],
    "baseCurrency": "EUR"
  }'

Checkout genérico por monedero

Checkout estándar financiado con monedero — funciona tanto con claves API como con sesiones web.

curl -X POST \
  https://www.cargacell.com/api/v1/wallet/checkout \
  -H "Content-Type: application/json" \
  -H "x-api-key: cc_live_your_generated_key" \
  -d '{
    "items": [
      {
        "productId": "12345",
        "recipientNumber": "+5355512345",
        "quantity": 1
      }
    ],
    "baseCurrency": "EUR"
  }'

Listar recargas (admin)

Las claves API de administrador pueden llamar a los endpoints del back-office usando la misma cabecera x-api-key.

curl -X GET \
  "https://www.cargacell.com/api/v1/admin/recharges?page=1&limit=20" \
  -H "x-api-key: cc_live_admin_key"

Flujos de recarga

Existen tres rutas de despacho. Elige la que mejor se adapte a tu integración.

Checkout con pago externo

Solo web

El navegador inicia un pago MONEI mediante POST /payments/prepare, luego confirma tras la autorización mediante POST /payments/checkout. Requiere sesión JWT web. Las claves API son rechazadas.

Checkout por monedero

Llama a POST /wallet/checkout con tus artículos. El backend calcula el saldo disponible a partir de los top-ups aprobados menos los pagos de monedero capturados, y rechaza si es insuficiente. Funciona con claves API y sesiones web.

Recarga B2B por monedero

B2B

Llama a POST /api-access/b2b/recharges. Usa el mismo motor de monedero que la ruta 2, pero está diseñado específicamente para clientes API que nunca deben interactuar con el flujo MONEI. Se despacha inmediatamente cuando el saldo es suficiente.

En todas las rutas financiadas por monedero, el pago exitoso crea filas de recarga en cola. Estas son despachadas por el procesador de recargas, o marcadas como en lista de espera cuando aplica una ventana de promoción de DT One.

Gestión de claves

Todas las operaciones con claves están disponibles en Panel → Perfil.

Crear

Crea una clave con nombre para cada integración o entorno. El valor en texto plano se muestra solo una vez en el momento de creación — cópialo inmediatamente.

Restringir

Añade entradas a la lista blanca de IP para bloquear una clave a infraestructura fija — puertas de enlace de oficina, servidores worker o IPs de salida de funciones cloud.

Revocar

Revoca las claves comprometidas o no utilizadas inmediatamente. La revocación tiene efecto al instante. Nunca reutilices claves antiguas — genera una nueva.