Ir para o conteúdo

Mudanças e Impacto nas Integrações

Esta página resume o que muda da v1 para a v1.1 da API de Cartão de Crédito e o que cada mudança exige de quem já integra. Leia antes de migrar seu cliente.

Como ler esta página

  • 🔴 Ação necessária — sua integração quebra se você não ajustar.
  • 🟡 Atenção — muda a resposta ou o status HTTP, possivelmente em cenários que você não usa hoje.
  • 🟢 Compatível — nada a fazer; só amplia o que a API entrega.

A v1 continua disponível

Nada na v1 foi alterado. A v1.1 é uma versão paralela, com prefixo próprio. Migre quando quiser — mas note que os recursos novos de acompanhamento e conciliação existem apenas na v1.1.

🔴 Prefixo e versão da rota

O que mudou: todas as rotas passaram para /public/api/v1.1/cartao/....

Impacto: a v1.1 divulgada em rascunhos anteriores aparecia como /api/v1.1/cartao/..., sem o segmento /public, e as páginas de contrato chegaram a apontar para /api/v1/. Nenhuma dessas formas é válida.

Como adaptar: use sempre https://api.veflow.com/public/api/v1.1/cartao.

🔴 Recursos renomeados

O que mudou: os nomes de recurso passaram a corresponder ao que eles são.

v1 v1.1 Por quê
simulacao/{id} agendas/{id} o recurso sempre foi a agenda de recebíveis
simulacao/{id}/vinculo agendas/{id}/carrinho/itens a seleção persistida é um item de carrinho
simula-contrato carrinho/itens/previa não criava simulação nenhuma — é cálculo
parcela-garantia carrinho/itens/lote parcela de garantia é N itens de carrinho
titulos urs o ativo é a Unidade de Recebível
contrato contratos uma agenda pode gerar mais de um contrato

Como adaptar: ajuste as URLs e o nome dos arrays na desserialização (titulos → urs).

🔴 tipoVinculo e acao foram substituídos por estrategia

O que mudou: o campo que define como as URs são selecionadas passou a se chamar estrategia.

Impacto — leia com atenção: na v1, tipoVinculo usava 1 = por valor e 2 = por UR. Em rascunhos da v1.1 o campo acao usava 1 = URs selecionadas e 2 = split por valor — ou seja, os valores 1 e 2 tinham significado invertido. Um cliente que apenas trocasse o nome do campo passaria a enviar a estratégia oposta, sem nenhum erro de validação.

Como adaptar: use estrategia com os valores novos e revise o mapeamento, não só o nome:

estrategia Significado
1 URs selecionadas manualmente
2 Split por valor desejado
3 Troca por valor desejado
4 Alocação automática por parcela

🔴 tipoContrato mudou de valores e de lugar

O que mudou: tipoContrato agora tem dois valores e é informado no item do carrinho, não na criação do contrato.

tipoContrato Significado
1 Troca de titularidade — antecipação, com cessão ao fundo
2 Garantia — ônus de cessão fiduciária sobre recebíveis performados

Impacto:

  • Fumaça deixou de ser tipo de contrato. Passou a ser configuração da garantia (tipoContrato: 2 + bloco fumaca com prazo estendido, somenteUrPerformada e regra de retenção). Quem enviava tipoContrato: 3 deve enviar 2 com o bloco fumaca.
  • Promessa de cessão nunca pôde ser criada e não aparece na escrita. Ela existe apenas em leitura, como ônus de terceiro sobre a UR — ver efeitos[].
  • Penhor é legado e não é ofertado.
  • A modalidade da operação define o tipoContrato aceito: operação de garantia aceita 2, operação de antecipação aceita 1. Tipo incompatível com a modalidade responde 400 — ver 2.1. Conceitos.

Antecipação pela v1.1

A antecipação continua pela v1; enquanto a v1.1 não a libera, as escritas de operação de antecipação respondem 400.

Como adaptar: informe tipoContrato ao adicionar o item ao carrinho e remova-o do corpo da criação do contrato.

🔴 Criar contrato: corpo, retorno e cardinalidade

