3.3. Atualizações das URs¶

🔔 Tipo de Notificação¶

Campo	Valor	Significado
tipoNotificacao	`3`	Atualização das URs baseada na conciliação bancária

🧾 Descrição¶

Esta notificação é enviada via POST sempre que a plataforma conclui o processo de conciliação bancária das URs de um contrato. Ela traz a posição atualizada de cada UR, comparando o que foi creditado em conta com o que estava registrado no contrato.

É especialmente útil em situações de chargeback, liquidação parcial, mudança de prioridade e ajustes automáticos de posição — inclusive nos contratos de garantia com configuração de fumaça (prazo estendido, somente URs performadas e regra de retenção). Fumaça não é um tipo de contrato: tipoContrato continua com valor 2 (Garantia).

Esta é a notificação da fase de caixa. O detalhe linha por linha do que a agenda anunciou, quais créditos chegaram e quais ônus existiam sobre a UR está em 7.3. Extrato de conciliação da UR; os casos que não fecharam ficam listados em 7.4. Divergências.

📤 Payload Enviado¶

{
  "tipoNotificacao": 3,
  "contrato": {
    "identificador": "19710560-04CD-4E48-881D-D38350B39079",
    "identificadorInteroperabilidade": ["0DC43268-E05F-478E-931C-A43B8B3DD79B"],
    "status": 4
  },
  "titulos": [
    {
      "id": "7D121577-3C5A-494D-B052-291D9E100D0D",
      "credenciadora": "",
      "arranjo": "",
      "statusSolicitacao": 0,
      "statusLiquidacao": "Aguardando",
      "evento": 1,
      "dataPrevistaLiquidacao": "",
      "valor": 0.00,
      "valorChargeback": 0.00,
      "valorLiquidado": 0.00,
      "identificadorMovimentacao": [""]
    }
  ]
}

🧾 Detalhamento dos Campos¶

Campo	Tipo	Descrição
tipoNotificacao	integer	Tipo `3` = Atualização por conciliação
contrato.identificador	string	GUID referente ao identificador do contrato
contrato.identificadorInteroperabilidade	string[]	GUID gerado no ambiente de interoperabilidade do contrato
contrato.status	number	Status do contrato (ver tabela Status do contrato abaixo)
titulos[].id	string	GUID da UR
titulos[].credenciadora	string	CNPJ da credenciadora (somente números)
titulos[].arranjo	string	Sigla do arranjo (ex.: `MCC`, `VCC`)
titulos[].statusSolicitacao	integer	Estado do vínculo da UR na registradora (ver tabela statusSolicitacao)
titulos[].statusLiquidacao	string	Estado de caixa da UR, apurado na conciliação (ver tabela statusLiquidacao)
titulos[].evento	integer	Último evento detectado na conciliação (ver tabela Eventos de Conciliação)
titulos[].dataPrevistaLiquidacao	string	Data prevista de liquidação da UR, no formato `YYYY-MM-DD`
titulos[].valor	number	Valor atual da UR após a conciliação
titulos[].valorChargeback	number	Valor de diferença detectado na conciliação (chargeback ou ajuste da credenciadora)
titulos[].valorLiquidado	number	Valor efetivamente creditado. Preenchido nos eventos `3` e `4`
titulos[].identificadorMovimentacao	string[]	Identificadores de movimentação utilizados para conciliar o valor pago da UR

🔀 Os Dois Eixos de Status da UR¶

Cada UR carrega dois status independentes, e essa é a informação mais importante desta página:

Campo	Pergunta que responde	Natureza
`statusSolicitacao`	A registradora aceitou esta UR neste contrato?	Estado do vínculo na registradora
`statusLiquidacao`	O dinheiro entrou?	Estado de caixa, apurado na conciliação

São eixos diferentes e não se substituem: uma UR pode ter vínculo perfeito (statusSolicitacao = 0) e ainda estar Aguardando o crédito; e pode ter o crédito integral em conta e, mesmo assim, ter tido o vínculo removido depois. Leia sempre os dois campos juntos.

Correção em relação à documentação anterior: a versão antiga afirmava que o status da UR servia para identificar URs liquidadas. Isso estava incorreto — aquele enum é de vínculo e não possui valor de liquidada. Liquidação sempre foi apurada em outro eixo. A partir da v1.1 existem dois campos explícitos, um para cada eixo.

