Polski

Application Programming Interface (SMS API)

Proszę upewnij się, aby zajrzeć na W Jaki Sposób zanim zbytnio zagłębisz się w cokolwiek. Dzięki!

Wyślij API SMS

Funkcja: sendSms

Wysyła wiadomości SMS za pomocą znaków GSM oraz Unicode. Łączy długie wiadomości automatycznie do 5 wiadomości (765 znaków).
Zwraca objekt JSON, żeby potwierdzić żądanie (lub oznajmić błąd).

Przykład POST/GET

username=xxx&password=yyyy&function=sendSms &number=+491234567890&message=Have%20a%20nice%20day! &senderid=+44987654321&callbackurl=http://www.my-server.com/callback.php

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendSms",
    "number":"+491234567890",
    "message":"Have a nice day!",
    "senderid":"+449876543210",
    "callbackurl":"http://www.my-server.com/callback.php"
}

Parametry Obowiązkowe

Parametr Opis Typ
number Numer telefonu komórkowego w formacie międzynarodowym. Na przykład: 49123456789 lub +49123456789 lub 0049123456789 string
message Treść wiadomości. My-Cool-SMS automatycznie wykrywa kodowanie danych wejściowych i przetwarza wiadomość SMS odpowiednio na znaki GSM lub Unicode.
Możesz użyć opcjonalnego parametru znaków Unicode, aby wymusić poszczególne kodowanie. Jeżeli znaki Unicode są ustawione jako prawdziwe, wiadomość SMS zostanie wysłana w postaci znaków Unicode i parametr wiadomości musi być podany w notacji Unicode UCS2. Jeżeli znaki Unicode są ustawione jako fałszywe, wiadomość SMS zostanie wysłana w postaci znaków GSM i parametr wiadomości może zawierać jedynie znaki z alfabetu GSM7.
Długie wiadomości są automatycznie łączone. Maksimum 765 znaków dla wiadomości GSM lub 335 dla Unicode.
Należy pamiętać, że powinno się zawsze używać parametru znaków unicode, gdy wysyłamy żądania GET.
string
Wskazówka: Dowiedz się więcej o GSM, Unicode oraz UCS2.

Parametry Opcjonalne

Parametr Opis Typ
unicode Wymusza na wiadomości kodowanie Unicode lub GSM. Jeżeli ustawiony jako prawdziwy, parametr wiadomości musi być wysłany w notacji UCS2. Jeżeli ustawiony jako fałszywy, parametr wiadomości może zawierać jedynie znaki z alfabetu GSM7.
Jeżeli nie ustawiony lub ustawiony na NULL, My-Cool-SMS wykryje automatycznie kodowanie danych wejściowych.
boolean
senderid Numer telefonu komórkowego w formacie międzynarodowym, na przykład: +44123456789 lub alfanumeryczny ID nadawcy o maksymalnej ilości 11 zmaków, na przykład: Firma string
scheduletime Wysyła wiadomość o określonej porze. Używaj formatu i strefy czasowej ATOM, tzn.: "2011-04-17T17:59:36.67+08" albo "2011-04-17 17:59:36-02" timestamp with timezone
callbackurl Opcja Callback URL służy temu aby otrzymać dla tej wiadomości aktualizacje statusów oraz raportów doręczenia. Na przykład: http://www.myserver.com/callback.php string
Wskazówka: Dowiedz się więcej o opcji wywołań zwrotnych dla raportów doręczenia.

Przykład Udanego Odzewu

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "body":"Have a nice day!",
    "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
    "bodygsm7":"486176652061206E6963652064617921",
    "number":"+491234567890"
    "senderid":"+449876543210",
    "senderidenabled":true,
    "unicode":false,
    "numchars":321,
    "escapenumchars":0,
    "smscount":3,
    "charge":0.112,
    "balance":752.121,
    "countrycode":"DE",
    "prefix":"+49",
    "timestamp":"2013-04-02T22:27:22-07:00",
    "callbackurl":"http://www.my-server.com/callback.php"
}

Wartości Udanego Odzewu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
smsid Unikatowy ID dla tej wiadomości SMS. Powinien zostać zachowany przez stronę klienta i użyte jako odsyłacz dla raportów doręczenia string(32)
body Treść wiadomości w postaci znaków Unicode string
bodyucs2 Treść wiadomości w notacji UCS2 bytecode string
bodygsm7 Treść wiadomości w notacji GSM7 bytecode (lub NULL, jeżeli wiadomość została wysłana w postaci znaków Unicode) string || NULL
senderid Indicates the sender id used for the sent message. string
senderidenabled Wskazuje czy numer docelowy obsługuje dynamiczny ID nadawcy boolean
unicode Wskazuje czy wiadomość została wysłana przy użyciu znaków Unicode lub GSM boolean
numchars Wskazuje, ile znaków zawierała wiadomość integer
escapenumchars Wskazuje, ile znaków trzeba było uciąć (i było liczonych jako dwa znaki w GSM) integer
smscount Wskazuje, czy wiadomość została złączona w jedną długą wiadomość SMS oraz podaje liczbę użytych wiadomości SMS integer
charge Wskazuje, na jaką kwotę obciążone zostało Twoje konto za tą wiadomość float
balance Pozostał saldo na Twoim koncie float
countrycode Indicates to which country the SMS was sent to (ISO Code) string
prefix Indicates the prefix of the country to which the SMS was sent to string
timestamp Timestamp of when the SMS was accepted (using the time zone you were on when you logged in to the web portal the last time or UTC if unknown). Given in DATE_ATOM Format (e.g. 2013-04-02T22:27:22-07:00). string
callbackurl Adres URL wywołań zwrotnych na który zostaną wysłane statusy aktualizacji oraz raporty doręczenia dla tej wiadomości. string || NULL

