Integración

Escritura

La API permite crear y modificar registros. No permite borrarlos.

Crear#

POST {BASE}/layouts/{recurso}/records
Authorization: Bearer {token}
Content-Type: application/json

{
  "fieldData": {
    "ID_EMPRESA": "5B7C…",
    "NOMBRE": "Cliente de ejemplo",
    "EMAIL": "usuario@ejemplo.com",
    "VIGENTE": 1
  }
}

Devuelve el recordId del registro creado. Para conocer su ID estable, léelo a continuación.

Modificar#

PATCH {BASE}/layouts/{recurso}/records/{recordId}
Content-Type: application/json

{ "fieldData": { "EMAIL": "otro@ejemplo.com" } }

Solo viajan los campos que quieres cambiar: lo que no envías, no se toca.

Las cinco reglas que evitan el 90 % de los problemas#

1. La empresa se escribe a mano#

En las pantallas, la empresa se rellena sola porque la sesión del usuario sabe en cuál está trabajando. Una integración no tiene esa sesión, así que debe enviar ID_EMPRESA explícitamente en cada alta.

Un registro sin empresa es un registro perdido

No da error al crearlo, pero no aparece desde ninguna empresa, y la API no puede borrarlo. Queda como basura permanente hasta que alguien lo corrija desde la aplicación. Envía siempre la empresa.

2. Comprueba que el recurso publica campos#

Consulta primero GET {BASE}/layouts/{recurso} y aborta si la lista viene vacía. Escribir contra un recurso sin campos publicados crea registros en blanco, y vuelve al problema anterior.

3. Las fechas van en MM/DD/YYYY#

Mes, día, año. Repetido aquí porque en escritura el error no se ve: el registro se crea, con otra fecha.

4. Envía solo campos que el recurso publica#

Si mandas un campo que ese recurso no expone, la llamada falla entera. La forma robusta de escribir un cliente genérico es recortar el payload contra la lista de campos del recurso antes de enviarlo, en lugar de mantener listas a mano que se quedan viejas.

5. Las validaciones son las mismas que en pantalla#

Un campo obligatorio lo sigue siendo, un valor de catálogo tiene que existir y un enlace tiene que apuntar a algo real. La API no es una puerta trasera a las reglas de negocio: es la misma puerta.

Cómo se enlazan los registros#

Los enlaces se hacen con el ID del registro destino, no con su código ni con su nombre:

Para enlazar	Envía
Una tarea con su proyecto	`ID_PROYECTO` con el `ID` del proyecto
Un parte con su tarea	`ID_TAREA`
Cualquier registro con su empresa	`ID_EMPRESA`
Un registro con un valor de catálogo	`ID_ESTADO`, `ID_TIPO_TAREA`, `ID_TARIFA`…

Resuelve los catálogos una vez, al empezar

Descárgate los catálogos que vayas a usar —estados, tipos, tarifas— y guárdalos en memoria como descripción → ID. Resolver cada valor con una llamada por registro multiplica el tiempo del proceso por diez sin ganar nada.

Dar de baja: no se borra, se retira#

No hay operación de borrado. Lo que se hace es marcar el registro como no vigente (VIGENTE: 0).

Por qué está bien que sea así

Si borraras un artículo, los albaranes del año pasado se quedarían sin él y los informes dejarían de cuadrar. Retirándolo, desaparece de los desplegables para lo nuevo y el histórico sigue intacto.

Ficheros e imágenes#

Los recursos que manejan documentos exponen el fichero como una URL dentro del campo. Se descarga con esa URL usando el mismo testigo de sesión. Hay recursos específicos para las imágenes —de artículo, de cliente, de persona— separados del recurso principal, precisamente para que consultar la ficha no arrastre la imagen.

No pidas las imágenes si no las vas a usar

Es la diferencia entre una sincronización de segundos y una de minutos.

Un orden de trabajo que funciona#

Abrir sesión.
Leer los catálogos necesarios y cachearlos.
Consultar los campos de cada recurso que vayas a escribir.
Escribir, recortando el payload y comprobando la respuesta de cada llamada.
Registrar qué se creó, con su ID, para poder repetir sin duplicar.
Cerrar sesión, pase lo que pase.

Hazlo repetible desde el principio

Toda integración se ejecuta dos veces algún día: porque falló a mitad, porque alguien la relanzó, porque hubo un corte de red. Si antes de crear compruebas si ya existe —por su ID o por su código—, ese día no pasa nada. Si no, aparecen duplicados que hay que limpiar a mano.

Qué viene después#

Para acciones que no son un simple alta —generar un documento, recalcular importes—, están los Procesos.