# bokning.io

> Bokningssystem för salonger, byggt för att en agent ska kunna genomföra en
> bokning från början till slut. Allt som går att göra i gränssnittet går att
> göra över API eller MCP.

## Så kommer du igång

Du behöver en API-nyckel. Salongen skapar den i sin portal under **Integration**
och ger dig den; den avgör vilken salong anropen gäller. Skicka den som
`Authorization: Bearer bk_…`.

Två sätt att koppla upp sig, med samma funktioner bakom:

- **MCP** (rekommenderat för agenter): `https://bokning.io/api/mcp`
  Streamable HTTP, JSON-RPC 2.0, protokollversion 2025-06-18.
  `claude mcp add --transport http bokning https://bokning.io/api/mcp --header "Authorization: Bearer bk_…"`
- **REST**: `https://bokning.io/api/v1` — OpenAPI: `https://bokning.io/api/v1/openapi.json`

## Det du behöver veta innan du bokar

- **Namn räcker.** Tjänster och personal får anges med namn ("Klippning",
  "Alma Berg") i stället för id.
- **En bokning behöver ett anrop.** `book_appointment` tar tjänst, kund och en
  period, och väljer första lediga tid. Du behöver inte hämta tider först.
- **Kunden behöver e-post eller telefon.** Bekräftelsen skickas dit.
- **Tider är ISO 8601.** Salongens lokala tidszon framgår av `get_business`.
  Svaren innehåller både exakt tidpunkt och lokal tid, så du slipper räkna.
- **Priser är i ören.** 65000 betyder 650 kr. Formaterade varianter följer med.
  Kunden betalar i salongen — ingen betalning sker vid bokningen.
- **Dubbelbokning är omöjlig.** Databasen avgör, inte applikationen. Två
  samtidiga försök på samma tid ger den ena `BK409`.

## Felkoder

| Kod | Betyder | Gör så här |
| --- | --- | --- |
| BK400 | Felaktig indata | Läs `hint` — den säger vad som saknas |
| BK401 | Nyckeln saknas eller är ogiltig | Be salongen om en ny |
| BK403 | Nyckeln saknar skrivbehörighet | Be om en nyckel med `write` |
| BK404 | Tjänsten, personen eller bokningen finns inte | `hint` listar vad som finns |
| BK409 | Tiden är upptagen | Hämta nya tider, eller använd `join_waitlist` |
| BK422 | För nära inpå, för långt fram, eller för sent att avboka | Välj en annan tid |

## Verktyg

### get_business
Salongens namn, adress, telefon, tidszon och bokningsregler (hur nära inpå och hur långt fram det går att boka, samt avbokningsgräns). Börja här om du behöver veta vad som gäller.

Behörighet: read. Argument: inga.

### list_services
Alla bokningsbara tjänster med längd och pris i ören. Använd för att översätta vad kunden vill ha till en tjänst som går att boka.

Behörighet: read. Argument: inga.

### list_staff
Personalen och vilka tjänster var och en utför. Filtrera på en tjänst för att se vilka som kan ta den.

Behörighet: read. Argument: service.

### find_slots
Lediga starttider för en tjänst under en period. Varje tid kommer med både exakt tidpunkt (starts_at, ISO 8601) och lokal tid i salongens tidszon. Behöver du bara boka första lediga går det att hoppa över det här steget och gå direkt på book_appointment.

Behörighet: read. Argument: service, staff, from, days, earliest, latest.

### book_appointment
Skapar en bokning. Ange antingen en exakt starts_at, eller en period (from/days) och ett tidsfönster (earliest/latest) så väljs första lediga tid som passar. Databasen avgör om tiden är ledig, så två samtidiga bokningar kan aldrig ta samma tid. Svaret innehåller bokningsreferens och en länk där kunden kan se eller avboka. Kunden betalar i salongen — ingen betalning sker vid bokningen.

Behörighet: write. Argument: service, customer, starts_at, staff, from, days, earliest, latest, notes.

### get_booking
Slår upp en bokning på dess referens, t.ex. "894EAD75".

Behörighet: read. Argument: reference.

### cancel_booking
Avbokar och meddelar kunden. Tiden blir ledig igen direkt. Går att köra om — en redan avbokad tid ger inget nytt utskick.

Behörighet: write. Argument: reference.

### reschedule_booking
Flyttar en befintlig bokning till en ny tid hos samma frisör och meddelar kunden. Den nya tiden måste vara ledig enligt schemat.

Behörighet: write. Argument: reference, starts_at.

### list_bookings
Salongens bokningar i en period. Använd för överblick, avstämning och rapporter.

Behörighet: read. Argument: from, to, status, limit.

### join_waitlist
När ingen tid passar: bevaka en period. Kunden får ett meddelande så fort någon avbokar. Tiden reserveras inte — meddelandet innehåller en länk rakt in i bokningen.

Behörighet: write. Argument: service, customer, from, to, staff, earliest, latest.

## Ett typiskt förlopp

1. `list_services` — översätt kundens önskemål till en tjänst.
2. `book_appointment` med tjänst, kund och period. Klart.
3. Får du `BK409` finns ingen tid som passar: `find_slots` för att visa
   alternativ, eller `join_waitlist` för att bevaka perioden.