Português

Application Programming Interface (SMS API)

Por favor, assegura-te de consultar Como Fazer antes de ir a fundo em qualquer coisa. Obrigado!

Enviar API de mensagem

Função: sendSms

Envia mensagens GSM e Unicode. Concatena longas mensagens automaticamente, até cinco (765 caracteres).
Retorna um objecto JSON a confirmar a requisição (ou exibir um erro).

Exemplo de 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

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo
number O número de telemóvel em formato internacional. Por exemplo: 49123456789 ou +49123456789 ou 0049123456789 string
message O corpo da mensagem. My-Cool-SMS auto-detecta o código de entrada e processa a mensagem conforme GSM ou Unicode.
Podes usar parâmetro Unicode opcional para obrigar um código particular. Se Unicode for true, a mensagem será enviada como Unicode e o parâmetro da mensagem deverá ser em notação Unicode UCS2. Se Unicode for false, a mensagem será enviada como GSM e o parâmetro da mensagem deve contém somente caracteres GSM7.
Mensagens longas são concatenadas automaticamente. Máximo de 765 caracteres para mensagens GSM ou 335 para Unicode.
Nota que deves sempre usar parâmetro Unicode quando enviar requisições GET.
string
Dica: Mais sobre GSM, Unicode e UCS2.

Parâmetros opcionais

Parâmetro Descrição Tipo
unicode Obriga código Unicode ou GSM na mensagem. Se true, o parâmetro da mensagem deve ser em notação UCS2. Se falso, o parâmetro da mensagem deve ser apenas em alfabeto GSM7.
Se não determinado ou NULL, My-Cool-SMS detectará o código automaticamente.
boolean
senderid Número do telemóvel em formato internacional, por exemplo:+44123456789 ou ID alfanumérica do remetente até 11 caracteres, por exemplo: Companhia string
scheduletime Envia a mensagem num horário específico. Use formato e fuso horário ATOM, isto é: "2011-04-17T17:59:36.67+08" ou "2011-04-17 17:59:36-02" timestamp with timezone
callbackurl Retorna URL para receber actualizações de status e relatórios de entrega a esta mensagem. Por exemplo: http://www.myserver.com/callback.php string
Dica: Mais sobre retorno de relatórios de entrega.

Exemplo de resposta de sucesso

{
    "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"
}

Valores de resposta de sucesso

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. boolean
smsid ID única para esta mensagem. Deve ser armazenada no cliente e usada como referência para relatórios de entrega string(32)
body O corpo da mensagem em Unicode string
bodyucs2 O corpo da mensagem em notação UCS2 bytecode string
bodygsm7 O corpo da mensagem em notação GSM7 bytecode (ou NULL se a mensagem foi enviada como Unicode) string || NULL
senderid Indicates the sender id used for the sent message. string
senderidenabled Indica se o número de destino suporta ID do remetente dinâmica boolean
unicode Indica se a mensagem foi enviada como Unicode ou GSM boolean
numchars Indica quantos caracteres a mensagem contém integer
escapenumchars Indica quantos caracteres de escape foi preciso adicionar (e incluir na contagem de caracteres em GSM) integer
smscount Indica se a mensagem foi concatenada numa mensagem longa e provê o número de mensagens usadas integer
charge Indica o quanto foi descontado de tua conta para esta mensagem float
balance Saldo restante em tua conta 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 URL de retorno à qual actualizações de status e relatórios de entrega desta mensagem serão enviados. string || NULL

Erros específicos da função API

Código de erro Descrição de erro
210 O número parece inválido
211 O parâmetro está vazio
212 O parâmetro da mensagem é muito longo
213 O parâmetro Unicode está determinado para obrigar Unicode, mas o parâmetro da mensagem não foi submetido em notação UCS2.
214 O parâmetro Unicode está determinado para obrigar GSM, mas o parâmetro da mensagem foi submetido em notação UCS2.
215 O parâmetro Unicode está determinado para obrigar GSM, mas o parâmetro da mensagem contém caracteres fora do alfabeto GM7.
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 ID do remetente resumida não é permitida
218 O parâmetro callbackurl parece inválido.
219 O horário agendado parece inválido. Use formato e fuso horário ATOM, isto é: "2011-04-17T17:59:36.67+08" ou "2011-04-17 17:59:36-02"
Dica: Veja também a secção de erros genéricos

