Integración de API eSIM: arquitectura, flujos de trabajo, webhooks y seguridad

Una API eSIM permite a una empresa vender y gestionar conectividad dentro de su propio sitio web, aplicación móvil, proceso de reserva, portal de clientes o sistema empresarial.

Es posible que el cliente nunca vea al proveedor de conectividad de la cadena de suministro. Elige un plan, paga a la marca que conoce, recibe información de instalación y gestiona el servicio mediante una experiencia coherente.

La integración técnica que permite ese recorrido es más compleja que enviar una solicitud y recibir un código QR. Los pedidos pueden completarse de forma asíncrona. Los perfiles tienen su propio ciclo de vida. La validez del paquete puede comenzar con la compra, la instalación o el primer uso de la red. Los registros de consumo pueden llegar más tarde. Los webhooks pueden retrasarse, duplicarse o entregarse fuera de orden. Un tiempo de espera agotado no demuestra que un pedido haya fallado.

Por tanto, una integración fiable debe responder a cuatro preguntas:

1. ¿Qué sistema es responsable de cada dato?
2. ¿Qué operaciones son síncronas y cuáles asíncronas?
3. ¿Cómo se recupera la integración de la incertidumbre y los fallos?
4. ¿Cómo se autentican, autorizan, monitorizan y concilian las operaciones sensibles?

Esta guía explica una arquitectura práctica para empresas que integran un servicio white-label de SIM y eSIM. Los ejemplos son ilustrativos y no dependen de un proveedor concreto. No son una especificación de la API actual de SIM24.biz.

Puntos clave

• Una API comercial eSIM normalmente conecta los sistemas empresariales con la plataforma de un proveedor. No da a una tienda convencional acceso directo a la eUICC o al SM-DP+.
• Defina los sistemas de referencia antes del desarrollo. La plataforma comercial, el proveedor, el servicio de pagos y el CRM no deben atribuirse todos la autoridad sobre el mismo estado.
• Trate la entrega de pedidos y muchas operaciones del ciclo de vida como asíncronas, aunque normalmente se completen con rapidez.
• Utilice una referencia estable generada por el cliente de la API y una estrategia de idempotencia para evitar que un reintento cree un segundo pedido no deseado.
• Una solicitud cuyo tiempo de espera se agota tiene un resultado desconocido hasta que el cliente recupera el recurso o recibe un evento verificado.
• Los consumidores de webhooks deben verificar la autenticidad, rechazar mensajes antiguos o no válidos, guardar identificadores de eventos y procesar duplicados con seguridad.
• Un código HTTP de éxito confirma que una solicitud se aceptó o respondió correctamente. No demuestra necesariamente que se instalara un perfil o que funcionen los datos móviles.
• Separe los estados de pedido, perfil, paquete, red y pago. Reducirlos a un único indicador «activo» hace poco fiables el soporte y la conciliación.
• Utilice credenciales con privilegios mínimos, almacenamiento seguro de secretos, rotación controlada, aislamiento sólido entre clientes de la plataforma y registros de auditoría detallados.
• Un entorno de pruebas realista, las pruebas de fallos y la conciliación financiera son requisitos del lanzamiento, no mejoras opcionales.

¿Qué hace realmente una API eSIM?

El término «API eSIM» se utiliza para varias interfaces diferentes.

API comercial y de productos

Esta interfaz expone productos, precios, destinos, volúmenes incluidos, validez y reglas comerciales. Un socio la utiliza para crear un catálogo o seleccionar un producto para un pedido.

API de pedidos y entrega

Crea un pedido, reserva o asigna un perfil y devuelve información de entrega cuando está disponible.

API del ciclo de vida del perfil

Según el servicio y la arquitectura de aprovisionamiento, puede exponer asignación de perfiles, estado de descarga, información de habilitación, sustitución u otras acciones permitidas del ciclo de vida.

API de gestión de conectividad

Puede exponer el estado de la SIM, el estado del paquete, consumo, saldo, recargas, suspensión, reactivación, información de red y alertas.

API de administración de socios

Una plataforma para revendedores o clientes empresariales puede proporcionar jerarquías de cuentas, permisos, listas de precios, límites e informes.

Interfaces de aprovisionamiento remoto de SIM

Las especificaciones GSMA definen interfaces y procedimientos de seguridad utilizados por componentes como SM-DP+, Local Profile Assistant, eUICC, IoT Profile Assistant y eSIM IoT Remote Manager.

No son lo mismo que una API comercial pública. Una aplicación de viajes suele llamar a la API empresarial de su proveedor. A continuación, la plataforma del proveedor trabaja con el inventario de perfiles y la infraestructura de aprovisionamiento pertinentes mediante sistemas controlados.

Esta distinción importa. Una respuesta exitosa de la API de pedidos puede significar que se asignó un perfil y que la información de activación está disponible. No demuestra que el dispositivo del cliente haya descargado el perfil, lo haya habilitado, se haya registrado en una red o haya utilizado datos.

Una arquitectura de referencia práctica

Un servicio white-label basado en API suele contener las siguientes capas.

Por qué resulta útil un servicio de integración

Una tienda puede llamar directamente a un proveedor, pero un backend dedicado o una capa de integración suele establecer un límite más seguro.

Puede:

• mantener las credenciales del proveedor fuera de navegadores y aplicaciones móviles;
• convertir el modelo de datos del proveedor en el modelo interno de la marca;
• aplicar reglas y límites comerciales;
• adjuntar referencias de idempotencia;
• guardar identificadores de solicitudes y respuestas;
• recibir y verificar webhooks;
• poner trabajo en cola y reintentarlo con seguridad;
• proteger la experiencia del cliente frente a cambios en los proveedores de la cadena;
• admitir más de un proveedor en el futuro;
• generar una pista de auditoría para soporte y finanzas.

El servicio de integración no tiene que ser una gran plataforma independiente. Puede ser un módulo claramente separado dentro de un backend existente. Lo importante es que la lógica específica del proveedor no se extienda a todos los componentes orientados al cliente.

Defina el sistema de referencia de cada entidad