Błędy Funkcyjne API

Kod Błędu Opis Błędu
210 Numer wydaje się być nieprawidłowy
211 Parametr wiadomości jest pusty
212 Parametr wiadomości jest za długi
213 Parametr unicode jest ustawiony aby forsował znaki Unicode, jednak parametr wiadomości nie był wysłany w notacji UCS2.
214 Parametr unicode jest ustawiony aby forsował znaki GSM, jednak parametr wiadomości był wysłany w notacji UCS2.
215 Parametr unicode jest ustawiony aby forsował znaki GSM, jednak parametr zawiera znaki z poza alfabetu GSM7.
216 The input for Sender ID is invalid. You may use a phone number or an alphanumeric text with up to eleven characters (A-Z, a-z, 0-9 and the dash symbol).
217 Kody krótkie ID Nadawców nie są dozwolone
218 Parametr url wywołania zwrotnego wydaje się być nieprawidłowy
219 Ustawiony czas wydaje się być nieprawidłowy. Używaj formatu i strefy czasowej ATOM, tzn.: "2011-04-17T17:59:36.67+08" albo "2011-04-17 17:59:36-02"
Wskazówka: Również proszę spojrzeć na część o błędach ogólnych

Przychodzące API SMS

Opcja Callback: pushIncomingSms

My-Cool-SMS automatycznie wysyła dane SMS na Twój serwer, jeśli adres URL wywołania zwrotnego dla Twojego numeru jest zdefiniowany w ustawieniach Twojej skrzynki odbiorczej. Można edytować Twój URL wywołania zwrotnego w ustawieniach skrzynki odbiorczej poprzez interfejs www My-Cool-SMS.

Przykład Wywołania Zwrotnego

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Incoming SMS Callback
Content-Length: n
Cache-Control: no-cache
Connection: close

{
   "from":"+1230987654321",
   "fromcountrycode":"US",
   "to":"+440987654321",
   "unicode":false,
   "smscount":1,
   "body":"Have a nice day with incoming SMS!",
   "bodyucs2":"0048006100760065002000610020006e00690063006500200064",
   "bodygsm7":"5374616666206D6565746925",
   "numchars":54,
   "escapenumchars":0,
   "cost":"0.010"
}
Wskazówka: Zajrzyj tu aby uzyskać więcej informacji dotyczących w jaki sposób obsługiwać funkcję wywołania zwrotnego JSON.

Wartości Wywołania Zwrotnego

Klucz Opis Typ
from Id nadawcy z którym wysłano wiadomość. Może być w postaci numeru w międzynarodowym formacie lub alfanumeryczny id nadawcy. string
fromcountrycode Zawiera dwuliterowy kod numeru kierunkowego ISO nadawcy, jeśli parametr od jest numerem. Zawiera NULL jeśli parametr od jest alfanumeryczny. string(2) || NULL
to Numer na który wysłano wiadomość (Twój wirtualny numer telefonu). string
unicode Wskazuje czy wiadomość została wysłana za pomocą znaków Unicode lub GSM. boolean
smscount Wskazuje, czy wiadomość została złączona w jedną długą wiadomość SMS oraz podaje liczbę użytych wiadomości SMS integer
body Treść wiadomości w postaci znaków Unicode string
bodyucs2 Treść wiadomości w notacji UCS2 bytecode string
bodygsm7 Treść wiadomości w notacji GSM7 bytecode (lub NULL, jeżeli wiadomość została wysłana w postaci znaków Unicode) string
numchars Wskazuje, ile znaków zawierała wiadomość integer
escapenumchars Wskazuje, ile znaków trzeba było uciąć (i było liczonych jako dwa znaki w GSM) integer
cost Wskazuje, na jaką kwotę obciążone zostało Twoje konto za tą wiadomość float

Funkcja: getIncomingSms

Queries the server for received SMS text messages. Returns a status summary for the selected virtual number and an array containing inbound SMS. Can be customized by using the optional parameters.

Przykład POST/GET

username=xxx&password=yyy&function=getIncomingSms&virtualnumber=+449876543201

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"getIncomingSms",
    "virtualnumber":"+449876543201"
}

Parametry Obowiązkowe

Parametr Opis Typ

Parametry Opcjonalne

Parametr Opis Typ
thresholdid Only messages with a higher id should be returned. This parameter is required to only receive messages that have been received after the ones that were fetched already. Every message fetched with the getIncomingSms function contains a unique id, which should be stored on client side in order to use it here. Defaults to 0. integer
limit The maximum amount of messages to be returned. Defaults to 25. If set to 0, no limit will be applied. integer
order Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC" string
thresholdoperator Specifies whether the returned messages should have higher or lower ids as compared to the id provided in thresholdid. Can be either "gt" (greater than) or "lt" (lower than). Defaults to "gt" string(2)
virtualnumber The virtual number for which sms text messages should be fetched. If no virtual number is provided inbound texts for all virtual numbers will be returned. string
unreadsmstosyncids This parameter is useful if you want to sync the read/unread status of your inbound SMS pipe on several devices. Provide the ids of the messages that are marked as unread on your device to receive a list of ids of messages that have been marked as read on a different device. You can use those ids to update the read/unread status on your device. If no messages were marked as read the list will be empty. array[int]

