● MANUAL COMPLETO DE INTEGRACIÓN

Consulta al Buró de Crédito,
como una llamada HTTP.

Score Capital resuelve la conexión con el Buró, el análisis de riesgo con tus reglas de negocio, y te regresa una decisión lista para usar. Este manual cubre el flujo estándar de integración y los flujos avanzados disponibles bajo solicitud.

endpoints documentados

<5s

tiempo típico de respuesta

flujos: Físicas y Morales

Score Capital API

Visión general

Cómo funciona

Score Capital API es una capa sobre tu conexión existente con el Buró de Crédito. En lugar de administrar tokens OAuth, credenciales y reglas de análisis por tu cuenta, envías los datos de la persona o empresa a consultar y recibes de vuelta un reporte ya evaluado.

Cada solicitud del flujo principal pasa por tres pasos: (1) se valida tu API key y se identifica tu cuenta, (2) se consulta al Buró de Crédito con las credenciales asociadas a tu cuenta, (3) se aplican tus reglas de negocio configuradas para determinar el estatus final.

Nota — Todos los reportes generados vía API quedan disponibles también en tu panel de Score Capital, identificados con el origen API.

Seguridad

Autenticación

Cada solicitud requiere tu API key en el encabezado X-API-Key. La misma key funciona para todos los endpoints de tu cuenta.

Encabezado	Valor
`X-API-Key`	Tu clave secreta, provista por Score Capital
`Content-Type`	`application/json`

Importante — Tu API key otorga acceso completo a tu cuenta. No la expongas en código de cliente (frontend, apps móviles) — úsala únicamente desde tu servidor.

Resumen de endpoints

Para la gran mayoría de integraciones, solo necesitas los dos endpoints principales — resuelven credenciales, consultan y devuelven la decisión final. Los flujos avanzados están disponibles bajo solicitud.

Endpoint	Método	Nivel	Persiste	¿Analiza?
/v1-reporte/reporte	`POST`	PRINCIPAL	Sí	Sí
/v1-reporte/reporte-pm	`POST`	PRINCIPAL	Sí	Sí
/v1-reporte/directo/pf/token	`POST`	AVANZADO	No aplica	No aplica
/v1-reporte/directo/pf/reporte	`POST`	AVANZADO	No	No
/v1-reporte/con-token/pf	`POST`	AVANZADO	Sí	Sí
/v1-reporte/directo/pm/token	`POST`	AVANZADO	No aplica	No aplica
/v1-reporte/directo/pm/reporte	`POST`	AVANZADO	No	No
/v1-reporte/con-token/pm	`POST`	AVANZADO	Sí	Sí
/v1-reporte/nip/enviar	`POST`	CUMPLIMIENTO	No aplica	No aplica
/v1-reporte/nip/verificar	`POST`	CUMPLIMIENTO	No aplica	No aplica
/v1-reporte/nip/reenviar	`POST`	CUMPLIMIENTO	No aplica	No aplica
/v1-reporte/reporte-con-nip/pf	`POST`	CUMPLIMIENTO	Sí	Sí
/v1-reporte/reporte-con-nip/pm	`POST`	CUMPLIMIENTO	Sí	Sí
/v1-reporte/con-token-nip/pf	`POST`	CUMPLIMIENTO	Sí	Sí
/v1-reporte/con-token-nip/pm	`POST`	CUMPLIMIENTO	Sí	Sí

Regla simple — si un reporte se guarda, siempre se analiza (el campo analisis vive dentro de la fila que se guarda, no puede existir sin ella). Los únicos endpoints que NO analizan son /directo/pf/reporte y /directo/pm/reporte — ahí recibes la respuesta cruda del Buró sin ningún procesamiento de Score Capital, para que apliques tu propio criterio.

¿Cuál usar? — Si solo necesitas "mandar datos, recibir una decisión", usa /reporte o /reporte-pm. La Conexión Directa existe para integraciones donde tú ya manejas tus propias credenciales de Score Capital. Los endpoints de Cumplimiento exigen verificación de identidad (NIP) antes de generar el reporte — úsalos si necesitas dejar constancia auditable del consentimiento del titular. Todas las solicitudes, se guarden o no, quedan registradas para fines de facturación.

Producto principal · Personas Físicas

PRINCIPALPersiste en tu cuenta

Generar un reporte