Los sistemas distribuidos dejan de ser fiables cuando la responsabilidad es ambigua.

Para cada entidad importante, defina qué sistema es la fuente autorizada y cuáles conservan copias sincronizadas.

No sobrescriba el historial con el último estado

Guarde ambos:

• el estado materializado actual que utiliza la aplicación; y
• un historial al que solo se añaden entradas de solicitudes, respuestas, eventos y acciones manuales importantes.

Si un pedido pasa de pending a fulfilled, el registro actual debe mostrar fulfilled. El historial de auditoría debe seguir mostrando cuándo se creó, qué solicitud API lo inició, cuándo lo aceptó el proveedor y qué evento confirmó la entrega.

Esta distinción es esencial al investigar cargos duplicados, entregas retrasadas o una acción de soporte disputada.

Utilice un modelo de dominio claro

Una integración eSIM no debe tratar «una eSIM» como una única fila de base de datos que contiene todos los estados.

Entre las entidades útiles habituales se incluyen:

Producto

La oferta comercial disponible para la venta, como un plan regional de 10 GB válido durante 30 días. Puede incluir cobertura de destinos, volumen incluido, reglas de validez, servicios admitidos y precio mayorista.

Pedido

La solicitud comercial de adquirir un producto. Un pedido tiene su propio estado, referencia de cliente, precio y relación con el pago.

Perfil

La suscripción móvil descargable asociada a identificadores de aprovisionamiento y a un estado de ciclo de vida. Un perfil puede vincularse a un pedido, pero no es el pedido.

Relación con la SIM o eUICC

Para SIM físicas o casos de IoT gestionado, el servicio puede modelar por separado la tarjeta, eUICC, EID, ICCID, dispositivo y activo asignado.

Paquete o derecho de servicio

El volumen incluido y la validez que puede consumir el cliente. Una recarga puede crear un nuevo derecho de servicio sin crear un perfil nuevo.

Consumo

Los registros de consumo o saldos agregados comunicados por el proveedor. El consumo debe incluir el momento de observación o tarificación, la unidad y la fuente.

Operación del ciclo de vida

Una acción solicitada, como suspender, reactivar, recargar, sustituir o cancelar. La solicitud puede estar pendiente antes de completarse o fallar.

Evento

Una notificación inmutable de que ocurrió algo, identificada de forma independiente del recurso con el que se relaciona.

Separar estos conceptos evita contradicciones como «se reembolsó la eSIM, pero sigue activa». El reembolso corresponde a un pago o pedido, mientras que el perfil y el paquete requieren sus propias acciones y estados resultantes.

El flujo de trabajo del catálogo

La primera decisión de integración es cómo llegan los productos a la tienda.

Consulta del catálogo en tiempo real

El canal del cliente o el backend solicita productos al proveedor cuando los necesita.

Ventajas:

• datos actuales del proveedor;
• menos tareas de sincronización;
• acceso rápido a nuevos productos.

Riesgos:

• la compra depende de la disponibilidad y latencia del proveedor;
• los detalles mayoristas pueden filtrarse a la lógica orientada al cliente;
• los cambios de producto pueden afectar inmediatamente a una tienda operativa;
• las llamadas repetidas pueden consumir los límites de solicitudes.

Catálogo local sincronizado

La marca importa periódicamente los productos del proveedor y publica versiones minoristas aprobadas desde su propia base de datos.

Ventajas:

• una tienda más rápida y controlada;
• títulos, traducciones, precios y presentación comercial locales;
• aprobación deliberada de los cambios del proveedor;
• resiliencia cuando el catálogo del proveedor no está disponible temporalmente.

Riesgos:

• los productos y precios pueden quedar desactualizados;
• se requieren sincronización y revisión de cambios;
• el inventario no disponible puede seguir visible.

Patrón de control recomendado

Utilice un catálogo sincronizado para la presentación, pero valide la disponibilidad crítica y las condiciones comerciales actuales antes de crear el pedido del proveedor.

Guarde:

• el identificador inmutable del producto del proveedor;
• la versión del proveedor y la local o la marca de tiempo de última actualización;
• la moneda y el coste mayoristas;
• el identificador del producto minorista;
• los destinos y redes cuando se faciliten;
• el volumen incluido, la validez y la regla de activación;
• las restricciones de servicio;
• el estado de venta y el motivo de retirada.

Nunca utilice el nombre traducido de un producto como identificador de API.

El flujo completo de compra y entrega

Un recorrido robusto del cliente puede diseñarse como una secuencia de transiciones de estado.

Paso 1: Valide el producto

Confirme que el producto seleccionado sigue disponible para la venta, que el destino y las reglas del servicio coinciden con el pedido y que el coste actual no infringe un límite de control comercial.

Paso 2: Cree un pedido local

Genere su propio identificador de pedido antes de llamar a sistemas externos. Guarde el cliente, producto, precio minorista ofertado, moneda, tratamiento fiscal y una instantánea de las condiciones importantes del producto.

El producto puede cambiar más adelante. El pedido histórico debe seguir mostrando qué compró el cliente.

Paso 3: Autorice o cobre el pago

La secuencia correcta depende del método de pago y de las reglas del proveedor.

Entre los patrones habituales se incluyen:

• autorizar el pago, crear el pedido del proveedor y después capturarlo;
• cobrar el pago, crear el pedido del proveedor y reembolsar automáticamente si falla la entrega;
• reservar inventario del proveedor, cobrar el pago y confirmar la entrega.

Cada patrón crea un caso de fallo diferente. Documente qué ocurre si el pago tiene éxito, pero se agota el tiempo de espera de la solicitud al proveedor, o si el proveedor completa un pedido después de que falle la captura del pago.

Paso 4: Envíe el pedido al proveedor

Envíe una referencia estable del socio y un valor de idempotencia cuando se admita.

Una solicitud ilustrativa podría ser así:

POST /v1/orders HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: 7f5089ca-68d4-4e0e-91c3-f44d74c21c6a

