dansk
english
svenskaKEYWORD RESERVATION OVER HTTP
Forord
Dette dokument beskriver hvorledes man gennem et API; kan søge efter og reservere keywords og numre gennem HTTP POST/GET.
Vores service er baseret på et script, der lytter efter de forskellige request parametre, der definere hvad der skal ske.
Parametre navnene er ligefrem, f.eks. hedder nummer parametret "number", og brugernavn parametret "username".
Efter en forespørgsel, vil systemet returnere et XML dokument, der beskriver status'en på forespørgslen, og såfremt forespørgslen er succesfuldt, vil XML dokumentet indeholde en række værdier.
Vores service er baseret på et script, der lytter efter de forskellige request parametre, der definere hvad der skal ske.
Parametre navnene er ligefrem, f.eks. hedder nummer parametret "number", og brugernavn parametret "username".
Efter en forespørgsel, vil systemet returnere et XML dokument, der beskriver status'en på forespørgslen, og såfremt forespørgslen er succesfuldt, vil XML dokumentet indeholde en række værdier.
Syntax for forespørgsler
Keyword reservation er baseret på både GET og POST URL forespørgsler.
Forespørgslen skal sendes til følgende adresse:
De tilsendte variabler, analyseres som enten GET eller POST parametre.
Alle parametre skal URL Encodes, i henhold til RFC 1738, med undtagelse af at + betragtes som et mellemrum([SPACE]).
En forespørgsel vil se således ud:
Dette vil kontrollere om keywordet "KEYWORD" er ledigt på nummeret +4512345678.
Forespørgslen skal sendes til følgende adresse:
http://keyword.coolsmsc.dk/
De tilsendte variabler, analyseres som enten GET eller POST parametre.
Alle parametre skal URL Encodes, i henhold til RFC 1738, med undtagelse af at + betragtes som et mellemrum([SPACE]).
En forespørgsel vil se således ud:
http://keyword.coolsmsc.dk/?username=xxxx&password=xxxx&number=4512345678&keyword=KEYWORD&mode=check
Dette vil kontrollere om keywordet "KEYWORD" er ledigt på nummeret +4512345678.
Parametre
| username | Påkrævet | Brugernavnet for den konto, der laver opslaget. |
| password | Påkrævet | Kodeordet til den konto, der laver opslaget. |
| mode | Påkrævet | Angiver, hvilken handling man ønsker at udføre, den kan antage følgende værdier: check - Kontrollerer tilgængeligheden af keyword og nummer. reserve - Reserverer kombinationen af keyword og nummer. delete - Sletter kombinationen af keyword og nummer |
| lang | Sproget du ønsker at resultatet skal beskrives i, værdierner kan være som følger: da for Dansk. en for Engelsk. Hvis udeladt er sproget dansk. | |
| number | Hvilket nummer skal den pågældende handling udføres på. Dette parameter er påkrævet, når man laver "reserve" eller "delete", det skal ligeledes angives hvis man har udfyldt parametret keyword. | |
| keyword | Hvilket keyword, man ønsker at udføre den pågældende handling med.< | |
| apiurl | Angiver hvilken URL adresse vi skal kalde, når vi modtager indkommende beskeder til tjenesten. Dette angives kun når man laver en reserve, hvorved denne URL sættes op til API tjenesten. | |
| random | Hvis man forespørger på et extended nummer, skal man sætte denne til true, hvis man ønsker et tilfældigt nummer. | |
| pattern | Hvis man søger på et extended number, kan den udfyldes for f.eks. at lave wildcard søgning, hvor * er joker tegn.kan man sætte dette til "true" hvorved en række tilfældige numre vil blive vist. | |
| limit | Når man forespørger på en række extended numbers, kan man sætte en limit på hvor mange resultater man vil have. Denne er som standard 25. |
Kontroller om keyword er ledigt
Hvis du ønsker at kontrollere om keywordet "KWD" er ledig på applikationskoden 1272, kan du kalde følgende url:
Når du laver et opslag vil der være en HTTP Header med navnet X-Status der enten vil være "success" eller "failure", afhængig af resultatet af forespørgslen.
Det anbefales at kontrollere resultatet af din forespørgsel med denne header.
Udover HTTP Headeren, vil der blve returneret et XML Dokument med yderligere information.
For XML Dokumentet findes der en DTD på http://keyword.coolsmsc.dk/dtd/keyword.dtd
Et eksempel på forsøg med forkert brugernavn og adgangskode, vil returnere følgende:
Et eksempel, hvor keywordet er ledigt, vil returnere følgende:
Et eksempel, hvor keywordet er optaget, vil returnere følgende:
http://keyword.coolsmsc.dk/?username=xxxx&password=xxxx&number=1272&keyword=KEYWORD&mode=check
Når du laver et opslag vil der være en HTTP Header med navnet X-Status der enten vil være "success" eller "failure", afhængig af resultatet af forespørgslen.
Det anbefales at kontrollere resultatet af din forespørgsel med denne header.
Udover HTTP Headeren, vil der blve returneret et XML Dokument med yderligere information.
For XML Dokumentet findes der en DTD på http://keyword.coolsmsc.dk/dtd/keyword.dtd
Et eksempel på forsøg med forkert brugernavn og adgangskode, vil returnere følgende:
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE keyword SYSTEM "http://keyword.coolsmsc.dk/dtd/keyword.dtd">
<keyword version="1.0">
<status>failure</status>
<error>
<description>Adgang nægtet</description>
</error>
</keyword>
<!DOCTYPE keyword SYSTEM "http://keyword.coolsmsc.dk/dtd/keyword.dtd">
<keyword version="1.0">
<status>failure</status>
<error>
<description>Adgang nægtet</description>
</error>
</keyword>
Et eksempel, hvor keywordet er ledigt, vil returnere følgende:
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE keyword SYSTEM "http://keyword.coolsmsc.dk/dtd/keyword.dtd">
<keyword version="1.0">
<status>success</status>
<result>
<number>1272</number>
<keyword>KEYWORD</keyword>
<status>available</status>
</result>
</keyword>
<!DOCTYPE keyword SYSTEM "http://keyword.coolsmsc.dk/dtd/keyword.dtd">
<keyword version="1.0">
<status>success</status>
<result>
<number>1272</number>
<keyword>KEYWORD</keyword>
<status>available</status>
</result>
</keyword>
Et eksempel, hvor keywordet er optaget, vil returnere følgende:
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE keyword SYSTEM "http://keyword.coolsmsc.dk/dtd/keyword.dtd">
<keyword version="1.0">
<status>failure</status>
<error>
<description>Keywordet er optaget</description>
</error>
</keyword>
<!DOCTYPE keyword SYSTEM "http://keyword.coolsmsc.dk/dtd/keyword.dtd">
<keyword version="1.0">
<status>failure</status>
<error>
<description>Keywordet er optaget</description>
</error>
</keyword>
Søg efter nummer
Hvis du benytter extended numbers, kan du søge efter ledige numre, ved at kalde denne url:
Hvis du vil undersøge et specifikt nummer, kan du kalde følgende:
Hvis du vil finde ledige numre, der ender på 321, kan du kalde følgende:
Et eksempel, hvor 3 numre er ledige er ledigt, vil returnere følgende:
http://keyword.coolsmsc.dk/?username=xxxx&password=xxxx&mode=check&random=true
Hvis du vil undersøge et specifikt nummer, kan du kalde følgende:
http://keyword.coolsmsc.dk/?username=xxxx&password=xxxx&mode=check&number=45609940404040
Hvis du vil finde ledige numre, der ender på 321, kan du kalde følgende:
http://keyword.coolsmsc.dk/?username=xxxx&password=xxxx&mode=check&random=true&pattern=*321
Et eksempel, hvor 3 numre er ledige er ledigt, vil returnere følgende:
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE keyword SYSTEM "http://keyword.coolsmsc.dk/dtd/keyword.dtd">
<keyword version="1.0">
<status>success</status>
<result>
<number>45609940404321</number>
<status>available</status>
</result>
<result>
<number>45609940405321</number>
<status>available</status>
</result>
<result>
<number>45609940406321</number>
<status>available</status>
</result>
</keyword>
<!DOCTYPE keyword SYSTEM "http://keyword.coolsmsc.dk/dtd/keyword.dtd">
<keyword version="1.0">
<status>success</status>
<result>
<number>45609940404321</number>
<status>available</status>
</result>
<result>
<number>45609940405321</number>
<status>available</status>
</result>
<result>
<number>45609940406321</number>
<status>available</status>
</result>
</keyword>
Reserver
Når du vil reservere et keyword, kalder du URL'en på samme måde, som hvis du havde søgt på et keyword, dog med mode sat til reserve, og apiurl, sat til den URL du ønsker indkommende beskeder sendt til.
URL'en kan se således ud:
Hvis reservering kan gennemføres, gives et svar tilbage:
Bemærk, at status nu er sat til "reserved".
Et eksempel på forsøg med ugyldig URL, vil returnere følgende:
URL'en kan se således ud:
http://keyword.coolsmsc.dk/?username=xxxx&password=xxxx&number=1272&keyword=KEYWORD&mode=reserve&apiurl=http%3A%2F%2Fyouserver.tld%2Fscript.ext
Hvis reservering kan gennemføres, gives et svar tilbage:
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE keyword SYSTEM "http://keyword.coolsmsc.dk/dtd/keyword.dtd">
<keyword version="1.0">
<status>success</status>
<result>
<number>1272</number>
<keyword>KEYWORD</keyword>
<status>reserved</status>
</result>
</keyword>
<!DOCTYPE keyword SYSTEM "http://keyword.coolsmsc.dk/dtd/keyword.dtd">
<keyword version="1.0">
<status>success</status>
<result>
<number>1272</number>
<keyword>KEYWORD</keyword>
<status>reserved</status>
</result>
</keyword>
Bemærk, at status nu er sat til "reserved".
Et eksempel på forsøg med ugyldig URL, vil returnere følgende:
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE hlr SYSTEM "http://hlr.coolsmsc.dk/dtd/hlr.dtd">
<hlr version="1.0">
<status>failure</status>
<error>
<description>apiurl parametret skal indeholde en gyldig URL</description>
</error>
</hlr>
<!DOCTYPE hlr SYSTEM "http://hlr.coolsmsc.dk/dtd/hlr.dtd">
<hlr version="1.0">
<status>failure</status>
<error>
<description>apiurl parametret skal indeholde en gyldig URL</description>
</error>
</hlr>
Slette en tjeneste
Hvis du vil slette en tjeneste, kan du benytte parametret mode og sætte den til "delete":
Det kan gøres for et keyword:
Ligeledes er det muligt at slette et nummer:
Såfremt forespørgslen kan gennemføres, vil man få et XML svar tilbage med status success:
Bemærk at her er status i result sat til deleted.
Det kan gøres for et keyword:
http://keyword.coolsmsc.dk/?username=xxxx&password=xxxx&number=1272&keyword=KEYWORD&mode=delete
Ligeledes er det muligt at slette et nummer:
http://keyword.coolsmsc.dk/?username=xxxx&password=xxxx&number=45609940406321&mode=delete
Såfremt forespørgslen kan gennemføres, vil man få et XML svar tilbage med status success:
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE keyword SYSTEM "http://keyword.coolsmsc.dk/dtd/keyword.dtd">
<keyword version="1.0">
<status>success</status>
<result>
<number>1272</number>
<keyword>KEYWORD</keyword>
<status>deleted</status>
</result>
</keyword>
<!DOCTYPE keyword SYSTEM "http://keyword.coolsmsc.dk/dtd/keyword.dtd">
<keyword version="1.0">
<status>success</status>
<result>
<number>1272</number>
<keyword>KEYWORD</keyword>
<status>deleted</status>
</result>
</keyword>
Bemærk at her er status i result sat til deleted.
