API dokumentasjon

[

English version of API documentation ]

For å benytte vårt API må din konto være aktivert for dette. På Produkter-siden kan man se om kontoen har API aktivert. Bestill tilgang til API direkte eller kontakt oss dersom du ønsker å aktivere API.

Send SMS - HTTP GET/POST

Eksempel på utsendelse av SMS (get):

https://sveve.no/SMS/SendMessage?user=xxx&passwd=xxx&to=xxx&msg=Meldingstekst&f=json

Parameter	Type	Maks lengde	Obligatorisk	Default	Beskrivelse
user	String		true		Brukernavn
passwd	String		true		API passord. Dette finner du på siden API -> API-nøkkel
to	String		true		Mottakers mobilnummer (kommaseparert ved flere), og/eller navn på eksisterende mottakergruppe
msg	String	1071	true		Selve meldingsteksten. Det forutsettes at teksten er UTF-8 encoded.
from	String	11	false	27333	Avsender som vises på mottakers telefon (f.eks. firmanavn eller ditt eget mobilnummer). ÆØÅ kan ikke benyttes. Minimum 3 tegn anbefales for korrekt visning på alle mobiltelefoner. NB: fra 1.1.2025 medfører mobilnummer-avsendere ekstra kostnad.
reply	Boolean		false	false	Meldingen kan besvares. Ved aktivering (true) blir avsender et nummer med 14 siffer.
reply_id	Integer		false		ID på tidligere sendt melding (sendt med reply=true). Fører til at meldingene kommer i samme meldingstråd på mottakers telefon ved bruk av reply=true.
date_time	String	12	false		Dato/klokkeslett for planlagt utsendelse. Format: yyyyMMddttmm. Eksempel: 202310061315 (6. okt. 2023 kl. 13:15). NB! maks 5000 tegn som "to"-verdi støttes ved planlagt utsendelse
reoccurrence	String		false		Gjentakelse av utsendelse av samme melding (sendt med date_time). Format: verdi\|enhet Verdier: 11=time, 5=dag, 99=uke, 2=måned Eks 1: 6\|11 (hver 6. time) Eks 2: 14\|5 (hver 14. dag)
reoccurrence_ends	String		false	never	Gyldige verdier: never, after, on never=gjentakelse stopper aldri after=gjentakelse stopper etter et antall ganger on=gjentakelse stopper etter en dato
ends_after	Integer		false		Brukes dersom reoccurrence_ends=after. Gjentakelse stopper etter angitt antall ganger.
ends_on	String		false		Brukes dersom reoccurrence_ends=on. Gjentakelse stopper etter angitt dato (format: dd.MM.yyyy), eks: 31.12.2024
ref	String	36	false		Din egen referanse. Vil bli sendt tilbake i leveringsrapport.
f	String		false	xml	Returformat, gyldige verdier: json, xml
test	Boolean		false	false	Sett denne til 'true' for å gjøre test-kall som ikke medfører utsendelse av SMS. Test-kall vil ikke trigge leveringsrapport.

Vi støtter både HTTP GET og POST for å sende SMS. Maksimal størrelse på en GET request er 6900 tegn, som tilsvarer ca 700 enkeltmottakere. Vi anbefaler uansett å bruke POST dersom man skal sende til mange enkeltmottakere i samme request.

Ved bruk av POST finnes det 3 alternativer:

1. Body JSON

Tre varianter støttes. Eksemplene viser kun noen av parameterne. Alle parameterne i tabellen over støttes.

Variant 1 (én meldingstekst, en eller flere mottakere):

{
  "user": "brukernavn",
  "passwd": "api-passord",
  "to": "mobilnummer1, mobilnummer2, ..",
  "msg": "Meldingstekst",
  "from": "MinBedrift",
  "f": "json",
  "test": false
}

Variant 2 (én meldingstekst, en eller flere mottakere):

{
  "request": {
    "user": "brukernavn",
    "passwd": "api-passord",
    "to": "mobilnummer1, mobilnummer2, ..",
    "msg": "Meldingstekst",
    "from": "MinBedrift",
    "f": "json",
    "test": false
  }
}

Variant 3 (ulike meldingstekster i samme kall):

