---
title: Mudanças e Impacto nas Integrações
url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/9.%20Mudan%C3%A7as%20e%20Impacto%20nas%20Integra%C3%A7%C3%B5es/
---
# 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.

!!! tip "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.

!!! warning "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.

**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`.

!!! warning "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:

```json
{ "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 `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:** 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 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}`

---

## 🟢 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.