Integración de DECA con ERP, facturación y gestores de flota

La API REST permite crear, actualizar, consultar y listar documentos DeCA desde un sistema externo. El ERP conserva su referencia y DECA devuelve el identificador, la versión y la URL pública estable del documento.

Abrir Swagger UI Abrir consola de pruebas Descargar demo VB.NET + Access

Qué incluye la integración

El objetivo es que el cliente pueda integrar DECA en su flujo normal de trabajo: albaranes, expediciones, viajes o cargas. No hace falta que el usuario vuelva a introducir los mismos datos en la web.

API REST autenticada

Las llamadas se hacen contra https://deca.netsistemas.com/api.php usando la cabecera X-Api-Key de cada empresa.

Proyecto demo descargable

Incluye una aplicacion WinForms en VB.NET Framework 4.8 con base Access de ejemplo y un cliente API reutilizable.

Swagger UI oficial

Documentación generada desde OpenAPI, con esquemas, ejemplos, autenticación y llamadas reales mediante Try it out.

Importante: Swagger y la consola llaman al entorno real. Para pruebas de creación o modificación conviene utilizar una empresa y una clave API de pruebas.

Puesta en marcha

Un integrador puede comprobar la conexión completa sin instalar herramientas adicionales.

Solicitar la clave

DECA facilita una X-Api-Key vinculada a la empresa. Debe almacenarse como un secreto de configuración.

Probar la lectura

Abra Swagger, pulse Authorize e invoque accion=listar. Una respuesta HTTP 200 confirma conexión y permisos.

Probar un alta

Cree primero un viaje sin fecha con una referencia externa de pruebas. No se genera PDF hasta que se asigne la fecha.

Guardar el vínculo

Conserve idDeca y url. Envíe también origenRegistro e idExterno para poder recuperar el enlace desde el ERP.

Flujo recomendado para un ERP

Sincronizar maestros

Opcionalmente, el ERP mantiene clientes, vehiculos y conductores con accion=guardar. La web los ofrece despues en sus selectores.

Enviar a DECA

El ERP llama a accion=crear o accion=actualizar con JSON y la clave API de la empresa.

Guardar la respuesta

DECA devuelve idDeca, url, numVersion y si se ha generado PDF. El ERP debe guardar al menos el identificador y la URL.

Consultar o reenviar

El ERP puede consultar el estado, abrir la URL publica o reenviar el PDF al conductor.

Clientes, vehiculos y datos maestros

La API permite sincronizar los maestros habituales del ERP. Es opcional para crear un DeCA, pero evita dobles mantenimientos y deja clientes, matriculas y conductores disponibles tambien en la aplicacion web.

Clientes

/api_clientes.php crea, actualiza, consulta, lista, activa y desactiva clientes. Admite nombre, NIF, domicilio y referencia ERP.

Vehiculos

/api_vehiculos.php mantiene tractoras, remolques, rigidos y otros vehiculos. Las matriculas activas aparecen en el formulario web.

Conductores

/api_conductores.php mantiene nombre y telefono. Los conductores activos pueden utilizarse para el envio directo por WhatsApp.

Sin duplicados: use accion=guardar y envie siempre origenRegistro + idExterno. La primera llamada crea el maestro; las siguientes actualizan el mismo registro. Las bajas se realizan con accion=desactivar y conservan el historial.

El DeCA conserva una copia de los datos contractuales de cada viaje. Aunque se use el maestro, el alta del documento debe incluir cargador, matriculas y mercancias tal como eran en ese transporte.

Endpoints principales

Operacion	Metodo	Uso
Crear	POST	`accion=crear`. Crea un DeCA desde los datos del ERP.
Actualizar	POST	`accion=actualizar`. Actualiza datos y genera nueva version si procede.
Consultar	GET	`accion=consultar&id=123`. Devuelve cabecera, estado y lineas.
Buscar	GET	`accion=buscar&origen=ERP_CLIENTE&idExterno=12345`. Localiza el DeCA asociado al registro del ERP.
Listar	GET	`accion=listar`. Permite filtros por fechas, no planificados, limit y offset.
Guardar cliente	POST	`/api_clientes.php` con `accion=guardar`. Crea o actualiza por referencia ERP.
Guardar vehiculo	POST	`/api_vehiculos.php` con matricula, tipo y referencia ERP.
Guardar conductor	POST	`/api_conductores.php` con nombre, telefono y referencia ERP.
Listar maestros	GET	Los tres endpoints admiten `id`, referencia ERP, `q`, `activo`, `limit` y `offset`.

