Gönderi oluşturma ve teklifleri alma

Gönderi oluşturma ve teklifleri alma #

Tek bir çağrıyla hem sistemde gönderi oluşturacak hem de o gönderiye teklifleri alabilirsiniz. Bunun için /shipments endpoint’ine POST isteği göndermelisiniz.

İstek # 


curl --request POST \
  --url https://api.geliver.io/api/v1/shipments \
  --header 'Authorization: Bearer {{bearerToken}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "test": true,
	"senderAddressID": "b6029b1b-cc61-4263-95c3-2bd17614c9d6",
	"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.
senderAddressID String (UUID) Zorunlu Gönderici adres ID’si. Arayüzdeki adresler bölümünden veya /addresses endpointinden adreslerinizi düzenleyebilirsiniz.
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.
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.
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
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
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
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
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
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
items Array (Item) Opsiyonel Ürün listesi. Detaylar için lütfen API Referans Dökümanını inceleyin
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
recipientAddress.cityName String Opsiyonel Şehir adı. Şehir kodu kullanılmadıysa zorunlu.
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.
recipientAddress.districtName String  Opsiyonel İlçe adı. Eğer districtID kullanılmadıysa zorunlu. Örn: Esenyurt
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.
recipientAddress.streetName String Opsiyonel Cadde adı
shipment.productPaymentOnDelivery boolean Opsiyonel Kapıda ödemeli kargo tekliflerini alabilmeyi sağlar. 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ı 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 #

Gönderi oluşturma isteğine cevap aşağıdaki gibidir. Cevaptaki offers alanından teklifleri alabilirsiniz.