Przykład Udanego Odzewu

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "minid":177,
   "messages":[
      {
         "id":201,
         "virtualnumber":"+449876543201",
         "senderid":"+886983029751",
         "body":"Have a nice day!",
         "bodyucs2":"AAAA",
         "bodygsm7":"AA",
         "unicode":false,
         "timestamp":"2011-08-10 00:08:37.488+08",
         "unixtimestamp":"1316531343.9",
         "numchars":16,
         "escapechars":0,
         "smscount":1,
         "charge":"0.015",
         "senderidcountrycode":"TW",
         "virtualnumbercountrycode":"HK"
      }
   ]
}

Wartości Udanego Odzewu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
total The total number of messages on this virtual number integer
fetched The number of messages that were fetched integer
maxid The "maxid" parameter indicates the highest unique id (last message) on this virtual number. This value should be stored and use for future queries as "thresholdid" parameter in order to just fetch new messages. integer
minid The lowest sms id found for this user. Can be used for client side reference. integer
messages Contains an array of SMS text objects (with self-explaining attribute names, see example). array

Błędy Funkcyjne API

Kod Błędu Opis Błędu
232 Numer wydaje się być nieprawidłowy
233 The virtual number is either invalid or not registered with this user account. Please contact service@my-cool-sms.com for assistance.
234 The provided thresholdid is invalid
235 Nieprawidłowy parametr limitu
236 Invalid order parameter
242 No virtual numbers found.
Wskazówka: Również proszę spojrzeć na część o błędach ogólnych

Wyszukiwanie Bilansu API

Funkcja: getBalance

Odsyła przedmiot JSON zawierający saldo pozostałych środków na Twoim koncie (lub oznajmiający błąd).

Przykład POST/GET

username=xxx&password=yyyy&function=getBalance

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

Przykład Udanego Odzewu

{
    "success":true,
    "balance":752.210
}

Wartości Udanego Odzewu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
balance Saldo pozostałych środków w walucie Euro float

Raport Doręczenia API

Istnieją dwa sposoby otrzymywania raportów doręczenia od My-Cool-SMS. Możesz odczytywać serwer My-Cool-SMS za pomocą getDeliveryReport lub otrzymywać wywołania zwrotne HTTP na adres URL na Twoim serwerze za pomocą pushDeliveryReport. Należy pamiętać, że raporty doręczenia dla korespondencji są dostępne jedynie poprzez getDeliveryReport.

Funkcja: getDeliveryReport

Zwraca raport doręczenia dla pojedynczej wiadomości SMS (wysłanej za pomocą sendSms) lub korespondencji grupowej (wysyłanej za pomocą sendMailing). Jeśli raport doręczenia korespondencji grupowej jest wymagany (ustawiając opcjonalny parametr groupkey jako prawdziwy), zwrócony obiekt może zawierać streszczenie (domyślnie) lub indywidualne raporty doręczenia dla każdego odbiorcy (ustawiając opcjonalny parametr mailingdetails jako prawdziwy)

Przykład POST/GET

username=xxx&password=yyyy&function=getDeliveryReport &id=ce184cc0a6d1714d1ac763f4fe89f521

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

Parametry Obowiązkowe

Parametr Opis Typ
id ID odsyłacza. Albo sms id (wysłany przez sendSms) albo klucz grupy korespondencyjnej (wysłany przez sendMailing).
Jeżeli używany jest klucz grupowy, opcjonalny parametr groupkey musi być ustawiony jako prawdziwy.
string

Parametry Opcjonalne

Parametr Opis Typ
groupkey Ustaw jako prawdziwy, jeśli został wysłany klucz grupowy w parametrze id i chcesz zwrócić raport doręczenia dla korespondencji (zamiast pojedynczej wiadomości SMS). Domyślne jako fałszywe. string
mailingdetails Ustaw jako prawdziwy, jeśli chcesz osobny raport doręczenia dla każdego odbiorcy korespondencji dodatkowo do streszczenia. Domyślne jako fałszywe. string

Przykład Udanego Odzewu: groupkey=false (Domyślnie)

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}

Wartości Udanego Odzewu: groupkey=false (Domyślnie)

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
smsid Id sms z którym powiązany jest raport doręczenia string
status Wskazuje status tej wiadomości SMS string
Wskazówka: Zajrzyj tu aby uzyskać więcej informacji o kodach statusu.

Przykład Udanego Odzewu: groupkey=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0
}
Wskazówka: Zajrzyj tu aby uzyskać więcej informacji o kodach statusu.

Przykład Udanego Odzewu: groupkey=true&mailingdetails=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0,
    "details":[
        {
            "recipient":"+1230987654321",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "recipient":"+1230987654322",
            "status":"SMS_STATUS_DELIVERED"
        }, 
        (...)
    ]
}
Wskazówka: Zajrzyj tu aby uzyskać więcej informacji o kodach statusu.

Błędy Funkcyjne API

Kod Błędu Opis Błędu
223 Nieznany ID SMS
224 Nieznany Klucz Grupowy
Wskazówka: Również proszę spojrzeć na część o błędach ogólnych

Funkcja: getDeliveryReports

