{"info":{"_postman_id":"ca6fb85e-e9fb-4e2d-9e4f-124bc2fc0a0e","name":"Qapida","description":"

Partnyor üçün Konnektor API

Konnektor partnyorlara qutu məntiqi ilə bağlama məlumatlarını qapida servisinə göndərə bilirlər. Hər qutuda 1-3000 bağlama qəbul edilməsi mümkündür. Qutu adında göndərildiyi tarixin istifadə edilməsi oxunaqlığı artırır. Nümunə: [partnyor] [date: DD:MM:YYYY] - XKargo 24.10.2024 .

Test bağlamaları göndərilərkən zəhmətolmasa qutu adında test sözünü əlavə edin.
Məsələn: XKargo test 24.10.2024

Limit

Dəqiqədə 3 requestdən artıq olduqda 429 xətası qayıdacaqdır.

Geri dönüş

Həmçinin Qapida xidməti Partnyor tərəfindən təqdim edilmiş APİ ünvanına default olaraq aşağıdakı məlumatları qaytaracaqdır.

Bəzi hallarda Qapida xidməti status məlumatını partyorun xidmətinə təqdim etmiş olsada HTTP 201 cavabı almadığı üçün prosesi təkrarlaya bilər. Bu hallarda 3cü tərəfə (müştəri/digər partnyor) təkrar status getməməsi Partyor tərəfindən təmin edilməlidir.

Geri dönüşləri göndərəcək IP ünvanımız: 35.207.189.140

İmza və Şəkillər (POD)

Delivered (Çatdırıldı) və NotDelivered (Çatdırılmadı) statuslarında müştərinin digital imza nümunəsi və şəkillər əlavə olunacaqdır.
\n
Şəkil və imzalar link olaraq təqdim ediləcək, partnyorlar bu link vasitəsi ilə faylları yükləməli və öz sistemində istifadə etməlidir. Linklər təqdim edildiyi andan hər bir link üzrə 10 dəqiqəlik bitmə vaxtı (expire date) olacaqdır. Bu vaxt ərzində partnyor faylları öz sisteminə yükləməlidir.
\n
İmza və Şəkil üçün standart formatlar: PNG, JPEG. Kuryerlərdən fayllar yalnız bu formatlarda qəbul edilir və göndərilir. Faylların orta ölçüsü 250KB.
\n

Geri dönüş: Xətalar

Callback xətası baş verərsə, callback avtomatik təkrarlanacaqdır. Bu proses 1 saatlıq fasilələrlə xəta düzələnə və ya maksimum 5 dəfəyə qədər təkrarlanır. Əgər xəta davam edərsə məlumatın göndərilməsi mümkün olmayacaq və status məlumatı üçün Qapida Partyor Portalından istifadə edilməlidir.
\n
Şəkillərin yüklənmə mərhələsində xəta baş verərsə qapida tərəfində bu görünmür. Bu halda GET endpoint istifadə edilməli və məlumatlar APİ vasitəsi ilə yenidən çəkilməlidir. İmza və şəkillər təkrar olaraq 10 dəqiqəlik bitmə vaxtı ilə göndəriləcəkdir. GET hər barkod üzrə maksimum 2 dəfə istifadə edilə bilər. Əgər uğursuz olarsa mlumatlar üçün Qapida Partnyor Portalı istifadə edilməlidir
\n

Status Kodları

Aşağıdakı statuslar geri dönüş məlumatlarında olacaqdır:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status Kodu	Açıqlama
0	Qəbul edildi (Anbar bağlamanı yoxladı və qəbul etdi)
4	Yoldadır (Kuryer bağlamanı çatdırılma üçün qəbul etdi)
5	Çatdırıldı
6	Çatdırılmadı (Bağlama geri qaytarıldı)
7	İmtina edildi (Bağlama əməliyyatsız geri qaytarıldı - müxtəlif səbəblərdən)

Reason

if Status == 6 then reason = (RecipientNotFound || WrongAddress || RefusedByRecipient || NoAccess)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Reason (Səbəb)	Açıqlama
RecipientNotFound	Telefon zəngi cavablandırılmadı, çatdırılma ünvanında heç kim yoxdur, səhv FIN kodu (təqdim edilən sənədin FIN kodu uyğun gəlmir)
WrongAddress	Ünvan aydın deyil, yalnış göstərilib
RefusedByRecipient	Müştəri bağlamadan imtina etdi, filialdan özü götürəcək
NoAccess	Giriş yoxdur, ünvana çatmaq mümkün deyil

[\n {\n    \"barcode\": \"XXX0208408162\",\n    \"status\": 6,\n    \"reason\": \"WrongAddress\",\n    \"signature_url\":\"customer_signature_image_url\",\n    \"images\":[\"image_url_10_minute_expire_1\",\"image_url_10_minute_expire_2\"]\n }\n]\n\n

Partnyor APİ-ni özündə tətbiq etdikdən sonra Test üçün Host və APİKey almalıdır. Host partnyora unikal hazırlanır. APİKey partnyora unikal olaraq yaradılır və authentication üçün istifadə edilir. APİKey olmadıqda 401 xətası qayıdacaqdır.

\n
Bəzi hallarda bağlama məlumatları yalnışlıqla Qapida xidmətinə göndərilə bilər. Bu hallarda Qapıda xidmətində bu bağlama statusu imtina olaraq göstərilir və bağlama fiziki olaraqq qəbul edilibsə geri qaytarılır.
\n

Partyor hemçinin geri dönüşlərdə sinxronizasiya üçün header de olan X-Request-ID-ni istifade ede biler. Bu id her emeliyyata unique yaradilir.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"11395166","collectionId":"ca6fb85e-e9fb-4e2d-9e4f-124bc2fc0a0e","publishedId":"2s9YeA9E8V","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2023-11-21T07:45:22.000Z"},"item":[{"name":"Delivery order bağlama məlumatlarını əlavə et","id":"4dc97131-80fe-4fd1-8a23-1630708ed7be","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PUT","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"uid\": \"Test 23.03.2026\",\n \"items\": [\n {\n \"barcode\": \"AZ200005\",\n \"tr_barcode\": \"AZ200005\",\n \"company\": {\n \"name\": \"Postcargo Temu\",\n \"barcode\": \"AZ200005\"\n },\n \"customer_uid\": \"5QS2L2M\",\n \"customer_fin\": \"5QS2L2M\",\n \"customer_name\": \"samir\",\n \"customer_phone\": \"+994517133322\",\n \"customer_surname\": \"dadaşov\",\n \"customer_available\": \"\",\n \"delivery_address\": \"ə qarayəv 3\",\n \"delivery_city\": \"\",\n \"delivery_region\": \"\",\n \"current_status\": \"\",\n \"current_place\": \"\",\n \"date\": 1773914672,\n \"longitude\": 0,\n \"latitude\": 0,\n \"package_weight\": \"0.09\",\n \"package_dimensions\": \"\",\n \"option\": \"\"\n },\n {\n \"barcode\": \"AZ200006\",\n \"tr_barcode\": \"AZ200006\",\n \"company\": {\n \"name\": \"Postcargo Temu\",\n \"barcode\": \"AZ200006\"\n },\n \"customer_uid\": \"5QS2L3M\",\n \"customer_fin\": \"5QS2L3M\",\n \"customer_name\": \"samir\",\n \"customer_phone\": \"+994517133322\",\n \"customer_surname\": \"dadaşov\",\n \"customer_available\": \"\",\n \"delivery_address\": \"ə qarayəv 3\",\n \"delivery_city\": \"\",\n \"delivery_region\": \"\",\n \"current_status\": \"\",\n \"current_place\": \"\",\n \"date\": 1773914672,\n \"longitude\": 0,\n \"latitude\": 0,\n \"package_weight\": \"0.09\",\n \"package_dimensions\": \"\",\n \"option\": \"\"\n },\n {\n \"barcode\": \"AZ200006\",\n \"tr_barcode\": \"AZ200006\",\n \"company\": {\n \"name\": \"Postcargo Temu\",\n \"barcode\": \"AZ200006\"\n },\n \"customer_uid\": \"5QS2L3M\",\n \"customer_fin\": \"5QS2L3M\",\n \"customer_name\": \"samir\",\n \"customer_phone\": \"+994517133322\",\n \"customer_surname\": \"dadaşov\",\n \"customer_available\": \"\",\n \"delivery_address\": \"ə qarayəv 3\",\n \"delivery_city\": \"\",\n \"delivery_region\": \"\",\n \"current_status\": \"\",\n \"current_place\": \"\",\n \"date\": 1773914672,\n \"longitude\": 0,\n \"latitude\": 0,\n \"package_weight\": \"0.09\",\n \"package_dimensions\": \"\",\n \"option\": \"\"\n },\n {\n \"barcode\": \"AZ200007\",\n \"tr_barcode\": \"AZ200007\",\n \"company\": {\n \"name\": \"Postcargo Temu\",\n \"barcode\": \"AZ200007\"\n },\n \"customer_uid\": \"5QS2L4M\",\n \"customer_fin\": \"5QS2L4M\",\n \"customer_name\": \"samir\",\n \"customer_phone\": \"+994517133322\",\n \"customer_surname\": \"dadaşov\",\n \"customer_available\": \"\",\n \"delivery_address\": \"ə qarayəv 3\",\n \"delivery_city\": \"\",\n \"delivery_region\": \"\",\n \"current_status\": \"\",\n \"current_place\": \"\",\n \"date\": 1773914672,\n \"longitude\": 0,\n \"latitude\": 0,\n \"package_weight\": \"0.09\",\n \"package_dimensions\": \"\",\n \"option\": \"\"\n },\n {\n \"barcode\": \"AZ200008\",\n \"tr_barcode\": \"AZ200008\",\n \"company\": {\n \"name\": \"Postcargo Temu\",\n \"barcode\": \"AZ200008\"\n },\n \"customer_uid\": \"5QS2L5M\",\n \"customer_fin\": \"5QS2L5M\",\n \"customer_name\": \"samir\",\n \"customer_phone\": \"+994517133322\",\n \"customer_surname\": \"dadaşov\",\n \"customer_available\": \"\",\n \"delivery_address\": \"ə qarayəv 3\",\n \"delivery_city\": \"\",\n \"delivery_region\": \"\",\n \"current_status\": \"\",\n \"current_place\": \"\",\n \"date\": 1773914672,\n \"longitude\": 0,\n \"latitude\": 0,\n \"package_weight\": \"0.09\",\n \"package_dimensions\": \"\",\n \"option\": \"\"\n }\n ]\n }"},"url":"{{host-staging}}/v1/packages?key={{api-key-staging}}","description":"

Bağlamaların əlavə edilməsi üçün:

Əsas uid qutu adı olaraq istifadə edilir. Partyorla bağlama məlumatlarının sinxronizasiyası üçün istifadə edilir. Eyni qutu adı bir neçə requestdə göndərilə bilər. Hər yeni bağlama məlumatı qutuya əlavə ediləcəkdir. Məsələn: \"PartnyorAdı 01.01.2022\"

{\n\"uid\": \"main_uid\"\n\n

Müştərilər bir çox hallarda daxili barkodları tanımadıqları üçün satıcı tərəfindən təqdim edilən məlumatların göstərilməsi prosesi sürətləndirir. Bağlama məlumatlarında satıcının adı və satıcı tərəfindən təqdim edilən barkod.

\"company\": {\n    \"name\":\"temu\",\n    \"barcode\":\"TRM723472364\"\n},\n\n

CustomerUid partyorun servisində alıcıya uyğun unikal nömrədir. Partyorla yarana biləcək xətaların aradan qaldırılmasında istifadə edilir. Olmadıqda FinKod və ya telefon nömrəsi göndərilə bilər.

...\n\"customer_uid\":\"\",\n...\n\n

Aşağıdakı məlumatlar tələb olunan məlumatlardır. Hər hansı biri olmadıqda geri xəta qaytarılacaqdır.

{\n    \"uid\": \"required\",\n    \"items\": [\n        {\n            \"barcode\": \"required\",\n            \"company\": {\n                \"name\": \"temu\",\n                \"barcode\": \"TRM723472364\"\n            },\n            \"customer_uid\": \"required\",\n            \"customer_fin\": \"required\",\n            \"customer_name\": \"required\",\n            \"customer_surname\": \"required\",\n            \"customer_phone\": \"required\",\n            \"delivery_address\": \"required\",\n            \"date\": 1606711656,\n            \"status\":\"required\",\n        }\n    ]\n}\n\n

Barkod məlumatı üçün bağlamanın üzərində skanerlərlə rahat oxuna bilən və bağlamaya unikal olan barkod istifadə edilməlidir.

Müştərilərin bütün əlaqə nömrələri beynəlxalq formatda göndərilməlidir. Nümunə: 994 xx xxx xx xx

\n","urlObject":{"path":["v1","packages"],"host":["{{host-staging}}"],"query":[{"key":"key","value":"{{api-key-staging}}"}],"variable":[]}},"response":[],"_postman_id":"4dc97131-80fe-4fd1-8a23-1630708ed7be"},{"name":"Delivery Order bağlama məlumatı","id":"ac55da41-9ee4-4d63-a588-0a481116d4de","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""},"url":"{{host-staging}}/v1/packages?key={{api-key-staging-2}}&barcode=XXX0208408162","description":"

Bağlama məlumatının əldə edilməsi üçün:

Hər bağlama üzrə maksimum 2 dəfə istifadə edilə bilər. Əgər xəta baş verərsə uyğun məlumatlar Qapida Partnyor Portalından əldə edilməlidir. APi yalnız tamamlanmış (Delivered, Not delivered) bağlamalar haqqında məlumatları təqdim edir.

Tamamlanmamış bağlamalar üçün HTTP 202 status kodu qaytarılacaqdır.

HTTP 404 - > 2 request

Response - status kode HTTP 200:

{\n    \"barcode\": \"XXX0208408162\",\n    \"status\": 6,\n    \"reason\": \"WrongAddress\",\n   \"signature_url\": \"https://example.com/signature.jpg\",\n   \"images\": [\n      \"https://example.com/image1.jpg\",\n      \"https://example.com/image2.jpg\"\n   ]\n}\n\n

APİ üzrə 60 request / dəqiqə limit əlavə edilmişdir.

\n","urlObject":{"path":["v1","packages"],"host":["{{host-staging}}"],"query":[{"key":"key","value":"{{api-key-staging-2}}"},{"key":"barcode","value":"XXX0208408162"}],"variable":[]}},"response":[],"_postman_id":"ac55da41-9ee4-4d63-a588-0a481116d4de"}]}