Integración
Procesos
Hay cosas que no se hacen escribiendo registros sueltos: generar un albarán a partir de unos partes, renovar cuotas, recalcular importes. Eso son procesos de negocio de la solución, y la API permite lanzarlos.
Cómo se lanza#
GET {BASE}/layouts/{recurso}/script/{proceso}?script.param={parámetro}
Authorization: Bearer {token}
{recurso}es el contexto sobre el que se ejecuta.{proceso}es el nombre exacto del proceso.script.parames su parámetro, texto plano. Cuando hace falta pasar varios datos, lo habitual es enviar un JSON serializado.
La respuesta trae un campo de resultado: si es distinto de 0, el proceso ha
terminado con error y no debes dar la operación por buena.
Un proceso que falla puede responder HTTP 200
La llamada ha ido bien; lo que ha fallado es el proceso. Comprueba siempre el resultado dentro de la respuesta, no solo el código HTTP. Es el error de integración que más tarde se detecta: todo parece correcto durante semanas.
Saber qué procesos existen#
GET {BASE}/scripts
Devuelve los procesos publicados. No inventes nombres: pídelos así, o consulta con Esofitec cuáles están pensados para ser llamados desde fuera.
No todo proceso está pensado para llamarse desde la API
Muchos asumen que hay una persona delante, con una pantalla abierta y un registro seleccionado. Llamarlos desde una integración puede dejar datos a medias. Usa solo los que Esofitec te indique como invocables, y pregunta antes de improvisar.
Cuándo usar un proceso y cuándo escribir directamente#
| Situación | Qué usar |
|---|---|
| Dar de alta un cliente, un artículo, una persona | Escritura directa |
| Registrar un parte con sus horas y materiales | Escritura directa |
| Generar un documento a partir de otros | Proceso |
| Numerar, recalcular totales, aplicar tarifas | Proceso |
| Cualquier cosa que en la aplicación sea un botón | Proceso |
La regla práctica
Si en la aplicación eso se consigue rellenando campos, escribe. Si se consigue pulsando un botón, hay un proceso detrás, y replicarlo a mano desde fuera es garantizarse un descuadre. La numeración de documentos es el ejemplo clásico: parece un simple número hasta que dos procesos simultáneos piden el mismo.
Buenas prácticas#
- Uno cada vez. Los procesos que numeran o generan documentos no deben lanzarse en paralelo desde varios hilos.
- Comprueba antes y después. Si el proceso genera un documento, léelo después para confirmar que existe con los datos esperados.
- Registra el parámetro que enviaste. Cuando algo salga raro, es lo primero que se necesita para reproducirlo.
Qué viene después#
Errores y límites explica cómo se informan los fallos y qué cuidados tiene el servidor.