Returns delivery reports for a list of messages.

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReports",
    "ids":[
        "ce184cc0a6d1714d1ac763f4fe89f521",
        "d1ac763f4fe89f521ce184cc0a6d1714"
    ]
}

Parametry Obowiązkowe

Parametr Opis Typ
ids An array of sms ids to perform the delivery status lookup for. array[]

Przykład Udanego Odzewu:

{
    "success":true,
    "reports": [
        {
            "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "smsid":"d1ac763f4fe89f521ce184cc0a6d1714",
            "status":"SMS_STATUS_DELIVERED"
        }
    ]
}

Wartości Udanego Odzewu:

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
reports[] Contains an array with delivery report objects. Each object contains the reference id (smsid) and the corresponding delivery status (status). array
reports[n].smsid Contains the reference sms id for this delivery report string
reports[n].status Contains the delivery status for this SMS. Possible states are: SMS_STATUS_QUEUED, SMS_STATUS_AT_CARRIER, SMS_STATUS_DELIVERY_DELAYED, SMS_STATUS_DELIVERED, SMS_STATUS_BOUNCED, SMS_STATUS_EXPIRED, SMS_STATUS_ERROR or UNKNOWN_ID. string
Wskazówka: Zajrzyj tu aby uzyskać więcej informacji o kodach statusu.

Błędy Funkcyjne API

Kod Błędu Opis Błędu
240 The input for the "ids" parameter seems invalid. Please make sure to provide an array with valid sms ids.
241 The maximum number of delivery reports per request is 100.
Wskazówka: Również proszę spojrzeć na część o błędach ogólnych

Funkcja: getRecentReports

Zwraca obiekt JSON razem z raportem doręczenia dla niedawno wysłanych wiadomości.

Przykład POST/GET

username=xxx&password=yyyy&function=getRecentReports&limit=10

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"getRecentReports",
    "limit":10
}

Parametry Obowiązkowe

Parametr Opis Typ
limit Wskazuje, ile raportów powinno zostać zwrócone integer

Przykład Udanego Odzewu

{
   "success":true,
   "reports":[
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:08:37.233+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:01:03.338+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day with long Unicode messages! \u7e41",
         "bodyucs2":"0048006100760065002000610020006e00690063006500",
         "bodygsm7":"",
         "unicode":true,
         "timesent":"2011-04-18 21:53:24.787+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      (...)
   ]
}

Wartości Udanego Odzewu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
number Numer docelowy string
senderid Id nadawcy z którym wysłano wiadomość string
body Treść wiadomości w postaci znaków Unicode string
bodyucs2 Treść wiadomości w notacji UCS2 bytecode string
bodygsm7 Treść wiadomości w notacji GSM7 bytecode (lub NULL, jeżeli wiadomość została wysłana w postaci znaków Unicode) string
unicode Wskazuje czy wiadomość została wysłana przy użyciu znaków Unicode lub GSM boolean
timesent Czas kiedy wysłano wiadomość timestamp with time zone
status Wskazuje status tej wiadomości SMS string
Wskazówka: Zajrzyj tu aby uzyskać więcej informacji o kodach statusu.

Błędy Funkcyjne API

Kod Błędu Opis Błędu
225 Nieprawidłowy parametr limitu
Wskazówka: Również proszę spojrzeć na część o błędach ogólnych

Opcja Callback: pushDeliveryReport

My-Cool-SMS automatycznie przesyła raport doręczenia na Twój serwer, jeśli parametr url wywołania zwrotnego jest ustawiony przy wysyłaniu za pośrednictwem funkcji sendSms. Wywołanie zwrotne jest wysyłane jako żądanie surowych danych JSON.

Przykład Wywołania Zwrotnego

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Delivery Report
Content-Length: n
Cache-Control: no-cache
Connection: close

{
    "smsid":"498673a1f58df975ab95da33884d9e14",
    "status":"SMS_STATUS_DELIVERED"
}
Wskazówka: Zajrzyj tu aby uzyskać więcej informacji dotyczących w jaki sposób obsługiwać funkcję wywołania zwrotnego JSON.

Wartości Wywołania Zwrotnego

Klucz Opis Typ
smsid Unikatowy ID i odsyłacz do wiadomości SMS. Smsid został zwrócony w udanej odpowiedzi na funkcję sendSms string(32)
status Wskazuje status tej wiadomości SMS string

Odsyłacz Statusu

Status Opis
SMS_STATUS_QUEUED W Kolejce - Wiadomość czeka obecnie w kolejce i nie została jeszcze wysłana.
SMS_STATUS_AT_CARRIER U dostawcy - Wiadomość została wysłana do operatora i powinna być widoczna jako 'doręczono' z chwilą kiedy dotrze do odbiorcy.
Proszę zwróć uwagę na to, że w niektórych przypadkach dostawca nie wysyła raportu doręczenia. Wiadomość będzie dalej wyświetlana jako 'u dostawcy', mimo że została doręczona pomyślnie.
SMS_STATUS_DELIVERY_DELAYED Doręczenie opóźnione - Doręczenie wiadomości zostało opóźnione
SMS_STATUS_DELIVERED Doręczono - Wiadomość została pomyślnie doręczona na numer docelowy
SMS_STATUS_BOUNCED Odrzucono - Wiadomość została odrzucona przez operatora docelowego. Przyczyną może być: nieprawidłowy numer telefonu komórkowego, nieprawidłowe id nadawcy lub telefon docelowy był zbyt długo poza zasięgiem sieci albo nastąpiło przeciążenie sieci na poziomie dostawcy.
SMS_STATUS_EXPIRED Wygasło - Wiadomość wygasła i nie mogła zostać doręczona.
Problem ten występuje zazwyczaj, jeżeli telefon docelowy został wyłączony lub był przez zbyt długi okres czasu poza zasięgiem sieci.
SMS_STATUS_ERROR Nie powiodło się - Doręczenie nie powiodło się (nie zostałeś obciążony kosztami za tą wiadomość).
Przyczyną niedoręczenia może być: brak rozpoznania przez My-Cool-SMS operatora, do którego należy dany numer telefonu (proszę skontaktować się z Pomocą, jeżeli jesteś pewien, że numer jest poprawny) lub chwilowy błąd sieciowy.

