Collegare la tua app o il tuo ERP alle API di QuoteCrest

Nella parte 1 abbiamo configurato uno spazio di lavoro QuoteCrest — Stripe, sincronizzazione contabile, aliquote fiscali, termini e una libreria degli articoli. Ora collegheremo quello spazio di lavoro alla tua applicazione o al tuo ERP, così i preventivi scorrono attraverso i tuoi sistemi esistenti invece che in una scheda del browser.

La REST API di QuoteCrest offre ai team del piano Business l'intera superficie dell'app: preventivi e voci, clienti, la libreria degli articoli, aliquote fiscali, modelli di termini, pagamenti, il generatore di preventivi con IA e i trigger di sincronizzazione contabile. Il riferimento completo è su quotecrest.com/api-docs; questo articolo è il tour guidato da zero alla prima chiamata API.

Passo 1: Registra un'applicazione OAuth

In QuoteCrest, vai in Impostazioni → Sviluppatori e clicca su Registra applicazione. Ti servono tre cose:

• Nome — mostrato al tuo team nella schermata di autorizzazione ("ERP Sync", "Acme Field App").
• Redirect URI — dove QuoteCrest rimanda gli utenti dopo l'autorizzazione. Deve essere HTTPS (localhost è consentito per lo sviluppo). Una URI per riga.
• Scope — read per l'accesso in lettura, write per creare e aggiornare. Richiedi solo ciò che ti serve.

Lascia attivo Client confidenziale per le app lato server in grado di proteggere un segreto. Alla creazione ottieni un Client ID e — una sola volta — un Client Secret. Copia subito il secret; viene salvato con hash e non può essere mostrato di nuovo.

Passo 2: Autorizza con OAuth 2.0 + PKCE

QuoteCrest usa il grant Authorization Code con PKCE, obbligatorio per ogni client. Il flusso:

1. Genera un code verifier e una challenge. Una stringa casuale e il suo hash SHA-256, codificato in base64url:

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

2. Manda l'utente alla schermata di autorizzazione:

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

L'utente accede, vede cosa potrà fare la tua app e approva. QuoteCrest reindirizza alla tua redirect_uri con un parametro ?code=.

3. Scambia il codice con i token:

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

Ricevi un access_token (valido 2 ore), un refresh_token e gli scope concessi. Gli access token sono vincolati a un solo team — il team dell'utente che ha autorizzato. I refresh token ruotano a ogni utilizzo: ogni refresh restituisce una nuova coppia e il vecchio refresh token viene invalidato, quindi salva la coppia più recente in modo atomico.

Passo 3: Fai la tua prima chiamata

Ogni richiesta invia il token come header Bearer. Comincia da /me, che restituisce il team autorizzato, i suoi valori predefiniti (termini di pagamento, scadenza dei preventivi, modalità di prezzo) e gli scope del tuo token:

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

Gli endpoint di elenco si paginano con page e per_page (massimo 100) e restituiscono un blocco meta con i totali.

Passo 4: Il flusso ERP essenziale

Un'integrazione tipica rispecchia ciò che una persona fa nell'app — creare il cliente, costruire il preventivo, inviarlo e tenere d'occhio accettazione e pagamento.

Crea un 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"}}'

Crea un preventivo — i valori predefiniti del team (modello di termini, scadenza, termini di pagamento, modalità di prezzo) si applicano automaticamente a tutto ciò che ometti:

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}}'

Aggiungi le voci in una sola chiamata con bulk_create, poi invia:

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 invia al cliente via email il link al portale; usa invece publish se la tua app consegna il link da sola. Il campo portal_url del preventivo è la pagina vista dal cliente, e GET /api/v1/quotes/7/pdf restituisce il PDF renderizzato per il tuo archivio documenti.

Monitora accettazione e pagamento interrogando il preventivo (status, payment_status, payment_due) o elencando /api/v1/payments — ogni pagamento riporta importo, commissioni e netto. Quando un preventivo viene accettato con la sincronizzazione automatica attiva, la fattura arriva in QuickBooks o Xero senza un'altra chiamata API; puoi anche avviare in qualsiasi momento un aggiornamento del catalogo con POST /api/v1/integrations/quickbooks/sync (o xero).

Oppure salta del tutto la costruzione manuale. Una sola chiamata al generatore di preventivi con IA trasforma una descrizione del lavoro in linguaggio naturale in una bozza completa — titolo, ambito dei lavori e voci con prezzi che usano la tua libreria degli articoli e le tue categorie:

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}'

Errori, limiti e buona educazione

• 401 — token mancante, scaduto o revocato. Fai il refresh e riprova.
• 403 plan_required — il team non è su Business. 403 feature_disabled — un feature flag (per es. la generazione con IA) è disattivato per il team.
• 402 insufficient_credits — il saldo dei crediti IA del team è esaurito.
• 422 — errori di validazione, con i dettagli nel corpo della risposta.
• 429 — limite di richieste superato. Il traffico API generale è limitato per IP; la generazione con IA è limitata a 10 richieste al minuto per team. Rallenta e riprova dopo il ritardo indicato.

Due abitudini terranno la tua integrazione noiosa (nel senso buono): tratta il client secret e i refresh token come password — solo lato server, cifrati a riposo — e costruisci la tua sincronizzazione attorno all'idempotenza, controllando se un record esiste già prima di crearlo, perché i tuoi utenti possono sempre modificare le cose direttamente in QuoteCrest.

Il riferimento completo degli endpoint, gli schemi e i formati di errore sono su quotecrest.com/api-docs. Se costruisci qualcosa sulle API, ci farebbe davvero piacere saperlo.