Organizacije in delovni prostori

Pregled

qr3.app uporablja dvonivojsko hierarhijo:

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

Organizacija — najvišja raven, povezana z računom Stripe in naročniškim paketom
Delovni prostor (Workspace) — izolirano območje za kode QR, skeniranja in ključe API

API za organizacije

`GET /v1/organizations`

Vrne organizacijo, ki ji pripada trenutni ključ API.

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

`GET /v1/organizations/usage`

Vrne trenutno porabo organizacije glede na omejitve paketa — sešteto za vse delovne prostore in izračunano v živo: scans za trenutni obračunski mesec (glede na max_scans_per_month) in dynamic_codes, število aktivnih dinamičnih kod (glede na max_dynamic_codes). Nobena od teh vrednosti ob dosegu omejitve ni blokirana; to končno točko (endpoint) uporabite za prikaz porabe in obvestila o nadgradnji.

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`

Ustvari novo organizacijo.

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]"
  }'

Polja:

Polje	Tip	Obvezno	Opis
`name`	string	✅	Prikazno ime (največ 255 znakov)
`slug`	string	✅	URL-ju prijazno, edinstveno (najmanj 2, največ 63 znakov, samo `a-z0-9-`)
`billing_email`	string	—	E-pošta za izstavitev računov

`PATCH /v1/organizations/:id`

Spremeni ime, e-poštni naslov za račune in e-poštni naslov za obvestila organizacije.

Spremeni jih lahko le org_admin v seji Nadzorne plošče. Zahteve s ključem API so zavrnjene s 403 — tudi s ključi qr3_sk_ in qr3_test_sk_ —, zato razkrit ključ ne more preusmeriti naslova za račune ali obvestila.

`DELETE /v1/organizations/:id`

Mehki izbris (soft-delete) organizacije. Vsi pripadajoči delovni prostori in kode QR se ohranijo, vendar niso več dostopni.

Zahteva vlogo org_admin (seja Nadzorne plošče). Zahteve z le navadnim ključem API so zavrnjene s 403 — ključi API nikoli ne pridobijo skrbniške vloge, zato razkrit ključ ne more izbrisati organizacije.

API za delovne prostore

`GET /v1/workspaces`

Seznam delovnih prostorov, ki jih klicatelj vidi: org_admin in lastnik organizacije vidita vse delovne prostore organizacije, drugi člani le delovne prostore, ki jim pripadajo, ključ API pa le svoj delovni prostor. Delovni prostor, ki ga klicatelj ne vidi, na vsaki poti /v1/workspaces/:id odgovori s 404, natanko tako kot neznan ID.

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

`POST /v1/workspaces`

Ustvari nov delovni prostor.

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
  }'

Z API ključem lahko delovni prostor ustvari le ključ, ki ga je ustvaril org_admin ali lastnik organizacije; vsak drug ključ prejme 403, še preden se preveri slug (odgovor torej ne razkrije, kateri slugi so zasedeni). Vloga osebe, ki je ustvarila ključ, se preveri pri vsaki zahtevi: če ji vlogo znižajo, njen ključ izgubi to pravico. Ključ API je vezan na svoj delovni prostor in novega pozneje ne vidi: njegov id je v odgovoru 201; org_admin ga odpre v Nadzorni plošči in tam zanj lahko ustvari ključ. V Nadzorni plošči lahko delovne prostore ustvarja le org_admin.

Polja:

Polje	Tip	Privzeto	Opis
`name`	string	—	Prikazno ime (obvezno)
`slug`	string	—	URL-ju prijazno, edinstveno znotraj organizacije (obvezno)
`default_locale`	string	`de`	Privzeti jezik
`approval_required`	boolean	`false`	Rezervirano za načrtovani potek dela za odobritev (ni implementiran)
`primary_color`	string	—	Primarna barva blagovne znamke (`#RRGGBB`)

Omejitve paketov:

Paket	Največ delovnih prostorov
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`

Arhivira delovni prostor. Ni mogoče uporabiti za lasten delovni prostor.

Zahteva org_admin ali ws_admin delovnega prostora, ki ga želite arhivirati; druge vloge prejmejo 403. Delovni prostor, ki ga klicatelj ne vidi, odgovori s 404 — za ključ API je to vsak delovni prostor razen njegovega lastnega, ki ga prav tako ne more arhivirati.

Revizijski dnevniki

`GET /v1/audit-logs`

Sledljiv dnevnik vseh sprememb v delovnem prostoru.

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

Parametri poizvedbe:

Parameter	Tip	Opis
`resource_type`	string	Filtriranje po viru: `codes`, `api_keys`, `webhooks`, `workspaces`
`resource_id`	string	Filtriranje po določeni ID-številki vira
`action`	string	Filtriranje po dejanju (npr. `codes.created`)
`cursor`	string	Kazalec za paginacijo (Pagination-Cursor)
`limit`	integer	Največ 100 (privzeto: 50)

Primer odgovora:

{
  "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"
    }
  ]
}