Integración API · Versión 1.3 · Compatible con las altas 1.2

FORMATO NTS alternativo

Una alternativa al JSON habitual de DECA ERP para crear documentos de transporte con conductores, vehículos, grupos de origen y destinos, mercancías y sustituciones.

Disponible por defecto para todas las empresas actuales y nuevas con empresa activa, suscripción vigente y clave API válida. Utiliza la misma clave de empresa que las API existentes; no necesita una segunda clave ni una activación individual inicial. El administrador puede desactivarlo para una empresa.

Descargar ejemplo JSON Descargar OpenAPI Probar en Swagger

Demo VB.NET + Access

La demo de escritorio incluye el botón FORMATO NTS alternativo: prepara o importa el JSON de un viaje, guarda el borrador y la respuesta en Access, y permite reintentar o sustituir el documento. Utiliza la misma clave API que el formato habitual. Incluye código fuente y un ejemplo JSON sin credenciales.

Descargar Access 32 bits Descargar Access 64 bits

Elija la arquitectura del motor ACE/Office instalado. La demo envía un documento NTS por viaje, no lotes. Al actualizar, conserve su base Access y no la sobrescriba con la base de ejemplo.

Conexión y empresa

POST https://deca.netsistemas.com/api_nts.php
Content-Type: application/json
X-Api-Key: CLAVE_API_DE_LA_EMPRESA
Idempotency-Key: OPERACION-UNICA-001

También se admite Authorization: Bearer CLAVE_API_DE_LA_EMPRESA. La clave debe mantenerse en el servidor del integrador, nunca en una URL ni en código público del navegador.

La clave determina la empresa emisora: el JSON no permite seleccionar otra empresa. El NIF y domicilio del emisor deben estar completos en DECA ERP. Los maestros se buscan y registran dentro de esa empresa.

El formato habitual continúa en api.php y los repartos en api_repartos.php. Elija un solo formato para cada operación: no hay deduplicación automática entre endpoints distintos. Este endpoint NTS admite altas, actualizaciones con versiones y sustituciones, no anulaciones sin sustituto.

Como alternativa a la clave de empresa, puede enviar solo X-User-Api-Key: CLAVE_PERSONAL. Se aplican los permisos de ese usuario y se registra su identidad en el historial.

Las llamadas crean documentos reales. Use una empresa de pruebas y datos ficticios durante la integración. El ejemplo descargable no contiene credenciales.

Ejemplo de alta

{
  "numeroDocumento": "EJEMPLO-2026-001",
  "cargador": {
    "nif": "DEMO-CARGADOR",
    "razonSocial": "Granja de ejemplo",
    "domicilio": "Camino de ejemplo 5, Segovia"
  },
  "transportista": {
    "nif": "DEMO-TRANSPORTISTA",
    "razonSocial": "Transportes de ejemplo",
    "domicilio": "Calle de ejemplo 10, Madrid"
  },
  "vehiculo": { "matriculaTractora": "1234BCD" },
  "canalNotificacion": "EMAIL",
  "conductores": [{
    "dni": "DEMO-CONDUCTOR-01",
    "nombre": "Conductor de ejemplo",
    "contactos": [{
      "tipoCanal": "EMAIL", "valor": "conductor@example.com"
    }]
  }],
  "grupos": [{
    "esOrigenCargadorContractual": true,
    "destinos": [{
      "razonSocial": "Destino de ejemplo",
      "domicilio": "Calle de ejemplo 20, Barcelona",
      "lineasMercancia": [{
        "descripcion": "Mercancia de ejemplo",
        "peso": 1200, "unidadMedida": "KG",
        "bultos": 24, "palets": 2
      }]
    }]
  }]
}

En curl, usando el archivo descargado y sustituyendo la clave por la de su empresa:

curl https://deca.netsistemas.com/api_nts.php \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: CLAVE_API_DE_LA_EMPRESA" \
  -H "Idempotency-Key: OPERACION-UNICA-001" \
  --data-binary @nts-ejemplo.json

