Документація ESG SaveEcoBot API

ESG SaveEcoBot API надає доступ до ESG-профілю підприємства через Bearer API-ключ. Основний ідентифікатор підприємства в API — registry_id (ЄДРПОУ або РНОКПП).

Ця сторінка допомагає швидко зрозуміти логіку API, формат авторизації та базові принципи роботи з відповідями. Усі відповіді ESG SaveEcoBot API повертаються у форматі JSON, окрім запитів завантаження файлів.

Документація розбита на окремі сторінки за сутностями та розділами даних. Зліва є навігація, через яку можна перейти до потрібної секції: від деталей підприємства до конкретних типів даних, файлів і довідників.

Окремо доступна сторінка Історія змін, де коротко фіксуються важливі оновлення документації й структури.

Інтерактивна документація API

Інтерактивна Swagger UI документація дає візуальний інтерфейс для перегляду всіх доступних endpoint’ів, схем запитів і відповідей. Вона також дозволяє тестувати API-запити прямо в браузері з вашим Bearer API-ключем.

Наш OpenAPI файл

Ви можете завантажити наш файл специфікації OpenAPI, щоб використовувати його у ваших API-інструментах та генераторах SDK.

Авторизація

Усі запити до ESG SaveEcoBot API виконуються через Bearer API-ключ. Щоб отримати його, необхідно зв'язатися з командою за адресою [email protected].

Приклад запиту

$ ESG_API_TOKEN="your_api_token"
$ curl "https://esg.saveecobot.com/api/v1/me" \
  -H "Authorization: Bearer $ESG_API_TOKEN" \
  -H "X-Request-Id: crm-sync-2026-05-14-001" \
  -H 'Accept: application/json'

Ідентифікатор запиту

За потреби клієнт може передати власний ідентифікатор запиту в заголовку X-Request-Id. Це корисно для дебагу та звірки логів між вашою системою і ESG SaveEcoBot API:

• якщо X-Request-Id був переданий, API використає саме його;
• якщо X-Request-Id не передано, API сформує його автоматично;
• це значення повертається і в заголовку відповіді X-Request-Id, і в stats.request_id.

Заголовки відповіді

У кожній відповіді API повертає службові заголовки:

• X-Request-Id: ідентифікатор запиту. Якщо ви передали його самостійно, API поверне це саме значення. Якщо не передали, API згенерує його автоматично.
• X-Response-Time-Ms: час формування відповіді в мілісекундах.

Формат успішної відповіді

{
  "results": {},
  "stats": {
    "request_id": "uuid", 
    "response_time_ms": 21
  }
}

Поля відповіді

• results: основний блок даних, який залежить від конкретного запиту.
• stats.request_id: ідентифікатор конкретного HTTP-запиту.
• stats.response_time_ms: час обробки запиту в мілісекундах.

Формат помилки

{
  "error": {
    "code": "not_found",
    "message": "Resource not found.",
    "details": null
  },
  "stats": { 
    "request_id": "uuid", 
    "response_time_ms": 12
  }
}

Поля відповіді

• error.code: машинозчитуваний код помилки.
• error.message: короткий текстовий опис помилки.
• error.details: додаткові подробиці, якщо вони передаються.
• stats.request_id: ідентифікатор запиту, який зручно передавати в підтримку.
• stats.response_time_ms: час обробки запиту в мілісекундах.

Блок про підприємство у відповідях

У всіх запитах по підприємству в results автоматично додається короткий блок enterprise, щоб у відповіді завжди було видно, для якого саме підприємства повернуті дані.

Виняток — запит деталей підприємства, де enterprise уже містить повний набір основних полів.

Короткий блок має такий вигляд:

"enterprise": {
  "type": "company",
  "registry_id": "00178353"
}

Поля

• enterprise.type: тип підприємства. Можливі значення: company або fop.
• enterprise.registry_id: ідентифікатор підприємства. Для company це ЄДРПОУ, для fop — РНОКПП.

Пагінація

Усі запити зі списками використовують однаковий блок пагінації:

"pagination": {
  "current_page": 1,
  "per_page": 20,
  "total": 57,
  "last_page": 6
}

Поля пагінації

• pagination.current_page: номер поточної сторінки.
• pagination.per_page: кількість записів на сторінці. Використовується фіксоване значення 20.
• pagination.total: загальна кількість записів у вибірці.
• pagination.last_page: номер останньої доступної сторінки.

Параметри пагінації

• page: номер сторінки.

Фільтрація

Усі фільтри в ESG SaveEcoBot API передаються через query-параметри в URL.

Наприклад:

• ?domain=air
• ?report_type_id=9

Якщо запит підтримує кілька фільтрів одночасно, їх можна поєднувати в одному URL, наприклад:

$ ESG_API_TOKEN="your_api_token"
$ curl "https://esg.saveecobot.com/api/v1/enterprises/00178353/reports/air?report_type_id=9&page=2" \
  -H "Authorization: Bearer $ESG_API_TOKEN" \
  -H 'Accept: application/json'

Приклад запиту

$ ESG_API_TOKEN="your_api_token"
$ curl "https://esg.saveecobot.com/api/v1/me" \
  -H "Authorization: Bearer $ESG_API_TOKEN" \
  -H "X-Request-Id: crm-sync-2026-05-14-001" \
  -H 'Accept: application/json'

Приклад відповіді

