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"
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', '{{BASE_URL}}/api/v1/consignment-documents', [
'headers' => [
'APIKEY' => '{{APIKEY}}'
],
'multipart' => [
[
'name' => 'document_file',
'contents' => fopen('/path/to/e-arsiv-fatura.pdf', 'r'),
'filename' => 'e-arsiv-fatura.pdf'
],
[
'name' => 'document_type',
'contents' => '1'
],
[
'name' => 'status',
'contents' => '1'
],
[
'name' => 'document_reference',
'contents' => 'GIB2024000012345'
],
[
'name' => 'document_issued_at',
'contents' => '2024-12-17T10:30:00+03:00'
]
]
]);
$body = json_decode($response->getBody(), true);
// Döküman ID'sini saklayın - gönderi oluştururken kullanılacak
$documentId = $body['data']['id'];
print_r($body);
<?php
$ch = curl_init();
$postFields = [
'document_file' => new CURLFile(
'/path/to/e-arsiv-fatura.pdf',
'application/pdf',
'e-arsiv-fatura.pdf'
),
'document_type' => 1,
'status' => 1,
'document_reference' => 'GIB2024000012345',
'document_issued_at' => '2024-12-17T10:30:00+03:00'
];
curl_setopt_array($ch, [
CURLOPT_URL => '{{BASE_URL}}/api/v1/consignment-documents',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $postFields,
CURLOPT_HTTPHEADER => [
'APIKEY: {{APIKEY}}'
]
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch)) {
echo 'Hata: ' . curl_error($ch);
} else {
$result = json_decode($response, true);
// Döküman ID'sini saklayın - gönderi oluştururken kullanılacak
$documentId = $result['data']['id'];
print_r($result);
}
curl_close($ch);
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("APIKEY", "{{APIKEY}}");
using var content = new MultipartFormDataContent();
// Dosya ekle
var fileContent = new ByteArrayContent(File.ReadAllBytes("/path/to/e-arsiv-fatura.pdf"));
fileContent.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/pdf");
content.Add(fileContent, "document_file", "e-arsiv-fatura.pdf");
// Diğer parametreler
content.Add(new StringContent("1"), "document_type");
content.Add(new StringContent("1"), "status");
content.Add(new StringContent("GIB2024000012345"), "document_reference");
content.Add(new StringContent("2024-12-17T10:30:00+03:00"), "document_issued_at");
var response = await client.PostAsync("{{BASE_URL}}/api/v1/consignment-documents", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
const form = new FormData();
form.append('document_file', fs.createReadStream('/path/to/e-arsiv-fatura.pdf'));
form.append('document_type', '1');
form.append('status', '1');
form.append('document_reference', 'GIB2024000012345');
form.append('document_issued_at', '2024-12-17T10:30:00+03:00');
const response = await axios.post(
'{{BASE_URL}}/api/v1/consignment-documents',
form,
{
headers: {
...form.getHeaders(),
'APIKEY': '{{APIKEY}}'
}
}
);
// Döküman ID'sini saklayın - gönderi oluştururken kullanılacak
const documentId = response.data.data.id;
console.log(response.data);
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.nio.file.Files;
import java.nio.file.Path;
HttpClient client = HttpClient.newHttpClient();
String boundary = "----WebKitFormBoundary" + System.currentTimeMillis();
Path filePath = Path.of("/path/to/e-arsiv-fatura.pdf");
byte[] fileBytes = Files.readAllBytes(filePath);
String body = "--" + boundary + "\r\n" +
"Content-Disposition: form-data; name=\"document_file\"; filename=\"e-arsiv-fatura.pdf\"\r\n" +
"Content-Type: application/pdf\r\n\r\n" +
new String(fileBytes) + "\r\n" +
"--" + boundary + "\r\n" +
"Content-Disposition: form-data; name=\"document_type\"\r\n\r\n1\r\n" +
"--" + boundary + "\r\n" +
"Content-Disposition: form-data; name=\"status\"\r\n\r\n1\r\n" +
"--" + boundary + "\r\n" +
"Content-Disposition: form-data; name=\"document_reference\"\r\n\r\nGIB2024000012345\r\n" +
"--" + boundary + "\r\n" +
"Content-Disposition: form-data; name=\"document_issued_at\"\r\n\r\n2024-12-17T10:30:00+03:00\r\n" +
"--" + boundary + "--";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("{{BASE_URL}}/api/v1/consignment-documents"))
.header("Content-Type", "multipart/form-data; boundary=" + boundary)
.header("APIKEY", "{{APIKEY}}")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = client.send(
request,
HttpResponse.BodyHandlers.ofString()
);
System.out.println(response.body());
package main
import (
"bytes"
"fmt"
"io"
"mime/multipart"
"net/http"
"os"
)
func main() {
file, _ := os.Open("/path/to/e-arsiv-fatura.pdf")
defer file.Close()
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
// Dosya ekle
part, _ := writer.CreateFormFile("document_file", "e-arsiv-fatura.pdf")
io.Copy(part, file)
// Diğer parametreler
writer.WriteField("document_type", "1")
writer.WriteField("status", "1")
writer.WriteField("document_reference", "GIB2024000012345")
writer.WriteField("document_issued_at", "2024-12-17T10:30:00+03:00")
writer.Close()
req, _ := http.NewRequest(
"POST",
"{{BASE_URL}}/api/v1/consignment-documents",
body,
)
req.Header.Set("Content-Type", writer.FormDataContentType())
req.Header.Set("APIKEY", "{{APIKEY}}")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
fmt.Println(string(respBody))
}
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