O que mudou: POST /agendas/{idAgenda}/contratos cria 1..N contratos — um por item do carrinho.

v1 v1.1
Corpo { identificadorSimulacao, tipoContrato } { idsItens?, contaCorrente? } — omitir idsItens contrata todo o carrinho
Retorno um identificador array contratos + ursRejeitadas + identificadorProcessamento
Status 200 202 dentro da janela — fora dela, 200 com aceito: false (ver abaixo)

Impacto: o retorno deixou de ser um objeto com um identificador. Um cliente que lê resposta.identificador não encontra mais o contrato.

Como adaptar: itere sobre contratos[]. Cada elemento traz idItem, identificador, tipoContrato e status.

A criação pode falhar parcialmente

Entre montar o carrinho e criar o contrato, uma UR pode ter sido comprometida por terceiro. Essas URs voltam em ursRejeitadas[] com o motivo. Trate esse array — ele não é exceção, é resultado esperado.

🔴 URs deixaram de vir embutidas nas consultas

O que mudou: GET /agendas/{id} e GET /contratos/{id} não trazem mais o array de URs no corpo. As URs viraram sub-recursos paginados.

Antes Agora
GET /simulacao/{id} → titulos[] inline GET /agendas/{id}/urs
GET /contrato/{id} → titulos[] inline GET /contratos/{id}/urs

Impacto: uma agenda de 30 dias de um EC de porte médio passa de dez mil URs — o corpo inline não era sustentável.

Como adaptar: faça a chamada ao sub-recurso e pagine.

🔴 Paginação

O que mudou: os parâmetros de paginação são indicePagina e tamanhoDaPagina.

Impacto: rascunhos da v1.1 usavam ?pagina= e ?quantidade=, que não são válidos.

Como adaptar: use ?indicePagina=1&tamanhoDaPagina=20, mais ordem e direcaoOrdem quando precisar ordenar. O envelope de lista é { registros, paginacao, mensagem }.

🔴 idTitulos virou idsUrs

O que mudou: as listas de identificadores de UR se chamam idsUrs. Ao adicionar URs, o corpo passou a ser um array urs de objetos, para permitir valor por UR:

{ "urs": [ { "idUr": "7D12...", "valorGarantido": 800.00, "tipoValor": 1 } ] }

Impacto: o valor por UR respeita o valorDisponivel. Nesta versão, cada UR fica em um item só nas estratégias 1 a 3.

🔴 tipoEfeito 3 e 4 trocados

O que mudou: em efeitos[], tipoEfeito 3 é Penhor e 4 é Promessa de cessão — os valores que a API devolve. A documentação anterior publicava os dois invertidos.

Impacto: quem mapeou pela documentação anterior inverte Penhor e Promessa de cessão sem nenhum erro.

Como adaptar: refaça o mapeamento — ver 8.1. Enumerações.

🔴 statusLiquidacao — a UR liquidou ou está em aberto

O que mudou: as URs do contrato passaram a ter dois eixos de status:

Campo Responde
statusSolicitacao "a registradora aceitou a UR neste contrato?"
statusLiquidacao "o dinheiro entrou?"

Impacto: a documentação anterior afirmava que o status da UR servia para identificar URs liquidadas — mas aquele enum é de vínculo e não possui valor de liquidada. Agora são dois campos independentes.

statusLiquidacao tem a mesma semântica nos dois fluxos, antecipação e garantia; muda apenas a origem do dado.

Como adaptar: o campo é numérico, de 1 a 7 — ver 8.1. Enumerações. A documentação anterior o publicava pelo nome; quem desserializa como texto precisa ajustar.

🔴 Agenda criada na v1.1 se opera só pela v1.1

O que mudou: agenda, item do carrinho e contrato criados pela v1.1 só são operados pelas rotas da v1.1. As rotas da v1 não os operam.

Impacto: quem migra aos poucos e cria a agenda pela v1.1 não consegue seguir o fluxo dela pelas rotas da v1.

Como adaptar: quem usa a v1 continua nela até migrar 100% da integração para a v1.1.

🟡 202 no lugar de 201 para processamento assíncrono

