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 |