Servicios

GET /api/v1/services

Este endpoint lista los servicios visibles y ordenables para tu cuenta API.

Cada servicio ya incluye:

• serviceId estable de CelMex.
• Nombre comercial.
• Tipo de servicio.
• Grupo o categoría.
• Precio final para tu cuenta.
• Tiempo estimado.
• Disponibilidad.

Cuándo usarlo

Úsalo para:

• Construir tu catálogo.
• Mostrar resultados de búsqueda.
• Filtrar por tipo o categoría.
• Sincronizar servicios visibles en tu panel.

Regla de integración

Este endpoint es paginado por diseño.

• No existe un modo soportado para descargar los 3,000+ servicios en una sola respuesta.
• El pageSize máximo permitido es 50.
• Si necesitas una copia local completa del catálogo, debes recorrer páginas en segundo plano hasta completar el total.
• Ese recorrido completo debe hacerse como proceso de sincronización, no dentro de una carga de pantalla ni durante la navegación del usuario.
• El listado está protegido con rate limiting específico para impedir sincronizaciones agresivas o crawling continuo.

Frecuencia recomendada de actualización

No consultes GET /api/v1/services cada vez que un usuario entra a una vista, abre una categoría o refresca una pantalla.

Recomendación práctica:

• sincroniza el catálogo base cada 24 horas;
• cuando necesites una copia completa, recorre page=1, page=2, page=3, etc. con pageSize=50 hasta terminar;
• no consultes el listado completo en cada carga de pantalla ni por cada usuario;
• sirve categorías, búsqueda y listados desde tu propia cache o base de datos local;
• antes de confirmar una venta, consulta GET /api/v1/services/:serviceId para validar detalle, reglas y precio visible.

Patrón recomendado:

1. sincroniza GET /api/v1/services en segundo plano;
2. si quieres reflejar todo el catálogo, consume todas las páginas con pageSize=50;
3. guarda serviceId, nombre, grupo, precio y disponibilidad en tu sistema;
4. muestra ese catálogo desde tu propia capa cacheada;
5. consulta el detalle del servicio justo antes de construir o confirmar el formulario final.

Query params

• search: búsqueda libre por nombre o categoría.
• type: filtro por tipo como IMEI, REMOTE o SERVER.
• page: página a consultar, empezando en 1.
• pageSize: cantidad de resultados por página. Máximo 50.

Metadatos útiles de catálogo

Además de los resultados paginados, la respuesta incluye:

• total: cantidad total de resultados que hacen match con tu query actual;
• totalVisible: cantidad total de servicios visibles para tu cuenta;
• typeCounts: desglose total por tipo de servicio visible para tu cuenta.

Ejemplo de respuesta

{
  "success": true,
  "requestId": "req_01K5CAD7F8G9H0J1K2L3M4N5P6",
  "timestamp": "2026-03-19T16:25:00.000Z",
  "data": {
    "page": 1,
    "pageSize": 50,
    "totalPages": 67,
    "hasMore": true,
    "total": 3350,
    "totalVisible": 3350,
    "typeCounts": {
      "IMEI": 1657,
      "REMOTE": 169,
      "SERVER": 1524,
      "INSTANT": 133
    },
    "items": [
      {
        "serviceId": "srv_01K5CAF2E4R6T8Y0U1I2O3P4A5",
        "name": "Premium Android Remote Unlock",
        "type": "REMOTE",
        "group": {
          "id": "grp_01K5CAH9J8K7L6M5N4B3V2C1X0",
          "name": "Android Remote Services"
        },
        "price": 149.90,
        "currency": "MXN",
        "estimatedTime": "1-6 Hours",
        "availability": {
          "isVisible": true,
          "isOrderable": true
        }
      },
      {
        "serviceId": "srv_01K5CAK4Q7W8E9R0T1Y2U3I4O5",
        "name": "Recarga TELCEL",
        "type": "SERVER",
        "group": {
          "id": "grp_01K5CAH9J8K7L6M5N4B3V2C1X0",
          "name": "CelMex Official Partners."
        },
        "price": 10.00,
        "currency": "MXN",
        "estimatedTime": "Instantáneo",
        "availability": {
          "isVisible": true,
          "isOrderable": true
        }
      }
    ]
  }
}

Recomendación de catálogo

No generes formularios directamente desde la respuesta corta de lista.

El patrón correcto es:

1. Listar con GET /api/v1/services?page=1&pageSize=50
2. Guardar el serviceId
3. Consultar GET /api/v1/services/:serviceId
4. Construir el formulario usando el detalle del servicio