{
  "partner_order_reference": "WEB-20260914-18427",
  "product_id": "regional-eu-10gb-30d",
  "quantity": 1
}

Una respuesta ilustrativa de aceptación podría ser:

{
  "order_id": "ord_82h41",
  "partner_order_reference": "WEB-20260914-18427",
  "status": "processing",
  "created_at": "2026-09-14T13:05:28Z"
}

La solicitud y los nombres de los campos anteriores son solo ejemplos. Las integraciones reales deben seguir la documentación del proveedor elegido.

Paso 5: Determine el resultado asíncrono

El proveedor puede devolver la información de entrega inmediatamente o seguir procesando.

Su integración debe poder obtener el resultado mediante:

• un webhook;
• la consulta del recurso del pedido;
• un endpoint de estado;
• una tarea de conciliación controlada.

No mantenga abierta indefinidamente una solicitud del navegador del cliente mientras varios sistemas externos completan su trabajo.

Paso 6: Guarde de forma segura los datos de entrega

Guarde el identificador de pedido del proveedor, la referencia del perfil, los datos de activación permitidos y el estado comercial pertinente. Limite el acceso a la información de activación, porque una divulgación no controlada puede permitir que una persona no prevista instale el perfil.

Paso 7: Proporcione el recorrido de instalación

El cliente puede recibir:

• un código QR;
• una dirección SM-DP+ y un código de activación;
• un enlace de activación compatible con el sistema operativo;
• instrucciones dentro de una aplicación móvil;
• otro método de activación admitido por el proveedor.

El código QR no es el perfil eSIM. Normalmente representa información que utiliza el dispositivo para iniciar un proceso seguro de aprovisionamiento.

Paso 8: Observe los eventos posteriores del ciclo de vida

Cuando el proveedor y la cadena de aprovisionamiento los exponen, los estados posteriores pueden incluir descarga, instalación, habilitación, primer registro en la red, activación del paquete, consumo y vencimiento.

No afirme tener una visibilidad que los sistemas de la cadena no proporcionan. Algunas plataformas pueden saber que se emitió información de activación, pero no recibir inmediatamente un estado autorizado de instalación en el dispositivo.

Diseñe máquinas de estados explícitas

Un único campo de estado llamado active es demasiado impreciso para una integración de producción.

Ejemplos de estados del pedido

• created
• payment_pending
• payment_authorised
• submitted
• processing
• fulfilled
• failed
• cancelled
• refunded
• manual_review

Ejemplos de estados del perfil

• unassigned
• allocated
• activation_data_issued
• downloaded
• enabled
• disabled
• deleted
• expired
• unknown

Ejemplos de estados del paquete

• pending
• available
• active
• depleted
• expired
• cancelled

Estos son estados internos ilustrativos. El proveedor puede utilizar otra terminología y no exponer todas las transiciones.

Conserve «desconocido» como un estado real

Los sistemas distribuidos generan incertidumbre. Si se agota el tiempo de espera después de enviar una solicitud, el estado correcto no es automáticamente failed. El proveedor puede haberla recibido y completado.

Marque el resultado como desconocido o pendiente de conciliación. Consulte el recurso utilizando la referencia estable del socio o la clave de idempotencia antes de intentar crear un pedido de sustitución.

Idempotencia: evitar pedidos duplicados accidentales

Una operación es idempotente cuando repetir la misma solicitud prevista no crea un efecto comercial adicional.

HTTP define métodos como GET, PUT y DELETE como idempotentes en su semántica prevista. POST no es idempotente por defecto, pero la creación de pedidos suele utilizar POST. Por eso es importante un mecanismo de idempotencia a nivel de negocio.

Un patrón seguro para pedidos

1. Genere una clave de idempotencia única para la compra prevista.
2. Guárdela de forma persistente antes de enviar la solicitud al proveedor.
3. Envíe la misma clave cuando reintente esa misma operación prevista.
4. Nunca la reutilice para otro producto, cliente o cantidad.
5. Guarde la respuesta del proveedor asociada a la clave.
6. Consulte mediante la referencia del socio después de una respuesta incierta.

El proveedor debe definir:

• qué endpoints admiten idempotencia;
• durante cuánto tiempo se conservan las claves;
• si se comparan los cuerpos de las solicitudes;
• qué respuesta se devuelve cuando se repite una clave;
• el comportamiento cuando la primera solicitud sigue procesándose;
• el comportamiento ante un conflicto si se reutiliza la misma clave con datos diferentes.

La idempotencia no sustituye a la conciliación

Un defecto del cliente de la API o del proveedor puede seguir generando registros incoherentes. Finanzas y operaciones deben comparar periódicamente pedidos locales, pedidos del proveedor, perfiles asignados, pagos y facturas.

Tiempos de espera y estrategia de reintentos

Los reintentos deben depender de la operación y del tipo de fallo.

Condiciones que suelen permitir reintentos

• fallo temporal de red;
• restablecimiento de la conexión;
• servicio del proveedor no disponible;
• límite de solicitudes explícito con una indicación utilizable para reintentar;
• error del servidor documentado como transitorio.

Condiciones que normalmente requieren corrección o revisión

• identificador de producto no válido;
• autenticación fallida;
• permisos insuficientes;
• solicitud mal formada;
• fallo por saldo de cuenta o límite de crédito;
• estado incompatible del recurso;
• rechazo por una regla de negocio.

Utilice espera exponencial acotada con variación aleatoria

Aumentar el tiempo entre reintentos reduce la posibilidad de que muchos clientes sobrecarguen simultáneamente un servicio en recuperación. Añada variación aleatoria, o jitter, para que todos los procesos no reintenten en el mismo instante.

Establezca:

• un número máximo de intentos;
• un tiempo total máximo;
• una vía hacia una cola de mensajes fallidos o revisión manual;
• alertas de fallos sostenidos;
• políticas separadas para lecturas y operaciones que cambian estados.

Nunca reintente una solicitud incierta de creación de pedido con una referencia nueva solo porque no recibió la primera respuesta HTTP.

Webhooks: eventos entregados por el proveedor

