API e 12.al

Krijo linke, lexo statistika dhe shkarko kode QR nga aplikacioni yt. API është REST + JSON, pa cookies, me tokena Bearer.

URL bazë

https://12.al/api/v1

Kufiri i kërkesave

60/min për token · 300/min në Business

Specifikimi

OpenAPI 3.1 (YAML)

1. Merr një token

Hyr në panel dhe hap Cilësimet → Tokenat e API-t (/app/settings/api-tokens).
Jepi një emër dhe zgjidh lejet: links:read, links:write, qr:read, stats:read, pages:read.
Kopjoje menjëherë: token-i shfaqet vetëm një herë. Çdo token punon vetëm në workspace-in ku u krijua.

export TOKEN="12|12al_…"

2. Shembuj me curl

Kontrollo token-in

Kthen përdoruesin, workspace-in, lejet e token-it dhe kufirin e kërkesave.

curl https://12.al/api/v1/me \
  -H "Authorization: Bearer $TOKEN"

Krijo një link

Leja: links:write. Slug-u është opsional; pa të gjenerojmë një 5-shkronjësh.

curl -X POST https://12.al/api/v1/links \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"destination":"https://shembull.al/oferta","slug":"oferta","tags":["fushata"],"utm":{"source":"instagram"}}'

Listo linket

Leja: links:read. Filtra: q (kërkim), tag, archived=1, page, per_page (maks. 100).

curl "https://12.al/api/v1/links?tag=fushata&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Ndrysho destinacionin

Leja: links:write. Dërgo vetëm fushat që ndryshojnë. {"archived": false} e rikthen një link të arkivuar.

curl -X PATCH https://12.al/api/v1/links/42 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"destination":"https://shembull.al/oferta-e-re"}'

Arkivo një link

Leja: links:write. Linku ndalon së ridrejtuari; statistikat ruhen.

curl -X DELETE https://12.al/api/v1/links/42 \
  -H "Authorization: Bearer $TOKEN"

Krijo shumë linke njëherësh

Leja: links:write. Deri 100 linke për kërkesë; përgjigjja ka rezultatin për secilin.

curl -X POST https://12.al/api/v1/links/bulk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"links":[{"destination":"https://a.al"},{"destination":"https://b.al","slug":"b-al"}]}'

Statistikat e 30 ditëve

Leja: stats:read. Totale, seri ditore, vendet, pajisjet dhe burimet kryesore. Mbështet ETag (If-None-Match → 304).

curl "https://12.al/api/v1/links/42/stats?range=30d" \
  -H "Authorization: Bearer $TOKEN"

Shkarko kodin QR

Leja: qr:read. SVG ose PNG (size 64–1024/2048/4096 sipas planit).

curl "https://12.al/api/v1/links/42/qr.png?size=1024" \
  -H "Authorization: Bearer $TOKEN" -o qr.png

Faqet bio dhe domainet

Leja: pages:read për faqet, links:read për domainet.

curl https://12.al/api/v1/pages -H "Authorization: Bearer $TOKEN"
curl https://12.al/api/v1/domains -H "Authorization: Bearer $TOKEN"

3. Gabimet

Çdo gabim ka të njëjtën formë. Mesazhet janë shqip; dërgo Accept-Language: en për anglisht. Fusha code nuk ndryshon kurrë.

{
  "errors": [{
    "status": "422",
    "code": "validation_failed",
    "title": "Të dhënat nuk janë të vlefshme.",
    "detail": "Ky slug është i zënë.",
    "source": { "pointer": "/slug" }
  }]
}

401 unauthenticated: token mungon, është i pavlefshëm, ka skaduar ose nuk je më anëtar i workspace-it.
403 missing_ability: token-it i mungon leja e duhur.
404 not_found: burimi nuk ekziston në këtë workspace.
422 validation_failed: fushat e gabuara, një gabim për çdo fushë.
429 rate_limited: shumë kërkesa; prit sa thotë header-i Retry-After.

4. Referenca e plotë

Të gjitha endpoint-et, fushat dhe përgjigjet, nga specifikimi OpenAPI.