Ir para o conteúdo

7.3. Risco Sacado Sacados

Cadastro e vínculo de sacados para operações Risco Sacado (idModalidadeOperacao = 2), onde o limite e o deságio são controlados por par cedente×sacado.

O passo a passo completo está em Roteiro - Operação Risco Sacado. Em resumo: cadastre e vincule o cedente (linha base) em Vincular Cedente a Operações; então, para cada sacado, (1) cadastre-o como empresa Tipo Sacado e (2) vincule-o ao cedente na operação.

Sacado é uma empresa

O sacado é uma empresa do grupo econômico; o idSacado usado nos vínculos é o idEmpresa dessa empresa. As rotas de cadastro ficam sob /public/api/v1/sacados; as de vínculo sob /public/api/v1/cedentes/{idEmpresa}/operacoes/{idOperacao}/sacados.

Cadastro de Sacados

Gerencia as empresas Tipo Sacado do grupo econômico. O cadastro é independente do vínculo: uma vez criada a empresa sacado, ela pode ser vinculada a quantos cedentes/operações forem necessários.

Cadastrar Sacado

Método URL
POST https://BASE_URL/public/api/v1/sacados

Cria uma empresa do tipo Sacado. Idempotente: se já existir empresa com o mesmo CNPJ no grupo econômico, garante o tipo Sacado nela e devolve o idEmpresa. O payload é o mesmo do cadastro de empresa (CNPJ, nome, razão social, e-mail, telefone, endereço, etc.).

Response Body — 200 OK
{
  "idEmpresa": 456,
  "cnpj": "98765432000188",
  "nome": "Sacado Exemplo LTDA",
  "status": "Sacado criado com sucesso."
}

Use o idEmpresa retornado como idSacado em Vincular Sacado.

Consultar Sacado

Método URL
GET https://BASE_URL/public/api/v1/sacados/{idEmpresa}

Retorna o cadastro de um sacado (empresa Tipo Sacado). Empresas que não são sacado retornam 400.

Response Body — 200 OK
{
  "idEmpresa": 456,
  "cnpj": "98765432000188",
  "nome": "Sacado Exemplo LTDA",
  "razaoSocial": "Sacado Exemplo Sociedade LTDA",
  "tipoPessoa": 2,
  "email": "contato@sacado.com.br",
  "inscricaoEstadual": "123456789",
  "inscricaoMunicipal": "987654",
  "codigoCnae": "6499999",
  "situacao": "Ativo",
  "endereco": {
    "logradouro": "Av. Brasil",
    "numero": "1000",
    "complemento": null,
    "bairro": "Centro",
    "cep": "89010000",
    "cidade": "Blumenau",
    "uf": "SC",
    "pais": "BRA"
  }
}

Consultar Sacado por CNPJ

Método URL
GET https://BASE_URL/public/api/v1/sacados/por-cnpj/{cnpj}

Resolve um sacado pelo CNPJ (com ou sem máscara). Mesmo corpo de resposta de Consultar Sacado.

Consultar Sacados em Lote (por CNPJs)

Método URL
POST https://BASE_URL/public/api/v1/sacados/por-cnpjs

Resolve vários sacados de uma vez. Retorna apenas os encontrados (Tipo Sacado).

Request Body
{
  "cnpjs": ["98765432000188", "11222333000181"]
}
Response Body — 200 OK
[
  { "idEmpresa": 456, "cnpj": "98765432000188", "nome": "Sacado Exemplo LTDA", "situacao": "Ativo" }
]

Listar Sacados (cadastro)

Método URL
GET https://BASE_URL/public/api/v1/sacados

Lista paginada das empresas Tipo Sacado do grupo econômico. Não confundir com Listar Sacados Vinculados (pares cedente×sacado de uma operação).

Query Params

Campo Tipo Descrição
nome Texto Filtro por nome (substring, case-insensitive).
cnpj Texto Filtro por CNPJ (com ou sem máscara).
indicePagina Número Índice da página (1-based). Default: 1.
tamanhoDaPagina Número Tamanho da página (1 a 100). Default: 20.
Response Body — 200 OK
{
  "registros": [
    { "idEmpresa": 456, "cnpj": "98765432000188", "nome": "Sacado Exemplo LTDA", "situacao": "Ativo" }
  ],
  "paginacao": {
    "paginaAtual": 1,
    "paginaTotal": 1,
    "paginaQuantidadeRegistro": 20,
    "quantidadeRegistros": 1,
    "temPaginaAnterior": false,
    "temProximaPagina": false
  },
  "mensagem": null
}

