Español

Interfaz de Programación de Aplicaciones (API SMS)

Por favor asegúrate de echar un vistazo al Cómo antes de ir demasiado lejos en cualquier tema. ¡Gracias!

API para Enviar SMS

Función: sendSms

Envía GSM y Unicode Mensajes de texto. Concatena automáticamente en formato largo hasta cinco mensajes (765 caracteres).
Retorna un objeto JSON confirmando la solicitud (o declarando un error).

PUBLICAR/OBTENER Ejemplo

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

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

Parámetro Descripción Tipo
number El número de teléfono celular en formato internacional. Por ejemplo: 49123456789 ó +49123456789 ó 0049123456789 string
message El cuerpo del mensaje. My-Cool-SMS detecta la codificación de la entrada y procesa los mensajes según sea GSM o Unicode.
Puedes usar el parámetro opcional Unicode para forzar una codificación particular. Si Unicode se define verdadero, el mensaje será enviado como Unicode y el parámetro del mensaje debe ser provisto en Notación Unicode UCS2. Si Unicode se define falso, el mensaje será enviado como GSM y el parámetro del mensaje debe contener caracteres únicamente del alfabeto GSM7.
Los mensajes largos son concatenados automáticamente. Máximo 765 caracteres para mensajes GSM o 335 para Unicode..
Por favor nota que siempre debes usar el parámetro Unicode cuando envíes solicitudes GET.
string
Consejo: Averigua más sobre GSM, Unicode y UCS2.

Parámetros Opcionales

Parámetro Descripción Tipo
unicode Fuerza a decodificar Unicode o GSM en el mensaje. Si se define verdadero, el parámetro del mensaje debe ser enviado en notación UCS2. Si se define falso, el parámetro del mensaje debe contener caracteres del alfabeto GSM7 únicamente.
Si no se define o se define en NULO, My-Cool-SMS detectará la codificación de la entrada.
boolean
senderid El número de teléfono celular en formato internacional, por ejemplo +44123456789 o ID de remitente alfanumérica de hasta 11 caracteres, por ejemplo: Compañía string
scheduletime Envía el mensaje a una hora específica. Usa formato ATOM y zona horaria, i.e..: "2011-04-17T17:59:36.67+08" o "2011-04-17 17:59:36-02" timestamp with timezone
callbackurl URL de callback para recibir actualizaciones de estado y reportes de entrega para este mensaje. Por ejemplo: http://www.myserver.com/callback.php string
Consejo: Averigua más sobre callbacks de reporte de entrega.

Ejemplo de Respuesta Exitosa

{
    "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 Respuesta Exitosa

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no boolean
smsid ID única para este mensaje. Se debe almacenar en cliente final y usado como referencia para reportes de entrega. string(32)
body El cuerpo del mensaje en Unicode string
bodyucs2 El cuerpo del mensaje en notación bytecode UCS2 string
bodygsm7 El cuerpo del mensaje en notación bytecode GSM7 (o NULO si el mensaje fue enviado como Unicode) string || NULL
senderid Indicates the sender id used for the sent message. string
senderidenabled Indica si el número destino soporta ID de remitente dinámico. boolean
unicode Indica si el mensaje fue enviado como Unicode o GSM. boolean
numchars Indica cuántos caracteres contenía el mensaje integer
escapenumchars Indica cuántos caracteres se necesita para una secuencia de escape (se cuentan como dos caracteres en GSM) integer
smscount Indica si el mensaje estaba concatenado en formato largo y provee el número final de mensajes usados. integer
charge Indica cuánto fue cobrado de tu cuenta por este mensaje. float
balance Saldo restante en tu cuenta 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 callback a los que las actualizaciones de estado y reportes de entrega para este mensaje serán enviados. string || NULL

Errores de Función Específica API

Código del Error Descripción del Error
210 El número parece inválido
211 El parámetro del mensaje está vacío
212 El parámetro del mensaje es demasiado largo
213 El parámetro Unicode se define para forzar Unicode pero el parámetro del mensaje no fue enviado en notación UCS2.
214 El parámetro Unicode se define para forzar GSM pero el parámetro del mensaje fue enviado con notación UCS2
215 El parámetro unicode se define para forzar GSM pero el parámetro del mensaje contiene caracteres fuera del alfabeto 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 Identificaciones del remitente en Shortcode no están permitidas.
218 El parámetro callbackurl parece inválido
219 La hora de programación parece inválido. Usa formato ATOM y zona horaria, i.e.: "2011-04-17T17:59:36.67+08" o "2011-04-17 17:59:36-02"
Consejo: Mira también la sección acerca de errores genéricos

API de SMS Entrantes

Callback: pushIncomingSms

My-Cool-SMS atrae automáticamente los datos del mensaje a tu servidor si una URL de callback para tu número está definida en tu configuración de bandeja de entrada. Puedes editar el URL para callback en tu configuración de bandeja de entrada vía la interfaz web de My-Cool-SMS.

Ejemplo de callback

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"
}
Consejo: Revisa aquí para más información sobre cómo manejar callbacks JSON.

