Группы компаний

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

До чего достаёт ключ

Ключ принадлежит компании, в которой его создали, своей домашней компании. Только владелец даёт ему другие компании группы, в Настройки › Разработчикам. Это выбранные компании или все, включая добавленные позже. Задать их может и поддержка Ocost, и каждое изменение видно в Настройках. Новый ключ достаёт только до своей домашней компании.

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

GET /public/v1/businesses перечисляет компании, до которых достаёт ключ, сначала домашнюю. Это может спросить любой ключ.

Shell
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 ничего не перенаправляет. Без него запрос действует в домашней компании ключа.

Shell
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 или IDNOvat_id
Налоговый номер, например Steuernummertax_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}:

Shell
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 оставляет файлы одной компании:

Shell
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 перенаправляет, как выше. Любой другой инструмент действует в компании, которую называет заголовок, иначе в домашней компании ключа. Каждый вызов остаётся с ключом, в его домашней компании, с компанией, где он действовал.

См. также