# Identificadores

En v5, cada entidad y cada activo se direcciona con un identificador único, opaco y tipado. Un solo id apunta de forma inequívoca a una persona, una organización o un activo (finca, nave, marca, documento…), sin que usted necesite saber en qué jurisdicción ni en qué tabla vive.

Aplica a la superficie **v5** (aditiva). La API v4 conserva sus identificadores enteros por jurisdicción y no cambia.

## Formato

Tres partes separadas por guion bajo: jurisdicción, tipo y clave local.

`{jur}_{tipo}_{pk}`
`pa_own_42``co_own_7``pa_finca_153``pa_ph_9``pa_entrada_88`

Trate el identificador como una **cadena opaca** : pásela tal cual entre llamadas y guárdela como referencia, pero **no la analice ni la construya** en su código. El formato interno puede evolucionar; lo único garantizado es que un id que la API le devuelve se lo puede volver a enviar.

## Jurisdicción

El prefijo identifica el país. El identificador lleva la jurisdicción dentro de sí.

| Prefijo | País | Estado |
| --- | --- | --- |
| pa | Panamá | Activo |
| co | Colombia | Reservado (cableado próximamente) |
| ec | Ecuador | Reservado (cableado próximamente) |

## Tipos

El código de tipo indica a qué clase de registro apunta el identificador. La lista es append-only: un código nunca se reutiliza para otra cosa.

| Código | Apunta a | Categoría |
| --- | --- | --- |
| own | Entidad — persona natural u organización | Entidad |
| finca | Finca / propiedad raíz | Activo |
| ph | Propiedad horizontal (apartamento o local) | Activo |
| edif | Edificio (contexto de la propiedad horizontal) | Activo |
| nave | Nave / embarcación | Activo |
| bm | Bien mueble | Activo |
| marca | Marca / registro marcario | Activo |
| imp | Importación | Activo |
| exp | Exportación | Activo |
| entrada | Entrada — documento escaneado del Registro | Documento |
| elemento | Elemento — documento digital | Documento |

## Reglas

- **El id lleva la jurisdicción.** En las llamadas por id ya no necesita `?country=`; el prefijo basta. `country` sobrevive solo como _filtro_ en la búsqueda. 
- **Validación estricta.** Un identificador mal formado, con prefijo o tipo desconocido, o con clave no numérica devuelve `400` — nunca se resuelve silenciosamente al registro equivocado. 
- **Append-only.** Los códigos de tipo se agregan, nunca se reasignan. Un id que funciona hoy seguirá apuntando al mismo tipo de registro mañana. 
- **Sin `panadata_id` en v5.** El identificador tipado es el único id público; el antiguo campo duplicado se elimina de las respuestas v5. 

## Direccionar vs. resolver

Un identificador apunta a un registro concreto. No es (todavía) una identidad única de la entidad real entre jurisdicciones.

Si ya tiene el id, úselo directamente para leer el detalle. Si parte de un nombre o un RUC y quiere encontrar la entidad —incluso sin saber el país— use `POST /v5/resolve`, que devuelve **candidatos ordenados con su nivel de confianza** , no una única respuesta. La vinculación de la misma entidad entre jurisdicciones es probabilística y se expone como sugerencia; nunca se fusionan dos identidades en silencio.

## Una sola llave para REST y MCP

La misma API key opera la API REST y el servidor MCP sobre el mismo espacio de identificadores: un id obtenido vía REST sirve tal cual como argumento de una herramienta del MCP, y viceversa. El consumo de ambos se descuenta del mismo saldo prepago.