O que você precisa começar a usar a API externa é como criar requisições remotas e processar as respostas.
Pré-requisitos
Antes de fazer sua primeira solicitação, acesse Configurações > Integrações > Integração da API para configurar seu acesso. Duas opções de autenticação estão disponíveis:
Token: Identifique seu endpoint regional e seu token de App. Use o App Token único diretamente em seus pedidos. Tokens de aplicativo estão obsoletos e serão removidos em uma versão futura. Veja a nota sobre a descontinuação de tokens do aplicativo abaixo para mais informações.
Segurança do token
O token API é exclusivo de um projeto. Ele é gerado como uma string aleatória quando o projeto é criado, com verificações de unicidade realizadas contra o ambiente Xtremepush. O token está disponível apenas para usuários com função de administrador do projeto. Deve-se ter cuidado ao compartilhar o token, pois ele concede acesso total à API ao projeto, a menos que você esteja usando o método OAuth 2.0. Um único token está disponível para o projeto e só pode ser rotacionado manualmente por meio de coordenação com nossa equipe de suporte.
Depreciação de App Token
App Tokens não estão disponíveis em projetos criados após o lançamento de junho de 2026 e serão removidos para projetos existentes em uma versão futura.
Se você já tem projetos usando App Tokens, migre para a autenticação OAuth 2.0. Se você estiver configurando um novo projeto, use o OAuth 2.0 para autenticar suas requisições de API.
Para mais informações sobre como configurar o OAuth 2.0, veja OAuth 2.0
OAuth 2.0: Veja OAuth 2.0 para mais detalhes.
Solicitar a descontinuação
Os pedidos Get são suportados atualmente, mas serão removidos em uma versão futura. Use solicitações POST para todas as chamadas ao
/tokenendpoint.
Criação de solicitações
Os métodos externos da API são usados enviando requisições HTTP POST com corpo JSON para um Endpoint da API.
https://external-api.xtremepush.com/api/external/{method name}/{model name}O Xtremepush gerencia várias instâncias diferentes localizadas em diferentes regiões do mundo. Cada projeto na plataforma está localizado em uma única região, que é selecionada ao criar um projeto. Você deve usar o endpoint correspondente da API para cada projeto:
Região | API Endpoint |
|---|---|
UE | |
EUA |
Os nomes dos métodos e modelos são mostrados em detalhes na API Reference junto com os parâmetros disponíveis. Exemplos são fornecidos para cURL para facilitar o teste, e a documentação permite testes ao vivo fornecendo seus próprios valores para parâmetros.
Processamento de respostas
Após fazer uma solicitação à API, a resposta é retornada como um objeto formatado em JSON com um código de status HTTP apropriado. Exemplos específicos são fornecidos na Referência da API para cada método, mas todos seguem uma estrutura básica:
{
"code" : integer http error/success code
"success" : boolean - whether client request is successful
"message" : string - system error message if code is error (4xx-5xx) for use in logging so can be reviewed in the event of errors
"errors" : errors list if success is false (optional)
"data" : contains array of response data (optional)
"model" : contains created / updated object attributes (optional)
}Sucesso
Uma resposta bem-sucedida pode conter um message e o associado model ao criar ou atualizar, ou, para um método de lista, pode conter uma data propriedade com um array de objetos.
{
"code": 200,
"success": true,
"message": "Campaign successfully created",
"model": {
"id": CAMPAIGN_ID,
"text": "Testing Campaign is sent to subscribers to 15_01_04",
"title": "Flag Test Campaign",
....
}
}Erro
Uma implementação de API deve lidar com respostas de erro, indicadas por códigos de status HTTP 4xx-5xx padrão.
Erros 4xx indicam um problema na requisição, como usar um URI inválido ou ter parâmetros de API incorretos. Sempre que possível, informações adicionais serão fornecidas para ajudar você a depurar no lado do cliente.
{
"code": 400,
"success": false,
"message": "Campaign is not created",
"errors": {
"text": ["Text cannot be blank."]
}
}Tratamento de respostas de erro
Diretriz geral para lidar com respostas de erro:
4xx – Problema com o cliente. Erro de log, então o alerta vai para a equipe de TI.
5xx – Problema de conectividade de rede ou Xtremepush. Tente até o limite de tentativas e depois registre o erro com o alerta para a equipe de TI, que pode escalar com o suporte do Xtremepush se necessário.
Uma possível estratégia de retentativa (dependendo do seu caso) é enviar uma tentativa imediatamente e, se ainda assim retornar o mesmo código, tentar novamente após 30 segundos. A solicitação, resposta e carimbo de data para qualquer coisa que não seja um código de resposta 2XX devem ser registrados para que possam ser analisados posteriormente.