Inex API Documentation

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

მიმდინარე სერვისით თქვენ შეძლებთ შექმნათ ამანათი Inex Group-ის სისტემაში. სერვისი ავტომატურად ამოწმებს არსებობს თუ არა ამანათი მითითებული თრექინგ კოდით. თუ ამანათი უკვე არსებობს და ის თქვენს ვენდორს ეკუთვნის, დაბრუნდება არსებული ამანათის ინფორმაცია (200 OK). თუ ამანათი სხვა ვენდორის მიერაა რეგისტრირებული, დაბრუნდება შეცდომა (403 Forbidden).

POST /integrators/parcels/create

პარამეტრები

ველი	ტიპი	სავალდებულო	აღწერა
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`.
senderCountryCode	string	Conditional	გამგზავნი ქვეყნის კოდი (ISO 3166-1 alpha-2, მაგ: CN, TR, US). თუ თქვენს ოპერატორზე ქვეყანა მიბმული არ არის, ველი სავალდებულოა; წინააღმდეგ შემთხვევაში გამოიყენება ოპერატორზე მიბმული ქვეყანა. ქვეყანა უნდა იყოს ონლაინ ამანათებისთვის აქტიური.
deliveryType	string	Yes	მიღების ტიპი. Values: `pickupInStore` (ფილიალიდან გატანა), `delivery` (საკურიერო).
pickupLocationId	string	Conditional	ფილიალის კოდი (locationCode). სავალდებულოა თუ deliveryType არის pickupInStore და აკრძალულია, თუ deliveryType არის delivery. იხილეთ ფილიალების სერვისი
receiver.personalId	string	Yes	მიმღების პირადი ნომერი. მაქსიმუმ 255 სიმბოლო.
receiver.firstname	string	Yes	მიმღების სახელი. მაქსიმუმ 255 სიმბოლო.
receiver.lastname	string	Yes	მიმღების გვარი. მაქსიმუმ 255 სიმბოლო.
receiver.phoneNumber	string	Yes	მიმღების ტელეფონის ნომერი. მაქსიმუმ 255 სიმბოლო.
receiver.email	string	No	მიმღების ელ.ფოსტა. მაქსიმუმ 255 სიმბოლო.
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.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	ლოგიკური შეცდომა, მაგალითად: დაფიქსირდა თრექინგ კოდის დუბლირება ან ვერ მოხერხდა მისამართიდან უბნის/ფილიალის ამოცნობა.
404 Not Found	ამანათი მითითებული თრექინგ ნომრით არ მოიძებნა.
403 Forbidden	თქვენ არ გაქვთ ამ ოპერაციის შესრულების უფლება
500 Server Error	ამანათის შექმნისას დაფიქსირდა ხარვეზი, იხილეთ თანდართული მესიჯი

cURL (Pickup in Store) BASH

curl -X POST https://id-staging.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://id-staging.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"
                            }
                        ]
                    }
                }'

Response (200 OK)

JSON Response JSON

{
    "data": {
        "weight": 500,
        "length": 0,
        "height": 0,
        "width": 0,
        "status": "received",
        "subStatus": null,
        "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 (422 - Validation)

JSON Response JSON

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