Belge yükleme

Sisteminiz, şirketinizin taraf olduğu bir anlaşmanın belge kasasına belge yükleyebilir. Yükleme uygulamanın kendi yüklemesinden geçer: aynı boyut sınırı, aynı dosya denetimleri, saklanmadan önce aynı virüs taraması, her taraf için aynı kurallar; karşı taraf da aynı şekilde haberdar edilir.

documents:write kapsamı (belge kasasını okumak ayrı bir yetkidir, documents:read) ve bir X-Idempotency-Key gerekir.

Çağrı

POST /deals/{id}/documents, iki alanlı bir multipart/form-data alır: dosya file alanında, kategorisi category alanında.

curl "https://app.quatlasglobal.com/api/integrations/v1/deals/<anlaşma-kimliği>/documents" \
  -H "Authorization: Bearer $QUATLAS_KEY" \
  -H "X-Idempotency-Key: EBA-2026-000123-invoice" \
  -F "category=CommercialInvoice" \
  -F "[email protected];type=application/pdf"

{
  "id": "<belge-kimliği>",
  "dealId": "<anlaşma-kimliği>",
  "category": "CommercialInvoice",
  "fileName": "fatura.pdf",
  "contentType": "application/pdf",
  "sizeBytes": 184213,
  "uploadedAt": "2026-10-15T13:20:05Z",
  "uploadedBySide": "Shipper",
  "scanStatus": "Clean",
  "livemode": true
}

Yeni belge GET /deals/{id}/documents listesinde görünür ve GET /documents/{id}/download ile indirilir.

Dosya

En fazla 25 MB. Daha büyük dosya 413 (Document.PayloadTooLarge) döner.
PDF, JPEG, PNG, DOCX ya da XLSX; türü parçanın içerik türünde bildirilir. Dosyanın içeriği bu türe uymalıdır: ilk baytları, DOCX ve XLSX’te de paketi, Office’in okuduğu gibi (kök ilişkilerinin gösterdiği ana parça; Word, Excel, LibreOffice ve Google dışa aktarımları geçer; kök ilişkileri olmayan ya da 5.000’den fazla girdisi olan bir ZIP, klasörlerinin adı ne olursa olsun, geçmez). XLSX diye gönderilen bir Word belgesi ya da DOCX diye gönderilen bir çalışma kitabı olduğu şey olarak saklanır: yanıttaki contentType gerçek türdür ve fileName o türün uzantısını taşır (Word belgesi taşıyan list.xlsx, list.docx olarak saklanır). Söylediği şey olmayan dosya 415 (Document.UnsupportedMediaType) döner; detail dosyanın ne olduğunu söyler. Arşivler (ZIP, RAR, …) dahil başka her tür de aynı şekilde reddedilir.
Boş olmamalı. Dosya yoksa ya da boşsa 400 (Document.FileRequired) döner.

Virüs taraması

Her dosya, uygulamadaki gibi, saklanmadan önce taranır. Taramadan geçemeyen dosya 422 (Document.Infected) ile reddedilir ve hiç saklanmaz; tarayıcı yanıt veremezse yükleme taranmadan saklanmaz, 503 (Document.ScanUnavailable) ile reddedilir. Bu yüzden kabul edilen belge her zaman Clean’dir: beklenecek bir ara durum yoktur, 201 taramanın sonucudur.

Kategoriler: taraf ve aşamaya göre

category, uygulamanın belge kategorilerinden birinin adıdır; büyük küçük harf fark etmez. Tarafınızın hangilerini yükleyebileceği, uygulamanın ekranlarının sunduğu gibi, anlaşmanın aşamasına bağlıdır:

Aşama	Gönderici	Taşıyıcı
Kapanış odası (anlaşma canlıya geçmeden)	`PackingList`, `CommercialInvoice`, `DangerousGoodsCertificate` (yalnız tehlikeli yükte), `LoadingInstruction`, `Other`	Anlaşmanın moduna ait taşıma belgesi (`RoadConsignmentNote`, denizde `BillOfLading`, `AirWaybill`, `RailConsignmentNote`; mod yoksa dördünden biri), `WeighbridgeTicket`, `Other`
Canlı (operasyon sayfası)	`PackingList`, `CommercialInvoice`, `DangerousGoodsCertificate` (yalnız tehlikeli yükte), `LoadingInstruction`, `BillOfLading`, `AirWaybill`, `RoadConsignmentNote`, `RailConsignmentNote`, `WeighbridgeTicket`, `Other`	Aynısı, `DangerousGoodsCertificate` ve `LoadingInstruction` olmadan
Çekilinmiş	Hiçbiri: `409` (`Document.DealNotOpen`)	Hiçbiri

