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 http://api.geliver.io/api/v1/shipments \
  --header 'Authorization: Bearer cb611162-541f-4fb3-a353-586e2013fb31' \
  --header 'Content-Type: application/json' \
  --data '{
	"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",
		"address2": "",
		"countryCode": "TR",
		"countryName": "Türkiye"
		"cityName": "Manisa",
		"cityCode": "45",
		"districtName": "Yunusemre",
		"streetName": "4793",
	},
}'
Parametreler Tip Zorunluluk Açıklama
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 Eğer kargo boyutları ve/ve ağırlığı 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 Float 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 Float 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 Float 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 Float 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. Ş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.
metadata Object (ShipmentMetadata) Opsiyonel Gönderi için ekstra ayarları yapabilirsiniz. Detay için aşağıya baknız.
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.metadata Object Opsiyonel Aşağıdaki açıklamayı okuyun

Metadata #

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.
reference1 Barkod üzerinde çıkmasını istediğiniz sipariş kodu

{
    "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": {
        "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",
            "cityName": "Manisa",
            "city": null,
            "state": "",
            "zip": "",
            "districtID": 108740,
            "districtName": "Yunusemre",
            "district": null,
            "streetID": null,
            "streetName": "4793",
            "countryCode": "TR",
            "countryName": "",
            "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": "10.75",
                "currency": "TL",
                "amountLocal": "10.75",
                "currencyLocal": "TL",
                "amountVat": "1.99",
                "amountLocalVat": "1.99",
                "amountTax": "0.26",
                "amountLocalTax": "25.27",
                "totalAmount": "12.99",
                "totalAmountLocal": "12.99",
                "providerCode": "SURAT",
                "providerServiceCode": "SURAT_STANDART",
                "averageEstimatedTime": 140219000000000,
                "averageEstimatedTimeHumanReadible": "02 gün 14 saat",
                "durationTerms": "",
                "rating": 0,
                "isAccepted": false,
                "isGlobal": true,
                "isC2C": true
            },
            "fastest": {
                "id": "9ac749a6-661f-4dcc-836c-9cc9b6e7d32b",
                "createdAt": "2022-06-24T12:20:34.372615+03:00",
                "updatedAt": "2022-06-24T12:20:34.372615+03:00",
                "amount": "14.5",
                "currency": "TL",
                "amountLocal": "14.5",
                "currencyLocal": "TL",
                "amountVat": "2.68",
                "amountLocalVat": "2.68",
                "amountTax": "0.35",
                "amountLocalTax": "34.08",
                "totalAmount": "17.52",
                "totalAmountLocal": "17.52",
                "providerCode": "YURTICI",
                "providerServiceCode": "YURTICI_STANDART",
                "averageEstimatedTime": 117401000000000,
                "averageEstimatedTimeHumanReadible": "02 gün 08 saat",
                "durationTerms": "",
                "rating": 0,
                "isAccepted": false,
                "isGlobal": true,
                "isC2C": false
            },
            "list": [
                {
                    "id": "f4934e21-09b5-4994-bbf2-4e17c3d38530",
                    "createdAt": "2022-06-24T12:20:34.369703+03:00",
                    "updatedAt": "2022-06-24T12:20:34.369703+03:00",
                    "amount": "13.75",
                    "currency": "TL",
                    "amountLocal": "13.75",
                    "currencyLocal": "TL",
                    "amountVat": "2.54",
                    "amountLocalVat": "2.54",
                    "amountTax": "0.33",
                    "amountLocalTax": "32.32",
                    "totalAmount": "16.61",
                    "totalAmountLocal": "16.61",
                    "providerCode": "MNG",
                    "providerServiceCode": "MNG_STANDART",
                    "averageEstimatedTime": 228848000000000,
                    "averageEstimatedTimeHumanReadible": "03 gün 15 saat",
                    "durationTerms": "",
                    "rating": 0,
                    "isAccepted": false,
                    "isGlobal": true,
                    "isC2C": false
                },
                {
                    "id": "9ac749a6-661f-4dcc-836c-9cc9b6e7d32b",
                    "createdAt": "2022-06-24T12:20:34.372615+03:00",
                    "updatedAt": "2022-06-24T12:20:34.372615+03:00",
                    "amount": "14.5",
                    "currency": "TL",
                    "amountLocal": "14.5",
                    "currencyLocal": "TL",
                    "amountVat": "2.68",
                    "amountLocalVat": "2.68",
                    "amountTax": "0.35",
                    "amountLocalTax": "34.08",
                    "totalAmount": "17.52",
                    "totalAmountLocal": "17.52",
                    "providerCode": "YURTICI",
                    "providerServiceCode": "YURTICI_STANDART",
                    "averageEstimatedTime": 117401000000000,
                    "averageEstimatedTimeHumanReadible": "02 gün 08 saat",
                    "durationTerms": "",
                    "rating": 0,
                    "isAccepted": false,
                    "isGlobal": true,
                    "isC2C": false
                },
                {
                    "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": "10.75",
                    "currency": "TL",
                    "amountLocal": "10.75",
                    "currencyLocal": "TL",
                    "amountVat": "1.99",
                    "amountLocalVat": "1.99",
                    "amountTax": "0.26",
                    "amountLocalTax": "25.27",
                    "totalAmount": "12.99",
                    "totalAmountLocal": "12.99",
                    "providerCode": "SURAT",
                    "providerServiceCode": "SURAT_STANDART",
                    "averageEstimatedTime": 140219000000000,
                    "averageEstimatedTimeHumanReadible": "02 gün 14 saat",
                    "durationTerms": "",
                    "rating": 0,
                    "isAccepted": false,
                    "isGlobal": true,
                    "isC2C": true
                },
                {
                    "id": "54232abb-e3bc-430c-ae00-6bc77d96649b",
                    "createdAt": "2022-06-24T12:20:34.377362+03:00",
                    "updatedAt": "2022-06-24T12:20:34.377362+03:00",
                    "amount": "15",
                    "currency": "TL",
                    "amountLocal": "15",
                    "currencyLocal": "TL",
                    "amountVat": "2.77",
                    "amountLocalVat": "2.77",
                    "amountTax": "0.36",
                    "amountLocalTax": "35.25",
                    "totalAmount": "18.12",
                    "totalAmountLocal": "18.12",
                    "providerCode": "PTT",
                    "providerServiceCode": "PTT_STANDART",
                    "averageEstimatedTime": 147401000000000,
                    "averageEstimatedTimeHumanReadible": "02 gün 16 saat",
                    "durationTerms": "",
                    "rating": 0,
                    "isAccepted": false,
                    "isGlobal": true,
                    "isC2C": false
                },
                {
                    "id": "a7ff2e77-5e80-4867-a151-9d640e827f8c",
                    "createdAt": "2022-06-24T12:20:34.380314+03:00",
                    "updatedAt": "2022-06-24T12:20:34.380314+03:00",
                    "amount": "0",
                    "currency": "TL",
                    "amountLocal": "0",
                    "currencyLocal": "TL",
                    "amountVat": "0",
                    "amountLocalVat": "0",
                    "amountTax": "0",
                    "amountLocalTax": "0",
                    "totalAmount": "0",
                    "totalAmountLocal": "0",
                    "providerCode": "SURAT",
                    "providerServiceCode": "SURAT_STANDART",
                    "averageEstimatedTime": 140219000000000,
                    "averageEstimatedTimeHumanReadible": "02 gün 14 saat",
                    "durationTerms": "",
                    "rating": 0,
                    "isAccepted": false,
                    "isGlobal": false,
                    "isC2C": false
                }
            ],
            "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.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ş