Developers · Referencia

Referencia de la API de Interlinked

Vista conceptual del contrato de API. Los endpoints y payloads finales se entregan junto con tus llaves de sandbox; esta página describe el modelo de integración para que tu equipo pueda planear el trabajo.

Solicita acceso →

Autenticación

Todas las peticiones usan un bearer token en el encabezado Authorization. Cada cliente B2B recibe un par de llaves emitidas por nuestro equipo:

il_test_… — sandbox. Responde con datos ficticios y nunca genera costo.
il_live_… — producción. Emite perfiles reales sobre la red Interlinked.

curl https://api.interlinked.mx/v1/catalog \
  -H "Authorization: Bearer il_test_4f9a2c8b1d..."

Las llaves se muestran una sola vez al emitirlas. Guárdalas como secreto en tu backend y nunca las expongas en clientes web o móviles.

Modo test vs live

El entorno lo determina la llave, no la URL. El mismo endpoint y el mismo payload funcionan en ambos modos, así que pasar a producción es cambiar una variable de entorno.

Aspecto	Test	Live
Prefijo de llave	il_test_	il_live_
Datos	Catálogo y perfiles ficticios	Catálogo y perfiles reales
ICCID	Rango de prueba, no instalable	Perfil real instalable
Costo	Sin costo	Consumo facturable
Webhooks	Simulables bajo demanda	Eventos reales del perfil

Endpoints

GET/v1/catalogLista los planes disponibles. Filtros por país, región y vigencia.

GET/v1/catalog/{plan_code}Detalle de un plan: datos incluidos, vigencia y precio mayorista.

POST/v1/ordersCrea una orden para un plan y devuelve el perfil eSIM emitido.

GET/v1/orders/{order_id}Estado de una orden y su perfil asociado.

GET/v1/esims/{iccid}Estado del perfil, consumo de datos y fecha de expiración.

POST/v1/esims/{iccid}/topupAgrega datos adicionales a un perfil ya emitido.

Ejemplo completo

Compra de un plan de datos y entrega del perfil al viajero, en modo sandbox.

# 1. Buscar planes para Japón
GET /v1/catalog?country=JP

{
  "data": [
    { "plan_code": "JP-5GB-15D", "country": "JP",
      "data_mb": 5120, "validity_days": 15,
      "wholesale_price_mxn": 21500 }
  ]
}

# 2. Crear la orden
POST /v1/orders
{ "plan_code": "JP-5GB-15D", "customer_ref": "user_10482" }

{
  "id": "ord_9f2c7a41",
  "mode": "test",
  "status": "completed",
  "esim": {
    "iccid": "8952010000000000123",
    "activation_code": "LPA:1$rsp.interlinked.mx$K2-TEST",
    "qr_url": "https://cdn.interlinked.mx/qr/ord_9f2c7a41.png"
  }
}

# 3. Consultar consumo
GET /v1/esims/8952010000000000123

{
  "iccid": "8952010000000000123",
  "status": "active",
  "data_used_mb": 812,
  "data_total_mb": 5120,
  "expires_at": "2026-07-04T00:00:00Z"
}

Webhooks

Configuramos una URL de tu backend por modo. Cada evento se firma con HMAC-SHA256 en el encabezado X-Interlinked-Signature; verifica la firma antes de procesar el cuerpo.

esim.issuedEl perfil fue emitido y está listo para instalarse.

esim.activatedEl viajero instaló y activó el perfil en destino.

esim.data_lowEl consumo superó el umbral configurado (por defecto 80%).

esim.depletedSe agotaron los datos del plan.

esim.expiredLa vigencia del plan terminó.

Errores

Los errores devuelven un cuerpo estable con error.code y error.message.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or revoked."
  }
}

401invalid_api_keyLa llave no existe, fue revocada o está mal formada.

403mode_mismatchSe usó una llave de prueba contra un recurso de producción o viceversa.

404plan_not_foundEl plan solicitado no existe en el catálogo del cliente.

422invalid_requestFaltan campos obligatorios o el payload no es válido.

429rate_limitedSe excedió el límite de peticiones por minuto.

Emitimos tus llaves de sandbox manualmente

Cuéntanos sobre tu integración y te damos de alta en el entorno de pruebas.

Solicita acceso →