🔢 statusSolicitacao — estado do vínculo¶

Código	Significado	Aplicação
0	Sucesso	Vínculo aceito pela registradora. A UR está efetivamente dentro do contrato
1	Falha	A registradora recusou o vínculo desta UR. A UR não gera expectativa de caixa
2	Em processamento	Vínculo enviado à registradora, aguardando retorno. Estado transitório
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

🔢 statusLiquidacao — estado de caixa¶

Valor	Significado
Aguardando	UR dentro do prazo e sem nenhuma informação de crédito ainda. Estado inicial
Anunciada	O pagamento da UR foi anunciado (credenciadora ou registradora informou a expectativa de crédito), mas o dinheiro não entrou
LiquidadaParcialmente	Parte do valor foi creditada e conciliada; o restante segue em aberto
Liquidada	Valor integral creditado e conciliado. Ciclo de caixa encerrado para esta UR
NaoLiquidada	A data prevista passou e não houve crédito compatível no último processamento do dia
EmAnalise	Divergência entre o valor esperado e o creditado, em apuração (chargeback, ajuste da credenciadora, crédito de terceiro)
NaoAplicavel	A UR não gera expectativa de caixa neste contrato — vínculo com falha, cancelado ou em remoção

statusLiquidacao tem a mesma semântica nos dois fluxos, antecipação e garantia. Os valores, as transições e o significado de cada um são idênticos; muda apenas a origem do dado:

Em troca de titularidade (tipoContrato = 1), o crédito é esperado na conta do cessionário, porque a UR foi cedida ao fundo, e a liquidação é apurada na baixa do recebível.
Em garantia (tipoContrato = 2), o crédito ocorre na conta do EC ou na conta vinculada, e a conciliação da movimentação bancária com a agenda serve para comprovar o cumprimento da garantia.

Em nenhum dos dois casos o enum muda. Se o seu sistema já trata statusLiquidacao para antecipação, o mesmo tratamento vale para garantia.

🔢 Lendo os dois eixos juntos¶

statusSolicitacao	statusLiquidacao	Leitura
0 Sucesso	Aguardando	UR vinculada e saudável; o crédito ainda não chegou
0 Sucesso	LiquidadaParcialmente	Vínculo em ordem, parte do dinheiro entrou; verifique `valorChargeback`
0 Sucesso	Liquidada	Ciclo completo: vínculo aceito e caixa realizado
0 Sucesso	EmAnalise	Vínculo em ordem, valor divergente. Caso listado em 7.4. Divergências
3 Pendente extensão	Aguardando	UR presa à prorrogação do prazo (fumaça); o caixa depende da extensão
1 Falha	NaoAplicavel	A UR não entrou no contrato
1000 Em remoção	Aguardando	Remoção em andamento; a UR ainda consta e não deve ser reaproveitada
999 Cancelada	NaoAplicavel	Vínculo desfeito. O registro permanece apenas para auditoria

🔢 Eventos de Conciliação¶

Código	Significado
1	Valor da UR aumentou
2	Valor da UR reduziu (chargeback ou ajuste)
3	UR liquidada parcialmente ou não liquidada
4	UR liquidada completamente
5	Prioridade na liquidação da UR reduziu
6	Prioridade na liquidação da UR aumentou

Os eventos 3 e 4 somente são disparados quando a plataforma possui os dados de crédito bancário (liquidação).

O evento 3 somente é disparado no último processamento do dia do processo de conciliação (19h). Antes disso, uma UR vencida sem crédito não é classificada como não liquidada, porque o crédito ainda pode chegar.

Os eventos 5 e 6 refletem mudança de prioridade na liquidação da UR: quando o crédito recebido não cobre a soma dos ônus incidentes, os efeitos de menor prioridade ficam descobertos. A ordem de precedência vigente aparece em 7.3. Extrato de conciliação da UR.

🔢 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
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

💳 `identificadorMovimentacao` e o Envio dos Créditos¶

O array identificadorMovimentacao é o elo entre a conciliação e os créditos que o próprio cliente enviou.

Os créditos em conta são informados à plataforma pelo endpoint de liquidações:

