Envio de código de utilização única (OTP)

URL da API

URL utilizado para enviar pedidos HTTP:

https://portal.bulkgate.com/api/1.0/otp/send

Nota

Se o pedido não chegar ao destino, repita-o no servidor de reserva backup1.bulkgate.com.

Métodos HTTP suportados

POST - application/json

POST /api/1.0/otp/send HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Importante

Além de request_quota_number, o endpoint aplica um limite de 60 pedidos por minuto para toda a conta. Ao ultrapassá-lo, é devolvido the_quota_of_send_per_minute_has_been_exceeded.

Tabela de parâmetros

NOME DO PARÂMETRO	VALOR	OBRIGATÓRIO	VALOR PREDEFINIDO
application_id	Application ID	Sim	-
application_token	Application token	Sim	-
number	Número de telefone para o qual é enviado o código de verificação	Sim	-
country	Código do país do número de telefone	não	O valor é obtido a partir do perfil.
language	Idioma do texto da mensagem, um dos 100 códigos ISO suportados. Um código desconhecido faz com que o pedido seja rejeitado. Sem ele, o idioma é detetado a partir do número de telefone.	não	`null`
code_type	Tipo de código. (`string`, `int` ou `combined`)	não	`int`
code_length	Comprimento do código de verificação (4-100).	não	6
request_quota_number	O número de pedidos por minuto para `request_quota_identification`	não	1
request_quota_identification	Identificação do "utilizador / requerente do OTP" a que se aplica a quota por minuto `request_quota_number`. Recomendamos utilizar um endereço IP para esta identificação.	Sim	-
trials_available_resend	Limite de reenvios disponíveis	não	`null` - ilimitado
trials_available_verification	Limite de verificações disponíveis	não	`null` - ilimitado
daily_limit	Limite de pedidos disponíveis por dia (contínuo, para as últimas 24 horas)	não	`null` - ilimitado
daily_limit_country	Limite diário por país sob a forma de um mapa `{"cz": 100, "sk": 50}`. Quando preenchido, são permitidos apenas os países indicados — qualquer outro falha com `country_is_disabled`.	não	`null` - ilimitado
expiration	Expiração do pedido de OTP em segundos; decorrido este tempo, o pedido deixa de ser possível. Um valor inferior a `60` é ignorado e é utilizado o valor predefinido.	não	`604800` - 7 dias
channel	Canais alternativos. Os canais são indicados em cascata: se não for possível entregar a mensagem pelo canal de maior prioridade, são utilizados os canais seguintes da cascata. Se nenhum deles conseguir entregar a mensagem, é utilizado o SMS.	não	SMS, Viber, RCS, WhatsApp ou Text2Voice

Canais

O objeto channel determina os canais que entregam o código e por que ordem. A ordem das chaves no pedido é a ordem da cascata — se o primeiro canal não conseguir entregar o código, é tentado o seguinte. Se nenhum conseguir, é utilizado o SMS.

Objeto SMS

NOME DO PARÂMETRO	VALOR	OBRIGATÓRIO	VALOR PREDEFINIDO
sender_id	ID do remetente, consulte tipo de ID do remetente	não	`gSystem`
sender_id_value	Valor do remetente - `gOwn` (por exemplo, "420 777 777 777"), `gText` (por exemplo, "BulkGate"), `gProfile` (por exemplo, "423"), `gMobile` ou `gPush` (KEY)	não	`null`
domain	URL de um website que utiliza WebOTP para o preenchimento automático do código recebido.	não	`null`

Objeto Viber

NOME DO PARÂMETRO	VALOR	OBRIGATÓRIO	VALOR PREDEFINIDO
sender	Nome do seu remetente registado para Viber	Sim	-
expiration	Segundos de espera antes de tentar outro canal	não	60
code_type	Tipo de código exigido pelo Viber, indicado no modelo de OTP aprovado.	não	`null`
code_reason	Motivo do envio do código, exigido pelo Viber.	não	`null`
business_name	Nome da empresa apresentado na mensagem.	não	`null`

Objeto RCS

