# Groupes de sociétés
> Groupes de sociétés : les sociétés qu’une clé atteint, l’en-tête Ocost-Business, l’orientation par les identifiants du document, needs_company et les fichiers du groupe.
>
> Avant: [Clés et autorisations](https://ocost.io/docs/fr/authentication.md)

Un groupe, ce sont les sociétés qu’un propriétaire gère dans Ocost. Une seule clé d’API peut envoyer et lire pour plusieurs d’entre elles. Cette page dit quelles sociétés une clé atteint et où chaque fichier arrive.

## Ce qu’une clé atteint

Une clé appartient à la société où elle a été créée, sa société d’origine. Seul le propriétaire lui donne d’autres sociétés du groupe dans [Paramètres › Développeurs](https://app.ocost.io/settings/api). C’est une sélection, ou toutes, y compris celles ajoutées plus tard. Le support d’Ocost peut aussi les définir, et chaque changement apparaît dans Paramètres. Une nouvelle clé n’atteint que sa société d’origine.

La clé et son secret restent les mêmes quand ses sociétés changent. Une société qu’elle n’atteint plus est refusée dès la requête suivante. De même pour une société qui quitte le groupe.

`GET /public/v1/businesses` liste les sociétés qu’une clé atteint, sa société d’origine d’abord. Toute clé peut le demander.

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

## Nommer la société

Nommez la société d’une requête avec l’en-tête `Ocost-Business`, son identifiant. L’en-tête décide, et Ocost n’oriente rien. Sans lui, la requête agit dans la société d’origine de la clé.

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

Un fichier ainsi envoyé a `routed_by: header`. Une société que la clé n’atteint pas est refusée avec `403 urn:ocost:key:business`. Un en-tête qui n’est pas un identifiant donne `400`.

## Laisser le document décider

Envoyez sans `Ocost-Business`, et une clé qui atteint plusieurs sociétés oriente le fichier. Ocost le stocke et le lit dans la société d’origine de la clé. Avant d’écrire quoi que ce soit de la lecture, il cherche les sociétés du groupe sur le document.

Seul un identifiant exact d’une société compte :

| Sur le document | `routed_by` |
| --- | --- |
| N° de TVA, ou un autre numéro fiscal ou d'entreprise, comme un ІПН, un NIP, un EIN ou un IDNO | `vat_id` |
| N° fiscal, comme une Steuernummer | `tax_number` |
| ЄДРПОУ ou РНОКПП | `edrpou` |
| N° de registre avec son tribunal | `register` |
| L’IBAN de la société, comme compte à payer | `iban` |

Une facture reçue nomme la société comme acheteur, une facture émise comme vendeur. Un contrat peut nommer l’une ou l’autre partie. Un numéro lu dans le doute ne compte jamais. Un nom ou une adresse non plus.

Le numéro d'une partie peut figurer hors de son bloc, comme dans un motif de paiement "… для ТОВ «Приклад» 42135797" ou un pied de page. Ocost le rattache à la partie qu'il suit. Si aucune partie ne porte le numéro d'une société, un numéro n'importe où dans le texte compte, jamais celui de la société du vendeur.

| Le document nomme | Le fichier |
| --- | --- |
| Une société par son identifiant | Y est déplacé, avec `routed_by` comme ci-dessus |
| Aucune société du groupe | Reste dans la société d’origine de la clé, avec `routed_by: home` |
| Deux sociétés, ou une autre par son seul nom | Attend en `needs_company` dans la société d’origine |

Un fichier déplacé garde son identifiant. Il compte parmi les documents du mois de la société où il a été déplacé.

## Attribuer un fichier en attente

Un fichier en attente liste ses `candidates`, chacun avec `why`. Les sociétés que le document nomme viennent d’abord, la société d’origine de la clé en dernier.

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

Dans Ocost, le propriétaire ou le comptable répond dans Aujourd’hui › Attribuer. Ou répondez avant avec `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"}'
```

Chaque réponse met `routed_by: person`. La société doit être atteinte par votre clé et par la clé qui a envoyé le fichier. Un fichier qui n’attend pas donne `409`.

## Trouver les fichiers du groupe

Une clé qui ne nomme aucune société trouve les fichiers qu’elle a envoyés dans chaque société qu’elle atteint. `GET /public/v1/files/{file_id}`, son contenu et son document marchent avec le seul identifiant du fichier. `DELETE` aussi.

`GET /public/v1/files` liste les fichiers de la société d’origine et ceux que la clé a envoyés ailleurs. Le `business_id` de chaque fichier dit où il est. Le paramètre `business_id` garde ceux d’une société :

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

Les mêmes octets déjà présents dans une société atteinte renvoient ce fichier. Ocost les compte une fois.

## Le MCP dans un groupe

Le [serveur MCP](https://ocost.io/docs/fr/mcp.md) prend les mêmes clés et le même en-tête. `send_file` sans `Ocost-Business` oriente comme ci-dessus. Tout autre outil agit dans la société que l’en-tête nomme, sinon dans la société d’origine de la clé. Chaque appel est gardé avec la clé, dans sa société d’origine, avec la société où il a agi.

## Voir aussi

- [Clés et autorisations](https://ocost.io/docs/fr/authentication.md): Les clés d'API : comment une requête en porte une, leur renouvellement, leurs autorisations et les refus.
- [Statuts et raisons](https://ocost.io/docs/fr/statuses.md): Les statuts d'un fichier et les raisons pour lesquelles il n'a pas été lu, et que faire pour chacun.
- [Le document](https://ocost.io/docs/fr/document.md): Le schéma ocost.document.v1 dans les termes de l'EN 16931 (transposable en UBL et CII) : un exemple, type et sens, sources, contrôles, versions, et chaque champ et chaque valeur.
- [Connecter un assistant](https://ocost.io/docs/fr/mcp.md): Connecter un assistant au serveur MCP (https://api.ocost.io/public/mcp, les mêmes clés) : Claude Code, Claude Desktop, Cursor, claude.ai et ChatGPT par OAuth, et tout client.
