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

# Enviar documentos

> Como enviar documentos em Base64, tratar recusas e reenviar com segurança

Os documentos do comprador, do vendedor e da loja são enviados por `POST /v2/proposal/{propostaId}/document`, **um arquivo por chamada**.

## Quando enviar

| Etapa ativa do participante | O que enviar |
| - | - |
| `ENVIO_DOCUMENTOS` (6), com a proposta aprovada | Os documentos com status `PENDENTE` na [consulta da proposta](https://documentacao.credicarro.com.br/pages/v2/proposal/get.md) |
| `CORRECAO_DOCUMENTOS` (7), com a proposta pendente | Só os tipos com status `INVALIDO` |

Fora dessas etapas, a API retorna `422` com `Document.InvalidProposalStage`.

> [!NOTE]
>
> Cada participante tem a sua etapa. Olhe o `status_ativo` de **cada** participante antes de enviar.

## Tipos aceitos

| Código | Tipo | Comprador | Vendedor | Loja |
| - | - | :-: | :-: | :-: |
| 1 | `CNH` | ✓ | ✓ | |
| 2 | `CPF` | | ✓ | |
| 3 | `RG` | | ✓ | |
| 4 | `COMPROVANTE_RENDA` | ✓ | | |
| 5 | `COMPROVANTE_RESIDENCIA` | ✓ | ✓ | |
| 6 | `DOCUMENTO_VEICULO` | ✓ | ✓ | ✓ |
| 7 | `CNH_DIGITAL` | ✓ | ✓ | |
| 8 | `LAUDO_ECV` | | ✓ | ✓ |
| 9 | `LAUDO_VISTORIA` | ✓ | ✓ | |
| 11 | `CARTAO_CNPJ` | | ✓ | |
| 57 | `ATPV` | ✓ | | |

## Regras do arquivo

* Formatos: PDF, JPG/JPEG ou PNG
* Até **10 MiB** depois de decodificado
* `nomeArquivo` com extensão, sem caminho, até 255 caracteres
* A extensão precisa corresponder ao conteúdo real do arquivo
* `conteudoBase64` em Base64 puro, **sem** o prefixo `data:application/pdf;base64,`
* Header `Idempotency-Key` **obrigatório**

***

## Exemplo

```bash theme={null}
curl -X POST https://api.staging.credicarro.com.br/integration/v2/proposal/{propostaId}/document \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{
    "participante": "COMPRADOR",
    "tipoDocumento": 1,
    "nomeArquivo": "cnh-comprador.pdf",
    "conteudoBase64": "JVBERi0xLjcKJcOkw7zDtsOfCjIgMCBvYmoK..."
  }'
```

Para montar o `conteudoBase64`, leia os bytes do arquivo e codifique em Base64 padrão, sem quebras de linha e sem o prefixo `data:`.

Gere a chave uma vez por envio — por exemplo, um UUID salvo junto ao registro do documento no seu sistema — e passe a mesma chave em todas as tentativas desse envio.

Resposta: `204 No Content`, sem corpo. O documento entra com status `RECEBIDO` e passa por análise. Um novo envio do mesmo tipo e participante substitui o anterior.

> [!WARNING]
>
> Gere a `Idempotency-Key` **uma vez por envio** e reaproveite a mesma chave nas retentativas desse envio. Com a mesma chave e o mesmo conteúdo, um envio bem-sucedido nas últimas 24 horas não é processado de novo. Uma chave nova a cada tentativa reenvia e substitui o documento.

***

## Correção de documentos

Quando um documento é recusado, o participante vai para `CORRECAO_DOCUMENTOS` e o documento aparece com `status` = `INVALIDO` e o `motivo`:

```json theme={null}
{
  "status_ativo": {
    "enum_etapa": 7,
    "etapa": "CORRECAO_DOCUMENTOS",
    "enum_situacao": 4,
    "situacao": "PENDENTE_CORRECAO",
    "enum_responsavel_acao": 2,
    "responsavel_acao": "INTEGRADOR"
  },
  "documentos": [
    { "enum_tipo": 1, "tipo": "CNH", "enum_status": 2, "status": "INVALIDO", "motivo": "Documento ilegível" },
    { "enum_tipo": 5, "tipo": "COMPROVANTE_RESIDENCIA", "enum_status": 1, "status": "VALIDO" }
  ]
}
```

**1. Filtre os recusados**

Selecione os documentos com `enum_status` = 2 (`INVALIDO`).

**2. Mostre o motivo**

Exiba o `motivo` para a loja ou o cliente corrigir o arquivo.

**3. Reenvie o mesmo tipo**

Envie de novo com o mesmo `participante` e `tipoDocumento`, com uma **nova** `Idempotency-Key`. Enviar um tipo que não está recusado retorna `422` com `Document.NotPendingCorrection`.

***

## Erros

Erros de formato retornam `400`, com o campo em `campo`:

| `tipo` | Como resolver |
| - | - |
| `Validation.Field.Required` | Envie o campo indicado em `campo` (inclusive o header `Idempotency-Key`). |
| `Validation.IdempotencyKey.Invalid` | Use uma `Idempotency-Key` de 1 a 200 caracteres. |
| `Validation.Field.InvalidOption` | Use `COMPRADOR`, `VENDEDOR` ou `LOJA` e um `tipoDocumento` da tabela. |
| `Validation.Document.TypeNotAllowed` | O tipo não é aceito para o participante. Confira a tabela. |
| `Validation.File.InvalidName` | Use só o nome do arquivo, sem caminho, com até 255 caracteres. |
| `Validation.File.InvalidExtension` | Use `.pdf`, `.jpg`, `.jpeg` ou `.png`. |
| `Validation.File.InvalidBase64` | Remova o prefixo `data:` e quebras de linha. |
| `Validation.File.Empty` | O arquivo está vazio. |
| `Validation.File.TooLarge` | Comprima ou reduza a resolução do arquivo. |

Regras que dependem da proposta e do arquivo:

| `tipo` | Status | Como resolver |
| - | - | - |
| `Document.InvalidProposalStage` | `422` | Aguarde a etapa `ENVIO_DOCUMENTOS` ou `CORRECAO_DOCUMENTOS`. |
| `Document.NotPendingCorrection` | `422` | Na correção, reenvie só os tipos com status `INVALIDO`. |
| `Document.InvalidContent` | `422` | A extensão não corresponde ao conteúdo. Não renomeie arquivos de outro formato. |
| `Document.InvalidProposalModality` | `422` | A modalidade da proposta não permite envio de documentos pela integração. Fale com o time Credicarro. |
| `Idempotency.KeyConflict` | `409` | Use uma nova chave para um novo envio. |
| `Document.UploadFailed` | `502` | Falha temporária ao armazenar o arquivo. Repita com a mesma `Idempotency-Key`. |


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