Documentation/Connecting/Your own panel/Examples·7 / 9

Examples

Common tasks of your system and of support — a command or two each. The address and the token are in variables, as on the “Calls” page.

  1. Make a client

    For a month, three devices, with the order number as the external ID. The repeat key is the order's number: a repeated request gets the same answer, not a second client.

    On your server
    curl -s "$VELI/clients" \
      -H "Authorization: Bearer $VELI_TOKEN" \
      -H "content-type: application/json" \
      -H "Idempotency-Key: order-88123:new" \
      -d '{"name": "order-88123", "days": 30, "change": {"devices": 3, "external": "88123", "tags": ["month"], "meta": {"order": "88123"}}}'
  2. Extend by a month

    The term grows from its end, for an expired one from now. With a key a repeated request does not extend twice.

    On your server
    curl -s "$VELI/clients/order-88123" \
      -H "Authorization: Bearer $VELI_TOKEN" \
      -H "content-type: application/json" \
      -H "Idempotency-Key: order-88123:extend" \
      -d '{"change": {"days": 30}}'
  3. The link, the QR code and app buttons

    The link is in link, the page with buttons in page, ready “Add to …” links in apps, what is left in left. A QR code for a chat or a letter — PNG.

    On your server
    curl -s "$VELI/clients/order-88123" \
      -H "Authorization: Bearer $VELI_TOKEN" | jq -r .link
    curl -s "$VELI/clients/order-88123/qr?format=png&size=512" \
      -H "Authorization: Bearer $VELI_TOKEN" -o qr.png
    curl -s "$VELI/clients/order-88123" \
      -H "Authorization: Bearer $VELI_TOKEN" | jq '{page, apps, left}'
  4. Find clients by an external ID

    A person may have several subscriptions — the answer is always a list.

    On your server
    curl -s "$VELI/clients?external=88123" \
      -H "Authorization: Bearer $VELI_TOKEN" | jq -r '.clients[] | "\(.name) \(.status) \(.left.days)"'

Repeats without consequences

Systems send a notice again, people click twice, a server falls between the request and the answer. The Idempotency-Key header on a POST makes a repeat safe.

  • The same key and the same request — the same answer, with no second action, with the Idempotent-Replayed: true header.
  • The same key with another request — 409 idempotency: the key is already spent on something else.
  • The panel remembers a key for a day; each token has its own keys. A key is up to 128 visible characters; handy is the order's number and the action: order-88123:extend.
  • A key is for one action: extending and making have different keys, or the second request would get the first one's answer.
A repeat with the same key
HTTP/1.1 200 OK
idempotent-replayed: true

{"done": 1}