Copiar Página

3.2. Atualizações do Contrato

🔔 Tipo de Notificação

Campo	Valor	Significado
tipoNotificacao	2	Atualização do contrato: novo status, URs incluídas ou removidas e totais recalculados

---

🧾 Descrição

Esta notificação é enviada via POST para o endpoint de WebHook configurado previamente sempre que houver atualização no contrato — mudança de status, alteração no vínculo das URs, recálculo dos totais ou cancelamento.

Ela é útil para refletir o estado do vínculo das URs processadas no contrato e para atualizar os dados financeiros agregados do seu lado.

Esta é uma notificação da fase de contrato. Por isso o valor que sempre aparece nos totais é o garantido — o valor efetivamente comprometido pelas URs no contrato, conforme o aceite da registradora. Os valores de cessão (nominal, desconto, aquisicao e taxa) só aparecem em contrato de troca de titularidade, e os valores da fase de agenda (valorConstituido, valorComprometido, valorLivre) pertencem a 3.1. Listagem de URs.

A posição do contrato também pode ser consultada de forma ativa em 5.3. Detalhes do contrato e 5.4. Listar URs do contrato.

---

📤 Payload Enviado

{
  "tipoNotificacao": 2,
  "contrato": {
    "identificador": "19710560-04CD-4E48-881D-D38350B39079",
    "identificadorInteroperabilidade": ["0DC43268-E05F-478E-931C-A43B8B3DD79B"],
    "status": 1,
    "registradora": {
      "id": 1,
      "nome": "B3"
    }
  },
  "totais": {
    "taxa": 0.00,
    "nominal": 0.00,
    "desconto": 0.00,
    "aquisicao": 0.00,
    "garantido": 0.00
  },
  "titulos": [
    {
      "id": "7D121577-3C5A-494D-B052-291D9E100D0D",
      "credenciadora": "",
      "arranjo": "",
      "status": 1,
      "dataPrevistaLiquidacao": "",
      "valorNominal": 0.00,
      "valorGarantido": 0.00,
      "valorDesconto": 0.00,
      "valorAquisicao": 0.00
    }
  ]
}

🧾 Detalhamento dos Campos

🔹 contrato

Campo	Tipo	Descrição
identificador	string	GUID referente ao identificador do contrato
identificadorInteroperabilidade	string[]	GUID gerado no ambiente de interoperabilidade do contrato
status	number	Status do contrato (ver tabela Status do contrato abaixo)
registradora	object	Registradora onde o contrato está sendo processado. Retorna null enquanto a registradora não estiver definida
registradora.id	number	Identificador da registradora (ver tabela Registradoras abaixo)
registradora.nome	string	Nome da registradora

🔹 totais

Campo	Tipo	Descrição
garantido	number	Soma do valor efetivamente comprometido pelas URs neste contrato, conforme o aceite da registradora. Presente nos dois tipos de contrato
taxa	number	Deságio utilizado na antecipação, com até 4 casas decimais. Somente em troca de titularidade
nominal	number	Soma dos valores nominais das URs cedidas ao fundo, antes do deságio. Somente em troca de titularidade
desconto	number	Soma dos deságios aplicados sobre o valor nominal. Somente em troca de titularidade
aquisicao	number	Soma dos valores líquidos (nominal - desconto). Somente em troca de titularidade

🔹 titulos

Campo	Tipo	Descrição
id	string	GUID da UR
credenciadora	string	CNPJ da credenciadora (somente números)
arranjo	string	Sigla do arranjo (ex.: MCC, VCC)
status	integer	Estado do vínculo da UR na registradora (ver tabela Status da UR abaixo). Não informa liquidação
dataPrevistaLiquidacao	string	Data prevista de liquidação da UR, no formato YYYY-MM-DD
valorGarantido	number	Valor da UR efetivamente comprometido neste contrato. Pode ser menor que o valor solicitado quando a registradora acata parcialmente. Presente nos dois tipos de contrato
valorNominal	number	Valor bruto da UR cedida ao fundo. Somente em troca de titularidade
valorDesconto	number	Valor do deságio aplicado sobre a UR. Somente em troca de titularidade
valorAquisicao	number	Valor líquido da UR após o deságio (valorNominal - valorDesconto). Somente em troca de titularidade