Recibe los datos de identificación de una persona física, consulta el Buró de Crédito y regresa el reporte con el análisis de riesgo aplicado.

POST/v1-reporte/reporte

Cuerpo de la solicitud

Nuestro sistema soporta un catálogo amplio de campos opcionales para enriquecer la consulta. Este es el subconjunto que actualmente utilizamos — cubre lo necesario para obtener un resultado completo y confiable.

Campo	Tipo	Límite
firstName	string	2–26 caracteres	REQUERIDO
paternalLastName	string	2–26 caracteres	REQUERIDO
maternalLastName	string	2–26 caracteres	REQUERIDO
rfc	string	máx. 13 caracteres	REQUERIDO — formato `AAAANNNNNNZZZ`
birthDate	string	8 caracteres	REQUERIDO — formato `DDMMYYYY`
street	string	2–40 caracteres	REQUERIDO — calle y número
neighborhood	string	2–40 caracteres	REQUERIDO — colonia
city	string	2–40 caracteres	REQUERIDO
municipalityOrBorough	string	2–40 caracteres	REQUERIDO — alcaldía o municipio
state	string	2–4 caracteres	REQUERIDO — código de estado, ver catálogo abajo
postalCode	string	exactamente 5 dígitos	REQUERIDO

¿La persona no tiene apellido materno? — El Buró de Crédito requiere este campo con contenido. Si tu usuario no cuenta con apellido materno, envía el texto "NO PROPORCIONADO" en su lugar. Score Capital no completa ni modifica este dato — es responsabilidad de quien integra la API proporcionarlo correctamente.

Catálogo de códigos de estado válidos

state debe enviarse como el código exacto, no el nombre completo del estado. Un código fuera de este catálogo hace que la solicitud sea rechazada.

Código	Estado	Código	Estado
`AGS`	Aguascalientes	`MOR`	Morelos
`BCN`	Baja California	`NAY`	Nayarit
`BCS`	Baja California Sur	`NL`	Nuevo León
`CAM`	Campeche	`OAX`	Oaxaca
`CHS`	Chiapas	`PUE`	Puebla
`CHI`	Chihuahua	`QRO`	Querétaro
`CDMX`	Ciudad de México	`QR`	Quintana Roo
`COA`	Coahuila	`SLP`	San Luis Potosí
`COL`	Colima	`SIN`	Sinaloa
`DGO`	Durango	`SON`	Sonora
`EM`	Estado de México	`TAB`	Tabasco
`GTO`	Guanajuato	`TAM`	Tamaulipas
`GRO`	Guerrero	`TLAX`	Tlaxcala
`HGO`	Hidalgo	`VER`	Veracruz
`JAL`	Jalisco	`YUC`	Yucatán
`MICH`	Michoacán	`ZAC`	Zacatecas

Respuesta

Una solicitud exitosa regresa 200 OK con el reporte completo.

Campo	Tipo	Descripción
id	uuid	Identificador único del reporte
status	enum	`Aprobado` · `Rechazado` · `Pendiente` · `No Consultado`
numberControl	string	Número de control asignado a la consulta
score	integer	Score crediticio (rango 300–850)
icc	integer	Índice de capacidad de crédito (rango 0–9)
analisis	object	Desglose completo de la evaluación
createdAt	datetime	Fecha y hora de creación del reporte

Objeto de análisis

El campo analisis contiene el desglose completo que sustenta el status final — las mismas reglas que usa tu equipo internamente.

Campo	Descripción
justificacionDecision	Lista de razones, en lenguaje llano, detrás de la decisión
iccAnalysis	Categoría recomendada según la matriz score × ICC
peorMorosidad	Peor atraso detectado, últimos 12 meses y más reciente
clavesObservacion	Claves de observación detectadas y su nivel de riesgo
restriccionesPostales	Coincidencias contra tu lista de códigos postales restringidos

Ejemplo de respuesta completa

response.raw

analisis

Producto principal · Personas Morales / PFAE

PRINCIPALPersiste en tu cuenta

Generar un reporte

Recibe los datos de una empresa (Persona Moral) o de una persona física con actividad empresarial (PFAE), consulta el Buró Empresas y regresa el reporte con el análisis de riesgo y el interpretador oficial aplicados.

POST/v1-reporte/reporte-pm

Buró Empresas rara vez regresa un score numérico — por eso el análisis incluye un scoreInterno propio (0–100), calculado con el comportamiento de pago real, antigüedad y calificación de cartera.