O que mudou: solicitações recebidas para processamento assíncrono respondem 202 Accepted com identificadorProcessamento.

Impacto: a v1 usava 201 para "recebido fora da janela de operação e agendado". Um cliente que trate 201 como criação concluída interpreta errado.

Como adaptar: trate 202 como aceite. Fora da janela de operação (publicada como 09:00–18:00 em dias úteis; vale o horário cadastrado da registradora da operação), a resposta depende do recurso — ver 1.2. Convenções da API:

  • Agenda (solicitar ou refazer): 202 com dataAgendamento.
  • Contrato: 200 com aceito: false, motivo e proximaJanela — o pedido não é agendado.

🟡 Formato de erro em ProblemDetails

O que mudou: os erros da v1.1 seguem o formato ProblemDetails (type, title, status, errors, traceId) — ver 1.2. Convenções da API.

Impacto: na v1, o erro de fora de janela vinha como um objeto simples com mensagem.

🟡 Tabelas de status ampliadas

O que mudou:

  • Status do contrato passou de 1–9 para 1–12, com 10 Incluindo UR, 11 Substituindo URs e 12 Processando contrato.
  • Status de solicitação da UR ganhou o valor 1000 Em remoção.

Impacto: esses estados já ocorriam e não estavam documentados. Um switch exaustivo sobre os valores antigos cai no ramo padrão.

🟡 CET foi removido da documentação

O que mudou: o campo CET saiu do bloco totais.

Impacto: ele estava documentado sem nunca ter existido no retorno da API. Quem tentava lê-lo já recebia undefined. O custo efetivo não é calculado pela plataforma, que não apura IOF.

🟡 Idempotency-Key

O que mudou: as escritas POST, PATCH e DELETE aceitam o header Idempotency-Key.

Como adaptar: envie um UUID por operação lógica — recomendado em qualquer retentativa automática. Reenviar a mesma chave depois de um sucesso devolve a resposta original em vez de duplicar a operação. Erro e recusa de negócio (aceito: false) não ficam guardados: repetir com a mesma chave executa de novo. A mesma chave com outra requisição, depois de um sucesso guardado, responde 422. Detalhes em 1.2. Convenções da API.

🟡 Resultado de negócio no status da entidade

O que mudou: um pedido que não pode ser atendido — por exemplo, fora da janela de operação, item já contratado, agenda vencida, UR sem disponível ou já em outro item — responde 2xx com a entidade no status atual, e não 409 ou 422. Todo resultado de negócio traz aceito (verdadeiro ou falso) e motivo (lista de textos), e proximaJanela quando couber.

Impacto: um cliente que trate qualquer 2xx como pedido atendido toma a recusa por sucesso.

Como adaptar: quando a resposta traz aceito, decida por ele e pelo motivo, não pelo código HTTP; aceito ausente numa resposta de sucesso não é recusa — ver 1.2. Convenções da API.

🟡 statusAgenda ganhou 0 e 6

O que mudou: o status da agenda passou a ter 0 Em processamento e 6 Vencida, só na v1.1.

Impacto: um switch exaustivo sobre os valores antigos cai no ramo padrão.

Como adaptar: trate os dois valores — ver 8.1. Enumerações.

🟢 totais.aquisicao mantido, e totais agora depende do tipo

O que mudou: totais.aquisicao permanece na v1.1 (rascunhos anteriores o haviam removido). E o bloco passou a ser condicional ao tipo de contrato:

tipoContrato Campos de totais
1 Troca de titularidade constituido, livre, garantido, disponivel, nominal, desconto, aquisicao, taxa
2 Garantia constituido, livre, garantido, disponivel

Por quê: nominal, desconto e aquisicao só existem onde houve cessão ao fundo. Contrato de garantia não tem cessão nem deságio.

Como adaptar: não assuma a presença de nominal/aquisicao em contrato de garantia. Ver 2.2. Dicionário de dados.

🟢 Valores novos na UR

O que mudou: cada UR passou a trazer valorComprometido, valorLivre e valorDisponivel, além de valorConstituido e valorGarantido.