Funkcja: getOutboundSms

This function is useful if you want to sync the outbound SMS streams in your account for different devices. It queries the server for outbound sms data and returns and array delivery statuses and additional information on the messages, such as content and timestamps.

Przykład POST/GET

username=xxx&password=yyy&function=getOutboundSms

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"getOutboundSms"
}

Parametry Obowiązkowe

Parametr Opis Typ

Parametry Opcjonalne

Parametr Opis Typ
thresholdid Use this parameter to specify the particular message for which you would like to check if messages were sent before or after. Combine with the thresholdoperator parameter to specify if you need messages with lower or greater ids. string(32)
limit The maximum amount of messages to be returned. Defaults to 25. integer
thresholdoperator Specifies whether the returned messages should have higher or lower ids as compared to the id provided in thresholdid. Can be either "gt" (greater than) or "lt" (lower than). Defaults to "gt" string
order Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC" string

Przykład Udanego Odzewu

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "minid":177,
   "messages":[
      {
        "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
        "body":"Have a nice day!",
        "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
        "bodygsm7":"486176652061206E6963652064617921",
        "number":"+491234567890"
        "senderid":"+449876543210",
        "senderidenabled":"+449876543210",
        "unicode":false,
        "numchars":321,
        "escapenumchars":0,
        "smscount":3,
        "charge":0.112,
        "countrycode":"DE",
        "prefix":"+49",
        "timestamp":"2013-04-02T22:27:22-07:00",
        "callbackurl":"http://www.my-server.com/callback.php",
        "status":"SMS_STATUS_DELIVERED"
      }
   ]
}

Wartości Udanego Odzewu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
total The total number of SMS sent on this account. integer
fetched The total number of SMS returned by this query. integer
maxid Indicates the newest sms returned by this query. Can be used as new thresholdoperator parameter in a subsequent API call. integer
minid Indicates the oldest sms returned by this query. Can be used as new thresholdoperator parameter in a subsequent API call. integer
messages An array containing objects with the outbound SMS returned by this query. The SMS object attributes correspond to the return values of the sendSms function (please see that section for details). array

Błędy Funkcyjne API

Kod Błędu Opis Błędu
234 The provided thresholdid is invalid
235 Nieprawidłowy parametr limitu
236 Invalid order parameter
Wskazówka: Również proszę spojrzeć na część o błędach ogólnych

Lista Adresowa API

Funkcja: sendMailing

Wysyła wiadomość SMS do całej listy adresowej. Wskazówka: Możesz tworzyć i zarządzać listy adresowe w swoim interfejsie www My-Cool-SMS.
Odsyła obiekt JSON potwierdzający żądanie (lub oznajmiający błąd).

Przykład POST/GET

username=xxx&password=yyyy&function=sendMailing &uniqueid=75F3FAB&message=Staff%20meeting%20in%2020%20minutes. &senderid=MyCompany

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendMailing",
    "uniqueid":"75F3FAB",
    "message":"Staff meeting in 20 minutes. Balcony meeting room.",
    "senderid":"MyCompany"
}

Parametry Obowiązkowe

Parametr Opis Typ
uniqueid Unikatowy id listy adresowej. Znajdziesz swoje unikatowe id w interfejsie zarządzania swojej listy adresowej na stronie internetowej. string
message Treść wiadomości. My-Cool-SMS automatycznie wykrywa kodowanie danych wejściowych i przetwarza wiadomość SMS odpowiednio na znaki GSM lub Unicode.
Możesz użyć opcjonalnego parametru znaków Unicode, aby wymusić poszczególne kodowanie. Jeżeli znaki Unicode są ustawione jako prawdziwe, wiadomość SMS zostanie wysłana w postaci znaków Unicode i parametr wiadomości musi być podany w notacji Unicode UCS2. Jeżeli znaki Unicode są ustawione jako fałszywe, wiadomość SMS zostanie wysłana w postaci znaków GSM i parametr wiadomości może zawierać jedynie znaki z alfabetu GSM7.
Długie wiadomości są automatycznie łączone. Maksimum 765 znaków dla wiadomości GSM lub 335 dla Unicode.
Należy pamiętać, że powinno się zawsze używać parametru znaków unicode, gdy wysyłamy żądania GET.
string
Wskazówka: Dowiedz się więcej o GSM, Unicode oraz UCS2.

Parametry Opcjonalne