Receber API de mensagem

Chamada de volta: pushIncomingSms

My-Cool-SMS automaticamente envia os dados da mensagem ao teu servidor se um URL de retorno para teu número for determinado nos ajustes em tua caixa de entrada. Podes editar teu URL de retorno nos ajustes em tua caixa de entrada via interface My-Cool-SMS.

Exemplo de retorno

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"
}
Dica: Clique aqui para mais informações sobre como lidar com retornos JSON.

Valores de retorno

chave Descrição Tipo
from A ID do remetente que enviou a mensagem. Pode ser um número em formato internacional ou uma ID do remetente alfanumérica string
fromcountrycode Contém os dois caracteres do código do país do assinante no formato ISO, se o parâmetro 'de' é um número. Contém NULL se o parâmetro for alfanumérico. string(2) || NULL
to O número de destino da mensagem (teu número de telefone virtual). string
unicode Indica se a mensagem foi enviada em Unicode ou GSM. boolean
smscount Indica se a mensagem foi concatenada numa mensagem longa e provê o número de mensagens usadas integer
body O corpo da mensagem em Unicode string
bodyucs2 O corpo da mensagem em notação UCS2 bytecode string
bodygsm7 O corpo da mensagem em notação GSM7 bytecode (ou NULL se a mensagem foi enviada como Unicode) string
numchars Indica quantos caracteres a mensagem contém integer
escapenumchars Indica quantos caracteres de escape foi preciso adicionar (e incluir na contagem de caracteres em GSM) integer
cost Indica o quanto foi descontado de tua conta para esta mensagem float

Função: 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.

Exemplo de POST/GET

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

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo

Parâmetros opcionais

Parâmetro Descrição Tipo
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]

Exemplo de resposta de sucesso

{
   "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"
      }
   ]
}

Valores de resposta de sucesso

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. 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

Erros específicos da função API

Código de erro Descrição de erro
232 O número parece inválido
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 Parâmetro limite inválido
236 Invalid order parameter
242 No virtual numbers found.
Dica: Veja também a secção de erros genéricos

API de verificar balanço

Função: getBalance

Retorna um objecto JSON a conter o saldo restante de tua conta (ou a declarar um erro).

Exemplo de POST/GET

username=xxx&password=yyyy&function=getBalance

Exemplo de JSON

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

Exemplo de resposta de sucesso

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

Valores de resposta de sucesso

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. boolean
balance Saldo restante em Euros float

API do relatório de entrega

Há duas maneiras de receber relatórios de entrega do My-Cool-SMS. Podes nomear o servidor do My-Cool-SMS com getDeliveryReport ou receber retorno HTTP na URL de teu servidor com pushDeliveryReport. Nota que relatórios de entrega para correios são disponíveis apenas via getDeliveryReport.

Função: getDeliveryReport

Retorna um relatório de entrega para uma mensagem (enviada com sendSms) ou uma lista de correio (enviada com sendMailing). Se um relatório de entrega duma lista de correio é requerido (definindo o parâmetro opcional groupkey para true), o objecto de retorno pode conter um resumo (padrão) ou relatórios de entrega individuais para cada destinatário (a ajustar o parâmetro opcional mailingdetails para true)

Exemplo de POST/GET

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

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo
id ID de referência. Ou uma ID da mensagem (como retornado por sendSms) ou uma chave de grupo de correio (como retornado por sendMailing).
Se uma chave de grupo é usada, o parâmetro opcional groupkey deve ser definido como true.
string

Parâmetros opcionais

Parâmetro Descrição Tipo
groupkey Defina como true se uma chave de grupo foi provida no parâmetro ID e queres o relatório de entrega para uma lista (ao invés duma mensagem) seja retornado. Padrão é false. string
mailingdetails Defina como true se queres um relatório de entrega separado para cada destinatário duma lista, em adição ao resumo. Padrão é false string

Exemplo de resposta de sucesso: groupkey=false (Padrão)

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

