💡 Casos de uso

📝 1. Caso de Uso: Envio de Título

Operação parcialmente assíncrona que cria um novo título na Plataforma Liber. O Sacado confere o resultado fazendo polling no recurso do título, caso não utilize o Webhook.

Item	Descrição
Nome do Caso de Uso	Envio de Título
Ator Principal	Sacado
Sistemas Envolvidos	API Liber Connect, Plataforma Liber
Objetivo	Permitir que o Sacado envie (crie) um novo título na Plataforma Liber
Início	Envio de `HTTP POST` para `/invoices`
Validação Inicial	API valida estrutura e dados da requisição
Encaminhamento	API envia solicitação de criação à Plataforma Liber
Resposta Inicial	Retorno imediato com `HTTP 202 Accepted`
Processamento	Assíncrono – título processado posteriormente

Resultado

Resultado - Sucesso	Campo `status` do título é preenchido
Resultado - Falha	Campo `status` permanece `null`, campo `errors` contém inconsistências

Reenvio

Reenvio	Título rejeitado pode ser corrigido e reenviado
Observações	Polling (`GET /invoices/{id}`) deve ser usado para acompanhar o status
	Durante a criação do título na Plataforma Líber (pode levar alguns instantes), qualquer GET /invoices/{ref} (mensagem 4) retorna: { "status": null }

📝 1.2 Caso de uso: Envio de título com status "Bloqueado"

Como apresentado anteriormente, a operação Envio de título permite a criação de novos títulos na Plataforma Liber. Porém, nesta operação, o Sacado poderá enviar os títulos com o status BLOQUEADO (BLOCKED), para que posteriormente Atualize ou Desbloqueie os títulos desejados via API ou Plataforma da Liber.
Lembrando que o envio do título BLOQUEADO não é obrigatório.

📝 2. Caso de Uso: Obtenção de Título

A operação de Obtenção de um título permite que o Sacado recupere o estado atual de um título na Plataforma Liber. Neste sentido, o Sacado pode utilizar essa operação para realizar polling e conhecer o resultado das operações requisitadas sobre um título, bem como verificar se o título foi vendido a um financiador.

Item	Descrição
Nome do Caso de Uso	Obtenção de Título
Ator Principal	Sacado
Sistemas Envolvidos	API Liber Connect
Objetivo	Permitir que o Sacado consulte o estado atual de um título
Início	Envio de `HTTP GET` para `/invoices/{reference-id}`
Processo	API retorna a última representação do título com seus campos atualizados
Uso Comum	Polling para verificar se o título foi criado, vendido, alterado ou rejeitado
Situação Especial	Recomendado verificar se `status = SOLD` e `last_trade.status = COMPLETED` para confirmar venda
Recomendação Extra	Aguardar 24h após `last_trade.completed_at` antes de ações críticas (ex: baixa de pagamento)
Observações	Requisições de consulta são síncronas e retornam o estado mais recente

📝 3. Caso de Uso: Atualização de Título

A operação Atualização do título permite que os campos Vencimento, Valor de Face e Financiador (due_date, face_valuee appointed_funder) de um título enviado sejam modificados segundo as alterações no sistema do cliente. Só é permitido realizar alterações em títulos que estejam no estado BLOQUEADO (BLOCKED), para evitar que títulos que estejam em processo de negociação sejam alterados.

Item	Descrição
Nome do Caso de Uso	Atualização de Título
Ator Principal	Sacado
Sistemas Envolvidos	API Liber Connect, Plataforma Liber
Objetivo	Permitir a alteração dos campos `due_date`, `face_value` e `appointed_funder` de um título
Pré-condição	Título deve estar no estado `BLOCKED`
Início	Envio de `HTTP PUT` para `/invoices/{reference-id}` com os dados atualizados
Validação Inicial	API valida dados e estrutura
Encaminhamento	API envia atualização para a Plataforma Liber
Resposta Inicial	`HTTP 202 Accepted` com os dados antigos do título
Processamento	Assíncrono – alterações aplicadas posteriormente
Resultado - Sucesso	Estado atualizado retornado via `GET`, título é automaticamente desbloqueado
Resultado - Falha	Título permanece inalterado; campo `errors` indica problemas
Observações	- Campos não permitidos são ignorados ou geram erro - Obtenha o título antes de atualizar

