Appointier

Sviluppatori

I tuoi dati sono tuoi. Leggili e modificali tramite l'API GraphQL e ricevi un webhook firmato quando succede qualcosa.

Token API

Crea un token nel Pannello di controllo, in Dati e integrazioni, e scegli cosa può leggere o modificare. Invialo come token Bearer all'endpoint /graphql della tua attività. Lo schema completo è su /graphql/schema.

curl https://your-business.appointier.com/graphql \
  -H "Authorization: Bearer $APPOINTIER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ customers(first: 5) { edges { node { firstName lastName email } } } }"}'

Ambiti

Un token porta con sé gli ambiti che scegli. Report e impostazioni sono in sola lettura; ogni altra area ha un ambito di lettura e uno di scrittura. Il ruolo di chi ha creato il token limita comunque ciò che può raggiungere.

  • read
  • write
  • customers.read
  • customers.write
  • appointments.read
  • appointments.write
  • catalog.read
  • catalog.write
  • packages.read
  • packages.write
  • sales.read
  • sales.write
  • invoices.read
  • invoices.write
  • reports.read
  • settings.read

Webhook

Ogni consegna include un header Appointier-Signature con un timestamp e un HMAC-SHA256 del timestamp e del corpo grezzo, calcolato con il segreto del tuo endpoint. Rifiuta tutto ciò che ha più di cinque minuti.

import crypto from "node:crypto";

export function verify(body, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (age > toleranceSeconds) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${body}`)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Eventi

  • appointment.created
  • appointment.updated
  • appointment.canceled
  • appointment.completed
  • appointment.no_show
  • customer.created
  • customer.updated
  • sale.completed
  • sale.voided
  • package.sold
  • package.redeemed
  • package.reversed
  • invoice.paid

Una consegna fallita viene ritentata dopo 1 minuto, 5 minuti, 30 minuti, 2 ore e 12 ore. Dopo 10 errori consecutivi l'endpoint viene sospeso e il titolare riceve un'e-mail. Qualsiasi consegna può essere rinviata dal registro.

Export completo

I titolari possono richiedere uno ZIP con ogni tabella in CSV e JSON Lines, più foto, moduli firmati, PDF delle note e un manifesto con il numero di righe. Il link arriva via e-mail e vale 24 ore.

  • customers
  • appointments
  • catalog
  • staff
  • locations
  • packages
  • memberships
  • gift_cards
  • forms
  • notes
  • products
  • sales
  • invoices
  • payments
  • notifications
  • audits

Lo stesso ZIP può essere consegnato ogni giorno o ogni settimana a un bucket Amazon S3, a un archivio compatibile con S3 o a un host SFTP.

Limiti di richieste

Ogni token può fare 600 richieste al minuto e ogni risposta include X-RateLimit-Limit e X-RateLimit-Remaining.