Cuerpo de la solicitud

El campo personType determina qué otros campos aplican.

Campo	Tipo	Límite
personType	enum	—	REQUERIDO — `PM` o `PFAE`
rfc	string	—	REQUERIDO
razonSocial	string	—	REQUERIDO — razón social si `PM`; nombre de pila si `PFAE`
SegundoNombre	string	—	OPCIONAL — solo `PFAE`
ApellidoP	string	—	REQUERIDO si PFAE
ApellidoM	string	—	REQUERIDO si PFAE
birthDate	string	8 caracteres	OPCIONAL — solo `PFAE`, formato `DDMMAAAA`. No se acepta para menores de 18 años.
street	string	2–40 caracteres	REQUERIDO
neighborhood	string	máx. 60 caracteres	REQUERIDO — colonia
city	string	máx. 40 caracteres	REQUERIDO
municipalityOrBorough	string	máx. 40 caracteres	REQUERIDO
state	string	2–4 caracteres	REQUERIDO — código de estado, mismo catálogo que Personas Físicas
postalCode	string	exactamente 5 dígitos	REQUERIDO — debe ser consistente con estado y ciudad

Validación cruzada — el código postal, ciudad/municipio y estado se validan entre sí contra el catálogo oficial de domicilios. Una combinación inconsistente hace que la solicitud se rechace, aunque cada campo individualmente tenga el formato correcto.

¿La persona no tiene apellido materno? — Igual que en Personas Físicas, ApellidoM es requerido para PFAE. Si tu usuario no cuenta con uno, envía el texto "NO PROPORCIONADO".

Respuesta

Una solicitud exitosa regresa 200 OK con el reporte completo.

Campo	Tipo	Descripción
id	uuid	Identificador único del reporte
personType	enum	`PM` · `PFAE`
status	enum	`Aprobado` · `Rechazado`
numberControl	string	Número de control asignado por el Buró
score	integer	Score del Buró — frecuentemente no disponible (ver `scoreNoDisponible`)
analisis	object	Evaluación de riesgo, score interno, calificación de cartera
interpretador	object	Interpretador oficial del Buró Empresas
createdAt	datetime	Fecha y hora de creación del reporte

Objeto de análisis

Campo	Descripción
statusFinal	Decisión: `Aprobado` o `Rechazado`
recomendacion	Explicación en lenguaje llano de la decisión
scoreInterno	Score propio de Score Capital, 0–100
nivelRiesgo	`Bajo` · `Medio` · `Medio-Alto` · `Alto`
calificacionCarteraLabel	Calificación oficial de cartera (A, B, C1, C2, D, E)
comportamientoPagos	% de cumplimiento histórico y detalle por crédito activo
perfilHistorico	Antigüedad y patrón de liquidación de créditos cerrados
analisisAcreedores	Concentración de deuda por tipo de acreedor
accionistas	Accionistas con porcentaje de participación (solo `PM`)
motivosRechazo	Lista de razones específicas si el reporte fue rechazado

Objeto interpretador

Campo	Descripción
vistaGlobal	Exposición total, morosidad máxima actual e histórica
tendencias	Distribución de morosidad por créditos financieros y comerciales
experienciaCrediticia	Antigüedad promedio y distribución de créditos activos/liquidados
apetitoCredito	Consultas e intensidad de búsqueda de nuevo crédito
extrasScoreCapital	Semáforo de riesgo y alertas propias de Score Capital

Ejemplo de respuesta completa

response.raw

analisis

interpretador

Modo de pruebas

SANDBOXSin costo · Sin persistencia

Sandbox — prueba tu integración sin costo

Antes de conectar tu sistema a producción, prueba el flujo completo con datos simulados. Misma API key, mismas reglas de validación, mismo formato de respuesta exacto — la única diferencia es que no se realiza ninguna consulta real y no tiene costo.

El resultado depende del endpoint, no de los datos — a diferencia de producción, en sandbox tú eliges el desenlace (aprobado, rechazado, pendiente) según qué ruta llames. Los datos que envíes solo se reflejan en la respuesta (nombre, RFC, domicilio) — pero sí se validan con las mismas reglas que producción, así que también puedes probar cómo se ve un error de validación.