Los webhooks permiten al proveedor notificar al socio cuando ocurre un evento asíncrono.

Los posibles eventos incluyen:

• pedido completado o fallido;
• perfil asignado;
• información de activación disponible;
• estado del perfil modificado;
• paquete activado, agotado o vencido;
• umbral de consumo alcanzado;
• SIM suspendida o reactivada;
• recarga completada;
• producto o precio modificado;
• estado de incidente o mantenimiento modificado.

Un formato representativo de evento

{
  "event_id": "evt_01J7S6A8QK",
  "event_type": "order.fulfilled",
  "occurred_at": "2026-09-14T13:05:31Z",
  "resource": {
    "type": "order",
    "id": "ord_82h41"
  },
  "data": {
    "partner_order_reference": "WEB-20260914-18427",
    "status": "fulfilled"
  }
}

Este ejemplo no es un esquema de SIM24.biz.

Autentique al emisor

Un endpoint de webhook expuesto a internet no debe confiar en una solicitud solo porque contiene un identificador de pedido plausible.

Los controles habituales incluyen:

• una firma calculada sobre el cuerpo exacto de la solicitud;
• una marca de tiempo incluida en el contenido firmado;
• una ventana de aceptación estrecha para reducir el riesgo de repetición;
• comparación de firmas en tiempo constante;
• rotación de secretos con un periodo de solapamiento controlado;
• TLS mutuo para casos de mayores garantías cuando se admita;
• controles de red como capa adicional, no como único método de autenticación.

La documentación del proveedor debe definir el algoritmo de firma canónico y la codificación. Analizar y volver a serializar el JSON antes de verificarlo puede alterar los bytes y hacer que fallen firmas válidas o que comparaciones inseguras se acepten inesperadamente. Verifique el cuerpo recibido sin modificar según el esquema documentado.

Procese los webhooks de forma asíncrona

Un consumidor fiable normalmente:

1. recibe la solicitud;
2. comprueba el tamaño y los requisitos básicos de transporte;
3. verifica la firma y la marca de tiempo;
4. guarda de forma duradera el evento y su identificador;
5. devuelve con rapidez la respuesta de éxito documentada;
6. procesa el efecto comercial mediante una cola o proceso de trabajo interno;
7. registra el éxito, el reintento o la intervención manual.

No realice trabajos lentos de entrega, correo electrónico o CRM antes de acusar recibo del webhook. Una respuesta lenta puede provocar reintentos del proveedor y aumentar los duplicados.

Prevea entregas duplicadas

La entrega al menos una vez es habitual en los sistemas de eventos. Un proveedor reintenta porque no puede saber si el consumidor guardó un evento antes de que fallara una conexión.

Guarde event_id con una restricción de unicidad. Volver a procesar el mismo evento no debe emitir un segundo reembolso, enviar varios correos de entrega ni aplicar la misma recarga dos veces.

Prevea eventos fuera de orden

Un evento retrasado order.processing puede llegar después de order.fulfilled.

Utilice:

• números de versión del recurso cuando se proporcionen;
• números de secuencia del proveedor;
• la hora de ocurrencia del evento con cautela;
• reglas de transiciones de estado permitidas;
• consulta del recurso actual cuando un evento entre en conflicto con el estado local.

No sustituya ciegamente el estado actual por el del último webhook recibido.

Trate un webhook como una notificación, no siempre como toda la verdad

Para acciones sensibles, utilice el evento para activar una consulta del recurso actual del proveedor. Esto reduce los datos transportados en los eventos y permite confirmar el estado actual mediante una llamada API autenticada.

El sondeo y la conciliación siguen siendo necesarios

Los webhooks mejoran la capacidad de respuesta, pero no deben ser el único mecanismo de sincronización.

Los eventos pueden perderse por:

• errores de configuración;
• secretos o certificados caducados;
• interrupciones temporales del receptor;
• defectos de entrega del proveedor;
• límites de conservación de eventos;
• un despliegue que rechace cuerpos de mensaje válidos.

Un proceso de conciliación puede comparar periódicamente:

• pedidos locales pendientes con el estado de pedido del proveedor;
• referencias locales de perfiles con el inventario asignado;
• solicitudes de recarga con los derechos de servicio completados;
• saldos de paquetes con registros de consumo;
• reembolsos con cancelaciones del proveedor;
• totales internos mensuales con la factura del proveedor.

La frecuencia de conciliación debe reflejar el riesgo comercial. Un pedido pagado sin entregar puede necesitar atención en minutos, mientras que la conciliación de consumo a nivel de factura puede ejecutarse diaria o mensualmente.

Autenticación y autorización

La seguridad de la API empieza por identificar la carga de trabajo que realiza la llamada y limitar lo que puede hacer.

Mantenga las credenciales en servidores de confianza

Nunca incorpore un secreto del proveedor en:

• JavaScript del navegador;
• una aplicación móvil pública;
• un archivo de configuración descargable;
• código fuente incorporado a un repositorio;
• capturas de pantalla de soporte o registros.

Los canales del cliente deben llamar al backend de la marca, que después llama al proveedor mediante credenciales del servidor.

Prefiera credenciales de corta duración cuando estén disponibles

OAuth 2.0 con credenciales de cliente u otro mecanismo adecuado de identidad de cargas de trabajo puede emitir tokens de acceso de duración limitada. RFC 9700 proporciona las buenas prácticas actuales de seguridad de OAuth 2.0 y desaconseja patrones históricos inseguros.

Si el proveedor utiliza claves API estáticas, compénselo con:

• almacenamiento en un gestor de secretos;
• separación estricta de entornos;
• permisos de mínimo privilegio;
• rotación periódica;
• monitorización de usos inusuales;
• procedimientos de revocación inmediata;
• prohibición de compartir una clave entre aplicaciones o socios no relacionados.

La autenticación no es autorización

Una credencial válida no debe conceder automáticamente acceso a todos los clientes de la plataforma, perfiles u operaciones.

Los controles deben aplicar:

