API integration · Version 1.3 · Compatible with v1.2 creation requests

alternative NTS FORMAT

An alternative to standard DECA ERP JSON for creating transport documents with drivers, vehicles, origin and destination groups, goods and document replacements.

Enabled by default for all existing and new companies with an active company account, current subscription and valid API key. It uses the same company key as the existing APIs; no second key or separate initial activation is required. Administrators can disable it for a company.

Download JSON example Download OpenAPI Test in Swagger

VB.NET + Access demo

The desktop demo includes the alternative NTS FORMATbutton: prepare or import trip JSON, save the draft and response in Access, and retry or replace the document. It uses the same API key as the standard format. Source code and a JSON example without credentials are included.

Download 32-bit Access demo Download 64-bit Access demo

Choose the architecture of your installed ACE/Office engine. The demo sends one NTS document per trip, not batches. When updating, keep your Access database and do not overwrite it with the sample database.

Connection and company

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

Also supported: Authorization: Bearer CLAVE_API_DE_LA_EMPRESA. Keep the key on the integrator server, never in a URL or public browser code.

The key determines the issuing company: the JSON cannot select another company. The issuer tax ID and address must be complete in DECA ERP. Master records are found and stored within that company.

The standard format remains at api.php and multi-stop trips at api_repartos.php. Choose one format per operation: there is no automatic deduplication across different endpoints. This NTS endpoint supports creation, updates with version history and replacement, not cancellation without a replacement.

Alternatively, send only X-User-Api-Key: PERSONAL_KEY. The user's permissions apply and their identity is recorded in the audit history.

Requests create real documents. Use a test company and fictional data during integration. The downloadable example contains no credentials.

Creation example

{
  "numeroDocumento": "EJEMPLO-2026-001",
  "cargador": {
    "nif": "DEMO-CONSIGNOR",
    "razonSocial": "Example Farm",
    "domicilio": "5 Example Road, 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
      }]
    }]
  }]
}

With curl, use the downloaded file and replace the key with your company key:

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

Supported fields

Names and hierarchy follow the alternative NTS FORMAT v1.2. The OpenAPI schema specifies types, requirements and lengths.

numeroDocumento, documentoOrigenId: Optional: external number up to 40 characters and GUID of the replaced document. The current number is unique within the company. A number is assigned if omitted.
fechaTransporte, observaciones: Optional. Date in YYYY-MM-DD format; if omitted, the issue date in Europe/Madrid is used. General notes: up to 500 characters.
cargador: Optional and backwards compatible. Send {"idCliente": 42} to use an active customer entity from the same company, or send nif, razonSocial, domicilio and contact details. If omitted, the account holder remains the contractual consignor. Do not mix the identifier and full details in the same object.
transportista: Required. nif (20), razonSocial (150) and domicilio (200) are required. Optional: contacto (150), telefono (30), email (150). Identified by tax ID within the company.
vehiculo: Required. matriculaTractora is required; matriculaRemolque and tipo are optional. Type describes the body type (up to 80 characters). Registrations are normalized by removing spaces and hyphens for validation: 2 to 15 letters or digits.
conductores: List of 1 or 2. Each requires dni (40) and nombre (100). numeroTarjeta (40), contactos, notaDeca (300) and mostrarNotaDeca are optional. incluirConductorPdf at the root decides whether the PDF shows their names and authorised notes. ID numbers, telephone numbers and email addresses are never included in the PDF.
contactos and canalNotificacion: Up to one contact per channel, with tipoCanal and valor (150). Channels: EMAIL, WHATSAPP, TELEGRAM or SMS. The root canalNotificacion is required and accepts the same values. Email addresses and SMS/WhatsApp phone numbers are validated.
grupos: From 1 to 100 groups. esOrigenCargadorContractual is a required boolean. If true, the origin is the resolved contractual consignor; if false, provide origen with company name and address. The authenticated company remains the record owner.
origen and destinos: Each party requires razonSocial (150) and domicilio (200); tax ID, contact, phone and email are optional, with the same limits as the carrier. Each group needs at least one destination. Destinations accept observaciones (300) and require lineasMercancia. They are identified by name and address within the company; ambiguous matches are rejected.
lineasMercancia: At least one per destination. Requires descripcion (200), peso greater than zero and unidadMedida (30). bultos accepts non-negative integers; palets, non-negative decimals. Weight and pallets: up to two decimal places and 9999999999.99. Packages: maximum 2147483647.

Units and limits

KG and T are available initially. The company administrator can add and manage other units under Settings → Units of measurement · NTS API; the system administrator can also do so on the company record. The original value and unit are preserved; a conversion factor allows calculation in kg. A unit without a factor does not contribute to the kg total.

By default, the API rejects units that have not been configured. The company administrator can disable this validation in the same section. In that case, the API preserves the code and quantity of an unknown unit without calculating its weight in kg; configured units continue to use their conversion factor.

Maximum per request: 2 MB and 20 documents. Per document: 200 destinations, 1,000 lines in total and PDF up to 5 MB. Unsupported data is rejected with validation errors.

Creation may create or update master records. Sending empty optional fields clears their values. Send the party details and vehicle type you want to retain; only the supplied driver contact channels are replaced. The document retains its own snapshot: later master-data changes do not alter an issued PDF.

