Resumen general

Para activar acceso API en tu cuenta, primero debes solicitar habilitación al equipo de soporte. Solicitar acceso API por WhatsApp

Qué es CelMex API

CelMex API te permite conectar tu sistema con CelMex para vender servicios desde tu propio panel, sitio web, ERP o backend sin depender del panel manual de CelMex.

Con esta API puedes:

• Consultar tu saldo disponible.
• Obtener el catálogo de servicios con tu precio final.
• Consultar el detalle completo de un servicio antes de venderlo.
• Crear pedidos desde tu sistema.
• Consultar pedidos creados y su estado actual.

Para quién está pensada

Esta API está diseñada para:

• Revendedores que quieren integrar CelMex en su propio panel.
• Equipos que ya venden liberaciones, eSIM, checks o servicios remotos.
• Backends que necesitan automatizar compras y seguimiento de pedidos.

No está pensada para uso directo desde frontend público ni desde scripts del navegador del cliente final.

Cómo se ve una respuesta

Todas las respuestas exitosas siguen la misma estructura:

{
  "success": true,
  "requestId": "req_01K5C9N4R2JQ9W6XZ1Y8A7B6C5",
  "timestamp": "2026-03-19T16:15:42.123Z",
  "data": {}
}

Todas las respuestas con error siguen esta estructura:

{
  "success": false,
  "requestId": "req_01K5C9N4R2JQ9W6XZ1Y8A7B6C5",
  "timestamp": "2026-03-19T16:15:42.123Z",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "La API key no es válida.",
    "details": null
  }
}

Flujo recomendado de integración

Este es el flujo normal que recomendamos para integrarte con CelMex:

1. Solicita acceso API y recibe tus base URLs y llaves por entorno.
2. Guarda la clx_test_... y la clx_live_... solo en tu backend.
3. Corre el suite completo de sandbox antes de pedir habilitación productiva.
4. Consulta GET /api/v1/services con paginación para obtener catálogo y precios.
5. Consulta GET /api/v1/services/:serviceId antes de mostrar el formulario final.
6. Crea el pedido con POST /api/v1/orders.
7. Guarda orderId, requestId y tu referencia interna.
8. Consulta GET /api/v1/orders/:orderId o GET /api/v1/orders/:orderId/status para seguimiento.

Requisito antes de producción

Tu integración debe pasar sandbox por completo antes de que CelMex habilite producción.

Lee:

• Sandbox de pruebas
• Activación y go-live

Principios del contrato

• JSON limpio, estable y fácil de parsear.
• Un solo método de autenticación con Bearer token.
• Hasta 5 IPs registradas automáticamente por cuenta API.
• Solo se expone el precio final que tú pagas.
• Los IDs públicos son propios de CelMex y no dependen del proveedor upstream.
• La idempotencia evita pedidos duplicados cuando tu infraestructura reintenta requests.

Endpoints disponibles

Qué necesitas para empezar

• Una cuenta CelMex con acceso API habilitado.
• Una Sandbox API key activa.
• Una Production API key activa.
• La Sandbox base URL y la Production base URL asignadas a tu cuenta.
• Un backend capaz de enviar requests HTTPS con header Authorization.
• Un lugar donde guardar serviceId, orderId, requestId y tu referencia interna.

Ejemplo rápido con cURL

1. Verificar que tu cuenta responde

curl -X GET "https://celmexunlockers.com/api/v1/account" \
  -H "Authorization: Bearer clx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Buscar servicios

curl -G "https://celmexunlockers.com/api/v1/services" \
  -H "Authorization: Bearer clx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "search=telcel"

3. Crear un pedido

curl -X POST "https://celmexunlockers.com/api/v1/orders" \
  -H "Authorization: Bearer clx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: ik_01K5C9T0B6N4Y3Z8P2Q7R1S6A5" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "srv_01K5C9Z8Y7X6W5V4U3T2S1R0Q9",
    "clientReference": "sale_20260319_000101",
    "inputs": {
      "IMEI": "352099001761482"
    }
  }'

Qué debes guardar en tu sistema

Para operar bien y dar soporte rápido, guarda siempre:

• requestId
• orderId
• serviceId
• clientReference
• fecha y hora del intento
• payload enviado a CelMex

Recomendaciones prácticas

• Consume la API desde tu backend, no desde frontend público.
• No consultes el catálogo en cada carga de pantalla; sincronízalo en segundo plano cada 24 horas.
• El catálogo de servicios es paginado; usa page y pageSize=50, y si necesitas una copia completa recorre todas las páginas en background.
• Consulta el detalle del servicio antes de construir tu formulario final.
• Usa Idempotency-Key en cada creación de pedido.
• No asumas que todos los pedidos se completan al instante; algunos servicios pueden quedar PROCESSING.