5.3. Consultar Duplicata¶

🔗 Endpoint¶

Método	URL
	`/public/api/v1/duplicata-escritural/escrituracoes/{identificadorDuplicata}/consultar`

🧾 Descrição¶

Consulta os dados completos de uma duplicata escritural pelo seu identificador único. Retorna informações de sacador, sacado, dados da transação, documentos fiscais, avalistas, meios de pagamento, liquidações, manifestação do sacado e solicitações de baixa.

⏳ Quando a solicitação foi registrada mas o retorno da registradora ainda não foi recebido, o sistema retornará 102 Processing.

📤 Requisição¶

🔗 Parâmetros de Path¶

Campo	Tipo	Obrigatório	Descrição
identificadorDuplicata	string	Sim	GUID da duplicata a ser consultada

🧪 Exemplo de cURL¶

curl -X GET https://api.vehub.com.br/public/api/v1/duplicata-escritural/escrituracoes/5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6/consultar \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}"

📥 Responses¶

✅ 200 OK¶

{
  "identificadorParticipante": "PART001",
  "codigoUnidadeDuplicata": "UNIDADE001",
  "situacaoUnidadeDuplicata": "ATIVA",
  "codigoIdentificacaoDuplicata": "DUP-2025-001",
  "situacaoDuplicata": "PENDENTE",
  "dataEmissao": "2025-01-15",
  "dataUltimaAlteracao": "2025-03-01",
  "numeroControleCliente": "CTRL-001",
  "valorRemanescente": 10000.00,
  "efeitoNegociacao": {
    "tiposEfeitoUnidade": ["CESSAO"],
    "dataEfeitoUnidade": "2025-02-01",
    "tiposEfeitoNegociacao": ["CESSAO"],
    "dataEfeitoNegociacao": "2025-02-01",
    "codigoIdentificacaoAtoCambialContrato": "CONTRATO-001",
    "cpfOuCnpjTitular": "12345678000199"
  },
  "sacador": {
    "cpfOuCnpj": "12345678000199",
    "nome": "Empresa Cedente LTDA",
    "inscricaoEstadual": "",
    "logradouro": "Av. Paulista, 1000",
    "cep": "01310100",
    "cidade": "São Paulo",
    "uf": "SP"
  },
  "sacado": {
    "cpfOuCnpj": "98765432000155",
    "nome": "Empresa Sacada S.A.",
    "inscricaoEstadual": "",
    "logradouro": "Rua das Flores, 42",
    "cep": "01310100",
    "cidade": "São Paulo",
    "uf": "SP",
    "telefone": "11999999999",
    "email": "financeiro@sacada.com.br",
    "nomeResponsavelManifestacao": "João da Silva",
    "cidadePracaPagamento": "São Paulo",
    "ufPracaPagamento": "SP"
  },
  "dadosTransacao": {
    "tipoDuplicata": 1,
    "dataEmissaoSacador": "2025-01-10",
    "dataVencimento": "2025-03-01",
    "numeroFatura": "FAT-2025-001",
    "valorFatura": 10000.00,
    "valorDesconto": 0.00,
    "valorDuplicata": 10000.00,
    "valorMulta": 0.00,
    "valorJuros": 0.00
  },
  "documentosFiscais": [
    {
      "tipoDocumentoFiscal": 3,
      "chaveDocumentoFiscal": "35250912345678000199550010000012341234567890",
      "numeroDocumentoFiscal": "000001234",
      "serieDocumentoFiscal": "001",
      "numeroOrdem": "",
      "numeroDuplicata": "",
      "situacaoDocumentoFiscal": "ATIVO",
      "motivosSituacao": []
    }
  ],
  "avalistas": [
    {
      "cpfOuCnpj": "12345678901",
      "nome": "João da Silva",
      "estadoCivil": 2,
      "cpfConjuge": "98765432100",
      "nomeConjuge": "Maria da Silva",
      "logradouro": "Rua das Flores, 42",
      "cep": "01310100",
      "cidade": "São Paulo",
      "uf": "SP"
    }
  ],
  "meiosPagamento": [
    {
      "numeroPagamento": "1",
      "tipoMeioPagamento": 2,
      "boleto": {
        "codigoBarras": "",
        "numeroIdentificacao": ""
      },
      "pix": {
        "tipoChave": 2,
        "chave": "12345678000199"
      },
      "dadosBancarios": {
        "ispb": "",
        "banco": "001",
        "agencia": "0001",
        "conta": "123456-7",
        "cpfOuCnpj": ""
      }
    }
  ],
  "dadosComplementares": {
    "clausulaOrdem": "",
    "assinaturaEmitente": ""
  },
  "liquidacoes": [
    {
      "motivoBaixa": "LIQUIDACAO",
      "dataBaixa": "2025-03-01",
      "valorBaixa": 10000.00,
      "valorDesconto": 0.00,
      "dataEfetivacaoBaixa": "2025-03-02",
      "numeroSolicitacaoBaixaSacado": "",
      "indicadorOrigemBaixa": "SACADO"
    }
  ],
  "manifestacaoSacado": {
    "situacaoAceite": "ACEITO",
    "dataHoraAceite": "2025-02-28T10:00:00",
    "motivosRecusa": [],
    "dataHoraRecusa": null,
    "novaDataVencimento": null,
    "valorPagamento": null,
    "anotacaoComercial": "",
    "dataHoraAnotacaoComercial": null
  },
  "solicitacoesBaixa": [
    {
      "numeroSolicitacaoBaixaSacado": "SOL-001",
      "situacaoBaixaSacado": "APROVADA",
      "cpfOuCnpjPagador": "98765432000155",
      "cpfOuCnpjRecebedor": "12345678000199",
      "valorPagamento": 10000.00,
      "dataPagamento": "2025-03-01",
      "instrumentoPagamento": 2,
      "chavePagamento": "12345678000199",
      "meioPagamento": {
        "tipoMeioPagamento": 2,
        "pix": {
          "tipoChave": 2,
          "chave": "12345678000199"
        }
      }
    }
  ]
}

