API un webhook dokumentācija

Pēdējās izmaiņas2026. gada 4. augustā

Pārskats

Staaro publiskais integrācijas punkts ir ienākošais webhook aktivizētājs. Jūsu serveris, Zapier, Make vai WooCommerce pēc klienta notikuma nosūta vienu parakstītu HTTP POST; Staaro to pārbauda un ievieto rindā vienu atsauksmes SMS. JSON atslēgas, galvenes, statusi un CSV lauki vienmēr paliek valodneitrāli.

POST https://api.staaro.ee/api/v1/triggers/webhook/YOUR_WEBHOOK_TOKEN

Ātrais sākums

  1. Staaro atveriet /integrations/webhook.
  2. Nokopējiet webhook URL un izveidojiet parakstīšanas noslēpumu.
  3. Izveidojiet JSON saturu, parakstiet precīzus neapstrādātos baitus un nosūtiet pieprasījumu.
BODY='{"phone":"+37120000000","customer_name":"Anna","external_id":"order-1042"}'
SIGNATURE=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$STAARO_SECRET" -hex | sed 's/^.* //')
curl -X POST 'https://api.staaro.ee/api/v1/triggers/webhook/YOUR_WEBHOOK_TOKEN' \
  -H 'Content-Type: application/json' \
  -H "X-Staaro-Signature: $SIGNATURE" \
  --data-binary "$BODY"

Autentifikācija

Standarta Staaro saturam aprēķiniet HMAC-SHA256 no precīza neapstrādāta pieprasījuma satura ar webhook noslēpumu un nosūtiet heksadecimālo rezultātu galvenē X-Staaro-Signature. Neparakstiet parsētu vai atkārtoti serializētu JSON. Tiek pieņemts arī WooCommerce base64 HMAC-SHA256 galvenē X-WC-Webhook-Signature.

Standarta pieprasījuma saturs

{
  "phone": "+37120000000",
  "customer_name": "Anna",
  "external_id": "order-1042",
  "scheduled_send_at": "2026-08-05T10:00:00Z",
  "language": "lv",
  "template_vars": {"location": "Rīga"}
}
  • phone — obligāts sūtīšanai; tiek normalizēts uz E.164.
  • customer_name — izvēles metadati.
  • external_id — ļoti ieteicams stabils notikuma ID idempotencei.
  • scheduled_send_at — izvēles ISO 8601 laiks.
  • language un template_vars — metadati. Faktiskā klienta valoda ir uzņēmuma saglabātā ziņojumu valoda, kas tiek fiksēta rindas izveides brīdī.

Atbildes

Rindā ievietots pieprasījums atgriež 202 Accepted. Paredzami biznesa iznākumi atgriež 200 ar skipped iemeslu, piemēram, no_phone, opted_out, quota_exhausted, suspended vai plan_requires_staaro. 401 nozīmē nederīgu parakstu, 404 — nezināmu tokenu, 400 — nederīgu saturu un 429 — pārsniegtu ātruma limitu.

Idempotence

Staaro sasaista external_id ar jūsu webhook tokenu; atkārtota vērtība neizveido otru SMS. Bez tās tiek jaukts neapstrādātais saturs, tāpēc pat atstarpju izmaiņas var radīt jaunu notikumu. WooCommerce izmanto pasūtījuma ID un nosūta ne vairāk kā vienu reizi katram pasūtījumam.

Python piemērs

import hashlib, hmac, json, requests

body = json.dumps({"phone": "+37120000000", "external_id": "order-1042"}, separators=(",", ":")).encode()
signature = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
response = requests.post(URL, data=body, headers={"Content-Type": "application/json", "X-Staaro-Signature": signature})
response.raise_for_status()

Limiti un drošība

  • 60 pieprasījumi minūtē vienam uzņēmumam.
  • Glabājiet tokenu un noslēpumu tikai servera pusē; neievietojiet tos pārlūka vai mobilās lietotnes kodā.
  • Parakstiet precīzus nosūtītos baitus un noplūdes gadījumā nekavējoties mainiet noslēpumu.
  • Atkārtojumiem izmantojiet to pašu external_id un eksponenciālu aizkavi.

Atbalsts: staaro.eu@gmail.com.

PĒDĒJĀS IZMAIŅAS · 04.08.2026. · Staaro OÜ · 17561530