Requisitos de formato de direcciones

Las direcciones se envían en varios lugares en la API de Fluz: verificación de identidad del usuario (KYC), registro de negocios (KYB), fuentes de fondos y emisión de tarjetas virtuales. Esta página define cómo formatear los campos de dirección para que sean aceptados, y la validación adicional que aplica específicamente a la emisión de tarjetas.

Dónde aplicaLos campos de dirección usan la misma estructura en toda la API. Las reglas de formato a continuación aplican en todos lados. Los requisitos para la emisión de tarjetas (solo EE. UU., sin apartados postales, validación de Smarty) aplican solo donde se indique.

Campos de dirección

Cada objeto de dirección usa los mismos campos estructurados. Dependiendo de la llamada, el objeto puede llamarse billingAddress, businessLegalAddress, o una dirección de propietario/individuo, pero los nombres de los campos son consistentes.

Campo	Requerido	Formato
`streetAddressLine1`	Sí	Dirección principal (número del edificio + calle). Debe ser una dirección real y entregable.
`streetAddressLine2`	No	Apartamento, suite, unidad o piso. Usa un designador secundario estándar (`Apt`, `Ste`, `Unit`, `Rm`, `Fl`, `#`).
`city`	Sí	Nombre de la ciudad. Debe ser la ciudad que USPS asocia con el código ZIP.
`state`	Sí	Código de estado de EE. UU. de dos letras (p. ej., `NY`) o el nombre completo del estado.
`postalCode`	Sí	Código ZIP de EE. UU. de 5 dígitos. Debe corresponder a la ciudad y el estado proporcionados.
`country`	Sí	Nombre del país. Las restricciones varían según el contexto; consulta País por contexto.

Reglas de formato

Estas aplican a todas las direcciones que envíes, en cualquier sección de la API:

Usa los campos estructurados. Coloca la calle en streetAddressLine1 y la unidad en streetAddressLine2; no combines todo en una sola línea.
Usa una dirección real y entregable. El número del edificio debe existir en la calle indicada. Una calle real no es suficiente: 500 Main St es inválida si el número más alto en Main St es 480.
Mantén consistentes ciudad, estado y ZIP. El código ZIP debe ser el asignado a esa ciudad y estado. Un ZIP no coincidente es la causa más común de rechazo de una dirección.
Usa abreviaturas de USPS. Sufijos estándar (St, Ave, Blvd, Dr, Ln, Rd, Ct, Pkwy) y direccionales (N, S, E, W, NE, NW, SE, SW) coinciden con mayor fiabilidad.
Coloca la unidad / apartamento / suite en streetAddressLine2 usando un designador reconocido. Si USPS requiere una unidad secundaria para un edificio y no se proporciona, la dirección puede fallar la validación.
Envía un ZIP de 5 dígitos para direcciones de EE. UU. El ZIP+4 se agrega automáticamente durante la estandarización.

Requisitos adicionales para la emisión de tarjetas

Las direcciones de facturación de tarjetas virtuales se validan y estandarizan a través de Smarty (USPS Delivery Point Validation) antes de guardarlas. Esto aplica a Agregar dirección de tarjeta virtual, Crear tarjeta virtual y emisión de tarjetas para usuarios autorizados.

Solo direcciones de EE. UU. Establece country en United States.
Sin apartados postales (PO boxes). El emisor de la tarjeta no acepta direcciones de apartado postal, incluso si USPS las considera entregables.
Debe estar verificada por Smarty. Si la dirección no puede coincidir con un punto de entrega real y entregable en EE. UU., la solicitud se rechaza con VC-0025 y no se guarda ninguna dirección. Reintentar con los mismos valores fallará de nuevo: la dirección en sí debe cambiar.

Las direcciones de facturación de tarjetas bancarias (Agregar fuentes de fondos) comparten la misma estructura de campos y deben coincidir con la dirección registrada con el emisor de la tarjeta. Una dirección de facturación no coincidente puede causar que la tarjeta sea rechazada durante la verificación de dirección (AVS).

País por contexto

No todas las direcciones son solo de EE. UU. Usa la restricción correcta para la llamada que estás realizando:

Contexto	Restricción de país
Dirección de facturación de tarjeta virtual	Solo EE. UU. (`United States`).
Dirección de facturación de tarjeta bancaria	Debe coincidir con los registros del emisor de la tarjeta (generalmente EE. UU.).
Registro de negocios (KYB) `businessLegalAddress`	Se aceptan direcciones internacionales (nombre del país, ISO 3166). Algunos países están restringidos para KYB (p. ej., Rusia, Irán).
Verificación KYC de usuario	La dirección residencial del usuario.

Por qué se rechaza una dirección (`VC-0025`)

Para la emisión de tarjetas, una dirección falla cuando Smarty no puede confirmarla como un punto de entrega de EE. UU. entregable. Las razones más comunes:

Motivo	Qué significa
Incongruencia entre ciudad / estado / ZIP	El código ZIP no pertenece a la ciudad o estado proporcionados.
Número de edificio inválido	La calle existe, pero el número principal (del edificio) no existe en ella.
Dirección no encontrada	La calle o la dirección no está presente en los datos de USPS.
Unidad secundaria faltante / inválida	USPS requiere un número de apartamento o suite para este edificio y falta o es incorrecto.
Punto no entregable	La dirección corresponde a un punto de entrega desocupado u otro no entregable.
Apartado postal o dirección fuera de EE. UU.	Rechazada por el emisor de la tarjeta (apartados postales) o no compatible (fuera de EE. UU.).

Ejemplos prácticos

Ejemplo 1 — Incongruencia entre ciudad / ZIP

2581 Oakwood Avenue, New York, NY 10605

Rechazada (VC-0025). El código ZIP 10605 corresponde a White Plains, NY (Condado de Westchester), no a la ciudad de Nueva York; por lo tanto, la ciudad y el ZIP no coinciden. Además, 2581 Oakwood Avenue no es un punto de entrega confirmado en ese ZIP. Smarty no devuelve una coincidencia válida, por lo que la dirección no se guarda. Solución: envía el ZIP que USPS asigna a la ciudad (o la ciudad que coincide con el ZIP), y un número de edificio que exista en la calle.

Ejemplo 2 — Número de edificio inválido

896 S State St, Dover, DE 19904

Rechazada (VC-0025). S State St existe en Dover, DE, pero 896 no es un punto de entrega confirmado por USPS para esa calle y ZIP. Debido a que el número de edificio específico no puede validarse, Smarty no devuelve una coincidencia entregable. Solución: confirma el número exacto del edificio y el ZIP que cubre esa cuadra de la calle.

Un envío válido

{
  "billingAddress": {
    "streetAddressLine1": "1600 Amphitheatre Pkwy",
    "streetAddressLine2": "",
    "country": "United States",
    "city": "Mountain View",
    "state": "CA",
    "postalCode": "94043"
  }
}

Guardado y normalizado (ciudad, estado y código postal almacenados en mayúsculas; ZIP+4 agregado):

{
  "streetAddressLine1": "1600 Amphitheatre Pkwy",
  "streetAddressLine2": null,
  "country": "United States",
  "city": "MOUNTAIN VIEW",
  "state": "CA",
  "postalCode": "94043"
}

Manejo de `VC-0025` en tu integración

Recopila la dirección en campos estructurados en lugar de un solo campo de texto libre, para poder solicitar la parte específica que necesita corrección.
No reintentes a ciegas. La misma dirección seguirá devolviendo VC-0025. Muestra el error y pide al usuario que corrija la dirección.
Valida antes de enviar (opcional). Ejecutar un autocompletado o verificación de dirección en tu propia interfaz reduce intentos fallidos.
Nada se guarda en caso de error, por lo que no hay limpieza antes de reintentar con valores corregidos.

Referencia de errores

Error	Código	Mensaje
`INVALID_BILLING_ADDRESS`	`VC-0025`	No se pudo verificar la dirección de facturación. Revisa la calle, ciudad, estado y código ZIP e inténtalo nuevamente.

Consulta Códigos de error de tarjeta virtual para la lista completa.

Próximos pasos

Direcciones de prueba

Direcciones buenas y malas conocidas para ejercitar cada resultado de validación en staging.

Códigos de error generales de la API

Dónde encajan los errores de dirección dentro del espacio de nombres más amplio de códigos de error.

¿Quieres saber más? Contáctanos en partnerships@fluz.app. Habla con nuestros expertos para más información o para solicitar una demo.

Desarrolladores

Recetas

Requisitos de formato de direcciones

Campos de dirección

Reglas de formato

Requisitos adicionales para la emisión de tarjetas

País por contexto

Por qué se rechaza una dirección (`VC-0025`)

Ejemplos prácticos

Ejemplo 1 — Incongruencia entre ciudad / ZIP

Ejemplo 2 — Número de edificio inválido

Un envío válido

Manejo de `VC-0025` en tu integración

Referencia de errores

Próximos pasos

Direcciones de prueba

Códigos de error generales de la API

​Campos de dirección

​Reglas de formato

​Requisitos adicionales para la emisión de tarjetas

​País por contexto

​Por qué se rechaza una dirección (VC-0025)

​Ejemplos prácticos

​Ejemplo 1 — Incongruencia entre ciudad / ZIP

​Ejemplo 2 — Número de edificio inválido

​Un envío válido

​Manejo de VC-0025 en tu integración

​Referencia de errores

​Próximos pasos

Direcciones de prueba

Códigos de error generales de la API

Campos de dirección

Reglas de formato

Requisitos adicionales para la emisión de tarjetas

País por contexto

Por qué se rechaza una dirección (`VC-0025`)

Ejemplos prácticos

Ejemplo 1 — Incongruencia entre ciudad / ZIP

Ejemplo 2 — Número de edificio inválido

Un envío válido

Manejo de `VC-0025` en tu integración

Referencia de errores

Próximos pasos