8.1. Enumerações¶

Referência única

Esta página é a referência única das enumerações da API de cartão de crédito da plataforma VeFlow. As páginas de endpoint e de webhook apontam para cá em vez de repetir as tabelas — o código e o significado de cada valor são mantidos aqui.

Não existe endpoint de enumeração nesta API: os valores abaixo fazem parte do contrato da API e devem ser mapeados no seu sistema. Todas as rotas que consomem ou devolvem esses valores partem da base https://api.veflow.com/public/api/v1.1/cartao.

📚 Índice¶

Enumeração	Onde aparece
`tipoContrato`	Item do carrinho, contrato, filtros de listagem
`estrategia`	Item do carrinho
`statusAgenda`	Agenda de recebíveis e webhook de listagem de URs
`statusContrato`	Contrato e webhook de atualizações do contrato
`statusSolicitacao`	UR dentro do contrato — eixo de vínculo na registradora
`statusLiquidacao`	UR dentro do contrato — eixo de caixa
`tipoValor`	Retenção da fumaça, alocação de URs no item
`tipoPerformance`	Personalização de performance do item
`tipoAlertaPerformance`	Item do carrinho
`origem`	Item do carrinho
`motivoCancelamento`	Cancelamento de contrato
`motivoRejeicao`	URs rejeitadas do contrato
`tipoEfeito` / `tipoOnus`	Efeitos (ônus) registrados sobre a UR
`eventoConciliacao`	Webhook de atualizações da UR
`tipoDivergencia`	Divergências da conciliação
`tipoNotificacao`	Todos os webhooks
`registradoras`	Contrato e webhook de atualizações do contrato

🔢 tipoContrato¶

Natureza do contrato que o item do carrinho vai compor.

Código	Descrição
1	Troca de titularidade
2	Garantia

Só existem esses dois valores

Fumaça não é tipo de contrato — é configuração da garantia (tipoContrato = 2 mais o bloco fumaca: prazo estendido, uso somente de URs performadas e regra de retenção).

Promessa de cessão nunca é criada pela API: não existe endpoint que a registre. Ela aparece apenas em leitura, como ônus de terceiro sobre a UR.

Penhor é legado: pode aparecer na leitura de registros antigos e não é gerado por nenhuma operação atual da plataforma.

Em tipoContrato = 1 há cessão das URs ao fundo, portanto há deságio (taxa) e os valores valorNominal, valorDesconto e valorAquisicao. Em tipoContrato = 2 não há cessão nem deságio: o item e o contrato trabalham apenas com valorGarantido.

🔢 estrategia¶

Como as URs do item do carrinho são escolhidas.

Código	Descrição
1	URs selecionadas
2	Split por valor desejado
3	Troca por valor desejado
4	Alocação automática por parcela

Migração da v1: revise o mapeamento, não só o nome

Na v1 este eixo se chamava tipoVinculo e usava 1 = por valor e 2 = por UR específica. Em estrategia, 1 = URs selecionadas e 2 = split por valor desejado — ou seja, os valores 1 e 2 tinham significado invertido.

Quem apenas renomeia o campo passa a enviar a estratégia oposta, sem nenhum erro de validação. Refaça o mapeamento de valores, não apenas o nome do campo.

Os nomes acao e tipoVinculo não existem nesta versão da API. O eixo é sempre estrategia.

🔢 statusAgenda¶

Resultado da consulta da agenda de recebíveis.

Código	Descrição
1	Agenda disponível
2	Agenda vazia
3	Agenda com promessa de cessão
4	Agenda ultrapassou tempo de publicação
5	Agenda com falha

O código 3 indica promessa de cessão registrada sobre as URs do período: é ônus de terceiro, aparece apenas em leitura e reduz o valorLivre. Quando statusAgenda = 5, o campo motivoFalha traz a descrição do erro; nos demais casos vem vazio ou null.

Enumeração homônima em outro produto

statusAgenda também existe na Duplicata Escritural, com outros significados no mesmo espaço numérico — ver 8.2. Enumerações homônimas entre produtos.

🔢 statusContrato¶

Estado do contrato de recebíveis.