Valores de resposta de sucesso: groupkey=false (Padrão)

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. boolean
smsid A ID da mensagem associada ao relatório de entrega string
status indica o status desta mensagem string
Dica: Clica aquipara mais informações sobre códigos de status.

Exemplo de resposta de sucesso: 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
}
Dica: Clica aquipara mais informações sobre códigos de status.

Exemplo de resposta de sucesso: 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"
        }, 
        (...)
    ]
}
Dica: Clica aquipara mais informações sobre códigos de status.

Erros específicos da função API

Código de erro Descrição de erro
223 ID de mensagem desconhecida
224 Chave de grupo desconhecida
Dica: Veja também a secção de erros genéricos

Função: getDeliveryReports

Returns delivery reports for a list of messages.

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo
ids An array of sms ids to perform the delivery status lookup for. array[]

Exemplo de resposta de sucesso:

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

Valores de resposta de sucesso:

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. 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
Dica: Clica aquipara mais informações sobre códigos de status.

Erros específicos da função API

Código de erro Descrição de erro
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.
Dica: Veja também a secção de erros genéricos

Função: getRecentReports

Retorna um objecto JSON com o relatório de entrega para as mais recentes mensagens enviadas.

Exemplo de POST/GET

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

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo
limit Indica quantos relatórios devem retornar integer

Exemplo de resposta de sucesso

{
   "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"
      },
      (...)
   ]
}

Valores de resposta de sucesso

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. boolean
number O número de destino string
senderid A ID do remetente que enviou a mensagem string
body O corpo da mensagem em Unicode string
bodyucs2 O corpo da mensagem em notação UCS2 bytecode string
bodygsm7 O corpo da mensagem em notação GSM7 bytecode (ou NULL se a mensagem foi enviada como Unicode) string
unicode Indica se a mensagem foi enviada como Unicode ou GSM boolean
timesent Horário de envio da mensagem timestamp with time zone
status indica o status desta mensagem string
Dica: Clica aquipara mais informações sobre códigos de status.

Erros específicos da função API

Código de erro Descrição de erro
225 Parâmetro limite inválido
Dica: Veja também a secção de erros genéricos

Chamada de volta: pushDeliveryReport

My-Cool-SMS automaticamente envia um relatório de entrega ao teu servidor se o parâmetro callbackurl for determinado quando do envio via função sendSms. O retorno é enviado como requisição dado não tratado JSON.

Exemplo de retorno

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"
}
Dica: Clique aqui para mais informações sobre como lidar com retornos JSON.

Valores de retorno

chave Descrição Tipo
smsid ID única e referência para a mensagem. A smsid foi retornada na resposta de sucesso da função sendSms string(32)
status indica o status desta mensagem string

Referência de status

Status Descrição
SMS_STATUS_QUEUED Em fila - Esta mensagem está em fila e ainda não foi enviada.
SMS_STATUS_AT_CARRIER Em andamento - A mensagem foi enviada à operadora e deve aparecer como 'entregue' tão breve seja entregue.
Por favor, note que nem todas as operadoras retornam um relatório de entrega. Nestes casos, a mensagem continuará a ser exibida como 'em andamento', mesmo se já entregue com sucesso.
SMS_STATUS_DELIVERY_DELAYED Entrega atrasada - A entrega da mensagem foi atrasada
SMS_STATUS_DELIVERED Entregue - A mensagem foi entrega ao número de destino com sucesso.
SMS_STATUS_BOUNCED Retornada - A mensagem foi retornada pela rede de destino. Possíveis motivos são: número de telemóvel ou id de usuário inválido(s), o telemóvel de destino está fora de área ou a rede está congestionada.
SMS_STATUS_EXPIRED Expirada - Esta mensagem expirou e não pôde ser entregue.
Este problema usualmente acontece se o telemóvel de destino estiver desligado ou fora da área de cobertura por muito tempo.
SMS_STATUS_ERROR Erro - A entrega falhou (não pagarás por esta mensagem).
Possíveis motivos são: My-Cool-SMS não sabe a que operadora o telemóvel pertence (por favor, contacte o suporte se estás certo de que o número de destino está correto) ou erro temporário na rede.

Função: 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.

Exemplo de POST/GET

username=xxx&password=yyy&function=getOutboundSms

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo

