Inex API Documentation

ამანათის შექმნა

მიმდინარე სერვისით თქვენ შეძლებთ შექმნათ ამანათი Inex Group-ის სისტემაში. სერვისი ავტომატურად ამოწმებს არსებობს თუ არა ამანათი მითითებული თრექინგ კოდით. თუ ამანათი უკვე არსებობს და ის თქვენს ვენდორს ეკუთვნის, დაბრუნდება არსებული ამანათის ინფორმაცია (200 OK). თუ ამანათი სხვა ვენდორის მიერაა რეგისტრირებული, დაბრუნდება შეცდომა (403 Forbidden). ველით parcelType ირჩევთ ამანათის ტიპს: online (ონლაინ ამანათი, ნაგულისხმევი) ან internalShipment (შიდა გზავნილი საქართველოს ფარგლებში). რომელი ტიპის შექმნა შეუძლია თქვენს ოპერატორს, განსაზღვრავს Inex Group-ის ადმინისტრატორი; ნებადაურთველი ტიპის მოთხოვნაზე დაბრუნდება 403 Forbidden.

POST /integrators/parcels/create

პარამეტრები

ველი	ტიპი	სავალდებულო	აღწერა
parcelType	string	No	ამანათის ტიპი. თუ არ გადმოეცემა, იქმნება ონლაინ ამანათი. გამოიყენეთ მხოლოდ თქვენს ოპერატორზე ნებადართული ტიპი, სხვა შემთხვევაში დაბრუნდება 403. Values: `online` (ონლაინ ამანათი), `internalShipment` (შიდა გზავნილი, საქართველო → საქართველო). internalShipment: გამგზავნი ფილიალი არის თქვენს ოპერატორზე მიბმული ფილიალი, გადაზიდვა ყოველთვის სახმელეთოა (byRoad), ტარიფი — თქვენს ოპერატორზე მიბმული ტარიფი. მიმღების ფილიალი/საკურიერო მისამართი უნდა იყოს საქართველოში. დანარჩენი ველები (მიმღები, დეკლარაცია, მიწოდება) იგივეა, რაც ონლაინ ამანათისთვის.
clientReferenceId	string	No	თქვენი შიდა ID (მაგ. შეკვეთის ნომერი). მაქსიმუმ 255 სიმბოლო.
waybillNumbers	array	Yes	თრექინგ კოდების მასივი.
waybillNumbers.*	string	Yes	თრექინგ კოდი. მაქსიმუმ 255 სიმბოლო.
status	string	Yes	ამანათის სტატუსი. Values: `created` (წინასწარი), `received` (მიღებული), `pending` (გამოგზავნილი).
weight	integer	Conditional	წონა გრამებში. სავალდებულოა თუ სტატუსია received ან pending.
width / height / length	integer	No	ზომები მილიმეტრებში.
shipmentType	string	Yes	გადაზიდვის ტიპი. Values: `byAir`, `bySea`, `byTrain`, `byRoad`. internalShipment ტიპზე მნიშვნელობა არ გამოიყენება — გადაზიდვა ყოველთვის byRoad-ია.
senderCountryCode	string	Conditional	გამგზავნი ქვეყნის კოდი (ISO 3166-1 alpha-2, მაგ: CN, TR, US). თუ თქვენს ოპერატორზე ქვეყანა მიბმული არ არის, ველი სავალდებულოა; წინააღმდეგ შემთხვევაში გამოიყენება ოპერატორზე მიბმული ქვეყანა. ქვეყანა უნდა იყოს ონლაინ ამანათებისთვის აქტიური. internalShipment ტიპზე ველის გადმოცემა აკრძალულია (422) — გამგზავნი ქვეყანა ყოველთვის საქართველოა.
deliveryType	string	Yes	მიღების ტიპი. Values: `pickupInStore` (ფილიალიდან გატანა), `delivery` (საკურიერო).
pickupLocationId	string	Conditional	ფილიალის კოდი (locationCode). სავალდებულოა თუ deliveryType არის pickupInStore და აკრძალულია, თუ deliveryType არის delivery. იხილეთ ფილიალების სერვისი
receiver.inexUserId	string (uuid)	Conditional	INEX SSO-ით შესული მომხმარებლის იდენტიფიკატორი (id_token-ის sub). მიმღები მიეთითება ან სრულად (personalId, firstname, lastname, phoneNumber), ან მხოლოდ ამ ველით. ახალი ანგარიში არ იქმნება. იხილეთ INEX SSO
receiver.personalId	string	Conditional	მიმღების პირადი ნომერი. მაქსიმუმ 255 სიმბოლო. სავალდებულოა, თუ receiver.inexUserId არ არის გადმოცემული; inexUserId-თან ერთად არასავალდებულოა და მხოლოდ მაშინ ჩაიწერება, თუ ანგარიშს პირადი ნომერი არ აქვს.
receiver.firstname	string	Conditional	მიმღების სახელი. მაქსიმუმ 255 სიმბოლო. სავალდებულოა, თუ receiver.inexUserId არ არის გადმოცემული; inexUserId-თან ერთად აკრძალულია.
receiver.lastname	string	Conditional	მიმღების გვარი. მაქსიმუმ 255 სიმბოლო. სავალდებულოა, თუ receiver.inexUserId არ არის გადმოცემული; inexUserId-თან ერთად აკრძალულია.
receiver.phoneNumber	string	Conditional	მიმღების ტელეფონის ნომერი. მაქსიმუმ 255 სიმბოლო. სავალდებულოა, თუ receiver.inexUserId არ არის გადმოცემული; inexUserId-თან ერთად აკრძალულია.
receiver.email	string	No	მიმღების ელ.ფოსტა. მაქსიმუმ 255 სიმბოლო. inexUserId-თან ერთად აკრძალულია.
deliveryDetail	object	Conditional	მისამართის ობიექტი. სავალდებულოა თუ deliveryType არის delivery და აკრძალულია ყველა სხვა შემთხვევაში.
deliveryDetail.city	string	Conditional	ქალაქის სახელი. სავალდებულოა თუ deliveryType არის delivery. მაქსიმუმ 255 სიმბოლო.
deliveryDetail.address	string	Conditional	ზუსტი მისამართი. სავალდებულოა თუ deliveryType არის delivery. მაქსიმუმ 1000 სიმბოლო.
deliveryDetail.district	string	No	უბანი. მაქსიმუმ 255 სიმბოლო.
deliveryDetail.latitude	number	No	მისამართის განედი (latitude).
deliveryDetail.longitude	number	No	მისამართის გრძედი (longitude).
declaration.sourceUrl	string (url)	Yes	გამოწერის წყარო (ვებ-გვერდი).
declaration.currencyCode	string	Yes	ვალუტის კოდი (მაგ: USD, EUR, GEL). ზუსტად 3 სიმბოლო.
declaration.fileUids	array (uuids)	No	ატვირთული ფაილების ID-ები (ინვოისი). იხილეთ ფაილის ატვირთვის სერვისი
declaration.items	array	Yes	ნივთების მასივი. მინიმუმ 1 ელემენტი.
declaration.items.*.description	string	Yes	ნივთის აღწერა. მაქსიმუმ 5000 სიმბოლო.
declaration.items.*.price	integer	Yes	ნივთის ფასი ცენტებში/თეთრებში (მაგ: 10.50$ = 1050). მინიმუმ 0.
declaration.items.*.quantity	integer	Yes	რაოდენობა. მინიმუმ 1.
declaration.items.*.categoryName	string	No	კატეგორიის სახელი. მაქსიმუმ 255 სიმბოლო.
declaration.items.*.pictureUrl	string (url)	No	ნივთის სურათის ლინკი. მაქსიმუმ 5000 სიმბოლო.

