Zollmax

  • +49.211.882.40.294
  • info@zollmax.com
Zollmax NCTS
Zollmax NCTS API Dokumentation

Zollmax NCTS API Dokumentation

Vereinfachen Sie Ihre Zollversandverfahren. Verwalten Sie Ihre NCTS-Daten mit einer sicheren, schnellen und umfassenden API.

API Reference Postman Collection

API Reference

Ausführliche Dokumentation aller API-Endpunkte

JWT-Token für den API-Zugriff abrufen

POST https://zollmax.com/api/v1/login

Request Body

{
  "email": "user@example.com",
  "password": "Password"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjo3OCwiZXhwIjoxNjQ1NzA3MTMyfQ.ipp2TR9UEtpvZ9eF4ng-e3GWEaElX5NayxgyNPpt8jQ",
  "user_id": 78,
  "expires_at": "2024-12-31T23:59:59Z"
}

NCTS-Daten im JSON-Format übermitteln

POST https://zollmax.com/api/v1/ncts_declarations/json

Request Body

Vollständiges JSON-Beispiel
{
  "doc_type": "T1",
  "doc_date": "2022-01-27",
  "vehicle_code": null,
  "vehicle_coun": "GB",
  "trailer_code": "TEST123",
  "trailer_coun": "GB",
  "border_cross_vehicle": "",
  "container": "",
  "seal_info": null,
  "security": true,
  "tanker": false,
  "is_aeo": false,
  "aeo_location": null,
  "transit_date": null,
  "departure_custom_code": "GB000060",
  "dispatch_country_id": "GB",
  "load_place": "GB London",
  "goods_location": "",
  "arrival_custom_code": "DE007430",
  "destination_country_id": "DE",
  "unload_place": "DE",
  "border_custom_code": null,
  "transit_customs_codes": "FR620001",
  "transit_countries_codes": "GB,FR,BE,NL,DE",
  "carrier_name": "TEST TRANSPORT",
  "carrier_address": "Some Address",
  "carrier_postcode": "11111",
  "carrier_city": "London",
  "carrier_country_id": "GB",
  "carrier_taxno": null,
  "carrier_eori_code": null,
  "trans_method": "road",
  "roro_operator_code": null,
  "guarantee_price": "0.0",
  "guarantee_curr": null,
  "status": "draft",
  "lrn_no": null,
  "lrn": null,
  "mrn": null,
  "mrn_no": null,
  "lrn_url": "https://zollmax.com/ncts_declarations/500072/preview.pdf",
  "manifesto_price": "0.0",
  "manifesto_curr": null,
  "position_no": "",
  "remote_ref": "TestRef001",
  "notes": null,
  "goods_attributes": [
    {
      "line_no": 1,
      "gtip_code": "69109000",
      "commodity": "Construction equipments",
      "brut_wg": 19199.96,
      "net_wg": 16721.82,
      "invoice_amount": "18906.0",
      "invoice_curr": "EUR",
      "exp_customs_type": null,
      "exp_customs_partial": null,
      "exp_customs_no": "21GB000X1234567890",
      "manifesto_type": null,
      "dep_country_id": "GB",
      "arv_country_id": "DE",
      "sender_taxno": null,
      "sender_name": "GB EXPORTER TEST 2",
      "sender_address": "Test consignor address 2",
      "sender_postcode": "11111",
      "sender_city": "London",
      "sender_country_id": "GB",
      "sender_eori_code": null,
      "consignee_taxno": "",
      "consignee_name": "DE IMPORTER TEST",
      "consignee_address": "Test consignee address",
      "consignee_postcode": "50678",
      "consignee_city": "KOLN",
      "consignee_country_id": "DE",
      "consignee_eori_code": null,
      "packs_attributes": [
        {
          "pack_type": "BI",
          "pack_count": "62",
          "notes": "As Addressed"
        }
      ],
      "documents_attributes": [
        {
          "doc_type": "380",
          "doc_no": "Invoice 123",
          "pre_post": "A"
        }
      ]
    },
    {
      "line_no": 2,
      "gtip_code": "69109000",
      "commodity": "Other construction equipments",
      "brut_wg": 19199.96,
      "net_wg": 16721.82,
      "invoice_amount": "20000.0",
      "invoice_curr": "EUR",
      "dep_country_id": "GB",
      "arv_country_id": "DE",
      "sender_name": "GB EXPORTER TEST 2",
      "sender_address": "Test consignor address 2",
      "sender_postcode": "11111",
      "sender_city": "London",
      "sender_country_id": "GB",
      "sender_eori_code": null,
      "consignee_taxno": null,
      "consignee_name": "DE IMPORTER TEST 2",
      "consignee_address": "Test consignee address 2",
      "consignee_postcode": "50678",
      "consignee_city": "KOLN",
      "consignee_country_id": "DE",
      "consignee_eori_code": null,
      "packs_attributes": [
        {
          "pack_type": "BI",
          "pack_count": "62",
          "notes": "As Addressed"
        }
      ],
      "documents_attributes": [
        {
          "doc_type": "730",
          "doc_no": "CMR002",
          "pre_post": "A"
        },
        {
          "doc_type": "380",
          "doc_no": "Invoice 1234",
          "pre_post": "A"
        },
        {
          "doc_type": "830",
          "doc_no": "21GB000X1234567891",
          "pre_post": "A"
        }
      ]
    }
  ]
}
Feldbeschreibungen
Dokumentangaben
doc_type string

Dokumentart (T1, T2 usw.)

