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

# Referencias externas

> Mapeá productos, categorías, sucursales y cajas del POS con los ids de tu ERP.

## Qué es

`external_refs` guarda la correspondencia entre una entidad del POS y su id en otro sistema. El ERP usa el sistema `tero-erp`, pero el campo `system` es libre para mapear también un ecommerce o un depósito.

Entidades soportadas: `product`, `category`, `location`, `pos`.

## Dónde está

| Método | Ruta | Alcance |
| - | - | - |
| `GET` | `/api/integration/v1/external-refs` | lectura o escritura |
| `PUT` | `/api/integration/v1/external-refs` | escritura |
| `DELETE` | `/api/integration/v1/external-refs` | escritura |

```bash theme={null}
export TERO_API='https://pos-api.terominds.com/api'
export TERO_API_KEY='tero_live_aabbccdd_xxxxxxxx'
export TERO_TENANT_ID='00000000-0000-0000-0000-000000000001'

# Alta o actualización (upsert por entidad + sistema)
curl -sS -X PUT "$TERO_API/integration/v1/external-refs?tenantId=$TERO_TENANT_ID" \
  -H "Authorization: Bearer $TERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "product",
    "entity_id": "22222222-2222-4222-8222-222222222222",
    "system": "tero-erp",
    "external_id": "SKU-4711"
  }'
```

Respuesta:

```json theme={null}
{
  "ok": true,
  "created": true,
  "external_ref": {
    "id": "uuid",
    "entity_type": "product",
    "entity_id": "22222222-2222-4222-8222-222222222222",
    "system": "tero-erp",
    "external_id": "SKU-4711",
    "created_at": "2026-10-21T19:00:00.000Z",
    "updated_at": "2026-10-21T19:00:00.000Z"
  }
}
```

## Consultar

```bash theme={null}
curl -sS "$TERO_API/integration/v1/external-refs?tenantId=$TERO_TENANT_ID&entity_type=product&entity_id=22222222-2222-4222-8222-222222222222" \
  -H "Authorization: Bearer $TERO_API_KEY"
```

Filtros disponibles: `entity_type`, `entity_id` y `system`.

## Eliminar

```bash theme={null}
curl -sS -X DELETE "$TERO_API/integration/v1/external-refs?tenantId=$TERO_TENANT_ID" \
  -H "Authorization: Bearer $TERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entity_type": "product", "entity_id": "22222222-2222-4222-8222-222222222222", "system": "tero-erp" }'
```

## Reglas

* Un `external_id` no puede apuntar a dos entidades distintas del mismo tipo y sistema. Si intentás reasignarlo, la API responde `409 external_id_taken`.
* Cada entidad tiene **una** referencia por sistema: volver a hacer `PUT` con la misma entidad y sistema actualiza el `external_id`.
* `system` es opcional y por defecto es `tero-erp`.

## Errores

| Código | `error` | Qué significa |
| - | - | - |
| 400 | `invalid_entity_type` | No es `product`, `category`, `location` ni `pos`. |
| 400 | `invalid_entity_id` | Falta `entity_id`. |
| 400 | `invalid_external_id` | Falta `external_id` o es demasiado largo. |
| 409 | `external_id_taken` | El id externo ya está asignado a otra entidad. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.