Acesso à API e agentes de IA

O SimplyQuote expõe uma API REST para que os seus agentes de IA, scripts e integrações trabalhem com os seus orçamentos e faturas em seu nome. O acesso é controlado por tokens de acesso pessoais com escopos e revogáveis.

1. Ativar o acesso à API

1. Abra a sua página de configurações e inicie sessão
2. Desça até à secção «Acesso à API e agentes de IA».
3. Dê um nome ao token, escolha os escopos e clique em «Criar token».
4. Copie o token imediatamente — por segurança, é mostrado apenas uma vez.

2. Fazer um pedido

Envie o token como Bearer token no cabeçalho Authorization:

curl https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here"

3. Criar e atualizar documentos

Criar e atualizar orçamentos e faturas usa o mesmo token com um escopo de escrita. Os totais são sempre calculados no servidor a partir dos itens que enviar:

curl -X POST https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Ltd",
    "client_email": "billing@acme.example",
    "items": [
      { "description": "Consulting", "quantity": 4, "unit_price": 120 },
      { "description": "Hosting (1 month)", "quantity": 1, "unit_price": 30 }
    ],
    "currency": "USD",
    "tax_rate": 10,
    "expiry_date": "2026-10-01"
  }'

Resposta de sucesso (as listas são análogas, com quotes/invoices mais total/page/limit/has_more):

// Wrapped envelope (POST/PATCH/lists): { success:true, data:{ quote } }
{
  "success": true,
  "data": {
    "quote": { "id": "uuid", "quote_number": "Q-1001", "total": 528.0 }
  }
}

curl -X PATCH https://simplyquote.net/api/v1/invoices/{id} \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

Listagens e paginação

Os endpoints de listagem aceitam updated_since (ISO 8601), page (por defeito 1), limit (por defeito 20, máximo 100) e status (sem distinção de maiúsculas; valores desconhecidos são ignorados). As respostas incluem total, page, limit e has_more.

GET /api/v1/quotes?status=sent&page=1&limit=20&updated_since=2026-01-01T00:00:00Z

Regras de campos para criar e atualizar

items é obrigatório em POST: array não vazio, cada linha com description não vazia, quantity > 0 (por defeito 1), unit_price >= 0 (por defeito 0). tax_rate é percentagem (0–100); ao criar, tax_rate > 0 implica tax_enabled. currency é guardada em maiúsculas. issue_date aceita qualquer data válida (guardada AAAA-MM-DD). Os orçamentos usam expiry_date e as faturas due_date (qualquer um dos aliases é aceite, null limpa). Estado: orçamentos draft|sent, faturas draft|sent|viewed|paid|cancelled — definir paid regista paid_at. Os totais são sempre recalculados no servidor.

4. Usar com um agente de IA

Dê ao seu agente o URL base, o seu token e a lista de endpoints abaixo. Exemplo de instruções para qualquer agente que use ferramentas (Claude, GPT, LangChain, etc.):

Pode aceder à minha conta SimplyQuote.
URL base: https://simplyquote.net
Em cada pedido, envie o cabeçalho: Authorization: Bearer sq_seu_token_aqui
Endpoints disponíveis: GET/POST /api/v1/quotes, GET/PATCH /api/v1/quotes/{id},
GET/POST /api/v1/invoices, GET/PATCH /api/v1/invoices/{id}, POST /api/mcp
As listas suportam ?page, ?limit (máx. 100), ?status e ?updated_since e devolvem { success:true, data:{ quotes|invoices, total, page, limit, has_more } }.
As leituras individuais devolvem o objeto simples. {id} é o UUID, não o número do documento.
Use POST para criar documentos — envie sempre items com description, quantity e unit_price.

5. Ligar via MCP (recomendado para agentes)

O SimplyQuote inclui um servidor MCP (Model Context Protocol) integrado em /api/mcp (HTTP de streaming sem estado, JSON-RPC 2.0). Agentes que suportem servidores MCP remotos (Claude, ChatGPT, Cursor, VS Code, etc.) podem ligar-se diretamente com o seu token, sem necessidade de engenharia de prompts. Ferramentas disponíveis:

list_quotesget_quotecreate_quotelist_invoicesget_invoicecreate_invoice

{
  "mcpServers": {
    "simplyquote": {
      "type": "http",
      "url": "https://simplyquote.net/api/mcp",
      "headers": {
        "Authorization": "Bearer sq_your_token_here"
      }
    }
  }
}

Exemplo de chamada de ferramenta (JSON-RPC 2.0 — lotes rejeitados, notificações devolvem 202 e GET devolve 405):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_quotes", "arguments": { "limit": 5 } }
}

Cada chamada de ferramenta é validada com os escopos do seu token — um token só de leitura pode listar e consultar, enquanto criar orçamentos ou faturas requer o escopo de escrita correspondente.

Endpoints

Escopos

• quotes:read — Ler os seus orçamentos
• invoices:read — Ler as suas faturas
• clients:read — Reservado — ainda sem endpoint próprio de clientes (os dados do cliente estão nos orçamentos/faturas)
• quotes:write — Criar e atualizar orçamentos
• invoices:write — Criar e atualizar faturas
• clients:write — Reservado — ainda sem endpoint próprio de clientes (os dados do cliente são criados/atualizados implicitamente ao guardar orçamentos/faturas)

Formato de resposta e erros

Os endpoints REST usam dois formatos — verifique qual se aplica em cada caso:

{
  "success": true,
  "data": { ... },
  "error": { "code": "...", "message": "...", "details": { ... } }
}

As leituras individuais devolvem o objeto simples acima (sem envelope), com erros planos { error, message } — p. ex. 404 se o id for desconhecido. As listas e POST/PATCH usam sempre o envelope.

// Flat envelope (single GET): bare object, no success/data wrapper
{
  "id": "uuid",
  "quote_number": "Q-1001",
  "status": "sent",
  "total": 528.0
}

// unknown id:
{ "error": "not_found", "message": "Quote not found" }

• success — true em caso de sucesso, false em caso de falha
• data — os dados em caso de sucesso
• error — código de erro, mensagem e detalhes opcionais em caso de falha

Os códigos de erro mais comuns:

• UNAUTHORIZED — Token em falta, inválido ou expirado (HTTP 401)
• FORBIDDEN — O token não tem o escopo necessário (HTTP 403)
• VALIDATION_ERROR — O corpo do pedido falhou a validação (HTTP 400)
• NOT_FOUND — O documento pedido não existe (HTTP 404)
• DATABASE_ERROR — Erro de armazenamento ao processar o pedido (HTTP 500)
• RATE_LIMIT — Demasiados pedidos — tente mais tarde (HTTP 429)

Webhooks, OAuth e referência completa

Webhooks: gira subscrições com GET/POST/PATCH/DELETE /api/v1/webhooks (qualquer token válido, sem escopo específico). A url tem de ser um endpoint HTTPS público. O segredo só é devolvido na criação — verifique as entregas com o cabeçalho X-SimplyQuote-Signature (HMAC-SHA256).

As apps parceiras usam OAuth 2.0 (/api/oauth/authorize, /api/oauth/token, /api/oauth/revoke) em vez de tokens pessoais. Detalhes em docs/API.md e na especificação legível por máquinas em /api/v1/openapi.json.

Notas de segurança

• Os tokens são guardados com hash — o SimplyQuote nunca guarda o token em texto simples.
• Conceda apenas os escopos de que o seu agente precisa; os de só leitura são normalmente suficientes.
• Revogue um token a qualquer momento nas Configurações para cortar o acesso imediatamente.
• Uma especificação legível por máquinas para agentes está disponível em /api/v1/openapi.json