Звіти підприємства

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

Перелік звітів

GET /api/v1/enterprises/{registry_id}/reports/{domain}

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

Параметри registry_id і domain в адресі запиту є обов'язковими. registry_id — це ідентифікатор підприємства.

Доступні значення domain можна отримати в запиті Домени даних.

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

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

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

{
  "results": {
    "enterprise": { "type": "company", "registry_id": "00178353" },
    "domain": { "slug": "air", "label": "Повітря" },
    "items": [
      {
        "id": 276873,
        "external_id": "AIR-2021-001",
        "type_id": 9,
        "type_name": "Звіт про викиди забруднюючих речовин",
        "registry_id": "2-ТП-2021",
        "authority_name": "Держстат",
        "name": "Звіт № 2-ТП (повітря)",
        "description_lines": [
          "Річний звіт",
          "Унікальний номер підприємства в реєстрі: AIR-2021-001"
        ],
        "address": "Україна, Київська область, місто Київ",
        "report_year": 2021,
        "report_date": "2022-01-31",
        "uploaded_at": "2022-02-01T10:00:00+00:00",
        "downloaded_at": "2022-02-03T14:20:00+00:00",
        "files_count": 1,
        "links": {
          "files": "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-files/276873",
          "details": "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-details/276873"
        },
        "permissions": [
          "123.45.67",
          "33484710001"
        ],
        "coordinates": null
      }
    ],
    "meta": {
      "available_years": [2020, 2021]
    },
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 2,
      "last_page": 1
    }
  },
  "stats": { "..." }
}

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

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

Фільтри

year: рік звітності.
report_type_id: ідентифікатор типу звіту. Доступні значення можна отримати в запиті Типи звітів.

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

`results.items[]`

id: ідентифікатор звіту в ESG SaveEcoBot API.
external_id: ідентифікатор звіту в зовнішньому джерелі, якщо він є.
type_id: ідентифікатор типу звіту.
type_name: назва типу звіту.
registry_id: номер звіту або реєстраційний ідентифікатор, якщо він є.
authority_name: орган, який оприлюднив або веде цей тип звітності.
name: назва звіту.
description_lines[]: короткий опис звіту у вигляді окремих рядків.
address: адреса, пов'язана зі звітом, якщо вона є.
report_year: рік, за який подано звіт.
report_date: дата звіту або дата його подання.
uploaded_at: дата, коли файл було завантажено або оприлюднено в джерелі.
downloaded_at: дата, коли файл був завантажений у систему ESG SaveEcoBot.
files_count: кількість файлів, пов'язаних із цим звітом.
links.files: посилання на окремий запит зі списком файлів звіту.
links.details: посилання на детальну структуровану інформацію по звіту, якщо вона доступна.
permissions[]: перелік номерів дозволів, пов'язаних зі звітом.
coordinates: координати адреси, якщо доступ до них дозволений для ключа.
coordinates.latitude: широта.
coordinates.longitude: довгота.

`results.meta`

available_years[]: перелік років, доступних у цій вибірці.

Деталі звіту

GET /api/v1/enterprises/{registry_id}/report-details/{report_id}

Цей запит повертає дані по одному звіту. Разом із блоком object, у якому міститься коротка інформація про звіт, повертається блок details зі структурованими річними даними, якщо вони доступні для цього звіту.

Параметри registry_id і report_id в адресі запиту є обов'язковими. registry_id — це ідентифікатор підприємства. report_id — це ідентифікатор звіту.

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

$ ESG_API_TOKEN="your_api_token"
$ curl "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-details/276873" \
  -H "Authorization: Bearer $ESG_API_TOKEN" \
  -H 'Accept: application/json'

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

{
  "results": {
    "enterprise": { "type": "company", "registry_id": "00178353" },
    "domain": { "slug": "air", "label": "Повітря" },
    "object": {
      "id": 276873,
      "external_id": "325472110068",
      "type_id": 9,
      "type_name": "Звіт про викиди забруднюючих речовин і парникових газів в атмосферне повітря від стаціонарних джерел викидів – № 2-ТП (повітря) (річна) (Держстат)",
      "registry_id": null,
      "authority_name": "Державна служба статистики України",
      "name": "Річний водний звіт",
      "description_lines": [],
      "address": null,
      "report_year": 2024,
      "report_date": "2025-02-10",
      "uploaded_at": "2025-02-10T09:00:00+00:00",
      "downloaded_at": "2025-02-10T09:15:00+00:00",
      "files_count": 1,
      "links": {
        "files": "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-files/276873",
        "details": "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-details/276873"
      },
      "permissions": []
    },
    "details": {
      "kind": "annual_data",
      "items": [
        {
          "code": "K00000",
          "name": "Усього по підприємству (без урахування діоксиду вуглецю)",
          "unit": "тонн",
          "unit_decimals": 3,
          "value": 10.001
        },
        {
          "code": "K03000",
          "name": "Речовини у вигляді суспендованих твердих частинок (мікрочастинки та волокна )",
          "unit": "тонн",
          "unit_decimals": 3,
          "value": 6.134
        },
        {
          "code": "K04000",
          "name": "Сполуки азоту",
          "unit": "тонн",
          "unit_decimals": 3,
          "value": 1.978
        },
        {
          "code": "K04001",
          "name": "Оксиди азоту (у перерахунку на діоксид азоту [NO + NО2])",
          "unit": "тонн",
          "unit_decimals": 3,
          "value": 1.976
        },
        {
          "code": "K04002",
          "name": "Азоту (1) оксид [N2О]",
          "unit": "тонн",
          "unit_decimals": 3,
          "value": 0.002
        },
        {
          "code": "K06000",
          "name": "Оксид вуглецю",
          "unit": "тонн",
          "unit_decimals": 3,
          "value": 1.757
        },
        {
          "code": "K07000",
          "name": "Вуглецю діоксид",
          "unit": "тонн",
          "unit_decimals": 3,
          "value": 335.931
        },
        {
          "code": "K11000",
          "name": "Неметанові леткі органічні сполуки (НМЛОС)",
          "unit": "тонн",
          "unit_decimals": 3,
          "value": 0.11
        },
        {
          "code": "K12000",
          "name": "Метан",
          "unit": "тонн",
          "unit_decimals": 3,
          "value": 0.022
        }
      ]
    }
  },
  "stats": { "..." }
}

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

