Группы компаний
Группа — это компании, которые один владелец ведёт в Ocost. Один ключ API может отправлять и читать для нескольких из них. Эта страница говорит, до каких компаний достаёт ключ и куда попадает каждый файл.
До чего достаёт ключ
Ключ принадлежит компании, в которой его создали, своей домашней компании. Только владелец даёт ему другие компании группы, в Настройки › Разработчикам. Это выбранные компании или все, включая добавленные позже. Задать их может и поддержка Ocost, и каждое изменение видно в Настройках. Новый ключ достаёт только до своей домашней компании.
Ключ и его секрет остаются прежними, когда меняются его компании. Компанию, до которой он больше не достаёт, Ocost отклоняет со следующего запроса. Так же и компанию, вышедшую из группы.
GET /public/v1/businesses перечисляет компании, до которых достаёт ключ, сначала домашнюю. Это может спросить любой ключ.
curl -sS https://api.ocost.io/public/v1/businesses \
-H "Authorization: Bearer $OCOST_KEY"{
"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 ничего не перенаправляет. Без него запрос действует в домашней компании ключа.
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. Сначала компании, которые называет документ, в конце домашняя компания ключа.
{
"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}:
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 оставляет файлы одной компании:
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 принимает те же ключи и тот же заголовок. send_file без Ocost-Business перенаправляет, как выше. Любой другой инструмент действует в компании, которую называет заголовок, иначе в домашней компании ключа. Каждый вызов остаётся с ключом, в его домашней компании, с компанией, где он действовал.