---
title: Mudanças e Impacto nas Integrações
url: https://docs.vehub.com.br/API/Cadastro%20de%20Cedente/1.%20In%C3%ADcio/1.4.%20Mudan%C3%A7as%20e%20Impacto%20nas%20Integra%C3%A7%C3%B5es/
---
# Mudanças e Impacto nas Integrações

Esta página resume as alterações recentes na API de Cadastro de Cedente e **o que cada uma exige (ou não)
de quem já integra**. Leia antes de subir uma nova versão do seu cliente.

!!! tip "Como ler esta página"
    - 🔴 **Ação necessária** — sua integração pode quebrar se você não ajustar.
    - 🟡 **Atenção** — muda a resposta ou o status HTTP, mas em cenários que provavelmente você não usa hoje.
    - 🟢 **Compatível** — nada a fazer; só amplia o que a API aceita.

---

## 🟢 Cadastro de Pessoa Física com CPF

**O que mudou:** o cadastro de cedente e de sacado passou a aceitar **Pessoa Física**. O documento vai no
campo novo `cpf` quando `tipoPessoa` é `1`; `cnpj` continua sendo o campo de `tipoPessoa` `2`.

**Impacto:** nenhum para quem só cadastra Pessoa Jurídica — o payload de PJ não mudou.

**Regras novas:**

| Cenário | Resultado |
| --- | --- |
| `tipoPessoa: 1` + `cpf` (11 dígitos) | ✅ `200` |
| `tipoPessoa: 2` + `cnpj` (14 dígitos) | ✅ `200` (inalterado) |
| `tipoPessoa: 1` sem `cpf` | ❌ `400` — `O CPF é obrigatório quando o tipo de pessoa é Pessoa Física.` |
| `tipoPessoa: 1` com `cnpj` preenchido | ❌ `400` — `Não informe o CNPJ quando o tipo de pessoa é Pessoa Física. Utilize o campo cpf.` |
| `tipoPessoa: 2` com `cpf` preenchido | ❌ `400` — mensagem simétrica |

!!! warning "Se você mandava o CPF dentro de `cnpj`"
    Não funcionava antes (`O CNPJ deve ter 14 caracteres.`) e continua não funcionando — mas agora o erro
    diz exatamente o que fazer. **Mova o valor para o campo `cpf`.**

---

## 🟡 Campos `cpf` e `cnpj` são mutuamente exclusivos nas respostas

**O que mudou:** todas as consultas de cedente e sacado passaram a devolver **apenas um** dos dois campos:
`cnpj` para Pessoa Jurídica, `cpf` para Pessoa Física. O campo do outro tipo é **omitido do JSON** — não
vem como `null`.

**Impacto — leia com atenção:** se você já tem no seu banco cadastros **Pessoa Física** criados por outro
canal (importação, cadastro interno), esses registros **deixam de trazer `cnpj`** nas respostas e passam a
trazer `cpf`. Um cliente que lê `resposta.cnpj` de forma obrigatória vai receber `undefined`/`null` nesses
casos.

**Como adaptar:** leia o documento como `cpf ?? cnpj`, ou decida pelo `tipoPessoa`.

Endpoints afetados: `GET /cedentes/{idEmpresa}`, `GET /cedentes/por-cnpj/{cnpj}`,
`GET /cedentes/por-documento/{cpfCnpj}`, `POST /cedentes`, `GET /sacados/{idEmpresa}`, `GET /sacados`,
`GET /sacados/por-cnpj/{cnpj}`, `GET /sacados/por-documento/{cpfCnpj}`, `POST /sacados/por-cnpjs`,
`POST /sacados`.

---

## 🟡 `por-cnpj` foi descontinuado em favor de `por-documento`

**O que mudou:** `GET /cedentes/por-cnpj/{cnpj}` e `GET /sacados/por-cnpj/{cnpj}` estão marcados como
**deprecated** no Swagger. Foram criados `GET /cedentes/por-documento/{cpfCnpj}` e
`GET /sacados/por-documento/{cpfCnpj}`, que resolvem CPF **ou** CNPJ.

**Impacto:** **nenhum agora** — o comportamento do `por-cnpj` não mudou; ele continua aceitando só CNPJ e
recusando CPF. Mas ele não localiza cadastros Pessoa Física e não receberá evoluções.

**Como adaptar:** troque a chamada por `por-documento/{cpfCnpj}`. O corpo de resposta é o mesmo.

---

## 🟡 `PUT` de cedente/sacado inexistente agora responde `404`

