Oregon Teknoloji Hizmetleri

Oregon NCTS API Dokümantasyonu

Oregon NCTS API Dokümantasyon

Gümrük transit işlemlerinizi kolaylaştırın. Güvenli, hızlı ve kapsamlı API ile NCTS verilerinizi yönetin.

API Referansı

Tüm API endpoint'lerin detaylı dokümantasyonu

API erişimi için JWT token alın

POST https://ncts.oregon.com.tr/api/v1/login

İstek Gövdesi

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

Yanıt

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

JSON formatında NCTS verisi gönderin

POST https://ncts.oregon.com.tr/api/v1/manifestos/json

İstek Gövdesi

Tam JSON Örneği
{
  "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/manifestos/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"
        }
      ]
    }
  ]
}
Alan Açıklamaları
Belge Bilgileri
doc_type string

Belge türü (T1, T2, vb.)

Örnek: T1
doc_date string

Belge oluşturma tarihi

Örnek: 2022-01-27
status string

Mevcut belge durumu

Örnek: draft
remote_ref string

Harici referans numarası

Örnek: TestRef001
Araç Bilgileri
vehicle_code string

Araç plaka numarası

Örnek: null
vehicle_coun string

Araç ülke kodu

Örnek: GB
trailer_code string

Römork plaka numarası

Örnek: TEST123
trans_method string

Taşıma yöntemi

Örnek: road
Rota Bilgileri
departure_custom_code string

Çıkış gümrük ofisi kodu

Örnek: GB000060
arrival_custom_code string

Varış gümrük ofisi kodu

Örnek: DE007430
transit_countries_codes string

Transit ülkeler (virgülle ayrılmış)

Örnek: GB,FR,BE,NL,DE
Taşıyıcı Bilgileri
carrier_name string

Taşıyıcı şirket adı

Örnek: TEST TRANSPORT
carrier_address string

Taşıyıcı adresi

Örnek: Some Address
Mal Bilgileri
goods_attributes array

Mal kalemleri dizisi

Örnek: [...]
gtip_code string

HS/GTIP emtia kodu

Örnek: 69109000
commodity string

Mal açıklaması

Örnek: Construction equipments
brut_wg number

Brüt ağırlık (kg)

Örnek: 19199.96

Yanıt

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

XML formatında NCTS verisi gönderin

POST https://ncts.oregon.com.tr/api/v1/manifestos/xml

İstek Gövdesi

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

Yanıt

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

Belirli bir NCTS referans numarasının durumunu sorgulayın

GET https://ncts.oregon.com.tr/api/v1/manifestos/{reference_number}

Yanıt

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

Tüm NCTS kayıtlarının listesini alın

GET https://ncts.oregon.com.tr/api/v1/manifestos

Yanıt

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

Sistem tarafından gönderilen okunmamış mesajları alın

GET https://ncts.oregon.com.tr/api/v1/messages/unread

Yanıt

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

NCTS belgelerini PDF formatında indirin

GET https://ncts.oregon.com.tr/api/v1/manifestos/{reference_number}/pdf

Yanıt

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

Postman Koleksiyonu

API testleri için hazır Postman koleksiyonu

Oregon NCTS API Koleksiyonu

7 endpoint ile kimlik doğrulama ve örnekler

Dahil Edilen Endpoint'ler:

  • Kimlik Doğrulama Token'ı Al
  • NCTS JSON Verisi Gönder
  • NCTS XML Verisi Gönder
  • NCTS Durumu Al

 

  • NCTS Listesi Al
  • Okunmamış Mesajları Al
  • PDF Döküman Al

Kullanım Talimatları:

  1. 1. Koleksiyonu Postman'a aktarın
  2. 2. Önce "Kimlik Doğrulama Token'ı Al" isteğini çalıştırın
  3. 3. Token otomatik olarak diğer istekler için kaydedilecek
  4. 4. Kimlik doğrulamalı token ile diğer endpoint'leri test edin

Hata Kodları

API yanıtlarında karşılaşabileceğiniz HTTP durum kodları ve çözüm önerileri

200 OK

İstek başarıyla işlendi

Çözüm:

Normal işlem akışı devam eder

400 Bad Request

Geçersiz istek parametreleri veya veri formatı

Çözüm:

İstek verilerini kontrol edin ve doğru format kullanın

401 Unauthorized

Geçersiz veya eksik kimlik doğrulama token'ı

Çözüm:

Giriş yapın ve geçerli bir Bearer token kullanın

404 Not Found

İstenen kaynak bulunamadı

Çözüm:

URL ve kaynak referanslarını kontrol edin

422 Unprocessable Entity

Veri formatı doğru ancak iş kurallarına uygun değil

Çözüm:

NCTS veri yapısını ve zorunlu alanları kontrol edin

429 Too Many Requests

Rate limit aşıldı

Çözüm:

İstek sıklığını azaltın ve yeniden deneyin

500 Internal Server Error

Sunucu tarafında beklenmeyen hata

Çözüm:

Daha sonra tekrar deneyin veya destek ekibiyle iletişime geçin

503 Service Unavailable

Servis geçici olarak kullanılamıyor

Çözüm:

Sistem bakımda olabilir, daha sonra tekrar deneyin

Yardım lazım mı?