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.

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 }
  ]
}

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.

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"

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 documentrouted_by
VAT ID, or another tax or company number, such as an ІПН, NIP, EIN or IDNOvat_id
Tax number, such as a Steuernummertax_number
ЄДРПОУ or РНОКППedrpou
Register number with its courtregister
The company's IBAN, as the account to pay intoiban

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 namesThe file
One company by its identifierMoves there, with routed_by as above
No company of the groupStays in the key's home, with routed_by: home
Two companies, or another one by its name aloneWaits 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.

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" }
  ]
}

In Ocost, the owner or the accountant answers under Today › Assign. Or answer first with 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"}'

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:

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"

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.

See also