> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subir un archivo

> Sube a VelaFi documentos de identidad para KYC/KYB o archivos de facturas. Admite hasta 5 archivos por solicitud en formato JPG, PNG, JPEG o PDF.

Usa el endpoint **POST** `/v2/base/file/upload` para subir documentos a VelaFi. Este endpoint admite archivos de verificación de identidad KYC/KYB, así como documentos de facturas para cuentas de comercio. La solicitud debe enviarse como `multipart/form-data`. Puedes subir hasta cinco archivos en una sola solicitud; cada archivo debe pesar entre 10 KB y 3 MB y estar en uno de los formatos admitidos. La respuesta devuelve una URL firmada temporal para cada archivo subido, para que puedas verificar que la carga fue exitosa antes de hacer referencia al archivo en llamadas posteriores a la API.

> [!WARNING]
>
> Este endpoint requiere autorización. Incluye el encabezado `X-BH-TOKEN` en cada solicitud. Las solicitudes sin un token válido serán rechazadas.

## Solicitud

```text theme={null}
POST /v2/base/file/upload
```

### Encabezados

| Encabezado | Valor | Obligatorio |
| - | - | - |
| `X-BH-TOKEN` | Tu token de `GET /v2/token/generate` | ✓ |
| `Content-Type` | `multipart/form-data` | ✓ |

### Parámetros del cuerpo

**businessType** `string` *required*

El tipo de documento de negocio que se sube. Actualmente su valor fijo es `FIAT_ACCOUNT`.

**files** `file` *required*

Uno o más archivos para subir. Máximo **5 archivos** por solicitud. Cada archivo debe pesar entre **10 KB y 3 MB**. Formatos admitidos: `jpg`, `jpeg`, `png`, `pdf`.

## Campos de la respuesta

**code** `number`

Código de estado de estilo HTTP. `200` indica éxito.

**msg** `string`

Mensaje de estado legible, p. ej. `"SUCCESS"`.

**data** `array`

Arreglo de objetos de archivos subidos, uno por archivo.

**data\[]**

**fileName** `string`

Nombre original del archivo tal como se subió (p. ej., `"id-front.jpg"`).

**fileType** `string`

Extensión del documento subido (p. ej., `"jpg"`, `"pdf"`).

**fileUrl** `string`

Ruta relativa de almacenamiento del archivo (p. ej., `"100001/00000000-0000-0000-0000-000000000001.jpg"`). Usa este valor cuando hagas referencia al archivo en llamadas posteriores a la API, por ejemplo en los campos de documentos (`govIdFrontUrl`, `govIdBackUrl`, `certificateOfIncorporationDocumentUrl`, `taxIdentificationDocumentUrl`) de una activación del canal `Pix - Woovi`.

**tempFileUrl** `string`

URL prefirmada temporal que puedes usar para verificar que el archivo se subió correctamente. Esta URL expira 30 minutos después de la carga y no debe almacenarse de forma permanente.

## Ejemplo

```bash cURL — single file theme={null}
curl --request POST \
  --url 'https://api.velafi.com/v2/base/file/upload' \
  --header 'X-BH-TOKEN: YOUR_TOKEN' \
  --header 'Content-Type: multipart/form-data' \
  --form 'businessType=FIAT_ACCOUNT' \
  --form 'files=@/path/to/id-front.jpg'
```

```bash cURL — multiple files theme={null}
curl --request POST \
  --url 'https://api.velafi.com/v2/base/file/upload' \
  --header 'X-BH-TOKEN: YOUR_TOKEN' \
  --header 'Content-Type: multipart/form-data' \
  --form 'businessType=FIAT_ACCOUNT' \
  --form 'files=@/path/to/id-front.jpg' \
  --form 'files=@/path/to/id-back.jpg'
```

### Respuesta

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "fileName": "id-front.jpg",
      "fileType": "jpg",
      "fileUrl": "100001/00000000-0000-0000-0000-000000000001.jpg",
      "tempFileUrl": "https://example-bucket.s3.amazonaws.com/00000000-0000-0000-0000-000000000001.jpg?X-Amz-Signature=..."
    }
  ]
}
```

> [!NOTE]
>
> Guarda el campo `fileUrl` de la respuesta: es la ruta relativa permanente a la que haces referencia en las solicitudes de envío de KYC/KYB. `tempFileUrl` es una URL firmada de corta duración, solo para verificación, y va a expirar.


## Related topics

- [Subir documentos de una orden](https://docs.velafi.com/es/api-reference/order/upload-invoice-documents-for-a-specific-order.md)
- [Activar la cuenta de un comercio empresa](https://docs.velafi.com/es/api-reference/merchant/activate-merchant-account-for-business.md)
- [Activar la cuenta de un comercio persona física](https://docs.velafi.com/es/api-reference/merchant/activate-merchant-account-for-individual.md)
- [Introducción](https://docs.velafi.com/es/docs/introduction.md)
- [Estados de las órdenes](https://docs.velafi.com/es/docs/order-statuses.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.