Belirli bir kargo firmasından etiketi tek seferde alma

Belirli bir kargo firmasından etiketi tek seferde alma #

Tüm teklifleri almak yerine belirli bir kargo firmasına ait etiketi tek seferde oluşturabilirsiniz.


curl --request POST \
  --url https://api.geliver.io/api/v1/transactions \
  --header 'Authorization: Bearer {{bearerToken}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "providerServiceCode": "GELIVER_STANDART",
    "shipment":{
        "test": true,
        "senderAddressID": "123123-123-aac-11",
        "returnAddressID": "b6029b1b-cc61-4263-95c3-2bd17614c9d6",
        "length": "10",
        "height": "10",
        "width": "10",
        "distanceUnit": "cm",
        "weight": "1",
        "massUnit": "kg",
        "items":[{"title":"test product", "quantity":1}],
        "recipientAddress":{
            "name": "Test Company Name",
            "email": "Test Email",
            "phone": "+905051234567",
            "address1": "Celal Bayar Üniversitesi Teknokenti Daire 102",
            "countryCode": "TR",
            "cityCode": "45",
            "districtName": "Yunusemre",
        },
        "productPaymentOnDelivery":false,
        "order": {
            "sourceCode": "API",
            "sourceIdentifier": "https://magazaadresiniz.com",
            "orderNumber": "ABC12333322",
            "totalAmount": 150,
            "totalAmountCurrency": "TL"
        }
    }
}'
Parametreler Tip Zorunluluk Açıklama
test boolean Opsiyonel Geliştirme sırasında test gönderisi oluştururken true değerini verirseniz ücretsiz olan test tekliflerini getirir. Test edebilmeniz için bu test gönderilerinde gönderi bilgilerini her çektiğinizde (app’ten veya api’den) gönderi dağıtım durumu alıcıya ulaşana kadar her seferde güncellenir. Canlıya çıktığınızda false’a çekmeyi unutmayın.
providerServiceCode String  Zorunlu Sağlayıcı servis kodu. Detaylar için lütfen Sağlayıcı servis kodları inceleyin. test alanı true ise, GELIVER_STANDART değeri verilebilir.
providerAccountID String (UUID)  Opsiyonel Kargo hesabınızın UUID cinsinden değeri
providerServiceCode String  Zorunlu Kargo hizmet kodu
shipment Object Zorunlu Gönderi bilgileri
shipment.senderAddressID String (UUID) Zorunlu Gönderici adres ID’si. Arayüzdeki adresler bölümünden veya /addresses endpointinden adreslerinizi düzenleyebilirsiniz.
shipment.returnAddressID String (UUID) Opsiyonel Gönderici adres ID’si. Arayüzdeki adresler bölümünden veya /addresses endpointinden adreslerinizi düzenleyebilirsiniz. Boş ise senderAddressID kullanılır.
shipment.parcelTemplateID String (UUID) Opsiyonel Kargo boyutları için hazır şablon kullanabilirsiniz. Bu alanı kullanırsanız aşağıdaki length, height, width, distanceUnit boyutları ignore edilir. Weight ve massUnit yine geçerli olur.
shipment.length String Zorunlu Kargo gönderisi uzunluğu. Varsayılan olarak cm cinsinden. Uzunluk ölçüsünü distanceUnit alanıyla değiştirebilirsiniz. Detaylar için lütfen API Referans Dökümanını inceleyin
shipment.height String Zorunlu Kargo gönderisi yüksekliği. Varsayılan olarak cm cinsinden. Uzunluk ölçüsünü distanceUnit alanıyla değiştirebilirsiniz. Detaylar için lütfen API Referans Dökümanını inceleyin
shipment.width String Zorunlu Kargo gönderisi genişliği. Varsayılan olarak cm cinsinden. Uzunluk ölçüsünü distanceUnit alanıyla değiştirebilirsiniz. Detaylar için lütfen API Referans Dökümanını inceleyin
shipment.distanceUnit String (cm) Opsiyonel Kargo gönderisi uzunluk cinsi. Varsayılan olarak “cm” değerindedir. Detaylar için lütfen API Referans Dökümanını inceleyin
shipment.weight String Zorunlu Kargo gönderisi ağırlığı. Varsayılan olarak kg cinsinden. Uzunluk ölçüsünü massUnit alanıyla değiştirebilirsiniz. Detaylar için lütfen API referans dökümanını inceleyin
shipment.massUnit String (kg) Opsiyonel Kargo gönderisi ağırlık cinsi. Varsayılan olarak “kg” değerindedir. Detaylar için lütfen API Referans Dökümanını inceleyin
shipment.items Array (Item) Opsiyonel Ürün listesi. Detaylar için lütfen API Referans Dökümanını inceleyin
shipment.recipientAddress.countryCode String Zorunlu Ülke kodu ISO2 formatındadır. /countries endpointinden tüm ülkelerin kodlarını inceleyebilirsiniz. Detaylar için lütfen API Referans Dökümanını inceleyin
shipment.recipientAddress.cityName String Opsiyonel Şehir adı. Şehir kodu kullanılmadıysa zorunlu.
shipment.recipientAddress.cityCode String Opsiyonel Şehir kodu, Türkiye için plaka numarasıdır (Tek hanelilerde başında 0 olmalı). Şehir adı kullanılmadıysa zorunlu. Tüm listeyi /cities?countryCode=TR isteğiyle alabilirsiniz. Detaylar için lütfen API Referans Dökümanını inceleyin.
shipment.recipientAddress.districtName String  Opsiyonel İlçe adı. Eğer districtID kullanılmadıysa zorunlu. Örn: Esenyurt
shipment.recipientAddress.districtID String Opsiyonel Geliver sisteminde tanımlanmış olan ilçe ID değeridir. İlçe adı kullanılmadıysa zorunlu. Örneğin İstanbul için /districts?countryCode=TR&cityCode=34 ile ilçeleri çekebilirsiniz. Detaylar için lütfen API Referans Dökümanını inceleyin.
shipment.recipientAddress.streetName String Opsiyonel Cadde adı
shipment.productPaymentOnDelivery boolean Opsiyonel Kapıda ödemeli kargo tekliflerini alabilmeyi sağlar. Tek aşamalı gönderi oluştururken kapıda ödemeli kargo seçeneğinin sağlayıcı servis kodunun kullanılması gerekmektedir. Kapıda ödemeli kargo teklifleri almak istemiyorsanız bu fieldı false bırakabilir veya isteğinizden kaldırabilirsiniz.
shipment.order Object Opsiyonel Aşağıdaki açıklamayı okuyun.
shipment.metadata Object Opsiyonel Aşağıdaki açıklamayı okuyun.