Endpoint	Escenario
`/v1-reporte-sandbox/reporte-pf-aprobado`	Persona física — score alto, sin observaciones
`/v1-reporte-sandbox/reporte-pf-rechazado`	Persona física — score bajo, morosidad activa
`/v1-reporte-sandbox/reporte-pf-pendiente`	Persona física — requiere revisión manual
`/v1-reporte-sandbox/reporte-pm-aprobado`	Persona moral / PFAE — perfil solvente, sin alertas
`/v1-reporte-sandbox/reporte-pm-rechazado`	Persona moral / PFAE — combina las alertas más comunes (PEP, cliente no localizado, cuentas reestructuradas)

Personas Físicas

Usa el mismo cuerpo de solicitud que el endpoint real — los mismos campos requeridos aplican.

POST/v1-reporte-sandbox/reporte-pf-aprobado

POST/v1-reporte-sandbox/reporte-pf-rechazado

POST/v1-reporte-sandbox/reporte-pf-pendiente

Solicitud (misma para los 3)

Respuesta — reporte-pf-aprobado

Personas Morales / PFAE

POST/v1-reporte-sandbox/reporte-pm-aprobado

POST/v1-reporte-sandbox/reporte-pm-rechazado

Solicitud (misma para los 2)

Respuesta — reporte-pm-rechazado (todas las alertas combinadas)

Conexión directa · Personas Físicas

AVANZADO

Conexión directa

Para integraciones donde ya manejas tus propias credenciales de Score Capital y necesitas un control más granular del proceso de autenticación. Disponible bajo solicitud — contacta a tu ejecutivo de cuenta para habilitarlo.

Tú eliges si el reporte se guarda — con tu token puedes consultar sin dejar rastro en tu cuenta (/directo/pf/reporte), o consultar y que quede registrado en tu panel igual que el flujo principal (/con-token/pf). Ambos casos se registran para fines de facturación, sin importar cuál elijas.

1. Obtener token

Autentica directamente con tus credenciales y obtén un token de acceso para tu sesión.

POST/v1-reporte/directo/pf/token

Solicitud

Respuesta

2a. Consultar sin guardar

Usa el token del paso anterior para realizar la consulta. Regresa la respuesta tal como la entrega Score Capital — no se crea ningún registro en tu panel.

POST/v1-reporte/directo/pf/reporte

Solicitud

2b. Consultar y guardar

Mismo mecanismo, pero además guarda el reporte en tu cuenta y aplica tu análisis de riesgo configurado — aparece en tu panel de Score Capital igual que uno generado desde /reporte.

POST/v1-reporte/con-token/pf

Solicitud

La respuesta de /con-token/pf tiene la misma forma que /v1-reporte/reporte — status, score, icc, analisis completo.

Conexión directa · Personas Morales

AVANZADO

Conexión directa

Mismo patrón que Personas Físicas, usando tus credenciales del sistema para Buró Empresas.

Tú eliges si el reporte se guarda — igual que en Personas Físicas: /directo/pm/reporte no deja rastro en tu panel, /con-token/pm sí. Ambos se registran para fines de facturación.

1. Obtener token

POST/v1-reporte/directo/pm/token

Solicitud

2a. Consultar sin guardar

POST/v1-reporte/directo/pm/reporte

Solicitud

2b. Consultar y guardar

Guarda el reporte en tu cuenta y aplica el análisis PM completo (analisis + interpretador).

POST/v1-reporte/con-token/pm

Solicitud

Cumplimiento · Verificación de identidad

CUMPLIMIENTO

Verificación de identidad (NIP)

Confirma que el titular de la consulta autorizó explícitamente la revisión de su historial crediticio, antes de generar el reporte. El código de verificación queda vinculado al reporte final y aparece en tu historial de auditoría, igual que los reportes generados desde tu panel de Score Capital.

Disponible bajo solicitud — contacta a tu ejecutivo de cuenta para habilitarlo. Es un flujo de 3 pasos: enviar el código, verificarlo, y usarlo al generar el reporte.

1. Enviar código

Genera un código de 6 dígitos, lo envía por correo al titular, y regresa un token que identifica esta verificación específica. Vigencia: 10 minutos.

POST/v1-reporte/nip/enviar

Solicitud

Respuesta

Guarda el token — lo necesitas para verificar el código y, después, para generar el reporte. No lo muestres al titular; solo el código de 6 dígitos llega por correo.

2. Verificar código

POST/v1-reporte/nip/verificar

