Zollmax

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

Zollmax NCTS API Documentation

Simplify your customs transit operations. Manage your NCTS data with secure, fast and comprehensive API.

API Reference Postman Collection

API Reference

Detailed documentation for all API endpoints

Get JWT token for API access

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"
}

Submit NCTS data in JSON format

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

Request Body

Complete JSON Example
{
  "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"
        }
      ]
    }
  ]
}
Field Descriptions
Document Information
doc_type string

Document type (T1, T2, etc.)

Example: T1
doc_date string

Document creation date

Example: 2022-01-27
status string

Current document status

Example: draft
remote_ref string

External reference number

Example: TestRef001
Vehicle Information
vehicle_code string

Vehicle registration number

Example: null
vehicle_coun string

Vehicle country code

Example: GB
trailer_code string

Trailer registration number

Example: TEST123
trans_method string

Transport method

Example: road
Route Information
departure_custom_code string

Departure customs office code

Example: GB000060
arrival_custom_code string

Arrival customs office code

Example: DE007430
transit_countries_codes string

Transit countries (comma separated)

Example: GB,FR,BE,NL,DE
Carrier Information
carrier_name string

Carrier company name

Example: TEST TRANSPORT
carrier_address string

Carrier address

Example: Some Address
Goods Information
goods_attributes array

Array of goods items

Example: [...]
gtip_code string

HS/GTIP commodity code

Example: 69109000
commodity string

Goods description

Example: Construction equipments
brut_wg number

Gross weight (kg)

Example: 19199.96

Response

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

Submit NCTS data in XML format

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"
}

Query the status of a specific NCTS reference number

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"
}

Get a list of all NCTS records

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
}

Get unread messages sent by the system

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
}

Download NCTS documents in PDF format

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

Ready-to-use Postman collection for API testing

Zollmax NCTS API Collection

7 endpoints with authentication and examples

Included Endpoints:

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

 

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

Usage Instructions:

  1. 1. Import the collection into Postman
  2. 2. First run the "Get Authentication Token" request
  3. 3. Token will be automatically saved for other requests
  4. 4. Test other endpoints with the authenticated token

Error Codes

HTTP status codes you may encounter in API responses and resolution suggestions

200 OK

Request processed successfully

Solution:

Normal process flow continues

400 Bad Request

Invalid request parameters or data format

Solution:

Check request data and use correct format

401 Unauthorized

Invalid or missing authentication token

Solution:

Login and use a valid Bearer token

404 Not Found

Requested resource not found

Solution:

Check URL and resource references

422 Unprocessable Entity

Data format is correct but doesn't comply with business rules

Solution:

Check NCTS data structure and required fields

429 Too Many Requests

Rate limit exceeded

Solution:

Reduce request frequency and try again

500 Internal Server Error

Unexpected server-side error

Solution:

Try again later or contact support team

503 Service Unavailable

Service temporarily unavailable

Solution:

System may be under maintenance, try again later