Order #

Order alanı ve alt alanları kapıda ödemeli gönderi oluşturulurken kullanılacaklar dışında opsiyoneldir. Shipment alanı altında (shipment.order) bulunur.

Alan adı Açıklama
sourceCode API üzerinden yapılan istekler için sabit “API” olarak gönderilir.
sourceIdentifier Gönderinin hangi web site veya uygulama tarafından oluşturulduğunu belirten alandır. Bu alanı daha sonra takip bilgisini alırken gönderi kaynağını eşlemek için kullanabilirsiniz.
orderNumber Takip bilgisi alınırken gönderinin oluşturulduğu kaynaktaki ilgili kayıt (sipariş) ile eşlemek için kullanılan string alandır.
totalAmount Gönderideki ürünün toplam fiyatını ifade eden integer alandır. Kapıda ödemede alıcıdan alınacak tutar buradan belirtilir. Kapıda ödemeli gönderiler dışında opsiyoneldir.
totalAmountCurrency Gönderideki ürünün fiyatının para birimini ifade eden string alandır. Kapıda ödemeli gönderiler dışında opsiyoneldir.
{
    "order": {
        "sourceCode": "API",
        "sourceIdentifier": "https://magazaadresiniz.com",
        "orderNumber": "ABC12333322"
    }
}

Metadata #

Gönderi için ekstra ayarlar yapabilirsiniz. Metadatadaki alanlar opsiyoneldir.

Alan adı Açıklama
providerCustomerCodes Alıcı eğer kargo firması veritabanında ekliyse onun kodlarını buradan verebilirsiniz. Adreslerin metadatasında da bir kereliğine ayarlayıp kullanmanızı tavsiye ederiz. Sadece kendi anlaşmalarınız için kullanılır.
reference1 Barkod üzerinde çıkmasını istediğiniz sipariş kodu. Sadece kendi anlaşmalarınız için kullanılır.

{
    "metadata": {
        "providerCustomerCodes":{
            "YURTICI": "Y12313435309",
            "SURAT": "S4910103"
        },
        "reference1":"SIPARIS_KODU",
    }
}

Cevap #

