UPS - Validar Direccion

Descripcion

Este modulo valida una direccion de envio utilizando el servicio Address Validation (XAV) de UPS. Recibe la direccion, ciudad, estado, codigo postal y pais. Realiza una peticion POST al endpoint /api/addressvalidation/v1/1 con el formato XAVRequest. Retorna si la direccion es valida, la direccion candidata corregida, la clasificacion (Residential o Commercial) y si no se encontraron candidatos.

Configuracion

Parametro	Tipo	Requerido	Descripcion
credentials_id	credentials	Si	Credencial UPS (provider: ups)
street	text	Si	Linea principal de direccion
city	text	Si	Ciudad
state	text	Si	Estado o provincia
postal_code	text	Si	Codigo postal
country_code	text	Si	Codigo 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 basico

{
  "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)
Documentacion: https://developer.ups.com/api/reference

Notas

El formato de la peticion 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 direccion candidata
La clasificacion puede ser “Residential” o “Commercial”
Se toma el primer candidato de la respuesta