---
title: "Comece a usar a API REST"
description: "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."
url: https://scratcher.io/pt-br/help/developers/rest-api
language: pt-BR
---

1. [Central de ajuda](https://scratcher.io/pt-br/help)
2. [API, webhooks e MCP](https://scratcher.io/pt-br/help/developers)
3. Comece a usar a API REST

# 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:

```text
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](https://platform.scratcher.io/docs/index.html). 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.

API, webhooks e MCP

- [Comece a usar a API REST](https://scratcher.io/pt-br/help/developers/rest-api)
- [Envie dados para seus sistemas com webhooks](https://scratcher.io/pt-br/help/developers/webhooks)
- [Scratcher MCP para as suas próprias ferramentas de IA](https://scratcher.io/pt-br/help/developers/mcp)

Continue aprendendo

## Artigos relacionados

- [Envie dados para seus sistemas com webhooks](https://scratcher.io/pt-br/help/developers/webhooks): Receba uma requisição na sua própria URL quando alguém se cadastrar, participar ou ganhar, com payload assinado, autenticação básica, payload personalizado e registro de cada entrega.
- [Scratcher MCP para as suas próprias ferramentas de IA](https://scratcher.io/pt-br/help/developers/mcp): Conecte o Claude, o ChatGPT e outras ferramentas de IA à sua conta Scratcher com MCP. Veja como configurar e o que a sua IA pode fazer.
- [Conecte mais de 8.000 apps com o Zapier](https://scratcher.io/pt-br/help/integrations/zapier): Envie novos cadastros do Scratcher para o Google Sheets, o Slack, seu CRM ou milhares de outros apps com o Zapier.

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](https://platform.scratcher.io/pt-BR/login)**

    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](https://scratcher.io/pt-br/book-a-meeting)**

    Uma videochamada gratuita de 30 minutos com nossa equipe: um tour, ideias de campanhas ou ajuda com a configuração.
- **[Mande um e-mail](mailto:contact@scratcher.io)**

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