+359 878 223 860 office@vladster.net
Изберете страница

Web API

Свържете външни услуги директно към вашата IncoPOS система използвайки IncoCloud Web API. Достъп до наличности, продажби, партньори и повече чрез RESTful интерфейс.

Интерактивен API Справочник (Swagger)
Ръководство за Бърз Старт

Бърз Старт

Стъпка 1: Получете Вашите API Идентификационни Данни

За да използвате IncoCloud Web API, ви е необходимо:

  1. Активен IncoCloud абонамент
  2. API идентификационни данни (app_id и app_secret)

За да получите API идентификационни данни:

  1. Влезте във вашия IncoCloud акаунт на incocloud.com/account
  2. Отидете на Услуги → Web API
  3. Кликнете Създаване на Ново Приложение
  4. Въведете име на приложението (например „Моята Интеграция“)
  5. Копирайте вашите app_id и app_secret – няма да видите секрета отново!

⚠️ Важно: Пазете вашия app_secret сигурно. Никога не го добавяйте към контрол на версии или го споделяйте публично. Той предоставя пълен достъп до вашите IncoPOS данни.

Стъпка 2: Генерирайте Access Token

Преди да можете да извикате API крайни точки, трябва да генерирате access token използвайки вашите идентификационни данни:

GET https://incocloud.com/connect/api/access_token?app_id=YOUR_APP_ID&app_secret=YOUR_APP_SECRET

Отговор:

{
  "token": "abc123def456...",
  "server_url": "https://server-xyz.incocloud.com"
}

Отговорът съдържа:

  • token – Използвайте го във всички последващи API заявки
  • server_url – Вашият назначен сървър URL. Всички бъдещи заявки трябва да използват този сървър URL, а не общия incocloud.com URL.

💡 Важно: Access token е свързан с конкретен сървър. Винаги използвайте server_url върнат с токена за всички API извиквания.

Стъпка 3: Направете Вашето Първо API Извикване

Сега можете да направите заявка за стоки от вашия инвентар:

GET https://server-xyz.incocloud.com/connect/api/item?token=YOUR_ACCESS_TOKEN

Пример с curl:

# Стъпка 1: Получете access token
curl "https://incocloud.com/connect/api/access_token?app_id=YOUR_APP_ID&app_secret=YOUR_APP_SECRET"

# Стъпка 2: Използвайте токена (заменете сървър URL и токен с реални стойности)
curl "https://server-xyz.incocloud.com/connect/api/item?token=YOUR_ACCESS_TOKEN"

Автентикация

IncoCloud Web API използва двустъпков процес на автентикация:

Стъпка 1: Получаване на Access Token

Крайна точка: GET /connect/api/access_token

Параметри:

  • app_id (задължителен) – Вашият application ID от IncoCloud настройки
  • app_secret (задължителен) – Вашият application secret

Връща:

  • token – Access token за използване в API заявки
  • server_url – Сървър URL за използване за всички заявки с този токен

Стъпка 2: Използване на Token в Заявки

Включете token параметъра във всички API заявки:

GET /connect/api/item?token=YOUR_ACCESS_TOKEN&other_params=values

Изисквания за Сигурност

  • HTTPS Изискван: Всички API заявки трябва да използват HTTPS (освен localhost за разработка)
  • Правилен Сървър: Трябва да използвате server_url предоставен от access token крайната точка
  • Изтичане на Token: Access токените са базирани на сесия и остават валидни докато не бъдат изрично отменени

Налични API Крайни Точки

IncoCloud Web API предоставя достъп до следните ресурси. Кликнете Интерактивен API Справочник (Swagger) за детайлна документация за всяка крайна точка.

Инвентар и Стоки

  • GET /connect/api/item – Получаване на стоки (продукти/услуги) с опционално филтриране
    • Параметри: id, location_id, group_id, tag_id, only_available, include_availability, code, catalog
    • Връща: Масив от стоки с детайли и опционална наличност по обект
  • GET /connect/api/item_group – Получаване на групи стоки/категории
  • GET /connect/api/item_tag – Получаване на тагове на стоки за филтриране и категоризация
  • GET /connect/api/item_tag_connection – Получаване на връзки между стоки и тагове

