Direcciones y validación

Direcciones a nivel colonia, validación contra catálogos oficiales y búsqueda de códigos postales.

Las direcciones mexicanas se modelan a nivel colonia, que es la granularidad que usan las paqueterías. SendIt valida contra el catálogo oficial de SEPOMEX y te da autocompletado de colonias para tus formularios.

Guarda direcciones reutilizables

Parámetros del cuerpo

curl -X POST https://api.sendit.mx/v1/addresses \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contactName": "María López",
    "contactPhone": "+5213312345678",
    "contactEmail": "maria@ejemplo.mx",
    "company": "Tienda MX",
    "street": "Av. López Mateos",
    "exteriorNumber": "45",
    "interiorNumber": "B-2",
    "neighborhood": "Jardines del Sol",
    "city": "Zapopan",
    "state": "JAL",
    "postalCode": "45050",
    "country": "MX",
    "reference": "Portón negro, entre Av. Patria y Moctezuma",
    "isResidential": true
  }'

{
  "success": true,
  "data": {
    "id": "clx_direccion_origen",
    "contactName": "María López",
    "contactPhone": "+5213312345678",
    "street": "Av. López Mateos",
    "exteriorNumber": "45",
    "neighborhood": "Jardines del Sol",
    "city": "Zapopan",
    "state": "JAL",
    "postalCode": "45050",
    "country": "MX",
    "isResidential": true,
    "isDefault": false,
    "isVerified": false,
    "createdAt": "2026-07-18T10:00:00.000Z"
  }
}

Usa el id devuelto como fromAddressId / toAddressId al crear envíos. Borrar una dirección nunca afecta envíos históricos: cada envío congela su propia copia.

Valida una dirección

La verificación compara la dirección contra el catálogo SEPOMEX y devuelve validez, confianza y la versión normalizada:

curl -X POST https://api.sendit.mx/v1/address-verifications \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "street": "Av. Insurgentes Sur",
      "exteriorNumber": "1235",
      "neighborhood": "Insurgentes Mixcoac",
      "postalCode": "03920",
      "city": "Ciudad de México",
      "state": "CDMX",
      "country": "MX"
    },
    "provider": "SEPOMEX"
  }'

{
  "success": true,
  "data": {
    "id": "av_1a2b3c4d5e",
    "isValid": true,
    "confidence": 0.95,
    "normalizedAddress": {
      "postalCode": "03920",
      "neighborhood": "Insurgentes Mixcoac",
      "city": "Ciudad de México",
      "state": "Ciudad de México",
      "country": "MX"
    },
    "errors": [],
    "provider": "SEPOMEX",
    "createdAt": "2026-07-17T12:00:00.000Z"
  }
}

Interpreta la confianza

Cuando varias colonias comparten el código postal, suggestions[] trae las alternativas para que el usuario elija.

La validación es consultiva y no bloquea la creación de envíos. Cada verificación queda registrada en GET /v1/address-verifications. Ese registro te sirve como evidencia ante paquetes no entregables.

Para muchas direcciones, valida hasta 100 por llamada con POST /v1/bulk/addresses/validate. Ver lotes.

Códigos postales y colonias

Cuatro endpoints alimentados por el catálogo SEPOMEX, ideales para autocompletar formularios:

Consulta un código postal

GET /v1/postal-codes/03100

{
  "success": true,
  "data": {
    "postalCode": "03100",
    "country": "MX",
    "state": { "code": "MX-CMX", "name": "Ciudad de México" },
    "municipality": "Benito Juárez",
    "city": "Ciudad de México",
    "colonies": [
      { "name": "Del Valle Centro", "type": "Colonia", "zone": "Urbano" },
      { "name": "Del Valle Norte", "type": "Colonia", "zone": "Urbano" },
      { "name": "Del Valle Sur", "type": "Colonia", "zone": "Urbano" }
    ]
  }
}

Con una sola llamada pre-llenas ciudad, estado y el dropdown de colonias. Un código inexistente devuelve 404 RESOURCE_NOT_FOUND.

Busca colonias (autocompletado)

GET /v1/postal-codes/search?q=Del+Valle&stateCode=MX-CMX&limit=10

Coincidencia parcial por nombre de colonia; filtra opcionalmente por estado. Máximo 50 resultados.

Lista los estados

GET /v1/postal-codes/states

Devuelve los 32 estados con su código ISO 3166-2 (MX-JAL, MX-NLE, MX-CMX). Son los mismos códigos que acepta el resto del API.