# Codigos Postales MX

> API REST de códigos postales de México. Consulta colonias, municipio, estado y ciudad a partir de un código postal, o encuentra el código postal a partir del nombre de una colonia. Ideal para validar direcciones, autocompletar formularios de envío o facturación, y evitar errores de captura en checko

API publicada en idoo.dev por Jonathan Fonseca (categoría: Datos geográficos).
Página: https://idoo.dev/apis/codigos-postales-mx

## Cómo llamar a la API

- **URL:** `https://idoo.dev/v1/codigos-postales-mx/{ruta}` — cualquier método HTTP; query, body y `Content-Type` llegan intactos a la API.
- **Autenticación:** header `Authorization: Bearer {api_key}` (o `X-API-KEY: {api_key}`). Una sola key de idoo.dev sirve para todas las APIs a las que estés suscrito.
- **Ambiente según la key:** `idoo_sk_test_...` → sandbox (gratis, no descuenta cuota); `idoo_sk_live_...` → producción.
- **Seguridad:** guarda la key en una variable de entorno (p. ej. `IDOO_API_KEY`) y llama a la API solo desde el servidor; nunca la expongas en el frontend ni la subas al repositorio.
- **Obtener acceso:** inicia sesión en https://idoo.dev/login, suscríbete a la API en https://idoo.dev/apis/codigos-postales-mx y crea tu key en https://idoo.dev/panel/apikeys.

## Respuestas

La respuesta de la API se devuelve **tal cual** (status, headers y body del proveedor). Solo los errores del propio gateway usan este sobre JSON:

```json
{"valid": false, "status": 402, "message": "…", "data": null, "timestamp": "2026-01-01 12:00:00"}
```

| Status | Causa | Qué hacer |
|---|---|---|
| 401 | No se envió la key | Agrega el header `Authorization: Bearer {api_key}` |
| 403 | Key inválida o revocada, o sin suscripción activa a la API | Revisa la key y la suscripción en el panel |
| 402 | Cuota mensual agotada (`data.periodo_reinicia` indica cuándo se renueva) | Mejora el plan o compra un paquete; no reintentes |
| 404 | La API no existe o no está publicada | Revisa el slug de la URL |
| 429 | Rate limit por minuto excedido | Espera los segundos del header `Retry-After` y reintenta |
| 502 | La API no respondió o no tiene URL para tu ambiente | Reintenta con backoff; si persiste, contacta al creador |

Headers útiles en cada respuesta: `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-Idoo-Cuota-Restante` (si el plan tiene cuota).
Solo descuentan cuota las llamadas de producción que la API responde con 2xx/3xx; los errores no se cobran.

## Planes

| Plan | Precio (MXN) | Llamadas/mes | Peticiones/min |
|---|---|---|---|
| Gratuito | Gratis | 6,000 | 60 |
| Pro | $199.00/mes | 20,000 | 60 |
| Ultra | $299.00/mes | 40,000 | 60 |
| Ultra + | $599.00/mes | 100,000 | 180 |
| Ilimitado | $1,999.00/mes | Ilimitadas | 600 |

## Documentación

## Códigos Postales — API

API de consulta de códigos postales de México (catálogo de asentamientos,
municipios y estados). Publicada en el marketplace de [idoo.dev](https://idoo.dev):
toda la autenticación, planes, cuotas y límites de uso los gestiona el gateway —
solo necesitas tu API key de idoo.dev, no hay ningún token adicional que manejar.

### Autenticación

Usa tu API key de idoo.dev contra la URL del gateway:

```
Authorization: Bearer {tu_api_key}
```

```
GET https://api.idoo.dev/v1/{slug-de-esta-api}/...
```

### Endpoints

Todos son `GET` y aceptan los parámetros como query string.

#### Buscar por código postal

`GET /index?codigo=CODIGO_POSTAL`

```bash
curl "https://api.idoo.dev/v1/codigos-postales-mx/index?codigo=44250" \
  -H "Authorization: Bearer {tu_api_key}"
```

#### Buscar por asentamiento y municipio

`GET /index?colonia=ASENTAMIENTO&municipio=MUNICIPIO`

```bash
curl "https://api.idoo.dev/v1/codigos-postales-mx/index?colonia=Huentitan&municipio=Guadalajara" \
  -H "Authorization: Bearer {tu_api_key}"
```

#### Buscar por asentamiento

`GET /index?colonia=ASENTAMIENTO`

```bash
curl "https://api.idoo.dev/v1/codigos-postales-mx/index?colonia=Huentitan" \
  -H "Authorization: Bearer {tu_api_key}"
```

### Respuesta

```json
{
    "valid": true,
    "status": 200,
    "html": "",
    "data": [
        {
            "Codigo": "44250",
            "Asentamiento": "Huentitán El Bajo",
            "TipoAsentamiento": "Colonia",
            "Municipio": "Guadalajara",
            "Estado": "Jalisco",
            "Ciudad": "Guadalajara"
        }
    ]
}
```

### Códigos de error

| Status | Cuándo ocurre | Contenido de `data` |
|---|---|---|
| 400 | Falta el parámetro `codigo`, o falta `colonia` | Mensaje indicando los parámetros válidos |
| 404 | La búsqueda no encontró ningún resultado | Mensaje de "no se encontraron resultados" |
| 405 | Se usó un método distinto de `GET` | Mensaje de método no permitido |
| 401 | Firma del gateway inválida o ausente (no debería ocurrir consumiendo vía idoo.dev; solo si alguien intenta llamar al backend directo) | Mensaje de no autorizado |