Usar a API do QuoteCrest

Visão geral

No plano Business, o QuoteCrest disponibiliza uma API REST completa para que o teu próprio software — um ERP, um CRM, uma app de serviços de campo — possa gerir os orçamentos diretamente. Tudo o que a aplicação faz está disponível: orçamentos e itens, clientes, a biblioteca de itens, taxas de imposto, modelos de termos, pagamentos, geração de PDF, o assistente de orçamentos com IA e os gatilhos de sincronização contabilística.

A referência completa e sempre atualizada dos endpoints está em quotecrest.com/api-docs.

Obter acesso

1. Garante que a tua equipa está no plano Business (Configurações → Faturamento). Chamadas à API de equipas Free ou Pro devolvem 403 plan_required.
2. Vai em Configurações → Desenvolvedores e clica em Registrar aplicação.
3. Dá-lhe um nome, o teu redirect URI (HTTPS, ou localhost durante o desenvolvimento) e os scopes de que precisas: read para acesso de leitura, write para criar e atualizar.
4. Copia o Client Secret quando for mostrado — aparece exatamente uma vez. O Client ID permanece visível na página da aplicação.

Autenticação

A API usa OAuth 2.0 Authorization Code com PKCE — sem chaves de API. A tua app envia um utilizador para /oauth/authorize, ele aprova os scopes solicitados, e tu trocas o código devolvido (mais o teu verificador PKCE) em /oauth/token por um token de acesso.

• Os tokens de acesso duram 2 horas; usa o refresh token para obter um novo par.
• Os refresh tokens rodam a cada utilização — guarda sempre o par mais recente.
• Cada token está vinculado a uma equipa: a equipa do utilizador que o autorizou.

Envia o token em cada pedido:

Authorization: Bearer YOUR_ACCESS_TOKEN

Começa com GET /api/v1/me — devolve a equipa autorizada, as suas predefinições de orçamento e os scopes do teu token.

O que podes construir

• Automação de orçamentos — cria clientes e orçamentos (POST /api/v1/quotes), adiciona itens em massa, envia ou publica, e descarrega o PDF. As predefinições da equipa (termos, validade, condições de pagamento, modo de preços) aplicam-se automaticamente.
• Orçamentos com IA — POST /api/v1/ai_quotes transforma uma descrição do trabalho em linguagem natural num rascunho de orçamento completo usando a tua biblioteca de itens.
• Acompanhamento de pagamentos — consulta o status / payment_status do orçamento ou lista /api/v1/payments para valores, taxas e recebimentos líquidos.
• Contabilidade — verifica o estado da conexão em GET /api/v1/integrations e dispara uma importação do catálogo do QuickBooks ou do Xero com POST /api/v1/integrations/{provider}/sync.

Para um passo a passo completo com pedidos de exemplo, lê o nosso guia em duas partes: configurar o teu espaço de trabalho e ligar a tua app à API.

Limites e erros

• O tráfego geral da API é limitado por IP; a geração com IA está limitada a 10 pedidos por minuto por equipa. Uma resposta 429 significa aguardar e tentar novamente.
• 401 — token expirado ou revogado (atualiza e tenta de novo). 402 insufficient_credits — o saldo de créditos de IA da equipa esgotou-se. 422 — erros de validação, com detalhes no corpo da resposta.

Revoga uma aplicação conectada a qualquer momento em Configurações → Desenvolvedores, ou como utilizador final a partir da tua página de aplicações autorizadas — os seus tokens deixam de funcionar imediatamente.