Razvijalci

API za termine na vaši spletni strani

Vgradite javne termine vašega ansambla na katerokoli spletno stran — s preprosto HTTP zahtevo, brez računa in brez ključa API.

Bistveno

•Javno dostopno, avtentikacija ni potrebna.
•CORS je omogočen, končna točka deluje neposredno iz brskalnika.
•Odgovori so predpomnjeni 5 minut, omejitev 60 zahtev na minuto.
•Vrnejo se samo podatki, ki ste jih v nastavitvah spletne strani omogočili za javni prikaz.
•Pri javni uporabi je obvezna omemba 'Powered by Chorilo' s povezavo na našo spletno stran.

Powered by Chorilo — Omemba na vaši strani

Če API uporabljate na javni strani, dodajte vidno omembo 'Powered by Chorilo' s povezavo na https://www.chorilo.com. Diskretna vrstica v nogi več kot zadošča.

Izmenjava je poštena: svoje termine samodejno vključite v druge sisteme in jih ni treba vzdrževati dvakrat. Vsaka zahteva API pa tudi obremeni naše strežnike in povzroča stroške infrastrukture — več obiska kot ima vaša stran, več virov to zahteva na naši strani. V zameno manjša omemba Chorilu prinese nekaj prepoznavnosti, ki nam pomaga doseči nove zbore.

HTML

<a href="https://www.chorilo.com" target="_blank" rel="noopener">
  Powered by Chorilo
</a>

Predogled

Končna točka

Ena sama GET končna točka vrne prihajajoče termine vašega ansambla. Zamenjajte z URL slug-om vaše javne Chorilo spletne strani.

Kje najdem svoj slug?

Odprite nastavitve vaše javne spletne strani v Chorilo zaledju. Slug je edinstveni del URL-ja, na primer 'moj-zbor' v https://chorilo.com/w/moj-zbor.

GET

https://backend.chorilo.com/api/public-websites/{slug}/embed-events

Nadzor vidnosti

API spoštuje nastavitve vidnosti vaše javne spletne strani. Vse, kar je na spletni strani skrito, je tudi prek API-ja blokirano — tudi če se izrecno zahteva.

Glavno stikalo: Če je show_events onemogočen, API vrne prazen seznam.

Tipi terminov: Vračajo se samo omogočeni tipi. Zahteva za blokirane tipe (npr. types[]=concert pri onemogočenem prikazu koncertov) je tiho filtrirana.

Nastavitev	Vpliva na tip
show_events	Glavno stikalo (onemogoči vse)
show_rehearsals	`rehearsal`
show_concerts	`concert`
show_other_events	`event`
show_event_descriptions	Nadzira polje description v odgovoru

Parametri poizvedbe

Vsi parametri so neobvezni. Brez parametrov končna točka vrne naslednje termine glede na privzete nastavitve vaše spletne strani.

Ime	Tip	Privzeto	Opis
limit	integer	5	Število vrnjenih terminov. Minimum 1, maksimum 100.
from	ISO 8601	zdaj	Začetek časovnega obdobja. Pretekli termini privzeto niso vrnjeni.
to	ISO 8601	—	Konec časovnega obdobja.
types[]	array	vsi dovoljeni	En ali več: rehearsal, concert, event. Blokirani tipi so tiho filtrirani.
lang	string (2)	—	Dvočrkovna koda jezika (de, en, fr, nl, es, sv, it, sl). Trenutno vrnjena kot odmev v meta odgovoru.

Omejitev zahtev in predpomnjenje

Končna točka je omejena na 60 zahtev na minuto na IP-naslov. Če je omejitev presežena, strežnik odgovori s HTTP 429.

Odgovori so na strežniški strani predpomnjeni 5 minut (glede na kombinacijo parametrov). Novi termini se lahko zato pojavijo z manjšim zamikom.

Omejitev

60 / min

na IP-naslov

Strežniški predpomnilnik

5 min

na kombinacijo parametrov

Oblika odgovora

Odgovor je JSON objekt. Vsak termin vsebuje samo javna polja — interni opisi, podatki udeležencev ali druge občutljive informacije niso nikoli vrnjene.

events[] — Seznam terminov z id, title, type, location, start_time, end_time, has_ticket_sale, neobvezno ticket_sale_url (če je prodaja vstopnic aktivna) in neobvezno description.
ensemble_name — Prikazno ime vašega ansambla.
theme_color — Šestnajstiška koda barve iz nastavitev spletne strani.
language — Koda jezika vaše spletne strani.

Polje description vsebuje izključno javni opis. Interni opis termina nikoli ni del odgovora.

JSON

{
  "events": [
    {
      "id": 42,
      "title": "Sommerkonzert",
      "type": "concert",
      "location": "Stadthalle Musterstadt",
      "start_time": "2026-06-14T19:30:00+02:00",
      "end_time": "2026-06-14T21:30:00+02:00",
      "description": "Letni poletni koncert na vrtu krajevnega doma.",
      "has_ticket_sale": true,
      "ticket_sale_url": "https://www.chorilo.com/shop/tickets/42"
    }
  ],
  "ensemble_name": "Musterchor",
  "theme_color": "#6366f1",
  "language": "de"
}

Primeri

Kako klicati API iz različnih jezikov. Primer naloži do 10 prihajajočih koncertov in drugih terminov.

curl "https://backend.chorilo.com/api/public-websites/mein-chor/embed-events?limit=10&types[]=concert&types[]=event"

Statusne kode

Koda	Pomen
200	Uspeh, termini v polju events.
404	Spletna stran s tem slug-om ni najdena.
422	Neveljavni parametri poizvedbe (npr. neznan tip ali to pred from).
429	Omejitev presežena, poskusite znova čez minuto.

All public endpoints

These are the read-only public endpoints currently exposed. No authentication required. JSON responses only.

Method	Path	Description	Limit
GET	/api/tickets/events	List public concert events	90/min
GET	/api/tickets/events/{eventId}	Single event detail	90/min
GET	/api/public-websites/{slug}	Public ensemble website by slug	90/min
GET	/api/public-websites/{slug}/embed-events	Embeddable concert calendar	60/min
GET	/api/choir-associations/public	Public association directory	90/min

Rate-limit response headers

Every /api/* response carries rate-limit headers. They are exposed via Access-Control-Expose-Headers for cross-origin agents.

X-RateLimit-Limit — per-window quota
X-RateLimit-Remaining — remaining requests
Retry-After — seconds to wait (HTTP 429 only)

JSON error format (RFC 9457)

All /api/* errors return application/problem+json regardless of Accept header.

{
  "type":     "https://www.chorilo.com/api/errors/not-found",
  "title":    "Resource not found",
  "status":   404,
  "detail":   "...",
  "instance": "/api/tickets/events/99999999"
}

Validation errors (422) include an errors object mapping fields to messages.

Vprašanja?

Za tehnična vprašanja o API-ju pišite na: support@chorilo.com