Campos admitidos

Los nombres y la jerarquía son los del FORMATO NTS alternativo v1.2. El esquema OpenAPI detalla los tipos, requisitos y longitudes.

numeroDocumento, documentoOrigenId: Opcionales: número externo hasta 40 caracteres y GUID del documento sustituido. El número vigente es único dentro de la empresa. Sin número se asigna uno.
fechaTransporte, observaciones: Opcionales. Fecha YYYY-MM-DD; si se omite, se usa la fecha de emisión en Europe/Madrid. Observaciones generales: hasta 500 caracteres.
cargador: Opcional y compatible con integraciones anteriores. Puede enviarse como {"idCliente": 42} para utilizar una entidad activa de la misma empresa, o con nif, razonSocial, domicilio y datos de contacto. Si se omite, la empresa titular continúa actuando como cargador contractual. No mezcle el identificador y los datos completos en el mismo objeto.
transportista: Obligatorio. nif (20), razonSocial (150) y domicilio (200) obligatorios. Opcionales: contacto (150), telefono (30), email (150). Se identifica por NIF dentro de la empresa.
vehiculo: Obligatorio. matriculaTractora requerida; matriculaRemolque y tipo opcionales. El tipo describe la carrocería (hasta 80 caracteres). Las matrículas se normalizan, sin espacios ni guiones para su validación: 2 a 15 letras o dígitos.
conductores: Lista de 1 o 2. Cada uno requiere dni (40) y nombre (100). numeroTarjeta (40), contactos, notaDeca (300) y mostrarNotaDeca son opcionales. incluirConductorPdf en la raíz decide si el PDF muestra sus nombres y notas autorizadas. DNI, teléfono y email nunca se incorporan al PDF.
contactos y canalNotificacion: Hasta un contacto por canal, con tipoCanal y valor (150). Canales: EMAIL, WHATSAPP, TELEGRAM o SMS. El canalNotificacion de la raíz es obligatorio y admite los mismos valores. Los correos y teléfonos SMS/WhatsApp se validan.
grupos: De 1 a 100 grupos. esOrigenCargadorContractual es un booleano obligatorio. Si vale true, el origen es el cargador contractual resuelto; si vale false, se requiere origen con razón social y domicilio. La empresa autenticada sigue siendo la titular del registro.
origen y destinos: Cada tercero requiere razonSocial (150) y domicilio (200); NIF, contacto, teléfono y email son opcionales, con los mismos límites que el transportista. Cada grupo necesita al menos un destino. Los destinos admiten observaciones (300) y requieren lineasMercancia. Se identifican por nombre y domicilio dentro de la empresa; las coincidencias ambiguas se rechazan.
lineasMercancia: Al menos una por destino. Requiere descripcion (200), peso positivo y unidadMedida (30). bultos admite enteros no negativos; palets, decimales no negativos. Peso y palets: hasta dos decimales y 9999999999.99. Bultos: máximo 2147483647.

Unidades y límites

KG y T están disponibles inicialmente. El administrador de la empresa puede añadir y gestionar otras unidades en Configuración → Unidades de medida · API NTS; el superadministrador también puede hacerlo en la ficha de la empresa. Se conserva el valor y la unidad original; el factor de conversión permite calcular kg. Una unidad sin factor no aporta peso al total en kg.

Por defecto, la API rechaza las unidades no configuradas. El administrador de la empresa puede desactivar esta validación en la misma sección. En ese caso, la API conserva el código y la cantidad de una unidad desconocida, sin calcular su peso en kg; las unidades configuradas siguen usando su factor.

Máximo por petición: 2 MB y 20 documentos. Por documento: 200 destinos y 1000 líneas en total, PDF hasta 5 MB. Los datos no compatibles se rechazan mediante errores de validación.

