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

# Subir documentos y comprobantes

> Declara los documentos justificativos de una entidad y sube los archivos (pruebas) que Localpayment revisa durante el proceso KYC/KYB.

Un documento contiene los datos declarados (tipo y número). Una prueba es el archivo que los respalda. Esta guía muestra cómo agregar documentos a una entidad, cargar sus archivos uno por uno, reemplazar o eliminar archivos y verificar que todos los documentos estén cubiertos para que la entidad esté lista para su revisión.

## Requisitos previos

* Una entidad creada con [Crear una entidad](https://docs.localpayment.com/es/docs/create-an-entity.md) y el `documentId` de cada uno de sus documentos.
* Archivos en formato JPG, PNG o PDF, de hasta 10 MB cada uno.

## Archivos por documento

Un documento contiene tantos archivos como necesites. Cada archivo tiene un tipo:

| proofType | Uso típico | Comportamiento en una nueva carga |
| - | - | - |
| FRONT | Anverso de un documento de identidad, o la imagen única de un documento. | Sustituye al archivo actual, que pasa a ser SUPERSEDED. |
| BACK | Reverso de un documento de identidad. | Sustituye al archivo actual, que pasa a ser SUPERSEDED. |
| SELFIE | Fotografía de la persona, subida al propio documento de identidad. | Sustituye al archivo actual, que pasa a ser SUPERSEDED. |
| DOCUMENT | Documento escaneado (PDF): comprobante de domicilio, estatutos sociales, registro fiscal. | Agrega un archivo, por ejemplo, cada página de un contrato. |
| OTHER | Cualquier otra evidencia. | Agrega un archivo. |

Un archivo APPROVED no se puede reemplazar (409 `PROOF_APPROVED`). Un archivo subido por error se puede eliminar con [Eliminar una prueba](https://docs.localpayment.com/es/reference/delete-proof.md) mientras no esté aprobado.

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'secondaryColor': '#31467c', 'tertiaryColor': '#ffffff', 'lineColor': '#0c1a29', 'textColor': '#0c1a29', 'edgeLabelBackground': '#ffffff', 'fontFamily': 'Manrope'}, 'fontFamily': 'Manrope', 'htmlLabels': false, 'flowchart': {'htmlLabels': false, 'wrappingWidth': 400, 'padding': 20}}}%%
flowchart TD
    A["Su backend<br/>POST /api/entity/v1/entities/{entityId}/documents<br/>PROOF_OF_ADDRESS"] --> B["Entities API<br/>201: documentId"]:::lp
    B --> C["Su backend<br/>POST /api/entity/v1/documents/{docId}/proofs?proofType=FRONT<br/>archivo multipart"]
    C --> D["Entities API<br/>201: id del comprobante, verificationStatus PENDING"]:::lp
    D --> E["Su backend<br/>POST /api/entity/v1/documents/{docId}/proofs?proofType=DOCUMENT<br/>PDF"]
    E --> F["Entities API<br/>201: id del comprobante"]:::lp
    F --> G["Su backend<br/>GET /api/entity/v1/entities/{entityId}/kyc-status"]
    G --> H["Entities API<br/>200: documentationStatus COMPLETE"]:::lp
    classDef default fill:#31467c,stroke:#0c1a29,stroke-width:1px,color:#ffffff,font-family:Manrope
    classDef lp fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef terminal fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef lbl fill:#0c1a29,stroke:#0c1a29,color:#ffffff,font-size:13px
