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.
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 |
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:
{
"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.
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. 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.