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

Група — це компанії, які один власник веде в 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 перенаправляє, як вище. Будь-який інший інструмент діє в компанії, яку називає заголовок, інакше в домашній компанії ключа. Кожен виклик лишається з ключем, у його домашній компанії, з компанією, де він діяв.

Див. також