---
url: https://docs.consultaunica.mx/start.md
description: >-
  Cómo consumir la API REST de Consulta Única: autenticación con API Key en el
  header x-api-key, colección de Postman y servicios disponibles.
---

# 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](https://developer.mozilla.org/es/docs/Web/HTTP/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](/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:

| Variable | Valor por defecto | Para qué sirve |
|---|---|---|
| `baseUrl` | `https://api.consultaunica.mx` | URL base de la API |
| `apiKey` | *(vacío)* | Tu clave de consulta |

Incluye los servicios del [listado de servicios](/services/): 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:

* Mediante correo electrónico: [info@consultaunica.mx](mailto:info@consultaunica.mx?subject=Acerca%20de%20la%20Documentaci%C3%B3n%20de%20la%20API)
* WhatsApp: <https://api.whatsapp.com/send?phone=528342575836&text=Hola%2C%20quisiera%20preguntar%20acerca%20de...>

## 🙌🏼 Servicios disponibles

|Servicio|Utilidad|
|-|-|
|Seguro Social|Mediante 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.|
|Afore|Con una CURP se consulta si se cuenta con Afore así como su nombre y medios para ponerse en contacto.|
|Hacienda|Mediante 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ía|Con 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ódigo|Descripción|Descuenta un uso de API|
|-|-|-|
|`200`|✅ Todo estuvo bien, se devuelve contenido de la consulta|Si|
|`409`|❌ Pre validación: error con alguno de los datos ingresados|No|
|`404`|❌ No se encontró el servicio|No|
|`429`|❌ Limite alcanzado, se acabaron los usos de la API|No|
|`400`|❌ Validación de servicio externo: error con los datos ingresados|No|
|`422`|❌ Error conocido de un servicio externo|No|
|`500`|❌ Error desconocido de un servicio externo|No|

#### 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`.

::: tip 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](../services/imss/sc_premium.md#formato-de-las-respuestas-de-error).
:::

### 📈 Ver tu consumo

* [API para ver tu consumo aquí](../usage/index.md)

### 🚦 Saber si el servicio está caído

* [Estado del servicio e incidentes](../usage/status.md) — tasas de éxito por tipo de consulta e incidentes activos. No consume créditos y funciona aunque su saldo esté agotado.

### 🏥 Servicio del Seguro Social

* [⭐️ Reporte detallado de Semanas Cotizadas (asíncrono con webhook)](../services/imss/sc_premium.md)
* [NSS rápido](../services/imss/nss_fast.md)
* [Vigencia de derechos al correo](../services/imss/vd_email.md)
* [NSS al correo](../services/imss/nss_regular.md)
* [Constancia de no derechohabiencia](../services/imss/no_dh.md)
* [Solo validar vigencia de derechos](../services/imss/vd_validity.md)
* [Reporte personalizado de cotización, RECI](../services/imss/reci.md)

### 💰 Servicio de Afore

* [Obtener detalles de Afore](../services/afore/get_only_details.md)

### 🏢 Servicios de Hacienda

* [Validación de RFC](../services/sat/rfc_validation.md)
* [Búsqueda de RFC](../services/sat/rfc_search.md)
* [Validación de contribuyente](../services/sat/tax_payer_validation.md)
* [Búsqueda de contribuyente](../services/sat/tax_payer_search.md)

### 📞 Servicio de Telefonía

* [Consulta de teléfono](../services/ifetel.md)
