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.
- Ve a Settings > API (en Developers).
- En Personal access tokens, haz clic en Create personal access token. El cuadro de diálogo indica «Generate a token to authenticate API requests.»
- Asígnale un Name que puedas reconocer más adelante, como «Data warehouse».
- 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.
- Haz clic en Save. Verás «Your access token has been created».
- 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.
- 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ñasread:lists(View lists): listar y leer listas de leadsread:leads(View leads): leer leadswrite:leads(Write leads): crear, actualizar y eliminar leads de una listaread:placements(View placements): leer ubicacioneswrite:placements(Write placements): crear, actualizar y eliminar ubicacionesread:products(View products): leer productoswrite: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 tokenGET /accounts: las cuentas a las que tienes acceso. Usa el id de la cuenta en las demás llamadas.GET /accounts/{account}/campaignsy/campaigns/{campaign}: tus campañasGET /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ódigoGET /accounts/{account}/listsy/lists/{list}: tus listas de leads/accounts/{account}/lists/{list}/leads: los leads de una lista.GETpara leer,POSTpara crear,PUTpara actualizar yDELETEpara eliminar. Un lead tiene unemail, unphone_numbery uncustom_tokenopcional./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.
- Ve a Settings > API. En My apps, haz clic en Create app («Register an OAuth application for the API.»).
- 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).
- Haz clic en Save. Verás «Your app has been created!» con el Client ID y el Client secret.
- 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ó.