Kehittäjät

Rajapinta (API)

Pyöräliikkeet ja integraatiokumppanit voivat rekisteröidä myymänsä pyörät suoraan Pyöräpassiin, kassajärjestelmästä tai verkkokaupasta. Rekisteröity pyörä saa liikkeen varmentaman L2-luottamustason ja ostaja voi lunastaa passin itselleen.

Kaksi tapaa integroida

Helpoin

WooCommerce-lisäosa

Valmis lisäosa hoitaa rekisteröinnin ilman omaa koodia. Asenna, liitä API-avain ja testaa yhteys. MyCashflow-liitännäinen on tulossa. Katso miten lisäosa toimii.

Lataa lisäosa (.zip)

Räätälöity

REST API

Kutsu rajapintaa suoraan omasta järjestelmästäsi (muut verkkokauppa-alustat, oma kassa tai taustajärjestelmä). Yksi POST-kutsu per rekisteröitävä pyörä.

API-avaimen hankkiminen

Lunasta liikkeesi hakemistosta (vahvistus tapahtuu heti, jos kirjautumissähköpostisi verkkotunnus vastaa liikkeen verkkotunnusta).
Avaa liikkeen hallinta ja luo API-avain. Säilytä avain turvassa, se antaa oikeuden rekisteröidä passeja liikkeesi nimissä.

Perusteet

Base URL: https://pyorapassi.fi/api/v1/passi
Todennus: Header X-API-Key: <avaimesi>
Sisältötyyppi: application/json
Kutsuraja: 300 pyyntöä / tunti / liike (avaimet jakavat saman rajan)

Testaa yhteys

GET /api/v1/passi/me

Vahvistaa avaimen ja palauttaa liikkeen, jolle se kuuluu. Kätevä integraation “Testaa yhteys” -toimintoon.

curl https://pyorapassi.fi/api/v1/passi/me \
  -H "X-API-Key: <avaimesi>"

# 200 OK
{ "ok": true, "shop_id": "…", "shop_name": "Liikkeesi nimi" }

Rekisteröi pyörä

POST /api/v1/passi/register

Luo pyörälle L2-tason (liikkeen varmentama) Pyöräpassi. Jos annat customer_email-kentän, ostaja saa sähköpostitse kutsun lunastaa passin.

Body-parametrit

Kenttä	Tyyppi	Kuvaus
`frame_number`	string, pakollinen	Pyörän runkonumero. Yksilöi pyörän rekisterissä.
`brand`	string	Merkki, esim. "Helkama".
`model`	string	Malli, esim. "Jopo".
`model_year`	number \| string	Vuosimalli, esim. 2022.
`warranty_months`	number	Takuu kuukausina (1–120). Näkyy passissa ostotodistuksena ja tuottaa takuumuistutuksen.
`sold_at`	string	Myyntipäivä YYYY-MM-DD (valinnainen; oletus rekisteröintipäivä).
`color`	string	Väri.
`bike_type`	string	Tyyppi, esim. "citybike", "gravel".
`customer_email`	string	Ostajan sähköposti. Jos annettu, ostaja saa kutsun lunastaa passin itselleen.

curl -X POST https://pyorapassi.fi/api/v1/passi/register \
  -H "X-API-Key: <avaimesi>" \
  -H "Content-Type: application/json" \
  -d '{
    "frame_number": "WBK123456789",
    "brand": "Helkama",
    "model": "Jopo",
    "model_year": 2022,
    "customer_email": "ostaja@example.com"
  }'

# 201 Created
{
  "ok": true,
  "passport_id": "…",
  "frame_number": "WBK123456789",
  "claim_url": "https://pyöräpassi.fi/vastaanota/…",
  "verification_level": "shop"
}

Virhetilanteet

HTTP	error	Selitys
400	`Invalid JSON / frame_number is required`	Runko puuttuu tai body ei ole kelvollista JSONia.
401	`Invalid or missing X-API-Key`	Avain puuttuu tai on virheellinen.
409	`already_owned / other_shop`	Runkonumerolla on jo omistaja tai sen on rekisteröinyt toinen liike.
429	`Rate limit exceeded`	Yli 300 pyyntöä tunnissa samalta liikkeeltä.
500	`(server error)`	Palvelinvirhe. Yritä myöhemmin uudelleen.

Rajapinta on versiossa v1 ja palvelu on pilottivaiheessa. Kysymykset ja integraatioyhteistyö: apua@pyorapassi.fi.