---
title: "Primeros pasos con la API REST"
description: "Crea un token de acceso personal con los permisos adecuados o registra una app OAuth, y consulta campañas, leads y listas desde tus propios sistemas."
url: https://scratcher.io/es-419/help/developers/rest-api
language: es-419
---

1. [Centro de ayuda](https://scratcher.io/es-419/help)
2. [API, webhooks y MCP](https://scratcher.io/es-419/help/developers)
3. Primeros pasos con la API REST

# Primeros pasos con la API REST

Crea un token de acceso personal con los permisos adecuados o registra una app OAuth, y consulta campañas, leads y listas desde tus propios sistemas.

La API REST de Scratcher permite que tus propios sistemas lean tus campañas, leads y listas, agreguen y actualicen leads, y administren productos y ubicaciones. Este artículo está dirigido al desarrollador que la configura.

La API forma parte de los planes que incluyen **Webhooks & API** (Basic y superiores). En los demás planes, los botones para crear tokens y apps están bloqueados.

## Crea un token de acceso personal

Un token de acceso personal es la forma más rápida de llamar a la API desde tus propios scripts y sistemas.

1. Ve a **Settings** > **API** (en **Developers**).
2. En **Personal access tokens**, haz clic en **Create personal access token**. El cuadro de diálogo indica «Generate a token to authenticate API requests.»
3. Asígnale un **Name** que puedas reconocer más adelante, como «Data warehouse».
4. En **Scopes**, elige lo que puede hacer el token (ver abajo). **Select all** selecciona todos los permisos. Otorga al token solo el acceso que necesita.
5. Haz clic en **Save**. Verás «Your access token has been created».
6. Copia el token que aparece en **Secret**. «Save the secret above, as this is the only time you will see it.» Guárdalo en un lugar seguro, por ejemplo, en un gestor de contraseñas.
7. Haz clic en **Close**.

Un token pertenece a tu usuario. Puede acceder a todas las cuentas de Scratcher de las que eres miembro, con los permisos que elegiste.

## Permisos

- `read:campaigns` (**View campaigns**): listar y leer campañas
- `read:lists` (**View lists**): listar y leer listas de leads
- `read:leads` (**View leads**): leer leads
- `write:leads` (**Write leads**): crear, actualizar y eliminar leads de una lista
- `read:placements` (**View placements**): leer ubicaciones
- `write:placements` (**Write placements**): crear, actualizar y eliminar ubicaciones
- `read:products` (**View products**): leer productos
- `write:products` (**Write products**): crear, actualizar y eliminar productos

Para leer los leads de una campaña, el token necesita tanto `read:campaigns` como `read:leads`. Para crear y modificar ubicaciones, tu plan también debe incluir **Embed / URL**.

## Revoca un token

Haz clic en el token de la lista para abrir **Show personal access token**. Allí se muestran el **Name** y los **Scopes**. Haz clic en **Revoke** y confirma («Are you sure you want to delete this token? This cannot be undone!»). Todo lo que use el token dejará de funcionar de inmediato.

## Haz una solicitud

La URL base es `https://platform.scratcher.io/api/v1/`. Envía el token en el encabezado `Authorization` y solicita JSON:

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

## Endpoints principales

- `GET /me`: el usuario al que pertenece el token
- `GET /accounts`: las cuentas a las que tienes acceso. Usa el id de la cuenta en las demás llamadas.
- `GET /accounts/{account}/campaigns` y `/campaigns/{campaign}`: tus campañas
- `GET /accounts/{account}/campaigns/{campaign}/leads`: los leads de una campaña, del más reciente al más antiguo, con sus campos, los consentimientos aceptados y, en el caso de los ganadores, el premio y el código
- `GET /accounts/{account}/lists` y `/lists/{list}`: tus listas de leads
- `/accounts/{account}/lists/{list}/leads`: los leads de una lista. `GET` para leer, `POST` para crear, `PUT` para actualizar y `DELETE` para eliminar. Un lead tiene un `email`, un `phone_number` y un `custom_token` opcional.
- `/accounts/{account}/products`: productos (`GET`, `POST`, `PUT`, `DELETE`)
- `/accounts/{account}/placements`: ubicaciones (`GET`, `POST`, `PUT`, `DELETE`)

Las listas están paginadas: agrega `?page=2` y así sucesivamente. Solo puedes acceder a las cuentas de las que eres miembro; otros ids de cuenta devuelven un error.

## Límites

Puedes hacer 60 solicitudes por minuto por usuario. Si superas ese límite, la API responde con el estado 429; espera un momento y vuelve a intentarlo.

## Referencia de la API

La referencia completa, con todos los campos, filtros, ejemplos y una colección de Postman, está en la [documentación de referencia de la API](https://platform.scratcher.io/docs/index.html). El botón **API reference** en la parte superior de **Settings** > **API** también te lleva allí.

## Crea una app con OAuth

Si desarrollas una app que otros usuarios de Scratcher conectan a su propia cuenta, registra una app OAuth en lugar de usar un token personal.

1. Ve a **Settings** > **API**. En **My apps**, haz clic en **Create app** («Register an OAuth application for the API.»).
2. Completa el **Application name** (los usuarios lo ven cuando aprueban tu app) y la **Redirect URI** (adonde se redirige a los usuarios después de aprobarla).
3. Haz clic en **Save**. Verás «Your app has been created!» con el **Client ID** y el **Client secret**.
4. Copia el client secret ahora: «Save the client secret above, as this is the only time you will see it.» Haz clic en **Continue**.

Tu app envía a los usuarios a `https://platform.scratcher.io/oauth/authorize` con tu client ID, la redirect URI y los permisos que necesita. El usuario inicia sesión en Scratcher y ve una **Authorization request**: «This application will be able to:» seguido de los permisos. Hace clic en **Authorize** o **Cancel**. Luego, tu app intercambia el código por tokens en `https://platform.scratcher.io/oauth/token`.

- Los tokens de acceso de OAuth duran dos meses. Los tokens de actualización duran tres meses; úsalos para obtener un nuevo token de acceso.
- Para cambiar el nombre o la redirect URI, haz clic en la app en **My apps**, modifícala y haz clic en **Save** («Your settings have been saved»). «You cannot view your secret afterwards.»
- **Delete app** elimina la app, y la conexión de todos los usuarios con ella deja de funcionar: «Are you sure you want to delete this app? This cannot be undone!»

## Apps que aprobaste

**Authorized apps** muestra las apps a las que diste acceso a tu cuenta, como Zapier, con los permisos que tienen. Haz clic en **Revoke** para retirarles el acceso.

## ¿Quién puede usar la API?

La página **API** se muestra a los usuarios con el rol **Owner**, **Admin** o **Manager**. Un token nunca puede hacer más que el usuario que lo creó.

API, webhooks y MCP

- [Primeros pasos con la API REST](https://scratcher.io/es-419/help/developers/rest-api)
- [Envía datos a tus sistemas con webhooks](https://scratcher.io/es-419/help/developers/webhooks)
- [Scratcher MCP para tus propias herramientas de IA](https://scratcher.io/es-419/help/developers/mcp)

Sigue aprendiendo

## Artículos relacionados

- [Envía datos a tus sistemas con webhooks](https://scratcher.io/es-419/help/developers/webhooks): Recibe una solicitud en tu propia URL cuando alguien se registra, participa o gana, con un payload firmado, autenticación básica, un payload personalizado y un registro de cada entrega.
- [Scratcher MCP para tus propias herramientas de IA](https://scratcher.io/es-419/help/developers/mcp): Conecta Claude, ChatGPT y otras herramientas de IA a tu cuenta de Scratcher con MCP. Te contamos cómo configurarlo y qué puede hacer tu IA.
- [Conecta más de 8.000 apps con Zapier](https://scratcher.io/es-419/help/integrations/zapier): Envía los nuevos registros de Scratcher a Google Sheets, Slack, tu CRM o miles de otras apps con Zapier.

¿Necesitas ayuda?

## ¿Sigues necesitando ayuda?

Hay personas reales para ayudarte. Si ya usas Scratcher, lo más rápido es el chat dentro de la plataforma.

- **[Chatea con nosotros](https://platform.scratcher.io/es-419/login)**

    Inicia sesión y haz clic en el botón del chat, abajo a la derecha. Rex responde al instante y nuestro equipo está a un clic.
- **[Agenda una reunión](https://scratcher.io/es-419/book-a-meeting)**

    Una videollamada gratuita de 30 minutos con nuestro equipo: una demostración, ideas para campañas o ayuda con tu configuración.
- **[Escríbenos](mailto:contact@scratcher.io)**

    Escribe a contact@scratcher.io y te responderemos.