La clave API debe enviarse en cabecera HTTP: X-Api-Key: clave_de_la_empresa. No debe viajar en la URL.

Identificacion del registro del ERP

Para mantener trazabilidad se recomienda enviar siempre estos dos campos:

`origenRegistro`

Identifica el sistema origen, por ejemplo ERP_CLIENTE, FACTUNET o APP_FLOTA.

`idExterno`

Identifica el registro dentro del ERP: numero de envio, albaran, expedicion o clave interna.

Con esta pareja, el ERP puede buscar posteriormente el documento sin depender de que el usuario haya guardado manualmente el idDeca.

Reglas que debe conocer el integrador

Evitar duplicados

La pareja origenRegistro + idExterno es única dentro de cada empresa. Repetirla en un alta devuelve HTTP 409; en ese caso debe actualizarse el documento existente.

Actualizaciones parciales

accion=actualizar conserva los campos que no se envían. Si se envía lineas, se sustituyen todas las líneas anteriores por las nuevas.

Fecha y PDF

Sin fechaTransporte el viaje queda no planificado. Al asignar fecha, DECA valida los datos obligatorios y genera la versión PDF.

URL estable

La URL pública no cambia al modificar el viaje. Siempre presenta la última versión, por lo que no es necesario reenviar otro enlace al conductor.

Ejemplos habituales desde un ERP

Crear o actualizar un cliente

POST https://deca.netsistemas.com/api_clientes.php
X-Api-Key: clave_de_la_empresa
Content-Type: application/json

{
  "accion": "guardar",
  "nombre": "Harinas Leonesas SL",
  "nif": "B24010101",
  "domicilio": "Pol. Ind. Leon Oeste 12, Leon",
  "origenRegistro": "ERP_EMPRESA",
  "idExterno": "CLI-00428"
}

Crear o actualizar un vehiculo

POST https://deca.netsistemas.com/api_vehiculos.php
X-Api-Key: clave_de_la_empresa
Content-Type: application/json

{
  "accion": "guardar",
  "matricula": "1234 KLM",
  "tipo": "tractora",
  "marca": "Volvo",
  "modelo": "FH 460",
  "origenRegistro": "ERP_EMPRESA",
  "idExterno": "VEH-00117"
}

Crear o actualizar un conductor

POST https://deca.netsistemas.com/api_conductores.php
X-Api-Key: clave_de_la_empresa
Content-Type: application/json

{
  "accion": "guardar",
  "nombre": "Carlos Martin Gomez",
  "telefono": "34600111222",
  "origenRegistro": "ERP_EMPRESA",
  "idExterno": "CON-00032"
}

Consultar maestros

GET /api_clientes.php?activo=1&q=Harinas&limit=50
GET /api_vehiculos.php?origen=ERP_EMPRESA&idExterno=VEH-00117
GET /api_conductores.php?id=32
X-Api-Key: clave_de_la_empresa

Crear DeCA con cliente y vehiculo

POST https://deca.netsistemas.com/api.php
X-Api-Key: clave_de_la_empresa
Content-Type: application/json

{
  "accion": "crear",
  "cargadorNombre": "Harinas Leonesas SL",
  "cargadorNif": "B24010101",
  "cargadorDomicilio": "Pol. Ind. León Oeste 12, León",
  "origen": "Leon",
  "destino": "Valladolid",
  "fechaTransporte": "2026-10-06",
  "matriculaTractora": "1234-KLM",
  "origenRegistro": "ERP_CLIENTE",
  "idExterno": "ALB-2026-00158",
  "lineas": [
    { "descripcion": "Harina de trigo", "cantidad": 40, "unidad": "sacos", "pesoKg": 1000 }
  ]
}

Crear viaje no planificado, sin fecha