🧾 Detalhamento dos Campos¶

🔹 Raiz¶

Campo	Tipo	Descrição
identificadorParticipante	string	Identificação do participante admitido
codigoUnidadeDuplicata	string	Código da unidade da duplicata
situacaoUnidadeDuplicata	string	Situação da unidade da duplicata
codigoIdentificacaoDuplicata	string	Código de identificação da duplicata
situacaoDuplicata	string	Situação atual da duplicata
dataEmissao	string	Data de emissão da duplicata (YYYY-MM-DD)
dataUltimaAlteracao	string	Data da última alteração registrada (YYYY-MM-DD)
numeroControleCliente	string	Número de controle do cliente
valorRemanescente	number	Valor remanescente da duplicata
efeitoNegociacao	object\|null	Informações de efeitos de negociação (quando houver)
sacador	object	Dados do sacador (emissor)
sacado	object	Dados do sacado (devedor)
dadosTransacao	object	Dados da transação
documentosFiscais	array	Documentos fiscais vinculados
avalistas	array	Avalistas da duplicata
meiosPagamento	array	Meios de pagamento configurados
dadosComplementares	object	Dados complementares
liquidacoes	array	Histórico de liquidações
manifestacaoSacado	object\|null	Manifestação do sacado (quando houver)
solicitacoesBaixa	array	Solicitações de baixa do sacado

🔹 efeitoNegociacao¶

Campo	Tipo	Descrição
tiposEfeitoUnidade	string[]	Tipos de efeito sobre a unidade da duplicata
dataEfeitoUnidade	string\|null	Data do efeito sobre a unidade (YYYY-MM-DD)
tiposEfeitoNegociacao	string[]	Tipos de efeito de negociação
dataEfeitoNegociacao	string\|null	Data do efeito de negociação (YYYY-MM-DD)
codigoIdentificacaoAtoCambialContrato	string	Código de identificação do ato cambial / contrato
cpfOuCnpjTitular	string\|null	CPF ou CNPJ do titular do contrato

