Appointier

Dla programistów

Twoje dane należą do Ciebie. Odczytuj je i zmieniaj przez API GraphQL i otrzymuj podpisany webhook, gdy coś się wydarzy.

Tokeny API

Utwórz token w Panelu sterowania w sekcji Dane i integracje i wybierz, co może odczytywać lub zmieniać. Wyślij go jako token Bearer do punktu końcowego /graphql swojej firmy. Pełny schemat znajdziesz pod adresem /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 } } } }"}'

Zakresy

Token ma zakresy, które wybierzesz. Raporty i ustawienia są tylko do odczytu, a każdy inny obszar ma zakres odczytu i zapisu. Uprawnienia osoby, która utworzyła token, nadal ograniczają to, do czego token sięgnie.

  • 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

Webhooki

Każda dostawa zawiera nagłówek Appointier-Signature ze znacznikiem czasu i HMAC-SHA256 z tego znacznika i surowej treści, wyliczonym przy użyciu sekretu Twojego punktu końcowego. Odrzucaj wszystko, co jest starsze niż pięć minut.

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));
}

Zdarzenia

  • 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

Nieudana dostawa jest ponawiana po 1 minucie, 5 minutach, 30 minutach, 2 godzinach i 12 godzinach. Po 10 kolejnych niepowodzeniach endpoint jest wstrzymywany, a właściciel dostaje e-mail. Każdą dostawę można wysłać ponownie z dziennika.

Pełny eksport

Właściciele mogą zażądać pliku ZIP z każdą tabelą w CSV i JSON Lines, a do tego zdjęciami, podpisanymi formularzami, PDF-ami notatek i manifestem z liczbą wierszy. Link przychodzi e-mailem i działa 24 godziny.

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

Ten sam plik ZIP może trafiać co dzień lub co tydzień do bucketa Amazon S3, magazynu zgodnego z S3 lub hosta SFTP.

Limity zapytań

Każdy token może wysłać 600 żądań na minutę, a każda odpowiedź zawiera nagłówki X-RateLimit-Limit i X-RateLimit-Remaining.