Endpoints públicos del módulo¶

Una acción para el personal y un endpoint para un servicio externo no son la misma superficie. Comparten lógica de negocio cuando conviene, pero tienen autenticación, límites y errores propios.

Cuándo exponer un endpoint¶

Úsalo para recibir datos de un proveedor, consultar información desde una aplicación autorizada o ejecutar una operación máquina a máquina. Para una interacción exclusivamente interna, una acción del módulo suele ser suficiente.

Reglas del contrato¶

versiona la ruta y el formato de respuesta;
documenta método, parámetros, respuesta y errores;
valida el cuerpo completo y limita su tamaño;
usa identificadores idempotentes para reintentos;
autentica la integración con una credencial o firma propia;
no reutilices automáticamente la sesión de un usuario del CRM;
no expongas rutas internas, consultas ni nombres de tablas.

Un módulo puede publicar una ruta propia o declarar un alias público en su contrato. El alias debe apuntar a un adaptador controlado por el módulo, no a un archivo arbitrario.

Ejemplo de respuesta¶

{
  "data": {
    "id": "reservation_123",
    "status": "confirmed"
  },
  "request_id": "req_example_123"
}

Los errores deben mantener un formato estable y explicar cómo corregir la petición, sin revelar información de infraestructura.

Webhooks entrantes¶

Cuando un proveedor envíe eventos al módulo, verifica la firma sobre el cuerpo original, comprueba la antigüedad de la petición y rechaza duplicados mediante una clave de entrega. Responde rápido y procesa en segundo plano cuando el trabajo sea largo.

Relación con la API de NexGestión¶

Si el módulo consume la API de NexGestión, usa una clave con el menor alcance posible y sigue la guía de autenticación. Si necesita notificaciones del CRM, consulta Webhooks.