# Группы компаний
> Группы компаний: до каких компаний достаёт ключ, заголовок Ocost-Business, перенаправление по кодам документа, needs_company и файлы в группе.
>
> Сначала: [Ключи и права](https://ocost.io/docs/ru/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/ru/mcp.md) принимает те же ключи и тот же заголовок. `send_file` без `Ocost-Business` перенаправляет, как выше. Любой другой инструмент действует в компании, которую называет заголовок, иначе в домашней компании ключа. Каждый вызов остаётся с ключом, в его домашней компании, с компанией, где он действовал.

## См. также

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