Операции Продажби

  • GET /connect/api/sale – Получаване на продажби/касови бележки с филтриране
    • Параметри: operation_number, location_id, partner_id, from_date, to_date, load_payments
    • Връща: Масив от продажби с детайли
  • POST /connect/api/sale – Създаване на нова продажба програмно
    • Забележка: Не е налично за локализация България – СУПТО
  • GET /connect/api/sales_order – Получаване на поръчки за продажби
  • GET /connect/api/return – Получаване на връщания на продажби
  • GET /connect/api/credit_note – Получаване на кредитни известия

Операции Доставки

  • GET /connect/api/purchase – Получаване на доставки
  • GET /connect/api/purchase_return – Получаване на връщания на доставки

Фактуриране и Документи

  • GET /connect/api/invoice – Получаване на фактури
  • GET /connect/api/cash_receipt – Получаване на касови бележки

Партньори и Клиенти

  • GET /connect/api/partner – Получаване на партньори (клиенти/доставчици)
  • GET /connect/api/partner_group – Получаване на групи партньори

Обекти и Магазини

  • GET /connect/api/location – Получаване на обекти (магазини/складове)
  • GET /connect/api/location_group – Получаване на групи обекти

Плащания

  • GET /connect/api/payment – Получаване на плащания
  • GET /connect/api/payment_type – Получаване на типове плащания (в брой, с карта и др.)

Конфигурация

  • GET /connect/api/vat_group – Получаване на ДДС/данъчни групи
  • GET /connect/api/price_rule – Получаване на ценови правила и промоции
  • GET /connect/api/operation_status – Получаване на статуси на операции

Хотелиерство (Хотел/Ресторант)

  • GET /connect/api/booking – Получаване на резервации
  • GET /connect/api/booking_availability – Проверка на наличност
  • GET /connect/api/booking_profile – Получаване на профили за резервации
  • GET /connect/api/booking_location_type – Получаване на типове обекти (типове стаи)
  • GET /connect/api/booking_rate_type – Получаване на типове тарифи
  • GET /connect/api/booking_status – Получаване на статуси на резервации
  • GET /connect/api/reservation – Получаване на резервации на маси
  • GET /connect/api/restaurant_order_request – Получаване на ресторантски поръчки
  • GET /connect/api/restaurant_order_request_status – Получаване на статуси на поръчки

Абонаменти и Ваучери

  • GET /connect/api/subscription – Получаване на абонаменти
  • GET /connect/api/subscription_event – Получаване на събития на абонаменти
  • GET /connect/api/voucher – Получаване на ваучери/подаръчни карти

Примери с Код

Пример 1: Получаване на Всички Стоки (Python)

import requests

# Стъпка 1: Получаване на access token
auth_response = requests.get(
    "https://incocloud.com/connect/api/access_token",
    params={
        "app_id": "YOUR_APP_ID",
        "app_secret": "YOUR_APP_SECRET"
    }
)
auth_data = auth_response.json()
token = auth_data["token"]
server_url = auth_data["server_url"]

# Стъпка 2: Получаване на всички стоки
items_response = requests.get(
    f"{server_url}/connect/api/item",
    params={
        "token": token,
        "include_availability": True
    }
)

items = items_response.json()
for item in items:
    print(f"{item['code']}: {item['name']} - Наличност: {item.get('availability', 'Няма данни')}")

Пример 2: Получаване на Продажби за Период от Дати (JavaScript/Node.js)

const axios = require('axios');

async function getSales(fromDate, toDate) {
    // Стъпка 1: Получаване на access token
    const authResponse = await axios.get('https://incocloud.com/connect/api/access_token', {
        params: {
            app_id: 'YOUR_APP_ID',
            app_secret: 'YOUR_APP_SECRET'
        }
    });

    const { token, server_url } = authResponse.data;

    // Стъпка 2: Получаване на продажби
    const salesResponse = await axios.get(`${server_url}/connect/api/sale`, {
        params: {
            token: token,
            from_date: fromDate,
            to_date: toDate,
            load_payments: true
        }
    });

    return salesResponse.data;
}

