Consumo de la API

Este resumen te permite entender cómo una aplicación habla con la API, para acompañar al cliente y diagnosticar incidencias. La referencia completa orientada a quien programa el cliente está en apis.esofitec.com.

El camino de una llamada#

1. Login. La aplicación envía usuario y contraseña a /api/login y recibe un token.
2. Token en cada petición. Ese token viaja en una cabecera —un dato que la aplicación adjunta a cada petición— llamada Authorization, con el formato Bearer <token>, en todas las llamadas siguientes.
3. Consultas. GET /api/view/{nombre} o GET|POST /api/proc/{nombre} devuelven datos al momento.
4. Operaciones a3ERP (custom). POST /api/custom/{dispatcher}/{nombre} devuelve un número de tarea; la aplicación consulta GET /api/task/{nº} hasta que el resultado está listo.

Para comprobar rápidamente desde el navegador si la API está viva, y para el diagnóstico de errores, consulta Solución de problemas.

Tres cosas que conviene tener claras (para soporte)#

La cabecera User-Agent#

El User-Agent es un texto con el que cada aplicación se identifica al llamar (lo envía en una cabecera). Cada aplicación debe enviar siempre el mismo User-Agent en todas sus llamadas. El token queda ligado a ese User-Agent: si cambia, el token deja de ser válido y la API responde 401.

Las tareas custom siempre responden 200#

Al consultar GET /api/task/{nº}, la API responde 200 aunque la tarea haya fallado. Hay que mirar el cuerpo de la respuesta: si trae un bloque de error, la operación no se completó.

Paginación#

Las consultas se devuelven paginadas: por defecto 50 registros por página. La aplicación puede pedir pageNumber y pageSize (máximo 50), y en la cabecera de respuesta X-Pagination viajan los totales (cuántos registros y páginas hay, página actual, si hay siguiente/anterior).

Parámetros de las consultas#

Los procedimientos con parámetros los reciben así: en GET, como objeto JSON codificado en base64 (una forma de empaquetar el texto para que viaje en una cabecera) dentro de la cabecera Parameters; en POST, como objeto JSON en el cuerpo de la petición.

Códigos de estado#

Para los detalles de cada método, modelos de petición/respuesta y ejemplos, consulta apis.esofitec.com.