--- title: 8.1. Enumerações url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/8.%20Enumera%C3%A7%C3%B5es/8.1.%20Enumera%C3%A7%C3%B5es/ --- # 8.1. Enumerações !!! note "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 | !!! warning "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 | !!! warning "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`. !!! warning "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](8.2.%20Enumerações%20homônimas%20entre%20produtos.md). --- ## 🔢 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 | !!! warning "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. !!! warning "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](8.2.%20Enumerações%20homônimas%20entre%20produtos.md). --- ## 🔢 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. !!! warning "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. | !!! warning "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 | !!! warning "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](../3.%20Notificações%20-%20WebHook/3.0.%20Visão%20Geral.md). --- ## 🔢 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](8.2.%20Enumerações%20homônimas%20entre%20produtos.md). * Headers obrigatórios e convenções gerais: [1.1. Primeiros Passos](../1.%20Início/1.1.%20Primeiros%20Passos.md). * Dúvidas sobre um código não listado aqui: [contato@vertrau.capital](mailto:contato@vertrau.capital).