Valores de Callback

Clave Descripción Tipo
from La identificación del remitente con el que el mensaje fue enviado. Puede ser un número en formato internacional o un texto alfanumérico. string
fromcountrycode Contiene el código de país ISO de dos letras del remitente si el parámetro es un número. Contiene NULO si el parámetro es alfanumérico. string(2) || NULL
to El número al que el mensaje fue enviado (tu número telefónico virtual). string
unicode Indica si el mensaje fue enviado en Unicode o GSM. boolean
smscount Indica si el mensaje estaba concatenado en formato largo y provee el número final de mensajes usados. integer
body El cuerpo del mensaje en Unicode string
bodyucs2 El cuerpo del mensaje en notación bytecode UCS2 string
bodygsm7 El cuerpo del mensaje en notación bytecode GSM7 (o NULO si el mensaje fue enviado como Unicode) string
numchars Indica cuántos caracteres contenía el mensaje integer
escapenumchars Indica cuántos caracteres se necesita para una secuencia de escape (se cuentan como dos caracteres en GSM) integer
cost Indica cuánto fue cobrado de tu cuenta por este mensaje. float

Función: 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.

PUBLICAR/OBTENER Ejemplo

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

Ejemplo de JSON

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

Parámetros Obligatorios

Parámetro Descripción Tipo

Parámetros Opcionales

Parámetro Descripción 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]

Ejemplo de Respuesta Exitosa

{
   "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 Respuesta Exitosa

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no 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

Errores de Función Específica API

Código del Error Descripción del Error
232 El 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 de límite inválido
236 Invalid order parameter
242 No virtual numbers found.
Consejo: Mira también la sección acerca de errores genéricos

API para revisión de Saldo

Función: getBalance

Retorna un objeto JSON conteniendo el saldo restante en tu cuenta (o declarando un error).

PUBLICAR/OBTENER Ejemplo

username=xxx&password=yyyy&function=getBalance

Ejemplo de JSON

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

Ejemplo de Respuesta Exitosa

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

Valores de Respuesta Exitosa

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no boolean
balance Saldo restante en Euros float

Reporte de Entrega API

Hay dos formas para recibir reportes de entrega de My-Cool-SMS. Puedes consultar el servidor My-Cool-SMS con getDeliveryReport o recibir callbacks HTTP en una URL en tu servidor con pushDeliveryReport. Por favor nota que los reportes de entrega para correos solo están disponibles vía getDeliveryReport.

Función: getDeliveryReport

Retorna un reporte de entrega para un solo mensaje (enviado con sendSms) o un grupo de correo (enviado con sendMailing). Si un reporte de entrega para grupo de correo es solicitado (definiendo el parámetro opcional groupkey en verdadero), el objeto de retorno puede contener un resumen (por defecto) o reportes de entrega individuales por cada uno de los destinatarios (configurando el parámetro opcional mailingdetails en verdadero)

PUBLICAR/OBTENER Ejemplo

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

Ejemplo de JSON

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

Parámetros Obligatorios

Parámetro Descripción Tipo
id Identificación de referencia. Una identificación del mensaje (como lo retornó sendSms) o una clave de grupo de correo (como lo retornó sendMailing).
Si una clave de grupo es usada, el parámetro opcional groupkey debe ser definido verdadero.
string

Parámetros Opcionales

Parámetro Descripción Tipo
groupkey Definir en verdadero si una clave de grupo fue provista en el parámetro id y quieres que el reporte para una lista de correo (en vez de un solo mensaje) sea retornado. Por defecto está en falso. string
mailingdetails Definir en verdadero si quieres un reporte de entrega separado por cada destinatario de una lista adicionalmente al resumen. Por defecto está en falso. string

Ejemplo de Respuesta Exitosa: groupkey=false (Por defecto)

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

Valores de Respuesta Exitosa: groupkey=false (Por defecto)

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no boolean
smsid La ID del mensaje asociado al reporte de entrega string
status Indica el estado de este mensaje string
Consejo: Da una mirada aquí para más información sobre códigos de estado.

Ejemplo de Respuesta Exitosa: 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
}
Consejo: Da una mirada aquí para más información sobre códigos de estado.

