CÍRCULO4 tokensPOST

Score de crédito de Persona Física

Consulta únicamente el score crediticio de una persona física y los códigos de razón que lo explican. Pensado para decisiones rápidas de bajo costo, cuando no necesitas el detalle cuenta por cuenta.

Endpoint

POSThttps://api.consultasnonstop.com/v1/circulo/score-pf

Parámetros

json

{
  "autorizacion": "aut_9f3k28d1",
  "nombres": "MARIA GUADALUPE",
  "primerApellido": "HERNANDEZ",
  "segundoApellido": "GOMEZ",
  "fechaNacimiento": "1985-01-01",
  "rfc": "HEGM850101AB1",
  "codigoPostal": "06700"
}

ParámetroTipoRequeridoDescripción

autorizacionstringSíFolio de la autorización del titular

nombresstringSíNombres de pila del titular

primerApellidostringSíPrimer apellido del titular

segundoApellidostringNoSegundo apellido del titular

fechaNacimientostringSíFecha de nacimiento del titular en formato ISO YYYY-MM-DD

rfcstringNoRFC del titular con homoclave

codigoPostalstringSíCódigo postal del domicilio del titular a 5 dígitos

Ejemplo rápido

Coloca tu API key en el header x-api-key y agrega el header Content-Type: application/json para enviar el body como JSON.

curl

curl -X POST https://api.consultasnonstop.com/v1/circulo/score-pf \
  -H "x-api-key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"autorizacion":"aut_9f3k28d1","nombres":"MARIA GUADALUPE","primerApellido":"HERNANDEZ","segundoApellido":"GOMEZ","fechaNacimiento":"1985-01-01","rfc":"HEGM850101AB1","codigoPostal":"06700"}'

Tip

¿Sabías que al pegar un cURL en Postman te crea automáticamente la llamada con todos los elementos?

Token

Cada consulta consume tokens. Lo que no uses, lo conservas — tu saldo se acumula sin fecha de vencimiento ni reinicios. Puedes consultarlo en cualquier momento desde el dashboard o directamente en el header de cada respuesta x-tokens-remaining.

Respuesta

JSON

200 OK

{
  "id": "e18b34c70a52d9f64b03e7a1",
  "status": "found",
  "autorizacion": "aut_9f3k28d1",
  "folioConsulta": "CNS-2026-0004816",
  "fechaConsulta": "2026-09-03",
  "rfc": "HEGM850101AB1",
  "nombres": "MARIA GUADALUPE",
  "primerApellido": "HERNANDEZ",
  "segundoApellido": "GOMEZ",
  "fechaNacimiento": "1985-01-01",
  "codigoPostal": "06700",
  "score": 743,
  "rangoScore": "BUENO",
  "codigosRazon": [
    {
      "codigo": "A05",
      "descripcion": "Antigüedad promedio de las cuentas menor a la deseable"
    },
    {
      "codigo": "B12",
      "descripcion": "Porcentaje de utilización de las líneas revolventes elevado"
    },
    {
      "codigo": "C03",
      "descripcion": "Número de consultas recientes al historial"
    }
  ]
}

Respuestas en error

JSON

400 Bad Request

[
  {
    "type": "required",
    "message": "El campo es requerido",
    "field": "autorizacion"
  },
  {
    "type": "format",
    "message": "El formato del campo es inválido",
    "field": "codigoPostal"
  }
]

Campos

Campos de entrada

CampoTipoDescripción

autorizacionstringFolio de la autorización otorgada por el titular. Debe estar en estatus autorizada y vigente.

nombresstringNombres de pila del titular tal como aparecen en su identificación oficial.

primerApellidostringPrimer apellido del titular.

segundoApellidostringSegundo apellido del titular. Se omite cuando el titular no tiene segundo apellido.

fechaNacimientostringFecha de nacimiento del titular en formato ISO YYYY-MM-DD.

rfcstringRFC del titular con homoclave. Mejora la precisión del match en la fuente.

codigoPostalstringCódigo postal del domicilio del titular a 5 dígitos.

Campos de respuesta

CampoTipoDescripción

idstringIdentificador interno de la consulta, útil para soporte y trazabilidad.

statusstringResultado del cálculo del score en la fuente. Ver catálogo Status.

messagestringDetalle del motivo cuando status es not_found. Solo está presente en respuestas not_found. Ver catálogo Mensajes not_found.

autorizacionstringFolio de la autorización al amparo de la cual se realizó la consulta.

folioConsultastringFolio de la consulta ante la fuente, para efectos de auditoría.

fechaConsultastringFecha en que se realizó la consulta en formato ISO YYYY-MM-DD.

rfcstringRFC del titular consultado.

nombresstringNombres de pila del titular según la fuente.

primerApellidostringPrimer apellido del titular según la fuente.

segundoApellidostringSegundo apellido del titular según la fuente.

fechaNacimientostringFecha de nacimiento del titular en formato ISO YYYY-MM-DD.

codigoPostalstringCódigo postal del domicilio registrado en la fuente.

scorenumberScore crediticio del titular. Va de 300 a 850: a mayor valor, menor riesgo.

rangoScorestringRango cualitativo al que pertenece el score. Ver catálogo Rango de score.

