Solução de SMS Personalizada

Integrando uma solução/provedor de SMS personalizado como parte da sua API de Operador

Fast Tracks suporta uma variedade de provedores de SMS, se o seu negócio precisa de um provedor que não está na lista de provedores suportados, então você pode construir esta API.

Serviço de SMS Fast Track

O serviço de SMS Fast Track pode ser configurado para enviar solicitações de SMS para os endpoints da API de Operador listados abaixo, o que permite que o Operador gerencie o provedor de SMS. Ele suporta o envio de mensagens e a obtenção do status de entrega. O envio está disponível tanto para solicitações de SMS únicas quanto em lote.
Os seguintes endpoints podem ser construídos como parte da sua API de Operador:

⬆️ POST /channels/sms/single

⬆️ POST /channels/sms/batch

O Operador pode então encaminhar essas solicitações para o provedor de SMS para processamento e responder com as respectivas respostas.
O formato da API e as respostas precisam ser formatados conforme descrito abaixo
É importante que os dados "meta" descritos abaixo sejam enviados de volta para o Fast Track, seja via Webhook ou Polling, para que os dados de conversão possam ser armazenados corretamente. Por favor, consulte os exemplos mostrados e as tabelas abaixo para mais esclarecimentos.

Pré-Requisitos

  1. Informe ao Fast Track se algum limite de taxa deve ser considerado. (Se você planeja implementar limitação de taxa, por favor, contate o Fast Track antes, para que possamos orientá-lo sobre a implementação suportada)
  2. Informe ao Fast Track se algum máximo em lote deve ser considerado.
  3. Forneça ao Fast Track quaisquer credenciais específicas para os provedores integrados (se necessário)
  4. Os formatos de SMS suportados são GSM7 & USC2

Enviar SMS (Único)

Uma solicitação de envio de SMS único conterá os dados de cada SMS individual em solicitações separadas para a API.

Implementação do Endpoint

Implemente o endpoint no formato abaixo para suportar o envio de SMS único através da API.
⬆️ POST <url-do-endpoint-da-api-operadora>/channels/sms/single

Cabeçalho da Solicitação

O cabeçalho da solicitação enviada contém um "X-Api-Key", que é um token necessário para autenticar as chamadas da API no endpoint. Este token precisa ser passado para o Fast Track para fazer essas solicitações.

Esquema do Corpo da Solicitação

Consulte o seguinte exemplo de uma solicitação de SMS único enviada pelo Fast Track. A descrição de cada campo está listada na tabela abaixo.
ChaveTipoDescrição
activity.id
inteiro
Um identificador único do SMS
activity.brand_id
inteiro
O identificador único da marca no Fast Track
activity.user_id
string
O identificador único do jogador
activity.activity_id
inteiro
O identificador único da atividade configurada no Fast Track
activity.action_group_id
inteiro
O identificador único do grupo de ação de onde o SMS se origina no Fast Track
activity.trigger_hash
string
Hash de gatilho
activity.action_id
inteiro
O identificador único da ação individual do Fast Track
content
string
O conteúdo do SMS
recipient
string
O número do destinatário
sender_name
string
O nome do remetente do SMS
provider_name
string
O nome do provedor integrado
encoding
string
Tipo de codificação do SMS. Pode ser "auto", "gsm7" ou "usc2"

Respostas Esperadas

A API de Operador deve retornar as respostas para cada mensagem SMS individual respectivamente para evitar o armazenamento não relacionado de dados de SMS.

Sucesso Resposta JSON HTTP 200-299

O "sms_id" será um identificador único gerado pela API de Operador que permite ao Fast Track identificar aquela mensagem SMS em particular para atualizar seu status de entrega após ser enviada.

ERRO Resposta JSON Não-200

Respostas errôneas são tipicamente associadas com códigos de status HTTP 400s ou 500s. A resposta deve conter um campo "error" com uma descrição para mostrar o que deu errado e ajudar na solução de problemas.
As respostas da API de Operador serão tratadas de maneira diferente dependendo da classe do código de status HTTP. A tabela abaixo fornece um resumo de como os status HTTP são tratados separadamente.
Códigos de Status HTTPDescrição
200-299
Entregue com Sucesso. Fast Track reconhecerá a mensagem e começará a processar a próxima mensagem na fila.
400-499
Não Sucesso. Ao receber esse erro, Fast Track pulará a mensagem SMS. Além disso, enviará seus dados para Ações Falhas, se o serviço estiver ativado.
500 ou qualquer outro código de status que não esteja listado acima
Não Sucesso. O serviço falha e o Fast Track continuará tentando até que uma resposta 200 seja recebida.