Parametr Opis Typ
unicode Wymusza na wiadomości kodowanie Unicode lub GSM. Jeżeli ustawiony jako prawdziwy, parametr wiadomości musi być wysłany w notacji UCS2. Jeżeli ustawiony jako fałszywy, parametr wiadomości może zawierać jedynie znaki z alfabetu GSM7.
Jeżeli nie ustawiony lub ustawiony na NULL, My-Cool-SMS wykryje automatycznie kodowanie danych wejściowych.
boolean
senderid Numer telefonu komórkowego w formacie międzynarodowym, na przykład: +44123456789 lub alfanumeryczny ID nadawcy o maksymalnej ilości 11 zmaków, na przykład: Firma string
scheduletime Wysyła wiadomość o określonej porze. Używaj formatu i strefy czasowej ATOM, tzn.: "2011-04-17T17:59:36.67+08" albo "2011-04-17 17:59:36-02" timestamp with time zone
Wskazówka: Dowiedz się więcej o opcji wywołań zwrotnych dla raportów doręczenia.

Przykład Udanego Odzewu

{
    "success":true,
    "groupkey":"041d3b026a50669481695dcf9e1985e4",
    "body":"Staff meeting in 20 minutes. Balcony meeting room.",
    "bodyucs2":"005300740061006600660020006D0065006500740069",
    "bodygsm7":"5374616666206D656574696E672069",
    "uniqueid":"75F3FAB"
    "senderid":"MyCompany",
    "senderidenabled":true,
    "unicode":false,
    "numchars":62,
    "escapenumchars":0,
    "smscount":1,
    "subscribers":79,
    "charge":3.212,
    "balance":752.121
}

Wartości Udanego Odzewu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
groupkey Unikatowy klucz odniesienia dla tej korespondencji. Powinien być przechowywany po stronie klienta i używany jako odsyłacz do raportów doręczenia string(32)
body Treść wiadomości w postaci znaków Unicode string
bodyucs2 Treść wiadomości w notacji UCS2 bytecode string
bodygsm7 Treść wiadomości w notacji GSM7 bytecode (lub NULL, jeżeli wiadomość została wysłana w postaci znaków Unicode) string || NULL
uniqueid string(7)
senderid Wskazuje czy numer docelowy obsługuje dynamiczny ID nadawcy boolean
unicode Wskazuje czy wiadomość została wysłana przy użyciu znaków Unicode lub GSM boolean
numchars Wskazuje, ile znaków zawierała wiadomość integer
escapenumchars Wskazuje, ile znaków trzeba było uciąć (i było liczonych jako dwa znaki w GSM) integer
smscount Wskazuje, czy wiadomość została złączona w jedną długą wiadomość SMS oraz podaje liczbę użytych wiadomości SMS integer
subscribers Liczba abonentów do których wysłabo tą wiadomość integer
charge Wskazuje, na jaką kwotę obciążone zostało Twoje konto za tą wiadomość float
balance Pozostał saldo na Twoim koncie float

Błędy Funkcyjne API

Kod Błędu Opis Błędu
220 Unikatowy id nie jest powiązany z żadną Twoją listą adresową
Wskazówka: Również proszę spojrzeć na część o błędach ogólnych

Funkcja: addSubscriber

Wstawia nowego abonenta do listy adresowej. Aktualizuje abonenta jeżeli wysłanby numer już istnieje w docelowej liście adresowej.
Odsyła obiekt JSON potwierdzający żądanie (lub oznajmiający błąd).

Przykład POST/GET

username=xxx&password=yyyy&function=addSubscriber &uniqueid=75F3FAB&number=+1230987654321&title=Ms&firstname=Marylin &lastname=Monroe&company=Hollywood

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"addSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321",
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood"
}

Parametry Obowiązkowe

Parametr Opis Typ
number Numer abonenta w międzynarodowym formacie. Na przykład: 49123456789 albo +49123456789 albo 0049123456789 string
uniqueid Unikatowy id listy adresowej. Znajdziesz swoje unikatowe id w interfejsie zarządzania swojej listy adresowej na stronie internetowej. string

Parametry Opcjonalne

Parametr Opis Typ
title Tytuł abonenta varchar(16)
firstname Imię abonenta varchar(32)
lastname Nazwisko abonenta varchar(32)
company Firma abonenta varchar(64)

Przykład Udanego Odzewu

{
    "success":true,
    "number":"+1230987654321"
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood",
    "subscribercost":0.019,
    "senderidenabled":true,
    "maxcharsgsm":765,
    "maxcharsunicode":335,
    "countrycode":"US",
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

Wartości Udanego Odzewu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
number Znormalizowany numer telefonu nowego abonenta string
title Tytuł nowego abonenta string
firstname Imię nowego abonenta string
lastname Nazwisko nowego abonenta string
company Firma nowego abonenta string
subscribercost Koszty za wiadomość do tego abonenta float
senderidenabled Wskazuje czy abonent obsługuje id nadawcy boolean
maxcharsgsm Wskazuje ile znaków obsługuje abonent dla wiadomości GSM integer
maxcharsunicode Wskazuje ile znaków obsługuje abonent dla wiadomości Unicode integer
countrycode Numer kierunkowy kraju abonenta (dwuliterowy format standardowy ISO) string(2)
mailinglistcost Nowe, całkowite koszty dla korespondencji do tej listy float
mailinglistsubscribers Nowa liczba abonentów na tej liście adresowej integer

Błędy Funkcyjne API

Kod Błędu Opis Błędu
221 Dane wejściowe {field} są za długie.
Wskazówka: Również proszę spojrzeć na część o błędach ogólnych

Funkcja: updateSubscriber

Zobacz Funkcja: addSubscriber

Funkcja: deleteSubscriber

Usuwa abonenta z listy adresowej (używszy numeru telefonu jako odsyłacz).
Odsyła obiekt JSON potwierdzający żądanie (lub oznajmiający błąd).

Przykład POST/GET

username=xxx&password=yyyy&function=deleteSubscriber &uniqueid=75F3FAB&number=+1230987654321

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"deleteSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321"
}

