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.
As entradas mais recentes vêm primeiro e trazem a data em que a mudança entrou no ambiente de homologação.
🟢 Escopo do limite de crédito no vínculo (escopoLimiteCredito)¶
Homologação desde 21/10/2026.
O que mudou: o vínculo do cedente (e do sacado) com a operação ganhou o campo opcional escopoLimiteCredito, que define se o limite de crédito vale só na operação (1) ou para todas as operações do mesmo cessionário (2). As respostas de vínculo passam a trazer o campo sempre preenchido.
Impacto: nenhum para quem não envia o campo — a criação grava 1 (Operação), e a atualização preserva o escopo gravado.
O campo é numérico
Como os demais enums da API, escopoLimiteCredito só aceita o código. Enviar "Financiador" ou "Operacao" como texto retorna 400 com O valor informado para o campo 'escopoLimiteCredito' não é válido para o tipo esperado.
Detalhes em Vincular Cedente a Operações e na tabela Escopo do Limite de Crédito.
🟡 PUT de vínculo de sacado com contrato-mestre não altera mais o limite¶
Homologação desde 13/10/2026.
O que mudou: quando o par cedente×sacado tem contrato-mestre cadastrado pelo gestor, o limite de crédito passa a seguir o contrato. Um PUT /cedentes/{idEmpresa}/operacoes/{idOperacao}/sacados/{idSacado} que envie limiteCredito diferente do gravado é recusado com 403 Forbidden:
{
"status": "erro",
"mensagem": "O limite deste vínculo segue o contrato-mestre e só pode ser alterado pelo gestor."
}
Impacto: só para pares com contrato-mestre. Os demais campos do vínculo continuam atualizáveis, e reenviar o mesmo valor de limite não é recusado.
Como adaptar: trate o 403 como "limite gerido pelo contrato" e não tente de novo. Para conferir o contrato e o limite vigente, use o endpoint novo GET /cedentes/{idEmpresa}/operacoes/{idOperacao}/sacados/{idSacado}/contrato-mestre, descrito em Risco Sacado - Sacados.
🟢 Cadastro simplificado e antecipação automática de cartão¶
Homologação entre 01/10/2026 e 06/10/2026.
O que mudou: endpoints novos, todos opcionais e restritos a grupos econômicos habilitados para a antecipação automática:
| Método | Endpoint | Entrada em homologação |
|---|---|---|
POST | /cedentes/simplificado | 01/10/2026 |
PATCH | /cedentes/operacoes/{idOperacao}/taxa | 01/10/2026 |
GET | /cedentes/operacoes/{idOperacao}/taxa/processamentos/{identificador} | 01/10/2026 |
PUT | /cedentes/{idEmpresa}/antecipacao-automatica | 02/10/2026 |
DELETE | /cedentes/{idEmpresa}/antecipacao-automatica | 02/10/2026 |
GET | /cedentes/{idEmpresa}/antecipacao-automatica | 02/10/2026 |
GET | /cedentes/{idEmpresa}/antecipacao-automatica/execucoes | 06/10/2026 |
PATCH | /cedentes/{idEmpresa}/operacoes/{idOperacao}/taxa | 06/10/2026 |
Impacto: nenhum para quem não usa o recurso. Em grupo não habilitado, esses endpoints respondem 403.
Detalhes na seção 8. Antecipação automática de cartão.
🟢 Endpoints documentados nesta revisão¶
Já disponíveis na API, passam a constar desta documentação:
| Método | Endpoint | Onde está |
|---|---|---|
POST | /cedentes/{idEmpresa}/usuarios | Cadastrar Usuário do Cedente |
GET | /cedentes/{idEmpresa}/operacoes/{idOperacao}/sacados/{idSacado}/contrato-mestre | Risco Sacado - Sacados |
Usuário do cedente recebe o perfil padrão do tipo Cedente
Desde 17/10/2026 em homologação, o usuário cadastrado por POST /cedentes/{idEmpresa}/usuarios recebe o perfil marcado como padrão para o tipo Cedente no grupo econômico, restrito à própria empresa e às operações em que ela é cedente. Sem perfil padrão configurado, o cadastro é recusado com Não há perfil padrão para o tipo Cedente.
🔴 Formato da resposta do PUT de cedente e de sacado¶
Homologação desde 12/08/2026.
O que mudou: PUT /cedentes/{idEmpresa} e PUT /sacados/{idEmpresa} passaram a usar o formato padrão de resposta da API:
| Situação | Antes | Agora |
|---|---|---|
200 | { "idEmpresa": 123, "status": "..." } | Embrulhado: { "sucesso": true, "dados": { "idEmpresa": 123, "status": "..." }, "mensagem": "Registro atualizado com sucesso." } |
400 de regra de negócio | { "status": "erro", "mensagem": "..." } | ProblemDetails: as mensagens vêm em errors, na chave vazia "" |
404 | (era 400) | Apenas a mensagem, como string JSON |
{
"sucesso": true,
"dados": {
"idEmpresa": 123,
"status": "Cadastro atualizado com sucesso."
},
"mensagem": "Registro atualizado com sucesso."
}
Impacto: quem lia idEmpresa ou status na raiz da resposta passa a receber undefined/null; quem lia mensagem no erro deixa de achá-la.
Como adaptar: leia o resultado em dados (dados.idEmpresa, dados.status). No 400, leia as mensagens em errors — numa chave por campo, para erro de validação de campo (formato que não mudou), ou na chave vazia "", para regra de negócio. Exemplos completos em Atualizar Cedente.
🟢 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, com o corpo trazendo apenas a mensagem como string JSON — por exemplo, "Cedente com ID 123 não encontrado.".
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, no formato ProblemDetails:
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "Ocorreram um ou mais erros de validação.",
"status": 400,
"errors": {
"": [
"Não é possível alterar o tipo de pessoa para PessoaFisica: o documento cadastrado (12345678000195) não corresponde ao tipo informado. O documento de um cadastro não pode ser alterado."
]
},
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}
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.