SMS em Lote

SMS em lote ajuda a processar uma coleção de SMS em uma única solicitação para a API. O número de mensagens dentro da solicitação em lote é limitado por uma quantidade inteira definida na configuração e enviada dentro de um intervalo de tempo configurado, mesmo quando o lote ainda não está cheio.

Implementação do Endpoint

Implemente o endpoint no formato abaixo para suportar o envio de SMS em lote através da API.
⬆️ POST <url-do-endpoint-da-api-operadora>/channels/sms/batch

Cabeçalho da Solicitação

O cabeçalho da solicitação enviada contém um "X-Api-Key", que é um token necessário para autenticar as chamadas da API no endpoint. Este token precisa ser passado para o Fast Track para fazer essas solicitações.

Esquema do Corpo da Solicitação

Aqui está um exemplo do formato esperado ao agrupar as solicitações. É semelhante à solicitação de SMS único, mas as solicitações são armazenadas em um array, uma após a outra.
ChaveTipoDescrição
activity.id
inteiro
Um identificador único do SMS
activity.brand_id
inteiro
O identificador único da marca no Fast Track
activity.user_id
string
O identificador único do jogador
activity.activity_id
inteiro
O identificador único da atividade configurada no Fast Track
activity.action_group_id
inteiro
O identificador único do grupo de ação de onde o SMS se origina no Fast Track
activity.trigger_hash
string
Hash de gatilho
activity.action_id
inteiro
O identificador único da ação individual do Fast Track
content
string
O conteúdo do SMS
recipient
string
O número do destinatário
sender_name
string
O nome do remetente do SMS
provider_name
string
O nome do provedor integrado
encoding
string
Tipo de codificação do SMS. Pode ser "auto", "gsm7" ou "usc2"

Respostas Esperadas

As respostas abaixo devem ser retornadas pela API de Operador.

Sucesso Resposta JSON HTTP 200

O "id" inicialmente enviado na solicitação será devolvido na resposta como "id". Isso é necessário para ajudar o Fast Track a identificar a mensagem SMS individual na solicitação inicial em lote. O "sms_id" será um identificador único gerado pela API de Operador, que o Fast Track usará para identificar a mensagem SMS relacionada ao atualizar seu status. Se alguma das categorias listadas ("sucesso", "falha" ou "fatal") não tiver um SMS associado, elas devem ser retornadas como um array vazio.
A solicitação precisa incluir uma das propriedades sucesso, falha ou fatal
O fluxo lógico de como a resposta será tratada é muito semelhante ao modo como os códigos de status HTTP são tratados no SMS Único. A única diferença é que a resposta com um código de status 200 será tratada, de acordo com a categoria da mensagem na resposta.
Categoria da RespostaDescrição
sucesso
Entregue com Sucesso. Fast Track reconhecerá a mensagem e começará a processar o próximo lote na fila.
falha
Não Sucesso. Ao receber esse erro, Fast Track pulará a mensagem SMS. Além disso, enviará seus dados para Ações Falhas, se o serviço estiver ativado.
fatal
Mensagens serão reenviadas
Quaisquer outras mensagens que não estiverem listadas na resposta serão reenviadas.

ERRO (resposta não 500) Resposta JSON

Fast Track só suportará o Código de Status HTTP 200 no agrupamento. Toda a solicitação em lote será reenviada se qualquer outro código de status for recebido com a seguinte resposta.
​
​

Dados de Conversão

Nós suportamos a recuperação de dados de conversão através de webhook.

Webhook

Fast Track fornecerá uma URL de Webhook & X-API-KEY que você pode enviar os dados de conversão para cada SMS.
O X-API-KEY fornecido é esperado como um cabeçalho na solicitação.
É importante que os dados de "atividade" que são fornecidos pelo Fast Track na solicitação de Envio de SMS sejam enviados de volta
POST {url-fornecida}/sms/conversion
ChaveTipoDescrição
activity.id
inteiro
Um identificador único do SMS
activity.brand_id
inteiro
Um identificador único da marca no Fast Track
activity.user_id
string
Identificador do jogador
activity.activity_id
inteiro
Identificador da atividade configurada no Fast Track
activity.action_group_id
inteiro
Identificador do grupo de ação de onde o SMS se origina no Fast Track
activity.trigger_hash
string
Hash de gatilho
activity.action_id
inteiro
O identificador único da ação individual do Fast Track
sms_id
string
O identificador único do SMS
delivery_status
string
Status de entrega do SMS
Status (delivery_status)Descrição
entregue
Mensagem entregue com sucesso ao destinatário final
não entregue
Mensagem não entregue