Parâmetros opcionais

Parâmetro Descrição Tipo
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

Exemplo de resposta de sucesso

{
   "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"
      }
   ]
}

Valores de resposta de sucesso

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. 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

Erros específicos da função API

Código de erro Descrição de erro
234 The provided thresholdid is invalid
235 Parâmetro limite inválido
236 Invalid order parameter
Dica: Veja também a secção de erros genéricos

API da lista de correio

Função: sendMailing

Envia uma mensagem a toda uma lista de correio. Dica: Podes criar e administrar listas de correio na interface do site My-Cool-SMS.
retorna um objecto JSON a confirmar a requisição (ou a declarar um erro).

Exemplo de POST/GET

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

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo
uniqueid A lista de correio não tem uma ID única. Encontras tuas ID únicas nas interfaces de administração das listas de correio no site. string
message O corpo da mensagem. My-Cool-SMS auto-detecta o código de entrada e processa a mensagem conforme GSM ou Unicode.
Podes usar parâmetro Unicode opcional para obrigar um código particular. Se Unicode for true, a mensagem será enviada como Unicode e o parâmetro da mensagem deverá ser em notação Unicode UCS2. Se Unicode for false, a mensagem será enviada como GSM e o parâmetro da mensagem deve contém somente caracteres GSM7.
Mensagens longas são concatenadas automaticamente. Máximo de 765 caracteres para mensagens GSM ou 335 para Unicode.
Nota que deves sempre usar parâmetro Unicode quando enviar requisições GET.
string
Dica: Mais sobre GSM, Unicode e UCS2.

Parâmetros opcionais

Parâmetro Descrição Tipo
unicode Obriga código Unicode ou GSM na mensagem. Se true, o parâmetro da mensagem deve ser em notação UCS2. Se falso, o parâmetro da mensagem deve ser apenas em alfabeto GSM7.
Se não determinado ou NULL, My-Cool-SMS detectará o código automaticamente.
boolean
senderid Número do telemóvel em formato internacional, por exemplo:+44123456789 ou ID alfanumérica do remetente até 11 caracteres, por exemplo: Companhia string
scheduletime Envia a mensagem num horário específico. Use formato e fuso horário ATOM, isto é: "2011-04-17T17:59:36.67+08" ou "2011-04-17 17:59:36-02" timestamp with time zone
Dica: Mais sobre retorno de relatórios de entrega.

Exemplo de resposta de sucesso

{
    "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
}

Valores de resposta de sucesso

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. boolean
groupkey Chave de referência única para este correio. Deve ser armazenada no cliente e usada como referência para relatórios de entrega string(32)
body O corpo da mensagem em Unicode string
bodyucs2 O corpo da mensagem em notação UCS2 bytecode string
bodygsm7 O corpo da mensagem em notação GSM7 bytecode (ou NULL se a mensagem foi enviada como Unicode) string || NULL
uniqueid string(7)
senderid Indica se o número de destino suporta ID do remetente dinâmica boolean
unicode Indica se a mensagem foi enviada como Unicode ou GSM boolean
numchars Indica quantos caracteres a mensagem contém integer
escapenumchars Indica quantos caracteres de escape foi preciso adicionar (e incluir na contagem de caracteres em GSM) integer
smscount Indica se a mensagem foi concatenada numa mensagem longa e provê o número de mensagens usadas integer
subscribers O número de destinatários da mensagem integer
charge Indica o quanto foi descontado de tua conta para esta mensagem float
balance Saldo restante em tua conta float

Erros específicos da função API

Código de erro Descrição de erro
220 A ID única não está associada com nenhuma de tuas listas de correio
Dica: Veja também a secção de erros genéricos

Função: addSubscriber

Insere um novo assinante a uma lista de correio existente. Actualiza um assinante se o número já existe na lista de interesse.
retorna um objecto JSON a confirmar a requisição (ou a declarar um erro).

Exemplo de POST/GET

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

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo
number O número do assinante no formato internacional. Por exemplo: 49123456789 ou +49123456789 ou 0049123456789 string
uniqueid A lista de correio não tem uma ID única. Encontras tuas ID únicas nas interfaces de administração das listas de correio no site. string