Tarafınızın listesinde olmayan kategori 400 (Document.CategoryNotOffered) döner; liste args.offered içinde gelir. Bilinmeyen kategori 400 (Document.InvalidCategory) döner.

CustomsDeclaration, CertificateOfOrigin ve InsuranceCertificate uygulamada kullanımdan kalktı (taraflar bunları platform dışında yürütür); AdditionalCostReceipt ise operasyonun maliyetler sekmesindeki bir maliyet satırına aittir. API bunların hiçbirini, hiçbir aşamada almaz; bir kişinin yüklediği böyle bir belge anlaşmanın belge listesinde yine görünebilir.

Kapanış odasında taşıyıcının taşıma belgesi, uygulamadaki gibi, taşıyıcı göndericinin belgelerini onaylayana kadar da bekler (409, Document.BillOfLadingTooEarly).

Şirketinizin taraf olmadığı bir anlaşma, var olmayan bir anlaşma gibi 404 (Deal.NotFound) döner.

Sonra ne olur

Belge, uygulamanın sakladığı yerde saklanır ve anlaşmanın belge kasasına aittir. Karşı taraf, belge uygulamada yüklendiğindeki gibi haberdar edilir; document.uploaded iki tarafın webhook’larına da gider (yalnız belgenin kimliği ve kategorisiyle). Bkz. Olaylar.

Günlük üst sınır

Hız sınırının yanında, her şirketin API üzerinden günlük bir yükleme hakkı vardır: varsayılan olarak UTC günü başına Exchange’de 50 dosya ve 250 MB, Enterprise’da 200 dosya ve 1 GiB; canlı ve deneme alanı ayrı sayılır. Aşılınca yanıt 429 (Integration.DailyUploadLimit) olur; Retry-After başlığı UTC gece yarısına kadar sürer.

Bir kural yüzünden reddedilen yükleme (sunulmayan kategori, tür, taraf kuralı, bilinmeyen anlaşma) sayılmaz. Virüslü bulunan dosya sayılır: bir tarama harcamıştır.

Hatalar

Durum	Kod	Ne zaman
`400`	`Document.FileRequired`	Dosya yok ya da boş.
`400`	`Document.InvalidCategory`	Kategori yok ya da uygulamanın bilmediği bir kategori.
`400`	`Document.CategoryNotOffered`	Uygulamanın anlaşmanın bu aşamasında tarafınıza sunmadığı bir kategori; `args.offered` sunulanları listeler.
`400`	`Integration.IdempotencyKeyRequired`	`X-Idempotency-Key` yok.
`404`	`Deal.NotFound`	Böyle bir anlaşma yok ya da şirketiniz taraf değil.
`409`	`Document.DealNotOpen`	Anlaşmadan çekilinmiş: belge alınmıyor.
`409`	`Document.BillOfLadingTooEarly`	Göndericinin belgeleri onaylanmadan taşıyıcının taşıma belgesi.
`413`	`Document.PayloadTooLarge`	25 MB’tan büyük.
`415`	`Document.UnsupportedMediaType`	İzin verilmeyen tür ya da bildirilen türe uymayan içerik (DOCX ya da XLSX diye bildirilen bir arşiv dahil).
`422`	`Document.Infected`	Dosya virüs taramasından geçemedi. Hiçbir şey saklanmadı.
`422`	`Integration.IdempotencyKeyReused`	`X-Idempotency-Key` bu anlaşmada başka bir dosya, kategori, dosya adı ya da tür için kullanılmış. Aynı yüklemenin tekrarı (aynı dosya ve alanlar, multipart sınırı fark etmez) ilk yanıtı geri alır.
`429`	`Integration.DailyUploadLimit`	Şirketin günlük yükleme hakkı doldu.
`502`	`Document.StorageFailed`	Dosya saklanamadı. Hiçbir şey tutulmadı; tekrar deneyin.
`503`	`Document.ScanUnavailable`	Tarayıcı yanıt veremedi. Az sonra tekrar deneyin.