Handleiding API

UITLEG

Door middel van onze API kan je onze SMS-toepassing inbouwen in je eigen systeem, website, desktop of mobile applicatie. Er kan bijvoorbeeld een optie worden ingebouwd zodat de benodigde gegevens voor sms-berichten worden verzameld (met bijvoorbeeld een klik op een knop of op een bepaald tijdstip) en de sms’jes dan vanuit je eigen systeem worden verstuurd.
Hiervoor kan je gebruik maken van onze SMS API dat werkt door middel van een simpele HTTP-request. Wanneer je een HTTP-request naar onze server stuurt, dan kan je met behulp van POST- of GETvariabelen de waarden meesturen. Bijvoorbeeld de afzender, het bericht en de ontvangers. De parameters die je hiervoor moet gebruiken staan hieronder beschreven.

PARAMETERS

Parameter Beschrijving
klantnaam De naam van je account zoals die in de URL staat die wij voor je aanmaken
username Je gebruikersnaam
sha1_password De SHA-1 hash van uw wachtwoord
originator De naam die je als afzender wilt meesturen bij de sms’jes, bestaande uit maximaal 11 alphanumerieke tekens
message Het sms-bericht, bestaande uit maximal 160 tekens, URL-gecodeerd
recipients De 06-nummers van de ontvangers, gescheiden door een komma
gateway 1 (vaste waarde)

Voorbeeld:

http://klantnaam.pompoensms.com/api/sms?username=testuser&sha1_password=70dd131e07724df45880 9f878a968e4f6db7d403&originator= Pompoen&message=SMS-voorbeeld.++Test+123&recipients=31612345678,0612345678&gateway=1

OPTIONELE PARAMETERS

Parameter Beschrijving
deliverydate aflevertijdstip, aan te geven als als yyyymmddhhmmss (bijvoorbeeld 20120323113000 voor het versturen op 23 maart 2012 om 11:30 uur precies)
cut automatisch berichten na 160 karakters afknippen, aan te geven als true of false
replace_illegal_chars non-GSM karakters vervangen door alternatieve karakters, aan te geven als true of false (zie hieronder voor uitleg)

Non-GSM karakters:

Voor het versturen van SMS-berichten wordt standaard de GSM 03.38-charset gebruikt. Helaas komen veel karakters niet voor in de GSM-charset. Om je hiervan zo min mogelijk last te laten hebben, worden standaard alle karakters die niet voorkomen in de GSM-charset omgezet naar aanverwante karakters. Zo wordt bijvoorbeeld ç omgezet om naar c; ë naar e en ® naar R. Dit gebeurt bij het bericht en bij de afzender (indien alfanumeriek). Als er karakters vervangen zijn, wordt dit in het resultaat vermeldt.

Voorbeeld:

<response>
<item type=”sms”>
<resultmessage>Message succesful sent. Replaced 2 characters which are not in the GSM 03.38-charset.</resultmessage>
</item>
</response>

AFLEVER RAPPORTAGE

Na het versturen van een sms wordt er een XML-resultaat gegenereerd met de status van het verstuurde bericht.

Voorbeeld:

<response>
<item code=”succes”>
<code>10</code>
<message>Succesfully sent 1 message(s)</message>
</item>
</response>

Resultaatcodes:

Parameter Beschrijving
10 Bericht(en) succesvol verzonden
20 Geen ‘username’ opgegeven
21 Geen ‘password’ opgegeven
22 Geen ‘originator’ opgegeven
23 Geen ‘recipients’ opgegeven
24 Geen ‘message’ opgegeven
25 Geen juiste ‘recipients’ opgegeven; aantal tekens van telefoonnummer(s) klopt mogelijk niet
26 Geen juiste ‘originator’ opgegeven; mogelijk teveel tekens (max. 11)
27 Geen juiste ‘message’ opgegeven; mogelijk teveel tekens (max. 160) of onjuiste URL-codering
28 Probleem met charset
29 Andere parameterfout
30 Incorrecte ‘username’ of ‘password’
31 Onvoldoende credits beschikbaar
98 Gateway onbereikbaar
99 Onbekende fout

CREDITS

Het aantal credits dat je gebruikt wordt automatisch van je tegoed afgeschreven.
Als je wilt weten hoeveel credits je nog in uw tegoed hebt, dan kunt je dat ook opvragen met een HTTP-request

Voorbeeld:

http://klantnaam.pompoensms.com/api/credits?username=testuser&sha1_password=70dd131e07724df458809f878a968e4f6db7d403

Als response krijg je een XML-response zoals hieronder terug:

<response>
<item type=”succes”>
<credits>75.0</credits>
</item>
</response>