# Grupos de empresas
> Grupos de empresas: a qué sociedades llega una clave, la cabecera Ocost-Business, el enrutado por los identificadores del documento, needs_company y los archivos del grupo.
>
> Antes: [Claves y permisos](https://ocost.io/docs/es/authentication.md)

Un grupo son las sociedades que un propietario lleva en Ocost. Una sola clave de API puede enviar y leer para varias de ellas.

## A qué llega una clave

Una clave pertenece a la sociedad donde se creó, su sociedad de origen. Solo el propietario le da otras sociedades del grupo en [Ajustes › Desarrolladores](https://app.ocost.io/settings/api). Es una selección, o todas, también las que se añadan después. El soporte de Ocost también puede fijarlas, y cada cambio aparece en Ajustes. Una clave nueva solo llega a su sociedad de origen.

La clave y su secreto siguen siendo los mismos cuando cambian sus sociedades. Una sociedad a la que ya no llega se rechaza desde la siguiente petición. Igual que una sociedad que deja el grupo.

`GET /public/v1/businesses` lista las sociedades a las que llega una clave, su sociedad de origen primero. Cualquier clave puede preguntarlo.

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

## Nombrar la sociedad

Nombra la sociedad de una petición con la cabecera `Ocost-Business`, su identificador. La cabecera decide, y Ocost no enruta nada. Sin ella, la petición actúa en la sociedad de origen de la clave.

```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 archivo enviado así tiene `routed_by: header`. Una sociedad a la que la clave no llega se rechaza con `403 urn:ocost:key:business`. Una cabecera que no es un identificador da `400`.

## Dejar que decida el documento

Envía sin `Ocost-Business`, y una clave que llega a varias sociedades enruta el archivo. Ocost lo guarda y lo lee en la sociedad de origen de la clave. Antes de escribir nada de la lectura, busca las sociedades del grupo en el documento.

Solo cuenta un identificador exacto de una sociedad:

| En el documento | `routed_by` |
| --- | --- |
| NIF-IVA, u otro número fiscal o de empresa, como un ІПН, un NIP, un EIN o un IDNO | `vat_id` |
| Número fiscal, como una Steuernummer | `tax_number` |
| ЄДРПОУ o РНОКПП | `edrpou` |
| Número de registro con su juzgado | `register` |
| El IBAN de la sociedad, como cuenta para el pago | `iban` |

Una factura recibida nombra a la sociedad como compradora, una emitida como vendedora. Un contrato puede nombrar a cualquiera de las partes. Un número leído con dudas nunca cuenta. Tampoco un nombre o una dirección.

El número de una parte puede estar fuera de su bloque, como en un concepto de pago "… для ТОВ «Приклад» 42135797" o un pie de página. Ocost lo asigna a la parte a la que sigue. Si ninguna parte lleva el número de una sociedad, cuenta uno en cualquier parte del texto, nunca el de la sociedad del vendedor.

| El documento nombra | El archivo |
| --- | --- |
| Una sociedad por su identificador | Se mueve allí, con `routed_by` como arriba |
| Ninguna sociedad del grupo | Se queda en la sociedad de origen de la clave, con `routed_by: home` |
| Dos sociedades, u otra solo por su nombre | Espera como `needs_company` en la sociedad de origen |

Un archivo movido conserva su id. Cuenta entre los documentos del mes de la sociedad a la que se movió.

## Asignar un archivo en espera

Un archivo en espera lista sus `candidates`, cada uno con `why`. Primero van las sociedades que nombra el documento, al final la sociedad de origen de la clave.

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

En Ocost, el propietario o el contable responde en Hoy › Asignar. O responde antes con `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"}'
```

Cualquier respuesta pone `routed_by: person`. La sociedad tiene que estar al alcance de tu clave y de la clave que envió el archivo. Un archivo que no espera da `409`.

## Encontrar archivos en el grupo

Una clave que no nombra ninguna sociedad encuentra los archivos que envió en cada sociedad a la que llega. `GET /public/v1/files/{file_id}`, su contenido y su documento funcionan solo con el id del archivo. `DELETE` también.

`GET /public/v1/files` lista los archivos de la sociedad de origen y los que la clave envió a otras. El `business_id` de cada archivo dice dónde está. El parámetro `business_id` deja los de una sociedad:

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

Los mismos bytes que ya están en una sociedad a su alcance devuelven ese archivo. Ocost los cuenta una vez.

## El MCP en un grupo

El [servidor MCP](https://ocost.io/docs/es/mcp.md) acepta las mismas claves y la misma cabecera. `send_file` sin `Ocost-Business` enruta como arriba. Cualquier otra herramienta actúa en la sociedad que nombra la cabecera, si no, en la sociedad de origen de la clave.

## Véase también

- [Claves y permisos](https://ocost.io/docs/es/authentication.md): Claves de API: cómo las lleva una solicitud, cómo rotarlas, sus permisos y los rechazos.
- [Estados y motivos](https://ocost.io/docs/es/statuses.md): Los estados de un archivo y los motivos por los que no se leyó, y qué hacer en cada caso.
- [El documento](https://ocost.io/docs/es/document.md): El esquema ocost.document.v1 en términos de EN 16931 (se corresponde con UBL y CII): un ejemplo, tipo y dirección, fuentes, comprobaciones, versiones, y cada campo y valor.
- [Conectar un asistente](https://ocost.io/docs/es/mcp.md): Conectar un asistente al servidor MCP (https://api.ocost.io/public/mcp, las mismas claves): Claude Code, Claude Desktop, Cursor, claude.ai y ChatGPT por OAuth, y cualquier cliente.