{
  "results": {
    "api_account": {
      "name": "Demo account",
      "all_registry_ids_allowed": false,
      "allowed_registry_ids": ["00178353", "03348471"],
      "billing_cycle": {
        "starts_at": "2026-05-01T00:00:00+03:00",
        "ends_at": "2026-05-31T23:59:59+03:00"
      },
      "limits": {
        "daily": {
          "enterprises": null,
          "data_requests": null,
          "downloads": null
        },
        "monthly": {
          "enterprises": null,
          "data_requests": null,
          "downloads": null
        },
        "period": {
          "enterprises": 5000,
          "data_requests": 120000,
          "downloads": 24000
        }
      }
    },
    "current_key": {
      "name": "Production key",
      "last_used_at": "2026-05-14T11:00:00+03:00"
    },
    "usage": {
      "account": {
        "daily": {
          "starts_at": "2026-05-14T00:00:00+03:00",
          "ends_at": "2026-05-14T23:59:59+03:00",
          "total_requests": 25,
          "enterprises": 10,
          "data_requests": 18,
          "downloads": 3
        },
        "monthly": {
          "starts_at": "2026-05-01T00:00:00+03:00",
          "ends_at": "2026-05-31T23:59:59+03:00",
          "total_requests": 180,
          "enterprises": 52,
          "data_requests": 137,
          "downloads": 14
        },
        "period": {
          "starts_at": "2026-05-01T00:00:00+03:00",
          "ends_at": "2026-05-31T23:59:59+03:00",
          "total_requests": 180,
          "enterprises": 52,
          "data_requests": 137,
          "downloads": 14
        }
      },
      "current_key": {
        "daily": {
          "starts_at": "2026-05-14T00:00:00+03:00",
          "ends_at": "2026-05-14T23:59:59+03:00",
          "total_requests": 11,
          "enterprises": 4,
          "data_requests": 7,
          "downloads": 1
        },
        "monthly": {
          "starts_at": "2026-05-01T00:00:00+03:00",
          "ends_at": "2026-05-31T23:59:59+03:00",
          "total_requests": 84,
          "enterprises": 24,
          "data_requests": 63,
          "downloads": 6
        },
        "period": {
          "starts_at": "2026-05-01T00:00:00+03:00",
          "ends_at": "2026-05-31T23:59:59+03:00",
          "total_requests": 84,
          "enterprises": 24,
          "data_requests": 63,
          "downloads": 6
        }
      }
    }
  },
  "stats": { "request_id": "crm-sync-2026-05-14-001", "response_time_ms": 43 }
}

Поля відповіді

results.api_account

• name: назва облікового запису.
• all_registry_ids_allowed: чи має API-обліковий запис доступ до всіх підприємств.
• allowed_registry_ids: перелік дозволених ідентифікаторів підприємств. Якщо all_registry_ids_allowed=true, повертається порожній масив.
• billing_cycle.starts_at: початок поточного розрахункового періоду у форматі ISO 8601 в київському часовому поясі.
• billing_cycle.ends_at: кінець поточного розрахункового періоду у форматі ISO 8601 в київському часовому поясі.
• limits.daily: необов’язкові добові ліміти. Якщо значення null, відповідний добовий ліміт не застосовується.
• limits.monthly: необов’язкові місячні ліміти. Якщо значення null, відповідний місячний ліміт не застосовується.
• limits.period.enterprises: ліміт унікальних підприємств на поточний розрахунковий період.
• limits.*.data_requests: ліміт успішних запитів до даних підприємств. Кожна сторінка пагінації та кожний повторний запит враховуються окремо.
• limits.*.downloads: ліміт унікальних документів. Оригінал і його квитанція мають спільну тарифну ідентичність.

results.current_key

• name: назва поточного ключа.
• last_used_at: дата й час останнього використання цього ключа у форматі ISO 8601 в київському часовому поясі.

results.usage

• account.daily: денна статистика використання по всьому API-обліковому запису.
• account.monthly: місячна статистика використання по всьому API-обліковому запису.
• account.period: статистика використання по всьому API-обліковому запису за поточний розрахунковий період.
• current_key.daily: денна статистика використання саме по поточному ключу.
• current_key.monthly: місячна статистика використання саме по поточному ключу.
• current_key.period: статистика використання саме по поточному ключу за розрахунковий період.
• *.starts_at: початок відповідного вікна обліку в київському часовому поясі.
• *.ends_at: кінець відповідного вікна обліку в київському часовому поясі.
• *.total_requests: усі фактичні запити з розпізнаним API-ключем, включно зі службовими, повторними, помилковими та відхиленими.
• *.enterprises: кількість унікальних підприємств.
• *.data_requests: кількість успішних тарифікованих запитів до даних підприємств.
• *.downloads: кількість унікальних документів.

Добове вікно відповідає календарній добі за київським часом. Місячне вікно відлічується від дати початку розрахункового періоду, а не від першого числа календарного місяця. Значення null у добових або місячних лімітах означає, що відповідний додатковий ліміт не застосовується.

Унікальне підприємство та унікальний документ тарифікуються один раз за весь розрахунковий період. Успішний запит до даних тарифікується щоразу. Запит квитанції враховується як отримання відповідного документа: якщо оригінал або квитанцію вже отримували в цьому періоді, повторного списання документа немає. Відповіді з помилками не збільшують тарифні лічильники, але входять до total_requests.

Квитанції документів

У відповідях API поруч із посиланням на завантаження документа доступне поле receipt з посиланням на його PDF-квитанцію. Квитанція формується окремо для вашого API-облікового запису та містить доступні метадані файла: назву й тип документа, джерело та його утримувача, розпорядника, дату завантаження файла з першоджерела, посилання на оригінальний файл, розмір, формат та інші реквізити.

Квитанція також містить QR-код із посиланням на сторінку перевірки її автентичності в ESG SaveEcoBot.