UPS - Validar Dirección

Descripción

Este modulo valida una dirección de envío utilizando el servicio Address Validation (XAV) de UPS. Recibe la dirección, ciudad, estado, código postal y pais. Realiza una petición POST al endpoint /api/addressvalidation/v1/1 con el formato XAVRequest. Retorna si la dirección es valida, la dirección candidata corregida, la clasificación (Residential o Commercial) y si no se encontraron candidatos.

Configuración

Parámetro	Tipo	Requerido	Descripción
credentials_id	credentials	Si	Credencial UPS (provider: ups)
street	text	Si	Línea principal de dirección
city	text	Si	Ciudad
state	text	Si	Estado o provincia
postal_code	text	Si	Código postal
country_code	text	Si	Código ISO del pais (por defecto: US)

Credenciales

Se requiere una credencial de tipo ups con los siguientes campos:

client_id: Client ID de la API de UPS
client_secret: Client Secret de la API de UPS

Salida

{
  "success": true,
  "valid": true,
  "candidate": {
    "AddressLine": ["123 MAIN ST"],
    "PoliticalDivision2": "MEMPHIS",
    "PoliticalDivision1": "TN",
    "PostcodePrimaryLow": "38118",
    "CountryCode": "US"
  },
  "classification": "Residential",
  "is_residential": true,
  "no_candidates": false,
  "message": "Direccion validada: Residential"
}

Ejemplo de Uso

Caso básico

{
  "credentials_id": "mi_credencial_ups",
  "street": "123 Main Street",
  "city": "Memphis",
  "state": "TN",
  "postal_code": "38118",
  "country_code": "US"
}

API Utilizada

Endpoint: POST /api/addressvalidation/v1/1
Base: UPS API (via helper _upsHelper)
Documentación: https://developer.ups.com/api/reference

Notas

El formato de la petición usa XAVRequest con AddressKeyFormat
Los nombres de campos internos UPS usan PoliticalDivision1 (estado) y PoliticalDivision2 (ciudad)
El campo no_candidates indica si UPS no pudo encontrar ninguna dirección candidata
La clasificación puede ser “Residential” o “Commercial”
Se toma el primer candidato de la respuesta