El alta puede crear o actualizar los maestros. Enviar campos opcionales vacíos borra su valor. Envíe los datos de terceros y el tipo de vehículo que quiera conservar; en contactos de conductor solo se reemplazan los canales informados. El documento conserva su propia instantánea: cambios posteriores en maestros no modifican un PDF emitido.

Los conductores se comparten por defecto. Con la clave API individual, un usuario que desactive «Compartir chóferes con la empresa» creará y actualizará sus propias fichas privadas. La clave API general de empresa seguirá usando las fichas compartidas; el esquema NTS y las llamadas existentes no cambian.

Respuestas, reintentos y lotes

La respuesta incluye idDeca, el ID global del DeCA, y numeroEmpresa, su número consecutivo dentro de la empresa. Ambos son independientes de doc_Id y numeroDocumento. En una sustitución, numeroDocumento se conserva, pero el nuevo DeCA recibe otros idDeca, doc_Id y numeroEmpresa. Un reintento idempotente devuelve los mismos identificadores ya asignados.

Alta correcta: HTTP 201. Reintento reconocido: HTTP 200, con el mismo documento.

{
  "resultado": "OK",
  "idDeca": 123,
  "doc_Id": "00000000-0000-4000-8000-000000000001",
  "numeroDocumento": "EJEMPLO-2026-001",
  "numeroEmpresa": 7,
  "urlAcceso": "https://deca.netsistemas.com/deca.php?t=TOKEN",
  "repetido": false,
  "notificacion": {"canal": "EMAIL", "estado": "NO_CONFIGURADO"},
  "avisos": ["El canal solicitado queda registrado. El envio automatico no esta configurado."]
}

En las altas, use Idempotency-Key (hasta 200 caracteres) estable por operación. Reintente con el mismo JSON y clave; cambiar datos con la misma clave produce 409. Sin esta cabecera se reconoce la huella del JSON. Para dos transportes idénticos sin número, use claves distintas. Un número ya registrado con una clave explícita nueva produce 409: reutilice la original. Para modificarlo, use accion: actualizar con una clave nueva.

Para lotes envíe {"documentos":[DOCUMENTO_1,DOCUMENTO_2]}. Se devuelve HTTP 207, resultado: LOTE_PROCESADO y documentos con indice, http y resultado individual. Cada documento tiene su propia transacción: un fallo no revierte los demás.

Conserve el orden del lote al reintentar con la misma clave. Para reenviar un elemento por separado, mantenga su número o use la clave original seguida de :INDICE, empezando por cero.

401 / 403: Clave no válida o empresa inactiva / suscripción vencida o formato deshabilitado.
404 / 409: Documento origen no accesible en esa empresa / conflicto de número, sustitución o idempotencia.
405 / 413 / 415 / 422: Método distinto de POST / petición demasiado grande / contenido distinto de application/json / JSON mal formado o campos inválidos.
500: Fallo interno; reintente con la misma clave de idempotencia.

Los errores incluyen resultado y errores, una lista de objetos con campo y mensaje. En lotes revise siempre el estado de cada elemento.

Actualizar el mismo documento y generar una versión

Envíe un POST al mismo api_nts.php con accion: "actualizar" y el doc_Id recibido al crear el documento. También puede usar id, el ID global entero del DeCA, no su numeroEmpresa. Si envía ambos identificadores, deben corresponder al mismo documento.

Content-Type: application/json
X-Api-Key: CLAVE_API_DE_LA_EMPRESA
Idempotency-Key: ERP-TRANSPORTE-001-CAMBIO-02

{
  "accion": "actualizar",
  "doc_Id": "00000000-0000-4000-8000-000000000001",
  "versionEsperada": 1,
  "vehiculo": {
    "matriculaTractora": "9876XYZ",
    "matriculaRemolque": "R5678BCD"
  },
  "observaciones": "Datos corregidos desde el ERP"
}

