Front OTP – SMS Gateway API (Produktbeskrivelse)

Dette dokumentet beskriver kun OTP (engangskode) funksjonaliteten i Front SMS Gateway API. Det er en forenklet og målrettet spesifikasjon for sending av engangskoder via SMS ved bruk av forhåndsgodkjente meldingsmaler. Denne funksjonaliteten benytter parameteren «type=otp» samt relaterte OTP-parametere.

1 Oversikt

OTP SMS API benyttes for sending av engangskoder til autentisering, innlogging og verifisering. API-et er HTTP-basert og benytter JSON over HTTPS. OTP SMS API støtter kun sending av OTP-meldinger og tillater ikke fritekst. Meldingsmal og struktur genereres automatisk av gatewayen og kan ikke tilpasses.

2 Endpoint

POST https://www.pling.as/psk/push.php

Kun HTTPS er tillatt.

3 Autentisering

Autentisering skjer ved bruk av serviceid og eventuelt IP-restriksjon eller passord, avhengig av kontokonfigurasjon. Autentiseringsinnstillinger konfigureres i administrasjonspanelet for SMS Gateway.

4 Obligatoriske parametere for OTP

For OTP SMS API benyttes forhåndsdefinerte avsenderverdier som settes opp ved bestilling av tjenesten.

Følgende verdier inngår i meldingen, men sendes ikke som parametere i API-kallet:

fromid – Avsender-ID som vises som meldingens avsender på mottakers telefon

sendername – Navn på virksomhet eller tjeneste som vises i meldingsteksten

Disse verdiene er statiske per konto og kan ikke overstyres i API-kallet.

OTP SMS API støtter kun HTTP POST med JSON.

ParameterBeskrivelseLovlige verdierKommentar
serviceidTjenesteidentifikatorUnik tjenesteidentifikator for autentisering av API-kalletObligatorisk
passwordPassord for gatewayIngen restriksjonerIkke nødvendig når IP-autentisering brukes
phonenoTelefonnummer til mottaker.Internasjonalt telefonnr. med landskode (004799999999 eller +4799999999)Obligatorisk
codeEngangskode / passordAntall tegn 4-15
Tillatte tegn:
A-Z, a-z, 0-9,
! @ # $ % & * – _
Obligatorisk – For best kompatibilitet med automatisk gjenkjenning av engangskoder på Android og iOS anbefales numeriske koder (0–9) på 4–8 tegn.

