Pular para o conteúdo
Rex, seu assistente de IA: o trabalho braçal fica com ele, as ideias ficam com você 👉 Conheça o Rex

Comece a usar a API REST

Crie um token de acesso pessoal com os escopos certos, ou registre um app OAuth, e leia campanhas, leads e listas a partir dos seus próprios sistemas.

A API REST da Scratcher permite que seus próprios sistemas leiam suas campanhas, leads e listas, adicionem e atualizem leads e gerenciem produtos e posicionamentos. Este artigo é para o desenvolvedor responsável pela configuração.

A API faz parte dos planos que incluem Webhooks & API (Basic e superiores). Nos demais planos, os botões para criar tokens e apps ficam bloqueados.

Crie um token de acesso pessoal

Um token de acesso pessoal é a forma mais rápida de chamar a API a partir dos seus próprios scripts e sistemas.

  1. Acesse Configurações > API (em Desenvolvedores).
  2. Em Tokens de acesso pessoal, clique em Criar token de acesso pessoal. A caixa de diálogo diz “Gere um token para autenticar as requisições à API.”
  3. Dê a ele um Nome que você reconheça depois, como “Data warehouse”.
  4. Em Escopos, escolha o que o token poderá fazer (veja abaixo). Selecionar tudo marca todos os escopos. Conceda ao token apenas o acesso de que ele precisa.
  5. Clique em Salvar. Você verá “Seu token de acesso foi criado”.
  6. Copie o token em Segredo. “Guarde o segredo acima, pois esta é a única vez que você poderá vê-lo.” Armazene-o em local seguro, por exemplo em um gerenciador de senhas.
  7. Clique em Fechar.

O token pertence ao seu usuário. Ele pode acessar todas as contas da Scratcher das quais você é membro, com os escopos que você escolheu.

Escopos

  • read:campaigns (Ver campanhas): listar e ler campanhas
  • read:lists (Ver listas): listar e ler listas de leads
  • read:leads (Ver leads): ler leads
  • write:leads (Gravar leads): criar, atualizar e excluir leads de uma lista
  • read:placements (Ver posicionamentos): ler posicionamentos
  • write:placements (Gravar posicionamentos): criar, atualizar e excluir posicionamentos
  • read:products (Ver produtos): ler produtos
  • write:products (Gravar produtos): criar, atualizar e excluir produtos

Para ler os leads de uma campanha, o token precisa de read:campaigns e read:leads. Criar e alterar posicionamentos também exige Embed / URL no seu plano.

Revogue um token

Clique no token na lista para abrir Mostrar token de acesso pessoal. Ali aparecem o Nome e os Escopos. Clique em Revogar e confirme (“Tem certeza de que deseja excluir este token? Esta ação não pode ser desfeita!”). Tudo o que usa o token para de funcionar imediatamente.

Faça uma requisição

A URL base é https://platform.scratcher.io/api/v1/. Envie o token no cabeçalho Authorization e solicite JSON:

curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" 

Principais endpoints

  • GET /me: o usuário ao qual o token pertence
  • GET /accounts: as contas às quais você tem acesso. Use o id da conta nas demais chamadas.
  • GET /accounts/{account}/campaigns e /campaigns/{campaign}: suas campanhas
  • GET /accounts/{account}/campaigns/{campaign}/leads: os leads de uma campanha, dos mais recentes aos mais antigos, com seus campos, consentimentos aceitos e, para os ganhadores, o prêmio e o código
  • GET /accounts/{account}/lists e /lists/{list}: suas listas de leads
  • /accounts/{account}/lists/{list}/leads: os leads de uma lista. GET para ler, POST para criar, PUT para atualizar e DELETE para excluir. Um lead tem um email, um phone_number e um custom_token opcional.
  • /accounts/{account}/products: produtos (GET, POST, PUT, DELETE)
  • /accounts/{account}/placements: posicionamentos (GET, POST, PUT, DELETE)

As listagens são paginadas: adicione ?page=2 e assim por diante. Você só pode acessar contas das quais é membro; outros ids de conta retornam um erro.

Limites

Você pode fazer 60 requisições por minuto por usuário. Se ultrapassar esse limite, a API responde com status 429; aguarde um momento e tente novamente.

Referência da API

A referência completa, com todos os campos, filtros, exemplos e uma coleção do Postman, está na documentação de referência da API. O botão Referência da API no topo de Configurações > API também leva até ela.

Crie um app com OAuth

Se você está criando um app que outros usuários da Scratcher conectam às próprias contas, registre um app OAuth em vez de usar um token pessoal.

  1. Acesse Configurações > API. Em Meus apps, clique em Criar app (“Registre um aplicativo OAuth para a API.”).
  2. Preencha o Nome do aplicativo (os usuários o veem ao aprovar seu app) e a URI de redirecionamento (para onde os usuários são enviados após a aprovação).
  3. Clique em Salvar. Você verá “Seu app foi criado!” com o Client ID e o Client secret.
  4. Copie o client secret agora: “Guarde o client secret acima, pois esta é a única vez que você poderá vê-lo.” Clique em Continuar.

Seu app envia os usuários para https://platform.scratcher.io/oauth/authorize com seu client ID, a URI de redirecionamento e os escopos necessários. O usuário entra na Scratcher e vê uma Solicitação de autorização: “Este aplicativo poderá:” seguido dos escopos. Ele clica em Autorizar ou Cancelar. Em seguida, seu app troca o código por tokens em https://platform.scratcher.io/oauth/token.

  • Os tokens de acesso do OAuth duram dois meses. Os refresh tokens duram três meses; use-os para obter um novo token de acesso.
  • Para alterar o nome ou a URI de redirecionamento, clique no app em Meus apps, faça a alteração e clique em Salvar (“Suas configurações foram salvas”). “Você não poderá ver seu segredo depois.”
  • Excluir app remove o app, e a conexão de todos os usuários com ele deixa de funcionar: “Tem certeza de que deseja excluir este app? Esta ação não pode ser desfeita!”

Apps que você aprovou

Apps autorizados lista os apps aos quais você deu acesso à sua conta, como o Zapier, com os escopos que possuem. Clique em Revogar para retirar o acesso.

Quem pode usar a API?

A página API é exibida para usuários com a função Proprietário, Administrador ou Gerente. Um token nunca pode fazer mais do que o usuário que o criou.

Precisa de ajuda?

Ainda precisa de ajuda?

Pessoas de verdade estão aqui para ajudar. Se você já usa o Scratcher, o jeito mais rápido é o chat dentro da plataforma.

  • Converse com a gente

    Entre na sua conta e clique no botão de chat no canto inferior direito. O Rex responde na hora, e nossa equipe está a um clique.

  • Agende uma reunião

    Uma videochamada gratuita de 30 minutos com nossa equipe: um tour, ideias de campanhas ou ajuda com a configuração.

  • Mande um e-mail

    Escreva para contact@scratcher.io e retornaremos o contato.