6.10. Consultar, Listar e Pendências¶

Especificação — em construção

Os serviços descritos nesta área ainda não estão disponíveis.

🔗 Endpoints¶

Método	URL
	`/credito/propostas/{idProposta}`
	`/credito/esteiras/{idEsteira}/propostas`
	`/credito/propostas/{idProposta}`

🧾 Descrição¶

A consulta da proposta é o serviço mais importante da integração. Além do estado atual, ela responde a pergunta que o seu código precisa fazer a cada passo: o que falta e qual é a próxima etapa?

Use-a em vez de replicar a ordem das etapas no seu fluxo. A ordem muda por configuração da esteira; a resposta desta consulta não.

Consultar proposta¶

🧪 Exemplo de cURL¶

curl -X GET "https://api.vehub.com.br/credito/propostas/1001" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}"

📥 Response — `200 OK`¶

{
  "sucesso": true,
  "mensagem": null,
  "dados": {
    "id": 1001,
    "idEsteira": 12,
    "produto": "ep",
    "simulacao": {
      "status": { "id": 26, "nome": "Aprovado pelo motor" },
      "dataCriacao": "2026-08-20T13:04:11Z",
      "dataGeracaoProposta": null,
      "numeroCcb": null,
      "temErro": false,
      "erros": null,
      "dadosFinanceiros": {
        "tipoSimulacao": 1,
        "taxa": 1.99,
        "valorSolicitado": 18000.00,
        "quantidadeParcelas": 24,
        "fluxoIrregular": false,
        "nroDiasIntervaloPrazo": null,
        "valorParcelaDesejada": null,
        "dataPrimeiroVencimento": "2026-10-10",
        "valorSeguro": 120.00,
        "valorOutrasDespesas": 0.00,
        "valorOutrosServicos": 30.00,
        "cet": { "valor": 2563.20, "percentualMensal": 2.10, "percentualAnual": 28.30 },
        "juros": { "valor": 2150.60, "percentualMensal": 1.99, "percentualAnual": 26.65 },
        "iof": { "valor": 412.30, "percentual": 2.31 },
        "totais": { "parcela": 850.00, "valorTotal": 20400.00, "valorDesembolso": 18000.00 },
        "parcelas": [ ]
      }
    },
    "tomador": { },
    "analiseCredito": {
      "status": { "id": 6, "nome": "Aprovado" },
      "score": "742",
      "limiteConcedido": "25000.00",
      "motivo": null,
      "dataHoraRetorno": "2026-08-20T13:22:40Z",
      "novaAnaliseSolicitada": false
    },
    "dadosBancarios": {
      "idBanco": 1,
      "agencia": "12345",
      "conta": "9876543",
      "tipoConta": 2
    },
    "destinatarioDesembolso": null,
    "parceiroOriginador": null,
    "proximaEtapa": "documentos",
    "pendencias": [
      {
        "etapa": "documentos",
        "codigo": "documento_nao_enviado",
        "mensagem": "Comprovante de residência não enviado.",
        "referencia": 92
      },
      {
        "etapa": "documentos",
        "codigo": "documento_nao_enviado",
        "mensagem": "Comprovante de renda não enviado.",
        "referencia": 93
      }
    ],
    "acoesDisponiveis": ["documentos", "avalistas", "garantias"]
  }
}

🧾 Detalhamento dos Campos¶

Campo	Tipo	Descrição
id	integer	Identificador da proposta
idEsteira	integer	Esteira à qual a proposta pertence
produto	string	`ep` ou `cdc`
simulacao	object	Estado e valores financeiros — ver 6.2
tomador	object	Ficha do tomador — ver 4.2 e 4.3
analiseCredito	object / null	Resultado do motor — ver 6.7
dadosBancarios	object / null	Conta do tomador. Nulo quando o desembolso vai ao parceiro
destinatarioDesembolso	integer / null	`1` Emitente, `2` Parceiro. Sempre `null` em EP
parceiroOriginador	object / null	Parceiro atrelado, quando o desembolso vai a ele
proximaEtapa	string	A etapa que você deve executar em seguida
pendencias	array	O que impede a proposta de avançar
acoesDisponiveis	array	Etapas que aceitam chamada no estado atual

Como usar `proximaEtapa` e `pendencias`¶

Em vez de codificar a sequência de etapas, faça um laço:

Esse desenho sobrevive a mudanças de configuração da esteira: se o negócio ligar a jornada simplificada ou o desembolso ao parceiro, o seu código continua funcionando.

Valores de `proximaEtapa`¶

Valor	Significado
`tomador`	Completar a ficha do tomador
`dados_bancarios`	Informar a conta do tomador
`desembolso`	Informar o parceiro originador (CDC)
`simulacao`	Gravar as condições financeiras
`avalistas`	Etapa opcional pendente de decisão
`garantias`	Etapa opcional pendente de decisão
`documentos`	Enviar documentos exigidos
`analise_credito`	Submeter ao motor de crédito
`envio`	Enviar à bancarizadora
`formalizacao`	Nada a fazer: formalização em curso — ou a proposta já foi registrada na bancarizadora (ver Proposta já registrada na bancarizadora), ou o desembolso não foi pago (ver Falha no pagamento)
`concluido`	Operação finalizada

Estrutura de `pendencias[]`¶

Campo	Tipo	Descrição
etapa	string	Etapa à qual a pendência pertence, com os mesmos valores de `proximaEtapa`
codigo	string	Identificador estável da pendência, para tratamento programático
mensagem	string	Texto legível, adequado para exibir ao operador
referencia	integer / null	Id do recurso relacionado, quando aplicável (ex.: o `idDocumento` pendente)