{
  "user": "brukernavn",
  "passwd": "api-passord",
  "f": "json",
  "test": false,
  "messages": [
    {
      "to": "mobilnummer1",
      "msg": "Meldingstekst 1",
      "from": "MinBedrift"
    },
    {
      "to": "mobilnummer2",
      "msg": "Meldingstekst 2",
      "from": "MinBedrift"
    }
  ]
}

2. Body parameter

Parametere sendes som form-data.

3. URL parameter

Samme som GET, men POST som metode. Parameterne sendes i URL og ikke i request body.

NB! sett ContentType=UTF-8 i POST-kallene.

Du kan laste ned Postman-maler for alle alternativene.

Retur ved SMS-kall

For hvert kall som gjøres blir det returnert informasjon om utsendelsen. Dette gjelder både for GET og POST. Vi anbefaler å benytte JSON som returformat (f=json) i kallene.

Vellykket utsendelse (2 meldinger sendt):

{
  "response": {
    "msgOkCount": 2,
    "stdSMSCount": 4,
    "ids": [
      42824111,
      42824112
    ]
  }
}

Utsendelsen feilet delvis (1 melding ble sendt og 2 ble avvist):

{
  "response": {
    "msgOkCount": 1,
    "stdSMSCount": 1,
    "errors": [
      {
        "number": "1792873691",
        "message": "Brukeren har ikke tilgang til å sende meldinger til dette landet"
      },
      {
        "number": "63987654",
        "message": "Telefonnummeret er ikke et mobilnummer"
      }
    ],
    "ids": [
      42824387,
      0,
      0
    ]
  }
}

Response-objekt

Key	Type	Beskrivelse
msgOkCount	Integer	Antall meldinger som ble sendt
stdSMSCount	Integer	Antall SMS-enheter totalt for utsendelsen. En SMS enhet består av inntil 160 tegn.
fatalError	String	Beskrivelse av feil dersom hele utsendelsen feilet
errors	Array	Beskrivelse av feil dersom utsendelse til enkeltnummer feilet
ids	Array	ID'er på enkeltmeldingene som ble sendt. Rekkefølge samsvarer med rekkefølgen av mobilnummer i utsendelsen

Tegnsett og antall tegn pr. melding

Følgende tegn hører til GSM 7-bit spesifikasjonen. Ved bruk av disse tegnene vil en sms-enhet bestå av 160 tegn. Ved lengre meldinger vil hver enhet bestå av 153 tegn, da 7 tegn brukes som header i hver delmelding slik at de kan settes sammen i riktig rekkefølge på telefonen. Sveve støtter meldinger på inntil 1071 tegn.

GSM-7

@£$¥èéùìòÇØøÅåΔ_ΦΓΛΩΠΨΣΘΞ^{}\[~]|€ÆæßÉ!"#¤%&'()*+,-./0123456789:;<=>?¡ABCDEFGHIJKLMNOPQRSTUVWXYZÄÖÑÜ§¿abcdefghijklmnopqrstuvwxyzäöñüà

Ved bruk av tegn utenom GSM-7 vil en sms-enhet bestå av 70 tegn. Sveve støtter alle Unicode-tegn med UTF-8 encoding, inkludert emoji og samiske bokstaver.

Begrensninger i samtidige API-forespørsler

For å sikre en stabil og rask tjeneste er det en begrensning på antall samtidige API-kall per brukerkonto. Dette påvirker ikke hvor mange SMS som kan sendes.

Det er en grense på 5 samtidige forespørsler mot API-et

Tips til robust integrasjon:

Les svaret som kommer fra APIet på én forespørsel før en ny sendes
Dersom det gjøres for mange samtidige kall vil serveren svare med http status 429 (Too Many Requests)
Hvert kall tar kun noen millisekunder, så dette påvirker ikke hvor mange SMS du kan sende. Det begrenser bare antall samtidige, parallelle kall mot APIet

Behov for flere samtidige kall?
Dersom du har behov for flere samtidige kall kan du kontakte oss på post@sveve.no. Dette kan være fordi du sender SMS fra flere ulike servere, eller at du av andre grunner har behov for flere samtidige kall.