Faturas

Criação, acompanhamento e gestão de faturas e pagamentos.

GET /api/invoices Auth

Listar Faturas

Retorna a lista paginada de faturas do usuário.

Query Parameters

page integer

Número da página

limit integer

Itens por página (máx: 100)

status string

Filtrar por status: pending, paid, overdue, cancelled

Status Codes

200 Lista retornada com sucesso

401 Não autenticado

Response

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439066",
      "number": "INV-2026-0042",
      "contactId": "507f1f77bcf86cd799439011",
      "total": 7000.00,
      "status": "pending",
      "dueDate": "2026-06-07T00:00:00Z",
      "createdAt": "2026-05-07T10:00:00Z"
    }
  ],
  "total": 28,
  "page": 1,
  "limit": 20
}

POST /api/invoices Auth

Criar Fatura

Gera uma nova fatura com itens do catálogo de produtos.

Request Body

contactId string obrigatório

ID do contato (cliente)

items object[] obrigatório

Lista de itens: { productId, quantity, unitPrice }

dueDate string obrigatório

Data de vencimento (ISO 8601)

notes string opcional

Observações

Status Codes

201 Criado com sucesso

400 Dados inválidos

401 Não autenticado

Request

{
  "contactId": "507f1f77bcf86cd799439011",
  "items": [
    {
      "productId": "507f1f77bcf86cd799439055",
      "quantity": 2,
      "unitPrice": 3500.00
    }
  ],
  "dueDate": "2026-06-07T00:00:00Z",
  "notes": "Pagamento via PIX"
}

Response

{
  "id": "507f1f77bcf86cd799439066",
  "number": "INV-2026-0042",
  "contactId": "507f1f77bcf86cd799439011",
  "items": [
    {
      "productId": "507f1f77bcf86cd799439055",
      "name": "Consultoria Mensal",
      "quantity": 2,
      "unitPrice": 3500.00,
      "total": 7000.00
    }
  ],
  "subtotal": 7000.00,
  "total": 7000.00,
  "status": "pending",
  "dueDate": "2026-06-07T00:00:00Z",
  "createdAt": "2026-05-07T10:00:00Z"
}

GET /api/invoices/:id Auth

Buscar Fatura por ID

Retorna os dados completos de uma fatura específica com itens detalhados.

Status Codes

200 Registro encontrado

401 Não autenticado

403 Sem permissão (não é o proprietário)

404 Não encontrado

Response

{
  "id": "507f1f77bcf86cd799439066",
  "number": "INV-2026-0042",
  "contactId": "507f1f77bcf86cd799439011",
  "items": [
    {
      "productId": "507f1f77bcf86cd799439055",
      "name": "Consultoria Mensal",
      "quantity": 2,
      "unitPrice": 3500.00,
      "total": 7000.00
    }
  ],
  "subtotal": 7000.00,
  "total": 7000.00,
  "status": "pending",
  "dueDate": "2026-06-07T00:00:00Z",
  "notes": "Pagamento via PIX",
  "createdAt": "2026-05-07T10:00:00Z",
  "updatedAt": "2026-05-07T10:00:00Z"
}

PUT /api/invoices/:id Auth

Atualizar Fatura

Atualiza dados de uma fatura. Use para alterar status, itens ou data de vencimento.

Request Body

status string opcional

Status: pending, paid, overdue, cancelled

dueDate string opcional

Nova data de vencimento (ISO 8601)

notes string opcional

Observações

Status Codes

200 Atualizado com sucesso

400 Dados inválidos

401 Não autenticado

403 Sem permissão (não é o proprietário)

404 Não encontrado

Request

{
  "status": "paid"
}

Response

{
  "id": "507f1f77bcf86cd799439066",
  "number": "INV-2026-0042",
  "status": "paid",
  "paidAt": "2026-05-07T16:00:00Z",
  "updatedAt": "2026-05-07T16:00:00Z"
}

DELETE /api/invoices/:id Auth

Remover Fatura

Remove permanentemente uma fatura. Apenas faturas com status "pending" ou "cancelled" podem ser removidas.

Status Codes

200 Removido com sucesso

401 Não autenticado

403 Sem permissão (não é o proprietário)

404 Não encontrado

Response

{
  "message": "Fatura excluída com sucesso"
}

GET /api/invoices/overdue Auth

Faturas Vencidas

Retorna todas as faturas pendentes cujo prazo já expirou.

Status Codes

200 Lista retornada com sucesso

401 Não autenticado

Response

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439066",
      "number": "INV-2026-0038",
      "contactId": "507f1f77bcf86cd799439011",
      "total": 7000.00,
      "dueDate": "2026-04-30T00:00:00Z",
      "status": "pending"
    }
  ],
  "total": 5,
  "totalValue": 23500.00
}