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 PayEx. 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:

Kjøpssiden kan sende følgende felt:

Kjøpsformen skal alltid sendes over SSL, slik at ingen kan endre POST-URLen i et man-in-the-middle-angrep.

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:

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:

Feilsiden må gjøre følgende:

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:

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 payex, billig sikkerhetspolicy

Mail: itk@samfundet.no | Telefon: 992 15 925 | Sist endret: 2017-09-28 20:48 | Revisjon: 18 (historie, blame) | Totalt: 1420 kB | Rediger