• límites entre socios y clientes de la plataforma;
• titularidad de los recursos;
• catálogo de productos permitido;
• acciones autorizadas del ciclo de vida;
• límites de gasto o volumen;
• rol de administrador;
• acceso a producción frente al entorno de pruebas.

OWASP API Security Top 10 2023 destaca entre los principales riesgos de API los fallos de autorización a nivel de objeto, autenticación, autorización a nivel de función y acceso sin restricciones a flujos de negocio sensibles.

Proteja más las operaciones administrativas

Operaciones como crear credenciales, suspender masivamente, cambiar precios, aprobar reembolsos y exportar datos pueden necesitar:

• autenticación multifactor;
• aprobación de una segunda persona;
• autenticación adicional reforzada;
• redes de origen restringidas;
• registros de auditoría detallados;
• notificación a los equipos de seguridad o finanzas.

Seguridad de solicitudes, respuestas y datos

Seguridad del transporte

Utilice configuraciones TLS actuales y valide correctamente los certificados. No desactive la verificación para resolver un problema del entorno de pruebas.

Validación de entradas

Valide el tipo, longitud, formato, valores permitidos y significado comercial. Un documento JSON válido aún puede solicitar una cantidad imposible, un producto no autorizado o un intervalo de exportación inseguro.

Minimización de salidas

Devuelva solo los campos que necesita quien llama. Evite exponer secretos de proveedores de la cadena, identificadores internos de red, información personal o datos de activación completos a roles no autorizados.

Registros sin filtraciones

Los registros deben contener información suficiente para el diagnóstico, incluidos:

• identificador de correlación;
• referencia del pedido del socio;
• identificador de solicitud del proveedor;
• endpoint y categoría del resultado;
• tiempos y número de reintentos;
• identificadores de recursos pertinentes;
• identidad del actor o de la carga de trabajo.

Oculte o excluya:

• tokens de acceso y claves API;
• secretos y firmas de webhooks;
• datos de tarjetas de pago;
• material de autenticación;
• datos personales innecesarios;
• códigos de activación completos cuando no sean necesarios para soporte.

Protección de datos

Determine qué datos personales necesita el proveedor y por qué. Para servicios sujetos al RGPD, defina los roles de responsable y encargado por actividad, acuerde las condiciones de tratamiento necesarias, enumere los subencargados, controle las transferencias internacionales y establezca procedimientos de conservación y eliminación.

Una integración API debe favorecer la minimización de datos. Si el proveedor puede completar un pedido eSIM mediante una referencia de pedido del socio, quizá no necesite el perfil de marketing completo del cliente ni datos de reserva ajenos al servicio.

Proteja los flujos de negocio sensibles

Muchos ataques contra API no aprovechan un paquete mal formado. Automatizan una función válida a escala abusiva.

Por ejemplo:

• crear grandes cantidades de perfiles con métodos de pago robados;
• solicitar repetidamente información de activación de sustitución;
• enumerar identificadores de pedidos o perfiles;
• abusar de productos promocionales;
• activar recargas costosas;
• exportar cantidades excesivas de datos de clientes;
• agotar inventario o límites de solicitudes del proveedor.

Los controles pueden incluir:

• límites de solicitudes por cliente de la plataforma y por operación;
• umbrales de gasto y volumen;
• comprobaciones de riesgo de pagos y cuentas;
• validación de estados previstos;
• aprobación de operaciones masivas de alto riesgo;
• monitorización de anomalías;
• mecanismos de corte de llamadas ante fallos;
• controles de protección del inventario;
• revisión manual de patrones excepcionales.

Un límite técnico de solicitudes, por sí solo, no es una estrategia antifraude. Diez solicitudes permitidas pueden seguir siendo perjudiciales si cada una compra un producto caro.

Versionado de API y gestión de cambios

Los servicios de conectividad evolucionan. Cambian los productos, redes, relaciones con proveedores e interfaces de software.

El proveedor debe documentar:

• enfoque de versionado;
• política de compatibilidad con versiones anteriores;
• plazo de retirada de versiones;
• notas de versiones;
• definición de cambio incompatible;
• disponibilidad en el entorno de pruebas antes del cambio en producción;
• método de anuncio de cambios urgentes;
• compatibilidad con versiones coexistentes;
• tratamiento de nuevos valores de enumeraciones y campos opcionales.

Construya lectores tolerantes, no descuidados

Un consumidor normalmente debe tolerar un campo opcional nuevo. No debe aceptar silenciosamente un valor desconocido que cambie el significado financiero o del ciclo de vida.

Por ejemplo, un nuevo estado de pedido debe llevar el registro a un estado explícito desconocido o de revisión, en lugar de tratarse como entregado.

Utilice documentación legible por máquinas

OpenAPI Specification proporciona un formato estándar para describir API HTTP. Una especificación mantenida puede facilitar la generación de clientes, validación, herramientas de prueba y documentación.

La documentación legible por máquinas no es automáticamente correcta. Compárela con el comportamiento real del entorno de pruebas y con las notas de versiones.

Observabilidad y monitorización operativa

Una integración no está completa hasta que los operadores pueden ver si funciona.

Métricas técnicas

• número de solicitudes por endpoint y resultado;
• percentiles de latencia;
• tasa de tiempos de espera agotados y errores de conexión;
• fallos de autenticación;
• respuestas de límite de solicitudes;
• volumen de reintentos;
• fallos de firma de webhooks;
• retraso de procesamiento de webhooks;
• tamaño de la cola y mensaje más antiguo;
• número de mensajes en la cola de fallidos.

Métricas de negocio

• pedidos pagados pendientes de entrega;
• éxito y tiempo de entrega;
• perfiles asignados pero no entregados;
• estado de instalación o activación cuando esté disponible;
• tiempo de finalización de recargas;
• tasa de reembolsos y sustituciones;
• diferencias de conciliación entre pedidos y proveedor;
• desviaciones de consumo y facturación;
• margen por producto;
• contactos de soporte por pedido.

Identificadores de correlación

Vincule los registros de cliente, pago, pedido local, pedido del proveedor, perfil y evento mediante identificadores estables. Propague un identificador de correlación por los servicios internos y conserve el identificador de solicitud o traza del proveedor cuando se facilite.