valorDisponivel é o valorLivre menos o que já está alocado em itens e menos a margem de segurança da operação (valorConstituido × (100 − percentual máximo por UR) %), nunca negativo, truncado em centavos. O percentual incide sobre o constituído, não sobre o livre — ver 2.2. Dicionário de dados. Use-o em vez de recalcular a regra do seu lado.

🟢 efeitos[] — quem comprometeu a UR

O que mudou: o detalhe da UR passou a trazer o array efeitos[], com tipoEfeito, tipoOnus, dataVencimentoEfeito, idEfeitoContrato, documentoTitular, titularEhVoce e valorComprometido.

Impacto: antes só era possível inferir que havia ônus de terceiro comparando valorLivre com valorConstituido. Agora a API diz quem comprometeu, por qual contrato, com que ônus e até quando. É onde a promessa de cessão de terceiros aparece.

🟡 CNPJ com ou sem máscara

O que mudou: os campos de CNPJ aceitam o valor com ou sem pontuação na entrada. Nas respostas, o CNPJ vem sempre sem pontuação. O CNPJ pode ser alfanumérico: as letras são devolvidas em maiúsculas.

Como adaptar: pode enviar o CNPJ como já envia. Ao ler o CNPJ das respostas, aceite letras — não valide como só números. Ver 1.2. Convenções da API.

🟢 Endpoints novos

Ciclo de vida do contrato — recuperados da v1, que a v1.1 não havia documentado, e novos:

  • GET /contratos — listar e filtrar contratos (não existia)
  • DELETE /contratos/{id} — cancelar contrato
  • DELETE /contratos/{id}/urs — remover UR do contrato
  • POST /contratos/{id}/urs · PATCH /contratos/{id}
  • GET /contratos/{id}/urs-removidas · urs-rejeitadas

Agenda e carrinho: GET /agendas, GET /agendas/{id}/urs/{idUr}, GET /agendas/{id}/totais, POST /agendas/{id}/refazer, GET /agendas/{id}/carrinho, GET e PATCH do item.

Conciliação e acompanhamento (seção 7, inteiramente nova):

  • GET /contratos/{id}/posicao — contratado × comprometido × esperado × liquidado × chargeback × em aberto
  • GET /contratos/{id}/posicoes-diarias
  • GET /urs/{idUr}/conciliacoes — extrato de uma UR
  • GET /liquidacoes/divergencias
  • GET /posicao/estabelecimentos
  • GET /liquidacoes/{identificadorProcessamento}

🟢 Antecipação automática e o campo origemAgenda

O que mudou: passa a existir um modo em que VeHub percorre o ciclo sozinho, todo dia útil — busca a agenda, monta o carrinho e registra o contrato — sem nenhuma chamada de API por ciclo.

Impacto na integração: nenhum, para quem não usar o recurso. Duas adições compatíveis:

  • GET /contratos ganha o filtro origemAgenda e o campo de mesmo nome em cada registro, para separar o que foi gerado pelo ciclo automático do que foi criado manualmente ou por API. Em contratos não automáticos o campo vem null.
  • ⚠️ origemAgenda não é origem. Já existia uma enumeração origem, que descreve de onde um item do carrinho entrou. A nova descreve de qual agenda o ciclo automático tirou as URs (1 = BATCH, 2 = ONLINE). Ver 8.1. Enumerações.

Notificações: nenhum tipo novo. Os contratos gerados pelo ciclo chegam pelo webhook de contratos que já existe (tipoNotificacao = 2), com o mesmo payload — ver 3.2. Atualizações do contrato. Quem já trata essa notificação passa a receber também os contratos automáticos, sem nenhuma alteração no endpoint de callback.

Onde configurar: a habilitação e o histórico do ciclo ficam na documentação de Cadastro de Cedente → 8. Antecipação automática de cartão, porque são propriedades do vínculo cedente × operação. Os contratos gerados são consultados pelos endpoints da seção 5 desta documentação, sem diferença.

🟢 Campo nome do estabelecimento mantido

O que mudou: o campo nome permanece em POST /agendas (rascunhos da v1.1 o haviam removido).

Por quê: identifica o estabelecimento no cadastro e nos relatórios da plataforma.