Diccionario · Versión 1.5

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: 5 de octubre 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 restrictivas nacionales e internacionales. 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.metrikone.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)

Este diccionario describe campos y valores. Cómo integrarse (quickstart, idempotencia, consumo, cobro, webhooks, concurrencia, ejemplos en curl, JavaScript y Python) está en la Guía del integrador. Referencia interactiva en /docs/referencia. 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 son por cliente (workspace ONE o externo), con formato vk_ + 64 caracteres hexadecimales, y en base de datos solo queda su hash SHA-256. El cliente las genera, regenera y revoca en el portal de clientes (/portal). Si pierdes la clave en texto plano no se puede recuperar: se regenera, y la anterior sigue válida 24 horas.

Header requerido en cada request:

Authorization: Bearer <api_key>
Content-Type: application/json
Idempotency-Key: <uuid>          # recomendado en POST /validate

Las operaciones /admin/ usan un token distinto reservado para operaciones internas de MéTRIK. Toda respuesta trae el header X-Valida-Request-Id; cítelo en soporte.

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 (filtros: desde, severidad, referencia_externa, sujeto_obligado_nit)
GET	/api/v1/cuenta/consumo	Contador del paquete mensual (periodo vigente y estado de cobro) o de la bolsa prepagada (saldo, sin periodo)
GET	/api/v1/cuenta/consumo/historial	Periodos anteriores, o bolsas anteriores si la modalidad es bolsa
GET	/api/v1/cuenta/alertas	Configuración de alertas y eventos del periodo
PUT	/api/v1/cuenta/alertas	Configurar umbrales, emails y webhook
POST	/api/v1/cuenta/alertas/webhook/rotar-secreto	Rotar el secreto del webhook
POST	/api/v1/cuenta/alertas/prueba	Enviar un evento de prueba a los canales
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	—	Nombre completo (natural) o razón social (jurídica). Mínimo 2 caracteres. Se exige al menos uno entre nombre y documento; con uno solo la respuesta marca consulta_parcial.	—
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 …
referencia_externa	string	—	Su identificador (expediente, fila del lote). Se devuelve tal cual y se filtra en GET /consultas. Máximo 128 caracteres.	"EXP-2026-00123"
sujeto_obligado.razon_social	string	—	Razón social del sujeto obligado final. OBLIGATORIO si el cliente API opera para terceros (agregador); el PDF se emite a su nombre.	3 a 200 caracteres
sujeto_obligado.nit	string	—	NIT del sujeto obligado final. Se aceptan puntos y guion del dígito de verificación; se guarda normalizado a dígitos.	"800.123.456-7" → 8001234567
Idempotency-Key (header)	string	—	Clave única por consulta (1-64 chars). Misma clave + mismo cuerpo en 24 h devuelve la misma respuesta sin cobrar; cuerpo distinto → 409.	UUID v4

{
  "tipo": "natural",
  "nombre": "Juan Pérez Gómez",
  "documento": { "tipo": "CC", "numero": "1077089147" },
  "fecha_nacimiento": "1985-03-15",
  "pais": "CO",
  "referencia_externa": "EXP-2026-00123",
  "sujeto_obligado": { "razon_social": "Transportes La Sabana SAS", "nit": "800.123.456-7" }
}

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 10 años.	—
severidad	enum	Sí	Severidad global derivada de los matches.	alto · medio · bajo · informativo · sin_hallazgo
total_matches	integer	Sí	Cantidad de coincidencias encontradas.	0+
consulta_parcial	boolean	Sí	true si la consulta trajo solo nombre o solo documento.	true · false
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
sujeto_obligado	object \| null	Sí	El sujeto obligado enviado, normalizado.	{ razon_social, nit } · null
referencia_externa	string \| null	Sí	La referencia enviada.	—
listas_consultadas	array<ListaConsultada>	Sí	Versión de cada lista contra la que corrió la consulta: slug, nombre, tier, version_id, hash_contenido, fetched_en, total_entradas y fuente_publicada_en (cuándo la fuente declara haber publicado; null si no lo declara). Queda grabada; el PDF la lee de ahí.	—
fecha_reporte	datetime	Sí	Timestamp de la consulta en UTC.	2026-09-08T14:32:00Z
cliente	string	Sí	Nombre del cliente API autenticado.	—

{
  "consulta_id": "4f8e2a91-…",
  "severidad": "sin_hallazgo",
  "total_matches": 0,
  "consulta_parcial": false,
  "matches": [],
  "hash_reporte": "a3f8d92e4b1c…",
  "sujeto_obligado": { "razon_social": "Transportes La Sabana SAS", "nit": "8001234567" },
  "referencia_externa": "EXP-2026-00123",
  "listas_consultadas": [ { "slug": "onu_consolidated", "tier": "1_vinculante", "fetched_en": "2026-09-05T05:15:12Z", "total_entradas": 1002, "version_id": "…", "hash_contenido": "…", "nombre": "…" } ],
  "fecha_reporte": "2026-09-08T14:32:00Z",
  "cliente": "Plataforma Ejemplo"
}

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í	Propiedad de la lista en el catálogo: true para ONU, CSN Colombia y PEP. En OFAC, UE y FTO vale false porque su carácter vinculante no lo fija el catálogo: depende del supervisor del sujeto obligado. Para esas listas, lea vinculancia.	true · false
vinculancia	object \| null	Sí	Rótulo de una coincidencia con OFAC, UE o FTO. Muestre rotulo y efecto junto al resultado. null en ONU, CSN y PEP.	{ rotulo, codigo (T2 · T3), categoria (k1 terrorismo · k2 resto), efecto, version }
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" · "SDNTK" · null
match_por	enum	Sí	Por qué campo coincidió.	nombre · documento
documento_coincidencia	object \| null	—	Documento que trae la ENTRADA de la lista (dato de la coincidencia, no identidad confirmada).	{ tipo, numero, pais }
derivado	boolean	Sí	true si salió del segundo pase (revalidación con el dato complementario hallado).	true · false
derivado_de	object \| null	—	De qué dato y lista se derivó.	{ tipo, valor, lista_nombre }