Un agente de soporte debe poder empezar por el número de pedido del cliente y llegar a las pruebas técnicas pertinentes sin buscar manualmente en varios sistemas inconexos.

Las alertas deben indicar una acción

«Han aumentado los errores de la API» resulta menos útil que:

«La creación de pedidos del proveedor ha superado el umbral de fallos acordado durante diez minutos; 28 pedidos pagados siguen pendientes; los reintentos automáticos están pausados; el responsable del incidente es Operaciones de Integración».

Cada alerta debe identificar gravedad, flujo afectado, impacto en clientes, equipo responsable y acción inmediata.

Gestión de interrupciones del proveedor

La experiencia del cliente debe fallar de forma segura cuando el servicio del proveedor no esté disponible.

Los posibles controles incluyen:

• corte de llamadas tras fallos repetidos;
• entrega en cola con un mensaje claro para el cliente;
• retirada temporal de los productos afectados;
• prevención de nuevas capturas de pago cuando no se pueda completar la entrega con seguridad;
• página de estado y notificación a soporte;
• conciliación cuando se restablezca el servicio;
• entrega manual controlada para casos aprobados;
• conmutación a otro proveedor solo cuando los productos y reglas comerciales sean realmente compatibles.

No cambie automáticamente a un producto alternativo con cobertura, reglas de activación o restricciones diferentes sin controles comerciales y relativos al cliente.

Decida de antemano el comportamiento del pago

Para cada punto de fallo, especifique si el sistema:

• mantendrá abierta la autorización;
• capturará el pago más tarde;
• anulará la autorización;
• emitirá un reembolso automático;
• retendrá el pedido para revisión manual;
• ofrecerá una elección al cliente.

Esta decisión corresponde a producto, finanzas y operaciones de atención al cliente, no solo al desarrollador de la API.

Requisitos del entorno de pruebas

Un entorno de pruebas útil debe admitir más que una única respuesta de éxito.

Pregunte si puede simular:

• procesamiento y entrega retrasada;
• fallo permanente;
• error transitorio del servidor;
• tiempo de espera agotado de una solicitud;
• limitación de solicitudes;
• clave de idempotencia duplicada;
• webhook duplicado;
• webhook fuera de orden;
• firma de webhook no válida;
• perfil no disponible;
• activación y vencimiento de paquetes;
• umbrales de consumo;
• éxito y fallo de recargas;
• suspensión y reactivación;
• exportación de facturas o consumo.

El proveedor debe explicar las diferencias entre pruebas y producción, incluidos catálogo de productos, autenticación, límites de solicitudes, conservación de datos y entrega de webhooks.

Estrategia de pruebas

Pruebas de contrato de interfaz

Valide que las solicitudes y respuestas coincidan con el esquema, campos obligatorios, tipos y valores permitidos acordados.

Pruebas de transiciones de estado

Pruebe transiciones permitidas y rechazadas. Un pedido cancelado no debe volver a procesamiento sin un flujo de recuperación definido.

Pruebas de idempotencia

Repita la misma solicitud de pedido antes y después de completarse. Verifique que solo ocurra un efecto comercial.

Pruebas de inyección de fallos

Genere tiempos de espera agotados, eventos retrasados, dependencias no disponibles y fallos internos parciales. Confirme que el sistema alcanza un estado recuperable.

Pruebas de seguridad

Pruebe el aislamiento entre clientes de la plataforma, la autorización a nivel de objeto, revocación de credenciales, firmas de webhooks, gestión de repeticiones, límites de entrada y exposición de datos sensibles.

Pruebas de carga y ráfagas

Utilice volúmenes acordados con el proveedor. Pruebe tanto el caudal normal como las ráfagas generadas por campañas, alteraciones de viajes u operaciones masivas de IoT.

Pruebas de extremo a extremo en dispositivos

Para productos y dispositivos representativos, pruebe todo el recorrido:

1. consultar el producto;
2. crear y pagar el pedido;
3. recibir la información del perfil;
4. descargar e instalar la eSIM;
5. habilitarla;
6. registrarse en una red permitida;
7. utilizar el servicio previsto;
8. observar el consumo o saldo;
9. aplicar una recarga u operación del ciclo de vida permitida;
10. conciliar la transacción.

Una prueba de API que se detiene en una respuesta 200 OK no ha probado la conectividad móvil.

Conciliación financiera

El éxito técnico y la corrección comercial son cosas diferentes.

Cree controles diarios o periódicos que comparen:

• pagos capturados;
• pedidos locales;
• pedidos del proveedor;
• perfiles o SIM asignados;
• paquetes entregados;
• cancelaciones y reembolsos;
• cargos por consumo;
• facturas mayoristas;
• comisiones de revendedores;
• impuestos y monedas.

Ejemplos de excepciones

• pago capturado sin pedido del proveedor;
• pedido del proveedor completado con pago fallido;
• dos pedidos del proveedor vinculados a un pedido local;
• reembolso emitido con un paquete que permanece activo inesperadamente;
• recarga cobrada dos veces;
• consumo que supera la regla comercial prevista;
• precio mayorista diferente de la instantánea importada del catálogo;
• factura con un perfil o una referencia de socio desconocidos.

Cada excepción debe entrar en una cola controlada con un responsable, un valor financiero y un historial de resolución.

Documentación que necesita su equipo

Una integración en producción necesita más que páginas de referencia de endpoints.

Solicite y mantenga:

• guía de autenticación;
• proceso de entornos y credenciales;
• definición de interfaz OpenAPI o equivalente;
• modelo de datos y descripciones de estados;
• catálogo de errores;
• reglas de idempotencia;
• límites de solicitudes;
• política de seguridad y reintentos de webhooks;
• proceso de cambios de productos y precios;
• política de versiones y retirada;
• contactos de soporte y escalado;
• proceso de incidentes y mantenimiento;
• guía de conciliación y facturación;
• información de protección y conservación de datos;
• información de continuidad del negocio.

