Въведение

Tekra API предоставя удобен начин за интеграция с нашата система за управление на поръчки. Тази документация ще ви запознае с основните методи за работа с API-то, включително създаване на поръчки и проверка на техния статус.

Endpoints

Production Endpoint Метод Описание
https://tekra.bg/api/v1/orders/create POST Създава нова поръчка.
https://tekra.bg/api/v1/orders/status GET Връща статуса на поръчка.
Test Endpoint Метод Описание
https://tekra.bg/api/v1/test/orders/create POST Създава нова поръчка.
https://tekra.bg/api/v1/test/orders/status GET Връща статуса на поръчка.

Headers

За да използвате API-то, трябва да включите следните headers във вашите заявки:

Създаване на поръчка

За да създадете поръчка, изпратете POST заявка към /orders/create със следните данни:

{
    "contact_person": {
        "name": "Иван",
        "surname": "Иванов",
        "phone": "+359888123456"
    },
    "shipping_address": {
        "city": "София",
        "address": "ул. Примерна",
        "address_num": "10",
        "zip_code": "1000"
    },
    "products": [
        {
            "product": "PRODUCT_2",
            "qty": 2
        }
    ],
    "note": "Бележка към поръчката"
}

Проверка на статус

За да проверите статуса на поръчка, изпратете GET заявка към /orders/status със следните данни:

{
    "order_number": "55504"
}

Грешки

Код на грешка Описание Тип
1000 Грешка при комуникация със сървъра. Моля, опитайте отново по-късно. error
1001 Методът на заявката не е позволен. Моля, уверете се, че използвате правилния HTTP метод. error
1002 Неоторизиран достъп. Моля, проверете вашите идентификационни данни и опитайте отново. error
1003 Липсва задължително поле в заявката. Моля, попълнете всички изисквани полета. error
1004 Невалиден формат на телефонен номер. Моля, въведете валиден телефонен номер. error
1005 Липсва име или фамилия. Моля, попълнете и двете полета. error
1006 Липсва адрес или номер на адрес. Моля, попълнете необходимите полета за адреса. error
1007 Невалиден формат на пощенски код. Моля, въведете правилен пощенски код. error
1008 Полето "products" трябва да съдържа непразен масив от продукти. error
1009 Липсва "product" за един от продуктите. Моля, уверете се, че сте предоставили правилен идентификатор за всеки продукт. error
1010 Невалидно или липсващо количество за продукт. Моля, уверете се, че количеството е зададено правилно. error
1011 Продуктът не е намерен. Моля, проверете идентификатора на продукта и опитайте отново. error
1012 Бележката не може да надвишава 130 символа. Моля, намалете броя на символите в бележката. error
1013 Частично приемане на поръчка поради грешка в комуникацията. Моля, свържете се с търговеца за повече информация. error
1014 Поръчката не може да бъде приета поради натрупани задължения. Свържете се с търговеца за изясняване на ситуацията. error
1015 Грешка при комуникация със сървъра. Моля, свържете се с търговеца за помощ. error
1016 Липсва задължителен header: X-TekraClientID или X-TekraAPIKey. Моля, уверете се, че тези стойности са предоставени в заглавките на заявката. error
1017 Поръчката не е намерена. Моля, проверете номер на поръчката и опитайте отново. error
2001 Поръчката е приета, но някои от заявените количества надвишават складовата наличност. Търговец ще се свърже за уточнение. success
Поръчката е създадена успешно. success

Примерен PHP код

Примерен PHP код за изпращане на заявка за създаване на поръчка:

<?php
$url = "https://tekra.bg/api/v1/test/orders/create";
$data = [
    "contact_person" => [
        "name" => "Иван",
        "surname" => "Иванов",
        "phone" => "+359888123456"
    ],
    "shipping_address" => [
        "city" => "София",
        "address" => "ул. Примерна",
        "address_num" => "10",
        "zip_code" => "1000"
    ],
    "products" => [
        [
            "product" => "PRODUCT_2",
            "qty" => 2
        ]
    ],
    "note" => "Бележка към поръчката"
];

$headers = [
    "X-TekraClientID: YOUR_CLIENT_ID",
    "X-TekraAPIKey: YOUR_API_KEY",
    "Content-Type: application/json"
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Примерни отговори

Примерен отговор при успешно създаване на поръчка:

{
    "data": {
        "order_number": "55504",
        "products": [
            {
                "product": "PRODUCT_2",
                "stock": 10
            }
        ]
    },
    "status": {
        "type": "success",
        "message": "Order created successfully."
    }
}

Примерен отговор при проверка на статус:

{
    "data": {
        "order_number": 55504,
        "status": "Приключена",
        "tracking_number": "1234567890"
    },
    "status": {
        "type": "success",
        "message": ""
    }
}

Обяснение на полетата:

Поле Описание
order_number Номер на поръчката.
products Масив от продукти, които са част от поръчката.
product Идентификатор на продукта.
stock Наличност на продукта. Това показва моментната наличност от продукта.
status Тип на отговора. В този случай, success, който показва, че поръчката е създадена успешно.
message Допълнително пояснение.

Примерен отговор при грешка:

{
    "data": [],
    "status": {
        "type": "error",
        "message": "Missing required field: contact_person",
        "error_code": 1003
    }
}

Обяснение на полетата при грешка:

Поле Описание
data Масив, съдържащ данни, които са върнати от сървъра. В случай на грешка, този масив обикновено ще бъде празен. За грешка с код #1013, в масива ще бъде включен order_number, който съдържа номера на поръчката, за която е възникнала грешката.
status
type Статус на заявката. В случая е "error", което показва, че е възникнала грешка.
message Съобщение, което обяснява каква е грешката. В този пример, липсващо задължително поле "contact_person".
error_code Уникален код за грешката, който помага при идентифицирането на проблема.

Тестови продукти

Product Наличност
PRODUCT_1 10
PRODUCT_2 3
PRODUCT_3 5