Lengre eller alfanumeriske koder kan redusere støtte for automatisk utfylling på enkelte enheter.
usernameBrukernavn for innloggingTekst inntil 255 tegn. Kan inneholde valgfri tekst (brukernavn, e-post eller annen identifikator). URL (http:// eller https://) er ikke tillatt.Ikke obligatorisk

Benyttes kun i OTP-meldinger til land som krever forhåndsgodkjent tekstmal. Hvis parameter ikke sendes eller er tom, fjernes tilhørende tekstsegment automatisk fra meldingen
refDeres ID eller referanseDeres meldingsreferanse, maks 100 tegn eller et heltallIkke obligatorisk. Hvis ref er inkludert med meldingen, blir ref og phoneno også sendt som parametere ved leveringsstatus

5 Eksempel på JSON request

Eksempel på HTTP POST med et JSON-dokument:

POST /psk/push.php HTTP/1.1
Host: www.pling.as
Content-Type: application/json

{
  "serviceid": "3",
  "phoneno": "+4799999999",
  "code": "123456",
  "username": "bruker@eksempel.no",
  "ref": "abc"
}

Eksempel melding:

Avsender (fromid): Min Bedrift

Din kode er 123456

Brukernavn: bruker@eksempel.no

Hilsen Min Bedrift

6 Meldingsmal

Standard OTP-mal (genereres automatisk av gateway med statisk avsenderkonfigurasjon):

Din kode er <code> Brukernavn: <username> Hilsen <sendername>

7 Eksempel på respons

{
  "id": 145099,
  "errorcode": 0,
  "description": "OK"
}

8 Feilkoder (OTP-relevante)

Ved utsendelse av melding vil vår gateway returnere en respons på den URL-en du sender. Denne responsen består av et ”errorcode” nummer og et ”ID” referansenummer som er unik for den ene forsendelsen.

ResponsBeskrivelse
errorcode=0OK (Melding sendt)
errorcode=1Ugyldig mobilnummer
errorcode=2Melding sendt fra uautorisert IP-adresse
errorcode=5Ingen resterende SMS meldinger på konto
errorcode=7Kontoen er sperret av Front, eller feil serviceid
errorcode=8serviceid er blank/parameter mangler
errorcode=9phoneno er blank/parameter mangler
errorcode=13Ugyldig passord
errorcode=17Duplikatmelding. Melding med samme phoneno og code sendt innen 120 sekunder.
errorcode=18Mangler kryptering. Bruk https i stedet for http.
errorcode=21Mobilnummer er svartelistet. Nummeret er kjent som ugyldig for mottak av SMS eller er tidligere benyttet i forbindelse med misbruk.
errorcode=25ref kan ikke overskride 100 tegn
errorcode=29code er påkrevd for otp-meldinger og må være 4-15 tegn
errorcode=39username ugyldig

Merk at nye feilkoder kan bli lagt til ved fremtidige versjoner.

9 Leveringsstatus (valgfritt)

Status på sendingen av en melding mot mottaker blir fortløpende postet til den URL som dere ønsker å motta på. Denne tjenesten er ikke obligatorisk, men for de som ønsker dette.

ParameterBeskrivelseLovlige verdierKommentar
statusNy status på SMS-1, 4, 5Se under
origidID ReferansenummerSamme siffer som bekreftelse ID’en når meldingen ble sendtUnikt nummer for hver enkelt tekstmelding
refDeres referansetekst inntil 100 tegnref som ble angitt da meldingen ble sendt
phonenoMobilnummeret meldingen ble sendt tilE164 mobilnummerKun inkludert når ref er inkludert

Eksempel på status: https://kunde.no/dr?status=4&origid=145099

Eksempel på status med ref:

https://kunde.no/dr?status=4&origid=145099&ref=abc&phoneno=%2B4799999999

Status -1:

Meldingen er mottatt av teleoperatøren men ikke levert til mobiltelefon. Denne status kan komme etter status 4 hvis meldingen blir levert umiddelbart.

Status 4:

Meldingen er mottatt hos mottakers mobiltelefon. Man vet ikke om mottaker har lest meldingen, men teleoperatøren har registret selve leveringen.

Status 5:

Meldingen har feilet. I de fleste tilfellene skyldes dette at man har sendt til et mobiltelefonnummer som ikke er i bruk. Det at meldingen feiler kan også komme av driftsfeil hos teleoperatørene.

Hvis det benyttes en annen teleleverandør enn Telenor ved utsendelse indikerer manglende status at meldingen er på vei. Den vanligste årsaken til at man ikke får status med det samme i dette tilfellet, er at mottaker har slått av sin mobiltelefon, eller befinner seg i et område uten dekning. Det hender at man ikke får noen status selv om meldingen faktisk blir levert.

10 SMS-tegnsett og segmentberegning

OTP-meldinger sendes enten som GSM 7-bit eller Unicode (UCS-2), avhengig av hvilke tegn som inngår i meldingen.

GSM (GSM 03.38)

1 SMS: opptil 160 tegn

Flere SMS: 153 tegn per segment

Enkelte utvidede GSM-tegn (f.eks. { } [ ] \ ^ ~ | €) teller som 2 tegn

Unicode (UCS-2)

1 SMS: opptil 70 tegn

Flere SMS: 67 tegn per segment

Benyttes dersom meldingen inneholder tegn utenfor GSM-standarden (for eksempel enkelte spesialtegn eller emoji)

Tegnsett avgjøres automatisk av gatewayen. Kunden kan ikke overstyre dette i OTP SMS API.

Dersom parameteren username inneholder tegn utenfor GSM-standarden, vil meldingen bli sendt som Unicode. Dette reduserer antall tilgjengelige tegn per SMS og kan føre til at meldingen deles opp i flere segmenter.

Segmentberegning håndteres automatisk av gatewayen. Sammensatte meldinger vises som én samlet melding for mottaker, men faktureres per SMS-segment.

11 Sikkerhet og anbefalinger

Det anbefales å implementere rate limiting, IP-begrensning og beskyttelse mot misbruk for OTP-funksjonalitet.

12 Historikk

V1.01 (01.03.2026): Første publiserte versjon.