Döküman Yükleme

Bu endpoint, sisteme sevkiyat evrakı (consignment document) yüklemek için kullanılır. Yüklenen dökümanlar gönderi oluşturulurken documents parametresi ile ilişkilendirilebilir.

Endpoint Bilgileri

Özellik Değer
URL {{BASE_URL}}/api/v1/consignment-documents
HTTP Metodu POST
İçerik Türü multipart/form-data
Kimlik Doğrulama APIKEY header

Ne Zaman Kullanılır?

Senaryo Açıklama
Mikro İhracat (ETGB) post_type: 2 gönderilerinde e-arşiv fatura yüklemesi zorunludur
Satış Gönderileri post_type: 4 gönderilerinde e-arşiv fatura yüklemesi zorunludur
Gümrük Evrakları Proforma fatura, menşe şahadetnamesi vb. belgeler
Özel Dökümanlar MSDS, FDA, TSCA gibi ürün bazlı gerekli belgeler

Önemli: Mikro ihracat (post_type: 2) ve satış (post_type: 4) gönderilerinde e-arşiv fatura yüklemeden gönderi oluşturmaya çalışırsanız, kargo firması gönderinizi reddedebilir.


İstek Parametreleri

Parametre Tip Zorunluluk Açıklama
document_file File ZORUNLU Yüklenecek dosya. Maksimum 4MB. Desteklenen formatlar: PDF, JPEG, PNG
document_type Integer ZORUNLU Evrak tipi. Kullanılabilir Değerler
status Integer ZORUNLU Döküman durumu. Kullanılabilir Değerler
consignment_id Integer OPSİYONEL Mevcut bir gönderiye bağlamak için gönderi ID'si
document_reference String ÖNERİLEN Döküman referans numarası (E-Arşiv No, Fatura No vb.)
document_issued_at DateTime ÖNERİLEN Döküman düzenlenme tarihi (ISO 8601 formatı)

Döküman Tipleri

Değer Kod Açıklama
1 INVOICE Fatura / E-Arşiv Fatura
2 PACKING_LIST Paketleme Listesi
3 CUSTOMS_FORM Gümrük Formu
4 MSDS Malzeme Güvenlik Bilgi Formu
5 FDA FDA Belgesi
6 TSCA TSCA Belgesi
7 OTHER Diğer
8 PROFORMA Proforma Fatura
9 BILL_OF_LADING Nakliye Evrakı / Konşimento
10 CN22 Gümrük Beyannamesi (CN22)
11 CN23 Gümrük Beyannamesi (CN23)
12 COO Menşe Şahadetnamesi
13 ETD Elektronik Ticaret Belgesi

Döküman Durumları

Değer Kod Açıklama
0 IN_REVIEW Onay bekliyor
1 APPROVED Onaylandı
2 REJECTED Reddedildi

Not: Mikro ihracat için e-arşiv fatura yüklerken status: 1 (Onaylı) kullanın.


Örnek Kullanım

Mikro İhracat için E-Arşiv Fatura Yükleme

curl -X POST "{{BASE_URL}}/api/v1/consignment-documents" \
  -H "APIKEY: {{APIKEY}}" \
  -F "document_file=@/path/to/e-arsiv-fatura.pdf" \
  -F "document_type=1" \
  -F "status=1" \
  -F "document_reference=GIB2024000012345" \
  -F "document_issued_at=2024-12-17T10:30:00+03:00"

API Cevabı

Başarılı Yanıt

{
    "status": true,
    "message": "Consignment document created successfully",
    "data": {
        "id": 12345,
        "fileName": "e-arsiv-fatura.pdf",
        "fileSize": 102400,
        "mimeType": "application/pdf",
        "status": 1,
        "documentType": 1,
        "documentReference": "GIB2024000012345",
        "documentIssuedAt": "2024-12-17T10:30:00+03:00",
        "consignment": null
    }
}

Response Alanları

Alan Tip Açıklama
id Integer Döküman ID'si. Gönderi oluştururken bu değeri kullanın
fileName String Yüklenen dosya adı
fileSize Integer Dosya boyutu (byte)
mimeType String Dosya MIME tipi
status Integer Döküman durumu
documentType Integer Döküman tipi
documentReference String Döküman referans numarası
documentIssuedAt String Döküman düzenlenme tarihi
consignment Object/null İlişkili gönderi (varsa)

Gönderi ile İlişkilendirme

Yüklediğiniz dökümanı gönderi oluştururken kullanmak için, API yanıtında dönen id değerini documents dizisine ekleyin:

{
    "provider_id": 7,
    "preference": 0,
    "address_resolver_type": 0,
    "consignor": { ... },
    "consignee": { ... },
    "packages": [
        {
            "package_type": 1,
            "post_type": 2,
            ...
        }
    ],
    "documents": [
        {
            "id": 12345
        }
    ]
}

Birden fazla döküman: Birden fazla döküman eklemek için documents dizisine birden fazla obje ekleyebilirsiniz.


Hata Yanıtları

Dosya Eksik

{
    "status": false,
    "errors": [
        {
            "message": "documentFile:This value should not be null.",
            "code": 400
        }
    ]
}

Dosya Boyutu Aşımı

{
    "status": false,
    "errors": [
        {
            "message": "The file is too large. Allowed maximum size is 4 MB.",
            "code": 400
        }
    ]
}

Geçersiz Dosya Formatı

{
    "status": false,
    "errors": [
        {
            "message": "The mime type of the file is invalid. Allowed types are: application/pdf, image/jpeg, image/png.",
            "code": 400
        }
    ]
}

Önemli Notlar

Konu Açıklama
Dosya Saklama Süresi consignment_id belirtilmeden yüklenen dosyalar 3 gün içinde bir gönderi ile ilişkilendirilmezse otomatik silinir
Dosya Boyutu Maksimum 4 MB
Desteklenen Formatlar PDF, JPEG, PNG
E-Arşiv Fatura Mikro ihracat (post_type: 2) ve satış (post_type: 4) için document_type: 1, status: 1 kullanın
Referans Bilgileri document_reference ve document_issued_at alanları kargo firmasına iletilir

İlgili Endpointler