+359 878 223 860 office@vladster.net
Select Page

Web API

Connect external services directly to your IncoPOS system using the IncoCloud Web API. Access inventory, sales, partners, and more through a RESTful interface.

Interactive API Reference (Swagger)
Quick Start Guide

Quick Start

Step 1: Get Your API Credentials

To use the IncoCloud Web API, you need:

  1. An active IncoCloud subscription
  2. API credentials (app_id and app_secret)

To obtain API credentials:

  1. Log into your IncoCloud account at incocloud.com/account
  2. Navigate to Services → Web API
  3. Click Creste New Application
  4. Enter an application name (e.g., “My Integration”)
  5. Copy your app_id and app_secret – you won’t see the secret again!

⚠️ Important: Keep your app_secret secure. Never commit it to version control or share it publicly. It provides full access to your IncoPOS data.

Step 2: Generate an Access Token

Before you can call any API endpoints, you must generate an access token using your credentials:

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

Response:

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

The response contains:

  • token – Use this in all subsequent API requests
  • server_url – Your assigned server URL. All future requests must use this server URL, not the generic incocloud.com URL.

💡 Important: The access token is tied to a specific server. Always use the server_url returned with the token for all API calls.

Step 3: Make Your First API Call

Now you can query items from your inventory:

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

Example with curl:

# Step 1: Get access token
curl "https://incocloud.com/connect/api/access_token?app_id=YOUR_APP_ID&app_secret=YOUR_APP_SECRET"

# Step 2: Use the token (replace server URL and token with actual values)
curl "https://server-xyz.incocloud.com/connect/api/item?token=YOUR_ACCESS_TOKEN"

Authentication

The IncoCloud Web API uses a two-step authentication process:

Step 1: Obtain Access Token

Endpoint: GET /connect/api/access_token

Parameters:

  • app_id (required) – Your application ID from IncoCloud settings
  • app_secret (required) – Your application secret

Returns:

  • token – Access token to use in API requests
  • server_url – Server URL to use for all requests with this token

Step 2: Use Token in Requests

Include the token parameter in all API requests:

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

Security Requirements

  • HTTPS Required: All API requests must use HTTPS (except localhost for development)
  • Correct Server: You must use the server_url provided by the access token endpoint
  • Token Expiration: Access tokens are session-based and remain valid until explicitly revoked

Available API Endpoints

The IncoCloud Web API provides access to the following resources. Click Interactive API Reference (Swagger) to view detailed documentation for each endpoint.

Inventory & Products

  • GET /connect/api/item – Get items (products/goods/services) with optional filtering
    • Parameters: id, location_id, group_id, tag_id, only_available, include_availability, code, catalog
    • Returns: Array of items with details and optional availability by location
  • GET /connect/api/item_group – Get item groups/categories
  • GET /connect/api/item_tag – Get item tags for filtering and categorization
  • GET /connect/api/item_tag_connection – Get connections between items and tags

Sales Operations

  • GET /connect/api/sale – Get sales/receipts with filtering
    • Parameters: operation_number, location_id, partner_id, from_date, to_date, load_payments
    • Returns: Array of sales with details
  • POST /connect/api/sale – Create a new sale programmatically
    • Note: Not available for България – СУПТО localization
  • GET /connect/api/sales_order – Get sales orders
  • GET /connect/api/return – Get sale returns
  • GET /connect/api/credit_note – Get credit notes

Purchase Operations

  • GET /connect/api/purchase – Get purchases/deliveries
  • GET /connect/api/purchase_return – Get purchase returns

Invoicing & Documents

  • GET /connect/api/invoice – Get invoices
  • GET /connect/api/cash_receipt – Get cash receipts

Partners & Customers

  • GET /connect/api/partner – Get partners (customers/suppliers)
  • GET /connect/api/partner_group – Get partner groups

Locations & Stores

  • GET /connect/api/location – Get locations (stores/warehouses)
  • GET /connect/api/location_group – Get location groups

Payments

  • GET /connect/api/payment – Get payments
  • GET /connect/api/payment_type – Get payment types (cash, card, etc.)

Configuration

  • GET /connect/api/vat_group – Get VAT/tax groups
  • GET /connect/api/price_rule – Get price rules and promotions
  • GET /connect/api/operation_status – Get operation statuses

Hospitality (Hotel/Restaurant)

  • GET /connect/api/booking – Get bookings/reservations
  • GET /connect/api/booking_availability – Check availability
  • GET /connect/api/booking_profile – Get booking profiles
  • GET /connect/api/booking_location_type – Get location types (room types)
  • GET /connect/api/booking_rate_type – Get rate types
  • GET /connect/api/booking_status – Get booking statuses
  • GET /connect/api/reservation – Get table reservations
  • GET /connect/api/restaurant_order_request – Get restaurant orders
  • GET /connect/api/restaurant_order_request_status – Get order statuses

Subscriptions & Vouchers

  • GET /connect/api/subscription – Get subscriptions
  • GET /connect/api/subscription_event – Get subscription events
  • GET /connect/api/voucher – Get vouchers/gift cards

Code Examples

Example 1: Get All Items (Python)

import requests

# Step 1: Get 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"]

# Step 2: Get all items
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']} - Available: {item.get('availability', 'N/A')}")

