Ir para o conteúdo

7.2. Roteiro Operação Risco Sacado

Roteiro fim-a-fim para deixar uma operação Risco Sacado operacional via API pública — do cadastro do cedente até a importação de títulos. Os passos devem ser executados na ordem abaixo; cada um devolve identificadores usados nos passos seguintes.

Pré-requisitos

  • Credencial de API pública (claim acesso_api_publica) e token obtido conforme Primeiros Passos. Toda requisição envia o Authorization: Bearer e o header GrupoEconomico.
  • A operação Risco Sacado já configurada pela Vertrau (modalidade 2). O cliente não cria operações — apenas se vincula a elas.
  • O sacado pode ser cadastrado pela própria API (ver Passo 6) ou já existir no grupo econômico.

Visão geral

Sequência de chamadas

# Passo Endpoint Resultado / uso
1 Cadastrar o cedente POST /public/api/v1/cedentes idEmpresa (cedente). Já existe? Resolva com GET /public/api/v1/cedentes/por-cnpj/{cnpj}.
2 Completar cadastro POST /cedentes/{idEmpresa}/pessoas, /contatos, /documentos Sócios/representantes, contatos e documentos exigidos para formalização.
3 Cadastrar conta corrente POST /cedentes/{idEmpresa}/contas → GET /cedentes/{idEmpresa}/contas idContaCorrente para usar nos vínculos.
4 Descobrir a operação GET /cedentes/{idEmpresa}/operacoes-disponiveis idOperacao com idModalidadeOperacao = 2 (Risco Sacado).
5 Vincular o cedente (linha base) POST /cedentes/{idEmpresa}/operacoes/{idOperacao} Cria a linha base do cedente (sem sacado). Não envie idSacado.
6 Cadastrar / resolver o sacado POST /public/api/v1/sacados (criar) ou GET /public/api/v1/sacados/por-cnpj/{cnpj} (resolver) idSacado (id da empresa sacado). Ver detalhe.
7 Vincular cada sacado POST /cedentes/{idEmpresa}/operacoes/{idOperacao}/sacados/{idSacado} Cria o par cedente×sacado (limite/deságio por sacado). Repita para cada sacado.
8 Conferir vínculos GET /cedentes/{idEmpresa}/operacoes e GET /cedentes/{idEmpresa}/operacoes/{idOperacao}/sacados Confirma a linha base e os pares antes de operar.
9 Importar títulos Ver Importação de Títulos Avulsos Aceito assim que o cedente está vinculado.
10 Acompanhar o lote Ver Consultar Lote Status do processamento.

Os passos 1 a 3 são o cadastro padrão do cedente (ver Empresa Cedente, Contas Correntes); os passos 4, 5 e 8 (cedente) estão em Vincular Cedente a Operações e os passos 6 e 7 (sacado) em Risco Sacado — Sacados.

Detalhamento dos passos específicos de Risco Sacado

Passo 5 — Vincular o cedente (linha base)

Em Risco Sacado, o vínculo do cedente é a linha base (sem sacado). Não envie idSacado aqui — os sacados são vinculados no passo 7.

POST /cedentes/{idEmpresa}/operacoes/{idOperacao}
{
  "idContaCorrente": 10,
  "coobrigacao": false,
  "limiteCredito": 500000.00
}

Deságio por Fonte Externa

Se a operação calcula o deságio por Fonte Externa (ex.: Q'Prof), não envie percentualDesagio (rejeitado com 400).

Passo 6 — Cadastrar o sacado

O sacado é uma empresa do grupo econômico; o idSacado é o idEmpresa dessa empresa.

  • Não existe ainda? Cadastre via POST /public/api/v1/sacados (ver Cadastrar Sacado). O payload é o mesmo do cadastro de empresa; a operação é idempotente (se o CNPJ já existir, garante o tipo Sacado e devolve o id).
  • Já existe? Resolva o idSacado pelo CNPJ: GET /public/api/v1/sacados/por-cnpj/{cnpj} (ou consulte/liste em Gerenciar Sacado).

Sem a empresa sacado, o Passo 7 retorna 400 ("Sacado não encontrado.").

Passo 7 — Vincular cada sacado

Para cada sacado, crie o par cedente×sacado. Pré-requisito: o cedente já vinculado (passo 5) — senão retorna 400 ("Vincule o cedente à operação antes de vincular o sacado.").

POST /cedentes/{idEmpresa}/operacoes/{idOperacao}/sacados/{idSacado}
{
  "idContaCorrente": 10,
  "limiteCredito": 30000.00
}

Repita para cada sacado. Atualize um par com PUT .../sacados/{idSacado} e remova com DELETE .../sacados/{idSacado}.

Observações

  • Idempotência: vincular cedente/sacado é idempotente — repetir devolve jaExistia = true sem duplicar.
  • Status do vínculo: o vínculo nasce em "Em avaliação". A aprovação (quando exigida) é feita internamente / via integração com a administradora; a importação de títulos já é aceita assim que o vínculo existe.
  • Limite de crédito: em Risco Sacado o limite é por par cedente×sacado (passo 7). A linha base (passo 5) pode ter um limite global do cedente, conforme a operação.
  • Validações: referências (operação, cedente, sacado, conta) são validadas — a conta deve pertencer ao cedente. Valores numéricos são não-negativos e respeitam o teto das colunas.