Billig frontend-API

MERK: Før du skal jobbe på en frontend (ny eller gammel), sett deg inn i Billig sikkerhetspolicy og relaterte dokumenter. Denne skal følges under utvikling såvel som i produksjon.

Generelt overblikk over kjøpsprosessen finnes på Billig Stripe. Dokumentasjon over databasen (som en frontend generelt har lesetilgang til) finnes på Billig database. De tekniske detaljene for selve kjøpsprosessen i nettbutikk finnes på denne siden. For utvikling mot frontend må man være kjent med og sette seg inn i kravene fra innløser.

Kjøpsform

Kjøpssiden (siste side brukeren ser i frontenden før kjøp) skal POSTes mot https://billettsalg.samfundet.no/pay, og inneholder følgende felter:

price_NNNN_count: Antall billetter som skal kjøpes fra prisgruppe NNNN (0-9).
membercard: Kortnummer billetten skal legges på. (Man kan også bruke cardnumber, men dette anbefales ikke, da nettlesere kan feiltolke dette som et sted å fylle inn kredittkort.)
email: Epostadressen billetten skal legges på. (Maksimalt én av membercard og email skal være satt for en gyldig ordre.)

Kjøpssiden kan sende følgende felt:

seat_NNNN_III: Valgt sete i billettgruppe, checkbox. Det må sendes med seat_NNNN_III for alle billetter i price_group med ticket_group med is_theater_ticket_group satt til true.
wheelchair-total: Antallet billetter i kjøpet som er til rullestolbrukere.

/pay vil gjøre all nødvendig inputvalidering, reservere billetter, sende folk videre osv. Neste gang frontenden ser brukeren, er det på én av to sider; OK-siden eller feilsiden.

Merk at det kan ta litt tid for nettleseren å koble til https://billettsalg.samfundet.no/ (SSL-tilkoblinger tar merkbart mer tid enn ikke-SSL-tilkoblinger). www.samfundet.no gjør dette ved å vise et ikon hentet fra billettsalg-siden seint i bestillingsprosessen (rett etter at kortnummeret er vist inn), slik at nettleseren allerede har tilkoblingen oppe idet formen POSTes.

OK-side

OK-siden vises idet kjøpet er fullført, og billettene sendt på epost. URLen vil være på typen https://www.samfundet.no/arrangement/billetter/status/XXX,YYY.

XXX og YYY er billettnummer (med HMAC), minst ett men potensielt veldig mange. Disse kan brukes til å konstruere en link til en PDF der brukeren kan laste ned billettene sine om han/hun ikke ønsker å vente på eposten. URLen vil være http://billig.samfundet.no/pdf?ticket0=XXX&ticket1=YYY osv.

Feilside

Feilsiden er litt mer komplisert å implementere rett, primært fordi man har ganske mye informasjon som skal sendes videre uten å lage XSS-hull. URLen klienten kommer til vil være på formen https://www.samfundet.no/arrangement/billetter/handlekurv?bsession=XYZ.

XYZ er en sesjons-ID som slås opp i tabellen payment_error. De aktuelle feltene her er:

error: Sesjons-IDen (så du kan spørre med en WHERE).
owner_cardno: Brukerens kortnummer (kan være NULL).
owner_email: Brukerens epostadresse (kan være NULL).
message: Feilmeldingen, ikke HTML-enkodet.

Dessuten finnes det en tabell payment_error_price_group, som i en del tilfeller beskriver innholdet av brukerens handlekurv. Felter her er, for hver prisgruppe som ligger i handlekurven:

error: Sesjons-IDen.
price_group: Prisgruppenummer.
number_of_tickets: Antall billetter for denne prisgruppen (0-9).

Feilsiden må gjøre følgende:

Om raden ikke finnes i payment_error, gikk noe veldig feil under kjøpsprosessen mht. databasen. Vis i så fall en generisk feilmelding.
Om payment_error_price_group er tom, ikke vis noen handlekurv eller kjøpsform, bare feilmeldingen. (Dette vil typisk skje i tilfeller hvor det ikke er ment at brukeren skal prøve på nytt, for eksempel at noe gikk feil i den aller siste fasen men billettene er sendt per epost likevel.)
Om payment_error_price_group har minst én rad, fyll inn handlekurven med informasjon fra disse radene, fyll ut kortnummer- og epostfeltene om de finnes (kortnummer vil ikke bli lagret i databasen, så de feltene må stå på default), og vis feilmeldingen over handlekurven. På den måten får brukeren beskjed om hva som er feil, og umiddelbar mulighet til å fikse problemene.

