CargoUse Native API 1.0
Makine okunur şema: openapi.json · Yapay zekâ özeti: llms.txt · llms-full.txt
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.
# 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"
{
"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:readalır (yazma kapsamları açıkça işaretlenmelidir). Bir uç, anahtarın kapsamı yoksa403 insufficient_scopedö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.
# Her istekte
Authorization: Bearer cu_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/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"
}
// 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.
# Her yanıtta
HTTP/2 200
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
# 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.
// Hata gövdesi
{
"statusCode": 409,
"path": "/api/v1/orders/SO-10045/ship",
"message": "Bu siparişin gönderisi zaten var.",
"code": "already_shipped"
}
// 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"] }
}
// 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.
// 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 }
}
// 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=<ISO> kullanın; webhook daha verimlidir.
# 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"
// 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=<unix saniye>,v1=<hex> — v1, gizli anahtarınızla "<t>.<ham gövde>" 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.
# Ö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"
}
}
// 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));
}
# 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ıç
- Bağlantı testi:
GET /v1/me— anahtarınız ve kapsamlarınız döner. - Profil kimliği:
GET /v1/profiles— app'te favorilediğiniz profillerdenenabled: trueolan biridseçin. - Sipariş oluştur:
POST /v1/orders— tek nesne ya da 200'e kadar dizi. - Fiyat al (isteğe bağlı):
POST /v1/orders/{orderId}/quote—incotermDDP (vergiler dahil) veya DDU. - Gönderiye dönüştür:
POST /v1/orders/{orderId}/ship— bakiyeden öder;shipmentNodöner.pay:falseile taslak bırakıp panelden ödeyebilirsiniz. - Depo giriş etiketi:
GET /v1/shipments/{shipmentNo}/inbound-label— QR ve depo adresi; koliye yapıştırın. - İzleme: webhook tanımlayın ya da
GET /v1/shipments?updatedSince=…ile sorgulayın;in_transitsonrası…/labelve…/tracking.
Uç başına ayrıntılı örnekler (cURL, Node.js) aşağıdaki bölümlerde, her ucun sağ panelindedir.
# 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"
# 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 } }'
# 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 }'
# 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}/testartık hedefin HTTP kodunu, süresini ve hata ayrıntısını döndürmez — alanlar korunur (statusCodevedurationMsher zamannull, başarısızlıktaerror: "failed"); ayrıntı uç kaydındakilastErroralanı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) birimlerGET /v1/shipmentslistesinde görünmez, webhook olayı üretmez;GET /v1/shipments/{shipmentNo}ve/trackingbu birimler için404 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.
Ü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.
Siparişler
GET /api/v1/orders — Sipariş listesi
Yeniden eskiye, sayfalı. channel ile kanal (api, shopify, etsy, excel) filtrelenir.
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.
GET /api/v1/orders/{orderId} — Sipariş detayı
Bağlı gönderiler (shipments[]) ve gönderi verisi (shipping) ile.
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).
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.
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.
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).
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.
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.
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.
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.
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.
Webhook'lar
GET /api/v1/webhooks — Webhook uçları
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ç.
GET /api/v1/webhooks/{id} — Webhook ucu detayı
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).
DELETE /api/v1/webhooks/{id} — Webhook ucu sil
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).
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.
GET /api/v1/webhooks/{id}/deliveries — Son teslimatlar
Son 30 teslimat: durum, deneme sayısı, HTTP kodu, hata ve gönderilen gövde.