{
    "result": true,
    "additionalMessage": "Success",
    "data": {
        "id": "5aca8839-3987-4c36-aaf5-00c32a915215",
        "createdAt": "2022-06-23T21:24:46.291746+03:00",
        "updatedAt": "2022-06-23T21:24:46.298209+03:00",
        "amount": "10.75",
        "currency": "TL",
        "amountLocal": "10.75",
        "currencyLocal": "TL",
        "amountVat": "1.99",
        "amountLocalVat": "10.75",
        "amountTax": "0",
        "amountLocalTax": "0",
        "totalAmount": "12.99",
        "totalAmountLocal": "12.99",
        "offerID": "38f0e8cc-7534-4af4-994f-90dd54451abd",
        "shipment": {
            "id": "e37b55c5-c649-4312-8987-5527bcacf0af",
            "createdAt": "2022-06-23T21:22:33.306058+03:00",
            "updatedAt": "2022-06-23T21:24:46.296889+03:00",
            "amount": "10.75",
            "currency": "TL",
            "amountLocal": "10.75",
            "amountVat": "1.935",
            "amountLocalVat": "0",
            "amountTax": "0",
            "amountLocalTax": "0",
            "totalAmount": "1.935",
            "totalAmountLocal": "1.935",
            "length": 10,
            "width": 10,
            "height": 10,
            "desi": 1,
            "distanceUnit": "cm",
            "weight": 1,
            "massUnit": "kg",
            "useWeightOfItems": false,
            "useDimensionsOfItems": false,
            "trackingStatus": null,
            "barcode": "2792351829",
            "labelFileType":"PDF",
            "labelURL":"https://api.geliver.io/tags/ec639f5d-fd32-4296-bde7-170f2b12bca2.pdf"
            "hidePackageContentOnTag": false,
            "shipmentDate": null,
            "invoiceGenerated": false,
            "orderID": "bb765dfb-f9a7-4227-b4dd-369506e46316",
            "order": null,
            "senderAddressID": "5d3ce1a0-0a30-4f79-b414-ebbadf1c4e73",
            "senderAddress": null,
            "recipientAddressID": "59bda251-73d1-4e2f-89e7-df40e362f275",
            "recipientAddress": null,
            "createReturnLabel": false,
            "statusCode": "TRACKING_CODE_CREATED",
            "offers": null,
            "acceptedOfferID": "38f0e8cc-7534-4af4-994f-90dd54451abd",
            "acceptedOffer": null,
            "providerCode": "SURAT",
            "providerServiceCode": "SURAT_STANDART",
            "enableAutomation": false,
            "organizationShipmentID": 43,
            "providerBranchName": null,
            "providerInvoiceNo": null,
            "providerReceiptNo": null,
            "providerSerialNo": null
        },
        "description": "",
        "isRefund": false,
        "isCustomAccountCharge": false
    }
}

Parametreler Açıklama
id Yeni oluşturulan transaction’un id’si.
amount Gönderi ücreti
currency Gönderi ücretinin döviz cinsi
amountTax Gönderinin vergilerinin ücretleri toplamı.
amountVat Gönderinin sadece KDV’sinin ücreti.
amount Gönderinin vergiler hariç ücreti.
totalAmount Gönderinin vergiler dahil toplam ücreti
offerID Kabul edilen teklifin id’si.
shipment.barcode Geliver tarafından üretilen barkod/sipariş kodu. Bu kod kargo şubesine iletilen etiket numarasıdır. Bu alandaki değer kargo şubesine tesliminde şube personeline söylenmesi gerekir. Eğer Geliver tarafından kullanılan dinamik veya pdf etiketi bastırırsanız orada da yazdığı için ayrıca söylemek gerekmez şube personeline.
shipment.labelFileType Etiket dosyasının türü. PDF veya ZPL olabilir.
shipment.labelURL Etiket dosyasının adresi.
shipment.trackingNumber Kargo firması tarafından üretilen takip numarası. Bazı kargo firmaları müşteri kargoyu şubeye teslim ettiğinde bu kodu üretir. Bu sebeple bu kodu almanız gerekiyorsa ya Kargo Takip için periyodik istek yapmanız gerekiyor ya da [Webhooks] (https://docs.geliver.io/docs/geliver/extra/webhooktracking/ “Webhooks”) kullanarak şubeye teslim edildiği anda sunucunuza istek yapılmasını ayarlayabilirsiniz.
shipment.trackingUrl Kargo takip adresi. Müşterilerinize bunu verebilirsiniz. Geliver’in kendi kargo takip sayfası hazır olana kadar Kargo firmasının verdiği adresler kullanılacaktır. trackingNumber’da olduğu gibi bazı kargo firmaları kargoyu şubeye teslim ettiğinde bu alan doluyor. Bu sebeple bu adresi almanız gerekiyorsa ya Kargo Takip için periyodik istek yapmanız gerekiyor ya da [Webhooks (https://docs.geliver.io/docs/geliver/extra/webhooktracking/ “Webhooks”) kullanarak şubeye teslim edildiği anda sunucunuza istek yapılmasını ayarlayabilirsiniz.
statusCode Gönderi durumu. Alabileceği değerler: CREATED,GOT_OFFERS,OFFER_ACCEPTED,TRACKING_CODE_CREATED,SHIPPED,DELIVERED
Hata kodu Hata açıklaması
E1085 Hatalı istek.
E1055 Yetkiniz yok
E1064 Teklif bulunamadı
E1051 Gönderi bulunamadı
E1065 Bu gönderi için daha önce bir teklif kabul edilmiş
E1066 Organizasyonun yeterli bakiyesi yok
E1067 Ürün bilgisi alınamadı
E1074 Bakiye güncelleme hatası
E1066 Yeterli bakiye yok
E1115 Kredi kartı ödemesi alınamadı
E1068 Gönderici adresi alınamadı
E1071 Gönderi barkodu oluşturulamadı
E1072 Kargo etiketi oluşturulamadı
E1073 Gönderi güncellenemedi
E1086 İşlem oluşturulamadı
E1115 Kredi kartı ödemesi alınamadı
E1111 Teklif güncellenemedi