Primeros pasos
Qué es la API de s360
La API de s360 permite que otros programas lean y escriban los datos de tu solución: tu ERP, tu web, un cuadro de mando, una aplicación propia o un flujo automatizado. Es la puerta de entrada y salida de s360 para todo lo que no es una persona delante de una pantalla.
Es una opción contratable
La API no viene de serie. Se contrata aparte y se habilita para tu solución. Si intentas conectarte y recibes un error de autenticación aunque las credenciales sean correctas, lo primero que hay que comprobar es que la opción esté contratada y activada.
Para qué se usa de verdad#
Estos son los casos que se repiten en todas las integraciones:
| Necesidad | Cómo se resuelve |
|---|---|
| Que los clientes se den de alta una sola vez | El ERP crea y actualiza clientes en s360 |
| Facturar en el ERP lo servido en s360 | Se leen los albaranes servidos y sus líneas |
| Imputar el coste de las compras | El ERP envía sus facturas y s360 las reparte por proyecto y tarea |
| Alimentar un cuadro de mando | Se leen proyectos, tareas, partes y sus importes |
| Registrar trabajo desde una aplicación propia | Se crean partes, servicios y materiales |
| Sincronizar catálogos | Se leen artículos, tarifas, tipos y estados |
Qué tiene que saber quien va a integrar#
Tres ideas antes de escribir una sola línea de código:
- Se trabaja contra recursos, no contra tablas. La API publica un conjunto de
recursos con nombre —
API_CLIENTES,API_PROYECTOS,API_PARTES…— y cada uno expone un juego concreto de campos. No hay acceso libre a la base de datos: lo que no publica un recurso, no existe para la API. Ver Catálogo de recursos. - La sesión es con testigo (token) y caduca. Se abre una sesión con las credenciales, se trabaja con el testigo que devuelve y se cierra al terminar. Ver Autenticación.
- Tu solución puede tener varias empresas. Casi todos los datos llevan la empresa a la que pertenecen, y filtrar por ella es responsabilidad de quien llama. Ver Consultas.
Lo que la API hace, y lo que no#
Sí puedes:
- Leer registros de cualquier recurso publicado, con filtros, orden y paginación.
- Contar cuántos cumplen una condición sin descargarlos.
- Crear y modificar registros.
- Descargar los ficheros y las imágenes asociadas a un registro.
- Lanzar procesos de negocio ya definidos en la solución, como generar un documento o recalcular importes. Ver Procesos.
No puedes:
- Borrar registros. No está expuesto: la baja se hace marcando el registro como no vigente, que es lo que conserva el histórico.
- Cambiar la estructura de la solución, ni crear campos, ni tocar la configuración.
- Saltarte las reglas de negocio: las validaciones que se aplican en pantalla se aplican también aquí.
No borrar es una decisión, no una carencia
En una solución de gestión, borrar rompe la trazabilidad de lo que ya se facturó o se ejecutó. Todo lo que se retira se retira desmarcando Vigente, y sigue estando para los informes del año pasado.
Antes de empezar#
Necesitas tres cosas, y Esofitec te las entrega al activar la opción:
| Dato | Qué es |
|---|---|
| Dirección base | La URL contra la que se hacen todas las llamadas |
| Usuario de integración | Una cuenta creada para máquinas, no para personas |
| Contraseña | Que no debe vivir en el código |
La credencial de integración no es la de una persona
Se crea una cuenta para cada integración, con sus permisos, y así se puede revocar sin dejar a nadie fuera y se sabe qué sistema hizo cada cosa. No reutilices la cuenta con la que entra un usuario.
Guarda la contraseña fuera del código
Variables de entorno o un gestor de secretos. Nunca en el repositorio, ni en un fichero de configuración versionado, ni en una captura de pantalla de un correo.
Por dónde seguir#
| Página | Qué encontrarás |
|---|---|
| Autenticación | Abrir sesión, usar el testigo y cerrarla |
| Consultas | Leer, buscar, filtrar, ordenar, paginar y contar |
| Escritura | Crear y modificar registros, y las reglas que hay que respetar |
| Procesos | Lanzar procesos de negocio de la solución |
| Catálogo de recursos | Qué publica la API, por familias |
| Errores y límites | Cómo se informan los fallos y cómo no tumbar el servidor |
| Analítica y BI | La vía de solo lectura para cuadros de mando |