🔹 sacador¶

Campo	Tipo	Descrição
cpfOuCnpj	string	CPF ou CNPJ do sacador
nome	string	Nome ou razão social
inscricaoEstadual	string\|null	Inscrição estadual
logradouro	string	Logradouro completo
cep	string	CEP
cidade	string	Cidade
uf	string	UF (2 caracteres)

🔹 sacado¶

Campo	Tipo	Descrição
cpfOuCnpj	string	CPF ou CNPJ do sacado
nome	string	Nome ou razão social
inscricaoEstadual	string\|null	Inscrição estadual
logradouro	string	Logradouro completo
cep	string	CEP
cidade	string	Cidade
uf	string	UF (2 caracteres)
telefone	string\|null	Telefone
email	string	E-mail
nomeResponsavelManifestacao	string\|null	Nome do responsável pela manifestação
cidadePracaPagamento	string\|null	Cidade da praça de pagamento
ufPracaPagamento	string\|null	UF da praça de pagamento

🔹 dadosTransacao¶

Campo	Tipo	Descrição
tipoDuplicata	integer	Tipo da duplicata (ver TipoDuplicata)
dataEmissaoSacador	string\|null	Data de emissão pelo sacador (YYYY-MM-DD)
dataVencimento	string	Data de vencimento (YYYY-MM-DD)
numeroFatura	string	Número da fatura
valorFatura	number\|null	Valor da fatura
valorDesconto	number\|null	Valor de desconto/abatimento
valorDuplicata	number	Valor da duplicata
valorMulta	number\|null	Valor de multa
valorJuros	number\|null	Valor de juros

🔹 documentosFiscais[]¶

Campo	Tipo	Descrição
tipoDocumentoFiscal	integer	Tipo do documento fiscal (ver TipoDocumentoFiscal)
chaveDocumentoFiscal	string	Chave eletrônica do documento fiscal
numeroDocumentoFiscal	string\|null	Número do documento fiscal
serieDocumentoFiscal	string\|null	Série do documento fiscal
numeroOrdem	string\|null	Número de ordem
numeroDuplicata	string\|null	Número da duplicata
situacaoDocumentoFiscal	string	Situação atual do documento fiscal
motivosSituacao	string[]	Motivos da situação (quando aplicável)

🔹 avalistas[]¶

Campo	Tipo	Descrição
cpfOuCnpj	string	CPF ou CNPJ do avalista
nome	string	Nome ou razão social
estadoCivil	integer\|null	Estado civil (ver EstadoCivil)
cpfConjuge	string\|null	CPF do cônjuge
nomeConjuge	string\|null	Nome do cônjuge
logradouro	string	Logradouro completo
cep	string	CEP
cidade	string	Cidade
uf	string	UF (2 caracteres)

🔹 meiosPagamento[]¶

Campo	Tipo	Descrição
numeroPagamento	string	Número sequencial do meio de pagamento
tipoMeioPagamento	integer	Tipo do meio de pagamento (ver TipoInstrumentoPagamento)
boleto	object\|null	Dados do boleto (quando tipoMeioPagamento = 1)
pix	object\|null	Dados do PIX (quando tipoMeioPagamento = 2)
dadosBancarios	object\|null	Dados bancários para TED (quando tipoMeioPagamento = 3)

🔹 meiosPagamento[].boleto¶

Campo	Tipo	Descrição
codigoBarras	string	Código de barras do boleto
numeroIdentificacao	string\|null	Número de identificação do boleto

🔹 meiosPagamento[].pix¶

Campo	Tipo	Descrição
tipoChave	integer	Tipo da chave PIX (ver TipoChavePix)
chave	string	Valor da chave PIX

🔹 meiosPagamento[].dadosBancarios¶

