Convenciones

Notación

• GET /v1/leads/{id} es un método y una ruta bajo https://api.totemstudio.ai. Una palabra entre llaves es un marcador que sustituyes por un valor.
• … sustituye a un valor que se omite en un ejemplo.
• $TOTEM_API_KEY es una variable de entorno que contiene tu clave secreta.
• Los campos se escriben tal como aparecen en el JSON. Un punto entra en un objeto: contact_permissions.do_not_contact.

Peticiones y respuestas

• Solo HTTPS. Los cuerpos de las peticiones y las respuestas son JSON en UTF-8, y los nombres de los campos van en snake_case.
• Todo recurso, como un lead, una llamada o un equipo, tiene un campo object con su tipo y un campo livemode. livemode es true en todo lo que devuelve la API; solo los datos de ejemplo de esta documentación llevan livemode: false.
• Una colección llega en un envoltorio de lista con object: "list", data, has_more y next_cursor. Se explica en Listas y paginación.
• Algunos cuerpos tienen una forma propia. Los elementos del feed de cambios llevan kind, y el registro va dentro de ellos, en object, o una eliminación, en removed. GET /v1/health responde {"object": "health", "status": "ok"}. Los errores siguen el formato que se describe en Errores.

Identificadores

Los identificadores son cadenas con un prefijo que indica el tipo de registro:

Trata cada identificador como un valor opaco: guárdalo entero, compáralo de forma exacta y no lo analices nunca. Un identificador no cambia mientras su registro existe. Un registro que se elimina y después se vuelve a crear puede volver con un identificador nuevo.

Los identificadores de miembro son de cada equipo: la misma persona tiene un mem_ distinto en cada equipo.

Fechas y horas

Las fechas y horas son cadenas ISO 8601 en UTC, como 2026-10-15T09:30:00Z, y pueden llevar fracciones de segundo. La zona horaria de cada equipo llega con GET /v1/teams/{id}; úsala para mostrar horas, nunca para guardarlas.

Valores vacíos

En los objetos de la API, un campo sin valor es null, nunca una cadena vacía. Algunos campos explican por qué están vacíos:

• el phone de un lead es null con phone_status en missing o invalid;
• los campos del embudo de un lead son null con pipeline_cleared: true cuando alguien convirtió el lead y borró sus datos del embudo.

Teléfonos e importes

• Los teléfonos son cadenas E.164, como +12025550123.
• El estimated_value y el value_at_conversion de un lead son importes tal como los guarda Totem: en unidades principales, como euros o dólares y no céntimos, con decimales si los hay. estimated_value_currency es siempre null, porque Totem no guarda la divisa de estos valores.
• Ningún campo de la versión 1.0a lleva un importe en la unidad mínima de la divisa.

Las enumeraciones pueden crecer

Los campos con un conjunto fijo de valores, como status o archive_reason, pueden ganar valores en cualquier versión, igual que los códigos de error. Cuando encuentres un valor que no conoces, conserva el registro, trata el valor como «otro» y sigue con la sincronización. En el feed de cambios también pueden aparecer nuevos tipos de registro: guarda u omite un elemento cuyo kind no conozcas y sigue sincronizando.

El documento OpenAPI enumera los valores conocidos hoy. Si generas un cliente a partir de él, asegúrate de que el cliente acepta un valor que no conoce en lugar de rechazar el objeto entero.

Versiones de los registros

Cada registro que entrega el feed de cambios lleva version, un entero que crece cada vez que el registro cambia, y updated_at, el momento de esa versión. Eso incluye los leads y sus dos facetas, las actividades, las llamadas, las conversaciones, las citas y los tableros. Aplica un registro solo si su version es mayor que la que tienes. El feed puede entregar un registro más de una vez; su versión indica qué copia es más reciente.

Los equipos, los miembros y los servicios reservables no tienen versión. Cuando vuelvas a leerlos, sustituye tu copia entera.

Versiones de la API y estabilidad

