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.
- Acesse Configurações > API (em Desenvolvedores).
- 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.”
- Dê a ele um Nome que você reconheça depois, como “Data warehouse”.
- 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.
- Clique em Salvar. Você verá “Seu token de acesso foi criado”.
- 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.
- 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 campanhasread:lists(Ver listas): listar e ler listas de leadsread:leads(Ver leads): ler leadswrite:leads(Gravar leads): criar, atualizar e excluir leads de uma listaread:placements(Ver posicionamentos): ler posicionamentoswrite:placements(Gravar posicionamentos): criar, atualizar e excluir posicionamentosread:products(Ver produtos): ler produtoswrite: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 pertenceGET /accounts: as contas às quais você tem acesso. Use o id da conta nas demais chamadas.GET /accounts/{account}/campaignse/campaigns/{campaign}: suas campanhasGET /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ódigoGET /accounts/{account}/listse/lists/{list}: suas listas de leads/accounts/{account}/lists/{list}/leads: os leads de uma lista.GETpara ler,POSTpara criar,PUTpara atualizar eDELETEpara excluir. Um lead tem umemail, umphone_numbere umcustom_tokenopcional./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.
- Acesse Configurações > API. Em Meus apps, clique em Criar app (“Registre um aplicativo OAuth para a API.”).
- 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).
- Clique em Salvar. Você verá “Seu app foi criado!” com o Client ID e o Client secret.
- 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.