SEPOMEX1 tokenPOST

Código postal

Consulta toda la información de un código postal en SEPOMEX: asentamientos (colonias) que comparten el CP, delegación o municipio, ciudad y estado. Útil para autocompletar formularios de domicilio y validar direcciones en procesos de onboarding.

Endpoint

POSThttps://api.datosnonstop.com/v1/sepomex/codigo-postal

Parámetros

json

{
  "codigoPostal": "06700"
}

ParámetroTipoRequeridoDescripción

codigoPostalstringSíCódigo postal de 5 dígitos a consultar

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.datosnonstop.com/v1/sepomex/codigo-postal \
  -H "x-api-key: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"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": "6a3b865g4d8f1c5a9e27b041",
  "status": "found",
  "codigoPostal": "06700",
  "asentamientos": [
    {
      "asentamiento": "Roma Norte",
      "ciudad": "Ciudad de México",
      "claveDeOficina": "06000",
      "codigoPostal": "06700",
      "delegacionMunicipio": "Cuauhtémoc",
      "estado": "Ciudad de México",
      "tipoDeAsentamiento": "Colonia"
    }
  ]
}

Respuestas en error

JSON

400 Bad Request

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

Campos

Campos de entrada

CampoTipoDescripción

codigoPostalstringCadena numérica de 5 dígitos que identifica un código postal en el directorio de SEPOMEX.

Campos de respuesta

CampoTipoDescripción

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

statusstringResultado de la consulta del código postal en SEPOMEX. Ver catálogo Status.

codigoPostalstringCódigo postal consultado (5 dígitos).

messagestringDetalle del motivo cuando status es not_found. Solo está presente en respuestas not_found.

asentamientosarrayLista de asentamientos asociados al código postal. Un mismo CP puede tener varios asentamientos. Solo está presente cuando status es found.

asentamientos[].asentamientostringNombre del asentamiento (colonia, fraccionamiento, pueblo, etc.) registrado en SEPOMEX.

asentamientos[].ciudadstringCiudad a la que pertenece el asentamiento.

asentamientos[].claveDeOficinastringClave de la oficina postal que da servicio al asentamiento.

asentamientos[].codigoPostalstringCódigo postal asociado al asentamiento (5 dígitos).

asentamientos[].delegacionMunicipiostringDelegación o municipio donde se ubica el asentamiento.

asentamientos[].estadostringEntidad federativa donde se ubica el asentamiento.

asentamientos[].tipoDeAsentamientostringTipo de asentamiento registrado en SEPOMEX (Colonia, Fraccionamiento, Pueblo, etc.).

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 localizó el código postal en SEPOMEX. La respuesta incluye los asentamientos asociados.

not_foundEl código postal no fue encontrado en la base de SEPOMEX. La respuesta incluye el campo message con el detalle.

Histórico

Endpoint

GEThttps://api.datosnonstop.com/v1/sepomex/codigo-postal/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": "6a3b865g4d8f1c5a9e27b041",
  "status": "found",
  "codigoPostal": "06700",
  "asentamientos": [
    {
      "asentamiento": "Roma Norte",
      "ciudad": "Ciudad de México",
      "claveDeOficina": "06000",
      "codigoPostal": "06700",
      "delegacionMunicipio": "Cuauhtémoc",
      "estado": "Ciudad de México",
      "tipoDeAsentamiento": "Colonia"
    }
  ]
}

Respuestas en error

JSON

404 Not Found

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

Sandbox

Endpoint

POSThttps://sandbox.api.datosnonstop.com/v1/sepomex/codigo-postal

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

curl

curl -X POST https://sandbox.api.datosnonstop.com/v1/sepomex/codigo-postal \
  -H "x-api-key: tu_api_key_sandbox" \
  -H "Content-Type: application/json" \
  -d '{"codigoPostal":"06700"}'

Casos de prueba

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

CasoCódigo Postal

Caso exitoso — Encontrado06700

Caso exitoso — No encontrado06777

Sin tokens33333

Error interno44444

Unavailable service55555

Endpoint histórico

GEThttps://sandbox.api.datosnonstop.com/v1/sepomex/codigo-postal/historico/{id}

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

curl

curl https://sandbox.api.datosnonstop.com/v1/sepomex/codigo-postal/historico/6a3b865g4d8f1c5a9e27b041 \
  -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 6a3b865g4d8f1c5a9e27b041.

Casoid

Caso exitoso6a3b865g4d8f1c5a9e27b041

No encontrado0000000000000000ffffffff

Fuera de rango1111111111111111aaaaaaaa

Error interno2222222222222222bbbbbbbb

Empezar gratis →