📝 4. Caso de Uso: Busca na Lista de Títulos

A operação Busca na lista de títulos permite que o Sacado recupere rapidamente uma lista paginada dos títulos previamente inseridos. Filtros estão disponíveis para restringir os títulos a serem retornados.

Item	Descrição
Nome do Caso de Uso	Busca na Lista de Títulos
Ator Principal	Sacado
Sistemas Envolvidos	API Liber Connect
Objetivo	Permitir que o Sacado recupere uma lista paginada de títulos inseridos
Início	Envio de `HTTP GET` para `/invoices`
Parâmetros	Filtros opcionais e paginação (`?p=2`, por exemplo)
Processo	API retorna a primeira página da lista com os títulos filtrados
Continuação	Sacado pode navegar entre páginas usando o parâmetro `p` = número página
Observações	Numeração de páginas inicia em 1

📝 5. Caso de Uso: Bloqueio de Título

A operação de Bloqueio de um título permite tornar um dado título indisponível a ser antecipado. Dessa maneira, o título não poderá mais ser utilizado em negociações entre um fornecedor e investidores.
É também Pré-condição obrigatória para operação de atualização do título.

Item	Descrição
Nome do Caso de Uso	Bloqueio de Título
Ator Principal	Sacado
Sistemas Envolvidos	API Liber Connect, Plataforma Liber
Objetivo	Tornar um título indisponível para negociação
Início	Envio de `HTTP PUT` para `/invoices/{reference-id}/block` com motivo
Pré-condição	Título não pode estar em `UNDER_NEGOTIATION` ou `SOLD`
Processo	API valida requisição, solicita bloqueio à Plataforma e retorna `202 Accepted`
Processamento	Assíncrono – bloqueio confirmado posteriormente
Verificação	Polling via `GET /invoices/{id}` para verificar estado `BLOCKED`
Observações	Pré-condição obrigatória para operação de atualização

📝 6. Caso de Uso: Desbloqueio de Título

A operação Desbloqueio de título permite desbloquear um título sem que seja realizada uma atualização dos dados desse título. Dessa maneira, o título torna-se novamente disponível para negociação entre fornecedor e investidores.

Item	Descrição
Nome do Caso de Uso	Desbloqueio de Título
Ator Principal	Sacado
Sistemas Envolvidos	API Liber Connect, Plataforma Liber
Objetivo	Permitir que o título volte a ficar disponível para negociação
Início	Envio de `HTTP DELETE` para `/invoices/{reference-id}/block`
Pré-condição	Título deve estar previamente bloqueado
Processo	API valida e solicita desbloqueio à Plataforma, retornando `202 Accepted`
Processamento	Assíncrono – desbloqueio efetivado posteriormente

📝 7. Caso de Uso: Operação de Busca por Fornecedores

A operação de Busca por Fornecedores permite que o Sacado recupere uma lista paginada com os fornecedores cadastrados na plataforma da Liber. Assim, o Sacado pode filtrar em seu sistema os títulos para envio de acordo com os Fornecedores que estão cadastrados.

Item	Descrição
Nome do Caso de Uso	Operação de Busca por Fornecedores
Ator Principal	Sacado
Sistemas Envolvidos	Sistema do Sacado, API Liber Connect, Plataforma Liber
Objetivo	Permitir que o Sacado recupere uma lista paginada de fornecedores cadastrados na Plataforma Liber para validar se um fornecedor está apto a receber títulos.
Início	Sacado realiza uma requisição HTTP GET para o endpoint `/suppliers` da API Liber Connect.
Pré-condição	Fornecedores devem estar previamente cadastrados na Plataforma Liber e sincronizados com a API Liber Connect.
Processo	1. Plataforma envia atualizações de cadastro para API Liber Connect. 2. Sacado solicita a lista de fornecedores via GET. 3. API retorna a primeira página da lista com dados e metadados de paginação. 4. Sacado pode consultar as demais páginas com o parâmetro `p`.
Processamento	API Liber Connect recupera dados atualizados dos fornecedores e retorna as informações com base nos critérios e filtros aplicados na requisição.