შენიშვნა მისამართის ამოცნობაზე (სახლში მიწოდება)

თუ ირჩევთ საკურიერო მიწოდებას (delivery), სასურველია მიუთითოთ უბანი (district). იმ შემთხვევაში თუ უბანი ცარიელია ან არასწორია, სისტემა შეეცდება მითითებული მისამართის (address) ტექსტიდან ავტომატურად ამოიცნოს შესაბამისი უბანი. თუ ამოცნობა ვერ მოხერხდა ან ამოცნობილ უბანს არ ემსახურება ფილიალი, სისტემა დააბრუნებს 400 სტატუსს შესაბამისი შეტყობინებით.

პასუხის სტრუქტურა 200 OK

Attribute	Type	Value	Description
data.weight	integer	1551	ამანათის წონა გრამებში.
data.length	integer	318	ამანათის სიგანე მილიმეტრებში.
data.height	integer	684	ამანათის სიმაღლე მილიმეტრებში.
data.width	integer	489	ამანათის სიგრძე მილიმეტრებში.
data.status	string	disposed	ამანათის სტატუსი. შესაძლო ვარიანტები: created, received, pending, arrived, takeout, returned, confiscated, lost, dropOfDate, damaged, compensated, notCompensated, returnToSellerIsInProgress, disposed, stored, form4, temporarilySuspended
data.subStatus	string\|null	null	ამანათის ქვე-სტატუსი. შეიძლება იყოს null. შესაძლო ვარიანტები: readyForTerminal, goingToTerminal, arrivedAtTerminalStored, readyFromTerminal, comingFromTerminal, arrivedAtBranch, readyForCustoms, goingToCustoms, arrivedAtCustomsStored, readyFromCustoms, comingFromCustoms, readyForTerminalTakeout
data.parcelType	string	internalShipment	ამანათის ტიპი: online ან internalShipment.
data.deliveryType	string	pickupInStore	მიღების ტიპი: pickupInStore (ფილიალიდან გატანა) ან delivery (საკურიერო).
data.senderCountry.name	string	United States	გამომგზავნი ქვეყნის სახელი ლათინურად.
data.senderCountry.code	string	US	გამომგზავნი ქვეყნის კოდი - ISO 3166-1 alpha-2.
data.receiverCity.name	string	Tbilisi	მიმღები ქალაქის სახელი ლათინურად.
data.receiverPickupLocation.locationCode	string	200001	ფილიალის კოდი. სწორედ ეს მნიშვნელობა უნდა გადმოგვცეთ ამანათის შექმნისას pickupLocationId-ში.
data.receiverPickupLocation.name	string	Isani	მიმღები ფილიალის სახელი ლათინურად.
data.receiverPickupLocation.address	string	Isani, Atskuri Street #45	მიმღები ფილიალის მისამართი ლათინურად.
data.receiverPickupLocation.phone	string	(0322) 2222222	მიმღები ფილიალის ტელეფონის ნომერი.
data.receiverPickupLocation.latitude	float	56.961032	მიმღები ფილიალის კოორდინატი.
data.receiverPickupLocation.longitude	float	94.614571	მიმღები ფილიალის კოორდინატი.
data.receiverPickupLocation.postalCode	string	Isani	მიმღები ფილიალის საფოსტო ინდექსი.
data.waybillNumbers	array	[]	ამანათის თრექინგ კოდების მასივი.
data.waybillNumbers.*	string	eqweqwecwrekjewqionwqe.ewqe1eqq	ამანათის თრექინგ კოდი.