Example 2: Get Sales for Date Range (JavaScript/Node.js)

const axios = require('axios');

async function getSales(fromDate, toDate) {
    // Step 1: Get 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;

    // Step 2: Get sales
    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;
}

// Usage
getSales('2025-01-01', '2025-01-31').then(sales => {
    console.log(`Found ${sales.length} sales`);
    sales.forEach(sale => {
        console.log(`Sale #${sale.operation_number}: $${sale.total}`);
    });
});

Example 3: Search Items by Code (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);
        }
    }
}

// Usage
var client = new IncoCloudClient("YOUR_APP_ID", "YOUR_APP_SECRET");
await client.Authenticate();
var items = await client.GetItemByCode("SKU-001");

Example 4: Create a Sale (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);
}

// Step 1: Authenticate
$auth = getAccessToken('YOUR_APP_ID', 'YOUR_APP_SECRET');
$token = $auth['token'];
$serverUrl = $auth['server_url'];

// Step 2: Create a sale
$sale = [
    'location_id' => 1,
    'partner_id' => 123,
    'details' => [
        [
            'item_id' => 456,
            'quantity' => 2,
            'price_out' => 29.99
        ]
    ]
];

$result = createSale($token, $serverUrl, $sale);
echo "Sale created with ID: " . $result['id'];

?>

Rate Limits

The IncoCloud Web API implements rate limiting to ensure fair usage and system stability. While rate limit information is not currently returned in response headers, please use the API responsibly to avoid hitting limits.

Best practices to avoid rate limiting:

  • Reuse access tokens instead of requesting new ones for each API call
  • Implement exponential backoff when retrying failed requests
  • Cache API responses when appropriate for your use case
  • Use filtering parameters to reduce response sizes
  • Avoid making unnecessary concurrent requests

If you encounter rate limiting issues, contact support at support@incopos.com for assistance.

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

Status Code Meaning Common Causes
200 OK Request succeeded Normal operation
400 Bad Request Invalid parameters Missing required fields, invalid data format
401 Unauthorized Invalid credentials or token Wrong app_id/app_secret, expired or invalid token
403 Forbidden Access denied Wrong server URL, service disabled, insecure connection (HTTP instead of HTTPS), insufficient permissions
404 Not Found Resource not found Invalid endpoint or resource ID
500 Internal Server Error Server error Contact support if persistent

Common Error Messages

  • “Insecure connection” – You must use HTTPS (not HTTP)
  • “Invalid credentials” – Check your app_id and app_secret
  • “Invalid token” – Generate a new access token
  • “Service disabled” – Web API service is not enabled for your IncoCloud account
  • “Wrong server” – You must use the server_url provided by the access token, not the generic incocloud.com URL
  • “Permission denied” – The API user doesn’t have access to this functionality. Check user permissions in IncoCloud settings.

Best Practices

Security

  • Store app_secret securely (environment variables, secrets manager)
  • Never commit credentials to version control
  • Always use HTTPS for API requests
  • Use the correct server_url returned by the access token endpoint
  • Implement proper error handling and logging

Performance

  • Reuse access tokens – don’t request a new token for every API call
  • Use filtering parameters to reduce response size
  • Cache responses when appropriate for your use case
  • Use date range filters for operations to limit results
  • Respect rate limits to ensure consistent API access

Data Integrity

  • Validate data before sending to the API
  • Handle API errors gracefully
  • Implement retry logic for transient failures
  • Monitor API usage for unusual patterns

Interactive API Explorer

The complete API reference with all endpoints, parameters, request/response examples, and the ability to test API calls directly in your browser is available through Swagger UI:


Launch Interactive API Explorer (Swagger UI) →

The Swagger UI provides:

  • Complete endpoint documentation with all parameters
  • Request and response schema definitions
  • Interactive testing – try API calls directly from your browser
  • Code generation for various programming languages

Support & Resources

  • Interactive API Reference: Swagger UI
  • Service Guides: Integration Tutorials
  • API Support: support@incopos.com
  • General Support: office@incopos.com
  • Phone: +359 878 223 860

Frequently Asked Questions

Do I need a special license for API access?

No, Web API access is included with your IncoCloud subscription. You just need to enable the Web API service in your IncoCloud settings and generate API credentials.

Are there rate limits?

Yes, the API has rate limits to ensure fair usage and system stability. While specific limits are not currently exposed in response headers, please use the API responsibly. Contact support if you have high-volume requirements.

Can I use the API from a mobile app?

Yes, but you should NOT embed your app_secret in mobile apps. Instead, create a backend service that handles authentication and proxies API requests securely.

What’s the difference between app_id/app_secret and the token?

The app_id and app_secret are long-term credentials you generate once in IncoCloud settings. The token is a session-based access token obtained by authenticating with your credentials. You use the token for all API requests.

Why do I need to use a specific server URL?

IncoCloud uses multiple servers for load balancing and data locality. Your data is on a specific server, and you must use that server’s URL (provided with the access token) for all requests.

Can I create sales for all localizations?

No, creating sales via POST is not available for the България – СУПТО localization due to regulatory requirements. All other regions support creating sales via the API.


← Back to IncoCloud |
IncoCloud Home |
IncoPOS Home

Documentation