Groupes de sociétés

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. 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.

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

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é.

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"

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 documentrouted_by
N° de TVA, ou un autre numéro fiscal ou d'entreprise, comme un ІПН, un NIP, un EIN ou un IDNOvat_id
N° fiscal, comme une Steuernummertax_number
ЄДРПОУ ou РНОКППedrpou
N° de registre avec son tribunalregister
L’IBAN de la société, comme compte à payeriban

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 nommeLe fichier
Une société par son identifiantY est déplacé, avec routed_by comme ci-dessus
Aucune société du groupeReste dans la société d’origine de la clé, avec routed_by: home
Deux sociétés, ou une autre par son seul nomAttend 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} :

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

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é :

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"

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