API HTTP Rest/JSON EZ4U SMS Gateway

Transcrição

1 v8 API HTTP Rest/JSON EZ4U SMS Gateway 1. Envio SMS Tópico s URL Base phonenumber Número(s) do(s) destinatário(s). Valor deverá iniciar-se por 91,92,93 ou 96 seguindo-se de 7 dígitos adicionais. Números separados por vírgula, messagetext Corpo do texto a enviar. 999 Caracteres disponíveis com substituição automática de caracteres específicos da língua portuguesa por congéneres do alfabeto inglês. Por cada bloco de 155 caracteres é utilizado 1 SMS (1º 160 caracteres) do pacote SMS em vigor. Determinados caracteres devido a restrições de codificação são contabilizados como 2. Bom dia. Estamos a experimentar o Sistema EZ4U. *startdate Especificação da data de início de envio e explicitação horária Formato pretendido: YYYY-MM-DD HH:MM:SS :33:00 *CC Especificação de centro de custos para categorização posterior 35 *alfasender *TTL Substituição de remetente por string alfanumérica de até 11 caracteres. Parâmetro relevante apenas para clientes com funcionalidade activa em conta. Não são admissíveis caracteres de acentuação apenas os contidos nos intervalos: [A-Z] [a-z] - [0-9] Período horário onde são admitidas retentativas. Valor inteiro entre 1 e 48. Aplicável apenas para chamadas com remetente alfanumérico activo. XPTO 24 *envio24 Activação/Desactivação da restrição de envio nocturno. 1 *Parâmetros opcionais *startdate Por defeito colocada a data de sistema actual; *alfasender Se não utilizado, SMS terá como remetente os primeiros 11 caracteres do username do cliente *TTL [48]- 48 Horas por defeito; *envio24 [1]- Por defeito não está habilitado o barramento de envio entre as 8h e as 23h; *CC [0001] Centro de Custos por defeito; Rua Guerra Junqueiro 417, Porto, Portugal info@ez4uteam.com

2 "Result":"OK", "LastSMSID": ,"NrOfInsertedMessages":2, "SMSIDs":["SMSID": , "SMSReceiverNumber": ,"SMSID": , " SMSReceiverNumber ": ] "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" "Result":"NOT OK", "ErrorCode":3, "ErrorDesc":"Error Creating Message: Inserted 2 of 5 Messages" "Result":"NOT OK", "ErrorCode":4, "ErrorDesc":"Error Retrieving smsid" "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" Chamada realizada com sucesso com indicação do número de SMS inseridos e lista de ids Erro de ligação ao sistema de envio Credenciais fornecidas não estão correctas Erro na criação de registos de SMS em sistema. Contactar a EZ4U se o problema persistir. Erro na obtenção do identificador do SMS Parâmetros obrigatórios não preenchidos na sua totalidade "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"messageText Parameter is not valid (max 999 char)" Máximo de 999 caracteres foi ultrapassado no texto do SMS a enviar. "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"startDate is not Valid (YYYY-MM-DD HH:MM:SS)" "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"alfaSender Parameter is not valid (max 11 char)" "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"phoneNumber is not Valid (9[ ]???????)" "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"CC Parameter is not valid (max 10 char)" "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"envio24h Parameter is not valid (0 1)" "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"TTL Parameter is not valid (min: 1, max: 48)" Data não se encontra no formato pretendido Máximo de 11 caracteres ultrapassado no parâmetro alfasender Formato do número de destino inválido Apenas 10 caracteres são permitidos na designação do centro de custos. Valor 0 para falso e 1 para verdadeiro são os únicos admissíveis para parâmetro envio24h Não foi introduzido para o parâmetro dentro do intervalo de horas possível para colocação do SMS em regime de retentativa [1-48] Serviço Base para Cliente sem Remetente Alfanumérico Ola%20Mundo&TTL=30 Serviço Base para Cliente com Remetente Alfanumérico, envio com Agendamento ( :51:00) e Envio Nocturno Ola%20Mundo&TTL=30&envio24h=1&alfaSender=XPTO&startDate= %2023:51:00 Serviço Base para Cliente sem Remetente Alfanumérico, envios Múltiplos e Agendados essagetext=ola%20mundo&ttl=30&envio24h=1&alfasender=xpto&startdate= %2023:51:00