სტატუსების აღწერა

იხილეთ სტატუსების აღწერა ამანათის დეტალებში

შესაძლო პასუხები

Code	Description
200 OK	ამანათის ობიექტი.
400 Bad Request	ლოგიკური შეცდომა, მაგალითად: დაფიქსირდა თრექინგ კოდის დუბლირება ან ვერ მოხერხდა მისამართიდან უბნის/ფილიალის ამოცნობა.
422 Unprocessable	ვალიდაციის შეცდომა, მაგალითად: მიმღები არ არის მითითებული, receiver.inexUserId უცნობია ან გადმოცემულია სხვა receiver ველებთან ერთად.
404 Not Found	ამანათი მითითებული თრექინგ ნომრით არ მოიძებნა.
403 Forbidden	თქვენ არ გაქვთ ამ ოპერაციის შესრულების უფლება, მაგალითად: მოთხოვნილი parcelType თქვენს ოპერატორზე ნებადართული არ არის, ან internalShipment-ისთვის ოპერატორზე არ არის მიბმული ტარიფი ან გამგზავნი ფილიალი.
500 Server Error	ამანათის შექმნისას დაფიქსირდა ხარვეზი, იხილეთ თანდართული მესიჯი

cURL (Pickup in Store) BASH

curl -X POST https://api.inex.ge/api/v1/integrators/parcels/create \
                -H "Authorization: Bearer {TOKEN}" \
                -H "Content-Type: application/json" \
                -d '{
                    "clientReferenceId": "ORDER-12345",
                    "waybillNumbers": ["TRACK-001"],
                    "status": "received",
                    "weight": 500,
                    "shipmentType": "byAir",
                    "senderCountryCode": "CN",
                    "deliveryType": "pickupInStore",
                    "pickupLocationId": "200001",
                    "receiver": {
                        "personalId": "01024085678",
                        "firstname": "John",
                        "lastname": "Doe",
                        "phoneNumber": "555123456",
                        "email": "john@example.com"
                    },
                    "declaration": {
                        "sourceUrl": "https://amazon.com",
                        "currencyCode": "USD",
                        "items": [
                            {
                                "price": 1000,
                                "quantity": 1,
                                "description": "T-Shirt"
                            }
                        ]
                    }
                }'

