> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.useopenwrench.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Datos de referencia del comprador y enmascaramiento

> Lee los datos de referencia del comprador visibles para proveedores: empresas relacionadas, ubicaciones, activos y tipos, y el enmascaramiento.

Las órdenes de trabajo referencian un mundo propiedad de tus compradores: sus empresas, ubicaciones, regiones y activos. La Supplier API expone vistas de solo lectura de todos ellos, filtradas por lo que tus relaciones te permiten ver.

Todos los ejemplos asumen:

```bash theme={null}
export BASE="https://api.useopenwrench.com/api/external"
export KEY="<your-api-key>"
export SECRET="<shared-secret>"
```

## Enmascaramiento de datos

Cuánto ves depende del tipo de proveedor al que pertenezca tu clave:

* **Claves de equipo interno de servicio** (tu empresa proveedora es el equipo interno del comprador) reciben registros completos.
* **Claves de proveedor tercero** reciben registros enmascarados en órdenes de trabajo, ubicaciones y facturas: los campos privados del comprador se ponen en blanco antes de devolver la respuesta.

Si un campo que esperas aparece consistentemente vacío, el enmascaramiento es lo primero a revisar. El alcance en sí no puede ampliarse con filtros; los filtros de seguridad de inquilino derivados de tu clave siempre aplican.

## Empresas compradoras

`GET /v1/supplier/buyer_company/buyer_companies` devuelve cada empresa compradora que tiene una relación con tu proveedor. No se respetan paginación ni filtros: el conjunto completo limitado al inquilino llega en una sola respuesta (`buyerCompanySettings` de cada empresa se elimina).

```bash theme={null}
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/buyer_company/buyer_companies"
```

Úsalo para personalizar el comportamiento por comprador en tu integración (qué tipos de problema usar, qué compradores auto-aprueban las completaciones de terceros, etc.).

## Ubicaciones y regiones

```bash theme={null}
# Listar: el tamaño de página se limita a 10 en este endpoint (los limits mayores se reducen silenciosamente)
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/location/locations?limit=10"

# Contar, una, o varias a la vez
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/location/locations/count_by"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/location/locations/1204"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/location/locations/multiple/1204,1205"
```

* El listado de ubicaciones limita `limit` a **10**; la mayoría de listados permite 25.
* `multiple/{ids}` descarta silenciosamente los ids que no puedas leer; el `count` de la respuesta equivale a lo que realmente se devolvió.
* Las regiones (agrupaciones de ubicaciones por empresa compradora) están en `GET /v1/supplier/location/regions` y `/regions/{id}` con paginación estándar.

## Activos y tipos de activos

Los activos son los equipos que tus técnicos atienden; los tipos de activos los clasifican.

```bash theme={null}
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/asset/assets?locationId=1204&limit=25"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/asset/assets/5511"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/asset/asset_types?limit=25"
```

La lectura de un solo activo hidrata los medidores del activo (envoltura tipo `ApiAssetWithMeter`), lo que da a tus técnicos el contexto de historial del medidor antes de una visita. Los cuatro endpoints (`assets`, `assets/{id}`, `asset_types`, `asset_types/{id}`) son de solo lectura con paginación estándar y filtros por campo.

## Etiquetas de activos

Las etiquetas de activos son marcadores definidos por el comprador sobre los activos (un nombre más un color opcional). Siempre pertenecen a una empresa compradora, así que el acceso a través de la Supplier API está limitado a las claves del equipo interno de servicio de un comprador: esas claves ven el catálogo de su empresa compradora, mientras que la clave de un proveedor tercero obtiene una lista vacía.

```bash theme={null}
# El catálogo (solo claves de equipo interno de servicio)
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/asset/asset_labels?no_pagination=true"

# Reemplazar las etiquetas de un activo
curl -X PUT "$BASE/v1/supplier/asset/assets/5511/labels" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [7, 21] }'
```

El catálogo es de solo lectura (`GET /v1/supplier/asset/asset_labels` y `/{id}`); las etiquetas se crean y editan en la app de OpenWrench. El listado está paginado a 10 por página por defecto, acepta filtros `search` y `label` sobre el texto de la etiqueta, y `no_pagination=true` devuelve el catálogo completo.

`PUT /v1/supplier/asset/assets/{assetId}/labels` reemplaza el conjunto completo de etiquetas del activo (`{ "ids": [...] }`; un array vacío las borra todas) y devuelve las etiquetas ahora activas. La escritura requiere permiso de escritura de activos, y cada id debe ser una etiqueta viva del catálogo de tu empresa compradora. La clave de un proveedor tercero recibe `400` incluso cuando posee permiso de escritura de activos. Un id de activo desconocido, eliminado o ajeno responde el mismo `400` que una escritura denegada, no un `404`.

## Estrategia de cacheo

Los datos de referencia cambian despacio. Una configuración práctica:

* Refresca las empresas compradoras a diario (una llamada).
* Sincroniza ubicaciones y activos de órdenes de trabajo activas bajo demanda, cacheando por id.
* Trata un `400` en una lectura individual como "fuera de tu alcance" y un `404` como "no existe", y espera que los ids desaparezcan de tu vista cuando termina una relación con un comprador.