schema-cobranca-api

Schema: Cobrança (API)

Documentação dos campos do banco de dados para cobranças e como atualizá-los via API.

Campos Disponíveis

Identificação

Campo	Tipo	Descrição
id	string	ID único da cobrança (cuid)
clientId	string	ID do cliente (credor)
description	string	Descrição da cobrança

Valores

Campo	Tipo	Descrição
amount	Decimal	Valor da cobrança
dueDate	DateTime	Data de vencimento

Status

Campo	Tipo	Valores	Descrição
status	enum	PENDING, AUTHORIZED, SENT, PARTIAL, PAID, OVERDUE, NEGOTIATING, WRITTEN_OFF	Status da cobrança

Documento e Autorização

Campo	Tipo	Descrição
documentUrl	string?	URL do PDF/documento
documentName	string?	Nome do arquivo
authorized	boolean	Se foi autorizada para cobrança
authorizedAt	DateTime?	Data da autorização
authorizedBy	string?	ID de quem autorizou

WhatsApp

Campo	Tipo	Descrição
whatsappSent	boolean	Se mensagem foi enviada
whatsappSentAt	DateTime?	Data/hora do envio
whatsappMessageId	string?	ID da mensagem no WhatsApp

Pagamento

Campo	Tipo	Descrição
debtorClaimedPayment	boolean	Devedor informou que pagou
debtorClaimedPaymentAt	DateTime?	Quando informou
paymentConfirmed	boolean	Pagamento confirmado
paymentConfirmedAt	DateTime?	Data confirmação
paymentConfirmationUrl	string?	URL do comprovante

Análise

Campo	Tipo	Descrição
analysisNotes	string?	Notas de análise
analysisRating	int?	Rating 1-5 do atendimento
observations	JSON?	Array de observações
metadata	JSON?	Dados extras

---

APIs Disponíveis

Listar Cobranças

GET /api/collections

Detalhes de uma Cobrança

GET /api/collections/{id}

Atualizar Cobrança (PATCH)

PATCH /api/collections/{id}
Content-Type: application/json

{
  status: SENT,
  description: Nova descrição,
  authorized: true,
  whatsappSent: true,
  paymentConfirmed: true,
  analysisNotes: Cliente receptivo
}

Marcar como Enviada (interno)

POST /api/internal/collections/mark-sent
Content-Type: application/json
Authorization: Bearer {GATEWAY_TOKEN}

{
  collectionId: id-da-cobranca,
  messageId: id-mensagem-whatsapp
}

---

Fluxo de Status

PENDING → AUTHORIZED → SENT → PAID
                  ↓         ↓
            NEGOTIATING  PARTIAL
                  ↓         ↓
             WRITTEN_OFF  OVERDUE

Transições Comuns

De	Para	Quando
PENDING	AUTHORIZED	Cliente autoriza cobrança
AUTHORIZED	SENT	Mensagem enviada ao devedor
SENT	PAID	Pagamento confirmado
SENT	PARTIAL	Pagamento parcial
SENT	NEGOTIATING	Em negociação
SENT	OVERDUE	Venceu sem pagamento
NEGOTIATING	PAID	Acordo cumprido
OVERDUE	WRITTEN_OFF	Dado como perdido

---

Exemplos de Uso

Após enviar WhatsApp:

curl -X POST http://denardi-escritorio-legal-web:3000/api/internal/collections/mark-sent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"collectionId": "xxx", "messageId": "whatsapp-msg-id"}'

Marcar pagamento informado:

curl -X PATCH http://denardi-escritorio-legal-web:3000/api/collections/xxx \
  -H "Content-Type: application/json" \
  -d '{"debtorClaimedPayment": true}'

Confirmar pagamento:

curl -X PATCH http://denardi-escritorio-legal-web:3000/api/collections/xxx \
  -H "Content-Type: application/json" \
  -d '{"paymentConfirmed": true, "status": "PAID"}'

---

Documentação criada em 2026-02-03