pendencias vazio e proximaEtapa igual a envio é a condição que garante que o envio vai passar.

Proposta já registrada na bancarizadora¶

A proposta que já tem a CCB emitida (numeroCcb preenchido) pode aparecer em 1 Em digitação, 9 Falha na inclusão da proposta, 10 Falha na simulação ou no retorno do motor (26, 27 ou 28): o status não distingue a proposta registrada da que ainda é rascunho, porque depois do registro a plataforma pode gravar Falha na simulação (quando a bancarizadora recusa a assinatura ou a liberação) e o retorno de status da bancarizadora pode devolvê-la à digitação. Nesses casos a consulta devolve:

Campo	Valor
`proximaEtapa`	`formalizacao`
`pendencias`	Uma pendência de código `proposta_registrada`: A proposta já foi registrada na instituição financeira. O tratamento passa a ser operacional.
`acoesDisponiveis`	`["assinantes"]`

A reabertura, a nova simulação, o envio, a submissão à análise e o cancelamento não são anunciados, porque os cinco respondem 409 com a CCB emitida.

Falha no pagamento¶

Com a proposta em 30 Falha no pagamento, a CCB está assinada e liberada, mas a instituição financeira não conseguiu pagar o desembolso. A conta é corrigida pela operação, e a proposta volta a 6 Finalizado. A consulta devolve:

Campo	Valor
`proximaEtapa`	`formalizacao`
`pendencias`	Uma pendência de código `falha_no_pagamento`: A instituição financeira não conseguiu pagar o desembolso. O tratamento passa a ser operacional.
`acoesDisponiveis`	`["assinantes", "ccb", "historico"]`

Listar propostas¶

🔹 Query Parameters¶

Parâmetro	Tipo	Descrição
pagina	integer	Página, começando em `1`
quantidade	integer	Registros por página. Máximo `100`
ordem	string	Campo de ordenação
direcaoOrdem	string	`asc` ou `desc`
nome	string	Filtro por nome do tomador
documento	string	Filtro por CPF ou CNPJ
status	array	Um ou mais códigos de status
dataContrato	date	Filtro por data da operação
dataPrimeiraParcela	date	Filtro por vencimento da primeira parcela

🧪 Exemplo de cURL¶

curl -X GET "https://api.vehub.com.br/credito/esteiras/12/propostas?pagina=1&quantidade=50&status=1&status=26" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}"

📥 Response — `200 OK`¶

{
  "registros": [
    {
      "id": 1001,
      "idContrato": 5001,
      "nome": "João da Silva",
      "documento": "12345678900",
      "valorEmprestimo": 18000.00,
      "dataContrato": "2026-08-20",
      "dataPrimeiraParcela": "2026-10-13",
      "status": 26,
      "statusPagamento": 0,
      "cobrancasRegistradas": false
    }
  ],
  "paginacao": { "pagina": 1, "quantidade": 50, "total": 137 },
  "mensagem": null
}

Campo	Tipo	Descrição
id	integer	Identificador da proposta
idContrato	integer	Identificador do contrato, usado nos serviços de carteira
valorEmprestimo	number	Valor da operação
status	integer	Ver 2.1. Enumerações
cobrancasRegistradas	boolean	`true` quando já há cobrança emitida para o contrato

Cancelar proposta¶

🔗 Endpoint¶

Método	URL
	`/credito/propostas/{idProposta}`

📥 Response — `200 OK`¶

{
  "sucesso": true,
  "mensagem": "Proposta cancelada com sucesso.",
  "dados": null
}

❌ 409 Conflict¶

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "status": 409,
  "errors": [
    { "campo": null, "mensagem": "Somente propostas em digitação podem ser canceladas. Situação atual: Aguardando assinaturas." }
  ]
}

O cancelamento por API é limitado a Em digitação

Depois que a proposta é submetida ao motor ou enviada à bancarizadora, o cancelamento passa a ser operação de plataforma, feita pelo time de operações. Não há endpoint público para cancelar uma proposta já registrada.

❌ 409 Conflict — proposta já registrada¶

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "status": 409,
  "errors": [
    { "campo": null, "mensagem": "A proposta já foi registrada na instituição financeira e não pode ser cancelada por aqui. O tratamento passa a ser operacional." }
  ]
}

Vale para a proposta com a CCB emitida mesmo que o status tenha voltado a Em digitação: a operação existe na bancarizadora, e cancelá-la aqui não a cancela lá.

6.10. Consultar, Listar e Pendências¶

🔗 Endpoints¶

🧾 Descrição¶

Consultar proposta¶

🧪 Exemplo de cURL¶

📥 Response — 200 OK¶

🧾 Detalhamento dos Campos¶

Como usar proximaEtapa e pendencias¶

Valores de proximaEtapa¶

Estrutura de pendencias[]¶

Proposta já registrada na bancarizadora¶

Falha no pagamento¶

Listar propostas¶

🔹 Query Parameters¶

🧪 Exemplo de cURL¶

📥 Response — 200 OK¶

Cancelar proposta¶

🔗 Endpoint¶

📥 Response — 200 OK¶

❌ 409 Conflict¶

❌ 409 Conflict — proposta já registrada¶

📥 Response — `200 OK`¶

Como usar `proximaEtapa` e `pendencias`¶

Valores de `proximaEtapa`¶

Estrutura de `pendencias[]`¶

📥 Response — `200 OK`¶

📥 Response — `200 OK`¶