--- title: 2.1. Criar, Consultar e Atualizar Cedente url: https://docs.vehub.com.br/API/Cadastro%20de%20Cedente/2.%20Empresa%20Cedente/2.1.%20Criar%2C%20Consultar%20e%20Atualizar%20Cedente/ --- ## Criar Cedente | Método | URL | | ------------------------------------------------ | ------------------------------- | | ![POST](https://img.shields.io/badge/POST-green) | `https://BASE_URL/public/api/v1/cedentes` | Cria o cadastro de uma nova empresa cedente com todos os dados necessários. !!! info "Pessoa Física usa `cpf`, Pessoa Jurídica usa `cnpj`" Os dois campos são **mutuamente exclusivos** e a escolha é ditada pelo `tipoPessoa`: - `tipoPessoa: 1` (Pessoa Física) → envie **`cpf`** (11 dígitos) e **não** envie `cnpj`. - `tipoPessoa: 2` (Pessoa Jurídica) → envie **`cnpj`** (14 dígitos) e **não** envie `cpf`. Informar o campo do tipo errado é rejeitado com `400`, em vez de o valor ser descartado em silêncio. O mesmo vale para o cadastro de sacado. ```json title="Request Body — Pessoa Jurídica" { "cnpj": "12345678000199", "nome": "Empresa Exemplo LTDA", "razaoSocial": "Empresa Exemplo Sociedade Limitada", "email": "financeiro@empresaexemplo.com.br", "telefone": { "ddi": "+55", "ddd": "47", "numero": "33221100" }, "tipoPessoa": 2, "inscricaoEstadual": "123456789", "isentoInscricaoEstadual": false, "inscricaoMunicipal": "987654", "endereco": { "logradouro": "Rua XV de Novembro", "numero": "1500", "complemento": "Sala 201", "bairro": "Centro", "cep": "89010-001", "cidade": "Blumenau", "uf": "SC", "pais": "BRA" }, "codigoCnae": "6499-9/99", "naturezaJuridica": "206-2", "objetoSocial": "Prestação de serviços financeiros e cessão de créditos.", "dataConstituicao": "2015-03-20", "faturamento": 5000000.0, "porte": 4, "integranteSnf": false, "ramoAtividade": 1, "tipoSociedade": 1, "classificacaoRisco": 2, "autorizacaoCessao": true, "codigoCoobrigacaoCedente": 2, "siteCorporativo": "https://empresaexemplo.com.br" } ``` ```json title="Request Body — Pessoa Física" { "cpf": "52998224725", "nome": "José Osmar Rodrigues Pereira", "razaoSocial": "José Osmar Rodrigues Pereira", "email": "jose.pereira@exemplo.com.br", "telefone": { "ddi": "+55", "ddd": "31", "numero": "988868145" }, "tipoPessoa": 1, "endereco": { "logradouro": "Rua Professor Elói Lacerda", "numero": "S/N", "bairro": "Centro", "cep": "36424000", "cidade": "Queluzito", "uf": "MG", "pais": "BRA" }, "codigoCnae": "6499-9/99", "dataConstituicao": "1966-07-25" } ``` ```json title="Response Body — Pessoa Jurídica" { "idEmpresa": 123, "cnpj": "12345678000199", "nome": "Empresa Exemplo LTDA", "status": "Cadastro criado com sucesso." } ``` ```json title="Response Body — Pessoa Física" { "idEmpresa": 124, "cpf": "52998224725", "nome": "José Osmar Rodrigues Pereira", "status": "Cadastro criado com sucesso." } ``` --- # Modelo de Dados ## Requisição | Campo | Tipo | Obrigatório | Descrição | | -------------------------- | --------------------- | :---------: | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `cnpj` | Texto (14) | Condicional | CNPJ da empresa (somente números). **Obrigatório** quando `tipoPessoa` = `2`; não deve ser informado quando `tipoPessoa` = `1` | | `cpf` | Texto (11) | Condicional | CPF do cedente (somente números). **Obrigatório** quando `tipoPessoa` = `1`; não deve ser informado quando `tipoPessoa` = `2` | | `nome` | Texto (200) | ✅ | Nome fantasia da empresa | | `razaoSocial` | Texto (200) | ✅ | Razão social | | `email` | Texto (200) | ✅ | E-mail corporativo principal | | `telefone` | [Telefone](#telefone) | ✅ | Telefone corporativo | | `tipoPessoa` | Número | ✅ | Tipo de pessoa. Ver [Tipo de Pessoa](../1.%20In%C3%ADcio/1.3.%20Dicion%C3%A1rio%20de%20Dados.md#tipo-de-pessoa) | | `inscricaoEstadual` | Texto (20) | Opcional | Inscrição estadual | | `isentoInscricaoEstadual` | Booleano | Opcional | Indica se isento de inscrição estadual. Default: `false` | | `inscricaoMunicipal` | Texto (20) | Opcional | Inscrição municipal | | `endereco` | [Endereço](#endereco) | ✅ | Endereço completo da sede | | `codigoCnae` | Texto (20) | ✅ | Código CNAE da atividade principal | | `naturezaJuridica` | Texto (20) | Opcional | Código da natureza jurídica (CONCLA) | | `objetoSocial` | Texto | Opcional | Descrição do objeto social da empresa | | `dataConstituicao` | Data | ✅ | Data de constituição da empresa (`YYYY-MM-DD`) | | `faturamento` | Decimal | Opcional | Faturamento mensal/anual estimado | | `porte` | Número | Opcional | Porte da empresa. Ver [Porte da Empresa](../1.%20In%C3%ADcio/1.3.%20Dicion%C3%A1rio%20de%20Dados.md#porte-da-empresa) | | `integranteSnf` | Booleano | Opcional | Integrante do Sistema Financeiro Nacional. Default: `false` | | `ramoAtividade` | Número | Opcional | Ramo de atividade. Ver [Ramo de Atividade](../1.%20In%C3%ADcio/1.3.%20Dicion%C3%A1rio%20de%20Dados.md#ramo-de-atividade) | | `tipoSociedade` | Número | Opcional | Tipo de sociedade. Ver [Tipo de Sociedade](../1.%20In%C3%ADcio/1.3.%20Dicion%C3%A1rio%20de%20Dados.md#tipo-de-sociedade) | | `classificacaoRisco` | Número | Opcional | Classificação de risco. Ver [Classificação de Risco](../1.%20In%C3%ADcio/1.3.%20Dicion%C3%A1rio%20de%20Dados.md#classificacao-de-risco) | | `autorizacaoCessao` | bool | Opcional | Autorização de cessão. Ver [Autorização de Cessão](../1.%20In%C3%ADcio/1.3.%20Dicion%C3%A1rio%20de%20Dados.md#autorizacao-de-cessao). Default: false | | `codigoCoobrigacaoCedente` | Número | Opcional | Código de coobrigação. Ver [Código de Coobrigação](../1.%20In%C3%ADcio/1.3.%20Dicion%C3%A1rio%20de%20Dados.md#codigo-de-coobrigacao-do-cedente) | | `siteCorporativo` | Texto (200) | Opcional | URL do site corporativo | | `dataContrato` | Data | Opcional | Data do contrato com o fundo | | `matriz` | Booleano | Opcional | Indica se a empresa é a **matriz** da sua base de CNPJ (raiz de 8 dígitos). Usado na validação de limite por Base CNPJ. Default `false`. | ### Telefone | Campo | Tipo | Obrigatório | Descrição | | -------- | ---------- | :---------: | ------------------------------- | | `ddi` | Texto (5) | Opcional | DDI do telefone. Default: `+55` | | `ddd` | Texto (3) | ✅ | DDD do telefone | | `numero` | Texto (15) | ✅ | Número do telefone | ### Endereço | Campo | Tipo | Obrigatório | Descrição | | ------------- | ----------- | :---------: | ---------------------------------------------------------------------------------------------------------------- | | `logradouro` | Texto (200) | ✅ | Logradouro (rua, avenida, etc.) | | `numero` | Texto (50) | ✅ | Número | | `complemento` | Texto (100) | Opcional | Complemento (sala, andar, bloco) | | `bairro` | Texto (80) | ✅ | Bairro | | `cep` | Texto (9) | ✅ | CEP (com ou sem máscara) | | `cidade` | Texto (100) | ✅ | Cidade | | `uf` | Texto (2) | ✅ | Unidade Federativa. Ver [UF](../1.%20In%C3%ADcio/1.3.%20Dicion%C3%A1rio%20de%20Dados.md#uf-unidades-federativas) | | `pais` | Texto (3) | Opcional | País (ISO 3166-1 alpha-3). Default: `BRA` | ## Retorno | Campo | Tipo | Descrição | | ----------- | ------ | ------------------------------ | | `idEmpresa` | Número | ID da empresa criada | | `cnpj` | Texto | CNPJ da empresa. Presente apenas para Pessoa Jurídica — omitido do JSON para Pessoa Física | | `cpf` | Texto | CPF do cedente. Presente apenas para Pessoa Física — omitido do JSON para Pessoa Jurídica | | `nome` | Texto | Nome da empresa | | `status` | Texto | Mensagem de status da operação | --- ## Consultar Cedente | Método | URL | | --------------------------------------------- | ------------------------------------------- | | ![GET](https://img.shields.io/badge/GET-blue) | `https://BASE_URL/public/api/v1/cedentes/{idEmpresa}` | Retorna o cadastro completo do cedente, incluindo pessoas vinculadas, contas, contatos e documentos. !!! info "`empresa.cpf` x `empresa.cnpj`" O bloco `empresa` traz **apenas um** dos dois: `cnpj` para Pessoa Jurídica (`tipoPessoa: 2`) e `cpf` para Pessoa Física (`tipoPessoa: 1`). O campo do outro tipo é **omitido do JSON**, não devolvido como `null`. ```json title="Response Body" { "idEmpresa": 123, "empresa": { "cnpj": "12345678000199", "nome": "Empresa Exemplo LTDA", "razaoSocial": "Empresa Exemplo Sociedade Limitada", "tipoPessoa": 2, "inscricaoEstadual": "123456789", "inscricaoMunicipal": "987654", "endereco": { "logradouro": "Rua XV de Novembro", "numero": "1500", "complemento": "Sala 201", "bairro": "Centro", "cep": "89010-001", "cidade": "Blumenau", "uf": "SC", "pais": "BRA" }, "codigoCnae": "6499-9/99", "dataConstituicao": "2015-03-20", "faturamento": 5000000.0, "porte": 4, "ramoAtividade": 1, "tipoSociedade": 1, "classificacaoRisco": 2 }, "pessoas": [ { "idPessoa": 1, "nome": "João Silva", "cpfCnpj": "12345678901", "papelSocio": true, "papelRepresentante": true, "participacao": 50.0 } ], "contasCorrentes": [ { "idConta": 1, "codigoBanco": "341", "agencia": "1234", "conta": "56789", "principal": true } ], "contatos": [ { "idContato": 1, "nome": "Maria Financeiro", "email": "maria@empresaexemplo.com.br", "telefone": "47999887766" } ], "documentos": [ { "idDocumento": 1, "arquivoNome": "contrato_social.pdf" } ], "cadastradoNaAdministradora": true, "ativo": true } ``` ### Campos de Status | Campo | Tipo | Descrição | | ---------------- | ----------- | -------------------------------------------------------------------------------------------------- | | `ativo` | Booleano | Indica se o cedente está ativo. `true` quando ativo; `false` quando inativado. | | `dataInativacao` | Data e hora | Data/hora (UTC) da inativação. Presente apenas quando o cedente está inativo (omitido quando ativo). | !!! warning "Cedente inativo bloqueia novos títulos" Um cedente **inativo** é bloqueado ao importar títulos ou criar lote: a API responde `400` com a mensagem `Cedente {cnpj} está inativo e não pode receber novos títulos.`. Lotes e títulos **já em andamento não são afetados** pela inativação. Para liberar novamente, basta [reativar o cedente](#reativar-cedente). --- ## Consultar Cedente por CNPJ | Método | URL | | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | ![GET](https://img.shields.io/badge/GET-blue) ![DEPRECATED](https://img.shields.io/badge/DEPRECATED-lightgrey) | `https://BASE_URL/public/api/v1/cedentes/por-cnpj/{cnpj}` | !!! warning "Endpoint descontinuado" Aceita **apenas CNPJ** e por isso não localiza cedentes Pessoa Física, cujo documento é o CPF. Continua funcionando **sem alteração de comportamento** para as integrações existentes, mas não receberá novas evoluções. Migre para o [GET `/cedentes/por-documento/{cpfCnpj}`](#consultar-cedente-por-documento-cpf-ou-cnpj), que resolve os dois tipos de documento. Resolve o identificador (`idEmpresa`) de um cedente a partir do CNPJ. Útil quando a integração conhece apenas o CNPJ e precisa do `idEmpresa` exigido pelos demais endpoints (vínculo com operações, contas, pessoas, etc.). ### Path Params | Campo | Tipo | Descrição | | ------ | ---------- | ------------------------------------- | | `cnpj` | Texto (14) | CNPJ do cedente. Aceita **com ou sem máscara** — pontos, barra (`/`) e traço são normalizados (ex.: `12.345.678/0001-99` é tratado como `12345678000199`). | ```json title="Response Body — 200 OK" { "idEmpresa": 123, "cnpj": "12345678000199", "nome": "Empresa Exemplo LTDA", "status": "Ativo" } ``` ```json title="Response Body — 400 Bad Request" { "status": "erro", "mensagem": "Empresa com o CNPJ 12345678000199 não encontrada." } ``` ### Retorno | Campo | Tipo | Descrição | | ----------- | ------ | ------------------------------------------- | | `idEmpresa` | Número | Identificador da empresa cedente. | | `cnpj` | Texto | CNPJ (somente números). | | `nome` | Texto | Razão social / nome do cedente. | | `status` | Texto | Situação do cadastro (`Ativo` / `Inativo`), derivada da inativação do cedente. | !!! note "Status x data de inativação" Este endpoint retorna apenas o `status` resumido (`Ativo`/`Inativo`). Para a **data exata** da inativação (`dataInativacao`), use o [GET `/cedentes/{idEmpresa}`](#consultar-cedente). --- ## Consultar Cedente por Documento (CPF ou CNPJ) | Método | URL | | --------------------------------------------- | ------------------------------------------- | | ![GET](https://img.shields.io/badge/GET-blue) | `https://BASE_URL/public/api/v1/cedentes/por-documento/{cpfCnpj}` | Resolve o identificador (`idEmpresa`) de um cedente a partir do documento, aceitando **CPF** (Pessoa Física) ou **CNPJ** (Pessoa Jurídica). Substitui o [GET `/cedentes/por-cnpj/{cnpj}`](#consultar-cedente-por-cnpj), descontinuado. ### Path Params | Campo | Tipo | Descrição | | --------- | ------------- | ------------------------------------- | | `cpfCnpj` | Texto (11/14) | CPF (11 dígitos) ou CNPJ (14 dígitos) do cedente. O tipo é detectado pelo tamanho. Aceita **com ou sem máscara** — pontos, barra (`/`) e traço são normalizados (ex.: `12.345.678/0001-99` é tratado como `12345678000199`). | ```json title="Response Body — 200 OK (Pessoa Jurídica)" { "idEmpresa": 123, "cnpj": "12345678000199", "nome": "Empresa Exemplo LTDA", "status": "Ativo" } ``` ```json title="Response Body — 200 OK (Pessoa Física)" { "idEmpresa": 124, "cpf": "52998224725", "nome": "José Osmar Rodrigues Pereira", "status": "Ativo" } ``` ```json title="Response Body — 400 Bad Request" { "status": "erro", "mensagem": "O documento 'abc' deve ter 11 dígitos (CPF) ou 14 dígitos (CNPJ)." } ``` ### Retorno | Campo | Tipo | Descrição | | ----------- | ------ | ------------------------------------------- | | `idEmpresa` | Número | Identificador da empresa cedente. | | `cnpj` | Texto | CNPJ (somente números). Presente apenas para Pessoa Jurídica — omitido para Pessoa Física. | | `cpf` | Texto | CPF (somente números). Presente apenas para Pessoa Física — omitido para Pessoa Jurídica. | | `nome` | Texto | Razão social / nome do cedente. | | `status` | Texto | Situação do cadastro (`Ativo` / `Inativo`), derivada da inativação do cedente. | ### Erros de validação do documento | Situação | Mensagem | | --------------------------------------- | ------------------------------------------------------------------------- | | Tamanho diferente de 11 ou 14 dígitos | `O documento '{valor}' deve ter 11 dígitos (CPF) ou 14 dígitos (CNPJ).` | | 11 dígitos com verificadores inválidos | `O CPF '{valor}' é inválido.` | | 14 dígitos com verificadores inválidos | `O CNPJ '{valor}' é inválido.` | | Documento válido, mas sem cadastro | `Cedente com o documento {valor} não encontrado.` (`404`) | --- ## Atualizar Cedente | Método | URL | | ----------------------------------------------- | ------------------------------------------- | | ![PUT](https://img.shields.io/badge/PUT-orange) | `https://BASE_URL/public/api/v1/cedentes/{idEmpresa}` | Atualiza os dados cadastrais da empresa cedente. O payload possui a mesma estrutura da [criação](#criar-cedente), sendo que todos os campos são opcionais — somente os campos enviados serão atualizados. ```json title="Request Body" { "email": "novo-email@empresaexemplo.com.br", "telefone": { "ddi": "+55", "ddd": "47", "numero": "33224455" }, "classificacaoRisco": 1 } ``` ```json title="Response Body" { "idEmpresa": 123, "status": "Cadastro atualizado com sucesso." } ``` ## Inativar Cedente | Método | URL | | ----------------------------------------------- | ------------------------------------------- | | ![PUT](https://img.shields.io/badge/PUT-orange) | `https://BASE_URL/public/api/v1/cedentes/{idEmpresa}/inativar` | Inativa a empresa cedente. A operação é idempotente: se o cedente já estiver inativo, a data de inativação original é preservada. ### Path Params | Campo | Tipo | Descrição | |-------|------|-----------| | `idEmpresa` | Número | Identificador da empresa cedente. | ```json title="Response Body — 200 OK" { "idEmpresa": 123, "ativo": false, "dataInativacao": "2025-04-01T14:30:00Z", "status": "Cedente inativado com sucesso." } ``` ```json title="Response Body — 400 Bad Request" { "status": "erro", "mensagem": "Cedente com ID 123 não encontrado." } ``` ### Retorno | Campo | Tipo | Descrição | |-------|------|-----------| | `idEmpresa` | Número | Identificador da empresa cedente. | | `ativo` | Booleano | Indica se o cedente está ativo após a operação. | | `dataInativacao` | Data e hora | Data/hora (UTC) da inativação. Nulo quando o cedente está ativo. | | `status` | Texto | Mensagem de status da operação. | ## Reativar Cedente | Método | URL | | ----------------------------------------------- | ------------------------------------------- | | ![PUT](https://img.shields.io/badge/PUT-orange) | `https://BASE_URL/public/api/v1/cedentes/{idEmpresa}/reativar` | Reativa uma empresa cedente inativada, limpando a data de inativação. ### Path Params | Campo | Tipo | Descrição | |-------|------|-----------| | `idEmpresa` | Número | Identificador da empresa cedente. | ```json title="Response Body — 200 OK" { "idEmpresa": 123, "ativo": true, "dataInativacao": null, "status": "Cedente reativado com sucesso." } ``` ```json title="Response Body — 400 Bad Request" { "status": "erro", "mensagem": "Cedente com ID 123 não encontrado." } ``` O modelo de retorno é o mesmo descrito na seção **Retorno** da inativação acima.