Beispiel: T1
doc_date string

Erstellungsdatum des Dokuments

Beispiel: 2022-01-27
status string

Aktueller Status des Dokuments

Beispiel: draft
remote_ref string

Externe Referenznummer

Beispiel: TestRef001
Fahrzeugangaben
vehicle_code string

Amtliches Kennzeichen des Fahrzeugs

Beispiel: null
vehicle_coun string

Ländercode des Fahrzeugs

Beispiel: GB
trailer_code string

Amtliches Kennzeichen des Anhängers

Beispiel: TEST123
trans_method string

Beförderungsart

Beispiel: road
Streckenangaben
departure_custom_code string

Code der Abgangszollstelle

Beispiel: GB000060
arrival_custom_code string

Code der Bestimmungszollstelle

Beispiel: DE007430
transit_countries_codes string

Durchfuhrländer (durch Komma getrennt)

Beispiel: GB,FR,BE,NL,DE
Angaben zum Frachtführer
carrier_name string

Firmenname des Frachtführers

Beispiel: TEST TRANSPORT
carrier_address string

Anschrift des Frachtführers

Beispiel: Some Address
Warenangaben
goods_attributes array

Array der Warenpositionen

Beispiel: [...]
gtip_code string

HS-/GTIP-Warennummer

Beispiel: 69109000
commodity string

Warenbezeichnung

Beispiel: Construction equipments
brut_wg number

Bruttogewicht (kg)

Beispiel: 19199.96

Response

{
  "status": "success",
  "reference_number": "MNF230000212",
  "message": "NCTS data processed successfully"
}

NCTS-Daten im XML-Format übermitteln

POST https://zollmax.com/api/v1/ncts_declarations/xml

Request Body

{
  "manifesto": {
    "ncts_data": "<BG015B><MesSenMES3>TRA.APP</MesSenMES3><SenIdeCodQuaMES4>BGC201593324ZZZZ7</SenIdeCodQuaMES4></BG015B>"
  }
}

Response

{
  "status": "success",
  "reference_number": "MNF230000212",
  "message": "NCTS data processed successfully"
}

Status einer bestimmten NCTS-Referenznummer abfragen

GET https://zollmax.com/api/v1/ncts_declarations/{reference_number}

Response

{
  "reference_number": "22TR34130001564240",
  "status": "in_transit",
  "current_location": "Istanbul Port",
  "estimated_arrival": "2024-01-15T14:30:00Z"
}

Liste aller NCTS-Datensätze abrufen

GET https://zollmax.com/api/v1/ncts_declarations

Response

{
  "data": [
    {
      "reference_number": "22TR34130001564240",
      "status": "in_transit",
      "created_at": "2024-01-10T09:00:00Z"
    }
  ],
  "total": 1,
  "page": 1
}

Vom System gesendete ungelesene Nachrichten abrufen

GET https://zollmax.com/api/v1/messages/unread

Response

{
  "messages": [
    {
      "id": 1,
      "type": "status_update",
      "message": "Your shipment has arrived at destination",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 1
}

NCTS-Dokumente im PDF-Format herunterladen

GET https://zollmax.com/api/v1/ncts_declarations/{reference_number}/pdf

Response

{
  "message": "PDF file download will start",
  "download_url": "https://zollmax.com/downloads/MNF230000212.pdf"
}

Postman Collection

Sofort einsatzbereite Postman-Collection zum Testen der API

Zollmax NCTS API Collection

7 Endpunkte mit Authentifizierung und Beispielen

Enthaltene Endpunkte:

  • Get Authentication Token
  • Submit NCTS JSON Data
  • Submit NCTS XML Data
  • Get NCTS Status

 

  • Get NCTS List
  • Get Unread Messages
  • Get PDF Document

Nutzungshinweise:

  1. 1. Importieren Sie die Collection in Postman
  2. 2. Führen Sie zuerst die Anfrage „Get Authentication Token“ aus
  3. 3. Das Token wird automatisch für die weiteren Anfragen gespeichert
  4. 4. Testen Sie die übrigen Endpunkte mit dem authentifizierten Token

Fehlercodes

HTTP-Statuscodes, die in API-Antworten auftreten können, sowie Lösungsvorschläge

200 OK

Anfrage erfolgreich verarbeitet

Lösung:

Der normale Prozessablauf wird fortgesetzt

400 Bad Request

Ungültige Anfrageparameter oder ungültiges Datenformat

Lösung:

Prüfen Sie die Anfragedaten und verwenden Sie das korrekte Format

401 Unauthorized

Ungültiges oder fehlendes Authentifizierungs-Token

Lösung:

Melden Sie sich an und verwenden Sie ein gültiges Bearer-Token

404 Not Found

Angeforderte Ressource nicht gefunden

Lösung:

Prüfen Sie die URL und die Ressourcenverweise

422 Unprocessable Entity

Das Datenformat ist korrekt, entspricht aber nicht den Geschäftsregeln

Lösung:

Prüfen Sie die NCTS-Datenstruktur und die Pflichtfelder

429 Too Many Requests

Anfragelimit überschritten

Lösung:

Verringern Sie die Anfragehäufigkeit und versuchen Sie es erneut

500 Internal Server Error

Unerwarteter serverseitiger Fehler

Lösung:

Versuchen Sie es später erneut oder wenden Sie sich an das Support-Team

503 Service Unavailable

Dienst vorübergehend nicht verfügbar

Lösung:

Das System wird möglicherweise gewartet – versuchen Sie es später erneut