Código	Descrição
1	Aguardando registro
2	Registrando
3	Falha no registro
4	Aguardando liquidação
5	Cancelado
6	Em liquidação
7	Liquidado
8	Em cancelamento
9	Falha no cancelamento
10	Incluindo UR
11	Substituindo URs
12	Processando contrato

A documentação anterior listava apenas de 1 a 9

Os códigos 10 (Incluindo UR), 11 (Substituindo URs) e 12 (Processando contrato) passaram a ser documentados: são doze status. Integrações que tratavam apenas 1 a 9 precisam aceitar os três novos valores.

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

Enumeração homônima em outro produto

statusContrato também existe na Duplicata Escritural, com outros significados no mesmo espaço numérico — ver 8.2. Enumerações homônimas entre produtos.

🔢 statusSolicitacao¶

Estado do vínculo da UR na registradora. Responde à pergunta "a registradora aceitou esta UR neste contrato?".

Código	Descrição
0	Sucesso
1	Falha
2	Em processamento
3	Pendente extensão
999	Cancelada
1000	Em remoção

1 (Falha) preenche motivoRejeicao e deixa valorGarantido em 0.00. 2 é estado transitório de envio à registradora. 3 é típico da garantia fumaça, cujo vínculo depende da prorrogação do prazo do contrato. 999 significa vínculo desfeito por cancelamento do contrato ou por remoção já confirmada.

O valor 1000 não era documentado

1000 (Em remoção) nunca havia sido documentado. Ele torna visível a janela entre o pedido de remoção da UR e a confirmação da registradora: enquanto não confirmada, a UR continua constando no contrato e não deve ser reaproveitada.

🔢 statusLiquidacao¶

Estado de caixa da UR, apurado pela conciliação bancária. Responde à pergunta "o dinheiro entrou?". Os valores são informados e devolvidos pelo nome.

Valor	Descrição
Aguardando	UR dentro do prazo e sem nenhuma informação de crédito ainda. Estado inicial.
Anunciada	O pagamento da UR foi anunciado pela credenciadora ou registradora, 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.

statusSolicitacao e statusLiquidacao são eixos diferentes

statusSolicitacao responde se a registradora aceitou a UR no contrato; statusLiquidacao responde se o dinheiro entrou. Os dois 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 ter tido o vínculo removido depois. Leia sempre os dois campos juntos.

A documentação anterior afirmava que o status da UR servia para identificar as URs liquidadas. Isso estava incorreto: aquele enum é de vínculo (statusSolicitacao), não de caixa. Para saber o que foi liquidado, use statusLiquidacao.

statusLiquidacao tem a mesma semântica nos dois fluxos, antecipação e garantia. Muda apenas a origem do dado: em troca de titularidade o crédito é esperado na conta do cessionário; em garantia, na conta do EC ou na conta vinculada.

🔢 tipoValor¶

Como um valor informado deve ser interpretado (retenção da fumaça, alocação de UR no item).

Código	Descrição
1	Valor fixo
2	Percentual

Quando tipoValor = 2, o valor deve estar entre 0 e 100.

🔢 tipoPerformance¶

Como a performance personalizada do item é interpretada.

Código	Descrição
1	Valor fixo por UR
2	Percentual por UR

Só é exigido quando a personalização de performance está ativa no item. Quando tipoPerformance = 2, o valor deve estar entre 0 e 100.

🔢 tipoAlertaPerformance¶

Alerta de performance do item do carrinho. Vem null quando não há alerta.

Código	Descrição
1	Contrato não performado
2	Contrato performado parcialmente

1 indica que nenhuma UR do item atende à performance esperada; 2, que parte das URs atende e o restante ficou descoberto.

🔢 origem¶

De onde o item entrou no carrinho.

Código	Descrição
1	URs selecionadas
2	Split por valor desejado
3	Troca por valor desejado
4	Parcela de garantia

estrategia diz como o item foi composto; origem diz de onde ele entrou no carrinho. Os valores 1 a 3 coincidem entre as duas enumerações; o 4 difere: estrategia = 4 é a alocação automática, origem = 4 é a parcela de garantia que disparou essa alocação.

🔢 motivoCancelamento¶

Motivo do cancelamento do contrato.

Código	Descrição
1	Valor solicitado não atingido
2	Falha ao vincular URs
3	Cancelamento manual
4	Outros
5	Falha no envio ao fundo

