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.countrysobrevive 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_iden 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.