> ## 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.

# Carregar documentos e comprovantes

> Declare os documentos comprobatórios da entidade e faça o upload dos arquivos (comprovantes) que a Localpayment analisa durante o processo de KYC/KYB.

Um documento é o conjunto de dados declarados (tipo e número). Uma prova é um arquivo que o comprova. Este guia mostra como adicionar documentos a uma entidade, fazer o upload de seus arquivos um a um, substituir ou remover arquivos e verificar se todos os documentos estão cobertos para que a entidade esteja pronta para revisão.

## Pré-requisitos

* Uma entidade criada com [Criar uma entidade](https://docs.localpayment.com/pt-br/docs/create-an-entity.md) e o `documentId` de cada um de seus documentos.
* Arquivos em JPG, PNG ou PDF, com até 10 MB cada.

## Arquivos por documento

Um documento pode conter quantos arquivos você precisar. Cada arquivo tem um tipo:

| proofType | Uso típico | Comportamento em um novo upload |
| - | - | - |
| FRONT | Frente de um documento de identidade, ou a única imagem de um documento. | Substitui o arquivo atual, que passa a ser SUPERSEDED. |
| BACK | Verso de um documento de identidade. | Substitui o arquivo atual, que passa a ser SUPERSEDED. |
| SELFIE | Foto da pessoa, carregada no próprio documento de identidade. | Substitui o arquivo atual, que passa a ser SUPERSEDED. |
| DOCUMENT | Documento digitalizado (PDF): comprovante de endereço, contrato social, registro fiscal. | Adiciona um arquivo, por exemplo, cada página de um contrato. |
| OTHER | Qualquer outra evidência. | Adiciona um arquivo. |

Um arquivo APPROVED não pode ser substituído (409 `PROOF_APPROVED`). Um arquivo enviado por engano pode ser removido com [Excluir uma prova](https://docs.localpayment.com/pt-br/reference/delete-proof.md) enquanto não estiver aprovado.

```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["Seu backend<br/>POST /api/entity/v1/entities/{entityId}/documents<br/>PROOF_OF_ADDRESS"] --> B["Entities API<br/>201: documentId"]:::lp
    B --> C["Seu backend<br/>POST /api/entity/v1/documents/{docId}/proofs?proofType=FRONT<br/>arquivo multipart"]
    C --> D["Entities API<br/>201: id da prova, verificationStatus PENDING"]:::lp
    D --> E["Seu backend<br/>POST /api/entity/v1/documents/{docId}/proofs?proofType=DOCUMENT<br/>PDF"]
    E --> F["Entities API<br/>201: id da prova"]:::lp
    F --> G["Seu 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
```

## Passo a passo

1. Declare o documento se a entidade ainda não o possuir, com [Adicionar um documento](https://docs.localpayment.com/pt-br/reference/add-entity-document.md). Mantenha o `documentId` dele.
2. Faça o upload do arquivo com [Fazer upload de uma prova](https://docs.localpayment.com/pt-br/reference/upload-proof.md): `POST /api/entity/v1/documents/{docId}/proofs?proofType=FRONT` como `multipart/form-data`, com uma parte chamada `file`.
3. Verifique o upload: a resposta 201 deve mostrar `sizeBytes` maior que zero e o `mimeType` esperado.
4. Repita para o verso (`proofType=BACK`) e para a selfie (`proofType=SELFIE`) do documento de identidade, e para cada um dos outros documentos.
5. Verifique a cobertura com [Obter Status KYC](https://docs.localpayment.com/pt-br/reference/get-kyc-status.md). `documentationStatus` deve ser `COMPLETE` para que a entidade esteja pronta para revisão.

### Carregar um arquivo

```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
}
```

Em Python, verifique o tamanho do arquivo armazenado e trate os erros de upload:

```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')}")
```

### Verifique a cobertura

Status KYC assim que ambos os arquivos estiverem no local:

```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"
        }
      ]
    }
  ]
}
```

## Leia os arquivos novamente

[Obter uma prova](https://docs.localpayment.com/pt-br/reference/get-proof.md) retorna os metadados e um `downloadUrl` válido por 10 minutos. [Baixar um arquivo de prova](https://docs.localpayment.com/pt-br/reference/download-proof-file.md) redireciona diretamente para ele. Ambos são auditados com o usuário presente no seu token de acesso.

> [!WARNING]
>
> O `downloadUrl` assinado concede acesso ao arquivo até que expire. Não o armazene nem o compartilhe com terceiros. Solicite um novo quando precisar do arquivo novamente.

## Substitua um arquivo rejeitado

Quando a área de Conformidade rejeita uma prova, o documento passa a `REJECTED` e `verificationReason` explica o 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"
}
```

Quando a entidade voltar para `PENDING_KYC`, faça o upload de um novo arquivo com o mesmo `proofType`. A prova rejeitada é substituída e o documento volta para `PENDING`. Quando as correções estiverem concluídas, chame [Solicitar verificação](https://docs.localpayment.com/pt-br/reference/request-entity-verification.md) novamente.

## Editar um documento

[Atualizar um documento](https://docs.localpayment.com/pt-br/reference/update-entity-document.md) altera o país emissor, as datas e os metadados. Qualquer alteração redefine as provas aprovadas do documento para `PENDING`. O tipo e o número são imutáveis: adicione um novo documento e exclua o antigo. O documento principal não pode ser excluído.

## Erros comuns

| Erro | Causa | Correção |
| - | - | - |
| 413 FILE\_TOO\_LARGE | Arquivo com mais de 10 MB. | Comprima ou divida o arquivo. |
| 415 UNSUPPORTED\_FILE\_TYPE | O arquivo não é um JPG, PNG ou PDF. | Converta o arquivo e faça o upload novamente. |
| 400 VALIDATION\_ERROR | proofType ausente ou inválido. | Verifique a string de consulta. |
| 409 PROOF\_APPROVED | O arquivo que você está substituindo ou excluindo já foi aprovado. | Guarde-o. Envie evidências adicionais como DOCUMENT ou OTHER. |
| 409 ENTITY\_IN\_REVIEW | A entidade está em análise: nenhum arquivo pode ser enviado, substituído ou excluído. | Aguarde o resultado em Obter Status KYC. |
| 409 ENTITY\_NOT\_EDITABLE | A entidade está REJECTED, BLOCKED ou CLOSED. | Não é possível adicionar arquivos a essa entidade. |
| 201 with sizeBytes 0 | A solicitação multipart não continha a parte de arquivo. | Anexe o arquivo e faça o upload novamente com o mesmo proofType. |

## Próximos passos

> [card] [Acompanhe a revisão e corrija as rejeições](https://docs.localpayment.com/pt-br/docs/track-review-and-fix-rejections.md)
>
> Siga as instruções da revisão e corrija o que a Localpayment solicitar.

> [card] [Tipos de documentos e provas](https://docs.localpayment.com/pt-br/reference/entity-document-and-proof-types.md)
>
> Tipos de documentos e provas aceitos, e restrições de arquivo.


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