Servidor de reserva

O servidor de reserva é um segundo endereço que executa exatamente a mesma API. Destina-se ao caso em que um pedido para portal.bulkgate.com não chega de todo ao destino — o host de reserva aceita o pedido e encaminha-o por uma rota diferente.

Como o serviço está construído

O BulkGate funciona em vários servidores localizados em três locais geográficos. Se um deles falhar, os restantes assumem o tráfego automaticamente — nada muda para a sua integração e portal.bulkgate.com continua a responder. Este caso não exige qualquer tratamento da sua parte. Toda a configuração está descrita em Infrastructure.

O que isto não cobre é o caminho até nós. Uma falha no percurso entre o seu servidor e o nosso — num operador, num fornecedor de conectividade ou em qualquer ponto intermédio — está fora do nosso controlo e, nesse caso, o pedido nunca chega até nós. É para isso que serve o host de reserva.

O estado atual do serviço está disponível em bulkgate.status.online.

Endereço

https://backup1.bulkgate.com

O host é um substituto exato — os caminhos, os parâmetros, os dados de acesso e as respostas são idênticos aos de portal.bulkgate.com. Basta trocar o domínio:

https://portal.bulkgate.com/api/2.0/advanced/transactional https://backup1.bulkgate.com/api/2.0/advanced/transactional

Funciona com a mesma conta, o mesmo token e o mesmo crédito. Não há nada para configurar nem para ativar.

Cuidado

Não utilize o host de reserva como endereço principal. Pode ser desligado para manutenção a qualquer momento e sem aviso prévio — destina-se a transportar tráfego apenas enquanto o host principal estiver inacessível. Mantenha portal.bulkgate.com em primeiro lugar na ordem.

Quando mudar para ele

Importante

O host de reserva resolve uma falha de ligação, não um pedido rejeitado. A um pedido que a API recusou, responde exatamente da mesma forma.

Mude quando o pedido não obtém resposta:

situação	mudar?
Tempo limite de ligação ou de leitura esgotado	Sim
Não foi possível resolver o DNS	Sim
Ligação recusada, rede inacessível	Sim
HTTP 5xx sem corpo	Sim
Uma resposta com um tipo de erro (4xx)	Não
`429 Too Many Requests` (limites	Não

Nos dois últimos casos, a API respondeu — o pedido chegou e foi avaliado. Repeti-lo no host de reserva devolve o mesmo erro e apenas consome mais uma tentativa do seu limite.

Integrar o failover na sua integração

Mantenha os endereços numa lista ordenada e experimente-os um a seguir ao outro. Se a ligação falhar, passe ao seguinte; se a API respondeu, devolva o resultado tal como está.

$hosts = ['portal.bulkgate.com', 'backup1.bulkgate.com']; foreach ($hosts as $host) { $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => "https://$host/api/2.0/advanced/transactional", CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode([ 'application_id' => 451, 'application_token' => 'NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj', 'number' => ['420777777777'], 'text' => 'Your order 4517 has been shipped.', // Proteção contra o envio duplicado quando a primeira tentativa esgotou o tempo limite, // mas a mensagem foi enviada na mesma — consulte O que ter em atenção. 'duplicates_check' => 'on', ], JSON_THROW_ON_ERROR), ]); $body = curl_exec($curl); $error = curl_error($curl); curl_close($curl); // A ligação falhou — experimentar o endereço seguinte. if ($body === false) { continue; } // A API respondeu, com sucesso ou com erro. Não se muda mais. print_r(json_decode($body, true, flags: JSON_THROW_ON_ERROR)); break; }

# pip install requests import requests hosts = ['portal.bulkgate.com', 'backup1.bulkgate.com'] for host in hosts: try: response = requests.post(f'https://{host}/api/2.0/advanced/transactional', json={ 'application_id': 451, 'application_token': 'NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj', 'number': ['420777777777'], 'text': 'Your order 4517 has been shipped.', 'duplicates_check': 'on', }, timeout=30) except requests.RequestException: continue # a ligação falhou, experimentar o endereço seguinte print(response.json()) break

O que ter em atenção

Aviso

Um tempo limite esgotado não significa que a mensagem não tenha sido enviada. O pedido pode ter chegado e a resposta ter-se perdido no regresso — uma nova tentativa no host de reserva enviaria então a mensagem uma segunda vez.

É por isso que deve enviar duplicates_check ativado nos endpoints transacionais. Uma mensagem com o mesmo texto para o mesmo número é descartada dentro de uma janela de 5 minutos, pelo que a tentativa repetida não duplica nada.

Importante

Nos endpoints promocionais, duplicates_check não protege uma nova tentativa — apenas remove duplicados dentro de um único lote, não entre pedidos. Um pedido repetido é, para ele, um novo lote e é enviado na íntegra. Nos envios em massa, verifique antes se a primeira tentativa foi concluída antes de a repetir.

Defina um tempo limite razoável. Sem ele, o cliente fica à espera de uma resposta que nunca chega e nunca chega a passar para o host de reserva.

Nota

A idempotência da API está em desenvolvimento — será possível marcar um pedido repetido para que a API o reconheça e devolva o resultado do pedido original em vez de voltar a enviar. Isso eliminará a diferença entre os endpoints transacionais e promocionais descrita acima. Documentaremos o procedimento aqui assim que estiver disponível.

Esta página foi útil?

Perguntar à IA Copiado