# Grupy spółek
> Grupy spółek: do których spółek sięga klucz, nagłówek Ocost-Business, przekierowanie po identyfikatorach dokumentu, needs_company i pliki w grupie.
>
> Najpierw: [Klucze i uprawnienia](https://ocost.io/docs/pl/authentication.md)

Grupa to spółki, które jeden właściciel prowadzi w Ocost. Jeden klucz API może wysyłać i czytać dla kilku z nich. Ta strona mówi, do których spółek sięga klucz i gdzie trafia każdy plik.

## Do czego sięga klucz

Klucz należy do spółki, w której go utworzono, swojej spółki macierzystej. Tylko właściciel daje mu inne spółki grupy w [Ustawienia › Programiści](https://app.ocost.io/settings/api). To wybrane spółki albo wszystkie, także dodane później. Może to też zrobić wsparcie Ocost, a każdą zmianę widać w Ustawieniach. Nowy klucz sięga tylko swojej spółki macierzystej.

Klucz i jego sekret pozostają te same, gdy zmieniają się jego spółki. Spółkę, do której już nie sięga, Ocost odrzuca od następnego żądania. Tak samo spółkę, która opuściła grupę.

`GET /public/v1/businesses` wymienia spółki, do których sięga klucz, najpierw spółkę macierzystą. Może o to zapytać każdy klucz.

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

## Wskaż spółkę

Wskaż spółkę żądania nagłówkiem `Ocost-Business` z jej identyfikatorem. Decyduje nagłówek, a Ocost niczego nie przekierowuje. Bez niego żądanie działa w spółce macierzystej klucza.

```bash
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"
```

Plik wysłany w ten sposób ma `routed_by: header`. Spółkę, do której klucz nie sięga, Ocost odrzuca z `403 urn:ocost:key:business`. Nagłówek, który nie jest identyfikatorem, daje `400`.

## Niech zdecyduje dokument

Wyślij bez `Ocost-Business`, a klucz, który sięga kilku spółek, przekieruje plik. Ocost zapisuje go i odczytuje w spółce macierzystej klucza. Zanim zapisze cokolwiek z odczytu, szuka spółek grupy na dokumencie.

Liczy się tylko dokładny identyfikator spółki:

| Na dokumencie | `routed_by` |
| --- | --- |
| Numer VAT UE lub inny numer podatkowy albo firmowy, na przykład ІПН, NIP, EIN lub IDNO | `vat_id` |
| Numer podatkowy, na przykład Steuernummer | `tax_number` |
| ЄДРПОУ lub РНОКПП | `edrpou` |
| Numer rejestru z sądem | `register` |
| IBAN spółki jako konto do zapłaty | `iban` |

Faktura przychodząca wskazuje spółkę jako nabywcę, wychodząca jako sprzedawcę. Umowa może wskazać każdą ze stron. Numer odczytany z wątpliwościami nigdy się nie liczy. Nazwa lub adres też nie.

Numer strony może stać poza jej blokiem, na przykład w tytule płatności "… для ТОВ «Приклад» 42135797" lub w stopce. Ocost przypisuje go stronie, po której stoi. Jeśli żadna strona nie ma numeru spółki, liczy się numer w dowolnym miejscu tekstu, nigdy spółki sprzedawcy.

| Dokument wskazuje | Plik |
| --- | --- |
| Jedną spółkę jej identyfikatorem | Przenosi się tam, z `routed_by` jak wyżej |
| Żadnej spółki grupy | Zostaje w spółce macierzystej klucza, z `routed_by: home` |
| Dwie spółki albo inną tylko z nazwy | Czeka jako `needs_company` w spółce macierzystej |

Przeniesiony plik zachowuje swój identyfikator. Liczy się do dokumentów miesiąca spółki, do której trafił.

## Przypisz czekający plik

Czekający plik wymienia swoje `candidates`, każdego z `why`. Najpierw są spółki wskazane przez dokument, na końcu spółka macierzysta klucza.

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

W Ocost odpowiada właściciel lub księgowy w Dziś › Przypisz. Albo odpowiedz wcześniej przez `PATCH /public/v1/files/{file_id}`:

```bash
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"}'
```

Każda odpowiedź ustawia `routed_by: person`. Do spółki musi sięgać Twój klucz i klucz, który wysłał plik. Plik, który nie czeka, daje `409`.

## Znajdź pliki w grupie

Klucz, który nie wskazuje spółki, znajduje wysłane przez siebie pliki w każdej spółce, do której sięga. `GET /public/v1/files/{file_id}`, jego treść i dokument działają po samym identyfikatorze pliku. `DELETE` też.

`GET /public/v1/files` wymienia pliki spółki macierzystej i te, które klucz wysłał gdzie indziej. `business_id` każdego pliku mówi, gdzie jest. Parametr `business_id` zostawia pliki jednej spółki:

```bash
curl -sS -G https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  --data-urlencode "business_id=018f3c2a-9a04-7c21-8e5b-6d2f4c0a9e15"
```

Te same bajty, które już są w spółce w zasięgu klucza, zwracają ten plik. Ocost liczy je raz.

## MCP w grupie

[Serwer MCP](https://ocost.io/docs/pl/mcp.md) przyjmuje te same klucze i ten sam nagłówek. `send_file` bez `Ocost-Business` przekierowuje jak wyżej. Każde inne narzędzie działa w spółce wskazanej nagłówkiem, a bez niego w spółce macierzystej klucza. Każde wywołanie zostaje przy kluczu, w jego spółce macierzystej, ze spółką, w której działało.

## Zobacz też

- [Klucze i uprawnienia](https://ocost.io/docs/pl/authentication.md): Klucze API: jak niesie je żądanie, ich wymiana, ich uprawnienia i odmowy.
- [Statusy i powody](https://ocost.io/docs/pl/statuses.md): Statusy pliku i powody, dla których nie został odczytany, oraz co zrobić w każdym przypadku.
- [Dokument](https://ocost.io/docs/pl/document.md): Schemat ocost.document.v1 w pojęciach EN 16931 (odwzorowywalny na UBL i CII): przykład, rodzaj i kierunek, źródła, kontrole, wersje oraz każde pole i każda wartość.
- [Podłączyć asystenta](https://ocost.io/docs/pl/mcp.md): Podłączyć asystenta do serwera MCP (https://api.ocost.io/public/mcp, te same klucze): Claude Code, Claude Desktop, Cursor, claude.ai i ChatGPT przez OAuth oraz każdy klient.
