Ir al contenido
Rex, tu asistente de IA: él se encarga del trabajo pesado, las ideas son tuyas 👉 Conoce a Rex

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:

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. 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ó.

¿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

    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

    Una videollamada gratuita de 30 minutos con nuestro equipo: una demostración, ideas para campañas o ayuda con tu configuración.

  • Escríbenos

    Escribe a contact@scratcher.io y te responderemos.