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