{
    "result": true,
    "additionalMessage": "Success",
    "data": {
        "test": true,
        "id": "c0bf54bb-7592-4dee-9600-ad8054257b02",
        "createdAt": "2022-06-24T12:20:34.359396+03:00",
        "updatedAt": "2022-06-24T12:20:34.359396+03:00",
        "amount": "0",
        "currency": "TL",
        "amountLocal": "0",
        "currencyLocal": "TL",
        "amountVat": "0",
        "amountLocalVat": "0",
        "amountTax": "0",
        "amountLocalTax": "0",
        "totalAmount": "0",
        "totalAmountLocal": "0",
        "length": 10,
        "width": 10,
        "height": 10,
        "desi": 1,
        "distanceUnit": "cm",
        "weight": 1,
        "massUnit": "kg",
        "useWeightOfItems": false,
        "useDimensionsOfItems": false,
        "trackingStatus": null,
        "labelFileType": "",
        "hidePackageContentOnTag": false,
        "shipmentDate": null,
        "invoiceGenerated": false,
        "orderID": "0dee7f6b-945b-4867-a2b8-1e3f642b45f4",
        "order": {
            "id": "0dee7f6b-945b-4867-a2b8-1e3f642b45f4",
            "createdAt": "2022-06-24T12:20:34.354659+03:00",
            "updatedAt": "2022-06-24T12:20:34.354659+03:00",
            "itemIDs": null,
            "buyerShippingCost": "15",
            "buyerShippingCostCurrency": "TL",
            "buyerShipmentMethod": "",
            "totalAmount": "100.5",
            "totalTax": "0",
            "sourceCode": "GLV",
            "orderNumber": "",
            "notes": "",
            "organizationID": null
        },
        "senderAddressID": "5d3ce1a0-0a30-4f79-b414-ebbadf1c4e73",
        "senderAddress": null,
        "recipientAddressID": "c1171eab-bc4e-4f3e-917e-cb7c36c6157d",
        "recipientAddress": {
            "id": "c1171eab-bc4e-4f3e-917e-cb7c36c6157d",
            "createdAt": "2022-06-24T12:20:34.352477+03:00",
            "updatedAt": "2022-06-24T12:20:34.352477+03:00",
            "shortName": "",
            "name": "Test Company",
            "email": "Test Email JSON",
            "phone": "Test Phone Json",
            "address1": "Address Test Json 1",
            "address2": "Address Test Json 1-2",
            "cityCode": "45",
            "city": null,
            "state": "",
            "zip": "",
            "districtName": "Yunusemre",
            "district": null,
            "streetID": null,
            "streetName": "4793",
            "countryCode": "TR",
            "source": null,
            "isDefaultSenderAddress": false,
            "isDefaultReturnAddress": false,
            "isActive": true
        },
        "returnAddressID": "5d3ce1a0-0a30-4f79-b414-ebbadf1c4e73",
        "createReturnLabel": false,
        "statusCode": "GOT_OFFERS",
        "offers": {
            "createdAt": "2022-06-24T12:20:34.366922+03:00",
            "updatedAt": "2022-06-24T12:20:34.366922+03:00",
            "cheapest": {
                "id": "afa76ed6-5808-4b5e-b7ea-da20d40bb796",
                "createdAt": "2022-06-24T12:20:34.374952+03:00",
                "updatedAt": "2022-06-24T12:20:34.374952+03:00",
                "amount": "0",
                "currency": "TL",
                "amountLocal": "0",
                "currencyLocal": "TL",
                "amountVat": "0",
                "amountLocalVat": "0",
                "amountTax": "0",
                "amountLocalTax": "0",
                "totalAmount": "0",
                "totalAmountLocal": "0",
                "providerCode": "GELIVER",
                "providerServiceCode": "GELIVER_STANDART",
                "averageEstimatedTime": 140219000000000,
                "averageEstimatedTimeHumanReadible": "02 gün 14 saat",
                "durationTerms": "",
                "rating": 0,
                "isAccepted": false,
                "isGlobal": true,
                "isC2C": true
            },
            "fastest": {
                  "id": "afa76ed6-5808-4b5e-b7ea-da20d40bb796",
                "createdAt": "2022-06-24T12:20:34.374952+03:00",
                "updatedAt": "2022-06-24T12:20:34.374952+03:00",
                "amount": "0",
                "currency": "TL",
                "amountLocal": "0",
                "currencyLocal": "TL",
                "amountVat": "0",
                "amountLocalVat": "0",
                "amountTax": "0",
                "amountLocalTax": "0",
                "totalAmount": "0",
                "totalAmountLocal": "0",
                "providerCode": "GELIVER",
                "providerServiceCode": "GELIVER_STANDART",
                "averageEstimatedTime": 140219000000000,
                "averageEstimatedTimeHumanReadible": "02 gün 14 saat",
                "durationTerms": "",
                "rating": 0,
                "isAccepted": false,
                "isGlobal": true,
                "isC2C": true
            },
            "list": [
                {
                    "id": "afa76ed6-5808-4b5e-b7ea-da20d40bb796",
                    "createdAt": "2022-06-24T12:20:34.374952+03:00",
                    "updatedAt": "2022-06-24T12:20:34.374952+03:00",
                    "amount": "0",
                    "currency": "TL",
                    "amountLocal": "0",
                    "currencyLocal": "TL",
                    "amountVat": "0",
                    "amountLocalVat": "0",
                    "amountTax": "0",
                    "amountLocalTax": "0",
                    "totalAmount": "0",
                    "totalAmountLocal": "0",
                    "providerCode": "GELIVER",
                    "providerServiceCode": "GELIVER_STANDART",
                    "averageEstimatedTime": 140219000000000,
                    "averageEstimatedTimeHumanReadible": "02 gün 14 saat",
                    "durationTerms": "",
                    "rating": 0,
                    "isAccepted": false,
                    "isGlobal": true,
                    "isC2C": true
                }
            ],
            "percentageCompleted": 100,
            "totalOffersRequested": 5,
            "totalOffersCompleted": 5,
            "allowOfferFallback": false
        },
        "acceptedOffer": null,
        "enableAutomation": false,
        "items": [
            {
                "id": "670b44e2-3826-4068-943a-f3e88930ef3f",
                "createdAt": "2022-06-24T12:20:34.355929+03:00",
                "updatedAt": "2022-06-24T12:20:34.355929+03:00",
                "title": "Test product",
                "variantTitle": "",
                "quantity": 1,
                "unitWeight": 0,
                "totalPrice": "0",
                "totalPriceLocal": "0",
                "massUnit": "",
                "unitPrice": "0",
                "currency": null,
                "unitPriceLocal": "0",
                "currencyLocal": "",
                "countryOfOrigin": "",
                "maxShipTime": null,
                "maxDeliveryTime": null,
                "sku": ""
            }
        ],
        "organizationShipmentID": 44,
        "providerBranchName": null,
        "providerInvoiceNo": null,
        "providerReceiptNo": null,
        "providerSerialNo": null
    }
}
Parametreler Açıklama
result İsteğin başarılı olup olmadığını belirtir. true ise başarılıdır.
data Oluşturulan gönderinin kaydı.
code Eğer istek başarısız ise burada hata kodu bulunur
message Eğer istek başarısız ise burada hata mesajı bulunur
additionalMessage Sadece test ortamı için geçerli olan detaylı hata mesajı
data.id Yeni oluşturulan gönderinin id’si.
data.statusCode Gönderi durumu. Bu aşamada “GOT_OFFERS” yani teklifler alındı olacak. Sonraki aşama olan Ödeme yapma aşamasında bu değişecektir.
data.offers Gönderiye yapılan teklifler. Anlık olarak oluşturulmaktadır. Tamamlanan teklif yüzdesini percentageCompleted alanından takip edebilirsiniz.
data.offers.percentageCompleted Tekliflerin tamamlanan yüzdesi. 100 ise tüm teklifler alınmıştır. Eğer 100 değilse /shipments/{id} ile tekrar çağrı yapabilirsiniz. Detaylar için lütfen API Referans Dökümanını inceleyin.
data.offers.totalOffersCompleted Alınan toplam teklif sayısı.
data.offers.list Alınan tüm teklifleri bu alanda fiyatlarıyla görebilirsiniz.
data.offers.list.id Tekliflerin her birinin id’sidir. İstediğiniz ödemeyi kabul etmek için ödeme adımında id alanına ihtiyacınız olacak.
data.offers.list.amount Tekliflerin her birinin fiyatı.
data.offers.list.amountTax Tekliflerin her birinin sadece vergilerinin ücretleri toplamı.
data.offers.list.amountVat Tekliflerin her birinin sadece KDV’sinin ücreti.
data.offers.list.amount Tekliflerin her birinin vergiler hariç ücreti.
data.offers.list.totalAmount Tekliflerin her birinin vergiler dahil toplam ücreti
data.offers.list.currency Tekliflerin her birinin para birimi kısaltması.
data.offers.cheapest Alınan en ucuz teklif. Bu teklifi kabul etmek için, teklifin id alanına ihtiyacınız olacak. Amount ve currency bilgisi tüm tekliflerdeki gibi bulunmakta.
data.offers.fastest Alınan en hızlı teslimat yapabilecek teklif. Bu teklifi kabul etmek için, teklifin id alanına ihtiyacınız olacak. Amount ve currency bilgisi tüm tekliflerdeki gibi bulunmakta
Hata kodları Açıklama
E1054 Gönderi parse edilemedi. İsteğin yanlış olduğunu belirtir.
E1055 Bu işlemi yapmaya yetkiniz yok.
E1053 Organizasyon bulunamadı
E1068 Gönderici adresi (senderAddressID) bulunamadı. Lütfen addresses endpointi ile adresin varolduğunu kontrol edin
E1056 Alıcı adresi oluşturulamadı
E1057 Sipariş oluşturulamadı
E1058 Gönderi kaydedilemedi
E1129 Alıcı adresi boş
E1130 Alıcı şehri boş
E1131 Alıcı ülkesi boş
E1132 Alıcı ilçesi boş
E1133 Alıcı ismi boş
E1134 Alıcı telefon numarası boş
E1136 Alıcı e-posta adresi boş