El producto exige el service flag
risk y cobra el servicio fijo
risk_fraud_score. Si falla la generación, el cargo se reembolsa
automáticamente. El PDF y las señales detalladas nunca viajan por email.Flujo
Cobertura del buró y THIN_FILE
El informe puede quedar ready con THIN_FILE cuando no tiene evidencia
utilizable del buró para esa evaluación. Esto puede ocurrir después de un
fetch exitoso que devuelve cero registros, incluido un HTTP 200 con
sources_queried: 0. Esto significa que no hubo una fuente personal
consultable: la respuesta solo contenía fuentes bulk o no compatibles. Se
trata como unavailable y puede producir THIN_FILE. Lo mismo ocurre cuando
el core responde explícitamente 503 bureau_unavailable porque no hay una
fuente personal de buró configurada. En ese caso, el PDF declara la fuente
personal como unavailable con cero registros; las señales de la plataforma
todavía pueden contribuir al score de fraude.
Cuando sources_queried > 0, la fuente personal respondió la consulta pero no
devolvió evidencia para el sujeto; sigue siendo un fetch válido y también puede
producir THIN_FILE.
THIN_FILE describe cobertura de evidencia; no significa limpio, aprobado ni
bajo riesgo. La tabla sources del PDF declara cada fuente funcional, su
cantidad de registros y freshness (live o unavailable). Los registros
persistidos del buró nunca se presentan como evidencia de identidad fresca
cuando el fetch on-demand no estuvo disponible.
Excepción para registros anteriores: los registros Source: open_finance derivados de consent
links pueden no traer ingest_run_id. No cuentan como evidencia personal fresca
del buró, no deben marcar FetchedThisRun y no representan una fuente personal
de fraude.
Las fallas son fail-closed: un sources_failed no vacío, una falla de
transporte o autenticación, una falla de storage o un contrato inválido no
producen un éxito de archivo delgado. El recovery/reembolso existente resuelve
el informe cobrado.
Crear un informe
POST /v1/qscore/fraud/reports es autenticado y exige una cuenta verificada.
La clave puede ir en el body o en el header Idempotency-Key.
Crear informe de fraude
200 OK
"idempotency_hit": true; no cobra ni genera otro informe.
Consultar y descargar
GET /v1/qscore/fraud/reports exige from y to (YYYY-MM-DD, timezone de
la organización, inclusivos), acepta status y pagina con page/
page_size (default 50, máximo 200). GET .../{report_id} devuelve sus
metadatos, razones y links. Un ID inválido o fuera de ownership responde
404 not_found.
GET /v1/qscore/fraud/reports/{report_id}/pdf descarga el PDF autenticado
como qxrisk_fraud_<report_id>.pdf. Solo existe cuando el estado es ready.
Listar informes listos
200 OK
Score, bandas y estados
El modelo esqscore-fraud-v1, de 1 a 999. A diferencia del crédito, aquí
un score alto es peor.
Los reason codes implementados son
NEW_SUBJECT, VELOCITY,
CONTACT_MISMATCH, SHARED_DEVICE_IP y THIN_FILE.
Webhook, email y verificación pública
El webhook firmadorisk_fraud_score_ready llega a la cuenta:
risk_fraud_score_ready
GET /verify/qscore-fraud/{code} no requiere auth. Un código válido devuelve:
200 OK
404 con valid:false y nunca revela PII,
score ni señales. El endpoint está limitado por IP.
Errores
FAQ
¿Es un score de crédito?
¿Es un score de crédito?
No. Es un score separado de fraude e identidad: un valor alto significa
mayor riesgo observado.
¿Existe un endpoint score-only?
¿Existe un endpoint score-only?
No. El producto siempre crea el informe completo, PDF y código verificable.
¿Un retry cobra dos veces?
¿Un retry cobra dos veces?
No si reutilizas la misma clave de idempotencia.