`results.object`

Поля об'єкта ті самі, що й у results.items[] в переліку звітів.

`results.details`

null: для звітів, у яких немає окремих структурованих річних даних.
kind: тип структурованих даних. Зараз використовується значення annual_data.

Якщо звіт має просту структуру:

items[]: плоский перелік показників.
items[].code: код показника.
items[].name: назва показника.
items[].unit: одиниця виміру.
items[].unit_decimals: рекомендована кількість десяткових знаків.
items[].value: значення показника.

Якщо звіт має секції:

sections[]: перелік секцій звіту.
sections[].number: номер секції.
sections[].name: назва секції.
sections[].columns[]: колонки всередині секції.
sections[].columns[].code: код колонки.
sections[].columns[].name: назва колонки.
sections[].groups[]: групи показників усередині секції.
sections[].groups[].number: номер групи.
sections[].groups[].name: назва групи.
sections[].groups[].items[]: перелік показників усередині групи.
sections[].groups[].items[].code: код показника.
sections[].groups[].items[].name: назва показника.
sections[].groups[].items[].unit: одиниця виміру.
sections[].groups[].items[].unit_decimals: рекомендована кількість десяткових знаків.
sections[].groups[].items[].values[]: перелік значень показника.
sections[].groups[].items[].values[].column_code: код колонки показника.
sections[].groups[].items[].values[].column_name: назва колонки показника.
sections[].groups[].items[].values[].amount: значення показника.

Файли звіту

GET /api/v1/enterprises/{registry_id}/report-files/{report_id}

Цей запит повертає файли конкретного звіту. Разом із переліком файлів items повертається блок object з короткою інформацією про сам звіт.

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

$ ESG_API_TOKEN="your_api_token"
$ curl "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-files/276873" \
  -H "Authorization: Bearer $ESG_API_TOKEN" \
  -H 'Accept: application/json'

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

{
  "results": {
    "enterprise": { "type": "company", "registry_id": "00178353" },
    "object": {
      "type": "report",
      "id": 276873,
      "registry_id": "2-ТП-2021",
      "type_id": 9,
      "type_name": "Звіт про викиди забруднюючих речовин",
      "name": "Звіт № 2-ТП (повітря)"
    },
    "items": [
      {
        "id": 276873,
        "type_name": "PDF",
        "name": "report-2021.pdf",
        "format": "pdf",
        "size": 120972,
        "uploaded_at": "2022-02-01T10:00:00+00:00",
        "downloaded_at": "2022-02-03T14:20:00+00:00",
        "links": {
          "download": "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-files/276873/download/276873"
        }
      }
    ]
  },
  "stats": { "..." }
}

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

`results.object`

type: тип об'єкта. Для цього запиту використовується значення report.
id: ідентифікатор звіту.
registry_id: реєстраційний номер звіту, якщо він є.
type_id: ідентифікатор типу звіту.
type_name: назва типу звіту.
name: назва звіту.

`results.items[]`

id: ідентифікатор файла звіту.
type_name: назва типу файла або документа.
name: назва файла.
format: формат файла, наприклад pdf або docx.
size: розмір файла в байтах.
uploaded_at: дата, коли файл було завантажено або оприлюднено в джерелі.
downloaded_at: дата, коли файл був завантажений у систему ESG SaveEcoBot.
links.download: посилання на завантаження конкретного файла.

Завантаження файла звіту

GET /api/v1/enterprises/{registry_id}/report-files/{report_id}/download/{file_id}

Цей запит повертає бінарний файл звіту для завантаження.

Параметри registry_id, report_id і file_id в адресі запиту є обов'язковими. registry_id — це ідентифікатор підприємства. report_id — це ідентифікатор звіту. file_id — це ідентифікатор файла звіту.

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

$ ESG_API_TOKEN="your_api_token"
$ curl -L "https://esg.saveecobot.com/api/v1/enterprises/00178353/report-files/276873/download/276873" \
  -H "Authorization: Bearer $ESG_API_TOKEN"

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

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="report-2021.pdf"

Перелік звітів

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

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

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

Фільтри

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

results.items[]

results.meta

Деталі звіту

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

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

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

results.object

results.details

Файли звіту

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

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

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

results.object

results.items[]

Завантаження файла звіту

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

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

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

`results.items[]`

`results.meta`

`results.object`

`results.details`

`results.object`

`results.items[]`