Integración
Errores y límites
Cómo se informan los errores#
Toda respuesta trae un bloque messages con un código y un texto:
{
"response": { },
"messages": [ { "code": "0", "message": "OK" } ]
}
code igual a 0 significa que todo ha ido bien. Cualquier otro valor es un
error, y hay que leerlo aunque el HTTP sea 200.
No te fíes solo del código HTTP
Es el fallo de integración más frecuente y el que más tarda en detectarse: la
llamada responde 200, el proceso escribe en el registro de actividad «correcto» y
los datos no están. Comprueba messages[0].code en todas las respuestas.
Los casos que hay que tratar aparte#
| Situación | Cómo llega | Qué hacer |
|---|---|---|
| Una búsqueda sin resultados | Como un error, no como una lista vacía | Tratarlo como «cero registros», no como un fallo |
| Testigo caducado | Error de autenticación en una llamada que antes funcionaba | Abrir sesión de nuevo y reintentar una vez |
| Campo inexistente | Error indicando que falta el campo | Recortar el payload contra los campos que publica el recurso |
| Validación de negocio | Error con el mensaje de la regla incumplida | Corregir el dato: la regla es la misma que en pantalla |
«Sin resultados» como error confunde a todo el mundo
Buscar clientes de una empresa que aún no tiene ninguno no es un fallo del sistema. Si tu cliente no distingue ese caso, tu integración se caerá el primer día que un filtro no devuelva nada, que siempre acaba pasando.
Límites que conviene respetar#
Sesiones simultáneas#
Tu solución tiene un número limitado de conexiones. Cada sesión abierta consume una.
Las sesiones huérfanas son el problema clásico
Un proceso que falla y no cierra la sesión deja la conexión ocupada hasta que
caduca. Repetido unas cuantas veces, agota el cupo y los usuarios dejan de
poder entrar. Cierra siempre en el bloque finally.
Tamaño de las respuestas#
Pide lo que vayas a usar:
- Usa los recursos
_IDSy_GRIDcuando no necesites la ficha completa. - No pidas imágenes ni documentos salvo que los vayas a guardar.
- Pagina de 100 en 100 en lugar de pedir miles de registros de una vez.
Búsquedas#
Una búsqueda por un campo que no está preparado para ello obliga al servidor a recorrer todo. Si una consulta tarda mucho, suele ser eso.
Filtra siempre por empresa y por fecha de modificación
Además de ser correcto, son los dos filtros que más reducen el trabajo del servidor. Una sincronización incremental bien filtrada es cientos de veces más barata que una completa.
Concurrencia#
Lee en paralelo si lo necesitas; escribe en serie. Los procesos que numeran documentos no deben ejecutarse a la vez desde varios hilos.
Dos procesos pidiendo el mismo número al mismo tiempo
Es la carrera clásica, y el resultado son dos documentos con el mismo número que alguien tiene que corregir a mano. Serializa las escrituras que numeren.
Qué registrar en tu integración#
Para que un problema se pueda diagnosticar sin adivinar:
- La operación y el recurso.
- El código y el mensaje devueltos.
- El identificador del registro afectado.
- La hora.
Y lo que no debe aparecer nunca en un registro de actividad: la cabecera de autorización, la contraseña y los datos personales que no necesites para depurar.
Antes de llamar a soporte#
Tres comprobaciones que resuelven la mayoría de las incidencias:
- ¿La opción está contratada y activa? Sin ella, las credenciales correctas también fallan.
- ¿El recurso publica los campos que envías? Consúltalo y compara.
- ¿Estás filtrando por empresa? Muchos «faltan datos» y «sobran datos» son eso.
Si tras ello sigue fallando, aporta la hora, el recurso, el código de error y el cuerpo enviado sin credenciales. Con eso se reproduce en minutos.
Qué viene después#
Para lectura masiva y cuadros de mando, Analítica y BI.