API DeCA para ERP, TMS, facturación y gestores de flota

Qué incluye la integración

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

Puesta en marcha

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

Flujo recomendado para un ERP

Entidades, 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, transportistas, matriculas y conductores disponibles tambien en la aplicacion web.

Identificacion del registro del ERP

Número de DeCA por empresa

Cada empresa tiene su propia numeración consecutiva, automática e inmutable. El campo numeroEmpresa identifica el número visible del DeCA dentro de esa empresa; idDeca sigue siendo el ID global que debe conservar el ERP y utilizar en consultas, modificaciones, historial y URLs.

{ "ok": true, "idDeca": 125, "numeroEmpresa": 8 }

numeroEmpresa es de solo lectura y no debe enviarse al crear o modificar. No cambia al editar, anular o finalizar un documento. Duplicar un DeCA genera un nuevo ID y un nuevo número. La numeración no se reinicia cada año y puede tener huecos si se eliminan documentos.

Los documentos existentes conservan sus IDs, URLs y PDFs históricos. Los nuevos PDFs muestran el número de empresa y el ID global. En NTS, numeroEmpresa es independiente de numeroDocumento, la referencia del ERP; una sustitución conserva esa referencia, pero crea un nuevo DeCA con otro ID y número.

Para mantener trazabilidad se recomienda enviar siempre estos dos campos:

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

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",
  "esCliente": true,
  "esTransportista": false,
  "origenRegistro": "ERP_EMPRESA",
  "idExterno": "CLI-00428"
}

Crear o actualizar un transportista

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

{
  "accion": "guardar",
  "nombre": "Transportes del Norte SL",
  "nif": "B00000001",
  "domicilio": "Calle del Transporte 8, Leon",
  "esCliente": false,
  "esTransportista": true,
  "origenRegistro": "ERP_EMPRESA",
  "idExterno": "TRA-00017"
}

Validar e importar clientes por lotes

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

{
  "accion": "validar",
  "modoDuplicados": "actualizar",
  "registros": [
    {
      "origenRegistro": "ERP_EMPRESA",
      "idExterno": "CLI-00428",
      "nombre": "Harinas Leonesas SL",
      "nif": "B24010101",
      "domicilio": "Pol. Ind. Leon Oeste 12, Leon",
      "esCliente": true,
      "esTransportista": false,
      "activo": true
    }
  ]
}

La respuesta anticipa cuántas fichas se crearían, actualizarían, omitirían o producirían error. Tras revisar el resultado, repita el mismo lote con accion=importar. La operación es atómica: si existe un error no se guarda ninguna fila.

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",
  "email": "carlos@transportes.test; trafico@transportes.test",
  "notificarEmail": true,
  "origenRegistro": "ERP_EMPRESA",
  "idExterno": "CON-00032"
}

Consultar maestros

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

Crear o actualizar una granja o lugar habitual

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

{
  "accion": "guardar",
  "codigo": "GR-018",
  "nombre": "Granja Los Prados",
  "domicilio": "Camino Rural 4, Segovia",
  "esOrigen": true,
  "esDestino": false,
  "activo": true,
  "origenRegistro": "ERP_EMPRESA",
  "idExterno": "GRANJA-018"
}

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",
  "idCliente": 42,
  "idTransportista": 57,
  "cargadorNombre": "Harinas Leonesas SL",
  "cargadorNif": "B24010101",
  "cargadorDomicilio": "Pol. Ind. León Oeste 12, León",
  "idLugarOrigen": 18,
  "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,
  "numeroEmpresa": 8,
  "token": "7f4e...",
  "url": "https://deca.netsistemas.com/deca.php?t=7f4e...",
  "numVersion": 1,
  "pdf": true
}

Crear un reparto o ruta multipunto

Use el endpoint específico cuando el mismo cargador contractual y transportista efectivo realizan varios envíos en un único viaje. Los datos comunes se indican una vez y cada elemento de envios identifica su recorrido y mercancía.

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

{
  "accion": "crear",
  "cargadorNombre": "Distribuciones Centro SL",
  "cargadorNif": "B28030303",
  "cargadorDomicilio": "Calle Comercio 15, Madrid",
  "transportistaNombre": "Transportes del Norte SL",
  "transportistaNif": "B00000001",
  "fechaTransporte": "2026-08-24",
  "matriculaTractora": "1234 KLM",
  "origenRegistro": "ERP_CLIENTE",
  "idExterno": "RUTA-2026-0087",
  "envios": [
    {
      "referencia": "PED-4501",
      "idLugarOrigen": 18,
      "destino": "Toledo",
      "lineas": [
        { "descripcion": "Conservas en cajas", "cantidad": 40, "unidad": "cajas", "pesoKg": 520 }
      ]
    },
    {
      "referencia": "PED-4502",
      "origen": "Toledo",
      "destino": "Ciudad Real",
      "lineas": [
        { "descripcion": "Bebidas paletizadas", "cantidad": 8, "unidad": "palets", "pesoKg": 4300 }
      ]
    }
  ]
}

La API histórica /api.php continúa sin cambios para viajes de un solo envío. También puede actualizar fecha, matrículas y estados de un reparto; para cambiar sus rutas o mercancías debe usarse /api_repartos.php.

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.

Recursos para desarrolladores