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,
    "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	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

callbackurl	URL de retorno à qual actualizações de status e relatórios de entrega desta mensagem serão enviados.	string

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 incoming 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

virtualnumber	The virtual number for which sms text messages should be fetched	string

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)

Exemplo de resposta de sucesso

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "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",
         "numchars":16,
         "escapechars":0,
         "smscount":1
      }
   ]
}

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

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: 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.

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.

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

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!

		Deutsch

		English

		Español

		Français

		Nederlands

		Polski

		Руccкий

		繁体中文

Application Programming Interface (SMS API)

Precisas de ajuda?

Enviar API de mensagem

Função: sendSms

Exemplo de POST/GET

Exemplo de JSON

Parâmetros mandatários

Parâmetros opcionais

Exemplo de resposta de sucesso

Valores de resposta de sucesso

Erros específicos da função API

Receber API de mensagem

Chamada de volta: pushIncomingSms

Exemplo de retorno

Valores de retorno

Função: getIncomingSms

Exemplo de POST/GET

Exemplo de JSON

Parâmetros mandatários

Parâmetros opcionais

Exemplo de resposta de sucesso

Valores de resposta de sucesso

Erros específicos da função API

API de verificar balanço

Função: getBalance

Exemplo de POST/GET

Exemplo de JSON

Exemplo de resposta de sucesso

Valores de resposta de sucesso

API do relatório de entrega

Função: getDeliveryReport

Exemplo de POST/GET

Exemplo de JSON

Parâmetros mandatários

Parâmetros opcionais

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

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

Exemplo de resposta de sucesso: groupkey=true

Exemplo de resposta de sucesso: groupkey=true&mailingdetails=true

Erros específicos da função API

Função: getRecentReports

Exemplo de POST/GET

Exemplo de JSON

Parâmetros mandatários

Exemplo de resposta de sucesso

Valores de resposta de sucesso

Erros específicos da função API

Chamada de volta: pushDeliveryReport

Exemplo de retorno

Valores de retorno

Referência de status

API da lista de correio

Função: sendMailing

Exemplo de POST/GET

Exemplo de JSON

Parâmetros mandatários

Parâmetros opcionais

Exemplo de resposta de sucesso

Valores de resposta de sucesso

Erros específicos da função API

Função: addSubscriber

Exemplo de POST/GET

Exemplo de JSON

Parâmetros mandatários

Parâmetros opcionais

Exemplo de resposta de sucesso

Valores de resposta de sucesso

Erros específicos da função API

Função: updateSubscriber

Função: deleteSubscriber

Exemplo de POST/GET

Exemplo de JSON

Parâmetros mandatários

Exemplo de resposta de sucesso

Valores de resposta de sucesso

Erros específicos da função API

API de utilidades

Função: doHlrLookup

Exemplo de JSON

Parâmetros mandatários