Cotações

Propostas comerciais com conversão direta para faturas.

GET /api/quotes Auth

Listar Cotações

Retorna a lista paginada de cotações 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: draft, sent, accepted, rejected, converted

Status Codes

200 Lista retornada com sucesso

401 Não autenticado

Response

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439077",
      "number": "QT-2026-0015",
      "contactId": "507f1f77bcf86cd799439011",
      "total": 9450.00,
      "status": "sent",
      "validUntil": "2026-05-30T00:00:00Z",
      "createdAt": "2026-05-07T10:00:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 20
}

POST /api/quotes Auth

Criar Cotação

Gera uma proposta comercial com itens do catálogo.

Request Body

contactId string obrigatório

ID do contato

items object[] obrigatório

Itens: { productId, quantity, unitPrice, discount }

validUntil string opcional

Data de validade (ISO 8601)

notes string opcional

Condições comerciais

Status Codes

201 Criado com sucesso

400 Dados inválidos

401 Não autenticado

Request

{
  "contactId": "507f1f77bcf86cd799439011",
  "items": [
    {
      "productId": "507f1f77bcf86cd799439055",
      "quantity": 3,
      "unitPrice": 3500.00,
      "discount": 10
    }
  ],
  "validUntil": "2026-05-30T00:00:00Z",
  "notes": "Desconto para contrato anual"
}

Response

{
  "id": "507f1f77bcf86cd799439077",
  "number": "QT-2026-0015",
  "contactId": "507f1f77bcf86cd799439011",
  "items": [...],
  "subtotal": 10500.00,
  "discount": 1050.00,
  "total": 9450.00,
  "status": "draft",
  "validUntil": "2026-05-30T00:00:00Z",
  "createdAt": "2026-05-07T10:00:00Z"
}

GET /api/quotes/:id Auth

Buscar Cotação por ID

Retorna os dados completos de uma cotação 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": "507f1f77bcf86cd799439077",
  "number": "QT-2026-0015",
  "contactId": "507f1f77bcf86cd799439011",
  "items": [
    {
      "productId": "507f1f77bcf86cd799439055",
      "name": "Consultoria Mensal",
      "quantity": 3,
      "unitPrice": 3500.00,
      "discount": 10,
      "total": 9450.00
    }
  ],
  "subtotal": 10500.00,
  "discount": 1050.00,
  "total": 9450.00,
  "status": "sent",
  "validUntil": "2026-05-30T00:00:00Z",
  "notes": "Desconto para contrato anual",
  "createdAt": "2026-05-07T10:00:00Z"
}

PUT /api/quotes/:id Auth

Atualizar Cotação

Atualiza dados de uma cotação. Use para alterar status, itens ou validade.

Request Body

status string opcional

Status: draft, sent, accepted, rejected

validUntil string opcional

Nova data de validade (ISO 8601)

notes string opcional

Condições comerciais

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": "accepted"
}

Response

{
  "id": "507f1f77bcf86cd799439077",
  "number": "QT-2026-0015",
  "status": "accepted",
  "updatedAt": "2026-05-07T15:30:00Z"
}

DELETE /api/quotes/:id Auth

Remover Cotação

Remove permanentemente uma cotação. Apenas cotações com status "draft" 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": "Cotação excluída com sucesso"
}

POST /api/quotes/:id/convert-to-invoice Auth

Converter em Fatura

Converte uma cotação aceita em fatura. Itens, valores e condições são copiados automaticamente.

Status Codes

201 Fatura gerada a partir da cotação

400 Cotação não pode ser convertida (status inválido)

404 Cotação não encontrada

Response

{
  "invoice": {
    "id": "507f1f77bcf86cd799439088",
    "number": "INV-2026-0043",
    "total": 9450.00,
    "status": "pending",
    "createdAt": "2026-05-07T12:00:00Z"
  },
  "quote": {
    "id": "507f1f77bcf86cd799439077",
    "status": "converted"
  }
}