Campo	Tipo	Descrição
ispb	string\|null	Código ISPB do banco
banco	string	Código do banco
agencia	string	Agência bancária
conta	string	Número da conta
cpfOuCnpj	string\|null	CPF ou CNPJ do titular da conta

🔹 dadosComplementares¶

Campo	Tipo	Descrição
clausulaOrdem	string\|null	Cláusula à ordem
assinaturaEmitente	string\|null	Assinatura do emitente

🔹 liquidacoes[]¶

Campo	Tipo	Descrição
motivoBaixa	string	Motivo da baixa da duplicata
dataBaixa	string	Data da baixa (YYYY-MM-DD)
valorBaixa	number\|null	Valor da baixa
valorDesconto	number\|null	Valor de desconto aplicado
dataEfetivacaoBaixa	string	Data de efetivação da baixa (YYYY-MM-DD)
numeroSolicitacaoBaixaSacado	string\|null	Número da solicitação de baixa do sacado
indicadorOrigemBaixa	string	Indicador da origem da baixa

🔹 manifestacaoSacado¶

Campo	Tipo	Descrição
situacaoAceite	string\|null	Situação do aceite
dataHoraAceite	string\|null	Data e hora do aceite (ISO 8601)
motivosRecusa	string[]	Motivos de recusa (ver TipoManifestacao)
dataHoraRecusa	string\|null	Data e hora da recusa (ISO 8601)
novaDataVencimento	string\|null	Nova data de vencimento proposta (YYYY-MM-DD)
valorPagamento	number\|null	Valor de pagamento proposto
anotacaoComercial	string\|null	Texto da anotação comercial
dataHoraAnotacaoComercial	string\|null	Data e hora da anotação comercial (ISO 8601)

🔹 solicitacoesBaixa[]¶

Campo	Tipo	Descrição
numeroSolicitacaoBaixaSacado	string	Número da solicitação de baixa
situacaoBaixaSacado	string	Situação da solicitação de baixa
cpfOuCnpjPagador	string	CPF ou CNPJ do pagador
cpfOuCnpjRecebedor	string	CPF ou CNPJ do recebedor
valorPagamento	number	Valor do pagamento
dataPagamento	string	Data do pagamento (YYYY-MM-DD)
instrumentoPagamento	integer	Instrumento de pagamento utilizado (ver TipoInstrumentoPagamento)
chavePagamento	string	Chave ou referência do pagamento
meioPagamento	object	Meio de pagamento utilizado na baixa

⏳ 102 Processing¶

Retornado quando a duplicata existe no sistema, mas o retorno da registradora ainda não foi recebido.

{
  "mensagem": "Consulta em andamento. O retorno da registradora ainda não foi recebido."
}

❌ 404 Not Found¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.4",
  "titulo": "Não encontrado",
  "status": 404,
  "erros": [
    "Duplicata não encontrada."
  ]
}

❌ 400 Bad Request¶

{
  "tipo": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "titulo": "Atenção",
  "status": 400,
  "erros": [
    "Identificador de duplicata inválido."
  ]
}

🔢 Enumeradores¶

Consulte os enumeradores utilizados nesta resposta:

TipoDuplicata — ver 5.1. Criar Escriturações
TipoDocumentoFiscal — ver 5.1. Criar Escriturações
EstadoCivil — ver 5.1. Criar Escriturações
TipoInstrumentoPagamento — ver 5.1. Criar Escriturações
TipoChavePix — ver 5.1. Criar Escriturações
TipoManifestacao — ver 6.5. Manifestação do Sacado

🕒 Observações¶

O campo efeitoNegociacao é opcional e só estará presente quando a duplicata estiver vinculada a um contrato de negociação.
Os arrays documentosFiscais, avalistas, meiosPagamento, liquidacoes e solicitacoesBaixa podem estar vazios.
O campo manifestacaoSacado será null enquanto nenhuma manifestação tiver sido registrada.
Quando o retorno for 102 Processing, aguarde e tente novamente em instantes.