---

💰 Quais Valores Chegam em Cada Tipo de Contrato

tipoContrato tem somente dois valores: 1 = Troca de titularidade e 2 = Garantia. A configuração de fumaça (prazo estendido, somente URs performadas e regra de retenção) é uma variação da garantia, e não um tipo de contrato: o contrato continua com tipoContrato igual a 2.

Campo	Troca de titularidade (1)	Garantia (2)
totais.garantido	✅ Presente	✅ Presente
totais.taxa	✅ Presente	❌ Não existe
totais.nominal	✅ Presente	❌ Não existe
totais.desconto	✅ Presente	❌ Não existe
totais.aquisicao	✅ Presente	❌ Não existe
titulos[].valorGarantido	✅ Presente	✅ Presente
titulos[].valorNominal	✅ Presente	❌ Não existe
titulos[].valorDesconto	✅ Presente	❌ Não existe
titulos[].valorAquisicao	✅ Presente	❌ Não existe

Por que a garantia não traz esses campos? Porque nominal, desconto, aquisicao e taxa só existem onde houve cessão ao fundo. Na troca de titularidade a UR muda de titular: alguém compra o recebível com deságio, então faz sentido falar de valor nominal, deságio e valor de aquisição. Em um contrato de garantia não há cessão nem deságio — a UR continua sendo do EC, apenas comprometida. Sem cessão não há preço de compra; sem deságio não há taxa.

Consequência prática para a integração: em contrato de garantia, o único valor a ser lido é o garantido (e o valorGarantido de cada UR). Não espere nominal, desconto, aquisicao nem taxa — eles simplesmente não vêm no payload.

---

🔢 Status da UR

Este é o eixo registral: responde se a registradora aceitou a UR neste contrato. Não informa se o dinheiro entrou — o estado de caixa chega em 3.3. Atualizações da UR e pode ser consultado em 5.4. Listar URs do contrato.

Código	Significado	Aplicação
0	Sucesso	UR vinculada corretamente ao contrato
1	Falha no vínculo	A registradora recusou o vínculo desta UR. O valorGarantido fica em 0.00
2	Em processamento	Vínculo enviado à registradora, aguardando retorno. Status inicial
3	Pendente extensão	Vínculo aceito, mas dependente da prorrogação do prazo do contrato — situação típica da garantia fumaça
999	Cancelada	Vínculo desfeito: cancelamento do contrato ou remoção da UR já confirmada pela registradora
1000	Em remoção	Remoção da UR solicitada e aguardando retorno da registradora. Enquanto não confirmada, a UR continua constando no contrato

---

🔢 Status do contrato

Código	Significado	Aplicação
1	Aguardando registro	Contrato recebido na plataforma e na fila de envio à registradora
2	Registrando	Contrato oficializado na registradora e aguardando retorno do registro
3	Falha no registro	Contrato obteve erro na formalização no regime de interoperabilidade
4	Aguardando liquidação	Contrato registrado e aguardando as datas previstas de liquidação das URs
5	Cancelado	Contrato oficialmente cancelado no regime de interoperabilidade. Ocorre também quando as URs rejeitadas impedem o contrato de atingir o valor solicitado
6	Em liquidação	Contrato obteve sua primeira liquidação de uma UR vinculada
7	Liquidado	Contrato obteve liquidações de todas as suas URs vinculadas
8	Em cancelamento	Solicitação de cancelamento recebida na plataforma e será encaminhada à registradora
9	Falha no cancelamento	Não foi possível cancelar o contrato no regime de interoperabilidade
10	Incluindo UR	Inclusão de UR em andamento no contrato já registrado
11	Substituindo URs	Substituição de URs em andamento — típico da recomposição de garantia
12	Processando contrato	Processamento interno em andamento. Estado transitório: aguarde a próxima atualização antes de novas ações

Os status 2, 8, 10, 11 e 12 são transitórios. Evite disparar novas ações sobre o contrato enquanto ele estiver em um desses estados.

---

🔢 Registradoras

Código	Nome
1	B3
2	Apresentação
3	Nuclea
4	CERC
5	TAG

---

📪 Exemplo de envio — troca de titularidade