{
  "accion": "crear",
  "cargadorNombre": "Ceramicas Levante SA",
  "cargadorNif": "A46020202",
  "origen": "Valencia",
  "destino": "Burgos",
  "matriculaTractora": "1198-MNC",
  "origenRegistro": "ERP_CLIENTE",
  "idExterno": "PRE-2026-0042",
  "lineas": [
    { "descripcion": "Azulejo ceramico paletizado", "cantidad": 18, "unidad": "palets", "pesoKg": 12600 }
  ]
}

Actualizar vehiculo o asignar fecha

{
  "accion": "actualizar",
  "id": 125,
  "fechaTransporte": "2026-08-21",
  "matriculaTractora": "7350-LPD",
  "matriculaRemolque": "R-8841-LHG"
}

{
  "ok": true,
  "idDeca": 125,
  "token": "7f4e...",
  "url": "https://deca.netsistemas.com/deca.php?t=7f4e...",
  "numVersion": 1,
  "pdf": true
}

Viajes sin fecha de transporte

La API permite crear registros no planificados, sin fechaTransporte. En ese caso el documento queda como borrador y no genera PDF hasta que se asigne fecha.

Alta anticipada

El ERP puede crear el registro aunque todavia no se conozca la fecha exacta del viaje.

Actualizacion posterior

Cuando el usuario asigne fecha de transporte, se llama a actualizar y DECA genera el PDF.

Listado filtrado

accion=listar&noPlanificados=1 devuelve solo documentos sin fecha de transporte. Para acotar el resultado, filtre por creación, modificación o registro.

GET /api.php?accion=listar&noPlanificados=1&fechaCampo=creacion&fechaDesde=2026-08-01&limit=100
X-Api-Key: clave_de_la_empresa

Las fechas desde y hasta son opcionales e independientes. fechaHasta es inclusiva. No combine viajes no planificados con fechaCampo=transporte, porque esos registros no tienen fecha de viaje.

Respuestas, errores y reintentos

Código	Qué significa	Acción recomendada
200	Operación correcta.	Validar `ok` y guardar los identificadores devueltos.
201	Maestro creado correctamente.	Guardar el identificador interno devuelto y mantener la referencia ERP.
400	JSON, fecha o datos obligatorios incorrectos.	Mostrar o registrar el campo `error`; no repetir sin corregir la petición.
401	Clave ausente o no válida.	Revisar la cabecera `X-Api-Key` y la configuración del entorno.
403	API no disponible para la empresa o suscripción caducada.	Contactar con soporte o con el administrador de la cuenta.
404	El `idDeca` no existe para esa empresa.	Comprobar el identificador o buscar por referencia externa.
409	Ya existe la referencia externa enviada.	Buscar el registro y realizar una actualización.
500	Error temporal al completar la operación.	Registrar la respuesta y reintentar de forma controlada; si persiste, contactar con soporte.

No registre la clave API en logs, URLs ni capturas. En producción utilice HTTPS, tiempos de espera razonables y reintentos solo para errores temporales.

Comprobación antes de pasar a producción

La clave API se guarda fuera del código fuente y nunca se envía en la URL.
Cada envío del ERP usa una referencia externa estable y única.
La sincronización de clientes, vehículos y conductores usa accion=guardar y se ha probado dos veces con la misma referencia.
Las bajas de maestros se envían como accion=desactivar; no se intenta borrar el historial.
El ERP conserva idDeca y url después de crear el documento.
Las modificaciones usan accion=actualizar y el identificador correcto.
Se tratan expresamente los códigos 400, 401, 403, 404, 409 y 500.
Se ha probado el flujo sin fecha, la asignación posterior de fecha y la generación del PDF.
La consulta paginada continúa mientras offset + items.length sea menor que total.

Recursos para desarrolladores

Demo VB.NET + Access

Proyecto de ejemplo para Visual Studio con cliente API, modelos, formularios y base Access.

Descargar ZIP

Swagger interactivo

Swagger UI oficial generado desde la definición OpenAPI, con autenticación, esquemas y Try it out.

Abrir Swagger

Consola guiada

Formulario sencillo con ejemplos preparados para altas, cambios, consultas y listados.

Abrir consola

OpenAPI JSON

Definicion tecnica para importar en Postman, generar clientes o documentacion interna.

Ver OpenAPI