Company groups
A group is the companies one owner runs in Ocost. One API key can send and read for several of them.
What a key reaches
A key belongs to the company it was made in, its home. Only the owner gives it more companies of the group under Settings › Developers: a selection, or all, those joining later too. Ocost's support can set them too, each change shown under Settings. A new key reaches its home alone.
Its secret stays the same when its companies change. A company it no longer reaches, or that leaves the group, is refused from the next request.
GET /public/v1/businesses lists the companies a key reaches, its home first. Every key may ask it.
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 }
]
}Name the company
Name the company a request acts in with the Ocost-Business header, its id. The header decides, and Ocost routes nothing. Without it, a request acts in the key's home.
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"A file sent this way has routed_by: header. A company the key doesn't reach is refused with 403 urn:ocost:key:business. A header that isn't an id is a 400.
Let the document decide
Send without Ocost-Business, and a key that reaches several companies routes the file. Ocost reads it in the key's home and looks for the group's companies on the document before writing anything.
Only an exact identifier of a company counts:
| On the document | routed_by |
|---|---|
| VAT ID, or another tax or company number, such as an ІПН, NIP, EIN or IDNO | vat_id |
| Tax number, such as a Steuernummer | tax_number |
| ЄДРПОУ or РНОКПП | edrpou |
| Register number with its court | register |
| The company's IBAN, as the account to pay into | iban |
An incoming invoice names the company as its buyer, an outgoing one as its seller. A contract may name either party. A number read in doubt never counts. Neither does a name or an address.
A party's number may stand outside its block, as in a payment purpose "… для ТОВ «Приклад» 42135797" or a footer. Ocost attaches it to the party it follows. If no party carries a company's number, one anywhere in the text counts, never the seller's company's.
| The document names | The file |
|---|---|
| One company by its identifier | Moves there, with routed_by as above |
| No company of the group | Stays in the key's home, with routed_by: home |
| Two companies, or another one by its name alone | Waits as needs_company in the home |
A moved file keeps its id and counts in the month of the company it moved to.
Assign a waiting file
A waiting file lists its candidates, each with why. The companies the document names come first, the key's home last.
{
"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" }
]
}In Ocost, the owner or the accountant answers under Today › Assign. Or answer first with 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"}'Either answer sets routed_by: person. Both your key and the sending key must reach the company. A file that doesn't wait answers 409.
Find files across the group
A key that names no company finds the files it sent in every company it reaches. GET /public/v1/files/{file_id}, its content and its document work by the file's id alone. So does DELETE.
GET /public/v1/files lists the home's files and those the key sent elsewhere. Each file's business_id says where it is. The business_id query keeps one company's:
curl -sS -G https://api.ocost.io/public/v1/files \
-H "Authorization: Bearer $OCOST_KEY" \
--data-urlencode "business_id=018f3c2a-9a04-7c21-8e5b-6d2f4c0a9e15"The same bytes already kept in a company of the reach answer that file. Ocost counts them once.
The MCP in a group
The MCP server takes the same keys and the same header. send_file without Ocost-Business routes as above. Every other tool acts in the company the header names, else in the key's home.