Ejemplo de Respuesta Exitosa: 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"
        }, 
        (...)
    ]
}
Consejo: Da una mirada aquí para más información sobre códigos de estado.

Errores de Función Específica API

Código del Error Descripción del Error
223 Identificación del mensaje desconocida
224 Clave de Grupo desconocida
Consejo: Mira también la sección acerca de errores genéricos

Función: getDeliveryReports

Returns delivery reports for a list of messages.

Ejemplo de JSON

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

Parámetros Obligatorios

Parámetro Descripción Tipo
ids An array of sms ids to perform the delivery status lookup for. array[]

Ejemplo de Respuesta Exitosa:

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

Valores de Respuesta Exitosa:

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no 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
Consejo: Da una mirada aquí para más información sobre códigos de estado.

Errores de Función Específica API

Código del Error Descripción del Error
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.
Consejo: Mira también la sección acerca de errores genéricos

Función: getRecentReports

Retorna un objeto JSON con reportes de entrega para los mensajes enviados más recientemente.

PUBLICAR/OBTENER Ejemplo

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

Ejemplo de JSON

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

Parámetros Obligatorios

Parámetro Descripción Tipo
limit Indica cuántos reportes deben ser retornados integer

Ejemplo de Respuesta Exitosa

{
   "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 Respuesta Exitosa

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no boolean
number El número de destino string
senderid La ID del remitente con la que se envió el mensaje string
body El cuerpo del mensaje en Unicode string
bodyucs2 El cuerpo del mensaje en notación bytecode UCS2 string
bodygsm7 El cuerpo del mensaje en notación bytecode GSM7 (o NULO si el mensaje fue enviado como Unicode) string
unicode Indica si el mensaje fue enviado como Unicode o GSM. boolean
timesent Hora a la cual el mensaje se envió timestamp with time zone
status Indica el estado de este mensaje string
Consejo: Da una mirada aquí para más información sobre códigos de estado.

Errores de Función Específica API

Código del Error Descripción del Error
225 Parámetro de límite inválido
Consejo: Mira también la sección acerca de errores genéricos

Callback: pushDeliveryReport

My-Cool-SMS automáticamente atrae un reporte de entrega a tu servidor si el parámetro callbackurl se define al enviar vía la función sendSms. El callback se hace como una solicitud JSON de datos sin procesar.

Ejemplo de callback

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"
}
Consejo: Revisa aquí para más información sobre cómo manejar callbacks JSON.

Valores de Callback

Clave Descripción Tipo
smsid Identificación única y referencia para el mensaje. La variable smsid fue retornada en la respuesta exitosa de la función sendSms string(32)
status Indica el estado de este mensaje string

