Enviar documentos

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
`CORRECAO_DOCUMENTOS` (7), com a proposta pendente	Só os tipos com status `INVALIDO`

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

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

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.

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:

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

Filtre os recusados

Selecione os documentos com enum_status = 2 (INVALIDO).

Mostre o motivo

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

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

Integração

Guias

Ajuda

Quando enviar

Tipos aceitos

Regras do arquivo

Exemplo

Correção de documentos

Erros

​Quando enviar

​Tipos aceitos

​Regras do arquivo

​Exemplo

​Correção de documentos

​Erros

Quando enviar

Tipos aceitos

Regras do arquivo

Exemplo

Correção de documentos

Erros