I en del tilfeller vil parametrene være noe justert i forhold til det brukeren skrev inn; dette er ikke noe frontenden trenger å tenke på.

JavaScript-kapabel feilside

I perioder med mye last kan det å generere feilsiden på serveren være en kilde til last, og det kan være ønskelig å heller bruke en statisk side som kan caches. Billig har en mekanisme for dette som frontenden kan gjøre opt-in på for klienter som støtter JavaScript; da vil i stedet de aktuelle parametrene sendes som en kryptografisk signert streng i hash-delen av URLen. (Merk at man også må støtte APIet i forrige seksjon, spesielt siden dette ikke brukes for feil-URLer i epost.)

For å bruke JavaScript-APIet, inkludér https://billettsalg.samfundet.no/formscript med <script>. Det vil automatisk markere formen (den antar at den første formen på siden er den riktige) som JavaScript-kapabel, slik at backenden vet den kan bruke denne feilmekanismen. Om backenden rapporterer en feil, vil den sende brukeren tilbake til samme URL, men med en lang base64-streng etter #. Da vil samme JavaScript dekode base64-strengen, verifisere at signaturen er korrekt (slik at mekanismen ikke kan brukes til XSS) og fylle inn formen.

Det må være et sted å legge feilmeldingen; dette skal være en tom <div> med id="dynamic-error" og være skjult per default, altså style="display: none".

I noen situasjoner vil det ikke være aktuelt for brukeren å sende inn siden på nytt (se forrige underseksjon). I slike tilfeller vil scriptet gjøre følgende:

Teksten inni første <h1> vil bli byttet ut med «Feil».
Første <h2> vil bli skjult.
Alle elementer med klassen «hidden-if-error» vil bli skjult. Kjøpsformen o.l. burde wrappes i en <div> med en slik deklarasjon.
Alle elementer med klassen «shown-if-error» vil bli vist.

JavaScript-kapabel billettside

Som med feilsiden, kan det være gunstig å generere billettside (den som kommer etter et ferdig kjøp) fra JavaScript. Imidlertid er det litt mer formatering som skal til for å generere en korrekt billettside, så det kan ikke gjøres like helautomatisk.

Om du har aktivert JavaScript for feilsiden, vil du også automatisk få det for billettsiden (du kan ikke velge å bruke kun den ene). I stedet for å få en liste med billettnummer på slutten av URLen (f.eks. /1234500000,1234600000/) vil du få en liste med events med «e» foran, f.eks. /e1234,e1235/. Hvis så er tilfelle, må du inkludere https://billettsalg.samfundet.no/formscript med <script>, altså samme URL som forrige gang (den finner automatisk ut fra parameteret hva slags resultat den har fått). Denne vil dekode billettlisten den får fra backenden (ikke prøv å dekode den selv, da formatet kan endre seg uten forvarsel!) og så kalle JavaScript-funksjonen ticket_callback(), som du må ha definert før <script>-taggen. Denne får ett parameter, et JavaScript-objekt som i JSON-format vil se slik ut:

{
  "tickets": [
    {
      "ticketno": "98434300000",
      "price_group": 1234,
      "on_card": true
    },
    {
      "ticketno": "98434400000",
      "price_group": 1234,
      "on_card": false
    }
  ],
  "price_groups": {
    1234: {
      "name": "Medlem",
      "event": 555,
      "price": 200
    }
  },
  "events": { 
    555: {
      "name": "Kosearrangement",
      "timestamp": 1505750400
    }
  }
}

Merk at billetter enkodes som strenger (de kan være større enn Number), mens prisgrupper og arrangementer enkodes som tall. Pris er i hele norske kroner, og timestamps er i UTC (så eksempeldatoen er 2017-09-18 18:00:00 UTC+0200). Du er alltid garantert at prisgrupper og events som det refereres til er tilgjengelig, og at det er minst én billett, men du kan få flere felter enn det som er listet i eksempelet. Ingen tekst er HTML-escapet, så det må du sørge for å gjøre selv.

Lenker: Start, billig, billig stripe, billig generelt, billig payex, billig sikkerhetspolicy, billig stripe, billig swedbank pay