```

## Paso a paso

1. Declara el documento si la entidad aún no lo tiene, con [Agregar un documento](https://docs.localpayment.com/es/reference/add-entity-document.md). Conserva su `documentId`.
2. Sube el archivo con [Subir una prueba](https://docs.localpayment.com/es/reference/upload-proof.md): `POST /api/entity/v1/documents/{docId}/proofs?proofType=FRONT` como `multipart/form-data`, con una parte llamada `file`.
3. Comprueba la carga: la respuesta 201 debe mostrar `sizeBytes` mayor que cero y el `mimeType` esperado.
4. Repite para el reverso (`proofType=BACK`) y la selfie (`proofType=SELFIE`) del documento de identidad, y para cada uno de los demás documentos.
5. Comprueba la cobertura con [Obtener el estado KYC](https://docs.localpayment.com/es/reference/get-kyc-status.md). `documentationStatus` debe ser `COMPLETE` para que la entidad esté lista para su revisión.

### Subir un archivo

```bash Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl -X POST "https://api.stage.localpayment.com/api/entity/v1/documents/2e16d844-4fa9-4295-9a21-83ec32ef241a/proofs?proofType=FRONT" \
  -H "Authorization: Bearer $LOCALPAYMENT_ACCESS_TOKEN" \
  -F "file=@id_front.jpg;type=image/jpeg"
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "id": "2c4c2f74-7179-4113-83fb-f11dbce9e07d",
  "documentId": "2e16d844-4fa9-4295-9a21-83ec32ef241a",
  "proofType": "FRONT",
  "fileName": "id_front.jpg",
  "mimeType": "image/jpeg",
  "sizeBytes": 102400,
  "verificationStatus": "PENDING",
  "verifiedBy": null,
  "verifiedAt": null,
  "verificationReason": null,
  "uploadedBy": "12345",
  "uploadedAt": "2024-01-15T17:03:13Z",
  "status": "CURRENT",
  "supersededAt": null,
  "supersededBy": null,
  "replacedByProofId": null,
  "deletedAt": null,
  "deletedBy": null,
  "inVerification": false
}
```

En Python, comprueba el tamaño del archivo almacenado y gestiona los errores de carga:

```python theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
import os
import requests

BASE_URL = "https://api.stage.localpayment.com/api/entity"
access_token = os.environ["LOCALPAYMENT_ACCESS_TOKEN"]
doc_id = "2e16d844-4fa9-4295-9a21-83ec32ef241a"

with open("id_front.jpg", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/v1/documents/{doc_id}/proofs",
        params={"proofType": "FRONT"},
        files={"file": ("id_front.jpg", f, "image/jpeg")},
        headers={"Authorization": f"Bearer {access_token}"},
        timeout=60,
    )

if response.status_code == 201:
    proof = response.json()
    if proof["sizeBytes"] == 0:
        raise RuntimeError("Empty file stored: upload again with the same proofType")
elif response.status_code in (413, 415):
    raise RuntimeError("Use a JPG, PNG, or PDF file of 10 MB or less")
elif response.status_code == 502:
    pass  # STORAGE_WRITE_FAILED: retry the upload
else:
    problem = response.json()
    # 409 PROOF_APPROVED or ENTITY_IN_REVIEW: the file cannot be replaced now
    raise RuntimeError(f"{problem.get('code')} correlationId={problem.get('correlationId')}")
```

### Comprobar cobertura

Estado de KYC una vez que ambos archivos estén en su lugar:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "entityId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "status": "PENDING_KYC",
  "documentationStatus": "COMPLETE",
  "statusReason": null,
  "documents": [
    {
      "documentId": "2e16d844-4fa9-4295-9a21-83ec32ef241a",
      "type": "CPF",
      "status": "PENDING",
      "proofs": [
        {
          "proofId": "2c4c2f74-7179-4113-83fb-f11dbce9e07d",
          "verificationStatus": "PENDING"
        }
      ]
    },
    {
      "documentId": "e0ea9515-442e-4bc5-bc82-b8d278255c37",
      "type": "PROOF_OF_ADDRESS",
      "status": "PENDING",
      "proofs": [
        {
          "proofId": "acb78b3f-fe18-4094-b6a9-2107f502d709",
          "verificationStatus": "PENDING"
        }
      ]
    }
  ]
}
```

## Leer archivos de vuelta

