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
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
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
stringBelge türü (T1, T2, vb.)
T1
doc_date
stringBelge oluşturma tarihi
2022-01-27
status
stringMevcut belge durumu
draft
remote_ref
stringHarici referans numarası
TestRef001
Araç Bilgileri
vehicle_code
stringAraç plaka numarası
null
vehicle_coun
stringAraç ülke kodu
GB
trailer_code
stringRömork plaka numarası
TEST123
trans_method
stringTaşıma yöntemi
road
Rota Bilgileri
departure_custom_code
stringÇıkış gümrük ofisi kodu
GB000060
arrival_custom_code
stringVarış gümrük ofisi kodu
DE007430
transit_countries_codes
stringTransit ülkeler (virgülle ayrılmış)
GB,FR,BE,NL,DE
Taşıyıcı Bilgileri
carrier_name
stringTaşıyıcı şirket adı
TEST TRANSPORT
carrier_address
stringTaşıyıcı adresi
Some Address
Mal Bilgileri
goods_attributes
arrayMal kalemleri dizisi
[...]
gtip_code
stringHS/GTIP emtia kodu
69109000
commodity
stringMal açıklaması
Construction equipments
brut_wg
numberBrüt ağırlık (kg)
19199.96
Yanıt
{
"status": "success",
"reference_number": "MNF230000212",
"message": "NCTS data processed successfully"
}
XML formatında NCTS verisi gönderin
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
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
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
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
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. Koleksiyonu Postman'a aktarın
- 2. Önce "Kimlik Doğrulama Token'ı Al" isteğini çalıştırın
- 3. Token otomatik olarak diğer istekler için kaydedilecek
- 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
İstek başarıyla işlendi
Çözüm:
Normal işlem akışı devam eder
Geçersiz istek parametreleri veya veri formatı
Çözüm:
İstek verilerini kontrol edin ve doğru format kullanın
Geçersiz veya eksik kimlik doğrulama token'ı
Çözüm:
Giriş yapın ve geçerli bir Bearer token kullanın
İstenen kaynak bulunamadı
Çözüm:
URL ve kaynak referanslarını kontrol edin
Veri formatı doğru ancak iş kurallarına uygun değil
Çözüm:
NCTS veri yapısını ve zorunlu alanları kontrol edin
Rate limit aşıldı
Çözüm:
İstek sıklığını azaltın ve yeniden deneyin
Sunucu tarafında beklenmeyen hata
Çözüm:
Daha sonra tekrar deneyin veya destek ekibiyle iletişime geçin
Servis geçici olarak kullanılamıyor
Çözüm:
Sistem bakımda olabilir, daha sonra tekrar deneyin