La documentación interna debe añadir:

• registro de decisiones de arquitectura;
• matriz de sistemas de referencia;
• diagramas de secuencia y estados;
• procedimiento de rotación de secretos;
• paneles operativos y alertas;
• procedimientos de respuesta a incidentes;
• controles de entrega manual y reembolsos;
• proceso de lanzamiento y reversión.

Una lista práctica de comprobación del lanzamiento

Arquitectura y datos

• □Cada entidad principal tiene un sistema de referencia definido.
• □Los identificadores del proveedor se guardan separados de los locales.
• □Las transiciones de estado y los resultados desconocidos se modelan explícitamente.
• □Los campos sensibles y las reglas de conservación están documentados.

Pedidos y pagos

• □La creación de pedidos tiene una estrategia de idempotencia.
• □Se han probado escenarios de tiempos de espera agotados y duplicados.
• □El comportamiento de captura, anulación y reembolso del pago está definido para cada punto de fallo.
• □La conciliación detecta desajustes entre pagos y pedidos del proveedor.

Webhooks y procesamiento asíncrono

• □Las firmas y marcas de tiempo se verifican correctamente.
• □Los eventos duplicados y fuera de orden son seguros.
• □Los eventos se guardan antes de emitir el acuse de recibo.
• □Los fallos de procesamiento llegan a una cola visible de reintentos o revisión manual.
• □El sondeo o la conciliación cubren los eventos perdidos.

Seguridad

• □No hay secretos del proveedor en navegadores ni aplicaciones móviles.
• □Las credenciales de producción y pruebas están separadas.
• □Las credenciales tienen privilegios mínimos y un procedimiento de rotación probado.
• □Se ha probado la autorización entre clientes de la plataforma y a nivel de objeto.
• □Los registros excluyen secretos, datos de pago e información personal innecesaria.
• □Las acciones administrativas y masivas se auditan.

Operaciones

• □Los paneles técnicos y de negocio están operativos.
• □Las alertas identifican un responsable y una acción.
• □Soporte puede rastrear un pedido de cliente hasta las referencias del proveedor y del perfil.
• □Se han ensayado el escalado al proveedor y los procedimientos ante interrupciones.
• □Los productos pueden retirarse con rapidez.

Preparación comercial

• □Los cambios de precios del catálogo están controlados.
• □El consumo y las facturas pueden conciliarse.
• □Las condiciones vigentes coinciden con el comportamiento de activación, validez, reembolso y sustitución.
• □Se han superado pruebas representativas de dispositivos y redes.
• □Se ha designado un responsable de decidir una reversión o pausa del lanzamiento.

Errores habituales de integración

Llamar directamente al proveedor desde la aplicación móvil

Esto expone credenciales o fuerza compromisos inseguros de autenticación. Utilice un backend controlado.

Tratar un tiempo de espera agotado como un pedido fallido

El pedido puede haberse completado. Consúltelo o concílielo antes de crear otro.

Utilizar correos electrónicos o nombres de productos como identificadores

Los nombres cambian y los datos del cliente no deben convertirse en una clave técnica. Utilice identificadores inmutables.

Suponer que los webhooks llegan una vez y en orden

Diseñe para reintentos, duplicados, retrasos y reordenación.

Enviar la entrega dos veces

Los eventos duplicados o reintentos pueden provocar múltiples correos y confusión. Haga idempotente cada efecto secundario.

Exponer el código QR demasiado ampliamente

La información de activación debe estar disponible solo para clientes y roles de soporte autorizados.

Registrar todos los cuerpos de mensajes sin ocultar datos sensibles

Esto puede copiar credenciales, datos personales e información de activación en varios sistemas de registros.

Mezclar estados de pedido y conectividad

Un pedido completado puede contener un perfil no instalado. Un perfil habilitado puede tener un paquete vencido. Mantenga separados los ciclos de vida.

Ignorar las finanzas hasta final de mes

Es más fácil investigar excepciones diarias que miles de diferencias sin explicación en una factura.

Construir solo el recorrido exitoso

La mayor parte de la complejidad de integración está en las operaciones inciertas, retrasadas y parcialmente completadas.

Cómo encaja SIM24.biz en un servicio basado en API

SIM24.biz apoya a empresas que desarrollan propuestas de conectividad SIM, eSIM e IoT con marca propia. Un modelo basado en API puede permitir al socio conservar su sitio web, aplicación, pagos, CRM, analítica y relación con el cliente existentes mientras integra las funciones de conectividad necesarias.

El límite correcto de integración depende del proyecto. Un socio puede utilizar un recorrido completo white-label. Otro puede utilizar API para catálogo, entrega y ciclo de vida mientras controla toda la interfaz del cliente. Un tercero puede combinar inventario de SIM físicas y eSIM con operaciones empresariales o de IoT.

Los endpoints, métodos de autenticación, webhooks, visibilidad del ciclo de vida, límites, funciones del entorno de pruebas y niveles de servicio disponibles en SIM24.biz deben confirmarse para la implementación y combinación de proveedores seleccionadas. Los esquemas y nombres de endpoints de este artículo son ilustrativos y no deben presentarse como documentación actual de la API de SIM24.biz.

Una fase responsable de análisis técnico debe definir:

• el recorrido objetivo del cliente;
• los sistemas de referencia;
• los productos y mercados necesarios;
• los flujos de integración y eventos;
• el modelo de pagos y conciliación;
• las responsabilidades de seguridad y datos;
• los escenarios del piloto;
• la responsabilidad operativa después del lanzamiento.

Conclusión

Una integración de API eSIM tiene éxito cuando los clientes reciben conectividad fiable y la empresa puede explicar cada pedido, perfil, pago y excepción.

La llamada API es solo una parte de ese resultado. El diseño completo debe gestionar la entrega asíncrona, estados independientes del ciclo de vida, operaciones idempotentes, webhooks verificados, respuestas inciertas, credenciales seguras, monitorización operativa y conciliación financiera.

