Firma notları: kodlar, sipariş numarası ve seçenekler
API'de kargo firması kodları, sipariş numarası kuralının nereden okunacağı ve options alanında kabul edilen firmaya özel anahtarlar.
Güncelleme:
Gönderi gövdesi bütün firmalarda aynıdır. Firmaya göre değişen üç şey var: carrier kodu, sipariş numarası kuralı ve options alanında kabul edilen anahtarlar. Bu sayfa yalnız API'nin kabul kurallarını listeler; kargo anlaşmanızın koşulları için kargo firmanıza başvurun.
Kodlar ve sipariş numarası
| Firma | carrier | Not |
|---|---|---|
| PTT Kargo | ptt | Numara PTT'ye gitmez; gönderi PTT'de hesabınıza tanımlı barkod aralığından alınan barkodla tanınır. |
| Yurtiçi Kargo | yurtici | |
| DHL eCommerce | dhl_ecommerce | |
| HepsiJet | hepsijet | Hesabınızın ön eki numaranın önüne eklenir; sınır ön ek dahil hesaplanır. |
| Aras Kargo | aras | |
| Sürat Kargo | surat | Takip sipariş numarasıyla yapılır; takip numarası firma gönderiyi kabul ettikten sonra gelir. |
| Kolay Gelsin | kolay_gelsin |
Sipariş numarası API'de 1–64 karakterdir; kargo firmasının sınırı daha kısa olabilir. Bu sınırı hesabınızın gönderi formu şeması verir. Değer firmaya ve hesaba göre değişebileceği için kodunuza sabit yazmayın. Sınırı aşan numara kargo firmasına gönderilmez ve kırpılmaz: 422 carrier_reference_rejected.
Gönderi formu şeması
GET /api/v3/carrier-accounts/{id}/shipment-form (scope shipments:read) bir kargo hesabının gönderi formunu döner. Kabul (POST /shipments) aynı tanımla doğrular: formda gösterilen her kısıt kabulde de uygulanır, tersi de. Panel aynı şemayı kullanır. Kargo hesaplarınızın kimlikleri GET /api/v3/carrier-accounts yanıtındadır; başka bir hesabın ya da kullanıma açık olmayan hesabın kimliği 404 döner.
Alan (data altında) | Anlamı |
|---|---|
reference | Sipariş numarası kuralı: max_length, pattern, prefix. Önek varsa platform ekler; siz yazmazsınız. |
fields | Gövdedeki alanlar ve kuralları (aşağıda). |
rules | Hesabın özet kuralları: kapıda ödeme açık mı (cod_allowed), üst sınırı (cod_max), izinli payer değerleri, koli sayısı ve ölçü kuralı. |
warnings | Formda gösterilecek bilgi notları. Kabulü etkilemez. |
Her fields[] kaydı:
| Alan | Anlamı |
|---|---|
key | Gövdedeki alanın yolu: invoice_number, options.irsaliye_no. parcels.*.weight_grams her koli için geçerlidir. |
label, help | Türkçe etiket ve açıklama. Metin değişebilir; kodunuzda karşılaştırmayın. |
type | string, integer, decimal, money, enum, multi_enum, boolean. |
unit | g, mm, desi ya da null. |
required, enabled | Varsayılan zorunluluk ve açıklık. Hesap ayarından kapalı alan enabled: false ve disabled_reason ile gelir. |
min, max, max_length, max_amount | Sınırlar. max_amount para alanında {amount, currency} (kuruş). |
pattern | Metnin uyması gereken düzenli ifade ya da null. |
enum | İzinli değerler [{value, label}]. value kalıcıdır, label değişebilir. multi_enum alana değer dizisi gönderilir. |
depends_on | Alanın zorunluluğunu ya da açıklığını değiştiren koşullar. |
pattern: ECMAScript ile PCRE'nin ortak alt kümesidir. Ayraç ve bayrak içermez, tam eşleşme için ^…$ ile çapalıdır. JavaScript'te new RegExp(pattern) ile olduğu gibi kullanılır; PHP'de /…/u ayraçları eklenir. Örnek: options.vergi_no için ^\d{10,11}$.
depends_on: Her koşul {key, equals | present, effect, reason} biçimindedir.
key: koşulun baktığı alan.equals: o alan bu değerdeyse;present: alan doluysa (true) ya da boşsa (false). Bir koşulda ikisinden yalnız biri bulunur.effect: koşul sağlanınca uygulanır.requiredalanı zorunlu yapar;enabledalanı yalnız bu koşulda açar;disabledalanı bu koşulda kapatır.reason: koşulun Türkçe açıklaması ya danull.
{
"key": "invoice_number",
"type": "string",
"required": false,
"max_length": 20,
"depends_on": [{ "key": "cash_on_delivery", "present": true, "effect": "required", "reason": "…" }]
}Bir alandaki koşullar bağımsızdır. Aynı alanda birden çok enabled koşulu varsa alan hepsi sağlanınca açılır. Hesap ayarından kapalı alan koşulla açılmaz. Kapalı alana gönderilen değer, öteki alanların koşullarında boş sayılır.
Kabul bu kuralları 422 validation_failed ile bildirir; errors[].code değerleri:
- Zorunlu alan boş:
required. - Kapalı alan dolu:
not_allowedya da firmaya özel kod (Hatalar ve sınırlar). - Sınır aşımı:
too_long,too_small.pattern'a uymayan metin:invalid. İzinli değerler dışında değer:not_allowed.
Aşağıdaki tablolar başvuru içindir; kesin kural her zaman hesabınızın şemasıdır.
Firmaya göre alanlar
Ağırlık (parcels[].weight_grams) isteğe bağlıdır; girilirse kargo firmasına iletilir. Fatura numarası her firmada üst düzey invoice_number alanıyla gönderilir (Gönderi oluşturma).
options içinde yalnız firmanın formundaki anahtarlar kabul edilir; tabloda aksi yazmıyorsa isteğe bağlıdır. Başka bir anahtar 422 validation_failed döner, kaydı {"field": "options.<anahtar>", "code": "not_allowed"} olur. Her firmanın altında artık kabul edilmeyen eski anahtarlar da listelenmiştir.
PTT (ptt)
options anahtarı yoktur. Kabul edilmeyen eski anahtarlar: odeme_sekli, ek_hizmet.
Yurtiçi Kargo (yurtici)
| Anahtar | Tip | Anlamı |
|---|---|---|
irsaliye_no | string, en çok 20 | İrsaliye numarası. Boşsa fatura numarası kullanılır. |
invoice_number en çok 20 karakterdir; kapıda ödemeli gönderide zorunludur. Kabul edilmeyen eski anahtarlar: fatura_no, tt_belge_no.
Aras (aras)
| Anahtar | Tip | Anlamı |
|---|---|---|
irsaliye_no | string, en çok 32 | İrsaliye numarası. Boşsa fatura numarası (invoice_number), o da boşsa sipariş numarası gider. |
invoice_number en çok 32 karakterdir. Kabul edilmeyen eski anahtarlar: fatura_no, aciklama, agirlik, hacimsel_agirlik, telefon2.
HepsiJet (hepsijet)
options anahtarı yoktur. Kabul edilmeyen eski anahtarlar: desi, total_parcels.
DHL eCommerce (dhl_ecommerce)
| Anahtar | Tip | Anlamı |
|---|---|---|
vergi_dairesi | string, en çok 100 | Alıcı firmaysa vergi dairesi. vergi_no doluysa zorunludur. |
vergi_no | 10 ya da 11 rakam (^\d{10,11}$) | Vergi numarası ya da T.C. kimlik numarası. vergi_dairesi doluysa zorunludur. |
Kabul edilmeyen eski anahtarlar: tel_ev, tel_cep, tel_is, fax, aciklama, kilo, desi, icerik, parca_no, sms_alici, sms_gonderici, musteri_no, bayi_no, adres_farkli, meydan_bulvar, semt, mahalle, cadde, sokak. Telefon, adres ve paket bilgisi ortak alanlardan gider.
Sürat Kargo (surat)
| Anahtar | Tip | Anlamı |
|---|---|---|
irsaliye_seri_no | string, en çok 20 | İrsaliye seri numarası. Kapıda ödemeli gönderide girilmesi önerilir. |
irsaliye_sira_no | string, en çok 20 | İrsaliye sıra numarası. Kapıda ödemeli gönderide girilmesi önerilir. |
kargo_turu | "1" | "2" | "3" | 1 dosya, 2 mi, 3 koli. Verilmezse koli. |
teslim_sekli | "1" | "2" | 1 adrese teslim, 2 şubede teslim. Verilmezse adrese teslim. |
ek_hizmetler | dizi: GondericiyeSms, TelefonIhbar, AliciyaSms, AdrestenAlim | Ek hizmetler, ör. ["AliciyaSms", "TelefonIhbar"]. |
Ağırlık girilmezse firmaya 0 kg gider; kargo ücreti firmanın kendi ölçümüne göre hesaplanır.
Kolay Gelsin (kolay_gelsin)
| Anahtar | Tip | Anlamı |
|---|---|---|
irsaliye_no | string, en çok 64 | İrsaliye seri ve numarası. |
Kargo hesabınıza bağlı kurallar
Bazı istekler kargo hesabınızın ayarlarına göre kabulde reddedilir; kodlar Hatalar ve sınırlar sayfasında. Kargo hesabınızı panelde bağlarken bu ayarları girersiniz.