Parametry Obowiązkowe

Parametr Opis Typ
uniqueid Unikatowy id listy adresowej. Znajdziesz swoje unikatowe id w interfejsie zarządzania swojej listy adresowej na stronie internetowej. string
number Numer abonenta, który ma zostać skasowany z listy adresowej string

Przykład Udanego Odzewu

{
    "success":true,
    "number":"+1230987654321"
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

Wartości Udanego Odzewu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
number Znormalizowany numer telefonu wykasowanego abonenta string
mailinglistcost Nowe, całkowite koszty dla korespondencji do tej listy float
mailinglistsubscribers Nowa liczba abonentów na tej liście adresowej integer

Błędy Funkcyjne API

Kod Błędu Opis Błędu
220 Unikatowy id nie jest powiązany z żadną Twoją listą adresową
222 Nie ma na tej liście adresowej abonenta z takim numerem telefonu
Wskazówka: Również proszę spojrzeć na część o błędach ogólnych

API Utils

Funkcja: doHlrLookup

Wykonuje Home Location Register (HLR) lookup i zwraca MSC, MCC, MNC, INSI numeru, jak i również informacje na temat nazwy sieci, czy numer korzysta obecnie z roamingu i czy został przeniesiony do innej sieci.
Wskazówka: Dowiedz się więcej o HLR, IMSI, MCC, MNC oraz MSC.

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"doHlrLookup",
    "number":"+491234567890"
}

Parametry Obowiązkowe

Parametr Opis Typ
number Numer, dla którego uczynić HLR Lookup, w międzynarodowym formacie. Na przyjkład: 49123456789 albo +49123456789 albo 0049123456789 string

Przykład Udanego Odzewu

{
    "success":true,
    "status":"HLR_STATUS_OK",
    "number":"+49178873xxxxx",
    "imsi":"262031350393955",
    "mcc":"262",
    "mnc":"03",
    "msin":"1350393955",
    "servingmsc":"88693542",
    "servinghlr":"491770112000",
    "originalnetworkname":"E-Plus",
    "originalnetworkprefix":"178",
    "originalcountryname":"Germany",
    "originalcountrycode":"DE",
    "originalcountryprefix":"+49",
    "roamingcountryname":"Taiwan",
    "roamingcountrycode":"TW",
    "roamingcountryprefix":"+886",
    "roamingnetworkname":"Taiwan Mobile",
    "portednetworkname": null,
    "isported":false,
    "iscorrect":true,
    "isroaming":true,
    "charge":0.010
}

Wartości Udanego Odzewu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
status Wskazuje status wyszukiwania. Proszę odwołać się o szczegóły do tabeli statusu odniesienia HLR. string
number Numer dla którego wykonano lookup HLR. string
imsi International Mobile Subscriber Identity (IMSI). Unikatowa identyfikacja powiązana z numerem docelowym. string
mcc Kod sieciowy Mobile Country Code (MCC) string
mnc Kod sieciowy Mobile Network Code (MNC), który może zawierać albo 2 cyfry (standard europejski) albo 3 cyfry (standard północno-amerykański) string
msin Numer identyfikacyjny Mobile Subscription Identification Number (MSIN) w bazie klientów danej sieci. string
servingmsc Tzw. Mobile Switching Center (MSC) który jest odpowiedzialny za przekierowywanie wiadomości SMS. string
servinghlr Tzw. Home Location Register (HLR) z którym powiązany jest numer docelowy. string
originalnetworkname Sieć telefonii komórkowej, do której ten numer przynależy (lub pierwotnie przynależał, jeżeli numer został przekierowany) string
originalnetworkprefix Prefiks sieci telefonii komórkowej do której przynależy ten numer (lub pierwotnie przynależał, jeżeli numer został przekierowany) string
originalcountryname Kraj do którego przynależy ten numer. string
originalcountrycode Dwuznakowy numer kierunkowy ISO do którego przynależy ten numer string
originalcountryprefix Prefiks kraju do którego przynależy ten numer string
roamingcountryname Kraj w którym ten numer obecnie korzysta z roamingu string
roamingcountrycode Dwuznakowy numer kierunkowy ISO kraju w którym ten numer obecnie korzysta z roamingu string
roamingcountryprefix Prefiks kraju w którym ten numer obecnie korzysta z roamingu string
roamingnetworkname The network the cell phone is currently roaming with string
portednetworkname The network the number has been ported to string
isported Wskazuje czy ten numer jest przekierowany boolean
iscorrect Wskazuje czy ten numer jest prawidłowy boolean
isroaming Wskazuje czy ten numer obecnie korzysta z roamingu (w innym kraju) boolean
charge Koszty policzone za HLR lookup (0.01 EUR) numeric
Wskazówka: Dowiedz się więcej o HLR, IMSI, MCC, MNC oraz MSC.

Błędy Funkcyjne API