/v1 es la versión actual de la API. Pueden aparecer nuevos campos, valores de enumeración, endpoints y códigos de error, así que ignora lo que no uses.

Cada operación indica su estabilidad en esta referencia y, en el documento OpenAPI, como x-totem-stability. En la versión 1.0a todas las operaciones son beta. Consulta las novedades en el registro de cambios.

Qué significa Beta

Mientras la API está en Beta, Totem puede cambiar o retirar campos, valores y comportamientos, sin un plazo fijo de aviso. El registro de cambios recoge los cambios bajo la fecha en que se publicaron, y una entrada que te pide cambiar tu integración o hacer una resincronización completa empieza por Acción necesaria. Los cambios que solo añaden, como campos, valores de enumeración, endpoints o códigos de error nuevos, pueden aparecer en cualquier momento, así que construye tu integración para que ignore lo que no conoce.

Identificadores de petición

Cada respuesta de la API lleva una cabecera Totem-Request-Id, como req_0f6b2c1e-8d4a-4b7e-9c3f-5a2d1e7b9c40, y el cuerpo de un error la repite en request_id. Regístrala y cítala cuando pidas ayuda a Soporte.

Errores

Los errores siguen la RFC 9457 y llegan como application/problem+json:

{
  "type": "https://totemstudio.ai/developers/errors#team_required",
  "title": "Team required",
  "status": 400,
  "code": "team_required",
  "request_id": "req_0f6b2c1e-8d4a-4b7e-9c3f-5a2d1e7b9c40",
  "param": "Totem-Team",
  "doc_url": "https://totemstudio.ai/developers/errors#team_required"
}

• code indica qué ha fallado. Decide según code, nunca según title, que está en inglés y puede cambiar. type y doc_url enlazan con la entrada del código en la página de Errores, que explica cuándo ocurre y qué hacer. Ambos enlazan con la edición en inglés; en la edición en español, la misma entrada lleva el mismo fragmento, por ejemplo /developers/es/errors#team_required.
• param, cuando aparece, nombra la cabecera, el parámetro o el campo que ha fallado. Nunca repite el valor que enviaste.
• Pueden aparecer códigos nuevos. Trata un código que no conoces según su estado HTTP.
• Un 401 lleva además la cabecera WWW-Authenticate: Bearer realm="Totem API".
• Un 429 lleva Retry-After, un número entero de segundos: espera al menos ese tiempo. Lo usan dos códigos, rate_limited y quota_exceeded; los dos se explican en Límites de frecuencia y cuota. Reintenta un 5xx con espera exponencial.

Durante la Beta, el cortafuegos situado delante de la API responde él mismo a algunas peticiones con un 403, un 404 o un 429 simple, sin este formato: sin cuerpo de error JSON, sin Retry-After y sin Totem-Request-Id. Responde 404 a cualquier ruta fuera de /v1/ y a cualquier método que no sea GET ni POST, HEAD incluido. Trata su respuesta según su estado; Errores indica cuándo ocurre cada una.

Datos personales en las URL

No pongas nunca un teléfono, una dirección de correo electrónico ni un nombre en una URL: las URL acaban en los registros de ambos lados. Para buscar un lead por teléfono o correo electrónico, envíalos en el cuerpo JSON de POST /v1/leads/search.

Los campos de texto no son de fiar

Los campos de texto, como name, surname, company, email y tags de un lead, display_name de un miembro o los valores de atribución, como los parámetros UTM y los nombres de anuncios, campañas y formularios, proceden de formularios web, de los enlaces por los que llegan los visitantes, de plataformas de anuncios, de perfiles de mensajería y de los propios miembros del equipo, y Totem los devuelve tal como se guardaron. Quien rellena un formulario o modifica un enlace elige lo que contienen. Escápalos allí donde los muestres y no los interpretes nunca como HTML, Markdown ni plantillas. Al exportarlos a CSV o a una hoja de cálculo, antepón una comilla simple a cualquier valor que empiece por =, +, -, @, un tabulador o un retorno de carro, para que ninguna celda se ejecute como fórmula.