Multiempresa

Si conectas varias empresas (por ejemplo, una gestoría con su cartera), trabajas con una API key por empresa. Esta página explica cómo se liga una clave a su empresa y cómo organizarlas.

Una clave, una empresa

Cada API key pertenece a una sola empresa. Se crea desde esa empresa en la aplicación, en Configuración → API Keys, con permiso para gestionar su configuración.
La empresa sale de la clave. Las rutas de /api/v1.1 no llevan identificador de empresa: todo lo que haces con una clave afecta a su empresa y solo a ella.
Un recurso de otra empresa responde como si no existiera (404).

Para operar otra empresa, usa la clave de esa empresa.

Consultar la empresa de una clave

`GET /api/v1.1/company`

Devuelve la empresa de la clave. No exige scope.

curl https://app.faxtal.com/api/v1.1/company \
  -H "X-API-Key: fctXXXXXXXX_YYYYYYYYYYYYYYYY"

{
  "id": "cmp_ABC123",
  "name": "Empresa Demo",
  "legal_name": "Empresa Demo S.L.",
  "tax_id": "B10000008",
  "country": "ES",
  "currency": "EUR",
  "contact_name": null,
  "contact_email": "facturacion@empresa-demo.es",
  "contact_phone": null,
  "address": { "line": "Calle Mayor 1", "post_code": "28001", "town": "Madrid", "province_code": "ES-M", "province_id": 28 },
  "is_active": true,
  "person_type_code": "J",
  "default_tax_group": "IVA",
  "plan": "business",
  "features": ["sii", "products"],
  "fiscal_systems": { "ticketbai_active": false, "verifactu_in_plan": true, "sii_in_plan": true }
}

`GET /api/v1.1/companies`

Lista las empresas accesibles con la clave. Como cada clave opera sobre una sola empresa, la lista tiene un elemento, con los mismos campos que GET /api/v1.1/company. No exige scope.

curl https://app.faxtal.com/api/v1.1/companies \
  -H "X-API-Key: fctXXXXXXXX_YYYYYYYYYYYYYYYY"

[
  { "id": "cmp_ABC123", "name": "Empresa Demo", "tax_id": "B10000008", "is_active": true }
]

Errores

HTTP	`code`	Causa
`401`	`unauthorized`	Falta la clave o no es válida, está revocada o ha caducado
`402`	`feature_outside_plan`	El plan de la empresa no incluye acceso a la API
`403`	`ip_forbidden`	La IP no está en la lista permitida de la clave
`429`	`rate_limited`	Se ha superado el límite de peticiones de la clave

Patrón recomendado

Una clave por empresa y por integración. Si dos procesos distintos (por ejemplo, la emisión y el registro de cobros) trabajan con la misma empresa, dale a cada uno su clave. Así puedes revocar uno sin parar el otro y el registro de uso distingue quién hizo qué.

Guarda la relación empresa ↔ clave en tu sistema. Asocia cada clave al NIF de la empresa y comprueba al arrancar que coinciden:

# claves.txt: una línea por empresa, "NIF clave"
while read nif key; do
  actual=$(curl -s https://app.faxtal.com/api/v1.1/company -H "X-API-Key: $key" | jq -r '.tax_id')
  [ "$actual" = "$nif" ] || echo "La clave de $nif apunta a $actual"
done < claves.txt

Da a cada clave lo mínimo. Limita sus scopes a lo que usa la integración (ver Autenticación), fija una caducidad y, si llamas desde IPs fijas, una lista de IPs permitidas.

Rota y revoca por empresa. Cada clave se rota o se revoca desde su empresa sin afectar a las demás.

Reparte la carga. El límite de peticiones se aplica por clave. Una empresa con mucho volumen no consume el margen de las otras.

El alta de empresas y su suscripción se gestionan en la aplicación, no desde la API.

Asistentes de IA

En el servidor MCP, una API key también autoriza una sola empresa. Una autorización OAuth puede cubrir varias empresas elegidas por el usuario; las tools eligen entre ellas con company_id.