// Употреба
getSales('2025-01-01', '2025-01-31').then(sales => {
    console.log(`Намерени ${sales.length} продажби`);
    sales.forEach(sale => {
        console.log(`Продажба #${sale.operation_number}: ${sale.total} лв`);
    });
});

Пример 3: Търсене на Стоки по Код (C#)

using System;
using System.Net.Http;
using System.Threading.Tasks;
using Newtonsoft.Json.Linq;

public class IncoCloudClient
{
    private readonly string appId;
    private readonly string appSecret;
    private string token;
    private string serverUrl;

    public IncoCloudClient(string appId, string appSecret)
    {
        this.appId = appId;
        this.appSecret = appSecret;
    }

    public async Task Authenticate()
    {
        using (var client = new HttpClient())
        {
            var response = await client.GetStringAsync(
                $"https://incocloud.com/connect/api/access_token?app_id={appId}&app_secret={appSecret}"
            );

            var data = JObject.Parse(response);
            token = data["token"].ToString();
            serverUrl = data["server_url"].ToString();
        }
    }

    public async Task GetItemByCode(string code)
    {
        using (var client = new HttpClient())
        {
            var response = await client.GetStringAsync(
                $"{serverUrl}/connect/api/item?token={token}&code={code}"
            );

            return JArray.Parse(response);
        }
    }
}

// Употреба
var client = new IncoCloudClient("YOUR_APP_ID", "YOUR_APP_SECRET");
await client.Authenticate();
var items = await client.GetItemByCode("SKU-001");

Пример 4: Създаване на Продажба (PHP)

<?php

function getAccessToken($appId, $appSecret) {
    $url = "https://incocloud.com/connect/api/access_token?" . http_build_query([
        'app_id' => $appId,
        'app_secret' => $appSecret
    ]);

    $response = file_get_contents($url);
    return json_decode($response, true);
}

function createSale($token, $serverUrl, $saleData) {
    $url = $serverUrl . "/connect/api/sale?token=" . urlencode($token);

    $options = [
        'http' => [
            'header'  => "Content-type: application/json\r\n",
            'method'  => 'POST',
            'content' => json_encode($saleData)
        ]
    ];

    $context  = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    return json_decode($result, true);
}

// Стъпка 1: Автентикация
$auth = getAccessToken('YOUR_APP_ID', 'YOUR_APP_SECRET');
$token = $auth['token'];
$serverUrl = $auth['server_url'];

// Стъпка 2: Създаване на продажба
$sale = [
    'location_id' => 1,
    'partner_id' => 123,
    'details' => [
        [
            'item_id' => 456,
            'quantity' => 2,
            'price_out' => 29.99
        ]
    ]
];

$result = createSale($token, $serverUrl, $sale);
echo "Продажба създадена с ID: " . $result['id'];

?>

Ограничения на Честотата

IncoCloud Web API прилага ограничения на честотата за да осигури справедлива употреба и стабилност на системата. Въпреки че информацията за ограничения на честотата в момента не се връща в заглавките на отговора, моля използвайте API отговорно, за да избегнете достигане на лимити.

Най-добри практики за избягване на ограничения на честотата:

  • Преизползвайте access токени вместо да изисквате нови за всяко API извикване
  • Имплементирайте експоненциално изчакване при повторни опити за неуспешни заявки
  • Кеширайте API отговори когато е подходящо за вашия случай на употреба
  • Използвайте параметри за филтриране за намаляване на размера на отговорите
  • Избягвайте правенето на ненужни едновременни заявки

Ако срещнете проблеми с ограничения на честотата, свържете се с поддръжката на api-support@vladster.net за помощ.

Обработка на Грешки

API използва стандартни HTTP статус кодове за указване на успех или неуспех:

Статус Код Значение Често Срещани Причини
200 OK Заявката е успешна Нормална работа
400 Bad Request Невалидни параметри Липсващи задължителни полета, невалиден формат на данни
401 Unauthorized Невалидни идентификационни данни или токен Грешен app_id/app_secret, изтекъл или невалиден токен
403 Forbidden Достъпът е отказан Грешен сървър URL, услугата е деактивирана, несигурна връзка (HTTP вместо HTTPS), недостатъчни права
404 Not Found Ресурсът не е намерен Невалидна крайна точка или ID на ресурс
500 Internal Server Error Сървърна грешка Свържете се с поддръжката ако продължава

Често Срещани Съобщения за Грешки

  • „Insecure connection“ – Трябва да използвате HTTPS (не HTTP)
  • „Invalid credentials“ – Проверете вашия app_id и app_secret
  • „Invalid token“ – Генерирайте нов access token
  • „Service disabled“ – Web API услугата не е активирана за вашия IncoCloud акаунт
  • „Wrong server“ – Трябва да използвате server_url предоставен от access token, а не общия incocloud.com URL
  • „Permission denied“ – API потребителят няма достъп до тази функционалност. Проверете потребителските права в IncoCloud настройки.

Най-добри Практики

Сигурност

  • Съхранявайте app_secret сигурно (променливи на среда, мениджър на секрети)
  • Никога не добавяйте идентификационни данни към контрол на версии
  • Винаги използвайте HTTPS за API заявки
  • Използвайте правилния server_url върнат от access token крайната точка
  • Имплементирайте правилна обработка на грешки и логване

Производителност

  • Преизползвайте access токени – не изисквайте нов токен за всяко API извикване
  • Използвайте параметри за филтриране за намаляване на размера на отговора
  • Кеширайте отговори когато е подходящо за вашия случай на употреба
  • Използвайте филтри за период от дати за операции за ограничаване на резултатите
  • Спазвайте ограниченията на честотата за осигуряване на последователен API достъп

Интегритет на Данните

  • Валидирайте данните преди изпращане към API
  • Обработвайте API грешки грациозно
  • Имплементирайте логика за повторни опити за преходни неуспехи
  • Наблюдавайте употребата на API за необичайни модели

Интерактивен API Explorer

Пълният API справочник с всички крайни точки, параметри, примери за заявка/отговор и възможността за тестване на API извиквания директно във вашия браузър е достъпен чрез Swagger UI:

Стартиране на Интерактивен API Explorer (Swagger UI) →

Swagger UI предоставя:

  • Пълна документация на крайните точки с всички параметри
  • Дефиниции на схеми за заявка и отговор
  • Интерактивно тестване – опитайте API извиквания директно от вашия браузър
  • Генериране на код за различни програмни езици

Поддръжка и Ресурси

  • Интерактивен API Справочник: Swagger UI
  • Ръководства за Услуги: Уроци за Интеграция
  • API Поддръжка: support@incopos.com
  • Обща Поддръжка: office@incopos.com
  • Телефон: +359 878 223 860

Често Задавани Въпроси

Нужен ли ми е специален лиценз за API достъп?

Не, Web API достъпът е включен във вашия IncoCloud абонамент. Само трябва да активирате Web API услугата във вашите IncoCloud настройки и да генерирате API идентификационни данни.

Има ли ограничения на честотата?

Да, API има ограничения на честотата за осигуряване на справедлива употреба и стабилност на системата. Въпреки че конкретните лимити в момента не се показват в заглавките на отговора, моля използвайте API отговорно. Свържете се с поддръжката ако имате изисквания за високи обеми.

Мога ли да използвам API от мобилно приложение?

Да, но НЕ трябва да вграждате вашия app_secret в мобилни приложения. Вместо това създайте backend услуга, която обработва автентикацията и прокси API заявките сигурно.

Каква е разликата между app_id/app_secret и токена?

app_id и app_secret са дългосрочни идентификационни данни, които генерирате веднъж в IncoCloud настройки. token е базиран на сесия access token, получен чрез автентикация с вашите идентификационни данни. Използвате токена за всички API заявки.

Защо трябва да използвам конкретен сървър URL?

IncoCloud използва множество сървъри за балансиране на натоварването и локалност на данните. Вашите данни са на конкретен сървър и трябва да използвате URL на този сървър (предоставен с access token) за всички заявки.

Мога ли да създавам продажби за всички локализации?

Не, създаването на продажби чрез POST не е налично за локализация България – СУПТО поради регулаторни изисквания. Всички други региони поддържат създаване на продажби чрез API.


← Обратно към IncoCloud |
IncoCloud Начало |
IncoPOS Начало

Документация