[Obtener una prueba](https://docs.localpayment.com/es/reference/get-proof.md) devuelve los metadatos y un `downloadUrl` válido durante 10 minutos. [Descargar el archivo de una prueba](https://docs.localpayment.com/es/reference/download-proof-file.md) redirige directamente a él. Ambos se auditan con el usuario de tu token de acceso.

> [!WARNING]
>
> El `downloadUrl` firmado otorga acceso al archivo hasta que caduque. No lo guardes ni lo compartas con terceros. Solicita uno nuevo cuando vuelvas a necesitar el archivo.

## Reemplazar un archivo rechazado

Cuando Cumplimiento rechaza una prueba, el documento pasa a `REJECTED` y `verificationReason` explica el motivo:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "documentId": "0266257c-a2aa-49ac-99fe-b3882a51d750",
  "entityId": "8f5b2c9a-1caf-4b2c-b085-82bbaead6ddd",
  "type": "NATIONAL_ID",
  "id": "00.000.000-0",
  "issuingCountry": "BRA",
  "issueDate": null,
  "expirationDate": null,
  "isPrimary": false,
  "status": "REJECTED",
  "metadata": null,
  "proofs": [
    {
      "id": "931398af-9c77-4958-abf8-4c749147c508",
      "documentId": "0266257c-a2aa-49ac-99fe-b3882a51d750",
      "proofType": "BACK",
      "fileName": "id_back.jpg",
      "mimeType": "image/jpeg",
      "sizeBytes": 98304,
      "verificationStatus": "REJECTED",
      "verifiedBy": "67890",
      "verifiedAt": "2024-01-15T17:20:34Z",
      "verificationReason": "Illegible image",
      "uploadedBy": "12345",
      "uploadedAt": "2024-01-15T17:19:49Z",
      "status": "CURRENT",
      "supersededAt": null,
      "supersededBy": null,
      "replacedByProofId": null,
      "deletedAt": null,
      "deletedBy": null,
      "inVerification": false
    }
  ],
  "createdAt": "2024-01-15T17:19:46Z",
  "updatedAt": "2024-01-15T17:19:46Z"
}
```

Una vez que la entidad vuelva a `PENDING_KYC`, sube un nuevo archivo con el mismo `proofType`. La prueba rechazada se reemplaza y el documento vuelve a `PENDING`. Cuando las correcciones estén hechas, llama de nuevo a [Solicitar verificación](https://docs.localpayment.com/es/reference/request-entity-verification.md).

## Editar un documento

[Actualizar un documento](https://docs.localpayment.com/es/reference/update-entity-document.md) modifica el país emisor, las fechas y los metadatos. Cualquier cambio restablece a `PENDING` las pruebas aprobadas del documento. El tipo y el número son inmutables: en su lugar, agrega un nuevo documento y elimina el anterior. El documento principal no se puede eliminar.

## Errores comunes

| Error | Causa | Solución |
| - | - | - |
| 413 FILE\_TOO\_LARGE | Archivo de más de 10 MB. | Comprime o divide el archivo. |
| 415 UNSUPPORTED\_FILE\_TYPE | El archivo no es JPG, PNG ni PDF. | Convierte el archivo y vuelve a subirlo. |
| 400 VALIDATION\_ERROR | Falta proofType o no es válido. | Verifica la cadena de consulta. |
| 409 PROOF\_APPROVED | El archivo que está reemplazando o eliminando ya está aprobado. | Consérvalo. Sube evidencia adicional como DOCUMENT u OTHER. |
| 409 ENTITY\_IN\_REVIEW | La entidad está en revisión: no se puede subir, reemplazar ni eliminar ningún archivo. | Espera el resultado en Obtener estado KYC. |
| 409 ENTITY\_NOT\_EDITABLE | La entidad está REJECTED, BLOCKED o CLOSED. | No se pueden agregar archivos a esa entidad. |
| 201 con sizeBytes 0 | La solicitud multipart no tenía una parte de archivo. | Adjunta el archivo y vuelve a subirlo con el mismo proofType. |

## Próximos pasos

> [card] [Realiza el seguimiento de las revisiones y corrige los rechazos.](https://docs.localpayment.com/es/docs/track-review-and-fix-rejections.md)
>
> Sigue las instrucciones de la revisión y corrige lo que te pida Localpayment.

> [card] [Tipos de documentos y comprobantes](https://docs.localpayment.com/es/reference/entity-document-and-proof-types.md)
>
> Tipos de documentos y pruebas aceptados, y restricciones de archivo.


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