Acceso y claves
¿Cómo consigo una clave?
Un administrador de tu equipo de Totem crea una integración en Ajustes → Desarrolladores y copia su clave secreta en el almacén de secretos de tu servidor. La API está en Beta, sin invitación. El administrador necesita una dirección de correo verificada, tu organización necesita el plan Pro o uno superior, o acceso a la API acordado con Totem, y el equipo debe haber completado su configuración legal; el Inicio rápido enumera todos los requisitos y qué comprobar si no ves Crear clave API. Después te guía en tus primeras peticiones.
¿Puede una clave leer varios equipos?
Sí, si los equipos pertenecen a la misma organización, y solo un administrador de la familia puede crear una clave así. Una integración cubre una lista explícita de hasta 30 equipos. Las peticiones sobre las colecciones de un equipo indican entonces el equipo en la cabecera Totem-Team, y guardas un cursor del feed de cambios por equipo. Consulta Autenticación.
¿Puedo limitar una clave a las direcciones IP de mis servidores?
Sí. Una integración puede llevar una lista de hasta 20 direcciones IP o rangos CIDR permitidos, que se configura en Ajustes → Desarrolladores. La API solo es accesible por IPv4, así que indica las direcciones IPv4 públicas desde las que salen tus peticiones. Una petición desde cualquier otra dirección recibe 403 ip_not_allowed. En Autenticación se explica cómo configurarla.
¿Puedo llamar a la API desde un navegador o una app móvil?
No. Una clave lee datos con nivel de administrador, así que debe quedarse en tu servidor. La API no envía cabeceras CORS y responde 400 secret_key_in_browser a una petición que lleve una clave y una cabecera Origin. Llama a la API desde tu backend y envía a tu app solo los datos que necesita.
Datos
¿Puedo escribir datos con la API?
No. La versión 1.0a es de solo lectura: ningún endpoint crea ni modifica nada en Totem. El registro de cambios anuncia cualquier capacidad nueva.
¿Puedo leer el texto de los mensajes, las transcripciones o las grabaciones?
No. La versión 1.0a devuelve datos de contacto, como nombres, correos electrónicos y teléfonos, y metadatos. No devuelve el texto de los mensajes, las transcripciones de llamadas, los resúmenes, las grabaciones, las notas, las respuestas de texto libre ni los campos personalizados de los formularios. Una conversación indica su canal, su estado y cuándo llegaron y salieron los últimos mensajes. Una llamada indica su dirección, su duración y su resultado.
¿Cómo busco un lead por teléfono o por correo electrónico?
Envía el teléfono o la dirección de correo electrónico en el cuerpo JSON de POST /v1/leads/search, nunca en una URL. Envía exactamente uno de los dos. La búsqueda es exacta, devuelve como máximo 10 leads y nunca pagina, así que, si muchos registros comparten el mismo teléfono o correo electrónico, puede que no los devuelva todos.
Sincronización y actualidad
¿Hay webhooks?
No. La API de Totem no tiene webhooks: lee el feed de cambios con tu cursor guardado cada 1 a 5 minutos. Los webhooks que incluyen los planes de Totem son otra función del producto, que se configura en Totem y no con una clave de la API. Una consulta que no encuentra nada nuevo devuelve una página vacía que, aun así, hace avanzar tu cursor, así que guarda también su next_cursor. Consulta Sincroniza una copia.
¿Cuánto tardan en aparecer los cambios?
Poco después de producirse en Totem. El feed de cambios retiene sus últimos 10 segundos, para no saltarse nunca un cambio que todavía se está escribiendo. Si consultas cada 1 a 5 minutos, tu copia va más o menos ese tiempo por detrás de Totem.
¿Por qué un registro nuevo responde 404 durante un momento?
Totem prepara cada registro para la API poco después de que cambie. Hasta entonces, las listas y la búsqueda omiten un registro nuevo, y GET sobre su identificador responde 404 resource_missing. El feed de cambios entrega el registro en cuanto está listo. Consulta Listas y paginación.
Pruebas y herramientas
¿Hay un entorno de pruebas?
Todavía no. La versión 1.0a no tiene entorno de pruebas ni claves de prueba: cada clave lee un equipo real. Usa un equipo dedicado que solo contenga contactos ficticios. El archivo fixtures.json del kit contiene datos de ejemplo para tus pruebas unitarias. Consulta Pruebas y puesta en producción.
¿Hay un SDK?
Sí. El SDK oficial de TypeScript, @totemstudioai/sdk, cubre todos los endpoints y ofrece respuestas tipadas, paginación y errores de la API. Se ejecuta en tu servidor, con las versiones de Node.js que indica su página. Para mantener una copia de un equipo, parte del cliente de referencia probado de la guía de sincronización. El documento OpenAPI sigue disponible para otros lenguajes.
Límites
¿Cuáles son los límites?
Una clave lee hasta 2.000 elementos por minuto, con ráfagas de hasta 10.000. Cada día UTC, los endpoints de lista y el feed de cambios le devuelven hasta 250.000 elementos, o 3 veces el número de registros de sus equipos si es mayor; las peticiones de un solo registro, la búsqueda y GET /v1/me no cuentan para esa cuota. Una página contiene hasta 100 elementos. Al superar un límite, la API responde 429 con Retry-After: espera esos segundos y continúa con el mismo cursor. Durante la Beta estas cifras son aproximadas, y una organización puede tener hasta 10 integraciones activas. Consulta Límites de frecuencia y cuota.
Privacidad
¿Cómo respeto las solicitudes de supresión?
Cuando un registro se suprime en Totem, el feed de cambios entrega una eliminación con reason: "erased". Suprimir un lead también suprime sus llamadas, sus conversaciones y los leads archivados que se fusionaron con él, y cada uno llega como una eliminación propia; sus citas se conservan, con lead igual a null. Borra el registro de tu copia y de todos los sistemas a los que lo pasaste, y conserva solo su marca de eliminación: su kind, su id y su version. Las eliminaciones permanecen en el feed 45 días, más de lo que vive un cursor, así que una sincronización que sigue consultando con éxito nunca se pierde ninguna. Mientras la API rechaza un equipo, no llega ninguna eliminación de él y, si el acceso vuelve cuando su cursor ya ha caducado, la resincronización completa borra lo que se eliminó mientras tanto. Un equipo de un sector excluido (sector_restricted) no recibe eliminaciones hasta que Totem cambie su política de sectores, así que conserva su copia solo mientras lo permita tu política de conservación. Consulta Sincroniza una copia.
¿Dónde funciona la API y quién protege los datos que copio?
La API funciona en Google Cloud, en la Unión Europea, y solo responde por HTTPS. Una vez copias los datos, protegerlos os corresponde a ti y al cliente al que pertenecen. En Seguridad y datos personales se explican las dos cosas y cómo informar de una vulnerabilidad.