apimarket apimarket
Api Market

IMSS

Creación de una cuenta y certificados en IDSE PRO

Guía Técnica: Creación de Cuenta y Gestión de Certificados en IDSE Pro

Introducción

IDSE Pro ofrece una API RESTful y una Interfaz de Usuario (UI) para automatizar y gestionar trámites ante el IMSS (Instituto Mexicano del Seguro Social) a través de su plataforma IDSE (IMSS Desde Su Empresa). Esta automatización es crucial para desarrolladores que buscan integrar la funcionalidad de IDSE en sus propios sistemas, reduciendo la carga operativa manual y minimizando errores.

Para interactuar con la API o la UI, es indispensable crear una cuenta en IDSE Pro. Este proceso vincula un Certificado Digital vigente (emitido por el SAT - e.firma/FIEL - o por el IMSS) a tu cuenta, el cual actúa como la credencial principal para la autenticación y autorización de todas las operaciones, garantizando la seguridad e identidad en las interacciones con la plataforma.

Esta guía proporciona los detalles técnicos necesarios para desarrolladores sobre la creación de cuentas, el registro de certificados y las diferencias clave entre los entornos Sandbox y Producción.

Tabla de Contenido

  1. Introducción
  2. Entornos Disponibles: Producción y Sandbox
  3. Proceso de Creación de Cuenta
  4. Gestión de Certificados Digitales
  5. Periodo de Prueba para Integradores (Solo Producción)
  6. Conclusión

Entornos Disponibles: Producción y Sandbox

IDSE Pro ofrece dos entornos distintos para facilitar el desarrollo y la operación segura:

  • Sandbox: Un entorno aislado diseñado exclusivamente para pruebas y desarrollo. Permite a los desarrolladores integrar y validar sus aplicaciones sin interactuar con los sistemas reales del IMSS ni afectar datos de producción.
  • Producción: El entorno en vivo donde se realizan las operaciones reales ante el IMSS. Todas las acciones en este entorno tienen efectos reales.

Proceso de Creación de Cuenta

La creación de una cuenta asocia un certificado digital válido (real para Producción, de prueba para Sandbox) con un usuario en IDSE Pro, habilitando el acceso y la gestión (real o simulada) de trámites del IMSS.

Métodos de Registro

Existen dos métodos para registrar una cuenta y su certificado asociado en ambos entornos:

  1. Interfaz de Usuario (UI): A través del portal web idse.apimarket.mx.
  2. API RESTful: Utilizando el endpoint documentado en Postman y genera los token que necesites en idse.apimarket.mx/tokens.

Fases del Registro

El proceso técnico es idéntico en ambos entornos, variando solo las credenciales usadas y las validaciones subyacentes:

  1. Recepción de Credenciales: Se reciben el certificado (real o prueba), clave privada (si aplica), contraseña (passphrase) y el identificador de usuario (RFC o usuario IMSS).
  2. Validación Criptográfica: Se realizan validaciones (ver Validaciones Técnicas).
  3. Almacenamiento Seguro: Las credenciales se almacenan de forma segura. La clave privada y contraseña no son visibles post-registro.
  4. Asignación de Privilegios: El certificado se asocia con privilegios de administrador.
  5. Sincronización Inicial: (Producción) Se puede iniciar la sincronización de Registros Patronales reales. (Sandbox) Puede simularse la sincronización con datos de prueba.
  6. Habilitación de Acceso: La cuenta queda activa en el entorno correspondiente.
  7. Activación del Periodo de Prueba (Solo Producción): Se inicia el periodo de prueba al registrar el primer certificado real en Producción.

Gestión de Certificados Digitales

Tipos de Certificados Soportados

IDSE Pro admite certificados SAT (e.firma / FIEL) y certificados IMSS en ambos entornos. La estructura requerida es la misma:

  1. Certificado del SAT (e.firma / FIEL):
    • Requiere .cer, .key (ambos Base64) y password (passphrase).
    • El user es el RFC.
  2. Certificado del IMSS:
    • Generalmente un archivo .pfx (Base64).
    • Puede requerir o no password. Si no la requiere, private_key y password pueden omitirse en la API.
    • El user es el usuario IDSE registrado ante el IMSS.