cURL (Courier Delivery) BASH

curl -X POST https://api.inex.ge/api/v1/integrators/parcels/create \
                -H "Authorization: Bearer {TOKEN}" \
                -H "Content-Type: application/json" \
                -d '{
                    "waybillNumbers": ["TRACK-DEL-001"],
                    "status": "received",
                    "weight": 1200,
                    "shipmentType": "byAir",
                    "senderCountryCode": "TR",
                    "deliveryType": "delivery",
                    "deliveryDetail": {
                        "city": "Tbilisi",
                        "address": "Chavchavadze Ave 1",
                        "district": "Vake"
                    },
                    "receiver": {
                        "personalId": "01024085678",
                        "firstname": "Jane",
                        "lastname": "Doe",
                        "phoneNumber": "555987654"
                    },
                    "declaration": {
                        "sourceUrl": "https://ebay.com",
                        "currencyCode": "USD",
                        "items": [
                            {
                                "price": 5000,
                                "quantity": 1,
                                "description": "Sneakers"
                            }
                        ]
                    }
                }'

cURL (Internal Shipment) BASH

curl -X POST https://api.inex.ge/api/v1/integrators/parcels/create \
                -H "Authorization: Bearer {TOKEN}" \
                -H "Content-Type: application/json" \
                -d '{
                    "parcelType": "internalShipment",
                    "clientReferenceId": "ORDER-77881",
                    "waybillNumbers": ["SHOP-000123"],
                    "status": "received",
                    "weight": 1500,
                    "shipmentType": "byRoad",
                    "deliveryType": "pickupInStore",
                    "pickupLocationId": "200001",
                    "receiver": {
                        "personalId": "01024085678",
                        "firstname": "Nino",
                        "lastname": "Beridze",
                        "phoneNumber": "555123456"
                    },
                    "declaration": {
                        "sourceUrl": "https://shop.example.ge",
                        "currencyCode": "GEL",
                        "items": [
                            {
                                "price": 2500,
                                "quantity": 1,
                                "description": "Headphones"
                            }
                        ]
                    }
                }'

Response (200 OK)

JSON Response JSON

{
    "data": {
        "weight": 500,
        "length": 0,
        "height": 0,
        "width": 0,
        "status": "received",
        "subStatus": null,
        "parcelType": "online",
        "senderCountry": {
            "name": "United States",
            "code": "US"
        },
        "deliveryType": "pickupInStore",
        "receiverCity": {
            "name": "Tbilisi"
        },
        "receiverPickupLocation": {
            "locationCode": "200001",
            "name": "Vake Branch",
            "address": "Chavchavadze Ave 33",
            "phone": "(032) 2222222",
            "latitude": 41.7151,
            "longitude": 44.7271,
            "postalCode": "0179"
        },
        "waybillNumbers": [
            "TRACK-001"
        ]
    }
}

Error Response (403 - Exists for other vendor)

JSON Response JSON

{
    "errors": {
        "general": [
            "Parcel is already processed by another vendor."
        ]
    },
    "message": "error"
}

Error Response (403 - Parcel type not allowed)

JSON Response JSON

{
    "errors": {
        "general": [
            "You are not allowed to create parcels of type internalShipment, please contact administrator."
        ]
    },
    "message": "error"
}

Error Response (422 - Validation)

JSON Response JSON

{
    "errors": {
        "pickupLocationId": [
            "The pickup location id field is required when delivery type is pickupInStore."
        ]
    },
    "message": "error"
}

cURL (Receiver by INEX SSO) BASH

curl -X POST https://api.inex.ge/api/v1/integrators/parcels/create \
                -H "Authorization: Bearer {TOKEN}" \
                -H "Content-Type: application/json" \
                -d '{
                    "waybillNumbers": ["TRACK-002"],
                    "status": "created",
                    "shipmentType": "byAir",
                    "senderCountryCode": "CN",
                    "deliveryType": "pickupInStore",
                    "pickupLocationId": "200001",
                    "receiver": {
                        "inexUserId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
                    },
                    "declaration": {
                        "sourceUrl": "https://shop.example.com",
                        "currencyCode": "USD",
                        "items": [{ "price": 2500, "quantity": 1, "description": "T-Shirt" }]
                    }
                }'