codigosRazonarrayFactores que más pesaron en el score, ordenados por impacto de mayor a menor.

codigosRazon[].codigostringClave del factor que afectó el score.

codigosRazon[].descripcionstringExplicación en lenguaje humano del factor.

Catálogos

Tablas de referencia para los valores de los campos enumerados en la sección anterior.

Status

Valores posibles del campo status.

ValorDescripción

foundSe calculó el score del titular. La respuesta incluye el score y sus códigos de razón.

not_foundLa fuente no pudo calcular un score para el titular. La respuesta incluye el campo message con el detalle.

Mensajes not_found

Valores posibles del campo message cuando status es not_found.

MensajeDescripción

El titular no tiene historial crediticio suficiente para calcular un scoreLa persona existe pero su historial no cumple la antigüedad mínima que exige el modelo.

No se encontró una persona con los datos proporcionadosLa combinación de nombre, fecha de nacimiento y código postal no coincide con ningún registro.

El historial del titular está bloqueado por el propio titularEl titular activó un bloqueo de consultas sobre su historial.

Rango de score

Valores posibles del campo rangoScore.

ValorScoreDescripción

EXCELENTE780 – 850Historial impecable y bajo nivel de endeudamiento.

BUENO700 – 779Historial sano con áreas de mejora menores.

REGULAR620 – 699Historial con atrasos ocasionales o utilización elevada.

BAJO540 – 619Historial con atrasos recurrentes.

MUY BAJO300 – 539Historial con incumplimientos graves o adeudos sin recuperar.

Histórico

Endpoint

GEThttps://api.consultasnonstop.com/v1/circulo/score-pf/historico/{id}

El {id} corresponde al campo id devuelto en la respuesta de la consulta principal.

Si necesitas la lista completa de elementos almacenados, accede a tu dashboard.

La respuesta está sujeta al tiempo de almacenamiento de tu plan. Si requieres más tiempo, cambia de plan en tu dashboard.

Respuesta

JSON

200 OK

{
  "id": "e18b34c70a52d9f64b03e7a1",
  "status": "found",
  "autorizacion": "aut_9f3k28d1",
  "folioConsulta": "CNS-2026-0004816",
  "fechaConsulta": "2026-09-03",
  "rfc": "HEGM850101AB1",
  "nombres": "MARIA GUADALUPE",
  "primerApellido": "HERNANDEZ",
  "segundoApellido": "GOMEZ",
  "fechaNacimiento": "1985-01-01",
  "codigoPostal": "06700",
  "score": 743,
  "rangoScore": "BUENO",
  "codigosRazon": [
    {
      "codigo": "A05",
      "descripcion": "Antigüedad promedio de las cuentas menor a la deseable"
    },
    {
      "codigo": "B12",
      "descripcion": "Porcentaje de utilización de las líneas revolventes elevado"
    },
    {
      "codigo": "C03",
      "descripcion": "Número de consultas recientes al historial"
    }
  ]
}

Respuestas en error

JSON

404 Not Found

[
  {
    "type": "not_found",
    "message": "el id no fue encontrado en el historico"
  }
]

Sandbox

Endpoint

POSThttps://sandbox.api.consultasnonstop.com/v1/circulo/score-pf

Para llamar al sandbox necesitas una API key de sandbox que puedes generar en el dashboard.

curl

curl -X POST https://sandbox.api.consultasnonstop.com/v1/circulo/score-pf \
  -H "x-api-key: tu_api_key_sandbox" \
  -H "Content-Type: application/json" \
  -d '{"autorizacion":"aut_9f3k28d1","nombres":"MARIA GUADALUPE","primerApellido":"HERNANDEZ","segundoApellido":"GOMEZ","fechaNacimiento":"1985-01-01","rfc":"HEGM850101AB1","codigoPostal":"06700"}'

Casos de prueba

Si envías un valor de RFC que no esté en la lista, el sandbox devuelve automáticamente una respuesta exitosa con la misma estructura que la de HEGM850101AB1.

CasoRFC

Caso exitoso — EncontradoHEGM850101AB1

Caso exitoso — No encontradoXAXX010101000

Autorización inválidaAUTA800101AB2

Sin tokensSINC700303EF4

Error internoERRD650404GH5

Unavailable serviceUNAE600505IJ6

Endpoint histórico

GEThttps://sandbox.api.consultasnonstop.com/v1/circulo/score-pf/historico/{id}

Para llamar al sandbox necesitas una API key de sandbox que puedes generar en el dashboard.

curl

curl https://sandbox.api.consultasnonstop.com/v1/circulo/score-pf/historico/e18b34c70a52d9f64b03e7a1 \
  -H "x-api-key: tu_api_key_sandbox"

Casos de prueba histórico

Si envías un valor de id que no esté en la lista, el sandbox devuelve automáticamente una respuesta exitosa con la misma estructura que la de e18b34c70a52d9f64b03e7a1.

Casoid

Caso exitosoe18b34c70a52d9f64b03e7a1

No encontrado0000000000000000ffffffff

Fuera de rango1111111111111111aaaaaaaa

Error interno2222222222222222bbbbbbbb

Crea tu cuenta →