3 2. Consulta Envio SMS Relatório de Entrega Individual Tópico URL Base smsid Identificador do SMS "Result": "OK", "MessageInfo": "PhoneNumber": " ", "CreationTimeStamp": " :59:00", "ProcessTimeStamp": " :59:10", "DeliveryStatus": "1" Chamada realizada com sucesso DeliveryStatus Codes: 0 Mensagem ainda não processada 1 Mensagem processada com sucesso e entregue 2 Mensagem processada e em entrega (pendente) 3 Mensagem processada sem sucesso (não entregue) 4 Mensagem processada e expirada (equipamento de destino sem rede, desligado, etc) "Result":"OK", "MessageList":[] "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" "Result":"NOT OK", "ErrorCode":3, "ErrorDesc":"SMS with ID = 120 not found" Chamada realizada com sucesso Filtro sem Resultados Erro de ligação ao sistema de envio Credenciais fornecidas não estão correctas SMS com ID especificado não foi encontrado "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" Parâmetros obrigatórios não preenchidos na sua totalidade Serviço Base

4 3. Consulta Envio SMS Relatório de Entrega Geral Tópico URL Base *startdate Data de início da pesquisa de SMS *enddate Data de fim da pesquisa *fromsmsid Identificador do SMS *Parâmetros opcionais *startdate [ ] Valor por defeito; * enddate [ ] Valor por defeito; * fromsmsid [0] Valor por defeito (deverá ser o valor da última pesquisa para obtenção de resultados paginados);