La mejor arquitectura establece límites claros. La marca controla su cliente y su lógica comercial. La capa de integración controla las dependencias externas. El proveedor aporta capacidades definidas de plataforma, aprovisionamiento y conectividad. Cada parte puede identificar qué estado conoce y de qué acción es responsable.

Construya los recorridos de fallo antes del lanzamiento, no después de que el primer cliente que ha pagado esté esperando su perfil.

Preguntas frecuentes

¿Qué es una API eSIM?

Una API eSIM es una interfaz empresarial mediante la cual un socio autorizado puede acceder a funciones como consulta de productos, pedidos, entrega de perfiles, estado, consumo, recargas o gestión del ciclo de vida. Su alcance exacto depende del proveedor.

¿Una API eSIM se conecta directamente a la eUICC?

Normalmente, una API empresarial minorista o white-label se conecta a la plataforma del proveedor. La entrega segura del perfil a la eUICC utiliza la arquitectura y los componentes de aprovisionamiento pertinentes, como SM-DP+ y Local Profile Assistant en el modelo de consumo.

¿Por qué son asíncronos los pedidos eSIM?

El proveedor puede necesitar asignar inventario, completar trabajos de aprovisionamiento o coordinar otros sistemas. Devolver un recurso pendiente permite terminar la solicitud del cliente sin esperar indefinidamente.

¿Qué es una clave de idempotencia?

Es un valor único que representa una operación prevista que cambia un estado. Cuando debe reintentarse la misma solicitud, reutilizar la clave ayuda a evitar un efecto comercial duplicado no deseado si el proveedor admite ese comportamiento.

¿Debo reintentar un pedido eSIM cuyo tiempo de espera se ha agotado?

Primero trate el resultado como desconocido. Consulte el pedido utilizando la referencia del socio o el mecanismo de idempotencia del proveedor. Reintente solo conforme a las reglas documentadas y utilice el mismo identificador para la misma operación prevista.

¿Cómo debe protegerse un webhook eSIM?

Verifique la firma del proveedor sobre la solicitud sin modificar según su esquema documentado, compruebe una marca de tiempo firmada o un control contra repeticiones, limite el tamaño del cuerpo, guarde el identificador del evento y procese el evento de forma idempotente. TLS mutuo puede ser adecuado para algunas integraciones que requieren mayores garantías.

¿Está garantizado que los webhooks lleguen una sola vez?

No diseñe basándose en ese supuesto. Los consumidores deben tolerar eventos duplicados, retrasados y fuera de orden, y utilizar conciliación para detectar cambios perdidos.

¿Debe guardarse el código QR?

Guarde solo lo necesario para el recorrido admitido del cliente y de recuperación, protéjalo como información sensible de entrega y restrinja el acceso. Confirme con el proveedor las reglas de conservación y nueva visualización.

¿Qué debe incluir un entorno de pruebas de API eSIM?

Debe admitir escenarios representativos de éxito y fallo, incluidos finalización asíncrona, solicitudes duplicadas, reintentos de webhooks, firmas no válidas, límites de solicitudes, cambios de ciclo de vida y datos de conciliación.

¿Cómo deben guardarse las credenciales API?

Consérvelas en un sistema de gestión de secretos del servidor, separe entornos y privilegios, rótelas mediante un procedimiento probado y nunca las coloque en código del navegador o de aplicaciones móviles.

¿Cómo podemos cambiar de proveedor eSIM más adelante?

Mantenga la lógica específica del proveedor detrás de un límite de integración, utilice identificadores internos y modelos de dominio, conserve exportaciones completas de datos y negocie derechos de transición. Los perfiles activos aún pueden necesitar una migración técnica o sustitución, en lugar de un simple cambio de base de datos.

¿Es mejor una integración API que una plataforma white-label completa?

Ofrece más control sobre la experiencia del cliente y los sistemas, pero requiere desarrollo y responsabilidad operativa permanente. Una plataforma white-label completa puede facilitar un lanzamiento más rápido. El modelo adecuado depende de la diferenciación, los recursos y la escala.

Conecte servicios eSIM y SIM a los sistemas que ya controla

SIM24.biz ayuda a los socios a definir recorridos de conectividad con marca propia, límites de integración y requisitos del piloto en torno a sus plataformas comerciales y de clientes existentes.

Hable con SIM24.biz sobre el modelo API o white-label adecuado para su servicio.

Fuentes

1. GSMA, «SGP.22 v2.7, eSIM Consumer Technical Specification»: https://www.gsma.com/solutions-and-impact/technologies/esim/gsma_resources/sgp-22-v2-7/
2. GSMA, «SGP.31 v1.3, eSIM IoT Architecture and Requirements»: https://www.gsma.com/solutions-and-impact/technologies/esim/gsma_resources/sgp-31-v1-3/
3. GSMA, «SGP.32 v1.3, eSIM IoT Technical Specification»: https://www.gsma.com/solutions-and-impact/technologies/esim/gsma_resources/sgp-32-v1-3/
4. IETF, «RFC 9110, HTTP Semantics»: https://www.rfc-editor.org/rfc/rfc9110.html
5. IETF, «RFC 9700, Best Current Practice for OAuth 2.0 Security»: https://www.rfc-editor.org/rfc/rfc9700.html
6. IETF, «RFC 8725, JSON Web Token Best Current Practices»: https://www.rfc-editor.org/rfc/rfc8725.html
7. OpenAPI Initiative, «OpenAPI Specification v3.1.1»: https://spec.openapis.org/oas/v3.1.1.html
8. Cloud Native Computing Foundation, «CloudEvents Specification»: https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md
9. OWASP Foundation, «OWASP API Security Top 10, 2023»: https://owasp.org/API-Security/editions/2023/en/0x11-t10/
10. Unión Europea, «Reglamento (UE) 2016/679, Reglamento General de Protección de Datos»: https://eur-lex.europa.eu/eli/reg/2016/679/oj/eng
11. Comité Europeo de Protección de Datos, «Directrices 07/2020 sobre los conceptos de responsable y encargado del tratamiento en el RGPD»: https://www.edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-072020-concepts-controller-and-processor-gdpr_en