Referencia de estado

Status Descripción
SMS_STATUS_QUEUED En cola - Este mensaje está actualmente en cola y no ha sido enviado aún.
SMS_STATUS_AT_CARRIER En el operador - El mensaje ha sido enviado al operador de la red y debe aparecer como 'entregado' tan pronto como llegue al teléfono destino.
Por favor nota que en algunas ocasiones los operadores no proveen un reporte de entrega. En ese caso el mensaje continuará apareciendo como 'en el operador', aunque ya haya sido entregado exitosamente.
SMS_STATUS_DELIVERY_DELAYED Entrega Retrasada - La entrega del mensaje se ha retrasado
SMS_STATUS_DELIVERED Enviado - El mensaje fue entregado exitosamente al número objetivo
SMS_STATUS_BOUNCED Devuelto - El mensaje ha sido devuelto por la red. Los posibles motivos son: número de teléfono celular o identificación del remitente inválidos, teléfono destino fuera del alcance de la red por demasiado tiempo, o congestiones de red en el operador.
SMS_STATUS_EXPIRED Expiró - Este mensaje ha expirado y no pudo ser entregado.
Este problema usualmente sucede si el teléfono celular destino se ha desconectado o ha salido del alcance de la red por un largo periodo de tiempo.
SMS_STATUS_ERROR Falló - La entrega ha fallado (no se ha cobrado por este mensaje).
Los posibles motivos para la entrega fallida son: My-Cool-SMS no conoce la red a la cual pertenece el número telefónico (por favor contacta a Soporte si sabes con certeza que el número es correcto) o un error temporal de la red.

Función: 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.

PUBLICAR/OBTENER Ejemplo

username=xxx&password=yyy&function=getOutboundSms

Ejemplo de JSON

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

Parámetros Obligatorios

Parámetro Descripción Tipo

Parámetros Opcionales

Parámetro Descripción 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

Ejemplo de Respuesta Exitosa

