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
Epost: itk@samfundet.no | Telefon: 992 15 925 | Sist endret: 2024-10-07 12:31 | Revisjon: 24 (historie, blame) | Totalt: 1904 kB | Rediger