Документація 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'

Інформація про поточний API-ключ

GET /api/v1/me

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

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

$ 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": 100,
          "pages": 1000,
          "downloads": 200
        },
        "monthly": {
          "enterprises": 500,
          "pages": 10000,
          "downloads": 2000
        },
        "yearly": {
          "enterprises": 5000,
          "pages": 120000,
          "downloads": 24000
        }
      }
    },
    "current_key": {
      "name": "Production key",
      "last_used_at": "2026-05-14T11:00:00+03:00"
    },
    "usage": {
      "account": {
        "daily": {
          "enterprises": 10,
          "pages": 18,
          "downloads": 3
        }
      },
      "current_key": {
        "daily": {
          "enterprises": 4,
          "pages": 7,
          "downloads": 1
        }
      }
    }
  },
  "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.enterprises: денний ліміт унікальних підприємств.
limits.daily.pages: денний ліміт унікальних сторінок або секцій.
limits.daily.downloads: денний ліміт завантажень.
limits.monthly.enterprises: місячний ліміт унікальних підприємств.
limits.monthly.pages: місячний ліміт унікальних сторінок або секцій.
limits.monthly.downloads: місячний ліміт завантажень.
limits.yearly.enterprises: річний ліміт унікальних підприємств.
limits.yearly.pages: річний ліміт унікальних сторінок або секцій.
limits.yearly.downloads: річний ліміт завантажень.

`results.current_key`

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

`results.usage`

account.daily: денна статистика використання по всьому API-обліковому запису.
account.monthly: місячна статистика використання по всьому API-обліковому запису.
account.yearly: річна статистика використання по всьому API-обліковому запису.
current_key.daily: денна статистика використання саме по поточному ключу.
current_key.monthly: місячна статистика використання саме по поточному ключу.
current_key.yearly: річна статистика використання саме по поточному ключу.
*.enterprises: кількість унікальних підприємств.
*.pages: кількість унікальних сторінок або секцій.
*.downloads: кількість унікальних завантажень.

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

Наш OpenAPI файл

Авторизація

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

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

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

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

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

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

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

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

Поля

Пагінація

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

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

Фільтрація

Інформація про поточний API-ключ

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

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

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

results.api_account

results.current_key

results.usage

Візьміть участь в тестуванні ESG профілю підприємства у системі SaveEcoBot

`results.api_account`

`results.current_key`

`results.usage`