Integración API · Versión 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 y sustituciones, no anulaciones sin sustituto.

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. Otras unidades se configuran por empresa en administración. 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.

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.

Respuestas, reintentos y lotes

La respuesta incluye numeroEmpresa, el número automático del DeCA dentro de la empresa. Es independiente de doc_Id y de numeroDocumento. En una sustitución, numeroDocumento se conserva, pero el nuevo DeCA recibe otro numeroEmpresa. Los reintentos idempotentes devuelven el número ya asignado.

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

{
  "resultado": "OK",
  "doc_Id": "00000000-0000-4000-8000-000000000001",
  "numeroDocumento": "EJEMPLO-2026-001",
  "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."]
}

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 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.

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 se usa su editor web o la sustitución por api_nts.php.

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.