Skip to main content
El scoring por lote es la modalidad de alto volumen de Qscore: en vez de pedir un informe crediticio a la vez, envías un lote de sujetos (RUTs chilenos hoy) y CBPay genera un informe Qscore completo para cada uno de forma asíncrona. Cuando el lote termina recibes un webhook y un email con los contadores — nunca una notificación por sujeto. Úsalo para re-puntuar una cartera existente (refresco mensual de tus deudores), para una barrida única de due diligence sobre una lista de proveedores, o para completar scores tras incorporar una cartera nueva. Para consultas puntuales de un solo sujeto, sigue usando el informe individual.

​
Cómo funciona

El lote se acepta de inmediato (202) y lo procesa un worker en segundo plano. Cada ítem pasa por el mismo pipeline del informe individual — incluido el fetch on-demand al buró — así que un score de lote es idéntico al que obtendrías uno por uno, con el mismo modelo determinista (1–999, bandas A–E, SC cuando el sujeto no tiene datos).

​
Paso a paso

1

Crea el lote

Envía POST /v1/qscore/batches con los sujetos como array JSON o como texto CSV (subjects_csv). Toda petición necesita un idempotency_key: un replay con la misma clave devuelve el lote original con idempotency_hit: true y jamás duplica el lote ni sus cobros.Las filas inválidas se rechazan al crear y se reportan en rejected_items — el lote solo procesa las válidas. Un doc_id que no pasa el dígito verificador del país produce invalid_doc_id; el mismo doc_id dos veces dentro del lote produce duplicate_in_batch (reportado con su forma normalizada). Un subject_type no reconocido no es un error: la fila se acepta y el tipo se infiere como se describe abajo.
La estimación de arriba asume una comisión configurada de 4.00 USDT por informe de persona y 2.50 USDT por informe de empresa: 3 × 4.00 + 1 × 2.50 = 14.50. Tu estimación refleja las comisiones configuradas en tu cuenta.
Un replay idempotente devuelve 200 (no 202) con el lote original e idempotency_hit: true; el detalle rejected_items / rejected_count solo se incluye en la respuesta de creación original.
2

Espera la señal de término

El worker procesa los ítems uno a uno. No necesitas hacer polling: cuando el lote llega a un estado final recibes exactamente un webhook risk_batch_completed y un email de término con los contadores y un link a tu cuenta.Los informes dentro de un lote nunca emiten el webhook individual risk_report_ready ni emails por informe — el lote es la señal. Si igual quieres hacer polling, GET /v1/qscore/batches/{id} devuelve los contadores en vivo (processed_items, succeeded_items, failed_items).
3

Lee los resultados

Los resultados por ítem están disponibles como JSON (paginado) o como export CSV listo para Excel.
En un ítem fallido, score es null y la fila trae error_code / error_message:
El export CSV (GET /v1/qscore/batches/{id}/results.csv) entrega todas las filas con BOM UTF-8 para que Excel lo abra bien, e incluye el verify_code público de cada informe. Cada celda está sanitizada contra inyección de fórmulas CSV. Puedes descargarlo en cualquier momento, incluso con el lote aún processing — las filas de ítems aún pending llevan los campos score/band/verify_code vacíos.
Los encabezados CSV visibles siguen el locale de la cuenta; el ejemplo de arriba muestra las claves crudas de las celdas.Cada report_id es un informe individual completo: puedes descargar su PDF con el endpoint estándar de descarga de informes, y cualquiera puede verificar su autenticidad en https://business.cbpayapp.com/verify/qscore/{verify_code}.

​
Lista y busca tus lotes

GET /v1/qscore/batches devuelve tu historial paginado, con filtros from / to (YYYY-MM-DD, zona horaria de tu organización, ambos inclusivos):

​
Estados del lote y del ítem

Lote (GET /v1/qscore/batches/{id}): Ítem (GET /v1/qscore/batches/{id}/items):

​
Cobros

Cada ítem cobra el fee standalone configurado en tu cuenta (risk_report_person o risk_report_company) cuando el worker lo procesa. El estimated_fee_usdt de la respuesta de creación es la estimación upfront de los ítems válidos.
  • Cobros idempotentes: cada ítem se cobra con una referencia de billing determinista derivada del lote y del ítem, así que un reinicio del worker jamás cobra dos veces un ítem.
  • Reembolsos automáticos: un ítem que termina failed recibe el reembolso de su fee en la misma corrida. Solo pagas por los informes efectivamente generados.
  • Los cobros y reembolsos aparecen en tu cartola como cualquier otro fee Qscore.

​
Errores

​
Webhook: risk_batch_completed

Exactamente un webhook por lote, entregado a las suscripciones de la cuenta dueña cuando el lote llega a un estado final. Suscríbete con el event type risk_batch_completed (ver webhooks). El body es el objeto plano de abajo y el event type viaja en el header X-Webhook-Event:
El webhook trae solo contadores — nunca scores ni documentos. Obtén los resultados con GET /v1/qscore/batches/{id}/items o el export CSV. El email de término sigue la misma regla de minimización de datos: contadores y un link, nada más.

​
Preguntas frecuentes

Depende del tamaño y de qué tan fresca esté la data del buró para cada sujeto. Cada ítem es un informe completo (incluido el fetch on-demand al buró), así que estima unos segundos por ítem; un lote de 1.000 sujetos típicamente termina en menos de una hora. No necesitas esperar en línea — el webhook te avisa cuando termina.
No. El worker corre exactamente el mismo pipeline del informe individual, con la misma versión determinista del modelo. Puntuar al mismo sujeto individualmente o dentro de un lote da el mismo resultado en el mismo momento.
Pártela en varios lotes de hasta 5.000 cada uno, con un idempotency_key distinto por lote. Los lotes se procesan de forma independiente y cada uno envía su propio webhook de término.
Sí. Declara subject_type por fila o deja que la API lo infiera de la serie del RUT chileno. Cada ítem se cobra con el fee que corresponde a su tipo.
El procesamiento es crash-safe: el worker retoma el lote donde quedó, y la referencia de billing determinista garantiza que un ítem jamás se cobra dos veces.
En esta versión no. Un lote que ya está processing corre hasta el final; los ítems que fallan se reembolsan automáticamente.
Solo tu cuenta — cualquier otra recibe 404 not_found. Los lotes jamás son visibles entre organizaciones. Los informes individuales que genera un lote son informes Qscore estándar, así que aparecen en los mismos lugares que cualquier otro informe (incluida la vista org-admin de informes de tu organización).
Última modificación el 18 de agosto de 2026