SMS versturen via HTTP-API
Versturen van SMS
Deze API werkt middels een HTTP request. Wanneer u een HTTP request naar onze server stuurt, kunt u met behulp van POST of GET variabelen de waarden meesturen. Bijvoorbeeld de afzender, het bericht en de ontvangers. Gebruik onderstaande URL voor het versturen van SMS-berichten:
Post zo de aanvraag:
http://www.mollie.nl/xml/sms/?username=[username]
&password=[password]&originator=[originator]&
recipients=[recipient(s)]&message=[message]
| Parameter | Uitleg | Opmerkingen |
|---|---|---|
| username | mollie.nl gebruikersnaam | |
| password | mollie.nl wachtwoord | |
| originator | afzender van het bericht | maximaal 14 cijfers of 11 tekens |
| recipients | ontvanger(s) van het bericht | nummers scheiden met komma |
| message | het bericht | maximaal 160 tekens (tenzij long sms of binary) |
| Optionele parameters | ||
| md5_password | uw mollie wachtwoord md5 ge-encrypt | in plaats van password gebruiken |
| gateway | welke SMS-route er gebruikt moet worden | Wat moet hier meegegeven worden? |
| reference | nodig voor afleverrapportage | meer over rapportages » |
| dlrurl | alternatieve url voor afleverrapportage | meer over rapportages » |
| deliverydate | lever bericht af op een bepaald tijdstip | formaat: yyyymmddhhmmss |
| charset | naam van charset waarin bericht wordt aangeleverd | Windows-1252 / UTF-8 / ISO-8859-1(5) / etc. |
| type | soort SMS-bericht | normal / wappush / vcard / flash / binary / long |
| udh | de 'header' van het SMS-bericht | alleen bij type=binary |
| return | geef extra informatie terug in terugkoppeling | optie: charged |
| cut | automatisch berichten na 160 karakters afknippen | true / false |
| replace_illegal_chars | non-GSM karakters vervangen door alternatieve karakters | true / false; zie Opmerkingen |
Verwerken van de response
Na het sturen van de HTTP-request geeft onze server een XML-resultaat terug. Hieronder vind je een voorbeeld:
<?xml version="1.0" ?>
<response>
<item type="sms">
<recipients>1</recipients>
<success>true</success>
<resultcode>10</resultcode>
<resultmessage>Message successfully sent.</resultmessage>
</item>
</response>
Het item recipients geeft in het geval dat het versturen gelukt is het aantal telefoonnummers waarnaar het bericht verstuurd is aan. Nummers die duidelijk geen telefoonnummer zijn worden door ons systeem gefilterd.
Het item success geeft simpelweg aan of het versturen gelukt is of niet, dit staat gelijk met of resultcode op 10 (success=true) staat of niet.
Mogelijke resultaten uit resultcode:
- 10 - succesvol verzonden
- 20 - geen 'username' opgegeven
- 21 - geen 'password' opgegeven
- 22 - geen of onjuiste 'originator' opgegeven
- 23 - geen 'recipients' opgegeven
- 24 - geen 'message' opgegeven
- 25 - geen juiste 'recipients' opgegeven
- 26 - geen juiste 'originator' opgegeven
- 27 - geen juiste 'message' opgegeven
- 28 - probleem met charset
- 29 - andere parameter fout
- 30 - incorrecte 'username' of 'password'
- 31 - onvoldoende credits om te versturen
- 98 - gateway onbereikbaar
- 99 - onbekende fout
Tip: het is ook mogelijk om een connectie te openen met onze 'secure SSL webserver'. In dit geval dient u een HTTPS-connectie te openen met https://secure.mollie.nl/. Voor de rest blijft alles gelijk.
Opmerkingen
Wij adviseren u alle variabelen die u aanlevert via een HTTP GET request te urlencoden (PHP / .NET / Ruby).
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 u hiervan zo min mogelijk last te laten hebben, zetten wij standaard alle karakters die niet voorkomen in de GSM-charset om naar aanverwante karakters. Zo zetten wij bijvoorbeeld ç om naar c; ë naar e en ® naar R. Dit doen wij bij het bericht en bij de afzender (indien alfanumeriek). Als er karakters vervangen zijn koppelen wij dit in de response terug aan u.
Voorbeeld van response als er karakters vervangen zijn:
<?xml version="1.0" ?>
<response>
<item type="sms">
<recipients>1</recipients>
<success>true</success>
<resultcode>10</resultcode>
<resultmessage>Message successfully sent. Replaced 2 characters which are not in the GSM 03.38-charset.</resultmessage>
</item>
</response>
Mocht u niet willen dat een bericht verstuurd wordt als het bericht karakters bevat die niet voorkomen in de GSM-charset, kunt u de parameter replace_illegal_chars meegeven met als waarde false. Als u dan een bericht verstuurt met karakters die niet voorkomen in de GSM-charset, wordt het bericht niet verstuurd en ontvangt u een fout met foutcode 28.
Het aanleveren van de berichten via de API kunt u doen in verschillende charsets. Als u weet in welke charset u het bericht aanlevert kunt u dit meegeven via de charset parameter. Als u deze parameter niet meegeeft proberen wij automatisch te detecteren in welke charset uw bericht is opgesteld.
SMS API downloads
Hieronder hebben wij classes, modules en voorbeelden in verschillende programmeertalen voor u klaarstaan.
| Omschrijving | Programmeertaal | Auteur | Versie |
|---|---|---|---|
| PHP class | PHP 4.x, 5.x of hoger | Mollie | v2.3 (17/06/09) |
| Ruby library | Ruby | Eloy Durán | v1.0.0 |
| Perl library | Perl | b10m | v0.02 |
| ASP script | ASP | D-motivatie | v1.00 |
| PowerShell | Microsoft PowerShell | M. Seegers | v1.0 |
| C# (.NET) | C# (.NET) | Oblivio | v2.0 |
| Java | Java | Crolox B.V. | v1.0 |
| Python | Python | I. van der Wijk | v1.0 |
| VB.NET | Visual Basic .NET | K. de Groot | v1.0 |
| Delphi (Win32 / .NET) | Delphi (Win32 / .NET) | Bob Swart | v1.0 | Plugins / modules voor derde partijen |
| Nagios Plugin | Nagios plugin voor Mollie | Brainstorm ICT | v1.1 |
| Zabbix Plugin | Zabbix plugin voor Mollie | Mollie B.V. | v1.1 |
