Diccionario · Versión 1.0

Diccionario de datos del API

Campos de entrada y salida del API de MéTRIK Valida, tipos, formato esperado, valores aceptados y ejemplos. Documento para tu equipo de integración técnica.

Última actualización: 15 de mayo de 2026Audiencia: equipo técnico, área de integraciónSpec OpenAPI interactivo →

Descargar PDF

1. Introducción

MéTRIK Valida expone un API REST sobre HTTPS para consulta SARLAFT contra listas vinculantes y de referencia. Este documento describe cada endpoint, los campos esperados en cada request, los campos retornados en cada response, los valores aceptados por cada enum y los códigos de error.

Base URL: https://api.valida.metrik.com.co
Versión vigente: v1
Formato: JSON sobre HTTPS
Codificación: UTF-8
Zona horaria de timestamps: UTC ISO 8601 (2026-05-15T14:32:00Z)

Para spec interactivo con ejecución desde el navegador, ver /docs. Para esquema crudo OpenAPI 3.1.0, ver /api/openapi.json.

2. Autenticación

Bearer api_key

Todas las rutas /v1/ requieren Authorization: Bearer <api_key>. Las api_keys se emiten por cliente (workspace ONE o externo) con hash SHA-256 en base de datos. Si pierdes la clave en texto plano, se rota — no se puede recuperar.

Header requerido en cada request:

Authorization: Bearer valida_<64chars>
Content-Type: application/json

Las operaciones /admin/ usan un token distinto (VALIDA_ADMIN_TOKEN) reservado para operaciones internas de MéTRIK.

3. Endpoints

Resumen de endpoints públicos del API.

Método	Path	Descripción	Auth
POST	/api/v1/validate	Consulta puntual contra todas las listas activas
POST	/api/v1/reporte-lote	Genera PDF agregado de un cargue masivo
GET	/api/v1/reporte/{consulta_id}	Descarga PDF del reporte auditable
GET	/api/v1/consultas	Lista las consultas históricas del cliente
GET	/api/v1/health	Estado del servicio (público)	público

4. Schemas — Request

ValidateRequest · POST /api/v1/validate

Campo	Tipo	Req.	Descripción	Valores
tipo	enum	Sí	Tipo de sujeto a validar.	natural · juridica
nombre	string	Sí	Nombre completo (natural) o razón social (jurídica). Mínimo 2 caracteres.	—
documento.tipo	enum	—	Tipo de documento. Si se incluye y hay match por documento, severidad escala automáticamente.	CC · CE · NIT · PAS
documento.numero	string	—	Número de documento (sin guiones ni espacios). Mínimo 3 caracteres.	—
fecha_nacimiento	date	—	YYYY-MM-DD. Opcional para personas naturales.	1985-03-15
pais	string	—	Código país ISO 3166-1 alpha-2 (2 letras).	CO · US · MX · ES …

{
  "tipo": "natural",
  "nombre": "Juan Pérez Gómez",
  "documento": { "tipo": "CC", "numero": "1077089147" },
  "fecha_nacimiento": "1985-03-15",
  "pais": "CO"
}

ReporteLoteRequest · POST /api/v1/reporte-lote

Campo	Tipo	Req.	Descripción	Valores
consulta_ids	array<uuid>	Sí	UUID de las consultas previamente ejecutadas. Máximo 500 por lote.	—
titulo	string	—	Título del cargue (queda en el header del PDF). Máximo 200 caracteres.	"Cargue CDA mayo 2026"

{
  "consulta_ids": [
    "4f8e2a91-…",
    "7b2c1d83-…"
  ],
  "titulo": "Cargue CDA mayo 2026"
}

5. Schemas — Response

ValidateResponse · 200 OK

Campo	Tipo	Req.	Descripción	Valores
consulta_id	uuid	Sí	Identificador interno de la consulta. Persiste 5 años (Ley 1581/2012).	—
severidad	enum	Sí	Severidad global derivada de los matches.	alto · medio · bajo · informativo · sin_hallazgo
total_matches	integer	Sí	Cantidad de coincidencias encontradas.	0+
matches	array<MatchItem>	Sí	Detalle de coincidencias. Ver schema MatchItem.	—
hash_reporte	string	Sí	SHA-256 hex del reporte. Usable para verificación independiente.	64 chars hex
fecha_reporte	datetime	Sí	Timestamp de la consulta en UTC.	2026-05-15T14:32:00Z
cliente	string	Sí	Nombre del cliente emisor (workspace o externo).	—

