Consulta Única API Docs

Esquema de color

Inicio ​

A continuación se describirá el consumo correcto de la API de Consulta.

📖 Información general ​

  • Es necesario mencionar que este es un servicio REST y se consume a traves de un cliente HTTP. Esta pensado para utilizarse sobre un Backend, no se recomienda consumir directamente en Javascript sobre el navegador debido a tema de CORS.
  • La autenticación a la API se realiza mediante el uso de una API Key la cual se debe enviar en Header del Request HTTP. El Header debe llamarse x-api-key.
  • La API Key tiene una longitud de 48 caracteres hexadecimales.
  • En caso de decidirse por adquirir el servicio puede ver nuestros paquetes y precios en el siguiente enlace: https://consultaunica.mx/paquetes
  • Después de la compra, su API Key queda disponible en nuestro portal: https://dash.consultaunica.mx/ajustes/api-key. Ya no se envía por correo electrónico. Si no la ve ahí después de su compra, favor de comunicarse con nosotros mediante alguno de los medios disponibles descritos abajo.
  • La URL base para consumir los servicios de la API es: https://api.consultaunica.mx/v3/{service_name}. La mayoría de los endpoints usan el método POST; algunos endpoints de consulta (como user-stats) usan GET. Revisa la documentación de cada servicio para confirmar el método.

📮 Colección de Postman ​

Descarga la colección con los servicios de consulta e impórtala en Postman:

⬇️ consulta-unica-api.postman_collection.json

En Postman: Import → arrastra el archivo → en la colección, pestaña Variables, escribe tu clave en apiKey. El header X-API-Key se envía solo en todas las peticiones.

La colección trae dos variables:

VariableValor por defectoPara qué sirve
baseUrlhttps://api.consultaunica.mxURL base de la API
apiKey(vacío)Tu clave de consulta

Incluye los servicios del listado de servicios: Seguro Social (6 consultas y SC Premium), Hacienda (4), Afore y Telefonía.

La consulta de NSS aparece dos veces porque el query param _v cambia su profundidad: ?_v=3 es la rápida y ?_v=2 la profunda.

Cada petición trae además sus respuestas de ejemplo guardadas —la exitosa y las de error— tomadas de la documentación de cada servicio. En Postman aparecen bajo la petición, en el desplegable de ejemplos, y puedes abrirlas sin gastar una consulta.

Los campos provienen de la definición OpenAPI de la propia API y los ejemplos de esta documentación, así que la colección refleja el contrato vigente de cada servicio.

💬 Medios de contacto ​

En caso de problemas o cualquier tema que quiera tratar, contamos con 2 medios de contacto disponibles:

🙌🏼 Servicios disponibles ​

ServicioUtilidad
Seguro SocialMediante una CURP y correo electrónico se puede consultar el NSS de una persona. Una segunda llamada puede devolver la constancia de vigencia de derechos, otras llamadas incluyen el reporte de no derechohabiencia y el reporte RECI.
AforeCon una CURP se consulta si se cuenta con Afore así como su nombre y medios para ponerse en contacto.
HaciendaMediante un RFC únicamente verifica si este RFC es válido ante Hacienda. Atención: no devuelve ningún documento ni información personal. También es posible localizar el nombre fiscal de una persona física o moral con su RFC. Es posible validar que el nombre del contribuyente, su RFC y su código postal sean los mismos que los que tiene Hacienda. Así como localizar un RFC de una persona física dado su nombre completo y fecha de nacimiento.
TelefoníaCon un número de teléfono de 10 dígitos devolverá qué tipo de teléfono es (fijo o móvil), la compañía telefónica, la lada y la ciudad de registro

🚀 Consumo de API ​

🌎 Códigos de respuesta ​

Códigos de respuesta que devuelven los endpoints de consumo:

CódigoDescripciónDescuenta un uso de API
200✅ Todo estuvo bien, se devuelve contenido de la consultaSi
409❌ Pre validación: error con alguno de los datos ingresadosNo
404❌ No se encontró el servicioNo
429❌ Limite alcanzado, se acabaron los usos de la APINo
400❌ Validación de servicio externo: error con los datos ingresadosNo
422❌ Error conocido de un servicio externoNo
500❌ Error desconocido de un servicio externoNo

Estructura de las respuestas de error ​

Los errores 4xx y 5xx devuelven un JSON con tres campos: message (mensaje corto de la causa), description (explicación de por qué ocurrió) y errorCode (identificador estable en inglés):

json
{
  "message": "Cuenta no válida, favor de verificar su clave de consulta",
  "description": "La clave no corresponde a una cuenta activa: puede ser incorrecta, o la cuenta está bloqueada, sin confirmar o desactivada.",
  "errorCode": "unauthorized_user"
}

El error de validación (409) agrega la llave errors, con un elemento {field, error} por cada campo inválido:

json
{
  "message": "Datos inválidos, favor de verificar la información ingresada",
  "description": "Alguno de los datos que enviaste tiene un formato incorrecto o falta información obligatoria.",
  "errorCode": "bad_request",
  "errors": [
    {
      "field": "body.nss.curp",
      "error": "String should have at least 18 characters"
    }
  ]
}

Los endpoints de consumo nunca devuelven un campo detail.

En los productos síncronos description y errorCode pueden llegar vacíos

En las consultas síncronas de Seguro Social, Hacienda, Afore y Telefonía, la mayoría de los errores propios de la consulta traen description y errorCode como cadena vacía (""); los traen llenos la validación (409) y los errores de acceso comunes a toda la API, como la clave de consulta, el saldo o el límite de peticiones. El detalle del objeto de tres campos está en el formato de las respuestas de error.

📈 Ver tu consumo ​

🚦 Saber si el servicio está caído ​

🏥 Servicio del Seguro Social ​

💰 Servicio de Afore ​

🏢 Servicios de Hacienda ​

📞 Servicio de Telefonía ​

Hecho por Consulta Única