VeFlow enviará uma requisição POST para o endpoint informado pelo cliente com o seguinte corpo:

POST /webhook/veflow HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Bearer {seu_token}
Idempotency-Key: 9f2c1b7e-5d84-4f3a-9c21-77bde1a4c5f0

{
  "tipoNotificacao": 2,
  "contrato": {
    "identificador": "19710560-04CD-4E48-881D-D38350B39079",
    "identificadorInteroperabilidade": ["0DC43268-E05F-478E-931C-A43B8B3DD79B"],
    "status": 4,
    "registradora": {
      "id": 1,
      "nome": "B3"
    }
  },
  "totais": {
    "taxa": 2.5000,
    "nominal": 50000.00,
    "desconto": 1500.00,
    "aquisicao": 48500.00,
    "garantido": 50000.00
  },
  "titulos": [
    {
      "id": "7D121577-3C5A-494D-B052-291D9E100D0D",
      "credenciadora": "11223344000155",
      "arranjo": "MCC",
      "status": 0,
      "dataPrevistaLiquidacao": "2025-08-10",
      "valorNominal": 1000.00,
      "valorGarantido": 1000.00,
      "valorDesconto": 50.00,
      "valorAquisicao": 950.00
    }
  ]
}

---

📪 Exemplo de envio — garantia

O mesmo contrato em fluxo de garantia chega sem os campos de cessão, porque não houve deságio:

POST /webhook/veflow HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Bearer {seu_token}
Idempotency-Key: 3ac41d90-2f77-4c0b-9a8e-6d5511ba7e42

{
  "tipoNotificacao": 2,
  "contrato": {
    "identificador": "5174568D-9FFE-4C10-9FC2-B0F4E7F8D1B6",
    "identificadorInteroperabilidade": ["A9F1C2D3-4455-6677-8899-AABBCCDDEEFF"],
    "status": 11,
    "registradora": {
      "id": 4,
      "nome": "CERC"
    }
  },
  "totais": {
    "garantido": 250000.00
  },
  "titulos": [
    {
      "id": "1C4D2288-77B6-4E31-9A05-33ADEF9012BB",
      "credenciadora": "10293847560102",
      "arranjo": "VCC",
      "status": 1000,
      "dataPrevistaLiquidacao": "2025-08-15",
      "valorGarantido": 1800.00
    }
  ]
}

---

🕒 Observações

• Esta notificação pode ser enviada várias vezes durante a evolução do contrato, sempre com a última posição conhecida. Trate cada envio como sobrescrita, não como delta — ver 3.0. Visão Geral.
• O status de cada UR ajuda a identificar falhas e pendências operacionais por UR. O valor 1000 (Em remoção) torna visível a janela entre o pedido de remoção e a confirmação da registradora: até a confirmação, a UR ainda consta no contrato e não deve ser reaproveitada.
• O status da UR não serve para identificar URs liquidadas: aquele enum é de vínculo e não possui valor de liquidada. Liquidação é assunto de 3.3. Atualizações da UR.
• Não existe CET no payload. O campo já esteve documentado, mas nunca existiu no retorno da API: a plataforma não apura IOF e, portanto, não calcula custo efetivo.
• Promessa de cessão nunca é criada pela API. Ela aparece apenas em leitura, como ônus de terceiro sobre a UR, reduzindo o valor disponível. Penhor é efeito legado, mantido só para leitura de contratos antigos.
• O registro e o cancelamento de contratos dependem da registradora e são processados apenas entre 09:00 e 18:00 em dias úteis. Fora dessa janela a solicitação é agendada, e a notificação só é disparada quando o processamento ocorre.
• O endpoint de recebimento deve estar apto a processar várias URs por envio e precisa ser idempotente — deduplique pelo header Idempotency-Key.
• Contratos gerados pela antecipação automática também produzem esta notificação, com o mesmo payload. A primeira chega quando a registradora responde (status 4 ou 3), não no instante da criação. Para identificá-los, cruze contrato.identificador com o identificadorContrato das execuções do ciclo ou use origemAgenda em 5.2. Listar contratos.
• Credenciais da API, headers obrigatórios e ambientes: 1.1. Primeiros Passos. Dúvidas de integração: contato@vertrau.capital.