Solicitud

Respuesta

3. Reenviar código (opcional)

Si el titular no recibió el correo o el código expiró antes de escribirlo, reenvía uno nuevo sin perder el token original. Extiende la vigencia otros 10 minutos.

POST/v1-reporte/nip/reenviar

Solicitud

Código	Significado
403	Código incorrecto
404	Token de verificación no encontrado
409	Este código ya fue verificado (o ya no se puede reenviar)
410	El código expiró (más de 10 minutos)

Generar el reporte con NIP verificado

Una vez verificado el token del paso anterior, úsalo para generar el reporte. El NIP es obligatorio en estos endpoints — si el token no está verificado o expiró, la solicitud se rechaza con 422 sin gastar ninguna consulta al Buró. El reporte queda guardado con el código de verificación asociado, visible en tu historial de auditoría.

Con credenciales del sistema

POST/v1-reporte/reporte-con-nip/pf

POST/v1-reporte/reporte-con-nip/pm

Solicitud — Personas Físicas

Respuesta

Con tu propio token del Buró (Conexión Directa + NIP)

Combina la Conexión Directa con la verificación de NIP — para integraciones que ya manejan su propio token y también necesitan cumplimiento de auditoría.

POST/v1-reporte/con-token-nip/pf

POST/v1-reporte/con-token-nip/pm

Solicitud — Personas Físicas

Código	Significado
400	Falta `token` (Buró) — solo en los endpoints con token propio
422	`nipToken` faltante, no verificado o expirado

Guía de referencia

Interpretación de resultados

Catálogos de referencia para leer correctamente los campos devueltos en analisis e interpretador. Por ahora cubre Personas Morales; la guía de Personas Físicas se agrega próximamente.

Calificación de cartera (Personas Morales)

El campo calificacionCarteraLabel refleja qué tan sólido es el comportamiento de pago de la empresa frente a sus acreedores. Va de A1 (mejor) a E (peor).

Calificación	Significado
`A1`	Compromiso de pago sólido, cuentas vigentes con todos sus acreedores
`A2`	Desempeño sobresaliente, incumplimientos ocasionales de 1–14 días
`B1`	Buen manejo, algún atraso de 15–29 días cubierto rápidamente
`B2`	Desempeño satisfactorio, atrasos de 30–44 días
`B3`	Pago habitualmente tardío, atrasos de 45–59 días
`C1`	Desempeño débil, atrasos de 60–89 días o información incompleta
`C2`	Comportamiento insatisfactorio, crédito vencido 90–179 días
`D`	Vencimiento de 180–365 días
`E`	Cuenta vencida por más de 365 días
`EX`	Cartera exceptuada, no se califica
`NC`	Cartera no calificada

Claves de observación (Personas Morales)

Indican una situación especial en una cuenta o crédito específico. Aparecen en clavesObservacion.

Clave	Significado
`AD`	Cuenta en aclaración directa con el acreedor
`CA`	Cartera al corriente vendida/cedida a otro acreedor del sistema
`CC`	Crédito cerrado a solicitud del cliente o del acreedor
`CL`	Cuenta en cobranza, pagada totalmente
`CO`	Crédito en controversia legal
`CP` / `CT`	Crédito hipotecario con inmueble declarado pérdida por catástrofe natural
`CV`	Cartera con problemas de pago, vendida/cedida a otro acreedor del sistema
`FD`	Fraude atribuible al cliente, confirmado judicialmente
`FN`	Fraude NO atribuible al cliente (robo de identidad/documentos)
`FP`	Fianza pagada en su totalidad
`FR`	Bien adjudicado o garantía ejecutada por falta de pago
`GP`	Pago mediante ejecución de garantía prendaria o fiduciaria
`IA`	Cuenta inactiva (crédito vigente sin usar)
`IM`	Integrante de grupo solidario causante de mora
`IS`	Integrante de grupo solidario subsidiado para evitar mora
`LC`	Convenio de finiquito con pago menor a la deuda (quita)
`LG`	Quita por programa institucional o gubernamental
`LO`	Cliente no localizado por el acreedor
`LS`	Tarjeta de crédito extraviada o robada
`MP`	Reestructura por buen comportamiento de pago
`NA`	Cartera al corriente vendida a un tercero fuera del sistema
`NV`	Cartera vencida vendida a un tercero fuera del sistema
`PC`	Cuenta enviada a despacho de cobranza
`RA`	Reestructura por programa institucional/gubernamental, sin quita
`RI`	Robo de identidad comprobado
`RF`	Resolución judicial favorable al cliente
`RN`	Reestructura por conclusión de proceso judicial
`RV`	Reestructura a petición del cliente, sin quita
`SG`	Demanda interpuesta por el acreedor
`UP`	Saldo reportado como pérdida total (castigo)
`VR`	Dación en pago o renta del bien