Somente os códigos de 1 a 5 são aceitos; qualquer outro valor é recusado com 400 Bad Request. Recomenda-se preencher a descrição livre sempre que o motivo for 4 (Outros), para rastreabilidade da operação.

🔢 motivoRejeicao¶

Motivo da rejeição da UR. Preenchido somente quando statusSolicitacao = 1 (Falha); null nos demais casos.

Código	Descrição
1	Falha ao vincular ao contrato
2	Não performado corretamente

1 cobre as recusas da registradora ao vínculo (valor livre insuficiente, ônus concorrente, UR inexistente ou já comprometida). 2 é recusa típica da garantia fumaça, que só aceita URs performadas.

🔢 tipoEfeito e tipoOnus¶

tipoEfeito descreve a natureza do ônus registrado sobre a UR.

Código	Descrição
1	Troca de titularidade
2	Cessão fiduciária
3	Promessa de cessão
4	Penhor

Promessa de cessão e penhor

Promessa de cessão (tipoEfeito = 3) aparece somente em leitura e sempre como ônus de terceiro (tipoOnus = 2). Ela nunca pode ser criada: não existe endpoint que registre promessa de cessão.

Penhor (tipoEfeito = 4) é legado. Pode aparecer em URs com histórico antigo e não é gerado por nenhuma operação atual da plataforma VeFlow.

tipoOnus descreve a origem do ônus, ou seja, de quem é o contrato que onerou a UR.

Código	Descrição
1	Próprio — contrato do seu grupo econômico
2	Terceiro — contrato de outra instituição

Em tipoOnus = 2 o documento do titular vem mascarado, porque o contrato pertence a terceiro. Um array de efeitos vazio ([]) significa UR livre de ônus.

🔢 eventoConciliacao¶

Último evento detectado na conciliação da UR, enviado no webhook de atualizações da UR.

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

O código 2 cobre chargeback e ajuste da credenciadora. Os eventos 3 e 4 são disparados somente quando a plataforma já possui os dados de crédito bancário, e o evento 3 apenas no último processamento do dia (19:00).

🔢 tipoDivergencia¶

Tipo da divergência apurada pela conciliação entre o que a agenda anunciou e o que entrou em conta.

Código	Descrição
1	Agenda sem crédito
2	Crédito sem agenda
3	Valor abaixo do esperado
4	Valor acima do esperado
5	Redução de posição da agenda
6	Atribuição ambígua
7	Data fora do esperado

1 é apurada somente na última rodada de conciliação do dia (19:00). Em 2 a UR e o contrato vêm null, porque não há linha de agenda correspondente. 5 decorre de chargeback da venda ou ajuste da credenciadora depois do registro do contrato. 6 bloqueia a conciliação daquele crédito até o desempate, para não liquidar a UR errada.

🔢 tipoNotificacao¶

Identifica qual webhook chegou. Está sempre na raiz do payload e é o campo usado para rotear o processamento.

Código	Descrição
1	Listagem de URs
2	Atualizações do contrato
3	Atualizações da UR

Todas as notificações chegam na mesma URL de callback: não existe URL por tipo. Ver 3.0. Visão Geral.

🔢 registradoras¶

Registradora responsável pelo registro do contrato.

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

🕒 Observações¶

Trate qualquer código desconhecido como valor futuro: registre a ocorrência e mantenha o recurso em estado neutro, em vez de rejeitar o payload. Novos códigos podem ser acrescentados a estas enumerações.
Filtros de listagem que recebem código inválido respondem 400 Bad Request no padrão RFC 9110 (tipo, titulo, status, erros), com a lista de valores aceitos na mensagem de erro.
valorConstituido, valorComprometido, valorLivre e valorDisponivel pertencem à fase de agenda; valorGarantido, à fase de carrinho e contrato; valorNominal, valorDesconto e valorAquisicao existem somente em antecipação (troca de titularidade), porque só ali houve cessão ao fundo. Garantia não tem deságio e nunca traz esses valores nem taxa.
Enumerações com o mesmo nome em outros produtos da Vertrau não têm o mesmo significado — ver 8.2. Enumerações homônimas entre produtos.
Headers obrigatórios e convenções gerais: 1.1. Primeiros Passos.
Dúvidas sobre um código não listado aqui: contato@vertrau.capital.