Estructura de la Petición API (Producción y Sandbox)

La estructura del cuerpo de la petición POST /certificates es la misma para ambos entornos. Solo cambia la URL base del endpoint.

{
  "certificate": "BASE64_DEL_CERTIFICADO_CER_O_PFX", // Certificado real (Prod) o de prueba (Sandbox)
  "private_key": "BASE64_DE_LA_CLAVE_PRIVADA_KEY_O_NULO_SI_PFX_SIN_KEY",
  "password": "PASSPHRASE_DE_LA_CLAVE_PRIVADA_O_NULO_SI_NO_APLICA",
  "user": "RFC_O_USUARIO_IMSS" // Asociado al certificado real (Prod) o de prueba (Sandbox)
}

Importante: Asegúrate de enviar la petición a la URL correcta (sandbox.idse... o idse...) según el entorno deseado.

Respuesta de la API y Atributos Clave

La estructura de la respuesta JSON del endpoint /certificates es idéntica en ambos entornos. Los valores reflejarán los datos del certificado registrado (real o de prueba) y el estado de la cuenta en ese entorno específico.

{
    "id": "...", // UUID único del certificado EN ESTE ENTORNO
    "name": "...", // Nombre del certificado (real o prueba)
    "custom_name": "...",
    "rfc": "...", // RFC (si aplica, real o prueba)
    "legal_name": "...", // Nombre legal (real o prueba)
    "user": "...", // Usuario asociado (real o prueba)
    "valid_from": "...",
    "valid_until": "...",
    "issuer": "...", // Emisor (real o prueba)
    "serial": "...",
    "mime": "...",
    "version": ...,
    "created_at": "...",
    "updated_at": "...",
    // Atributos específicos de Producción (pueden ser null/default en Sandbox)
    "subscription_expired_at": "...",
    "subscription_renewed_at": "...",
    "max_movements": ...,
    "can_sync_history": ...,
    "deactivated_at": null,
    "deleted_at": null
}

Los atributos id, valid_until, rfc, user, etc., son útiles en ambos entornos para identificar y gestionar los certificados. Atributos como subscription_expired_at o max_movements son principalmente relevantes en Producción.

Periodo de Prueba para Integradores (Solo Producción)

El periodo de prueba se aplica únicamente al entorno de Producción al registrar el primer certificado real.

  • Incluye:
    • 10 movimientos afiliatorios gratuitos.
    • 1 mes de suscripción sin costo.
  • Restricciones:
    • Limitado a 1 cuenta de IDSE.
    • Requiere la firma de un contrato.

El entorno Sandbox no tiene estas limitaciones y está diseñado para pruebas extensivas durante el desarrollo.

Conclusión

Esta guía ha detallado los procesos técnicos para la creación de cuentas y registro de certificados en los entornos Sandbox y Producción de IDSE Pro, enfocándose en las necesidades de los desarrolladores.

Pasos Clave para Desarrolladores:

  1. Utiliza el Sandbox: Realiza todas tus pruebas de integración y desarrollo en el entorno Sandbox usando credenciales de prueba y el endpoint API de Sandbox.
  2. Verifica la Diferencia en Validaciones: Ten en cuenta que la validación OCSP real solo ocurre en Producción. Un certificado válido en Sandbox podría ser rechazado en Producción si está revocado.
  3. Configura tus Entornos: Asegúrate de que tu aplicación pueda cambiar fácilmente entre las URLs base de API de Sandbox y Producción.
  4. Prueba con Certificados Reales (en Producción): Una vez validada tu integración en Sandbox, realiza pruebas finales en Producción (idealmente con una cuenta de prueba o un volumen bajo) antes del despliegue completo, activando así tu periodo de prueba.

Al seguir estos pasos y comprender las diferencias entre entornos, podrás integrar exitosamente tus sistemas con IDSE Pro para automatizar trámites del IMSS de forma segura y eficiente.