Parâmetros opcionais

Parâmetro Descrição Tipo
title Título do assinante varchar(16)
firstname Nome do assinante varchar(32)
lastname Apelido do assinante varchar(32)
company Companhia do assinante varchar(64)

Exemplo de resposta de sucesso

{
    "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
}

Valores de resposta de sucesso

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. boolean
number Normalizar telemóvel do novo assinante string
title Título do novo assinante string
firstname Nome do novo assinante string
lastname Apelido do novo assinante string
company Companhia do novo assinante string
subscribercost Custo por mensagem para o assinante float
senderidenabled Indica se o novo assinante suporta a ID do remetente boolean
maxcharsgsm Indica quantos caracteres o assinante suporta para mensagens GSM integer
maxcharsunicode Indica quantos caracteres o assinante suporta para mensagens Unicode integer
countrycode O código do país do assinante (duas letras no formato padrão ISO) string(2)
mailinglistcost Novo custo total para correio desta lista float
mailinglistsubscribers Novo número de assinantes nesta lista integer

Erros específicos da função API

Código de erro Descrição de erro
221 A informação para {field} é muito longa.
Dica: Veja também a secção de erros genéricos

Função: updateSubscriber

Veja Função: addSubscriber

Função: deleteSubscriber

Remover um assinante da lista de correio (a usar o número de telefone como referência)
Retorna um objecto JSON a confirmar a requisição (ou a declarar um erro).

Exemplo de POST/GET

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

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo
uniqueid A lista de correio não tem uma ID única. Encontras tuas ID únicas nas interfaces de administração das listas de correio no site. string
number Número de assinantes a serem removidos da lista de correio string

Exemplo de resposta de sucesso

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

Valores de resposta de sucesso

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. boolean
number Número de telefone normalizado do assinante removido string
mailinglistcost Novo custo total para correio desta lista float
mailinglistsubscribers Novo número de assinantes nesta lista integer

Erros específicos da função API

Código de erro Descrição de erro
220 A ID única não está associada com nenhuma de tuas listas de correio
222 Não há assinante com este número de telefone nesta lista de correio
Dica: Veja também a secção de erros genéricos

API de utilidades

Função: doHlrLookup

Realiza uma busca HLR (Home Location Register) e retorna os números MSC, MCC, MNC, INSI bem como informações sobre o nome da rede, se o número está em deslocamento e se foi movido para outra rede.
Dica: Saiba mais sobre HLR, IMSI, MCC, MNC e MSC.

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo
number O número para realizar a busca HLR em formato internacional. Por exemplo: 49123456789 ou +49123456789 ou 0049123456789 string

Exemplo de resposta de sucesso

{
    "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
}

Valores de resposta de sucesso

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. boolean
status Indica o status da busca. Consulte a tabela de referência de status HLR para detalhes. string
number O número para qual a busca HLR foi efetuada. string
imsi IMSI (International Mobile Subscriber Identity). Identificação única associada ao número de destino. string
mcc O MCC (Mobile Country Code) string
mnc O MNC (Mobile Network Code), o qual pode ser dois dígitos (Padrão Europeu) ou três dígitos (Padrão Norte-Americano) string
msin O MSIN ( Mobile Subscription Identification Number) dentro da base de clientes da rede. string
servingmsc O MSC (Mobile Switching Center) responsável por encaminhar a mensagem. string
servinghlr O HLR (Home Location Register) com o qual o número de destino está associado. string
originalnetworkname A rede de telefonia à qual este número pertence (ou pertencia originalmente, se este um número foi movido) string
originalnetworkprefix O prefixo da rede de telefonia à qual este número pertence (ou pertencia originalmente, se este um número foi movido) string
originalcountryname O país ao qual este número pertence. string
originalcountrycode Os dois caracteres ISO do código de país ao qual este número pertence string
originalcountryprefix O prefixo do país ao qual este número pertence. string
roamingcountryname O país no qual este número está em deslocamento. string
roamingcountrycode Os dois caracteres ISO do código de país no qual este número está em deslocamento. string
roamingcountryprefix O prefixo do país no qual este número está em deslocamento. string
roamingnetworkname The network the cell phone is currently roaming with string
portednetworkname The network the number has been ported to string
isported Indica se este número foi movido boolean
iscorrect Indica se este é um número válido boolean
isroaming Indica se o número está em deslocamento (em outro país) boolean
charge A taxa cobrada pela busca HLR (0.01 EUR) numeric
Dica: Saiba mais sobre HLR, IMSI, MCC, MNC e MSC.

