Integración
Autenticación
La API trabaja con sesiones: se abre una con las credenciales, se recibe un testigo (token) y todas las llamadas siguientes viajan con él. La contraseña solo viaja en la primera llamada.
La dirección base#
Todas las rutas de esta documentación cuelgan de una dirección base que te entrega Esofitec al activar la opción. Tiene esta forma:
BASE = https://{servidor}/…/{solución}
y en los ejemplos aparece siempre como BASE. Las rutas que se muestran a partir
de ahí —/sessions, /layouts/{recurso}/records…— son literales: se añaden tal
cual a esa dirección.
Siempre HTTPS
La API no debe usarse sobre HTTP. La primera llamada lleva la contraseña, y las demás un testigo que vale tanto como ella mientras no caduque.
Abrir sesión#
POST {BASE}/sessions
Authorization: Basic {usuario:contraseña en base64}
Content-Type: application/json
{}
Respuesta:
{
"response": { "token": "9a1f…" },
"messages": [ { "code": "0", "message": "OK" } ]
}
Ese token es el que se usa a partir de ahí.
La cabecera Basic se codifica en UTF-8
Si la contraseña tiene acentos, eñes o cualquier carácter no ASCII, hay
bibliotecas que construyen esa cabecera en latin-1 y el servidor la rechaza
con un error de credenciales, aunque la contraseña sea correcta. Es un fallo
difícil de diagnosticar porque parece un problema de permisos. Construye la
cabecera a mano codificando usuario:contraseña en UTF-8 antes de pasarlo a
base64.
Usar el testigo#
En todas las llamadas siguientes:
Authorization: Bearer {token}
Cerrar sesión#
DELETE {BASE}/sessions/{token}
Cierra siempre, aunque falle el proceso
Las sesiones abiertas cuentan para el límite de conexiones de tu solución. Cierra
en el bloque finally de tu código, no solo cuando todo va bien: un proceso que
revienta a mitad y deja la sesión abierta es la causa más común de que, horas
después, nadie pueda conectarse.
Cuánto dura#
El testigo caduca por inactividad. Una integración que corre cada noche debe abrir sesión al empezar y cerrarla al terminar; una que atiende peticiones durante el día tiene dos opciones razonables:
- Sesión por operación: abrir, hacer y cerrar. Sencillo y robusto; cuesta una llamada extra por operación.
- Sesión reutilizada: guardarla y renovarla cuando el servidor responda que ha caducado. Más eficiente y algo más de código.
Trata la caducidad como algo normal, no como un error
Que el testigo caduque no es un fallo: es el funcionamiento previsto. Si tu cliente reintenta una vez abriendo sesión de nuevo, la integración deja de romperse sola por las noches.
Qué cuenta como buena práctica#
- Una credencial por integración, no una compartida entre todas.
- Permisos mínimos: si un proceso solo lee, que su cuenta solo lea.
- Secretos fuera del código: variables de entorno o gestor de secretos.
- Nada de credenciales en los registros de actividad. Si registras las llamadas
para depurar, asegúrate de no volcar la cabecera
Authorization. - Rotación: cambia la contraseña de integración con la misma disciplina con la que cambias las de las personas, y revoca las de integraciones que ya no existan.
Qué viene después#
Con la sesión abierta, lo siguiente es leer: Consultas.