NOME DO PARÂMETRO	VALOR	OBRIGATÓRIO	VALOR PREDEFINIDO
sender	Remetente de texto para RCS. Tem de ser registado previamente — para o registar, contacte o nosso suporte.	Sim	-
expiration	Segundos de espera antes de tentar outro canal	não	60
use_card	Envia o código como cartão em vez de texto simples.	não	`false`

Objeto WhatsApp

NOME DO PARÂMETRO	VALOR	OBRIGATÓRIO	VALOR PREDEFINIDO
sender	O seu remetente de WhatsApp registado	Sim	-
template	Nome do modelo de WhatsApp aprovado utilizado para entregar o código.	Não	`verification_code`
language	Idioma do modelo. Sem ele, é utilizado o `language` do pedido.	Não	`null`
expiration	Segundos de espera antes de tentar outro canal da cascata. Mínimo `60`.	Não	`180`

Objeto Text2Voice

O código é lido em voz alta. A mensagem pode ser repetida para que o destinatário a possa anotar.

NOME DO PARÂMETRO	VALOR	OBRIGATÓRIO	VALOR PREDEFINIDO
sender	O seu número de chamada registado.	Sim	-
language	Idioma da voz, um dos 47 códigos ISO suportados. Sem ele, é utilizado o `language` do pedido.	Não	`null`
prefer_gender	Voz preferida - `male` ou `female`.	Não	`male`
safety_statement	Acrescenta um aviso de segurança no início da chamada.	Não	`true`
repeat	Quantas vezes o código é repetido durante a chamada.	Não	`1`
expiration	Segundos de espera antes de tentar outro canal da cascata. Mínimo `60`.	Não	`180`

Exemplo de pedido

{ "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": "420777777777", "country": "cz", "language": "pt", "code_type": "string", "code_length": 7, "request_quota_number": 1, "request_quota_identification": "127.0.0.1", "trials_available_resend": 2, "trials_available_verification": 5, "daily_limit": 100, "daily_limit_country": {"cz": 150, "sk": 50}, "expiration": 3600, "channel": { "rcs": { "sender": "Lt. Hagan", "expiration": 100 }, "viber": { "sender": "Lt. Hagan", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Lt-Hagan", "unicode": true } } }

Resposta

Em caso de sucesso:

{ "data": { "id": "otp-65cca8b4b6a6a2.24308291", "message": { "status": "accepted", "message_id": "cascade-xjyjzh7thor3", "part_id": [ "cascade-xjyjzh7thor3" ], "number": "420777777777", "channel": "whatsapp" } } }

Em caso de erro:

{ "type": "unknown_identity", "code": 400, "error": "Unknown identity", "detail": null }

{ "type": "invalid_input_parameters", "code": 400, "error": "Invalid input parameters", "detail": null }

Em que:

type e error (descrição do erro) encontram-se na tabela de tipos de erro
code representa o erro HTTP
detail é uma informação adicional sobre o erro

Tipos de erro da OTP API

Além dos tipos comuns, a OTP API devolve os seus próprios:

TIPO	QUANDO OCORRE
`the_quota_of_send_per_minute_has_been_exceeded`	A quota de envios por minuto está esgotada.
`the_quota_of_one_additional_resend_per_minute_has_been_exceeded`	Um reenvio menos de 60 s após o anterior.
`the_quota_of_one_additional_resend_has_been_exceeded`	`trials_available_resend` está esgotado.
`the_quota_of_one_additional_verification_has_been_exceeded`	`trials_available_verification` está esgotado.
`daily_limit_reached`	`daily_limit` está esgotado.
`country_is_disabled`	O país do número não consta de `daily_limit_country`.
`country_daily_limit_exceeded`	O limite diário para esse país está esgotado.
`invalid_phone_number`	Não foi possível reconhecer o número.
`invalid_code`	O código verificado não corresponde.
`unknown_channel`	A cascata contém um canal que a OTP API não conhece.
`request_can_not_be_created`	Não foi possível criar o pedido.

Esta página foi útil?

Perguntar à IA Copiado