Data Export API

Этот сервис предоставляет удобный и безопасный доступ к данным вашего аккаунта для:

• выгрузки в Excel / BI‑системы;
• построения отчётов и дашбордов;
• использования в собственных скриптах и интеграциях;
• резервного копирование данных;
• массовой обработки данных с помощью ИИ.

Доступ выдаётся по API‑ключу, каждый аккаунт видит только свои данные.

Базовая информация

• Базовый URL: https://data-api.autoweboffice.ru/v1
• Формат: JSON
• HTTP методы: GET (только чтение, без модификации данных)
• Кодировка: UTF‑8

Авторизация

Каждому клиенту выдается API‑ключ.

• В заголовке Authorization:

Authorization: Bearer YOUR_API_KEY

• Без корректного ключа все запросы вернут ошибку 401 Unauthorized.

Основные эндпоинты

1. Список доступных ресурсов

GET /v1/schema

Отдаёт описание:

• доступных ресурсов (contacts, orders, …);
• полей каждого ресурса (внутреннее имя, доступные поля (колонки), человекочитаемые title и description);
• доступных параметров запроса;
• текущих лимитов по запросам.

Фрагмент структуры ответа:

{
  "meta": {
    "title": "Data Export API",
    "list_endpoint": "GET /v1/{resource}",
    "authentication": "Authorization: Bearer <api_key>",
    "rate_limit": {
      "max_requests": 20,
      "window_seconds": 60,
      "description": "Не более 20 запросов за последние 60 секунд на один API-ключ. При превышении вернётся 429 Too Many Requests."
    }
  },
  "resources": [
    {
      "name": "orders",
      "description": "Счета",
      "endpoint": "/v1/orders",
      "fields": [
        {
          "name": "id",
          "column": "id_account",
          "title": "ID заказа",
          "description": null
        },
        {
          "name": "order_number",
          "column": "account_number",
          "title": "Номер заказа",
          "description": null
        }
        // ...
      ],
      "sortable": [
        "id",
        "order_date",
        "payment_date",
        "total_amount",
        "order_number",
        "status_changed_at"
      ]
    }
  ],

Рекомендуется всегда начинать интеграцию с запроса /v1/schema.

2. Получение данных ресурса

GET /v1/{resource}

Например:

GET /v1/orders
GET /v1/orders?page=2&limit=100
GET /v1/orders?sort=payment_date&order=desc
GET /v1/orders?filter[status_id]=5
GET /v1/orders?filter[email][like]=example
GET /v1/orders?filter[payment_date][gte]=2024-06-01&filter[payment_date][lte]=2024-06-30

Ответ:

{
  "data": [
    {
      "id": 1,
      "order_number": 1,
      "order_date": "2021-02-04 20:16:37",
      "payment_date": "0000-00-00 00:00:00",
      "status_id": 1,
      "status_changed_at": "2021-02-04 20:16:37",
      "total_amount": "3000.00",
      "currency_id": 0,
      "payment_system_id": 0,
      "discount_code": "[]",
      "email": "test@gmail.com",
      // ...
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 36735
  }
}

Параметры запросов

Все параметры передаются в query string.

• page (integer, по умолчанию 1)

  • Номер страницы (начиная с 1).

• limit (integer, по умолчанию 100)

  • Размер страницы (количество записей).
  • Не может превышать 1000, который указан в /api/schema → meta.rate_limit.

• sort (string)

  • Имя поля для сортировки (из schema.resources[].sortable).

• order (string, asc или desc)

  • Направление сортировки.

• filter[FIELD] (string)

  • Точное сравнение по полю FIELD.
  • Пример: ?filter[status_id]=5 — только оплаченные счета.
  • Список допустимых полей — имена из resources[].fields[].name.

• filter[FIELD][like] (string)

  • Поиск по подстроке (аналог SQL LIKE '%...%') только по одному полю.
  • Пример: ?filter[email][like]=example — все записи, где email содержит "example".

• filter[FIELD][gte] (string)

  • Фильтрация по значению больше или равно (аналог SQL >=).
  • Пример: ?filter[payment_date][gte]=2024-06-01 — все записи с датой оплаты начиная с 1 июня 2024.

• filter[FIELD][lte] (string)

  • Фильтрация по значению меньше или равно (аналог SQL <=).
  • Пример: ?filter[payment_date][lte]=2024-06-30 — все записи с датой оплаты до 30 июня 2024 включительно.

• Можно комбинировать диапазон:

GET /v1/orders?filter[payment_date][gte]=2024-06-01&filter[payment_date][lte]=2024-06-30

• Можно комбинировать с другими фильтрами:

GET /v1/orders?filter[status_id]=5&filter[payment_date][gte]=2024-06-01

• Важно:
  • Для поиска по подстроке используйте только filter[FIELD][like] для одного поля.
  • Для диапазонов используйте filter[FIELD][gte] и/или filter[FIELD][lte].

Примеры фильтрации

1. Строгое сравнение:

GET /v1/orders?filter[status_id]=5

2. Поиск по подстроке (LIKE):

GET /v1/orders?filter[email][like]=gmail.com

3. Диапазон дат:

GET /v1/orders?filter[payment_date][gte]=2024-06-01&filter[payment_date][lte]=2024-06-30

4. Только больше или только меньше:

GET /v1/orders?filter[payment_date][gte]=2024-06-01
GET /v1/orders?filter[payment_date][lte]=2024-06-30

5. Комбинированные фильтры:

GET /v1/orders?filter[status_id]=5&filter[payment_date][gte]=2024-06-01&filter[email][like]=gmail.com

Ограничения и производительность

1. Только чтение

   • API позволяет только получать данные (GET).
   • Никаких операций изменения / удаления.

2. Объём данных

   • Разовый ответ ограничен limit (см. /v1/schema → meta.limit).
   • При больших объёмах данных используйте постраничную выгрузку (page + limit).

3. Rate limit

   • См. блок meta.rate_limit в /v1/schema.
   • При превышении лимита вернётся 429 Too Many Requests и заголовок Retry-After.
   • Учитывайте ограничение на кол-во запросов в секунду, не более 5/сек. При привышении ошибка 503

Типичные паттерны использования

• Excel / BI

  • Используйте GET /v1/{resource} как источник для Power BI, Excel Power Query, любой ETL‑системы.
  • Для инкрементальной загрузки используйте фильтрацию и сортировку по дате (payment_date, order_date и т.п.).

• Скрипты / Python / R

  • Рекомендуется:
    • читать /v1/schema, чтобы автоматически строить описание полей;
    • выгружать данные пакетами (например, по 1000 записей) до тех пор, пока page * limit < total.

Нет нужного ресурса

Если вам нужен новый ресурс (таблица) или дополнительные поля, обратитесь к нам — мы добавим их в конфиг и они появятся в /api/schema.