5 ] "Result": "OK", "MessageList": [ "smsid": " ", "PhoneNumber": " ", "CreationTimeStamp": " :00:46", "ProcessTimeStamp": " :01:00", "DeliveryStatus": "1", "smsid": " ", "PhoneNumber": " ", "CreationTimeStamp": " :13:42", "ProcessTimeStamp": " :13:52", "DeliveryStatus": "1",,, "smsid": " ", "PhoneNumber": " ", "CreationTimeStamp": " :13:42", "ProcessTimeStamp": " :13:55", "DeliveryStatus": "1" "smsid": " ", "PhoneNumber": " ", "CreationTimeStamp": " :59:00", "ProcessTimeStamp": " :59:10", "DeliveryStatus": "1" "smsid": " ", "PhoneNumber": " ", "CreationTimeStamp": " :59:00", "ProcessTimeStamp": " :59:12", "DeliveryStatus": "1", "smsid": " ", "PhoneNumber": " ", "CreationTimeStamp": " :59:00", "ProcessTimeStamp": " :59:11", "DeliveryStatus": "1" "Result":"OK", "MessageList":[] "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" Chamada realizada com sucesso Máximo de 250 resultados devolvidos DeliveryStatus Codes: 0 Mensagem ainda não processada 1 Mensagem processada com sucesso e entregue 2 Mensagem processada e em entrega (pendente) 3 Mensagem processada sem sucesso (não entregue) Chamada realizada com sucesso Filtro sem Resultados Erro de ligação ao sistema de envio

6 "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" Credenciais fornecidas não estão correctas "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" Serviço Base

7 4. Gestão de Listas - Criação Tópico URL Base *listtitle Nome/Título da Lista ListaTeste *listdescription da Lista *Parâmetros opcionais *listtitle [DefaultTitle] Valor por defeito; *listdescription [DefaultDescription] Valor por defeito; A lista dos melhores contactos "Result":"OK", "ListID":179 "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" "Result":"NOT OK", "ErrorCode":3, "ErrorDesc":"Error Creating new List MSGDEBUG "Result":"NOT OK", "ErrorCode":4, "ErrorDesc":"Error Creating new List 0 "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"listTitle Parameter is not valid (max 100 char)" Chamada realizada com sucesso com devolução de ID de nova lista Erro no acesso ao sistema SMS Guardar mensagem de DEBUG Erro na introdução de lista em sistema Máximo de 100 caracteres ultrapassado no Título da Lista "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"listDescription Parameter is not valid (max 100 char)" Máximo de 100 caracteres ultrapassado na da Lista sta%20dos%20melhores%20contactos

8 5. Gestão de Listas - Eliminação Tópico URL Base listid Identificador da lista. Número Inteiro. 100 "Result":"OK" "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" "Result":"NOT OK", "ErrorCode":3, "ErrorDesc":" Error Deleting List MSGDEBUG "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" Lista eliminada com sucesso Erro no acesso ao sistema SMS Guardar mensagem de DEBUG

9 6. Gestão de Listas Adição de Contacto a Lista Tópico URL Base listid Identificador da lista. Número Inteiro. 100 contactlist "Result":"OK", "NrOfInsertedContacts":3 Lista de números de contacto separados por ;. Versão actual da API admite apenas números da rede móvel portuguesa. Valor deverá iniciar-se por 91,92,93 ou 96 seguindo-se de 7 dígitos adicionais. "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" "Result":"NOT OK", "ErrorCode":3, "List ID 100 not found ; ; Todos os contactos inseridos com sucesso na lista especificada com devolução de contagem visando confirmação final. A lista não foi encontrada em sistema "Result":"NOT OK", "ErrorCode":4, "ErrorDesc":"Error Creating new List: Inserted 2 of 3 Contacts" Contactos foram parcialmente rejeitados. A chamada devolve número de aceites VS total de introduzidos "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" 7; ;

10 7. Gestão de Listas Remoção de Contacto de Lista Tópico URL Base listid Identificador da lista. Número Inteiro. 100 contactnumber Número de contacto "Result":"OK", " NrOfDeletedSMS":1 "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" Todos os contactos inseridos com sucesso na lista especificada com devolução de contagem visando confirmação final

11 8. Gestão de Agendamentos Agendamentos de Campanhas Tópico URL Base messagetext Corpo do texto a enviar. 999 Caracteres disponíveis com substituição automática de caracteres específicos da língua portuguesa por congéneres do alfabeto inglês. Por cada bloco de 155 caracteres é utilizado 1 SMS do pacote SMS (1º bloco é de 160 caracteres) em vigor. Determinados caracteres devido a restrições de codificação são contabilizados como 2. Bom dia. Estamos a experimentar o Sistema EZ4U. listoflists Conjunto de listas a serem alvo de campanha separadas por ; 211;177 *alfasender *envio24h Substituição de remetente por string alfanumérica de até 11 caracteres. Parâmetro relevante apenas para clientes com funcionalidade activa em conta. Não são admissíveis caracteres de acentuação apenas os contidos nos intervalos: [A-Z] [a-z] - [0-9] Activação/Desactivação da restrição de envio nocturno. Esta opção sobrepõe-se ao agendamento XPTO 0 *removeduplicates Caso a lista ou o conjunto de listas incluem destinatários com 2 ou mais ocorrências, colocando este parâmetro a 1, não serão agendados mais que 1 SMS por destinatário no âmbito da campanha respectiva. 1 *campaigntitle Título da Campanha. Não tem qualquer impacto no envio do SMS. Máximo de 100 caracteres. Campanha Promocional *campaigndescription da Campanha. Não tem qualquer impacto no envio do SMS. *TTL Período horário onde são admitidas retentativas. Valor inteiro entre 1 e 48. Aplicável apenas para chamadas com remetente alfanumérico activo. Desconto para clientes 8 *startdate Especificação da data de início de envio e explicitação horária Formato pretendido: YYYY-MM-DD HH:MM:SS :33:00 *Parâmetros opcionais *startdate Por defeito colocada a data de sistema actual somada de 24 horas; *alfasender Se não utilizado, SMS terá como remetente os primeiros 11 caracteres do username do cliente *TTL 48 Horas por defeito; *envio24 Por defeito não são enviados SMS entre as 8h e as 23h *campaigntitle Se não especificado: Default Title *campaigndescription Se não especificado: Default Description *removeduplicates Por defeito são removidos os duplicados: 1 Nota: O total de destinatários admissível na versão corrente da API é de

12 "Result":"OK", "campaignid":303 "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" "Result":"NOT OK", "ErrorCode":3, "ErrorDesc":"Not All Lists belong to this Account [EZ4U]" "Result":"NOT OK", "ErrorCode":4, "ErrorDesc":"Error Creating Campaign" "Result":"NOT OK", "ErrorCode":5, "ErrorDesc":"Error Updating Campaign Final Volume" "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" Campanha inserida com sucesso em sistema com devolução do respectivo identificador. Uma ou mais listas referenciadas não pertence ao utilizador colocado nas credenciais. Erro ao criar campanha. Erro na determinação de total de destinatários da campanha. "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"messageText Parameter is not valid (max 999 char)" Máximo de 999 caracteres foi ultrapassado no texto do SMS a enviar. "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"alfaSender Parameter is not valid (max 11 char)" Máximo de 11 caracteres ultrapassado no parâmetro alfasender "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"campaignTitle Parameter is not valid (max 100 char)" Máximo de 100 caracteres ultrapassado no Título da Campanha "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"campaignDescription Parameter is not valid (max 100 char)" "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"listOfLists is not Valid (listid_1;listid_2;...;listid_n)" "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"startDate is not Valid (>= :00)" "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"startDate is not Valid (YYYY-MM-DD HH:MM:SS)" "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"envio24h Parameter is not valid (0 1)" "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"envio24h Parameter is not valid (0 1)" "Result":"NOT OK", "ErrorCode":-2, "ErrorDesc":"TTL Parameter is not valid (min: 1, max: 48)" Máximo de 100 caracteres ultrapassado na da Campanha Especificação imprecisa da lista de listas. Foi solicitado o agendamento de campanha para período não permitido pelo sistema. Data deverá ser posterior à indicada. Data não se encontra no formato pretendido Valores admitidos diferente de 0 (inactivo) ou 1(activo) para manutenção ou remoção de duplicados Valor 0 para falso e 1 para verdadeiro são os únicos admissíveis para parâmetro envio24h Não foi introduzido para o parâmetro dentro do intervalo de horas possível para colocação do SMS em regime de retentativa [1-48] emoveduplicates=1&campaigntitle=teste&campaigndescription=oportunidades%20%c3%9anicas&startdate= %2005:24:21&TTL=3&alfaSender=XPTO&messageText=Bem%20vindo%20ao%20sistema%20EZ4U

13 9. Gestão de Agendamentos Remoção de Campanhas Tópico URL Base campaignid Identificador da campanha respectiva 134 Nota: A remoção de campanhas apenas produz efeitos no respectivo agendamento de SMS em caso de enquadramento temporal devidamente contextualizado. P.e. caso seja dada indicação de remoção de campanha em data posterior ao início do seu envio, apenas será removido o registo de campanha respectivo e não os SMSs subjacentes. "Result":"OK", "NrOfDeletedSMS":213 "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" "Result":"NOT OK", "ErrorCode":3, "ErrorDesc":"Error Deleting Campaign [ ]" "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" A campanha foi removida com indicação do número de SMSs removidos do agendamento em sistema. A campanha especificada não foi encontrada em sistema

14 10. Bidireccionalidade Lista de Mensagens Recebidas Tópico URL Base fromsmsid* Identificador do SMS startdate* Data de início da pesquisa de SMS enddate* Data de fim da pesquisa onlyunread* Flag para filtro de SMS não lidos 0 ou 1 markasread* Flag para update de SMS como lidos 0 ou 1 *Parâmetros opcionais * fromsmsid Por defeito SMID >= 0 (sem filtro); * startdate Por defeito ; * enddate Por defeito ; * onlyunread Por defeito 0 devolve todas as mensagens lidas ou não lidas; * markasread Por defeito 1 assinala todas as mensagens consultadas como lidas; "Result": "OK", "MessageList": [ "messageid": "218", ], "messagerawid": "17bf699e-ac8b-4b0b-8a89-b251d8d38eac", "rawtimestamp": " :56:52", "inserttimestamp": " :56:55", "sendernumber": " ", "messagebody": "TESTE de recepcao EZ4U", "receivernumber": " ", "isprocessed": "1", "isread": "1" "nrofupdatedmessages": 0 "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" "Result":"NOT OK", "ErrorCode":3, "ErrorDesc":"User does not exist or does not have the service enabled." Lista de Mensagens em sistema que respeitam os critérios de pesquisa e indicação de número de mensagens que foram marcadas como lidas. Utilizador não existe ou não tem o serviço activo

15 "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" 25&endDate= &onlyUnRead=0&markAsRead=1

16 11. Bidireccionalidade Actualização de Estado de Mensagem Tópico URL Base fromsmsid* Identificador do SMS startdate* Data de início da pesquisa de SMS enddate* Data de fim da pesquisa readstatus Valor do estado da mensagem lida ou não lida 0 ou 1 *Parâmetros opcionais * fromsmsid Por defeito SMID >= 0 (sem filtro); * startdate Por defeito ; * enddate Por defeito ; "Result": "OK", "nrofupdatedmessages": 1 "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" "Result":"NOT OK", "ErrorCode":3, "ErrorDesc":"User does not exist or does not have the service enabled." "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" Indicação de Sucesso de Operação com indicação do número de mensagens efectivamente actualizadas. Utilizador não existe ou não tem o serviço activo &endDate= &readStatus=1

17 12. Dados Utilizador Consulta de Saldo Disponível Tópico URL Base "Result": "OK", "AvailableCreditsInfo": [ ] "AvailableCredits": "UnLimited" "Result": "OK", "AvailableCreditsInfo": [ ] "Acquired": "1000", "Consumed": "4", "ConsumedLandLine": "0", "AvailableCreditsWithoutScheduled": "996", "Scheduled": "3", "AvailableCredits": "993" "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" "Result":"NOT OK", "ErrorCode":3, "ErrorDesc":"User does not exist or does not have the service enabled." "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" Indicação de Sucesso de Operação com indicação de crédito ilimitado Indicação de Sucesso de Operação com indicação de: Total de Créditos Adquiridos; Total de Créditos já Consumidos; Consumos Discriminados Rede Fixa; Créditos Disponíveis sem contabilização de mensagens agendadas; Total Mensagens Agendadas; Total Créditos efectivamente Disponíves Utilizador não existe ou não tem o serviço activo

18 13. Eliminação SMS Individuais Agendados Ainda não enviados Tópico URL Base SMSID Identificador da mensagem a eliminar "Result":"OK", "NrOfDeletedSMS":1 "Result":"OK", "NrOfDeletedSMS":0 "Result":"NOT OK", "ErrorCode":1, "ErrorDesc":"Error while connecting to DB" "Result":"NOT OK", "ErrorCode":2, "ErrorDesc":"Wrong Credentials" "Result":"NOT OK", "ErrorCode":-1, "ErrorDesc":"Mandatory Parameters are not set" Indicação de Sucesso de Operação com informação de número de SMS efectivamente eliminadas. Indicação de Conclusão de operação sem que qualquer mensagem tenha sido eliminada mensagem já enviada ou SMSID não encontrado ou SMSID não associado ao utilizador especificado.