Referans numaraları

Her sevkiyat talebinin, teklifin, anlaşmanın ve operasyonun kimliğinin yanında bir referans numarası vardır. Kimlik API’nin anahtarı olarak kalır; numara ise telefonda okunan, e-posta konusunda görülen ve ERP ya da BPM ekranlarınıza yazılan numaradır. Onu kimliğin yanında saklayın.

Kayıt	Önek	Örnek	Alan
Sevkiyat talebi	REQ	REQ-048213	requestNumber
Teklif (taşıyıcının teklifi)	QTE	QTE-731905	quoteNumber
Anlaşma	DEAL	DEAL-206447	dealNumber
Operasyon (anlaşmanın sevkiyatı)	SHPT	SHPT-012618	shipmentNumber

Biçim

• Büyük harfli bir önek, bir tire ve rakamlar: DEAL-206447.
• En az altı rakam, başı sıfırla doldurulur. Numarayı metin olarak saklayın: SHPT-012618 ile SHPT-12618 farklı numaralardır.
• 16 karaktere kadar yer ayırın. Aralık doldukça bir basamak büyür; altı haneli bir numaradan sonra yedi haneli bir numara gelebilir.
• Numara hiç değişmez ve hiç yeniden kullanılmaz. Numaralardan önce açılmış kayıtların da numarası vardır.
• Numaralar tür başına tekildir. Türleri önek ayırır: REQ-048213 ve DEAL-048213 birlikte var olabilir.
• Numaralar sıralı değildir. Onlara göre sıralamayın, rakamlardan bir anlam çıkarmayın: oluşturulma sırası createdAt alanındadır.

Nerede görünürler

• Okumalar. Her durum, anlaşma, operasyon, belgeler ve maliyetler gövdesi, adını verdiği kayıtların numaralarını taşır; kayıt oluşana kadar her biri null olur: bir talebin durumu, talep verildiğinde ve canlıya geçtiğinde dealNumber, quoteNumber ve shipmentNumber kazanır.
• Webhook’lar. Her teslimat kimliklerin yanında requestNumber, quoteNumber, dealNumber ve shipmentNumber taşır. Bkz. Olaylar.
• Uygulama ve e-postalar. Kullanıcılar her ekranda aynı numaraları kopyalama düğmesiyle görür; bildirim e-postalarının konusu kaydın numarasıyla biter, örneğin [DEAL-206447].
• Belgeler. Operasyon özeti ve komisyon faturası numaraları basar.

Kaydı numarasıyla okuma

curl "https://app.quatlasglobal.com/api/integrations/v1/shipment-requests/by-number/REQ-048213" \
  -H "Authorization: Bearer $QUATLAS_KEY"

curl "https://app.quatlasglobal.com/api/integrations/v1/deals/by-number/DEAL-206447" \
  -H "Authorization: Bearer $QUATLAS_KEY"

curl "https://app.quatlasglobal.com/api/integrations/v1/operations/by-number/SHPT-012618" \
  -H "Authorization: Bearer $QUATLAS_KEY"

• Her biri, kimlikle okumanın verdiği yanıtın aynısını aynı kapsamla (requests:read, deals:read, tracking:read) ve aynı kurallarla verir: talep ETag başlığıyla, anlaşma sizin tarafınızın gördüğü haliyle, operasyon GET /deals/{id}/tracking gibi.
• Büyük küçük harf fark etmez, önek isteğe bağlıdır: deal-206447 ve 206447 aynı anlaşmayı bulur. Başka bir türün öneki (/deals/by-number üzerinde REQ-048213) 400 Integration.InvalidBusinessNumber döner.
• Şirketinizin okuyamayacağı bir numara, hiç var olmayan bir numara gibi 404 döner: şirketinizin sahibi olmadığı bir talep, tarafı olmadığı bir anlaşma ya da operasyon.

Deneme alanı

Deneme kayıtları aynı biçimde numara alır. Numaralar her aralığın canlı numaraların hiç kullanmadığı bir bölümünden gelir; bu yüzden bir deneme numarası hiçbir zaman canlı bir kaydın numarası olmaz. Test anahtarı onları deneme alanında numarayla okur, canlı anahtar hiçbir zaman bulamaz.