Validación de direcciones

El Validación de dirección el servicio verifica la dirección de entrega de cada tarjeta antes de la producción. Su objetivo es simple: reducir el número de tarjetas devueltas por una dirección no entregable.

• Dirección válida → la tarjeta se produce y se envía.
• Dirección inválida → el pedido de la tarjeta se rechaza, y se te notifica para que puedas corregir la dirección y volver a pedirla.

La validación se realiza automáticamente durante el flujo del pedido. No se requiere ninguna llamada adicional a la API desde el backend del emisor.

Cómo funciona

1. El backend del emisor envía un pedido de tarjeta, incluida la dirección de entrega del usuario final.
2. D1 confirma el pedido (HTTP 202); la validación de la dirección se realiza después.
3. D1 valida las entradas (formato, longitud, caracteres permitidos).
4. D1 envía la dirección al servicio de validación
5. D1 evalúa la respuesta según los umbrales de la configuración del emisor.
6. Resultado:

   1. Válida → la tarjeta pasa a producción; se envía una notificación.
   2. Inválida → la tarjeta se rechaza; se envía una notificación con el motivo (y opcionalmente una dirección corregida sugerida).
7. El emisor vuelve a pedir la tarjeta con una dirección corregida si es necesario.

Cómo elegir el modo de validación

Se selecciona un modo durante la incorporación. Se aplica a todos los pedidos de tarjetas.

Modo	Qué sucede	Cuándo usarlo
deshabilitado	Sin validación. Todas las tarjetas pasan a producción.	No quieres el servicio.
estadísticas	La validación se realiza, pero la tarjeta es siempre producida.	Para medir el impacto antes de activar la aplicación obligatoria.
habilitado	La validación se realiza. Las direcciones inválidas son rechazadas.	Uso estándar en producción.
premium	Igual que habilitado, además de una dirección corregida sugerida se devuelve cuando está disponible.	Quieres ayuda para corregir las direcciones rechazadas.

Qué necesitas configurar

Solo unos pocos parámetros son importantes para ti:

Parámetro	Descripción	Recomendado
addressValidation	Modo: deshabilitado / estadísticas / habilitado / premium	habilitado
addressValidationMatchScoreThreshold	Puntuación mínima de calidad (0–100). Por debajo de esto, la dirección se rechaza.	95
addressValidationOnReorder	Si es true, la dirección se vuelve a validar cuando vuelves a pedir una tarjeta previamente rechazada. Si es false, el nuevo pedido omite la validación.	false
addressValidationOutageFallback	Qué hacer si el servicio de validación no está disponible temporalmente: producir (aceptar la tarjeta) o rechazar (rechazar la tarjeta).	producir

Todos los demás parámetros técnicos (proveedor, estrategia de reintento, umbrales del código postal, etc.) se gestionan internamente y no requieren ninguna acción de tu parte.

Notificaciones que recibirás

Dirección válida – la tarjeta pasa a producción

{
  "operation": "PRODUCE",
  "status": "PENDING",
  "details": {
    "status": "CARD_PROD_REQUESTED",
    "addressValidation": {
      "status": "válido",
      "matchScore": 95
    }
  }
}

Dirección inválida – tarjeta rechazada

{
  "operation": "PRODUCE",
  "status": "FAILED",
  "errorCode": "INVALID_ADDRESS",
  "details": {
    "status": "DATA_EXCEPTION",
    "addressValidation": {
      "status": "inválido",
      "matchScore": 55
    }
  }
}

Dirección inválida – con una corrección sugerida (modo premium)

{
  "operation": "PRODUCE",
  "status": "FAILED",
  "errorCode": "INVALID_ADDRESS",
  "details": {
    "status": "DATA_EXCEPTION",
    "addressValidation": {
      "status": "inválido",
      "matchScore": 55,
      "suggestedAddress": {
        "line1": "221B Baker Street",
        "line2": "Flat 2",
        "city": "London",
        "postalCode": "NW1 6XE",
        "countryCode": "GB"
      }
    }
  }
}

¿Qué sucede cuando se rechaza una tarjeta?

1. Recibes una notificación PRODUCE / FAILED con errorCode = INVALID_ADDRESS.
2. En premium modo, se puede sugerir una dirección corregida.
3. Tú corriges la dirección y vuelves a pedir la tarjeta.

Disponibilidad y fiabilidad del servicio

• El validador se llama en tiempo real para cada pedido de tarjeta.
• Si el proveedor no está disponible temporalmente, el servicio reintenta automáticamente.
• Después de todos los reintentos, el plan de contingencia (producir o rechazar) se aplica.
• La cobertura de países y la precisión dependen de los datos de referencia de Loqate — consulta cobertura de países de Loqate.