GET /api/v1/services/:serviceId

Usa este endpoint cuando necesitas mostrar la ficha completa del servicio antes de venderlo.

El detalle puede incluir:

• instrucciones HTML;
• tiempo estimado;
• tiempo promedio;
• campos requeridos;
• reglas de cantidad;
• información adicional útil para renderizar el formulario.

Ejemplo de respuesta

{
  "success": true,
  "requestId": "req_01K5CAP6Z7X8C9V0B1N2M3Q4W5",
  "timestamp": "2026-03-19T16:28:00.000Z",
  "data": {
    "serviceId": "srv_01K5CAF2E4R6T8Y0U1I2O3P4A5",
    "name": "Premium Android Remote Unlock",
    "type": "REMOTE",
    "group": {
      "id": "grp_01K5CAH9J8K7L6M5N4B3V2C1X0",
      "name": "Android Remote Services"
    },
    "price": 149.90,
    "currency": "MXN",
    "estimatedTime": "1-6 Hours",
    "averageTime": "2-4 Hours",
    "instructionsHtml": "<p>Confirma el modelo exacto antes de crear el pedido.</p>",
    "providerInfo": {
      "infoText": "Remote service with manual verification.",
      "rawInfoHtml": "<p>Disponible de lunes a sábado.</p>"
    },
    "inputSchema": [
      {
        "fieldname": "MODEL",
        "fieldtype": "text",
        "description": "Código de modelo del equipo",
        "required": "on"
      },
      {
        "fieldname": "SN",
        "fieldtype": "text",
        "description": "Serial number",
        "required": "on"
      }
    ],
    "quantityRules": {
      "min": 1,
      "max": 1,
      "qnt": "1"
    },
    "availability": {
      "isVisible": true,
      "isOrderable": true
    }
  }
}

Cómo construir el formulario

Usa estas reglas:

• Si inputSchema trae campos text, muestra inputs de texto.
• Si trae opciones, renderiza dropdown o radio según tu UX.
• Si quantityRules.max es 1, no muestres selector de cantidad.
• Si instructionsHtml existe, muéstralo antes del envío final.

Caso especial: servicios con monto variable

Algunos servicios, como ciertas recargas o partners directos, usan:

• un precio visible mínimo en catálogo;
• pero el precio final se calcula con base en la opción elegida en el formulario.

Por eso siempre debes consultar el detalle del servicio antes de confirmar una venta.

Qué debes cachear y qué no

Puedes cachear:

• lista corta de servicios;
• grupos y resultados de búsqueda.

Tiempo recomendado:

• lista general: 24 horas;
• búsquedas y categorías: usa tu propia capa cacheada a partir de esa sincronización;
• detalle del servicio: consúltalo antes de vender y, si quieres, cachea la respuesta por poco tiempo (1-5 minutos) para evitar llamadas repetidas durante la misma sesión de venta.

Paginación recomendada

Para integraciones nuevas, usa siempre paginación en el listado:

• GET /api/v1/services?page=1&pageSize=50
• avanza con page=2, page=3, etc.
• usa totalPages y hasMore para controlar la navegación
• combina search y type con la paginación cuando necesites filtrar

Sincronización completa recomendada

Si tu sistema necesita una copia local completa del catálogo:

1. ejecuta un job cada 24 horas;
2. empieza por GET /api/v1/services?page=1&pageSize=50;
3. sigue avanzando hasta que hasMore sea false;
4. reemplaza o actualiza tu catálogo local con esos resultados;
5. durante el día, sirve listados y búsquedas desde tu propia base local.

Rate limiting del listado

GET /api/v1/services tiene protección específica además del límite general de la API:

• se espera que el recorrido completo del catálogo ocurra como máximo una vez cada 24 horas;
• si tu integración intenta recorrer páginas de forma agresiva o repetitiva, la API puede responder 429 RATE_LIMITED;
• el límite exacto depende de la configuración de tu cuenta API y puedes consultarlo en GET /api/v1/account;
• el detalle GET /api/v1/services/:serviceId sigue siendo el endpoint correcto para validar el servicio justo antes de vender.

Búsqueda interactiva recomendada

Si el usuario final está explorando servicios:

• no llames a la API en cada tecla;
• busca sobre tu copia local del catálogo;
• usa GET /api/v1/services/:serviceId sólo cuando ya vayas a mostrar el detalle final o construir el formulario.

No deberías cachear demasiado tiempo:

• el detalle si dependes de reglas dinámicas;
• instrucciones si el proveedor cambia con frecuencia;
• disponibilidad si operas con catálogos muy cambiantes.