Saltar al contenido
API de TotemDocumentación
ENEnglishESEspañol
Crear clave API
Beta

Primeros pasos Inicio rápido

Crear clave API

Inicio rápido

Haz tus primeras peticiones a la API de Totem en unos minutos. Comprueba tu clave, busca tu equipo, lista leads e inicia una sincronización.

Esta guía te lleva de una clave nueva a tus primeros leads en cuatro pasos.

Antes de empezar

Necesitas:

  • Un equipo de Totem con el plan Pro o uno superior, o con acceso a la API acordado con Totem, que haya guardado su configuración legal en Privacidad y acuerdos.
  • Una clave secreta. Un administrador del equipo abre Ajustes → Desarrolladores, elige Crear clave API y confirma el acceso de lectura al equipo. Totem muestra la clave una sola vez: cópiala directamente en el almacén de secretos de tu servidor.
  • curl y, para el paso 2, jq.

Si Crear clave API no aparece o está desactivado, Crear una clave enumera todos los requisitos y lo que indica Ajustes en cada caso.

Para seguir esta guía, carga la clave en una variable de entorno sin escribirla en la línea de comandos, para que no quede en el historial de la shell. Ejecuta esto, pega la clave y pulsa Intro; no se muestra nada:

Bash
read -rs TOTEM_API_KEY && export TOTEM_API_KEY

En un servidor, haz que tu almacén de secretos proporcione TOTEM_API_KEY al proceso.

1. Comprueba tu clave

Llama a GET /v1/me:

cURL
curl https://api.totemstudio.ai/v1/me \
  -H "Authorization: Bearer $TOTEM_API_KEY"

La respuesta describe tu clave: la integración a la que pertenece, los cuatro últimos caracteres de la clave, los equipos que lee y sus permisos.

JSON
{
  "object": "integration",
  "id": "prn_m1NFIcoIU8smXfqR4ymgt6j07TfRF",
  "livemode": false,
  "name": "Example CRM sync",
  "key": {
    "last4": "Q7xZ"
  },
  "teams": [
    "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR"
  ],
  "scopes": [
    "teams:read",
    "crm:read",
    "calls:read",
    "messages:read",
    "calendar:read"
  ]
}

Tu respuesta lleva tus propios valores y "livemode": true. Los ejemplos de esta documentación son ficticios, por eso dicen "livemode": false.

La misma petición desde Node.js 22 o posterior, como módulo ES, y desde Python 3 con la biblioteca requests (pip install requests), que también usan los ejemplos de la referencia:

me.mjsNode.js
const response = await fetch('https://api.totemstudio.ai/v1/me', {
  headers: { Authorization: `Bearer ${process.env.TOTEM_API_KEY}` },
  signal: AbortSignal.timeout(30_000),
})
// Lee el cuerpo como texto: un rechazo del cortafuegos situado delante de la API no es JSON.
console.log(response.status, await response.text())
me.pyPython
import os

import requests

response = requests.get(
    "https://api.totemstudio.ai/v1/me",
    headers={"Authorization": f"Bearer {os.environ['TOTEM_API_KEY']}"},
    timeout=30,
)
# Muestra el cuerpo como texto: un rechazo del cortafuegos situado delante de la API no es JSON.
print(response.status_code, response.text)

Un 401 significa que falta la clave, que está mal copiada o que ya no es válida. En Autenticación se enumeran todos los casos.

2. Busca tu equipo

GET /v1/teams lista los equipos que lee tu clave:

cURL
curl https://api.totemstudio.ai/v1/teams \
  -H "Authorization: Bearer $TOTEM_API_KEY"
JSON
{
  "object": "list",
  "data": [
    {
      "id": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "object": "team",
      "livemode": false,
      "name": "Example Dental",
      "timezone": "America/New_York",
      "default_country": "US"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Guarda el identificador del primer equipo para los pasos siguientes. Si la petición falla, el comando lo dice en lugar de guardar un valor erróneo:

Bash
TOTEM_TEAM_ID=$(curl -sS https://api.totemstudio.ai/v1/teams \
  -H "Authorization: Bearer $TOTEM_API_KEY" | jq -er '.data[0].id') \
  && export TOTEM_TEAM_ID \
  || { unset TOTEM_TEAM_ID; echo 'El paso 2 falló: ejecuta el curl de arriba para ver el error.' >&2; }

Las peticiones que leen datos de un equipo, como las listas y el feed de cambios, indican el equipo en la cabecera Totem-Team. Solo importa cuando una clave lee varios equipos: una clave con un solo equipo puede omitirla, y una clave con varios recibe 400 team_required si no la envía. Los pasos siguientes la envían siempre, así que sirven en los dos casos.

3. Lista leads

Pide a GET /v1/leads los cinco primeros leads:

cURL
curl "https://api.totemstudio.ai/v1/leads?limit=5" \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID"

La respuesta es una lista: los leads están en data. Un lead tiene muchos más campos de los que muestra este ejemplo; la referencia los enumera todos.

JSON
{
  "object": "list",
  "data": [
    {
      "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "object": "lead",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "record_kind": "lead",
      "name": "Alex",
      "surname": "Rivera",
      "email": "alex.rivera@example.com",
      "phone": "+12025550123",
      "status": "contacted",
      "contact_permissions": {
        "do_not_contact": false,
        "email_opt_out": false,
        "email_opt_out_at": null,
        "whatsapp_consent": null,
        "provenance": {
          "do_not_contact": null,
          "email_opt_out": null,
          "whatsapp_consent": null
        }
      },
      "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
      "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
      "created_at": "2026-09-28T10:15:00.000Z",
      "version": 3,
      "updated_at": "2026-09-28T10:20:01.250Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJrIjoibGVhZCIsImEiOiJsZWFkX3I3MkVmYlJOVXp1cU9SRkpSME84SHhBd0VYZDkzakdVVFlNYU1NWEtTRjBRYkxTOENpVUtKcEVQMzRMRlFHIiwicyI6ImYzNTI3NzI2MTkwYiJ93iHyRg"
}

has_more: true significa que hay más leads. Envía next_cursor en el parámetro cursor, con los mismos filtros y el mismo Totem-Team, para leer la página siguiente. En Listas y paginación se explican la paginación y los filtros.

4. Inicia una sincronización

Una lista es una foto fija. Para mantener una copia de un equipo siempre al día, lee el feed de cambios, GET /v1/sync/changes. La primera petición va sin cursor e inicia la carga inicial de todo el equipo:

cURL
curl https://api.totemstudio.ai/v1/sync/changes \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID"

Cada elemento de data es un registro de un kind, como un lead, una llamada o una cita, o una eliminación que te indica que borres un registro. A partir de ahí, tu sincronización repite un ciclo sencillo:

  1. Aplica a tu copia todos los elementos de la página. Omite los elementos cuya version no sea mayor que la que ya tienes.
  2. Cuando la página entera esté guardada, guarda next_cursor.
  3. Mientras has_more sea true, vuelve a pedir enviando el cursor guardado en cursor.
  4. Cuando has_more sea false, tu copia está al día. Sigue pidiendo con el cursor guardado cada 1 a 5 minutos, y guarda el next_cursor de cada página, aunque esté vacía.

En Sincroniza una copia se explica el resto: las eliminaciones, las fusiones y los traspasos, la recuperación tras un fallo y la resincronización completa. También incluye un cliente de referencia probado, en TypeScript, que puedes copiar en tu servidor.

Siguientes pasos

Versión de la API 1.0a