MASKAY API v1

Base: https://api.maskay.online · Solo HTTPS · Respuestas JSON UTF-8

Autenticación

Envía tu llave en el header Authorization: Bearer <llave> (o X-API-Key). Las llaves *_live_* solo funcionan desde las IPs registradas para la llave. Las llaves *_test_* (sandbox) funcionan desde cualquier IP, no cobran y responden datos ficticios para los documentos 00000001, 00000002, 00000003, 00000004, 00000005.

No pongas la llave en una app móvil ni en el navegador: llama a la API desde tu servidor.

Consultar una persona

curl -H "Authorization: Bearer mk_live_..." \
  "https://api.maskay.online/v1/persona/12345678?modulos=persona,telefonos"

modulos es opcional: por defecto devuelve todos los módulos habilitados para tu llave. Pedir menos módulos no cambia el precio, pero responde más rápido.

Headers opcionales: X-Sub-Cliente (para separar consumo por cliente final), X-Finalidad y X-Consentimiento-Id (obligatorios si tu llave tiene perfil con consentimiento, p. ej. educativo).

{
  "request_id": "01JC...",
  "ok": true,
  "entorno": "live",
  "documento": "12345678",
  "cobrado": 0.2,
  "repetido_24h": false,
  "saldo": 39.8,
  "data": { "persona": {...}, "telefonos": [...] }
}

Cobro

Se cobra solo si hay datos. Un documento sin datos responde 404 sin_datos y no se cobra.
Repetir el mismo documento dentro de 24 horas no se vuelve a cobrar (repetido_24h: true).
El saldo es del cliente y lo consultas en GET /v1/saldo; el consumo por día en GET /v1/consumo?desde=YYYY-MM-DD&hasta=YYYY-MM-DD.

Módulos

Módulo	Contenido
`persona`	Identidad (RENIEC): nombres, nacimiento, edad, sexo, estado civil, ubigeo, dirección, nombres de padres
`telefonos`	Teléfonos con operador, periodos y fecha de activación
`direcciones`	Direcciones históricas (RENIEC, operadores, SUNAT)
`correos`	Correos electrónicos
`padres`	Padres identificados (DNI, nombres) con sus teléfonos
`familia`	Hermanos, hijos y cónyuge
`sueldos`	Sueldos por periodo (empleador, RUC, situación)
`creditos`	Reporte RCC/SBS: calificación, entidades y deuda
`sunat`	RUC y estado SUNAT
`vehiculos`	Vehículos registrados
`inmuebles`	Partidas SUNARP
`foto`	Link temporal a la foto (10 min)
`nse`	Nivel socioeconómico estimado (A–E)

Perfiles:

Completo: persona, telefonos, direcciones, correos, padres, familia, sueldos, creditos, sunat, vehiculos, inmuebles, foto, nse
Educativo (menores: sin teléfonos del menor, sin sueldos, créditos ni foto): persona, direcciones, padres, nse · exige consentimiento
Contacto (identidad, teléfonos, correos, direcciones): persona, telefonos, correos, direcciones

Errores

HTTP	code	Significado
401	llave_invalida	Llave inválida, revocada o faltante
402	saldo_insuficiente	Recarga el saldo
403	ip_no_autorizada · modulo_no_permitido · api_deshabilitada	Permisos de la llave
404	sin_datos	Sin datos para el documento (no se cobra)
422	documento_invalido · consentimiento_requerido	Revisa el request
429	limite_por_minuto · tope_diario_* · patron_inusual	Límites de uso

Cada respuesta incluye request_id (también en el header X-Request-Id); úsalo al reportar problemas.