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+ blocofumacacom prazo estendido,somenteUrPerformadae regra de retenção). Quem enviavatipoContrato: 3deve enviar2com o blocofumaca. - 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.
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 |
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 que habilita o rateio parcial — a mesma UR pode ser dividida entre itens do carrinho, respeitando o valorDisponivel.
🟡 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 09:00–18:00 em dias úteis, a resposta traz dataAgendamento.
🟡 Formato de erro unificado e 404¶
O que mudou: todos os erros usam RFC 9110 (tipo, titulo, status, erros[]), e recurso inexistente responde 404.
Impacto: na v1, o erro de fora de janela vinha como um objeto simples com mensagem, e recurso inexistente respondia 400.
🟡 Tabelas de status ampliadas¶
O que mudou:
- Status do contrato passou de 1–9 para 1–12, com
10Incluindo UR,11Substituindo URs e12Processando contrato. - Status de solicitação da UR ganhou o valor
1000Em 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: os POST de escrita aceitam o header Idempotency-Key.
Como adaptar: envie um UUID por operação lógica. Reenviar a mesma chave devolve a resposta original em vez de duplicar a operação — recomendado em qualquer retentativa automática.
🟢 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 livre já descontado o percentual máximo por UR configurado na operação — 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.
🟢 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.
🟢 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 contratoDELETE /contratos/{id}/urs— remover UR do contratoPOST /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 abertoGET /contratos/{id}/posicoes-diariasGET /urs/{idUr}/conciliacoes— extrato de uma URGET /liquidacoes/divergenciasGET /posicao/estabelecimentosGET /liquidacoes/{identificadorProcessamento}
🟢 Campo nome do estabelecimento mantido¶
O que mudou: o campo nome permanece em POST /agendas (rascunhos da v1.1 o haviam removido).
Por quê: é o que permite conciliar o recebível quando o CNPJ do ponto de venda informado no arquivo do SLC não é o originário da UR. Sem ele, essa conciliação não tem substituto.