Sustituya el GUID de ejemplo por el real. Se conservan ID, GUID, numeración, URL pública y QR. Si hay cambios y el viaje tiene fecha, se genera el siguiente PDF (v2, v3...) y se guarda el historial, sin sobrescribir los PDF anteriores. Los documentos ya sustituidos no se pueden actualizar.

Los campos omitidos conservan su valor. En vehiculo puede enviar solo las propiedades que cambian.
Si envía grupos, debe incluir la lista completa de orígenes, destinos y líneas que deban quedar: reemplaza la anterior. Lo mismo sucede con conductores. Los campos de cada elemento siguen el esquema del alta.
Si cambia transportista o cargador, envíe su bloque completo. Para cargador también se admite {"idCliente": 42}; null vuelve a utilizar la empresa titular.
Puede enviar fechaTransporte: null o matrículas null para dejarlas pendientes. Sin fecha se guardan los datos y su auditoría, pero no se emite otro PDF.
versionEsperada es opcional: si no coincide con la última versión PDF almacenada, devuelve 409 para evitar sobrescribir cambios no revisados.
No use documentoOrigenId al actualizar: es exclusivo de sustituciones. numeroDocumento no puede cambiarse.

Respuesta y reintentos de actualización

Respuesta HTTP 200 con los campos habituales, incluido idDeca, y los campos de actualización numVersion, cambiado y pdfDisponible. Si no cambia ningún dato, cambiado es false y no se incrementa la versión. Si el viaje queda sin fecha, numVersion es null y pdfDisponible es false.

Utilice una nueva Idempotency-Key para cada modificación, distinta de la del alta. Reintente esa modificación con la misma clave y JSON: recibirá su respuesta original con repetido: true, sin otra versión y sin deshacer modificaciones posteriores. Una clave reutilizada con otros datos produce 409. Sin clave solo se comparan los datos actuales, por lo que no se garantiza la protección frente a reintentos tardíos.

Los lotes admiten altas y actualizaciones, indicando la acción en cada elemento. En Swagger NTS están disponibles los ejemplos actualizar y actualizarMercancias.

Sustituir un documento

Envíe el documento completo corregido con documentoOrigenId igual al doc_Id del documento NTS vigente y una nueva clave de idempotencia. Debe pertenecer a la misma empresa. Se conserva numeroDocumento y se generan nuevo GUID y nueva URL; el enlace anterior muestra un aviso con acceso al vigente.

Cada documento admite una única sustitución directa. Para corregir de nuevo mediante la API NTS, indique el GUID del documento actualmente vigente.

Modificar desde la web

Los usuarios autorizados pueden pulsar Modificar en el listado para editar un DeCA NTS completo: cargador, transportista, conductores, contactos, fecha, matrículas, orígenes, destinos y mercancías, incluidos bultos y palets. La fecha y las matrículas pueden dejarse pendientes. Se conserva el ID, el GUID y la URL; los cambios con fecha generan una nueva versión PDF. Las versiones anteriores y el usuario responsable quedan en el historial.

La consulta mediante api.php y api_repartos.php devuelve los datos actuales de sus respectivos esquemas. Una modificación web no se envía automáticamente al ERP: este debe volver a consultar el documento. Las huellas de la petición original se conservan para que un reintento NTS no sobrescriba lo editado. Las escrituras de las API de formato habitual siguen reservadas a ese formato; para NTS use su editor web o api_nts.php con accion: actualizar. Las sustituciones siguen siendo una operación diferente.

Estado de las notificaciones

El canal solicitado se guarda y la respuesta devuelve NO_CONFIGURADO para ese canal; no confirma la entrega de un mensaje. El integrador puede enviar urlAcceso con su propio sistema.

De forma independiente, si el conductor asociado tiene email y NotificarEmail activado en su ficha, DECA puede enviar el aviso por correo con la configuración de la empresa. Los envíos se consultan en Emails enviados. No se realizan envíos automáticos de SMS, WhatsApp ni Telegram desde este endpoint.