Organizācijas un darba vietas

Pārskats

qr3.app izmanto divu līmeņu hierarhiju:

Organization (Firma/Agentur)
  └── Workspace 1 (Kunde A)
  └── Workspace 2 (Kunde B)
  └── Workspace 3 (Internes Team)

Organizācija — augstākais līmenis, kas piesaistīts Stripe kontam un plānam
Darba vieta — izolēta vide QR kodiem, skenējumiem un API atslēgām

Organizations API

`GET /v1/organizations`

Atgriež organizāciju, kurai pieder pašreizējā API atslēga.

curl https://qr3.app/v1/organizations \
  -H "Authorization: Bearer qr3_sk_..."

`GET /v1/organizations/usage`

Atgriež organizācijas reāllaika lietojumu pret plāna limitiem — summētu pa visām darba vietām un aprēķinātu reāllaikā: scans kārtējam norēķinu mēnesim (pret max_scans_per_month) un dynamic_codes — aktīvo dinamisko kodu skaits (pret max_dynamic_codes). Sasniedzot limitu, neviens no tiem netiek bloķēts; izmantojiet šo galapunktu (endpoint) lietojuma rādīšanai un paziņojumiem par plāna uzlabošanu.

curl https://qr3.app/v1/organizations/usage \
  -H "Authorization: Bearer qr3_sk_..."

{
  "data": {
    "scans": {
      "used": 4120,
      "limit": 5000,
      "usage_pct": 82,
      "remaining": 880,
      "period": "2026-06",
      "period_start": "2026-06-01T00:00:00.000Z"
    },
    "dynamic_codes": {
      "used": 142,
      "limit": 500,
      "usage_pct": 28,
      "remaining": 358
    }
  }
}

`POST /v1/organizations`

Izveido jaunu organizāciju.

curl -X POST https://qr3.app/v1/organizations \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Digital Heroes GmbH",
    "slug": "digital-heroes",
    "billing_email": "[email protected]"
  }'

Lauki:

Lauks	Tips	Obligāts	Apraksts
`name`	string	✅	Redzamais nosaukums (maks. 255 rakstzīmes)
`slug`	string	✅	URL draudzīgs, unikāls (min. 2, maks. 63 rakstzīmes, tikai `a-z0-9-`)
`billing_email`	string	—	Rēķinu saņemšanas e-pasts

`PATCH /v1/organizations/:id`

Maina organizācijas nosaukumu, rēķinu e-pastu un paziņojumu e-pastu.

Tos var mainīt tikai org_admin vadības paneļa sesijā. Pieprasījumi ar API atslēgu tiek noraidīti ar 403 — arī ar qr3_sk_ un qr3_test_sk_ atslēgām —, tāpēc noplūdusi atslēga nevar novirzīt rēķinu vai paziņojumu adresi.

`DELETE /v1/organizations/:id`

Organizācijas mīkstā dzēšana (soft-delete). Visas saistītās darba vietas un QR kodi tiek saglabāti, taču vairs nav pieejami.

Nepieciešama loma org_admin (vadības paneļa sesija). Pieprasījumi ar parastu API atslēgu tiek noraidīti ar 403 — API atslēgas nekad neiegūst administratora lomu, tāpēc noplūdusi atslēga nevar dzēst organizāciju.

Workspaces API

`GET /v1/workspaces`

Uzskaitīt izsaucējam redzamās darba vietas: org_admin un organizācijas īpašnieks redz visas organizācijas darba vietas, pārējie dalībnieki tikai tās darba vietas, kurām tie pieder, un API atslēga tikai savu darba vietu. Darba vieta, ko izsaucējs neredz, katrā maršrutā /v1/workspaces/:id atbild ar 404 tieši tāpat kā nezināms ID.

curl https://qr3.app/v1/workspaces \
  -H "Authorization: Bearer qr3_sk_..."

`POST /v1/workspaces`

Izveidot jaunu darba vietu.

curl -X POST https://qr3.app/v1/workspaces \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kunde Bäckerei Schmidt",
    "slug": "baeckerei-schmidt",
    "default_locale": "de",
    "primary_color": "#8B4513",
    "approval_required": false
  }'

Ar API atslēgu darba vietu drīkst izveidot tikai atslēga, ko izveidojis org_admin vai organizācijas īpašnieks; jebkura cita atslēga saņem 403 vēl pirms slug pārbaudes (atbilde tātad neatklāj, kuri slug jau ir aizņemti). Atslēgas veidotāja loma tiek pārbaudīta katrā pieprasījumā: ja viņa loma tiek pazemināta, atslēga zaudē šīs tiesības. API atslēga ir piesaistīta savai darba vietai un jauno pēc tam neredz: tās id ir atbildē 201; org_admin to atver vadības panelī un tur var izveidot tai atslēgu. Vadības panelī darba vietas drīkst izveidot tikai org_admin.

Lauki:

Lauks	Tips	Noklusējums	Apraksts
`name`	string	—	Redzamais nosaukums (obligāts)
`slug`	string	—	URL draudzīgs, unikāls katrai organizācijai (obligāts)
`default_locale`	string	`de`	Noklusējuma valoda
`approval_required`	boolean	`false`	Rezervēts plānotajai apstiprināšanas darbplūsmai (nav ieviesta)
`primary_color`	string	—	Zīmola krāsa (`#RRGGBB`)

Plāna limiti:

Plāns	Maks. darba vietas
Free	1
Pro	1
Business	10
Agency	50
Enterprise	500

`PATCH /v1/workspaces/:id`

curl -X PATCH https://qr3.app/v1/workspaces/ws_xyz789 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neuer Name",
    "approval_required": true
  }'

`DELETE /v1/workspaces/:id`

Arhivē darba vietu. Nevar piemērot pašreizējai darba vietai.

Nepieciešama loma org_admin vai arhivējamās darba vietas ws_admin; pārējās lomas saņem 403. Darba vieta, ko izsaucējs neredz, atbild ar 404 — API atslēgai tā ir katra darba vieta, izņemot tās pašas darba vietu, ko tā arī nevar arhivēt.

Audit-Logs

`GET /v1/audit-logs`

Izsekojams visu darba vietas izmaiņu protokols.

curl "https://qr3.app/v1/audit-logs?resource_type=codes&limit=50" \
  -H "Authorization: Bearer qr3_sk_..."

Query parametri:

Parametrs	Tips	Apraksts
`resource_type`	string	Filtrēt pēc resursa: `codes`, `api_keys`, `webhooks`, `workspaces`
`resource_id`	string	Filtrēt pēc konkrēta resursa ID
`action`	string	Filtrēt pēc darbības (piem., `codes.created`)
`cursor`	string	Lapošanas kursors (Pagination cursor)
`limit`	integer	Maks. 100 (noklusējums: 50)

Atbildes piemērs:

{
  "data": [
    {
      "id": "aud_a1b2c3",
      "actor_type": "api",
      "action": "codes.created",
      "resource_type": "codes",
      "resource_id": "qr_xyz123",
      "changes": {},
      "created_at": "2026-03-15T10:00:00.000Z"
    }
  ]
}