Claves de prevención (Personas Morales)

A diferencia de las claves de observación (por crédito), estas describen la situación general del cliente o de una persona relacionada con la empresa. Aparecen en clavesPrevencion.

Código	Significado	Aplica a
`78`	Negocio receptor de tarjetas que ocasionó pérdida al acreedor	Cliente directo
`79`	Persona relacionada con una PFAE con clave de prevención	Persona relacionada
`80`	Cliente en quiebra, suspensión de pagos o concurso mercantil	Cliente directo
`81`	Cliente en trámite judicial	Cliente directo
`82`	Fraude comprobado judicialmente	Cliente directo
`83`	Liquidación acordada con pago menor a la deuda	Cliente directo
`84`	Cliente no localizado	Cliente directo
`85`	Desvío comprobado de recursos a fines distintos	Cliente directo
`86`	Disposición de garantías sin autorización	Cliente directo
`87`	Cambio de régimen de propiedad de sus bienes	Cliente directo
`88`	Retenciones a trabajadores no enteradas a la autoridad	Cliente directo
`92`	Pérdida total ocasionada al acreedor	Cliente directo

Histórico de pagos — MOP (Personas Morales)

Cada posición del historial indica cuánto tiempo llevaba vencido un pago en ese período. Es la base de comportamientoPagos y perfilHistorico.

Código	Significado
`1`	Al corriente, 0 días de atraso
`2`	Atraso de 1 a 29 días
`3`	Atraso de 30 a 59 días
`4`	Atraso de 60 a 89 días
`5`	Atraso de 90 a 119 días
`6`	Atraso de 120 a 179 días
`7`	Atraso de 180 días o más
`D`	Información anulada a solicitud del acreedor
`-`	Período no reportado

Códigos de razón del Score PyME

Cuando el score numérico está disponible, estos códigos explican qué factores lo afectaron.

Código	Significado
`01`	Morosidades recientes en el histórico de pagos
`02–03`	Poco historial de crédito en cuentas (totales / abiertas)
`04–06`	Morosidades altas en los últimos 4–12 meses
`07`	Score bajo en los accionistas
`16–17`	Utilización alta de sus líneas/cuentas de crédito
`19`	Poca antigüedad crediticia
`27–29`	Varias cuentas cerradas / saldos vencidos o vigentes altos

Cuando el score no está disponible (scoreNoDisponible: true), el motivo suele ser uno de estos códigos de exclusión o error:

Código	Significado
`-2`	El consultado no es una PyME (gobierno o fideicomiso)
`-3`	Sospecha de fraude
`-4`	Información insuficiente para calcular el score
`-7`	Todas las cuentas están cerradas
`-8`	Información desactualizada
`-103`	Score no disponible
`-104`	Score no válido

Histórico de pagos — MOP (Personas Físicas)

Manner of Payment: indica cuánto tiempo llevaba vencido un pago en ese período del historial. La escala de PF tiene más granularidad que la de PM.

Código	Significado
`00`	Muy reciente para calificar (cuenta de menos de 3 meses, sin actividad aún)
`01`	Al corriente, 0 días de atraso
`02`	Atraso de 1 a 29 días
`03`	Atraso de 30 a 59 días
`04`	Atraso de 60 a 89 días
`05`	Atraso de 90 a 119 días
`06`	Atraso de 120 a 149 días
`07`	Atraso de 150 días hasta 12 meses
`96`	Atraso de más de 12 meses
`97`	Deuda parcial o total sin recuperar
`99`	Fraude cometido por el cliente
`UR` / `-` / `X` / `U`	Sin actividad en el período (típico en cuentas revolventes sin saldo ni movimientos)
`D`	Información anulada a solicitud del acreedor

Claves de observación (Personas Físicas)

El catálogo es prácticamente el mismo que en Personas Morales (ver arriba) — mismas claves, mismo significado. Las siguientes son específicas del reporte de personas físicas, todas aplicables únicamente a crédito hipotecario de gobierno:

