Ett API. Ingen skjult overflate.

Poeng regnes ut hos oss, aldri i kassa

Kassa og nettbutikken sender det som skjedde — ordrer, returer, hvordan det ble betalt — og FriendsOf regner ut poengene etter butikkens egne regler, kampanjer og nivåer. Reglene endres uten at noe system må oppdateres.

En ordre uten medlem sendes likevel med e-post eller mobilnummer. Blir kunden medlem med det samme innen programmets frist (30 dager som standard, guest_earn_window_days), får hen poengene for ordren. Ingen trenger å logge inn eller være medlem før de handler.

Står programmet på pause, gir kjøp og handlinger fra den tiden aldri poeng, heller ikke etter at det er slått på igjen. Rapporteres en handling senere med et occurred_at inne i en pause, svarer API-et 409 program_paused.

Under alt ligger et sikkerhetsnett, i kroner og slått på som standard: et tak på saldo, en grense for én opptjening, en grense for bruk per dag og en høyeste kampanjemultiplikator. Poeng over en grense venter på at et menneske godkjenner dem (GET /api/v1/points/reviews, hver med hvilken grense som holdt dem og hva den var da, limit), og betaling over dagsgrensen avvises med daily_redemption_limit og hvor mye som er igjen i dag.

I kassekontrakten (provider-dokumentet) kan en retur av noe som ble betalt med poeng sendes i kroner, slik kassa kjenner den (amount på refusjonen, med den opprinnelige reservation_ref). FriendsOf regner om med det poengene var verdt da de ble brukt, og runder ned, så en retur gir aldri tilbake flere poeng enn kunden betalte med — heller ikke om butikken har endret poengverdien siden. Beløpet på en reservasjon vises alltid med den verdien den ble laget med.

Medlemslisten kan sorteres etter saldo, flest poeng først (sort: "POINTS" i profilsøket).

POST /api/v1/points/quote

{
  "member": { "email": "kari@example.no" },
  "lines": [
    { "line_ref": "1", "sku": "SANDNES-TYNN-MERINO", "line_total": "329.00" },
    { "line_ref": "2", "sku": "PINNE-4MM", "line_total": "166.00" }
  ]
}

→ { "points": 495, "value": "49.50", "available_after": 1450,
    "available_after_value": "145.00", "lines": [ … ] }

Anslaget bruker nøyaktig den samme beregningen som den ekte opptjeningen, og skriver ingenting. Alle kronebeløp kommer ferdig regnet ut: ingen integrasjon skal gange med en poengverdi selv. Et medlemsoppslag (GET /api/v1/points/members/lookup) gir saldoen i poeng og kroner, og betaling med poeng er to steg — hold av, trekk når salget er ferdig — med retur og tilbakebetaling på den samme reservasjonen.

For regnskapet: GET /api/v1/points/liability er hva kontoen skylder i poeng og kroner, hva som utløper snart og hva som har løpt ut i år, med månedstall som fryses den 1. GET /api/v1/points/balances er det samme per medlem, med totalen på hver side.

Flaten Flow Retail-kassen kaller midt i et salg

Medlemsoppslag, saldo i poeng og kroner, anslaget kvitteringen skriver ut, og betaling med poeng: reservasjon, gjennomføring og tilbakeføring. Innmelding fra kassa og kupongbruk er beskrevet i kontrakten, men ikke bygget ennå.

Den er skrevet mot hvordan Flow Retail Core faktisk ser ut innvendig, ikke gjettet fra en spesifikasjon. Vår halvdel kjører; selve kassestøtten bygges på den andre siden, og vi setter ingen dato på en annens veikart. Selve poengene tjenes fra ordren slik den kommer til oss, aldri fra kassa, så en utskrift venter aldri på en skriving.

POST /api/v1/tenants/{tenantUid}/provider/members/{memberId}/points/reserve
Idempotency-Key: sale-8842-terminal-3

{
  "reservation_ref": "sale-8842-terminal-3",
  "amount": "50.00"
}

Kassa sier hvor mye som skal betales med poeng; svaret sier nøyaktig hva som ble holdt av og hva det er verdt i kroner, som desimalstreng, fordi det er vi som eier poengverdien og kassa som skal poste oppgjørslinja. reservation_ref er reservasjonens egen identitet: den samme referansen gir alltid den samme reservasjonen tilbake, også etter en tidsavbrutt omstart, så et nytt forsøk kan aldri bli et nytt hold på saldoen.

Nøkkelen bestemmer kontoen, ikke stien: en nøkkel som peker på en annen kontos Flow Retail-tenant får 403 TENANT_MISMATCH og leser ingenting.