---
title: "Validar un código postal y listar sus colonias"
method: GET
path: "/postal-codes/{postal_code}"
tags: ["addresses"]
---

# Validar un código postal y listar sus colonias

`GET /postal-codes/{postal_code}`

## Request

- Base URL: `https://api.enviadores.com.mx/api/v1`
- URL: `https://api.enviadores.com.mx/api/v1/postal-codes/{postal_code}`
- Auth: HTTP bearer

Resuelve un código postal mexicano (catálogo SEPOMEX) en su estado, municipio y el conjunto de colonias/asentamientos — justo lo que se necesita para llenar una dirección antes de `POST /senders` o `POST /shipments`. Requiere scope `addresses:read`. Datos de referencia públicos y de solo lectura: responde IDÉNTICo con llaves `ek_live_` y `ek_test_` (no hay nada que simular). `422` si el CP no son 5 dígitos; `404` si no existe en el catálogo; `200` con los datos si es válido.

## Path parameters

- `postal_code` string, required

## Response `200`

El código postal existe.

- object
  - `success` unknown, required
  - `data` object, required: Resultado de `GET /postal-codes/{postal_code}`. Datos de referencia SEPOMEX (públicos, solo lectura).
    - `postal_code` string, required: El CP consultado (5 dígitos).
    - `state` string, nullable, required: Estado (`d_estado`). Úsalo como `state`.
    - `state_code` string, nullable, required: Código de estado normalizado (mismo esquema que `state_code` del directorio; p. ej. `DF`, `JAL`, `NL`).
    - `municipality` string, nullable, required: Municipio/alcaldía (`d_mnpio`). Suele ser el mejor valor para `city`.
    - `city` string, nullable, required: Ciudad (`d_ciudad`) cuando SEPOMEX la distingue del municipio; `null` en la mayoría de los CP.
    - `colonias` Colonia[], required: Asentamientos únicos del CP, ordenados por nombre. Un CP mapea a un estado/municipio pero a muchas colonias.
      - `name` string, required: Nombre del asentamiento (`d_asenta` de SEPOMEX). Úsalo como `colonia`/`neighborhood`.
      - `settlement_type` string, nullable, required: Tipo de asentamiento SEPOMEX: `Colonia`, `Fraccionamiento`, `Pueblo`, `Barrio`, etc.
  - `requestId` string, required: Correlación de logs; también en el header `X-Request-Id`.

## Other responses

- `401`: `UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).
- `403`: `INSUFFICIENT_SCOPE` — a la llave le falta el scope requerido · `PDV_NOT_ALLOWED` — violación del carril X-PDV-ID. Nota de orden: el limitador por llave corre ANTES del gate de scope, así que una petición con scope incorrecto y el bucket agotado responde `429 RATE_LIMITED` (el 429 tiene precedencia sobre este 403).
- `404`: `NOT_FOUND` — el código postal (bien formado) no está en el catálogo SEPOMEX.
- `422`: `VALIDATION_ERROR` — el código postal debe ser exactamente 5 dígitos.
- `429`: `RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.
- `500`: `SERVER_ERROR` — falla interna (p. ej. lectura de base de datos). Es transitoria; reintenta con backoff.

---

[API](https://skmtc.dev/enviadores/apis/enviadores-public-api.md) · [All operations](https://skmtc.dev/enviadores/apis/enviadores-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/enviadores/apis/enviadores-public-api/revisions/3633f08c889c?raw)