2.1. Conceitos¶
Todos os conceitos serão apresentados nesta documentação para facilitar o entendimento sobre os termos que serão utilizados nas próximas seções.
O dicionário abaixo reúne tanto os termos do mercado de recebíveis de cartão quanto os termos do modelo de dados da API VeFlow na v1.1 — agenda, carrinho, item, contrato e efeito.
📖 Dicionário¶
| Termo | Descrição |
|---|---|
| Agenda | Resultado da consulta das URs de um EC junto às registradoras, para um período e um conjunto de arranjos e credenciadoras. A agenda tem prazo de validade: depois de vencida, os itens montados sobre ela são invalidados e é necessário refazer a consulta. |
| Ambiente de Interoperabilidade | Ambiente de interoperabilidade conecta registradoras diferentes para garantir consultas e travas de recebíveis entre elas. |
| APIIMF | Entidade autorreguladora criada pelas principais registradoras (B3, CERC, Núclea e TAG) para organizar, padronizar e supervisionar o funcionamento das plataformas de registro de recebíveis, principalmente no mercado de cartões de crédito. |
| Arranjo de Pagamento | Arranjo é o conjunto de regras e estrutura que permite uma transação com cartão acontecer — como uma bandeira (Visa, Master, Elo) operando no débito ou no crédito. |
| Carrinho | Conjunto de itens montados sobre uma agenda. Uma agenda tem um carrinho; o carrinho tem N itens; cada item vira um contrato. |
| Cessão fiduciária | Efeito de ônus em que a UR é dada em garantia sem mudar de titularidade. É o efeito das operações de garantia (tipoContrato = 2). |
| Chargeback | Estorno de uma transação que reduz o valor da UR depois de ela ter sido constituída. |
| Conciliação | Processo de casar o crédito efetivamente recebido em conta com a UR que a agenda anunciou. |
| Contrato | Instrumento registrado na registradora que produz um efeito sobre as URs. Cada item do carrinho dá origem a um contrato. |
| Credenciadora | Credenciadora (ou adquirente) é quem viabiliza pagamentos por cartão nas maquininhas (ex: Cielo, Rede). |
| Data de liquidação | Data em que o valor da UR será creditado na conta do EC |
| Efeito de contrato | O que o contrato faz com a UR na registradora: troca de titularidade ou ônus. |
| Estabelecimento Comercial (EC) | Estabelecimento é a loja que efetuou a venda no cartão de crédito/débito |
| Fumaça | Modalidade de garantia com prazo estendido, que retém um percentual ou valor das URs futuras conforme elas vão sendo constituídas, em vez de nomear URs específicas. ⚠️ Fumaça não é um tipo de contrato: é uma configuração da garantia. O campo tipoContrato tem somente dois valores — 1 = Troca de titularidade e 2 = Garantia. |
| ID efeito Contrato | ID de Efeito de Contrato é o número que permite que registradoras diferentes reconheçam o mesmo contrato. Permite consulta e controle do contrato em qualquer registradora. Garante que URs (Unidades de Recebíveis) estejam corretamente vinculadas e travadas. É essencial no ambiente de interoperabilidade — todas as ações cruzadas usam esse ID. |
| Item do carrinho | Uma intenção de contrato: o tipo (tipoContrato), a estratégia de seleção (estrategia), os parâmetros comerciais e as URs alocadas. |
| Ônus | Gravame sobre a UR que limita seu uso por terceiros. Pode ser próprio (constituído pela própria operação) ou de terceiro (constituído por outro financiador). |
| Opt-in | Autorização do EC para que a plataforma consulte a agenda dele nas registradoras. |
| Promessa de cessão | Ônus que sinaliza compromisso futuro de cessão. Só é orquestrável via credenciadora e nunca é criada nesta API: aparece aqui apenas em leitura, como ônus de terceiro sobre a UR. |
| Registradoras | Registradora garante e controla os valores das vendas no cartão, como um cartório digital financeiro. (ex: B3, CERC, Núclea e TAG) |
| Resilição | Encerramento antecipado do efeito de um contrato sobre as URs. |
| SLC | Sistema de Liquidação de Cartões, origem dos arquivos de crédito usados na conciliação. |
| Troca de titularidade | Efeito em que a titularidade da UR passa ao financiador. É o efeito das operações de antecipação (tipoContrato = 1), com cessão ao fundo. |
| Unidade de Recebível (UR) | A Unidade de Recebível (UR) representa um valor que uma loja (estabelecimento comercial) tem a receber de uma venda feita no cartão. 🔑 As 4 informações essenciais para gerar uma UR: - Data de liquidação - Arranjo - Credenciadora - Estabelecimento Comercial (EC) |
| UR performada | UR cuja venda já ocorreu e cujo valor está constituído na registradora, em oposição ao valor ainda a constituir. |
🔗 Como os conceitos se encadeiam¶
O fluxo da v1.1 percorre os conceitos sempre nesta ordem:
- Opt-in do EC autoriza a consulta.
- A consulta produz uma agenda com as URs do período.
- Sobre a agenda monta-se o carrinho, com um ou mais itens do carrinho.
- Cada item é registrado como um contrato, que produz um efeito sobre as URs: troca de titularidade (antecipação) ou cessão fiduciária (garantia).
- Depois da liquidação, a conciliação confronta o crédito recebido com a UR anunciada, considerando eventuais chargebacks.
⚠️ Fumaça não é um tipo de contrato e promessa de cessão nunca é criada por esta API. Os únicos valores de
tipoContratosão1= Troca de titularidade e2= Garantia. Penhor é legado e, como a promessa de cessão, aparece somente em leitura, na forma de ônus de terceiro.
🤖 Antecipação automática¶
O encadeamento acima descreve o fluxo conduzido pelo integrador, em que cada etapa é uma chamada de API. Existe também um modo em que VeHub percorre esse mesmo caminho sozinho, todo dia útil: a antecipação automática.
Habilitado o cedente, o ciclo diário busca a agenda, monta o carrinho e registra o contrato sem nenhuma chamada de API. O integrador só configura uma vez e depois consulta o resultado.
Duas travas controlam o recurso:
- Habilitação do ambiente — feita pelo time de implantação. Sem ela, os endpoints de configuração retornam
403. - Habilitação do cedente na operação — feita por API, informando taxa, valores, arranjos e credenciadoras.
O ciclo prefere sempre a agenda BATCH do dia, publicada uma vez por dia útil pela registradora, e só solicita uma agenda ONLINE quando a BATCH ainda não saiu no horário da execução. A origem usada em cada dia fica registrada em origemAgenda.
Cada contrato gerado pelo ciclo é notificado pelo webhook de contratos que já existe — tipoNotificacao = 2, em 3.2. Atualizações do contrato —, com o mesmo payload dos contratos criados por API. Não há tipo de notificação novo.
📍 A configuração da antecipação automática não fica nesta documentação. Ela vive junto do cadastro de cedentes, porque é uma propriedade do vínculo cedente × operação: Cadastro de Cedente → 8. Antecipação automática de cartão. Os contratos que o ciclo gera são consultados normalmente pelos endpoints da seção 5 desta documentação.
🕒 Observações¶
- O ciclo de vida dos valores da UR (
valorConstituido,valorComprometido,valorLivre,valorDisponivel,valorGarantido,valorNominal,valorDesconto,valorAquisicao) está detalhado em 2.2. Dicionário de dados. - A lista de siglas de arranjos de pagamento também está em 2.2. Dicionário de dados.
- Início do fluxo, com a solicitação da agenda: 4.1. Solicitar agenda.
- Headers obrigatórios (
Authorization,GrupoEconomico) e convenções gerais: 1.1. Primeiros Passos.