{
  "consulta_id": "4f8e2a91-…",
  "severidad": "sin_hallazgo",
  "total_matches": 0,
  "matches": [],
  "hash_reporte": "a3f8d92e4b1c…",
  "fecha_reporte": "2026-05-15T14:32:00Z",
  "cliente": "AFI International Group"
}

MatchItem · elemento del array matches

Campo	Tipo	Req.	Descripción	Valores
lista	string	Sí	Slug único de la lista. Estable a lo largo del tiempo.	onu_consolidated · csn_colombia · pep_colombia · ofac_sdn · eu_consolidated …
lista_nombre	string	Sí	Nombre legible de la lista.	—
tier	enum	Sí	Tier normativo. Determina la consecuencia legal.	1_vinculante · 2_obligatoria · 3_referencia · 4_kyc_nacional
vinculante_colombia	boolean	Sí	True si la consulta es legalmente exigible en Colombia.	true · false
nombre_coincidencia	string	Sí	Nombre o alias de la entrada en lista que generó el match.	—
score	number	Sí	Score combinado Jaro-Winkler 70% + Levenshtein 30%. 0.0 a 1.0.	0.0 ≤ x ≤ 1.0
resultado	enum	Sí	Tipo de coincidencia.	exacto (≥ 0.95) · posible (0.70 - 0.95)
fundamento_legal	string	—	Referencia o programa que justifica la inclusión del nombre en la lista.	"UN Resolution 1267" · "OFAC SDN narco" · null

ConsultaResumen · elemento de GET /api/v1/consultas

Campo	Tipo	Req.	Descripción	Valores
consulta_id	uuid	Sí	Identificador de la consulta.	—
nombre_consultado	string	Sí	Nombre original consultado.	—
documento_consultado	string	—	Documento concatenado (tipo+número).	"CC 1077089147" · null
severidad	enum	Sí	Severidad global de la consulta.	alto · medio · bajo · informativo · sin_hallazgo
total_matches	integer	Sí	Total de coincidencias.	0+
creada_en	datetime	Sí	Timestamp UTC.	—

6. Enums y valores aceptados

Severidad global

alto	Coincidencia exacta en lista vinculante (Tier 1). Bloqueo + ROS UIAF.
medio	Coincidencia exacta en lista obligatoria (Tier 2: PEP) o no vinculante (Tier 3: OFAC/UE).
bajo	Coincidencia posible (puntaje 0.70 - 0.95). Sin coincidencia exacta.
informativo	Coincidencia solo en referencia internacional sin vinculancia local.
sin_hallazgo	Sin coincidencias.

Tier (clasificación normativa de la lista)

1_vinculante	Listas vinculantes legalmente en Colombia (ONU, CSN Colombia).
2_obligatoria	Listas obligatorias sin fuente única (PEP Colombia via SIGEP).
3_referencia	Listas no vinculantes — estándar de facto (OFAC, EU, INTERPOL).
4_kyc_nacional	Capa de debida diligencia colombiana (módulo v2).

Tipo de documento

CC	Cédula de Ciudadanía (personas naturales colombianas).
CE	Cédula de Extranjería.
NIT	Número de Identificación Tributaria (personas jurídicas).
PAS	Pasaporte.

Resultado del match

exacto	Puntaje ≥ 0.95. Coincidencia con muy alta probabilidad.
posible	Puntaje 0.70 - 0.95. Requiere análisis manual del oficial de cumplimiento.

7. Códigos de error

El API devuelve códigos HTTP estándar más un cuerpo JSON con la estructura { "error": "<codigo>", "message": "<descripcion>" }.

HTTP	error	Descripción y cómo corregir
400	validation_error	Payload inválido. Revisa el campo issues del cuerpo de respuesta para detalle por campo.
401	invalid_api_key	API key faltante, mal formada o revocada. Verifica el header Authorization. Si se rotó, solicita una nueva.
403	permiso_denegado	API key válida pero sin permisos para la operación. Reservado para operaciones admin.
404	not_found	Recurso no encontrado o no pertenece al cliente autenticado.
429	rate_limit	Excediste el límite de consultas del plan. Reintenta tras el período indicado en el header Retry-After.
500	db_error	Error de persistencia. Reintentar luego. Si persiste, contactar a soporte.
503	upstream_unavailable	Servicio downstream (Supabase, fuente de lista) temporalmente caído.