BolsaConsumo · campo bolsa de GET /api/v1/cuenta/consumo (modalidad bolsa)

Campo	Tipo	Req.	Descripción	Valores
modalidad	enum	Sí	Modalidad del contrato de consumo (campo de la raíz de la respuesta). Con bolsa, plan y periodo vienen en null.	mensual · bolsa
bolsa.estado	enum	Sí	vigente se puede consultar; agotada y vencida están cortadas: POST /validate responde 402.	vigente · agotada · vencida
bolsa.bloqueada	boolean	Sí	true si la bolsa está agotada o vencida.	true · false
bolsa.activada_en	datetime	Sí	Momento en que se activó la bolsa vigente.	2026-09-14T20:38:51Z
bolsa.vence_en	datetime	Sí	Vencimiento: 6 meses desde la entrega de credenciales.	2027-03-14T20:38:51Z
bolsa.dias_para_vencer	integer	Sí	Días que faltan para el vencimiento, redondeado hacia arriba; 0 si ya venció.	0+
bolsa.consultas_compradas	integer	Sí	Consultas compradas en esta bolsa.	20000
bolsa.consumidas	integer	Sí	Consultas cobrables desde activada_en. Nunca supera las compradas.	0+
bolsa.saldo	integer	Sí	consultas_compradas − consumidas. Nunca negativo: no hay excedente.	0+
bolsa.precio_total	number	Sí	Precio pagado por la bolsa, COP sin IVA.	1400000
bolsa.precio_unitario	number	Sí	precio_total / consultas_compradas.	70
bolsa.pago_referencia	string	Sí	Referencia del pago que abrió la bolsa.	"CC-0042"

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+
referencia_externa	string	—	Referencia enviada en /validate.	—
sujeto_obligado_razon_social	string	—	Sujeto obligado final.	—
sujeto_obligado_nit	string	—	NIT normalizado.	—
creada_en	datetime	Sí	Timestamp UTC.	—

6. Enums y valores aceptados

Severidad global

alto	Exacto en lista vinculante (Tier 1), o exacto con una designación de terrorismo de EE. UU. o de la UE (rótulo VERIFIQUE CON SU SUPERVISOR).
medio	Exacto en lista obligatoria (Tier 2: PEP) o en el resto del Tier 3 (rótulo LISTA RESTRICTIVA).
bajo	Coincidencia posible (puntaje 0.70 - 0.95). Sin coincidencia exacta.
informativo	Reservado: el motor SARLAFT no emite hoy esta severidad.
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 internacionales (OFAC, UE, FTO) cuyo carácter vinculante depende del supervisor del sujeto obligado. El nombre del valor se conserva por compatibilidad. El detalle lo declara el documento «Explicación de listas de consulta».

Modalidad de consumo

mensual	Paquete de consultas por mes calendario (America/Bogotá). El contador vuelve a cero el día 1.
bolsa	Bolsa prepagada con vencimiento (6 meses desde la entrega de credenciales). Se corta con lo primero: se agota o vence. Sin excedente, sin arrastre y sin bloqueo por mora.

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

Toda respuesta de error tiene la misma forma: { "error": "<codigo>", "message": "<descripcion>", "doc_url": "<ancla>", "request_id": "req_…", "issues"?: [...] }. Programe contra error; message puede cambiar. No existen 429, 403 ni 503.

HTTP	error	Descripción y cómo corregir
400	invalid_json	El cuerpo no es JSON válido.
400	validation_error	Payload inválido. Revisa el campo issues (path + message) para detalle por campo.
400	sujeto_obligado_requerido	El cliente opera para terceros y falta sujeto_obligado { razon_social, nit }.
400	idempotency_key_invalida	Idempotency-Key vacía, con espacios o de más de 64 caracteres.
401	invalid_api_key	API key faltante, mal formada, revocada, vencida (regenerada hace más de 24 horas) o de cliente inactivo. Verifica el header Authorization.
402	paquete_vencido_sin_pago	Solo paquete mensual. Cuenta de cobro vencida sin pago registrado Y consumo por encima del 100% del paquete. Nunca se bloquea solo por consumo. Registre el pago con soporte; no reintente en bucle.
402	bolsa_agotada	Bolsa prepagada: se usaron todas las consultas compradas. La consulta rechazada no se registró ni se cobró. Compre una bolsa nueva con soporte.
402	bolsa_vencida	Bolsa prepagada: llegó a su vencimiento, aunque quede saldo. Compre una bolsa nueva con soporte.
404	not_found	Recurso no encontrado o no pertenece al cliente autenticado.
409	idempotency_error	La Idempotency-Key ya se usó con un cuerpo distinto. Use una clave nueva.
409	sin_plan_asignado	GET /cuenta/consumo de un cliente sin paquete mensual ni bolsa prepagada. /validate funciona igual.
500	persistencia_error	La consulta corrió pero no se guardó; no se cobró. Reintente con la misma Idempotency-Key.
500	db_error	Error interno de lectura/escritura. Reintentar con espera exponencial; si persiste, soporte con el request_id.

Tabla completa con "cuándo" y "qué hacer" por código en la Guía del integrador.