Drivers are shared by default. A personal API key belonging to a user who turns off “Share drivers with the company” creates and updates only that user's private driver records. The company API key continues to use shared records; the NTS schema and existing calls remain unchanged.

Responses, retries and batches

The response includes idDeca, the global DeCA ID, and numeroEmpresa, its sequential number within the company. Both are separate from doc_Id and numeroDocumento. A replacement retains numeroDocumento, but the new DeCA receives new idDeca, doc_Id and numeroEmpresa values. An idempotent retry returns the same identifiers already assigned.

Successful creation: HTTP 201. Recognized retry: HTTP 200, with the same document.

{
  "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."]
}

For creation, use Idempotency-Key (up to 200 characters), stable per operation. Retry with the same JSON and key; changing data with the same key returns 409. Without this header, the JSON fingerprint is recognized. For two identical unnumbered transports, use different keys. An existing number with a new explicit key returns 409: reuse the original key. To change the document, use accion: actualizar with a new key.

For batches, send {"documentos":[DOCUMENTO_1,DOCUMENTO_2]}. Returns HTTP 207, resultado: LOTE_PROCESADO and documentos with indice, http and individual results. Each document has its own transaction: a failure does not roll back the others.

Keep the batch order when retrying with the same key. To resend an item separately, retain its number or use the original key followed by :INDICE, starting at zero.

401 / 403: Invalid key, inactive company, expired subscription or disabled format.
404 / 409: Source document not accessible in that company, or number, replacement or idempotency conflict.
405 / 413 / 415 / 422: Method other than POST, request too large, content other than application/json, malformed JSON or invalid fields.
500: Internal failure; retry with the same idempotency key.

Errors include resultado and errores, a list of objects with campo and mensaje. Always check each item status in a batch.

Update the same document and create a version

POST to the same api_nts.php with accion: "actualizar" and the doc_Id returned at creation. Alternatively use id, the global integer DeCA ID, not numeroEmpresa. If both identifiers are supplied, they must identify the same document.

Content-Type: application/json
X-Api-Key: YOUR_COMPANY_API_KEY
Idempotency-Key: ERP-TRANSPORT-001-CHANGE-02

{
  "accion": "actualizar",
  "doc_Id": "00000000-0000-4000-8000-000000000001",
  "versionEsperada": 1,
  "vehiculo": {
    "matriculaTractora": "9876XYZ",
    "matriculaRemolque": "R5678BCD"
  },
  "observaciones": "Details corrected by the ERP"
}

Replace the example GUID with the real one. The ID, GUID, numbering, public URL and QR code remain unchanged. Changes to a dated trip generate the next PDF version (v2, v3...) and an audit entry without overwriting earlier PDFs. Already replaced documents cannot be updated.

Omitted fields retain their values. Within vehiculo, send only the properties that change.
If you send grupos, include the complete list of origins, destinations and goods lines to retain: it replaces the previous list. The same applies to conductores. Each list item follows the creation schema.
Send complete transportista or cargador objects when changing them. For the consignor, {"idCliente": 42} is also supported; null selects the account holder again.
Use fechaTransporte: null or null registrations to leave them pending. Without a date, data and audit history are saved, but no new PDF is issued.
Optional versionEsperada returns 409 if it differs from the latest stored PDF version, helping prevent overwriting unreviewed changes.
Do not use documentoOrigenId when updating: it is reserved for replacements. numeroDocumento cannot change.

Update response and retries

HTTP 200 includes the usual fields, including idDeca, plus the update fields numVersion, cambiado and pdfDisponible. If nothing changes, cambiado is false and no version is added. If the trip has no date, numVersion is null and pdfDisponible is false.

Use a new Idempotency-Key for every change, different from the creation key. Retry that change using the same key and JSON to receive its original response with repetido: true, without another version or undoing later changes. Reusing a key with different data returns 409. Without a key, only current values are compared, so late-retry protection is not guaranteed.

Batches can mix creation and updates, with the action specified per item. NTS Swagger includes actualizar and actualizarMercancias examples.

Replace a document

Send the complete corrected document with documentoOrigenId equal to the doc_Id of the current NTS document and a new idempotency key. It must belong to the same company. The numeroDocumento is retained and a new GUID and URL are generated; the previous link shows a notice linking to the current document.

Each document allows one direct replacement. To correct it again using the NTS API, provide the GUID of the currently valid document.

Edit on the website

Authorized users can select Edit in the list to edit a complete NTS DeCA: consignor, carrier, drivers, contacts, date, registrations, origins, destinations and goods, including packages and pallets. The date and registrations can be left pending. The ID, GUID and URL are retained; changes with a date generate a new PDF version. Previous versions and the responsible user are recorded in the history.

Queries using api.php and api_repartos.php return the current data in their respective schemas. Web changes are not pushed automatically to the ERP: it must query the document again. Original request fingerprints are retained so a NTS retry does not overwrite web edits. Writes through the standard-format APIs remain restricted to that format; for NTS, use its web editor or api_nts.php with accion: actualizar. Replacement remains a separate operation.

Notification status

The requested channel is stored and the response returns NO_CONFIGURADO for that channel; this does not confirm message delivery. The integrator can send urlAcceso using its own system.

Independently, if the assigned driver has an email address and NotificarEmail enabled in their record, DECA can email a notification using the company configuration. Check deliveries under Sent emails. This endpoint does not automatically send SMS, WhatsApp or Telegram messages.