# CargoUse Native API 1.0 — tam metin > CargoUse Native API, siparişlerinizi kendi sisteminizden (ERP, mağaza yazılımı, pazaryeri entegratörü) CargoUse'a aktarmanız, fiyat almanız, gönderiye dönüştürmeniz ve gönderi durumunu izlemeniz için tasarlanmış REST arayüzüdür. Kısa dizin: https://apidocs.cargouse.com/llms.txt · Şema: https://apidocs.cargouse.com/openapi.json ## Giriş CargoUse Native API, siparişlerinizi kendi sisteminizden (ERP, mağaza yazılımı, pazaryeri entegratörü) CargoUse'a aktarmanız, fiyat almanız, gönderiye dönüştürmeniz ve gönderi durumunu izlemeniz için tasarlanmış REST arayüzüdür. - **Temel adres:** `https://api.cargouse.com/api/v1` - **Biçim:** JSON istek ve yanıt (`Content-Type: application/json`, UTF-8). Tarihler ISO-8601 UTC. - **Sürüm:** v1. Geriye uyumsuz değişiklikler yeni bir sürüm yolunda yayınlanır; v1 yanıtlarına yeni alanlar eklenebilir, alan kaldırılmaz. - **Kimlik:** Hesabım › API sayfasından ürettiğiniz API anahtarı (aşağıda). Akış özeti: **profil seç → sipariş oluştur → (isteğe bağlı) fiyat al → gönderiye dönüştür ve öde → koliye depo giriş etiketini yapıştırıp CargoUse deposuna gönder → durumları webhook veya sorgu ile izle → taşıyıcı etiketi ve takip bilgisini al.** Sağ paneldeki örnekler kopyalanıp çalıştırılabilir; `cu_live_XXXX…` yerine kendi anahtarınızı yazın. ```bash ## Bağlantı testi — anahtarınız ve kapsamlarınız döner curl "https://api.cargouse.com/api/v1/me" \ -H "Authorization: Bearer cu_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" ``` ```json { "customerId": 42, "email": "magaza@ornek.com", "name": "Ada Lovelace", "companyName": "Örnek Ticaret Ltd.", "balanceUsd": 1250.4, "currency": "USD", "apiKey": { "id": 12, "name": "ERP entegrasyonu", "keyPrefix": "cu_live_3f9a1c2b", "scopes": ["orders:write", "orders:read", "shipments:read", "webhooks:manage"], "rateLimitPerMin": 60, "dailyQuota": 5000 } } ``` ## Kimlik doğrulama Her istek `Authorization` başlığında bir API anahtarı taşır (sağdaki örnek). - Anahtar **app.cargouse.com › Hesabım › API** sayfasında üretilir ve **yalnız üretim anında bir kez** gösterilir. Kaybolursa yenisi üretilir, eskisi iptal edilir. - Hesap başına en fazla **5 aktif anahtar**. Anahtarlar müşteri veya CargoUse destek ekibi tarafından iptal edilebilir; iptal anında geçersizdir. - Anahtar üretilirken **kapsam** seçilir. Kapsam seçilmezse anahtar yalnız `orders:read` alır (yazma kapsamları açıkça işaretlenmelidir). Bir uç, anahtarın kapsamı yoksa `403 insufficient_scope` döner. | Kapsam | İzin verdiği uçlar | |---|---| | `orders:read` | Sipariş listeleme/detay, fiyat teklifi | | `orders:write` | Sipariş oluşturma/güncelleme/silme, gönderiye dönüştürme (**ödeme yapar**) | | `shipments:read` | Gönderi listeleme/detay, etiketler, takip | | `webhooks:manage` | Webhook uçlarını yönetme | `GET /v1/me` ve `GET /v1/profiles` herhangi bir geçerli anahtarla çalışır. API erişimi CargoUse ekibi tarafından hesabınızda açılan bir modüldür. Modül kapalıysa tüm istekler `403 MODULE_DISABLED` döner. ```http ## Her istekte Authorization: Bearer cu_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Content-Type: application/json ``` ```json // 401 — anahtar yok / geçersiz / iptal edilmiş { "statusCode": 401, "path": "/api/v1/orders", "message": "API anahtarı geçersiz veya iptal edilmiş.", "code": "invalid_api_key" } ``` ```json // 403 — anahtarın kapsamı bu uca yetmiyor { "statusCode": 403, "path": "/api/v1/orders/SO-10045/ship", "message": "Bu işlem için 'orders:write' kapsamı gerekli.", "code": "insufficient_scope", "details": { "required": "orders:write", "granted": ["orders:read"] } } ``` ## Limitler | Sınır | Değer | Aşılınca | |---|---|---| | Dakikalık istek | anahtar başına **60 istek/dk** | `429 rate_limited`, `Retry-After` başlığı | | Günlük istek | anahtar başına **5.000 istek/gün** (UTC) | `429 quota_exceeded` | | Toplu sipariş | istek başına **200 sipariş** | `400 too_many_orders` | | Sayfalama | `pageSize` en fazla 100 | sessizce 100'e düşürülür | Her yanıt `X-RateLimit-Limit` ve `X-RateLimit-Remaining` başlıklarını taşır. Yoğun aktarımlarda istekleri toplu gönderin (tek istekte 200 sipariş) ve durum izlemede sorgu yerine webhook kullanın. ```http ## Her yanıtta HTTP/2 200 X-RateLimit-Limit: 60 X-RateLimit-Remaining: 57 ``` ```http ## Sınır aşıldığında HTTP/2 429 Retry-After: 23 { "statusCode": 429, "path": "/api/v1/shipments", "message": "Dakikalık istek sınırı aşıldı (60/dk). 23 sn sonra tekrar deneyin.", "code": "rate_limited" } ``` ## Hatalar Tüm hatalar aynı gövdeyle döner (sağdaki örnekler). `code` alanı makine tarafından işlenmek içindir; `message` Türkçe açıklamadır; `details` varsa yapısal ek bilgi taşır. | HTTP | code | Anlamı | |---|---|---| | 401 | `missing_api_key` / `invalid_api_key` | Başlık yok / anahtar geçersiz ya da iptal edilmiş | | 403 | `MODULE_DISABLED` | API modülü hesabınızda kapalı | | 403 | `insufficient_scope` | Anahtarın kapsamı bu uca yetmiyor (`details.required`) | | 429 | `rate_limited` / `quota_exceeded` | Dakikalık / günlük sınır | | 400 | `validation_error` | Alan doğrulama hatası (`details.errors` satır satır) | | 400 | `profile_not_enabled` / `invalid_profile` | Ürün profili hesabınıza kapalı / geçersiz | | 404 | `order_not_found` / `shipment_not_found` | Kayıt yok ya da size ait değil | | 404 | `label_not_ready` | Taşıyıcı etiketi henüz üretilmedi (depoya kabulden sonra) | | 404 | `shipment_merged` | Birim tek pakette birleştirilmiş; `details.leaderShipmentNo` lider gönderiyi verir — detay/takibi onunla sorgulayın | | 409 | `ambiguous_order` | Aynı sipariş numarası birden çok kanalda; `?channel=` ile belirtin | | 409 | `already_shipped` / `order_locked` / `order_converted` | Siparişin aktif gönderisi var; silinemez / değiştirilemez | | 409 | `op_in_progress` | Aynı hesapta başka bir toplu gönderi/ödeme işlemi sürüyor; birkaç saniye sonra tekrar deneyin | | 422 | `missing_shipping_data` | Siparişte profil/paket/beyan yok; gövdede gönderin | | 422 | `ship_failed` | Gönderi oluşturulamadı (`details.errors`: fiyat bulunamadı, rota yok, alıcı eksik…) | | 400 | `invalid_url` / `webhook_limit` / `key_limit` | Webhook adresi geçersiz / 5 aktif uç / 5 aktif anahtar | Sipariş oluşturma (`POST /v1/orders`) satır bazında çalışır: bir satırın hatası diğerlerini durdurmaz; her satır `results[]` içinde `created` / `duplicate` / `error` olarak gelir ve yanıt kodu 200'dür. ```json // Hata gövdesi { "statusCode": 409, "path": "/api/v1/orders/SO-10045/ship", "message": "Bu siparişin gönderisi zaten var.", "code": "already_shipped" } ``` ```json // Doğrulama hatası — details.errors alan alan { "statusCode": 400, "path": "/api/v1/orders/SO-10045", "message": "receiver.postal boş; receiver.state 10 karakteri aşıyor", "code": "validation_error", "details": { "errors": ["receiver.postal boş", "receiver.state 10 karakteri aşıyor"] } } ``` ```json // POST /v1/orders — satır bazında sonuç (HTTP 200) { "received": 3, "created": 1, "duplicate": 1, "error": 1, "results": [ { "index": 0, "orderId": "SO-10045", "status": "created", "channelOrderId": 4182 }, { "index": 1, "orderId": "SO-10044", "status": "duplicate", "channelOrderId": 4170 }, { "index": 2, "orderId": "SO-10046", "status": "error", "channelOrderId": null, "errors": ["US/CA için receiver.state (eyalet kodu) gerekli"] } ] } ``` ## Sipariş alanları Sipariş satırı, Excel "ShipmentDraft" şablonunun alan-alan karşılığıdır (sağda tam örnek). Her satır **tek kalemli tek koli** bir gönderidir. | Alan | Zorunlu | Kural | Excel kolonu | |---|---|---|---| | `orderId` | evet | ≤ 64 karakter, hesabınızda benzersiz; tekrar gönderilirse `duplicate` (üzerine yazılmaz) | OrderID | | `productProfileId` | evet | `GET /v1/profiles` listesinden, `enabled: true` | — (Excel'de tek profil seçilir) | | `receiver.name` / `surname` | evet | birleştirilir, ≤ 100 | ReceiverName / ReceiverSurname | | `receiver.country` | evet | ISO-2 (US, DE, GB…) | ReceiverCountry | | `receiver.city` | evet | ≤ 35; `state` boşsa "AUSTIN, TX" biçimi ayrıştırılır | ReceiverCity | | `receiver.state` | US/CA | 2 harf eyalet kodu, ≤ 10 | (ReceiverCity içinde) | | `receiver.postal` | US/CA/GB | ≤ 20 | ReceiverPostal | | `receiver.street` + `buildingNumber` | evet | birleşik adres ≤ 35; US/CA/GB/AU/NZ/IE'de numara önce yazılır | ReceiverStreet / ReceiverBuildingNumber | | `receiver.address2` | hayır | ≤ 35 | — | | `receiver.phone` / `email` | hayır | ≤ 30 / geçerli e-posta | ReceiverPhone / ReceiverMail | | `item.quantity` | evet | pozitif tam sayı | ProformaAmount | | `item.unitPriceUsd` | evet | > 0, USD birim beyan değeri | ProformaPrice | | `item.originCountry` | hayır | ISO-2, varsayılan TR | OriginCountry | | `package.weightKg` | evet | > 0 | Kilogram | | `package.lengthCm` / `widthCm` / `heightCm` | evet | > 0 | LenghtCm / WidthCm / HeightCm | Alıcı bilgisi sonradan `PUT /v1/orders/{orderId}` ile güncellenebilir ve bağlı gönderiye yansır (ülke değişimi yeniden fiyatlandırır). Paket/beyan/profil yalnız gönderisi olmayan siparişte değiştirilebilir. ```json // Tek sipariş satırı — POST /v1/orders gövdesi (dizi de olabilir) { "orderId": "SO-10045", "productProfileId": 123, "receiver": { "name": "Ada", "surname": "Lovelace", "country": "US", "city": "Austin", "state": "TX", "postal": "73301", "street": "Main St", "buildingNumber": "12", "address2": "Apt 4B", "phone": "+1 512 555 0100", "email": "ada@example.com" }, "item": { "quantity": 2, "unitPriceUsd": 12.5, "originCountry": "TR" }, "package": { "weightKg": 0.5, "lengthCm": 20, "widthCm": 15, "heightCm": 5 } } ``` ```json // Almanya örneği — eyalet ve posta kodu kuralı yok, adres "sokak + numara" { "orderId": "SO-10046", "productProfileId": 123, "receiver": { "name": "Max Mustermann", "country": "DE", "city": "Berlin", "postal": "10115", "street": "Hauptstr.", "buildingNumber": "5" }, "item": { "quantity": 1, "unitPriceUsd": 39.9 }, "package": { "weightKg": 1.2, "lengthCm": 30, "widthCm": 20, "heightCm": 10 } } ``` ## Gönderi durumları | `status` | Etiket | Anlamı | |---|---|---| | `draft` | Taslak | Oluşturuldu, ödenmedi (`pay:false` veya bakiye yetersiz) | | `paid` | Depoya Bekleniyor | Ödendi; koli CargoUse deposuna gönderilmeli (depo giriş etiketi hazır) | | `at_warehouse` / `label_created` | Depoda | Depoya ulaştı, ölçüldü; taşıyıcı etiketi üretiliyor / üretildi | | `in_transit` | Kargoya Verildi | Taşıyıcıya teslim edildi; takip numarası ve etiket PDF hazır | | `delivered` | Teslim Edildi | Alıcıya ulaştı | | `cancelled` | İptal | İptal edildi (ücret iadesi bakiyeye) | | `failed` | Hata | Etiket üretimi başarısız — CargoUse ekibi ilgilenir | Depo ölçümü beyandan büyük çıkarsa gönderi yeniden fiyatlanır; fark `dueAmountUsd` alanında görünür ve panelden ödenir. Durum değişimlerini sorguyla izlemek için `GET /v1/shipments?updatedSince=` kullanın; webhook daha verimlidir. ```bash ## Son 15 dakikada değişen gönderiler curl "https://api.cargouse.com/api/v1/shipments?updatedSince=2026-09-16T07:00:00Z&pageSize=100" \ -H "Authorization: Bearer cu_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" ``` ```json // Gönderi özeti (GET /v1/shipments/{shipmentNo} — kısaltılmış) { "shipmentNo": "CU7F3K9Q", "status": "in_transit", "statusLabel": "Kargoya Verildi", "orderId": "SO-10045", "carrier": "UPS", "waybill": "1Z999AA10123456784", "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784", "price": 41.85, "dueAmountUsd": 0, "labelStatus": "created", "labelAvailable": true, "receivedAt": "2026-09-16T08:00:00.000Z", "shippedAt": "2026-09-16T15:00:00.000Z", "deliveredAt": null } ``` ## Webhook'lar Aktif bir webhook ucu tanımladığınızda, gönderi durumu veya takip numarası değiştiğinde adresinize `shipment.status_changed` olayı POST edilir (sağda örnek teslimat). Uç oluşturulmadan önce var olan gönderiler için geçmiş olay gönderilmez. **Başlıklar:** `X-CargoUse-Event`, `X-CargoUse-Event-Id` (tekilleştirme anahtarı), `X-CargoUse-Timestamp`, `X-CargoUse-Signature`. **İmza:** `X-CargoUse-Signature: t=,v1=` — `v1`, gizli anahtarınızla `"."` metninin HMAC-SHA256 özetidir. Gövdeyi **ayrıştırmadan** (ham byte'lar) doğrulayın ve `t` için 5 dakikalık tolerans uygulayın. **Teslimat kuralları:** 2xx dışındaki yanıtlar ve 10 saniyeyi aşan istekler başarısız sayılır; 1 dk → 5 dk → 30 dk → 2 sa → 12 sa aralıklarla toplam 5 deneme yapılır. Yönlendirmeler (3xx) izlenmez. 20 ardışık başarısız teslimatta uç otomatik pasife alınır; panelden veya `PATCH /v1/webhooks/{id}` ile yeniden etkinleştirilir. Aynı olay nadiren birden fazla kez iletilebilir; `X-CargoUse-Event-Id` ile tekilleştirin. İsteği hemen 2xx ile yanıtlayıp işi kuyruğa alın. **Tek paket:** Tek pakette birleştirilen (merged) birimler için olay gönderilmez ve bu birimler `GET /v1/shipments` listesinde yer almaz; paketi lider gönderi temsil eder (durum değişimleri onun için bildirilir). Teslimat geçmişi için `GET /v1/webhooks/{id}/deliveries`, kurulum testi için `POST /v1/webhooks/{id}/test`. ```http ## Örnek teslimat — CargoUse → sizin adresiniz POST /cargouse/webhook HTTP/1.1 Host: example.com Content-Type: application/json User-Agent: CargoUse-Webhooks/1.0 X-CargoUse-Event: shipment.status_changed X-CargoUse-Event-Id: evt_2b7c9f0e1a3d4c5b6a7f8e9d X-CargoUse-Timestamp: 1758034800 X-CargoUse-Signature: t=1758034800,v1=6f2a9c1d… { "id": "evt_2b7c9f0e1a3d4c5b6a7f8e9d", "type": "shipment.status_changed", "createdAt": "2026-09-16T15:00:04.000Z", "data": { "shipmentNo": "CU7F3K9Q", "orderId": "SO-10045", "channelOrderId": 4182, "previousStatus": "at_warehouse", "status": "in_transit", "statusLabel": "Kargoya Verildi", "waybill": "1Z999AA10123456784", "carrier": "UPS", "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784", "changes": ["status"], "occurredAt": "2026-09-16T15:00:00.000Z" } } ``` ```js // Node.js — imza doğrulama (rawBody: ayrıştırılmamış gövde) import { createHmac, timingSafeEqual } from 'node:crypto'; export function verifyCargoUse(rawBody, signatureHeader, secret, toleranceSec = 300) { const { t, v1 } = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('='))); if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false; // eski / yeniden oynatılan istek const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'); return expected.length === v1?.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1)); } ``` ```bash ## Uç oluştur — secret yalnız bu yanıtta döner curl -X POST "https://api.cargouse.com/api/v1/webhooks" \ -H "Authorization: Bearer cu_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/cargouse/webhook" }' ``` ## Hızlı başlangıç 1. **Bağlantı testi:** `GET /v1/me` — anahtarınız ve kapsamlarınız döner. 2. **Profil kimliği:** `GET /v1/profiles` — app'te favorilediğiniz profillerden `enabled: true` olan bir `id` seçin. 3. **Sipariş oluştur:** `POST /v1/orders` — tek nesne ya da 200'e kadar dizi. 4. **Fiyat al (isteğe bağlı):** `POST /v1/orders/{orderId}/quote` — `incoterm` DDP (vergiler dahil) veya DDU. 5. **Gönderiye dönüştür:** `POST /v1/orders/{orderId}/ship` — bakiyeden öder; `shipmentNo` döner. `pay:false` ile taslak bırakıp panelden ödeyebilirsiniz. 6. **Depo giriş etiketi:** `GET /v1/shipments/{shipmentNo}/inbound-label` — QR ve depo adresi; koliye yapıştırın. 7. **İzleme:** webhook tanımlayın ya da `GET /v1/shipments?updatedSince=…` ile sorgulayın; `in_transit` sonrası `…/label` ve `…/tracking`. Uç başına ayrıntılı örnekler (cURL, Node.js) aşağıdaki bölümlerde, her ucun sağ panelindedir. ```bash ## 1-2) Bağlantı + profil listesi KEY="cu_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" curl "https://api.cargouse.com/api/v1/me" -H "Authorization: Bearer $KEY" curl "https://api.cargouse.com/api/v1/profiles" -H "Authorization: Bearer $KEY" ``` ```bash ## 3) Sipariş oluştur curl -X POST "https://api.cargouse.com/api/v1/orders" \ -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{ "orderId": "SO-10045", "productProfileId": 123, "receiver": { "name": "Ada", "surname": "Lovelace", "country": "US", "city": "Austin", "state": "TX", "postal": "73301", "street": "Main St", "buildingNumber": "12", "email": "ada@example.com" }, "item": { "quantity": 2, "unitPriceUsd": 12.5 }, "package": { "weightKg": 0.5, "lengthCm": 20, "widthCm": 15, "heightCm": 5 } }' ``` ```bash ## 4) Fiyat teklifi (para hareketi yok) ve 5) gönderiye dönüştür + öde curl -X POST "https://api.cargouse.com/api/v1/orders/SO-10045/quote" \ -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{ "serviceLevel": "express", "incoterm": "DDP" }' curl -X POST "https://api.cargouse.com/api/v1/orders/SO-10045/ship" \ -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{ "serviceLevel": "express", "incoterm": "DDP", "pay": true }' ``` ```bash ## 6-7) Depo giriş etiketi, gönderi durumu, taşıyıcı etiketi (PDF) ve takip curl "https://api.cargouse.com/api/v1/shipments/CU7F3K9Q/inbound-label" -H "Authorization: Bearer $KEY" curl "https://api.cargouse.com/api/v1/shipments/CU7F3K9Q" -H "Authorization: Bearer $KEY" curl "https://api.cargouse.com/api/v1/shipments/CU7F3K9Q/label" -H "Authorization: Bearer $KEY" -o CU7F3K9Q.pdf curl "https://api.cargouse.com/api/v1/shipments/CU7F3K9Q/tracking" -H "Authorization: Bearer $KEY" ``` ## Sürüm notları - **1.0 (2026-09-15):** İlk yayın — siparişler, fiyat teklifi, gönderiye dönüştürme, gönderi sorgu/etiket/takip, webhook'lar. - **2026-10-18 (güvenlik):** `POST /v1/webhooks/{id}/test` artık hedefin HTTP kodunu, süresini ve hata ayrıntısını döndürmez — alanlar korunur (`statusCode` ve `durationMs` her zaman `null`, başarısızlıkta `error: "failed"`); ayrıntı uç kaydındaki `lastError` alanındadır. Başka bir hesaba ait ürün profili kopyası sipariş oluşturma/güncelleme, fiyat teklifi ve gönderiye dönüştürmede 403 döner. - **2026-10-29 (tek paket):** Aynı üretim siparişinin birimleri tek pakette birleştirilebilir. Birleşmiş (`merged`) birimler `GET /v1/shipments` listesinde görünmez, webhook olayı üretmez; `GET /v1/shipments/{shipmentNo}` ve `/tracking` bu birimler için `404 shipment_merged` (`details.leaderShipmentNo`) döner. Paketi lider gönderi temsil eder. ## Uçlar ### Hesap #### GET /api/v1/me — Hesap bilgisi + anahtarın kapsamları Bağlantı testi için idealdir. Bakiye eksi ise borç anlamına gelir. - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) ### Ürün Profilleri #### GET /api/v1/profiles — Favori ürün profilleri Yalnız app › Hesabım › Ürün Profilleri ekranında favorilediğiniz (kalp) profiller döner; siparişte `productProfileId` olarak kullanılır. `enabled: false` olanlar ops tarafından hesabınıza kapatılmıştır. - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) ### Siparişler #### GET /api/v1/orders — Sipariş listesi Yeniden eskiye, sayfalı. `channel` ile kanal (api, shopify, etsy, excel) filtrelenir. - Parametre `status` (query): - Parametre `channel` (query): api | shopify | etsy | excel - Parametre `pageSize` (query): 1-100 (varsayılan 50) - Parametre `page` (query): - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### POST /api/v1/orders — Sipariş oluştur Tek nesne veya en fazla 200 elemanlı dizi. Satır bazında sonuç: `created`, `duplicate` (aynı orderId daha önce gönderilmiş, üzerine yazılmaz) veya `error` (alan hataları `errors[]`). Bir satırın hatası diğerlerini durdurmaz; HTTP 200. - İstek gövdesi: V1CreateOrderDto[] (şema openapi.json › components.schemas) - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### GET /api/v1/orders/{orderId} — Sipariş detayı Bağlı gönderiler (`shipments[]`) ve gönderi verisi (`shipping`) ile. - Parametre `orderId` (path, zorunlu): Sizin sipariş numaranız - Parametre `channel` (query): - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 404: order_not_found - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### PUT /api/v1/orders/{orderId} — Sipariş güncelle Alıcı alanları (yalnız verilenler) bağlı gönderiye de yansır; ülke değişimi yeniden fiyatlandırır. `productProfileId` / `item` / `package` yalnız gönderisi olmayan siparişte değiştirilebilir (aksi halde 409 already_shipped). - Parametre `orderId` (path, zorunlu): - Parametre `channel` (query, zorunlu): - İstek gövdesi: V1UpdateOrderDto (şema openapi.json › components.schemas) - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### DELETE /api/v1/orders/{orderId} — Sipariş sil Taslak/iptal gönderileri de silinir. Aktif gönderisi olan sipariş silinemez (409 order_locked) — önce gönderiyi panelden iptal edin. - Parametre `orderId` (path, zorunlu): - Parametre `channel` (query, zorunlu): - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### POST /api/v1/orders/{orderId}/quote — Fiyat teklifi Para hareketi yoktur. Siparişteki paket/beyan/profil kullanılır; gövdede verilenler geçersiz kılar. Fiyat, depo ölçümü beyandan farklı çıkarsa değişebilir. - Parametre `orderId` (path, zorunlu): - Parametre `channel` (query, zorunlu): - İstek gövdesi: V1QuoteDto (şema openapi.json › components.schemas) - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### POST /api/v1/orders/{orderId}/ship — Gönderiye dönüştür ve öde Gönderiyi oluşturur ve ücreti bakiyenizden düşer (`pay:false` → taslak kalır, panelden ödenir). Bakiye yetersizse gönderi taslak kalır: `paid:false`, ödenecek tutar `amountDueUsd`. Aynı sipariş ikinci kez dönüştürülemez (409 already_shipped). - Parametre `orderId` (path, zorunlu): - Parametre `channel` (query, zorunlu): - İstek gövdesi: V1ShipDto (şema openapi.json › components.schemas) - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) ### Gönderiler #### GET /api/v1/shipments — Gönderi listesi Yeniden eskiye, sayfalı. Durum izleme için `updatedSince` (ISO-8601) ile yalnız değişenleri çekin; webhook daha verimlidir. Not (tek paket): birleşmiş (merged) birimler listelenmez; lider gönderi paketi temsil eder. - Parametre `pageSize` (query): - Parametre `page` (query): - Parametre `updatedSince` (query): ISO-8601 - Parametre `orderId` (query): - Parametre `status` (query): Virgülle çoklu: paid,at_warehouse,in_transit… - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### GET /api/v1/shipments/{shipmentNo} — Gönderi detayı CU numarasıyla. Fiyat kırılımı, beyan, alıcı, beyan/ölçüm paket bilgisi ve etiket durumu. - Parametre `shipmentNo` (path, zorunlu): - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 404: shipment_not_found / shipment_merged — birim tek pakette birleşmiş; details.leaderShipmentNo lideri verir - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### GET /api/v1/shipments/{shipmentNo}/label — Taşıyıcı etiketi (PDF) Depoya kabul ve etiket üretiminden sonra hazırdır (`labelAvailable: true`). Hazır değilse 404 label_not_ready. Yanıt `application/pdf` dosyadır. - Parametre `shipmentNo` (path, zorunlu): - Yanıt 200: PDF dosyası - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 404: label_not_ready / shipment_not_found - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### GET /api/v1/shipments/{shipmentNo}/inbound-label — Depo giriş etiketi verisi Koliye yapıştırılacak QR (gönderi numarası) + CargoUse depo adresi + kap sırası. Ödeme sonrası, depoya kabule kadar (`paid` / `at_warehouse`) alınabilir; kendi etiketinizi bu veriyle basabilirsiniz. - Parametre `shipmentNo` (path, zorunlu): - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### GET /api/v1/shipments/{shipmentNo}/tracking — Canlı taşıyıcı takibi Taşıyıcıdan anlık sorgulanır (normalize Türkçe olay listesi, yeniden eskiye). Takip numarası yoksa `tracking: null`. Taşıyıcı geçici olarak yanıt vermezse 503. - Parametre `shipmentNo` (path, zorunlu): - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 404: shipment_not_found / shipment_merged — birim tek pakette birleşmiş; details.leaderShipmentNo lideri verir - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) ### Webhook'lar #### GET /api/v1/webhooks — Webhook uçları - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### POST /api/v1/webhooks — Webhook ucu oluştur https zorunlu; yerel/özel ağ adresleri reddedilir. İmza gizi (`secret`) YALNIZ bu yanıtta döner. En fazla 5 aktif uç. - İstek gövdesi: V1CreateWebhookDto (şema openapi.json › components.schemas) - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### GET /api/v1/webhooks/{id} — Webhook ucu detayı - Parametre `id` (path, zorunlu): - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### PATCH /api/v1/webhooks/{id} — Webhook ucu güncelle `isActive: true` ile otomatik pasife düşmüş uç yeniden etkinleştirilir (hata sayacı sıfırlanır). - Parametre `id` (path, zorunlu): - İstek gövdesi: V1UpdateWebhookDto (şema openapi.json › components.schemas) - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### DELETE /api/v1/webhooks/{id} — Webhook ucu sil - Parametre `id` (path, zorunlu): - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### POST /api/v1/webhooks/{id}/test — Test olayı gönder `webhook.test` olayını gerçek başlıklar ve imzayla hemen gönderir; sonuç yalnız `ok` ile bildirilir — `statusCode`/`durationMs` her zaman null, başarısızlıkta `error: "failed"` (ayrıntı uç kaydındaki lastError alanında). - Parametre `id` (path, zorunlu): - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### POST /api/v1/webhooks/{id}/rotate-secret — İmza gizini yenile Yeni `secret` yalnız bu yanıtta döner; eski giz anında geçersizdir. - Parametre `id` (path, zorunlu): - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün) #### GET /api/v1/webhooks/{id}/deliveries — Son teslimatlar Son 30 teslimat: durum, deneme sayısı, HTTP kodu, hata ve gönderilen gövde. - Parametre `id` (path, zorunlu): - Yanıt 200: - Yanıt 401: API anahtarı yok / geçersiz (missing_api_key, invalid_api_key) - Yanıt 403: Modül kapalı (MODULE_DISABLED), kapsam yetersiz (insufficient_scope), hesap pasif - Yanıt 429: rate_limited (60/dk) veya quota_exceeded (5000/gün)