Referans Numarası Üretim Yönergeleri
API davranışı: reference_no alanı isteğe bağlıdır. Gönderilirse boş olamaz ve aynı müşteri için daha önce kullanılmamış olmalıdır. Veritabanı alanı en fazla 255 karakterdir. Bu sayfadaki format önerileri API tarafından doğrulanmaz; API büyük harfe çevirme veya checksum kontrolü yapmaz. reference_no tek başına tekrar gönderim koruması sağlamaz, bunun için Idempotency sayfasındaki X-Idempotency-Key header'ını kullanın.
Gönderi/sipariş referans numaraları için önerilen yapı şu şekildedir:
1. Genel Format
[PREFIX]-[TARİH/SIRA]-[RANDOM]-[CHECKSUM]
Örnek: ACM-260825-4F7K-9
2. Uzunluk
- Toplam: 10–16 karakter (tire/ayraç hariç)
- 8'in altı → çakışma (collision) riski artabilir
- 16'nın üstü → elle girişte hata artabilir, barkod/etiket alanında taşabilir. Etiket görünümünü kullandığınız şablonda kontrol edin.
3. Karakter Seti
- Sadece büyük harf + rakam (A–Z, 0–9) — case-sensitive karışıklığı azaltır
- Rastgele kısımda şu karakterleri karıştırma riski nedeniyle kullanma:
0/O, 1/I/L, 5/S, 8/B
- Boşluk,
/, \, _, # gibi karakterlerden kaçın (URL, barkod, EDI/entegrasyon sorunlarına yol açabilir)
- Ayraç olarak sadece
- kullanılabilir (okunabilirlik için, sistemde zorunlu değil)
4. Prefix (Önek)
- Sabit ve anlamlı olmalı: müşteri kodu, kanal veya sipariş tipi
- 2–4 karakter yeterli (örn.
ACM, WEB, B2B)
- Raporlama/filtreleme için faydalıdır, rastgele olmamalı
5. Randomize / Sıra Bölümü
- Tarih (YYMMDD) + rastgele blok kombinasyonu dengeli bir yöntemdir:
- Tarih → insan gözüyle hızlı tanıma, sıralama, arşivleme
- Rastgele 4–6 alfanümerik karakter → tahmin edilemezlik, çakışma önleme
- Salt sıra numarası (1, 2, 3…) tahmin edilebilir ve güvenlik açısından risk oluşturabilir — rakip/3. şahıs sipariş hacmini çıkarabilir
- Salt rastgele (tarihsiz) → insan gözüyle takip zorlaşır, önerilmez
6. Suffix / Checksum (Opsiyonel ama Önerilir)
- Son 1 karakter Luhn benzeri bir doğrulama basamağı olabilir
- Elle giriş hatalarını (yanlış girilen referans no) kendi sisteminizde otomatik yakalamanızı sağlar
7. Benzersizlik (Uniqueness)
- Üretim mantığı:
zaman damgası + rastgelelik birlikte kullanılmalı, tek başına biri yetersiz kalabilir
- Referansı kendi sisteminizde idempotency anahtarı olarak da kullanacaksanız, tekrarlı gönderimlerde aynı referansın aynı gönderiye eşlendiğinden emin olun. ComToHome API'de tekrar gönderim koruması için
X-Idempotency-Key header'ı kullanılır.
8. Human-Friendly Kurallar
- Blokları tire ile ayırmak okunabilirliği artırır:
ACM-260825-4F7K
- Telefon/sesli aktarımda karışmayacak karakterler seçilmeli (yukarıdaki 0/O, 1/I gibi çiftlerden kaçınma bu yüzden önemli)
- Büyük/küçük harf farkı olmamalı, kendi sisteminizde büyük harfe çevirmeniz önerilir
Önerilen Şablon
{PREFIX:2-4}-{YYMMDD:6}-{RANDOM:4-6}[-{CHECKSUM:1}]
Örnek: WEB-260825-7K9M
Bu yapı okunabilir ve tarih bazlı sıralanabilir, çakışma ve elle giriş hatası riskini azaltır. Seçtiğiniz formatı entegrasyonunuzda aşağıdaki regex ile doğrulayabilirsiniz:
^[A-Z0-9]{2,4}-\d{6}-[A-Z0-9]{4,6}(-\d)?$