API integration · Version 1.2

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.

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.

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 and replacement, not cancellation without a replacement.

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. Other units are configured per company in administration. 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.

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.

Responses, retries and batches

The response includes numeroEmpresa, the automatic DeCA number within the company. It is separate from doc_Id and numeroDocumento. A replacement retains numeroDocumento, but the new DeCA receives another numeroEmpresa. Idempotent retries return the number already assigned.

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

{
  "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 (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.

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.

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 replacement through api_nts.php.

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.