📝 8. Caso de Uso: Operação de Obtenção de Fornecedor

A operação de Obtenção de Fornecedor permite que o Sacado recupere os dados de um fornecedor específico cadastrado na plataforma da Liber. Assim, o Sacado pode obter informações documentais e de contato sobre o Fornecedor pesquisado.

Item	Descrição
Nome do Caso de Uso	Operação de Obtenção de Fornecedor
Ator Principal	Sacado
Sistemas Envolvidos	Sistema do Sacado, API Liber Connect, Plataforma Liber
Objetivo	Permitir que o Sacado consulte informações detalhadas de um fornecedor específico cadastrado na Plataforma Liber.
Início	Sacado realiza uma requisição HTTP GET para o endpoint `/suppliers/{supplier-document-number}`.
Pré-condição	O fornecedor consultado deve estar previamente cadastrado na Plataforma Liber.
Processo	1. Plataforma envia atualizações de fornecedores para a API Liber Connect. 2. Sacado envia requisição GET informando o documento do fornecedor. 3. API retorna os dados atualizados do fornecedor consultado.
Processamento	API Liber Connect consulta os dados do fornecedor com base no documento informado e retorna os dados atualizados (documentais e de contato).

📝 9. Caso de Uso: Download do termo de cessão

Item	Descrição
Nome do Caso de Uso	Recuperação de Termo de Cessão Assinado
Ator Principal	Sacado
Objetivo	Permitir que o sacado realize o download do termo de cessão assinado digitalmente via plataforma Líber
Pré-condição	1. Operação deve estar com status = `SOLD` 2. Ter o ID da operação (Conforme consulta GET `Operations`
Início	Envio de `HTTP GET` para `/programs/{program}/ceded-terms/{document_number}/{operation_id}` - Verificar se `program`, `document_number` (CNPJ raiz 8 dígitos) e `operation_id` foram informados corretamente
Processo	- Comportamento da resposta 307 (redirecionamento para URL de download) - Resposta inicial: 307 - Link temporário de redirecionamento fornecido para acesso ao arquivo - Cliente deve acessar URL retornada (caso 307) dentro do tempo de validade - Recuperação do termo assinado em PDF concluída com sucesso
Resultado - Falha	Parâmetros inválidos, operação não encontrada ou falha na autenticação
Observações	Recomenda-se lógica de fallback para lidar com 307; Comportamento do endpoint será otimizado para entregar o termo com o menor tempo de resposta possível

📝 Webhooks

Item	Descrição
Nome do Caso de Uso	Notificação de Eventos via Webhook
Ator Principal	Sacado (como consumidor dos eventos)
Sistemas Envolvidos	API Liber Connect, Servidor do Sacado, Plataforma Liber
Objetivo	Notificar o Sacado, de forma assíncrona, sobre eventos relacionados a títulos, fornecedores e outras entidades.
Início	A Plataforma Liber envia uma requisição HTTPS para a URL cadastrada pelo Sacado ao ocorrer um evento relevante.
Pré-condição	O Sacado deve ter uma URL de webhook previamente cadastrada e configurada para receber notificações.
Processo	1. Plataforma detecta evento (ex: alteração de status de título). 2. Envia requisição HTTPS para a URL do webhook. 3. Caso falhe, realiza até 6 novas tentativas. 4. Em falhas totais, envia e-mail de notificação (se configurado).
Processamento	O payload do evento contém os campos padrão (`event_type`, `event_timestamp`) e os dados específicos no campo `payload`. A requisição deve ser tratada de forma idempotente pelo serviço do Sacado.