> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluz.app/llms.txt > Use this file to discover all available pages before exploring further. # 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 aplica** Los 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](#country-by-context). | ## Reglas de formato Estas aplican a **todas** las direcciones que envíes, en cualquier sección de la API: 1. **Usa los campos estructurados.** Coloca la calle en `streetAddressLine1` y la unidad en `streetAddressLine2`; no combines todo en una sola línea. 2. **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`. 3. **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. 4. **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. 5. **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. 6. **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](https://www.smarty.com/) (USPS Delivery Point Validation) antes de guardarlas. Esto aplica a [Agregar dirección de tarjeta virtual](/features/add-billing-address), [Crear tarjeta virtual](/features/create-card) y [emisión de tarjetas para usuarios autorizados](/features/create-virtual-card-for-authorized-user). * **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](/features/add-bank-card)) 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 ```text theme={null} 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 ```text theme={null} 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 ```json theme={null} { "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): ```json theme={null} { "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](/features/virtual-card-error-codes) para la lista completa. ## Próximos pasos Direcciones buenas y malas conocidas para ejercitar cada resultado de validación en staging. 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](mailto:partnerships@fluz.app). Habla con nuestros expertos para más información o para solicitar una demo.