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
`origemAgenda`	Contrato gerado pela antecipação automática
`situacaoItem`	Item do carrinho
`situacaoUrItem`	Resposta da chamada que aloca URs no item (não volta nas consultas)
`motivoUrIgnorada`	Resposta da chamada que aloca URs no item (não volta nas consultas)
`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
`situacaoConciliacao`	Processamento de liquidações (6.2)
`parcelas[].situacao`	Posição do contrato (7.1)
`creditos[].origem`	Extrato de conciliação da UR (7.3)
`creditos[].situacao`	Extrato de conciliação da UR (7.3)
`efeitos[].situacao`	Extrato de conciliação da UR (7.3)
`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
0	Em processamento
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
6	Vencida (a `dataValidade` passou)

O código 3 indica promessa de cessão registrada sobre qualquer UR do período: é ônus de terceiro, aparece apenas em leitura e reduz o valorLivre. O código 4 significa somente que a agenda ultrapassou o tempo de publicação. Quando mais de uma situação se aplica, vale a primeira desta ordem: 0, 5, 2, 4, 6, 3, 1 — por isso uma agenda vencida com promessa de cessão aparece como 6. Quando statusAgenda = 5, o campo motivoFalha traz a descrição do erro; nos demais casos vem vazio ou null.

Na v1 e no webhook 1 (Listagem de URs) das assinaturas v1, statusAgenda segue de 1 a 5; os estados internos vêm null. Os códigos 0 e 6 existem somente na v1.1.

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?".

Código	Descrição
1	Aguardando — a UR está dentro do prazo e sem nenhuma informação de crédito ainda. Estado inicial.
2	Anunciada — o pagamento da UR foi anunciado pela credenciadora ou registradora, mas o dinheiro não entrou.
3	Liquidada parcialmente — parte do valor foi creditada e conciliada; o restante segue em aberto.
4	Liquidada — valor integral creditado e conciliado. Ciclo de caixa encerrado para esta UR.
5	Não liquidada — a data prevista passou e não houve crédito compatível no último processamento do dia.
6	Em análise — divergência entre o valor esperado e o creditado, em apuração (chargeback, ajuste da credenciadora, crédito de terceiro).
7	Não aplicável — a UR não gera expectativa de caixa neste contrato (vínculo com falha, cancelado ou em remoção).

A documentação anterior publicava pelo nome

A documentação anterior informava statusLiquidacao como texto, com o nome do estado (por exemplo, Aguardando). O campo é numérico, com os códigos de 1 a 7 acima. Quem desserializa o campo como texto quebra: refaça o mapeamento pelo código. Isso vale para as rotas v1.1; os webhooks das assinaturas v1 seguem o formato descrito na seção 3.

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 em 1 (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.

🔢 origemAgenda¶

De onde veio a agenda de recebíveis que originou um contrato gerado pela antecipação automática.

Código	Descrição
1	BATCH
2	ONLINE

⚠️ Não confunda com origem. origem é do item do carrinho e responde "de onde este item entrou"; origemAgenda é do contrato automático e responde "de qual agenda o ciclo tirou as URs". São enumerações distintas, com domínios distintos.

origemAgenda vem null em contratos criados manualmente ou por API — só é preenchido nos gerados pelo ciclo automático. A configuração e o histórico do ciclo estão em Antecipação automática de cartão, onde também ficam as demais enumerações do recurso (status da execução, motivoNaoContratacao, status e escopo do processamento de taxa).

🔢 situacaoItem¶

Situação do item do carrinho.

Código	Descrição
1	Em montagem
2	Contratado
3	Invalidado

🔢 situacaoUrItem¶

Situação de cada UR dentro do item do carrinho.

Código	Descrição
1	Alocada
2	Ignorada

Quando situacaoUrItem = 2, o motivo vem em motivoUrIgnorada.

🔢 motivoUrIgnorada¶

Motivo pelo qual a UR ficou fora do item do carrinho. Preenchido quando situacaoUrItem = 2 (Ignorada). A UR ignorada não é gravada no item: ela aparece, com o motivo, só na resposta da chamada que fez a alocação (como 4.10 e 4.16); as consultas do carrinho e do item não a trazem.

Código	Descrição
1	Sem valor disponível
2	Já alocada em outro item
3	Não performada
4	Fora da agenda

🔢 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	Penhor
4	Promessa de cessão

Os códigos 3 e 4 estavam invertidos na documentação anterior

A documentação anterior publicava 3 = Promessa de cessão e 4 = Penhor. O correto é 3 = Penhor e 4 = Promessa de cessão. Quem mapeou pela documentação anterior lê o 3 como promessa de cessão sem nenhum erro: refaça o mapeamento de valores.

Promessa de cessão e penhor

Promessa de cessão (tipoEfeito = 4) 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 = 3) é 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.

🔢 situacaoConciliacao¶

Situação do crédito na conciliação, devolvida no processamento do lote de liquidações (6.2. Consultar processamento de liquidações, campo itens[].situacaoConciliacao).

Código	Descrição
1	Conciliada
2	Não conciliada
3	Conciliada parcialmente

🔢 Situação da parcela — `parcelas[].situacao`¶

Situação de cada parcela do contrato frente ao crédito recebido, devolvida na posição do contrato (7.1. Posição do contrato).

Código	Descrição
1	Em aberto
2	Parcialmente coberta
3	Coberta
4	Vencida em aberto

🔢 Origem do crédito — `creditos[].origem`¶

Origem do dado de liquidação de cada crédito atribuído à UR, devolvida no extrato de conciliação da UR (7.3. Extrato de conciliação da UR).

Código	Descrição
1	Conciliação da movimentação bancária
2	Baixa da UR cedida ao fundo
3	Ajuste da operação

⚠️ Não confunda com origem. origem é do item do carrinho (1 a 4) e responde "de onde este item entrou"; creditos[].origem é do extrato de conciliação da UR e responde "de onde veio o dado deste crédito". São enumerações distintas, com domínios distintos.

🔢 Situação do crédito — `creditos[].situacao`¶

Situação da conciliação de cada crédito atribuído à UR, devolvida no extrato de conciliação da UR (7.3. Extrato de conciliação da UR).

Código	Descrição
1	Pendente de atribuição
2	Conciliado parcialmente
3	Conciliado
4	Estornado — não produzido nesta versão
5	Atribuição ambígua

Ordem diferente da de situacaoConciliacao

A situação do crédito no extrato da UR (creditos[].situacao: 1 Pendente de atribuição, 2 Conciliado parcialmente, 3 Conciliado) e a situacaoConciliacao do processamento de liquidações (1 Conciliada, 2 Não conciliada, 3 Conciliada parcialmente) têm ordens diferentes. Não reaproveite o mapeamento de uma na outra.

🔢 Situação do efeito — `efeitos[].situacao`¶

Situação de cada efeito (ônus) registrado sobre a UR, devolvida no extrato de conciliação da UR (7.3. Extrato de conciliação da UR).

Código	Descrição
1	Ativo
2	Liquidado
3	Cancelado

🔢 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 em ProblemDetails — ver 1.2. Convenções da API —, 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.