Clave	Significado
`CD`	Disminución del pago por convenio con la institución (ajuste al plan de pagos)
`PD`	Prórroga otorgada por desastre natural (apoyo gubernamental)
`PE`	Prórroga otorgada por situaciones especiales (ej. huelga)
`PI`	Prórroga o liberación del crédito por invalidez total o defunción del titular
`PR`	Prórroga otorgada por pérdida de relación laboral

Códigos de razón del score (BC Score)

El campo codigoRazon dentro de scoreBuroCredito explica qué factores influyeron más en el score. Es un catálogo extenso (más de 100 códigos, agrupados por versión del modelo de score) — algunos ejemplos comunes:

Código	Significado
`001`	Nivel de endeudamiento
`004`	Consulta reciente
`005`	Pago vencido reciente
`009–011`	Bajo promedio de antigüedad en créditos
`013`	Número de cuentas abiertas
`021`	Atrasos frecuentes o recientes
`-001`	Titular fallecido (código de exclusión)
`-009`	Expediente sin cuentas suficientes para calcular el score

Nota — El catálogo completo de códigos de razón varía según la versión del modelo de score (BC Score clásico vs. BC Score 2022) y supera los 100 valores. Si tu integración necesita interpretar cada código a detalle, contáctanos y te compartimos el catálogo completo.

Operación

Códigos de error

Código	Significado
400	Falta un campo requerido en la solicitud
401	API key faltante o inválida
422	Tu cuenta no tiene credenciales del Buró configuradas
429	Límite de solicitudes excedido
502	El Buró de Crédito rechazó la solicitud o no respondió

En la Conexión Directa (con-token), los errores originales se incluyen junto con una traducción — ver campo buro vs. mensaje en la respuesta.

Límites de uso

Por defecto, cada cuenta puede realizar hasta 30 solicitudes por minuto, combinando todos los endpoints. Si necesitas un límite mayor, contacta a tu ejecutivo de cuenta.

Operación

Registro de uso y facturación

Cada solicitud a la API, sin importar el endpoint o si terminó en éxito o error, queda registrada de forma auditable — esto sustenta tu facturación y te da trazabilidad completa de tu consumo.

Endpoint	Se registra
`/reporte`, `/reporte-pm`	Toda solicitud — exitosa, con error de validación, o rechazada por el Buró
`/con-token/pf`, `/con-token/pm`	Toda solicitud, igual que arriba
`/directo/pf/token`, `/directo/pm/token`	Toda solicitud de token, exitosa o con credenciales inválidas

¿Se cobran las solicitudes fallidas? — Depende de tu plan contratado — consulta con tu ejecutivo de cuenta. En cualquier caso, tanto los éxitos como los errores quedan documentados en tu historial, disponible bajo solicitud, para que puedas auditar tu propio consumo.

Consulta al Buró de Crédito,como una llamada HTTP.

Cómo funciona

Autenticación

Resumen de endpoints

Generar un reporte

Cuerpo de la solicitud

Catálogo de códigos de estado válidos

Respuesta

Objeto de análisis

Ejemplo de respuesta completa

Generar un reporte

Cuerpo de la solicitud

Respuesta

Objeto de análisis

Objeto interpretador

Ejemplo de respuesta completa

Sandbox — prueba tu integración sin costo

Personas Físicas

Personas Morales / PFAE

Conexión directa

1. Obtener token

2a. Consultar sin guardar

2b. Consultar y guardar

Conexión directa

1. Obtener token

2a. Consultar sin guardar

2b. Consultar y guardar

Verificación de identidad (NIP)

1. Enviar código

2. Verificar código

3. Reenviar código (opcional)

Generar el reporte con NIP verificado

Con credenciales del sistema

Con tu propio token del Buró (Conexión Directa + NIP)

Interpretación de resultados

Calificación de cartera (Personas Morales)

Claves de observación (Personas Morales)

Claves de prevención (Personas Morales)

Histórico de pagos — MOP (Personas Morales)

Códigos de razón del Score PyME

Histórico de pagos — MOP (Personas Físicas)

Claves de observación (Personas Físicas)

Códigos de razón del score (BC Score)

Códigos de error

Límites de uso

Registro de uso y facturación

Consulta al Buró de Crédito,
como una llamada HTTP.