Erros específicos da função API

Código de erro Descrição de erro
210 O número parece inválido
226 A busca HLR falhou. Sem cobranças.
Dica: Veja também a secção de erros genéricos

HLR Referência de status

Status Descrição
HLR_STATUS_UNKNOWN_NUMBER Este número não existe ou não pôde ser localizado em nenhum HLR. A mensagem não chegará.
HLR_STATUS_OK Este número existe e a busca HLR foi bem sucedida. A mensagem chegará.
HLR_STATUS_NOT_OK Este número está fora da rede por muito tempo ou foi desabilitado pela operadora de telefonia. A mensagem não chegará.
HLR_STATUS_FAILED A busca HLR falhou. Sem cobranças.
HLR_STATUS_AWAITING_RESPONSE Awaiting response from HLR.

Função: toUCS2

O UCS2 codifica a string Unicode dada
Importante: toUCS2 requer uma requisição JSON.

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo
number O número para realizar a busca HLR em formato internacional. Por exemplo: 49123456789 ou +49123456789 ou 0049123456789 string

Parâmetros opcionais

Parâmetro Descrição Tipo

Exemplo de resposta de sucesso

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

Valores de resposta de sucesso

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. boolean
ucs2 A string submetida em notação UCS2 string

Erros específicos da função API

Nenhum
Dica: Veja também a secção de erros genéricos

Função: fromUCS2

A string UCS2 descodificada

Exemplo de POST/GET

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

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo
str A string UCS2 para decodificação string

Exemplo de resposta de sucesso

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

Valores de resposta de sucesso

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. boolean
decoded A string UCS2 descodificada em Unicode string

Erros específicos da função API

Código de erro Descrição de erro
201 Entrada UCS2 inválida
Dica: Veja também a secção de erros genéricos

Função: normalizeNumber

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

Exemplo de POST/GET

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

Exemplo de JSON

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

Parâmetros mandatários

Parâmetro Descrição Tipo
number The phone number to normalize. Loose format, e.g. 00491787654321, 0049(178)765-4321 etc. string

Exemplo de resposta de sucesso

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

Valores de resposta de sucesso

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. boolean
number The normalized number in international MSISDN standard format. string
countrycode The corresponding country code (international two-character ISO format) string(2)

Erros específicos da função API

Código de erro Descrição de erro
237 The number could not be normalized.

Erros de resposta

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

Exemplo de resposta errada

{
    "success":false,
    "errorcode":103,
    "errordescription":"Parâmetro obrigatório ausente: senderid"
}

Valores de resposta errada

chave Descrição Tipo
success Indica se a requisição foi obtida com sucesso ou não. boolean
errorcode Código de erro de três dígitos string(3)
errordescription A descrição do erro string

Erros específicos da função API

Algumas funções têm erros de API específicos e que são únicos a esta função. Códigos de erro tem o formato 2xx neste caso. Por favor, observe a documentação da função para os códigos de erro individuais.

Erros de API genéricos

Adicionalmente aos erros específicos de função, qualquer requisição à API pode resultar num erro genérico de API, com código de erro no formato 1xx.

Código de erro genérico

Código de erro Descrição de erro
101 Falha de conexão. Nome de usuário ou senha errados
102 Esta conta ainda não foi activada.
103 Parâmetro obrigatório ausente
104 Requisição inválida. Sem GET, POST e dado não tratado JSON. Se estás a tentar o envio de JSON, por favor, verifica se está propriamente codificado.
105 Função desconhecida
106 Permissão negada
107 Erro API genérico
108 Estrutura de requisição inválida
109 Créditos insuficientes
Nós esquecemos de algo? Tens alguma pergunta? Tens alguma sugestão ou algo que deveríamos adicionar aqui? Se sim, avise-nos!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Español
Français
Nederlands
Polski
Руccкий
繁体中文