O envelope de paginação (paginacao) é o mesmo de toda listagem paginada da API — descrito em Envelope de Paginação.

Atualizar Sacado

Método URL
PUT https://BASE_URL/public/api/v1/sacados/{idEmpresa}

Atualiza parcialmente o cadastro de um sacado — somente os campos enviados são alterados. O payload é o mesmo da atualização de cedente (todos opcionais). Empresas que não são sacado retornam 400.

Request Body
{
  "nome": "Sacado Exemplo Atualizado",
  "email": "novo-contato@sacado.com.br"
}
Response Body — 200 OK
{
  "idEmpresa": 456,
  "status": "Sacado atualizado com sucesso."
}

Vínculo de Sacados

Em operações Risco Sacado, além do vínculo base do cedente, cada par cedente×sacado deve ser vinculado. Pré-requisito: o cedente já deve estar vinculado à operação (linha base) — ver Vincular Cedente a Operação. O corpo de requisição/retorno é o mesmo modelo de Vínculo do cedente.

Listar Sacados Vinculados

Método URL
GET https://BASE_URL/public/api/v1/cedentes/{idEmpresa}/operacoes/{idOperacao}/sacados

Lista os pares cedente×sacado da operação (cada item é um Vínculo com idSacado preenchido).

Vincular Sacado

Método URL
POST https://BASE_URL/public/api/v1/cedentes/{idEmpresa}/operacoes/{idOperacao}/sacados/{idSacado}

Vincula um sacado ao cedente na operação. Idempotente. Rejeita 400 se a operação não for Risco Sacado, se o cedente ainda não estiver vinculado, ou (Fonte Externa) se percentualDesagio for enviado.

Path Params

Campo Tipo Descrição
idEmpresa Número Identificador da empresa cedente.
idOperacao Número Identificador da operação.
idSacado Número Identificador da empresa sacado.
Request Body
{
  "idContaCorrente": 10,
  "limiteCredito": 30000.00
}
Response Body — 200 OK
{
  "jaExistia": false,
  "mensagem": "Vínculo de sacado criado com sucesso.",
  "vinculo": {
    "idVinculo": 88,
    "idOperacao": 9,
    "nomeOperacao": "Risco Sacado Varejo",
    "idEmpresa": 123,
    "idSacado": 456,
    "idModalidadeOperacao": 2,
    "status": "Em avaliação",
    "coobrigacao": null,
    "limiteCredito": 30000.00,
    "percentualDesagio": null,
    "idContaCorrente": 10,
    "prazoTac": null,
    "prazoLimiteNegociacao": null,
    "taxaTac": null,
    "taxaJurosDia": null,
    "numeroContrato": null,
    "dataContrato": null
  }
}

Atualizar / Desvincular Sacado

Método URL
PUT https://BASE_URL/public/api/v1/cedentes/{idEmpresa}/operacoes/{idOperacao}/sacados/{idSacado}
DELETE https://BASE_URL/public/api/v1/cedentes/{idEmpresa}/operacoes/{idOperacao}/sacados/{idSacado}

O PUT atualiza os parâmetros do par (campos null preservam o valor atual) e retorna o Vínculo. O DELETE remove o par e retorna { "status": "sucesso", "mensagem": "Vínculo de sacado removido com sucesso." }.

Modelo de Dados

O corpo de requisição (limiteCredito, idContaCorrente, etc.) e o retorno de vínculo (incluindo o envelope { jaExistia, mensagem, vinculo }) são compartilhados entre cedente e sacado. A referência completa de campos está em Vincular Cedente a Operações → Modelo de Dados.

Limite por par

Em Risco Sacado o limite de crédito é controlado por par cedente×sacado. Para acompanhar total/tomado/disponível e os títulos que compõem o tomado de cada par, use Consultar Limite de Crédito (variantes .../sacados/{idSacado}/limite).