# Групи компаній
> Групи компаній: яких компаній сягає ключ, заголовок Ocost-Business, перенаправлення за кодами документа, needs_company і файли в групі.
>
> Спершу: [Ключі та дозволи](https://ocost.io/docs/uk/authentication.md)

Група — це компанії, які один власник веде в Ocost. Один ключ API може надсилати й читати для кількох із них. Ця сторінка каже, яких компаній сягає ключ і куди потрапляє кожен файл.

## Чого сягає ключ

Ключ належить компанії, у якій його створено, своїй домашній компанії. Лише власник дає йому інші компанії групи, у [Налаштування › Розробникам](https://app.ocost.io/settings/api). Це вибрані компанії або всі, зокрема додані пізніше. Задати їх може й підтримка Ocost, і кожну зміну видно в Налаштуваннях. Новий ключ сягає лише своєї домашньої компанії.

Ключ і його секрет лишаються ті самі, коли змінюються його компанії. Компанію, якої він більше не сягає, Ocost відхиляє з наступного запиту. Так само компанію, що вийшла з групи.

`GET /public/v1/businesses` перелічує компанії, яких сягає ключ, спершу домашню. Це може запитати будь-який ключ.

```bash
curl -sS https://api.ocost.io/public/v1/businesses \
  -H "Authorization: Bearer $OCOST_KEY"
```

```json
{
  "businesses": [
    { "id": "018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77", "name": "Beispiel Holding GmbH", "own": true },
    { "id": "018f3c2a-9a04-7c21-8e5b-6d2f4c0a9e15", "name": "Beispiel Nord GmbH", "own": false },
    { "id": "018f3c2a-b5e7-7f42-9d13-4a8c2e6f1b09", "name": "Beispiel Süd GmbH", "own": false }
  ]
}
```

## Назвіть компанію

Назвіть компанію запиту заголовком `Ocost-Business` з її ідентифікатором. Вирішує заголовок, і Ocost нічого не перенаправляє. Без нього запит діє в домашній компанії ключа.

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Ocost-Business: 018f3c2a-9a04-7c21-8e5b-6d2f4c0a9e15" \
  -F "file=@invoice.pdf"
```

Файл, надісланий так, має `routed_by: header`. Компанію, якої ключ не сягає, Ocost відхиляє з `403 urn:ocost:key:business`. Заголовок, що не є ідентифікатором, дає `400`.

## Хай вирішить документ

Надішліть без `Ocost-Business`, і ключ, що сягає кількох компаній, перенаправить файл. Ocost зберігає й читає його в домашній компанії ключа. Перш ніж записати щось із прочитаного, він шукає компанії групи на документі.

Рахується лише точний код компанії:

| На документі | `routed_by` |
| --- | --- |
| Номер ПДВ чи інший податковий або реєстраційний номер, як-от ІПН, NIP, EIN чи IDNO | `vat_id` |
| Податковий номер, наприклад Steuernummer | `tax_number` |
| ЄДРПОУ чи РНОКПП | `edrpou` |
| Реєстраційний номер із судом | `register` |
| IBAN компанії як рахунок для оплати | `iban` |

Вхідний рахунок називає компанію покупцем, вихідний — продавцем. Договір може назвати будь-яку сторону. Номер, прочитаний із сумнівом, не рахується ніколи. Назва чи адреса теж ні.

Номер сторони може стояти поза її блоком, як у призначенні платежу "… для ТОВ «Приклад» 42135797" чи в нижньому колонтитулі. Ocost приписує його стороні, після якої він стоїть. Якщо жодна сторона не має номера компанії, рахується номер будь-де в тексті, але ніколи не компанії продавця.

| Документ називає | Файл |
| --- | --- |
| Одну компанію її кодом | Переїжджає туди, з `routed_by` як вище |
| Жодної компанії групи | Лишається в домашній компанії ключа, з `routed_by: home` |
| Дві компанії або іншу лише за назвою | Чекає як `needs_company` у домашній компанії |

Перенесений файл зберігає свій id. Він рахується до документів місяця тієї компанії, куди переїхав.

## Призначте файл, що чекає

Файл, що чекає, перелічує свої `candidates`, кожен із `why`. Спершу компанії, які називає документ, наприкінці домашня компанія ключа.

```json
{
  "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
  "status": "needs_company",
  "business_id": "018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77",
  "routed_by": null,
  "candidates": [
    { "business_id": "018f3c2a-9a04-7c21-8e5b-6d2f4c0a9e15", "name": "Beispiel Nord GmbH", "why": "vat_id" },
    { "business_id": "018f3c2a-b5e7-7f42-9d13-4a8c2e6f1b09", "name": "Beispiel Süd GmbH", "why": "vat_id" },
    { "business_id": "018f3c2a-7d1e-7b6a-9c40-2f5e8a1b3d77", "name": "Beispiel Holding GmbH", "why": "home" }
  ]
}
```

В Ocost власник або бухгалтер відповідає в розділі Сьогодні › Розподілити. Або дайте відповідь раніше через `PATCH /public/v1/files/{file_id}`:

```bash
curl -sS -X PATCH https://api.ocost.io/public/v1/files/$FILE_ID \
  -H "Authorization: Bearer $OCOST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"business_id": "018f3c2a-9a04-7c21-8e5b-6d2f4c0a9e15"}'
```

Будь-яка відповідь ставить `routed_by: person`. Цієї компанії мають сягати і ваш ключ, і ключ, що надіслав файл. Файл, що не чекає, дає `409`.

## Файли в групі

Ключ, що не називає компанії, знаходить надіслані ним файли в кожній компанії, якої сягає. `GET /public/v1/files/{file_id}`, його вміст і документ працюють лише за id файлу. `DELETE` теж.

`GET /public/v1/files` перелічує файли домашньої компанії і ті, що ключ надіслав деінде. `business_id` кожного файлу каже, де він лежить. Параметр `business_id` лишає файли однієї компанії:

```bash
curl -sS -G https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  --data-urlencode "business_id=018f3c2a-9a04-7c21-8e5b-6d2f4c0a9e15"
```

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

## MCP у групі

[Сервер MCP](https://ocost.io/docs/uk/mcp.md) приймає ті самі ключі й той самий заголовок. `send_file` без `Ocost-Business` перенаправляє, як вище. Будь-який інший інструмент діє в компанії, яку називає заголовок, інакше в домашній компанії ключа. Кожен виклик лишається з ключем, у його домашній компанії, з компанією, де він діяв.

## Див. також

- [Ключі та дозволи](https://ocost.io/docs/uk/authentication.md): Ключі API: як запит їх передає, заміна ключів, їхні дозволи і відмови.
- [Статуси та причини](https://ocost.io/docs/uk/statuses.md): Статуси файлу і причини, з яких його не прочитано, і що робити в кожному випадку.
- [Документ](https://ocost.io/docs/uk/document.md): Схема ocost.document.v1 у термінах EN 16931 (відображається на UBL і CII): приклад, вид і напрям, джерела, перевірки, версії, кожне поле і значення.
- [Підключити асистента](https://ocost.io/docs/uk/mcp.md): Підключити асистента до сервера MCP (https://api.ocost.io/public/mcp, ті самі ключі): Claude Code, Claude Desktop, Cursor, claude.ai і ChatGPT через OAuth, а також будь-який клієнт.
