Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🌐Requisições

Utilização de cada endpoint e padrões de requisição

Contamos atualmente com 4 endpoints de consulta e 3 de blacklist em nossa API de Parceiros, aprenda a seguir como utilizá-los da maneira correta e a função de cada um.

A URL de base de todos os endpoints é: https://web.smsfunnel.com.br/api/parceiros/v1

Padrão de corpo e regras das requisições

  1. A conta consultada é opcional. Se você não enviar email nem user_id, a consulta retorna os dados da própria conta dona do token. É o caminho natural para contas do tipo Cliente, que não gerenciam contas filhas e portanto não têm um e-mail de terceiro a informar.

  2. Se você informar a conta, ela precisa ser o próprio dono do token ou uma conta filha ativa dele. Qualquer outra conta responde 404. Use user_id (ID do usuário) ou email — não envie as duas chaves na mesma requisição; se ambas vierem, o user_id prevalece e o email é ignorado.

  3. Chave presente e vazia é erro. Enviar "email": "" ou "user_id": "" responde 422. Quem manda a chave quis nomear uma conta — cair silenciosamente na própria conta devolveria dados da conta errada. Para consultar a si mesmo, omita a chave.

  4. Você só terá acesso às informações da sua conta e dos seus usuários afiliados.

  5. As requisições não poderão constar headers como set-cookie e afins.

  6. Os parâmetros podem ser enviados na query string (?email=...&from_date=...) ou no corpo JSON da requisição — inclusive nos verbos GET.

  7. O payload não aceita campos além dos documentados em cada endpoint; campos desconhecidos respondem 422.

O que mudou: antes o campo email era obrigatório em todas as consultas. Agora ele é opcional.

Quem já envia email ou user_id não precisa alterar nada — o comportamento é idêntico ao de antes. A novidade serve para quem consulta a própria conta e não tinha um e-mail de terceiro para informar.

Autenticação

Todas as requisições exigem o header:

Authorization: Bearer SUA_CHAVE_DE_API

Código de Erros Comuns

  • 400 Bad Request: A requisição não pôde ser processada devido a um erro genérico.

  • 401 Unauthorized: Sua Chave de API é inválida ou o header Authorization está ausente/malformado.

  • 403 Forbidden: Seu usuário não tem a API de Parceiros habilitada, está inativo ou sua chave expirou.

  • 404 Not Found: O usuário solicitado não foi encontrado, está inativo ou não pertence aos seus afiliados.

  • 422 Unprocessable Entity: O payload tem algum problema — campo obrigatório ausente, campo vazio, valor inválido, campo não permitido ou intervalo de datas maior que 90 dias.

  • 500 Internal Server Error: Ocorreu um erro interno ao processar a requisição.

Corpo de Resposta de Erros Comuns

Endpoints

GET /recharges

Função: Obter dados de recargas do usuário.

Parâmetros:

Campo
Obrigatório
Descrição

email

Não

E-mail da conta a consultar. Omita para consultar a própria conta do token.

user_id

Não

ID da conta a consultar. Alternativa ao email.

from_date

Não

Data inicial. Se enviada, to_date passa a ser obrigatória.

to_date

Não

Data final. Máximo de 90 dias de diferença para from_date. Sem datas, o padrão são os últimos 90 dias.

Corpo de envio — consultando a própria conta:

Corpo de envio — consultando uma conta filha:

Corpo de resposta:

GET /sent-messages

Função: Obter mensagens enviadas do usuário.

Parâmetros: os mesmos de /recharges.

Corpo de envio — consultando a própria conta:

Uma requisição sem nenhum parâmetro também é válida e retorna os últimos 90 dias da própria conta.

Corpo de envio — consultando uma conta filha:

Corpo de resposta:

GET /credits

Função: Obter dados de créditos gerais do usuário. Não aceita filtro de datas — devolve sempre a posição atual.

Parâmetros:

Campo
Obrigatório
Descrição

email

Não

E-mail da conta a consultar. Omita para consultar a própria conta do token.

user_id

Não

ID da conta a consultar. Alternativa ao email.

Corpo de envio — consultando a própria conta:

Corpo de envio — consultando uma conta filha:

Corpo de resposta:

GET /clicks

Função: Obter o número de clicks nos envios do usuário.

Parâmetros:

Campo
Obrigatório
Descrição

from_date

Sim

Data inicial.

to_date

Sim

Data final. Máximo de 90 dias de diferença para from_date.

email

Não

E-mail da conta a consultar. Omita para consultar a própria conta do token.

user_id

Não

ID da conta a consultar. Alternativa ao email.

id

Não

ID da automação ou do broadcast. Se preenchido, retorna dados apenas do ID informado.

include_message

Não

true para incluir o texto das mensagens na resposta.

Diferente dos demais endpoints, from_date e to_date são obrigatórios em /clicks. Sem eles a resposta é 422.

As listas campaigns e broadcasts só aparecem na resposta quando existem campanhas ou broadcasts no período consultado.

Os textos das mensagens (messages nas campanhas e message, url, short_url nos broadcasts) só são retornados quando você envia "include_message": true.

Corpo de envio — consultando a própria conta:

Corpo de envio — consultando uma conta filha:

Corpo de resposta:

GET /phones-blacklist

Recupera todos os números da blacklist da conta informada — ou da própria conta do token, se você não informar email nem user_id. A paginação é de 1.000 registros por vez.

Parâmetros:

Campo
Obrigatório
Descrição

email

Não

E-mail da conta. Omita para operar a própria conta do token.

user_id

Não

ID da conta. Alternativa ao email.

page

Não

Página desejada. Padrão 1.

per_page

Não

Registros por página. Padrão 1000, máximo 5000.

Corpo de envio — própria conta:

Corpo de envio — conta filha:

Corpo de resposta:

POST /phones-blacklist

Inclusão de telefones na blacklist da conta informada — ou da própria conta do token, se você não informar email nem user_id. Caso o número seja inválido, ele será descartado, não sendo incluído na blacklist.

Parâmetros:

Campo
Obrigatório
Descrição

phones

Sim

Array de telefones.

email

Não

E-mail da conta. Omita para operar a própria conta do token.

user_id

Não

ID da conta. Alternativa ao email.

Corpo de envio — própria conta:

Corpo de envio — conta filha:

Corpo de resposta:

DELETE /phones-blacklist

Exclusão de telefones da blacklist da conta informada — ou da própria conta do token, se você não informar email nem user_id.

Parâmetros: os mesmos do POST /phones-blacklist.

Corpo de envio — própria conta:

Corpo de envio — conta filha:

Corpo de resposta:

Perguntas frequentes

Já uso email em todas as chamadas. Preciso mudar alguma coisa? Não. O comportamento de quem envia email ou user_id é exatamente o mesmo de antes.

Sou uma conta que não gerencia outras contas. O que faço? Simplesmente não envie email nem user_id. A consulta será da sua própria conta.

Enviei "email": "" e recebi 422. Por quê? Uma chave presente e vazia é tratada como erro, não como "consulta a mim mesmo" — assim uma variável não preenchida na sua integração não vira, sem aviso, uma consulta de outra conta. Para consultar a própria conta, remova a chave do payload.

Posso consultar qualquer conta pelo email? Não. A conta indicada precisa ser a sua própria ou uma conta filha ativa sua. Qualquer outra responde 404.

Dúvidas?

Em caso de dúvidas, entre em contato com nosso suporte.

PreviousAutenticação
NextQuickstart

Last updated