**O que mudou:** `PUT /cedentes/{idEmpresa}` e `PUT /sacados/{idEmpresa}` retornavam `400` quando o id não
existia. Agora retornam **`404 Not Found`**.

**Impacto:** clientes que tratam "não encontrado" olhando só para `400` deixam de reconhecer o caso.

**Como adaptar:** trate `404` como recurso inexistente e `400` como erro de validação do payload.

---

## 🔴 `PUT` não pode mais trocar o `tipoPessoa` sem trocar o documento

**O que mudou:** enviar `tipoPessoa` num `PUT` que **contradiz o documento já cadastrado** passa a ser
recusado com `400`:

```json
{
  "status": "erro",
  "mensagem": "Não é possível alterar o tipo de pessoa para PessoaFisica: o documento cadastrado (12345678000199) não corresponde ao tipo informado. O documento de um cadastro não pode ser alterado."
}
```

**Por que:** antes o `PUT` aceitava a troca e o cadastro ficava incoerente — um CNPJ de 14 dígitos passava a
ser devolvido dentro do campo `cpf`.

**Impacto:** se a sua rotina de atualização reenvia o cadastro inteiro (incluindo `tipoPessoa`), ela
continua funcionando **desde que o `tipoPessoa` enviado combine com o documento gravado**. O documento de um
cadastro não pode ser alterado pela API — para trocá-lo, crie um novo cadastro.

---

## 🔴 `PUT` não aceita mais campos de texto em branco

**O que mudou:** enviar `nome`, `razaoSocial` ou `email` como `""` ou só espaços num `PUT` retorna `400`.
Antes o valor em branco era gravado, apagando o dado.

```
O campo 'Nome' não pode ser enviado em branco. Omita o campo para mantê-lo inalterado.
```

**Como adaptar:** em atualização parcial, **omita** o campo que você não quer alterar em vez de mandar
string vazia.

---

## 🔴 Novas validações de conteúdo no `POST` e no `PUT`

Payloads que antes eram aceitos e gravavam dado inválido agora retornam `400`:

| Campo | Regra nova | Mensagem |
| --- | --- | --- |
| `endereco.uf` | Precisa ser uma UF brasileira existente | `O UF informado não é uma unidade federativa válida.` |
| `endereco.cep` | Precisa ter 8 dígitos (aceita `99999-999`) | `O CEP deve conter 8 dígitos numéricos.` |
| `objetoSocial` | Máximo de 4000 caracteres | `O objeto social deve ter no máximo 4000 caracteres.` |
| `siteCorporativo` | Só `http`/`https` | `O site corporativo deve ser uma URL http ou https.` |
| `nome`, `razaoSocial`, `objetoSocial` | Sem caracteres de controle (NUL, quebra de linha, tab) | `O <campo> contém caracteres de controle não permitidos.` |

**Impacto:** se a sua base de origem tem CEP com letras, UF fora do padrão ou site sem `https://`, esses
registros passam a ser recusados no cadastro. **Normalize antes de enviar.**

!!! note "Acentos e emoji continuam permitidos"
    A restrição é só de caracteres **de controle**. `Açaí`, `Ñoño` e `中文` seguem aceitos normalmente.

---

## 🟢 Mensagens de erro deixaram de expor detalhes internos

**O que mudou:** quando um valor não casa com o tipo do campo, a API devolvia a mensagem crua do
desserializador, com nome de classe .NET, assembly e posição no payload:

```
The JSON value could not be converted to Vertrau.VHub.Contracts.Empresa.Enumeradores.TipoPessoa. Path: $.tipoPessoa | LineNumber: 0 | BytePositionInLine: 785.
```

Agora devolve:

```
O valor informado para o campo 'tipoPessoa' não é válido para o tipo esperado.
```

**Impacto:** nenhum, a menos que sua integração faça *parsing* do texto da mensagem de erro — o que não é
suportado. Use o **status HTTP** e a **chave do campo** em `errors`.

---

## 🟢 Filtro por CPF na listagem de sacados

`GET /sacados` ganhou o query param opcional `cpf`, equivalente ao `cnpj` já existente. Nada muda para quem
não usa.

---

## Enums: sempre número

Ver [Dicionário de Dados](1.3.%20Dicion%C3%A1rio%20de%20Dados.md). Os enums desta API trafegam como
**número** na entrada e na saída. Enviar o nome do membro como string (`"PessoaJuridica"`) retorna `400` —
a documentação anterior dizia o contrário e estava incorreta.