Método	URL
	`/public/api/v1.1/cartao/liquidacoes`

Cada crédito enviado nesse lote carrega o seu identificador de movimentação. A conciliação tenta casar esses créditos com as URs dos contratos (por data, EC, credenciadora, arranjo e valor). Os identificadores que a plataforma conseguiu casar com aquela UR são exatamente os que voltam aqui, em identificadorMovimentacao.

Leitura prática:

Lista preenchida: cada elemento é um crédito seu que foi atribuído a esta UR. Um mesmo crédito pode ser rateado entre várias URs, e uma UR pode ser coberta por vários créditos.
Lista vazia ([]): nenhum pagamento foi encontrado para a UR. Ou o crédito ainda não foi enviado, ou não houve casamento com nenhuma movimentação recebida.
Para ver o rateio linha por linha (valor total do crédito e quanto dele foi atribuído a esta UR), consulte 7.3. Extrato de conciliação da UR.
Créditos pendentes de atribuição ou com atribuição ambígua ficam na fila de exceções — ver 7.4. Divergências.

📪 Exemplo de envio¶

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": 3,
  "contrato": {
    "identificador": "19710560-04CD-4E48-881D-D38350B39079",
    "identificadorInteroperabilidade": ["0DC43268-E05F-478E-931C-A43B8B3DD79B"],
    "status": 4
  },
  "titulos": [
    {
      "id": "7D121577-3C5A-494D-B052-291D9E100D0D",
      "credenciadora": "11223344000155",
      "arranjo": "MCC",
      "statusSolicitacao": 0,
      "statusLiquidacao": "Liquidada",
      "evento": 4,
      "dataPrevistaLiquidacao": "2025-08-10",
      "valor": 1000.00,
      "valorChargeback": 0.00,
      "valorLiquidado": 1000.00,
      "identificadorMovimentacao": ["1B428B23-C0A8-46D5-AF2C-1AFFAFAAC653"]
    },
    {
      "id": "1C4D2288-77B6-4E31-9A05-33ADEF9012BB",
      "credenciadora": "10293847560102",
      "arranjo": "VCC",
      "statusSolicitacao": 0,
      "statusLiquidacao": "LiquidadaParcialmente",
      "evento": 2,
      "dataPrevistaLiquidacao": "2025-08-10",
      "valor": 950.00,
      "valorChargeback": 50.00,
      "valorLiquidado": 700.00,
      "identificadorMovimentacao": ["9C55D0B1-77A4-4F2E-9C0B-3D51A2E9B7A2"]
    }
  ]
}

🕒 Observações¶

Esta notificação representa a posição conciliada da UR e pode ser enviada mais de uma vez, sempre refletindo a última posição conhecida. Trate cada envio como sobrescrita, não como delta — ver 3.0. Visão Geral.
Os campos valorChargeback e valorLiquidado são essenciais para auditoria e controle de caixa.
O campo identificadorMovimentacao vem como lista vazia quando nenhum pagamento referente àquela UR é encontrado. Ex.: "identificadorMovimentacao": [].
O evento 3 é disparado somente no último processamento do dia do processo de conciliação (19h). Os eventos 3 e 4 dependem de a plataforma já possuir os dados de crédito bancário.
Os créditos em conta devem ser enviados após as 10:05, por causa do processamento batch das agendas às 10:00 — ver 6.1. Envio dos créditos em conta.
statusSolicitacao e statusLiquidacao são eixos independentes. Não use o status de vínculo para concluir que uma UR foi liquidada: esse enum não tem valor de liquidada.
URs canceladas, rejeitadas ou removidas continuam aparecendo nas consultas de contrato para fins de auditoria — ver 5.4. Listar URs do contrato.
Garantia não tem deságio: esta notificação nunca traz valor nominal, desconto, aquisição nem taxa. Esses valores existem somente em antecipação (troca de titularidade) — ver 3.2. Atualizações do contrato.
O endpoint de recebimento deve estar apto a processar várias URs por envio e precisa ser idempotente — deduplique pelo header Idempotency-Key.
Credenciais da API, headers obrigatórios e ambientes: 1.1. Primeiros Passos. Dúvidas de integração: contato@vertrau.capital.