Uso multi-compañía

Una API key no siempre corresponde a una sola compañía. En los grupos empresariales con varias razones sociales, una misma key puede tener acceso a varias compañías, cada una identificada por su uniqueCode. Esta guía explica qué hace cada endpoint en ese caso y cómo indicar sobre qué compañía quieres operar.

Conocer tus compañías

GET /companies devuelve todas las compañías a las que tiene acceso tu key. Guarda el uniqueCode de cada una: es el valor que vas a usar como companyCode en el resto de la API.

curl -X GET 'https://{HOST}/api/public/v1/companies' \
  -H 'X-API-KEY: tu_api_key_aqui'

Si en tu sistema ya identificas a cada compañía por su identificación fiscal (RFC, CUIT, RUT), búscala directamente por ese valor con taxIdentificationValue. Es la forma más simple de mapear tus compañías a sus uniqueCode:

curl -X GET 'https://{HOST}/api/public/v1/companies?taxIdentificationValue=XAXX010101000' \
  -H 'X-API-KEY: tu_api_key_aqui'

La búsqueda es por coincidencia exacta y solo devuelve compañías a las que tu key tiene acceso. Si varias compañías comparten la identificación fiscal y se diferencian por sucursal, agrega branchCode para quedarte con una. La identificación fiscal de cada compañía viene en legalInformation.taxIdentificationValue y su sucursal en legalInformation.branchCode.

Para traer solo algunas compañías que ya conoces, pasa sus uniqueCode en include (se puede repetir).

Cómo queda asociada una key a sus compañías

Las compañías de una API key se fijan cuando se crea, a partir de las compañías a las que tiene acceso la persona que la genera. Hay dos variantes:

Ningún endpoint indica de qué tipo es tu key: si no lo sabes, consulta con tu contacto de onboarding. Esta guía describe el comportamiento de una key multi-compañía. Si envías siempre companyCode, como recomienda la regla 2, tu integración funciona igual con los dos tipos.

No existe un header ni un parámetro global para elegir la compañía de una llamada. La única forma es el companyCode de los endpoints que lo aceptan, en el query o en el body según el caso.

Lecturas: la vista consolidada

Los listados no se limitan a una compañía: devuelven los elementos de todas las compañías de la key en una sola colección. La paginación y el orden son globales, así que una misma página puede mezclar compañías.

# Todas las transacciones de todas tus compañías
curl -X GET 'https://{HOST}/api/public/v1/purchases?page=0&size=50' \
  -H 'X-API-KEY: tu_api_key_aqui'

# Solo las de una compañía
curl -X GET 'https://{HOST}/api/public/v1/purchases?companyCode=CODIGO_COMPANIA' \
  -H 'X-API-KEY: tu_api_key_aqui'

# Las de dos compañías: repite el parámetro
curl -X GET 'https://{HOST}/api/public/v1/purchases?companyCode=CODIGO_A&companyCode=CODIGO_B' \
  -H 'X-API-KEY: tu_api_key_aqui'

Para ordenar y recorrer las páginas, sigue la guía de Paginación: el orden se envía con la forma indexada sort[0].property=…&sort[0].direction=….

En las respuestas, el companyCode de cada elemento es el uniqueCode de su compañía. Cuando los elementos de transacciones no traen companyCode, como en archivos y documentos de facturación, cruza el purchaseCode con GET /purchases para saber a qué compañía pertenece cada uno.

Endpoints que necesitan una compañía

Algunos catálogos son propios de cada compañía y no se pueden consolidar:

GET /people y la compañía principal de cada persona

Una persona puede pertenecer a varias compañías, pero tiene una compañía principal. El filtro companyCode de GET /people, los filtros por identificación fiscal de la compañía y la búsqueda por {code} usan esa compañía principal. Una persona cuya compañía principal no está entre las de tu key no aparece, aunque también pertenezca a una compañía que sí lo está.

Consultas por {code}

GET, PATCH y DELETE sobre un recurso concreto encuentran el recurso en cualquiera de las compañías de tu key, sin que indiques cuál. Si el recurso es de una compañía a la que la key no tiene acceso, la API responde como si no existiera. Esto evita revelar recursos de otras compañías.

Altas: indica siempre la compañía

Al crear recursos, la API no elige una compañía por ti. Con una key multi-compañía, indica en cuál se crea cada recurso:

curl -X POST 'https://{HOST}/api/public/v1/projects' \
  -H 'X-API-KEY: tu_api_key_aqui' \
  -H 'Content-Type: application/json' \
  -d '{ "companyCode": "CODIGO_COMPANIA", "name": "Expansión regional" }'

En POST /cost-center-account-types, la cuenta contable y el centro de costos que vinculas tienen que pertenecer a la misma compañía que indicas.

Altas con reglas propias

Estos endpoints no deciden la compañía con companyCode:

• POST /people (JSON): con una key multi-compañía, la persona queda asociada a todas las compañías de la key. companyCodes en el body no restringe ese conjunto. No hay forma de elegir su compañía principal.
• POST /people (CSV): la compañía de cada fila sale de la columna NRO_IDENTIFICADOR_FISCAL_EMPRESA (o RFC_EMPRESA), que tiene que coincidir con una de tus compañías. Una fila sin coincidencia se rechaza. Las personas que ya existen conservan sus compañías.
• POST /account-types (CSV): la compañía de cada fila sale de NRO_IDENTIFICADOR_FISCAL_EMPRESA y, si hace falta distinguir sucursales, de CODIGO_IDENTIFICADOR. El parámetro companyCode no decide en qué compañía se crean las cuentas. Con una key multi-compañía, incluye esas columnas en todas las filas: si una fila no identifica su compañía, se rechaza el archivo entero.
• POST /account-types (JSON) y POST /budgets (CSV): no permiten elegir compañía, así que hoy no están disponibles para keys multi-compañía. Usa la carga por CSV de cuentas contables y el alta JSON de presupuestos.

Miembros de presupuestos

POST /budgets/{code}/members no valida que las personas que agregas pertenezcan a la compañía del presupuesto, y los personCode que la key no puede ver se omiten sin error. Con una key multi-compañía, verifica la compañía de cada persona con GET /people/{code} antes de agregarla.

Recorrido recomendado

Este es el flujo que conviene seguir para leer datos de varias compañías sin mezclarlos ni perder ninguno:

Errores y resultados vacíos

Un 400 por falta de compañía señala el campo companyCode en key cuando el parámetro es obligatorio:

{
  "errors": [
    { "category": "must not be blank", "key": "companyCode", "parameters": [] }
  ],
  "status": 400
}

Cuando la compañía es necesaria pero no se puede determinar, el campo viaja en parameters:

{
  "errors": [
    { "category": "AppErrorType", "key": "INVALID_REQUEST", "parameters": ["companyCode"] }
  ]
}

En los dos casos, la solución es la misma: envía companyCode.

Como una página vacía no indica si tienes acceso, valida los companyCode contra GET /companies antes de usarlos en filtros. Así un código mal escrito no pasa por "esa compañía no tiene datos".