Kod Błędu Opis Błędu
210 Numer wydaje się być nieprawidłowy
226 Lookup HLR nie powiodło się. Nie policzono kosztów.
Wskazówka: Również proszę spojrzeć na część o błędach ogólnych

HLR Odsyłacz Statusu

Status Opis
HLR_STATUS_UNKNOWN_NUMBER Ten numer nie istnieje albo nie mógł zostać zlokalizowany w żadnym rejestrze HLR. Wiadomość SMS nie zostanie doręczona.
HLR_STATUS_OK Ten numer istnieje i HLR lookup powiódł się. Wiadomość SMS zostanie doręczona.
HLR_STATUS_NOT_OK Ten numer znajduje się poza siecią przez bardzo długi czas albo został wyłączony przez operatora sieci komórkowej. Wiadomość SMS nie zostanie doręczona.
HLR_STATUS_FAILED HLR lookup nie powiódł się. Nie policzono żadnych kosztów.
HLR_STATUS_AWAITING_RESPONSE Awaiting response from HLR.

Funkcja: toUCS2

UCS2 koduje dany ciąg znaków Unicode
Ważne: UCS2 wymaga żądania JSON.

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"toUCS2",
    "str":"繁体中文"
}

Parametry Obowiązkowe

Parametr Opis Typ
number Numer, dla którego uczynić HLR Lookup, w międzynarodowym formacie. Na przyjkład: 49123456789 albo +49123456789 albo 0049123456789 string

Parametry Opcjonalne

Parametr Opis Typ

Przykład Udanego Odzewu

{
    "success":true,
    "ucs2":"7E414F534E2D6587"
}

Wartości Udanego Odzewu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
ucs2 Przedstawiony ciąg w notacji UCS2 string

Błędy Funkcyjne API

Żadne
Wskazówka: Również proszę spojrzeć na część o błędach ogólnych

Funkcja: fromUCS2

Dekodowuje dany ciąg UCS2

Przykład POST/GET

username=xxx&password=yyyy&function=fromUCS2 &str=0048006100760065002000610020006E00690063006500200064

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"fromUCS2",
    "str":"7E414F534E2D6587"
}

Parametry Obowiązkowe

Parametr Opis Typ
str Ciąg UCS2 do dekodowania string

Przykład Udanego Odzewu

{
    "success":true,
    "decoded":"繁体中文"
}

Wartości Udanego Odzewu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
decoded Dekodowany ciąg UCS2 w postaci znaków Unicode string

Błędy Funkcyjne API

Kod Błędu Opis Błędu
201 Nieprawidłowe Dane Wejściowe UCS2
Wskazówka: Również proszę spojrzeć na część o błędach ogólnych

Funkcja: normalizeNumber

Normalizes a cell phone number in loose format into international standard MSISDN format. For example from +1(712)543-2321 into +17125432321

Przykład POST/GET

username=xxx&password=yyyy&function=normalizeNumber&number=001(712)736-3423

Przykład JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"normalizeNumber",
    "number":"001(712)736-3423"
}

Parametry Obowiązkowe

Parametr Opis Typ
number The phone number to normalize. Loose format, e.g. 00491787654321, 0049(178)765-4321 etc. string

Przykład Udanego Odzewu

{
    "success":true,
    "number":"+17127363423",
    "countrycode":"US"
}

Wartości Udanego Odzewu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
number The normalized number in international MSISDN standard format. string
countrycode The corresponding country code (international two-character ISO format) string(2)

Błędy Funkcyjne API

Kod Błędu Opis Błędu
237 The number could not be normalized.

Odzewy Błędów

All API errors responses have a standardized JSON structure with a success, errorcode and errordescription attribute.

Przykład Odzewu Błędu

{
    "success":false,
    "errorcode":103,
    "errordescription":"Brak obowiązkowego parametru: senderid"
}

Wartości Odzewu Błędu

Klucz Opis Typ
success Wskazuje, czy żądanie mogło zostać przerobione z sukcesem czy nie boolean
errorcode Trzycyfrowy kod błędu string(3)
errordescription Opis błędu string

Błędy Funkcyjne API

Niektóre funkcje posiadają specyficzne kody błędów API, które są unikatowe dla tych szczególnych funkcji. Kody błędów mają w tym przypadku format 2xx. Dla indywidualnych kodów błędów proszę zajrzeć do dokumentacji funkcji.

Ogólne Błędy API

Dodatkowo oprócz błędów funkcyjnych, każde żądanie do API może wywołać ogólny błąd API o formacie kodu błędu 1xx.

Ogólne Kody Błędów

Kod Błędu Opis Błędu
101 Logowanie nie powiodło się. Błędne wprowadzenie nazwy użytkownika lub hasła.
102 To konto nie zostało jeszcze aktywowane.
103 Brak obowiązkowego parametru
104 Nieprawidłowe żądanie. Nie znaleziono danych GET, POST oraz JSON. Jeżeli próbujesz wysłać JSON, sprawdź proszę czy jest prawidłowo zakodowane.
105 Nieznana Funkcja
106 Odmowa dostępu
107 Ogólny Błąd API
108 Nieprawidłowa struktura żądania
109 Za mało dostępnych środków
Czy o czymś zapomnieliśmy? Masz jakieś pytania? Chcesz się podzielić dobrą radą czy powiedzieć nam, że czegoś tu brakuje? Jeżeli tak, daj nam znać!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Español
Français
Nederlands
Português
Руccкий
繁体中文