{
   "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 Respuesta Exitosa

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no 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

Errores de Función Específica API

Código del Error Descripción del Error
234 The provided thresholdid is invalid
235 Parámetro de límite inválido
236 Invalid order parameter
Consejo: Mira también la sección acerca de errores genéricos

Lista de Correo API

Función: sendMailing

Envía un mensaje a toda una lista de correo. Consejo: Puedes crear y administrar listas de correo en tu interfaz web de My-Cool-SMS.
Retorna un objeto JSON confirmando la solicitud (o declarando un error).

PUBLICAR/OBTENER Ejemplo

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

Ejemplo de JSON

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

Parámetros Obligatorios

Parámetro Descripción Tipo
uniqueid Identificación única de la lista de correo. Encontrarás dichas identificaciones en las interfaces de administración de lista de correo en el sitio web. string
message El cuerpo del mensaje. My-Cool-SMS detecta la codificación de la entrada y procesa los mensajes según sea GSM o Unicode.
Puedes usar el parámetro opcional Unicode para forzar una codificación particular. Si Unicode se define verdadero, el mensaje será enviado como Unicode y el parámetro del mensaje debe ser provisto en Notación Unicode UCS2. Si Unicode se define falso, el mensaje será enviado como GSM y el parámetro del mensaje debe contener caracteres únicamente del alfabeto GSM7.
Los mensajes largos son concatenados automáticamente. Máximo 765 caracteres para mensajes GSM o 335 para Unicode..
Por favor nota que siempre debes usar el parámetro Unicode cuando envíes solicitudes GET.
string
Consejo: Averigua más sobre GSM, Unicode y UCS2.

Parámetros Opcionales

Parámetro Descripción Tipo
unicode Fuerza a decodificar Unicode o GSM en el mensaje. Si se define verdadero, el parámetro del mensaje debe ser enviado en notación UCS2. Si se define falso, el parámetro del mensaje debe contener caracteres del alfabeto GSM7 únicamente.
Si no se define o se define en NULO, My-Cool-SMS detectará la codificación de la entrada.
boolean
senderid El número de teléfono celular en formato internacional, por ejemplo +44123456789 o ID de remitente alfanumérica de hasta 11 caracteres, por ejemplo: Compañía string
scheduletime Envía el mensaje a una hora específica. Usa formato ATOM y zona horaria, i.e..: "2011-04-17T17:59:36.67+08" o "2011-04-17 17:59:36-02" timestamp with time zone
Consejo: Averigua más sobre callbacks de reporte de entrega.

Ejemplo de Respuesta Exitosa

{
    "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 Respuesta Exitosa

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no boolean
groupkey Clave de referencia única para este correo. Se debe almacenar en cliente final y es usado como referencia para reportes de entrega. string(32)
body El cuerpo del mensaje en Unicode string
bodyucs2 El cuerpo del mensaje en notación bytecode UCS2 string
bodygsm7 El cuerpo del mensaje en notación bytecode GSM7 (o NULO si el mensaje fue enviado como Unicode) string || NULL
uniqueid string(7)
senderid Indica si el número destino soporta ID de remitente dinámico. boolean
unicode Indica si el mensaje fue enviado como Unicode o GSM. boolean
numchars Indica cuántos caracteres contenía el mensaje integer
escapenumchars Indica cuántos caracteres se necesita para una secuencia de escape (se cuentan como dos caracteres en GSM) integer
smscount Indica si el mensaje estaba concatenado en formato largo y provee el número final de mensajes usados. integer
subscribers Número de suscriptores a los que se envió el mensaje. integer
charge Indica cuánto fue cobrado de tu cuenta por este mensaje. float
balance Saldo restante en tu cuenta float

Errores de Función Específica API

Código del Error Descripción del Error
220 La identificación no está asociada con ninguna de tus listas de correo
Consejo: Mira también la sección acerca de errores genéricos

Función: addSubscriber

Inserta un nuevo suscriptor a la lista de correo. Actualiza un suscriptor si el número enviado ya existe en la lista de correo destino.
Retorna un objeto JSON confirmando la solicitud (o declarando un error).

PUBLICAR/OBTENER Ejemplo

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

Ejemplo de JSON

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

Parámetros Obligatorios

Parámetro Descripción Tipo
number El número del suscriptor en formato internacional. Por ejemplo: 49123456789 ó +49123456789 ó 0049123456789 string
uniqueid Identificación única de la lista de correo. Encontrarás dichas identificaciones en las interfaces de administración de lista de correo en el sitio web. string

Parámetros Opcionales

Parámetro Descripción Tipo
title Título del suscriptor varchar(16)
firstname Nombre del suscriptor varchar(32)
lastname Apellido del suscriptor varchar(32)
company Compañía del suscriptor varchar(64)

Ejemplo de Respuesta Exitosa

{
    "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 Respuesta Exitosa

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no boolean
number Número telefónico normalizado del nuevo suscriptor string
title Título del nuevo suscriptor string
firstname Nombre del nuevo suscriptor string
lastname Apellido del nuevo suscriptor string
company Compañía del nuevo suscriptor string
subscribercost Costo por mensaje a este suscriptor float
senderidenabled Indica si el suscriptor tiene soporte para identificación del remitente boolean
maxcharsgsm Indica cuántos caracteres soporta el suscriptor para mensajes GSM integer
maxcharsunicode Indica cuántos caracteres soporta el suscriptor para mensajes Unicode integer
countrycode El código de país del suscriptor (formato estándar ISO de dos letras) string(2)
mailinglistcost El nuevo costo total por enviar correo a esta lista float
mailinglistsubscribers El nuevo número de suscriptores en esta lista de correo integer

Errores de Función Específica API

Código del Error Descripción del Error
221 La entrada para {field} es demasiado larga.
Consejo: Mira también la sección acerca de errores genéricos

Función: updateSubscriber

Ver Función: addSubscriber

Función: deleteSubscriber

Remueve un suscriptor de la lista de correo (usando el número telefónico como referencia).
Retorna un objeto JSON confirmando la solicitud (o declarando un error).

PUBLICAR/OBTENER Ejemplo

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

Ejemplo de JSON

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

Parámetros Obligatorios

Parámetro Descripción Tipo
uniqueid Identificación única de la lista de correo. Encontrarás dichas identificaciones en las interfaces de administración de lista de correo en el sitio web. string
number El número de suscriptores a eliminar de la lista de correo string

Ejemplo de Respuesta Exitosa

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

Valores de Respuesta Exitosa

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no boolean
number El número telefónico normalizado del suscriptor eliminado string
mailinglistcost El nuevo costo total por enviar correo a esta lista float
mailinglistsubscribers El nuevo número de suscriptores en esta lista de correo integer

Errores de Función Específica API

Código del Error Descripción del Error
220 La identificación no está asociada con ninguna de tus listas de correo
222 No hay suscriptores con ese número telefónico en esta lista de correo
Consejo: Mira también la sección acerca de errores genéricos

Utilidades API

Función: doHlrLookup

Efectúa una búsqueda de Registro de Ubicación Base (HLR) y retorna el MSC, MCC, MNC e INSI del número, así como información del nombre de la red, si se encuentra en 'roaming' o si ha sido trasladado a otra red.
Consejo: Averigua más sobre HLR, IMSI, MCC, MNC y MSC.

Ejemplo de JSON

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

Parámetros Obligatorios

Parámetro Descripción Tipo
number El número para realizar la búsqueda en HLR en formato internacional. Por ejemplo: 49123456789 ó +49123456789 ó 0049123456789 string

Ejemplo de Respuesta Exitosa

{
    "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 Respuesta Exitosa

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no boolean
status Indica el estado de la búsqueda. Por favor recurre a la tabla de referencia de estado de HLR para ver detalles. string
number El número para el que se efectuó la búsqueda en HLR. string
imsi Identidad Internacional del Abonado a un Móvil (IMSI). Identificación única asociada con el número objetivo. string
mcc El Código de País de Móvil (MCC) string
mnc El Código de Operador de Móvil (MNC), que puede ser o de 2 dígitos (estándar europeo) o de 3 dígitos (estándar norteamericano). string
msin Número de Identificación de Suscripción de Móvil (MSIN) en la red de la base de clientes. string
servingmsc La Central de Conmutación Móvil (MSC) que es responsable de la asignación de ruta al mensaje. string
servinghlr El Registro de Ubicación Base (HLR) al que el número objetivo está asociado. string
originalnetworkname La red móvil a la que pertencece esté número (o pertenecía originalmente si es un número trasladado). string
originalnetworkprefix El prefijo de red la móvil al que pertencece esté número (o pertenecía originalmente si es un número trasladado). string
originalcountryname El país al que pertenece este número. string
originalcountrycode El código de país ISO de dos caracteres al que pertenece este número string
originalcountryprefix El prefijo del país al que pertenece este número string
roamingcountryname El país en el que este número está actualmente 'roaming' string
roamingcountrycode El código de país ISO de dos caracteres en el que este número está actualmente 'roaming' string
roamingcountryprefix El prefijo del país en el que este número está actualmente 'roaming' string
roamingnetworkname The network the cell phone is currently roaming with string
portednetworkname The network the number has been ported to string
isported Indica si este número ha sido trasladado boolean
iscorrect Indica si este número es válido boolean
isroaming Indica si este número está actualmente 'roaming' (en otro país) boolean
charge El cobro hecho por la búsqueda en HLR (0.01 EUR) numeric
Consejo: Averigua más sobre HLR, IMSI, MCC, MNC y MSC.

Errores de Función Específica API

Código del Error Descripción del Error
210 El número parece inválido
226 Búsqueda en HLR falló. No hay ningún cobro.
Consejo: Mira también la sección acerca de errores genéricos

HLR Referencia de estado

Status Descripción
HLR_STATUS_UNKNOWN_NUMBER Este número no existe o no pudo ser localizado en ningún HLR. El mensaje no llegará.
HLR_STATUS_OK Este número existe y la búsqueda en HLR fue exitosa. El mensaje llegará.
HLR_STATUS_NOT_OK Este número está fuera de la red por mucho tiempo o fue desactivado por el proveedor de red móvil. El mensaje no llegará.
HLR_STATUS_FAILED La búsqueda en HLR falló. No hay ningún cobro.
HLR_STATUS_AWAITING_RESPONSE Awaiting response from HLR.

Función: toUCS2

UCS2 codifica una cadena Unicode dada
Importante: toUCS2 requiere una solicitud JSON

Ejemplo de JSON

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

Parámetros Obligatorios

Parámetro Descripción Tipo
number El número para realizar la búsqueda en HLR en formato internacional. Por ejemplo: 49123456789 ó +49123456789 ó 0049123456789 string

Parámetros Opcionales

Parámetro Descripción Tipo

Ejemplo de Respuesta Exitosa

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

Valores de Respuesta Exitosa

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no boolean
ucs2 La cadena enviada en notación UCS2 string

Errores de Función Específica API

Ninguno
Consejo: Mira también la sección acerca de errores genéricos

Función: fromUCS2

Decodifica una cadena UCS2 dada

PUBLICAR/OBTENER Ejemplo

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

Ejemplo de JSON

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

Parámetros Obligatorios

Parámetro Descripción Tipo
str La cadena UCS2 a decodificar string

Ejemplo de Respuesta Exitosa

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

Valores de Respuesta Exitosa

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no boolean
decoded La cadena UCS2 decodificada en Unicode string

Errores de Función Específica API

Código del Error Descripción del Error
201 Entrada UCS2 Inválida
Consejo: Mira también la sección acerca de errores genéricos

Función: normalizeNumber

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

PUBLICAR/OBTENER Ejemplo

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

Ejemplo de JSON

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

Parámetros Obligatorios

Parámetro Descripción Tipo
number The phone number to normalize. Loose format, e.g. 00491787654321, 0049(178)765-4321 etc. string

Ejemplo de Respuesta Exitosa

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

Valores de Respuesta Exitosa

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no boolean
number The normalized number in international MSISDN standard format. string
countrycode The corresponding country code (international two-character ISO format) string(2)

Errores de Función Específica API

Código del Error Descripción del Error
237 The number could not be normalized.

Respuestas de Error

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

Ejemplo de Respuesta de Error

{
    "success":false,
    "errorcode":103,
    "errordescription":"Parámetro obligatorio faltante: senderid"
}

Valores de Respuesta de Error

Clave Descripción Tipo
success Indica si la solicitud pudo ser procesada correctamente o no boolean
errorcode Código de error de tres dígitos string(3)
errordescription Descripción del error string

Errores de Función Específica API

Algunas funciones tienen códigos de error API específicos que son únicos a esa función particular. Los códigos de error tienen el formato 2xx en ese caso. Por favor refiérete a la documentación de la función para códigos individuales de error.

Errores Genéricos API

Adicionalmente a los errores específicos de función, cualquier solicitud al API puede resultar en un error genérico API con formato de código de error 1xx.

Códigos Genéricos de Error

Código del Error Descripción del Error
101 Ingreso falló. Usuario o contraseña incorrectos.
102 Esta cuenta no se ha activado aún.
103 Parámetro obligatorio faltante
104 Solicitud inválida. No se encontró datos de GET, POST y JSON sin procesar. Si estás intentando enviar JSON, por favor revisa si está codificado correctamente.
105 Función Desconocida
106 Permiso Denegado
107 Error Genérico de API
108 Estructura de solicitud inválida
109 No hay suficiente crédito
¿Olvidamos algo? ¿Tienes preguntas? ¿Tienes alguna sugerencia o algo que deberíamos agregar aquí? Si así es, háznoslo saber!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Français
Nederlands
Polski
Português
Руccкий
繁体中文