Ligar a tua app ou ERP à API do QuoteCrest

Na parte 1 configurámos um espaço de trabalho do QuoteCrest — Stripe, sincronização de contabilidade, taxas de imposto, termos e uma biblioteca de artigos. Agora vamos ligar esse espaço de trabalho à tua própria aplicação ou ERP, para que os orçamentos fluam pelos teus sistemas existentes em vez de num separador do navegador.

A REST API do QuoteCrest dá às equipas do plano Business toda a superfície da app: orçamentos e linhas, clientes, a biblioteca de artigos, taxas de imposto, modelos de termos, pagamentos, o gerador de orçamentos com IA e os gatilhos de sincronização de contabilidade. A referência completa está em quotecrest.com/api-docs; este artigo é a visita guiada do zero até à primeira chamada à API.

Passo 1: Regista uma aplicação OAuth

No QuoteCrest, vai a Configurações → Desenvolvedores e clica em Registrar aplicação. Vais precisar de três coisas:

Nome — mostrado à tua equipa no ecrã de autorização ("ERP Sync", "Acme Field App").
Redirect URI — para onde o QuoteCrest envia os utilizadores depois de autorizarem. Tem de ser HTTPS (localhost é permitido para desenvolvimento). Uma URI por linha.
Scopes — read para acesso de leitura, write para criar e atualizar. Pede apenas o que precisas.

Mantém Cliente confidencial ativo para apps do lado do servidor capazes de proteger um segredo. Na criação recebes um Client ID e — exatamente uma vez — um Client Secret. Copia o secret de imediato; é guardado com hash e não pode voltar a ser mostrado.

Passo 2: Autoriza com OAuth 2.0 + PKCE

O QuoteCrest usa o grant Authorization Code com PKCE, obrigatório para todos os clientes. O fluxo:

1. Gera um code verifier e um challenge. Uma string aleatória e o seu hash SHA-256, codificado em base64url:

code_verifier  = random 43-128 char string
code_challenge = base64url( sha256(code_verifier) )

2. Envia o utilizador para o ecrã de autorização:

GET https://quotecrest.com/oauth/authorize
    ?client_id=YOUR_CLIENT_ID
    &redirect_uri=https://yourapp.com/callback
    &response_type=code
    &scope=read+write
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

O utilizador inicia sessão, vê o que a tua app vai poder fazer e aprova. O QuoteCrest redireciona de volta para a tua redirect_uri com um parâmetro ?code=.

3. Troca o código por tokens:

curl -X POST https://quotecrest.com/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d redirect_uri=https://yourapp.com/callback \
  -d code=AUTHORIZATION_CODE \
  -d code_verifier=CODE_VERIFIER

Recebes um access_token (válido por 2 horas), um refresh_token e os scopes concedidos. Os access tokens estão vinculados a uma única equipa — a equipa do utilizador que autorizou. Os refresh tokens rodam a cada utilização: cada refresh devolve um novo par e o refresh token antigo é invalidado, por isso guarda o par mais recente de forma atómica.

Passo 3: Faz a tua primeira chamada

Cada pedido envia o token como cabeçalho Bearer. Começa por /me, que devolve a equipa autorizada, as suas predefinições (condições de pagamento, expiração de orçamentos, modo de preços) e os scopes do teu token:

curl https://quotecrest.com/api/v1/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

Os endpoints de listagem paginam com page e per_page (máximo 100) e devolvem um bloco meta com os totais.

Passo 4: O fluxo ERP essencial

Uma integração típica espelha o que uma pessoa faz na app — criar o cliente, montar o orçamento, enviá-lo e ficar atento à aceitação e ao pagamento.

Cria um cliente:

curl -X POST https://quotecrest.com/api/v1/clients \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client": {"name": "Meridian Property Group", "email": "ops@meridian.example"}}'

Cria um orçamento — as predefinições da equipa (modelo de termos, expiração, condições de pagamento, modo de preços) aplicam-se automaticamente a tudo o que omitires:

curl -X POST https://quotecrest.com/api/v1/quotes \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quote": {"title": "Lobby renovation", "client_id": 42, "payment_percentage": 30}}'

Adiciona as linhas numa só chamada com bulk_create e depois envia:

curl -X POST https://quotecrest.com/api/v1/quotes/7/line_items/bulk_create ...
curl -X POST https://quotecrest.com/api/v1/quotes/7/send \
  -H "Authorization: Bearer ACCESS_TOKEN"

send envia ao cliente por email o link do portal; usa antes publish se a tua app entregar o link por conta própria. O campo portal_url do orçamento é a página que o cliente vê, e GET /api/v1/quotes/7/pdf devolve o PDF renderizado para o teu próprio arquivo de documentos.

Acompanha a aceitação e o pagamento consultando o orçamento (status, payment_status, payment_due) ou listando /api/v1/payments — cada pagamento traz o montante, as taxas e o líquido. Quando um orçamento é aceite com a sincronização automática ativa, a fatura chega ao QuickBooks ou ao Xero sem outra chamada à API; também podes acionar a qualquer momento uma atualização do catálogo com POST /api/v1/integrations/quickbooks/sync (ou xero).

Ou salta por completo a montagem manual. Uma única chamada ao gerador de orçamentos com IA transforma uma descrição do trabalho em linguagem corrente num rascunho completo — título, âmbito do trabalho e linhas com preços que usam a tua biblioteca de artigos e as tuas categorias:

curl -X POST https://quotecrest.com/api/v1/ai_quotes \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Replace 12 windows in a two-story office, energy-efficient double glazing", "client_id": 42}'

Erros, limites e bom comportamento

401 — token em falta, expirado ou revogado. Faz refresh e tenta de novo.
403 plan_required — a equipa não está no Business. 403 feature_disabled — um feature flag (por ex., a geração com IA) está desativado para a equipa.
402 insufficient_credits — o saldo de créditos de IA da equipa está esgotado.
422 — erros de validação, com os detalhes no corpo da resposta.
429 — limite de pedidos atingido. O tráfego geral da API é limitado por IP; a geração com IA é limitada a 10 pedidos por minuto por equipa. Abranda e tenta de novo após o atraso indicado.

Dois hábitos vão manter a tua integração aborrecida (no bom sentido): trata o client secret e os refresh tokens como palavras-passe — apenas do lado do servidor, cifrados em repouso — e constrói a tua sincronização em torno da idempotência, verificando se um registo já existe antes de o criar, porque os teus utilizadores podem sempre editar as coisas diretamente no QuoteCrest.

A referência completa de endpoints, os esquemas e os formatos de erro estão em quotecrest.com/api-docs. Se construíres alguma coisa sobre a API, gostávamos genuinamente de saber.