Cuenta, equipos y miembros

Resumen

Empieza aquí para saber qué puede leer tu clave.

GET /v1/me indica la integración de tu clave, los cuatro últimos caracteres de la clave, los equipos que lee y sus permisos. Llámalo primero para comprobar que una clave funciona.
GET /v1/teams lista todos los equipos que lee la clave, con su nombre, su zona horaria y su país por defecto, en una sola respuesta. Incluye los equipos que están restringidos por ahora. GET /v1/teams/{id} devuelve uno de ellos.
GET /v1/members lista los miembros de un equipo, solo con su nombre visible, en una sola respuesta. Totem no exporta el correo electrónico, el teléfono ni el rol de ningún miembro.
GET /v1/health indica si la API está funcionando. Es el único endpoint que no necesita clave.

Un equipo es un espacio de trabajo de Totem, con sus propios tableros, miembros, leads y citas. Una clave lee un equipo o varios equipos de la misma organización. GET /v1/me y GET /v1/teams describen la clave y nunca llevan la cabecera Totem-Team; GET /v1/members lee un solo equipo, así que una clave con varios equipos lo indica en esa cabecera. Autenticación explica cuándo enviarla.

Todas las fechas y horas que devuelve la API están en UTC. Usa la timezone de un equipo para mostrar sus horas en hora local, nunca para guardarlas.

El identificador de un miembro pertenece a un solo equipo: la misma persona tiene un identificador mem_ distinto en cada equipo. Los miembros no están en el feed de cambios, así que lee la lista cuando empieces a sincronizar un equipo, cuando un registro indique un miembro que no conoces y al menos una vez al día. Un miembro que deja el equipo sale de la lista, pero los registros anteriores siguen indicando su identificador: no vuelvas a leer la lista por un identificador que no resolvió la última vez y, si muestras nombres en registros anteriores, conserva el de una lectura anterior. Los miembros desactivados siguen en la lista, sin nada que indique que lo están. Lee GET /v1/teams en cada ejecución de la sincronización, porque un equipo que ya no aparece ha salido de la clave.

Obtén la integración de esta clave

GET /v1/me

Devuelve la integración a la que pertenece esta clave: su nombre, los cuatro últimos caracteres de la clave, los equipos que lee hoy y sus permisos. Llámalo primero para comprobar que la clave funciona y ver qué equipos lee; sus datos están en GET /v1/teams.

Límite de frecuencia: Lectura

Respuesta

Devuelve un objeto Me.

Errores

+ 12 errores comunes

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

{
  "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"
  ]
}

Lista los equipos que lee esta clave

GET /v1/teams

Lista todos los equipos que lee esta clave, en una sola respuesta que nunca se pagina, incluidos los que están restringidos por ahora (sus otros endpoints responden 403). Vuelve a leer esta lista en cada sincronización: un equipo que ya no aparece ha salido de la clave, así que borra su copia y su cursor.

Permisos: teams:read
Límite de frecuencia: Sincronización

Respuesta

Devuelve una lista de objetos Team.

object string
Siempre list.
data Array<Team>
Todos los equipos que lee esta clave, incluidos los restringidos.
has_more boolean
Siempre false: esta lista nunca se pagina.
next_cursor null Puede ser null
Siempre null: no hay página siguiente.

Errores

429 quota_exceeded Cuota diaria superada

+ 12 errores comunes

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

{
  "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
}

Obtén un equipo

GET /v1/teams/{id}

Devuelve un equipo que lee esta clave: su nombre, su zona horaria y su país predeterminado. Un equipo que la clave no lee responde 404 resource_missing.

Permisos: teams:read
Límite de frecuencia: Lectura

Parámetros de ruta

id string Obligatorio Prefijo del id team_…
El identificador público del equipo.

Respuesta

Devuelve un objeto Team.

Errores

403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 resource_missing Recurso no encontrado

+ 12 errores comunes

curl 'https://api.totemstudio.ai/v1/teams/team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR' \
  -H "Authorization: Bearer $TOTEM_API_KEY"

{
  "id": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "object": "team",
  "livemode": false,
  "name": "Example Dental",
  "timezone": "America/New_York",
  "default_country": "US"
}

Lista los miembros del equipo

GET /v1/members

Lista todos los miembros del equipo en una sola respuesta, que nunca se pagina y no admite limit ni cursor. Los miembros no llegan por el feed de cambios: lee esta lista al empezar a sincronizar un equipo, de nuevo cuando un elemento indique un miembro que no conoces y, como mínimo, una vez al día. Un miembro que deja el equipo sale de la lista, pero los registros anteriores siguen indicando su identificador, así que conserva de una lectura anterior el nombre que necesites.

Permisos: teams:read
Límite de frecuencia: Sincronización

Cabeceras

Totem-Team string Condicional Prefijo del id team_…
El equipo que se lee, como identificador team_…. Omítelo si la clave lee un solo equipo; es obligatorio si lee varios (400 team_required). Si lo envías, debe indicar un equipo que la clave lee: un identificador mal formado recibe 400 invalid_request, y un equipo fuera de la clave, 404 team_not_accessible, igual que una petición sin la cabecera cuando la clave ya no lee ningún equipo.

Respuesta

Devuelve una lista de objetos Member.

object string
Siempre list.
data Array<Member>
Todos los miembros del equipo.
has_more boolean
Siempre false: esta lista nunca se pagina.
next_cursor null Puede ser null
Siempre null: no hay página siguiente.

Errores

400 team_required Falta el equipo
403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 team_not_accessible Equipo no accesible
409 capture_not_ready Los datos del equipo aún se están preparando
429 quota_exceeded Cuota diaria superada

+ 12 errores comunes

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

{
  "object": "list",
  "data": [
    {
      "id": "mem_h548E7UiYhutHhucVrQCzkM0eaea0",
      "object": "member",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "display_name": "Sam Lee"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Comprueba que la API está disponible

GET /v1/health

Indica si la API está disponible; llama a este endpoint con GET, porque el cortafuegos que protege la API responde a cualquier otro método, HEAD incluido, con un 404 simple. No necesita clave ni admite cadena de consulta: cualquier parámetro, incluso uno para evitar la caché, recibe 400 invalid_request. La cabecera de respuesta Totem-Release indica la versión que respondió.

Autenticación: Sin clave

Respuesta

Devuelve un objeto Health.

object string
Siempre health.
status string
Siempre ok: si la API no está disponible, la respuesta es un error.

Errores

400 invalid_request Petición no válida
400 secret_key_in_browser Clave secreta enviada desde un navegador
500 internal_error Error interno
503 service_unavailable Servicio no disponible

curl 'https://api.totemstudio.ai/v1/health'

{
  "object": "health",
  "status": "ok"
}

El objeto `Me`

La integración propietaria de la clave, con los equipos que lee.

Atributos

object string
Siempre integration.
id string Prefijo del id prn_…
Identificador público de la integración.
livemode boolean
true con una clave real; false en los datos de ejemplo.
name string
El nombre que un administrador dio a la integración.
key object
La clave usada en esta petición.
- last4 string 4 caracteres
  Los cuatro últimos caracteres de la clave usada en esta petición.
teams Array<string> Prefijo del id team_…
Los equipos que lee esta clave hoy. Sus datos están en GET /v1/teams.
scopes Array<string>
Los permisos de la clave: el conjunto fijo de lectura en v1.0a.
Valores posibles
- teams:read
- crm:read
- calls:read
- messages:read
- calendar:read

{
  "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"
  ]
}

El objeto `Team`

Un equipo que lee esta clave, con su zona horaria y su país predeterminado.

Atributos

id string Prefijo del id team_…
Identificador público del registro.
object string
Siempre team.
livemode boolean
true en datos reales; false en los datos de ejemplo.
name string Puede ser null ≥ 1 caracteres
El nombre del equipo tal como aparece en Totem, o null si no hay ninguno guardado.
timezone string ≥ 1 caracteres
La zona horaria IANA del equipo: la de su horario comercial si es válida; si no, la de su país por defecto (Europe/Madrid si no hay ninguna). Úsala para interpretar las horas locales del equipo.
default_country string Puede ser null Patrón ^[A-Z]{2}$
El país por defecto del equipo (ISO 3166-1 alfa-2), que Totem usa cuando alguien escribe un teléfono sin prefijo; null si no hay ninguno. La API no lo aplica: Lead.phone se valida sin país por defecto, así que un número guardado sin prefijo de país tiene phone_status: invalid.

{
  "id": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "object": "team",
  "livemode": false,
  "name": "Example Dental",
  "timezone": "America/New_York",
  "default_country": "US"
}

El objeto `Member`

Un miembro del equipo, solo por su nombre visible: Totem no exporta su correo electrónico, su teléfono ni su rol.

Atributos

id string Prefijo del id mem_…
Identificador público del registro.
object string
Siempre member.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece este registro.
display_name string Puede ser null ≥ 1 caracteres
El nombre visible del miembro, o su nombre y apellido, o null si no hay ninguno guardado. Totem no exporta su correo electrónico, su teléfono ni su rol.

{
  "id": "mem_h548E7UiYhutHhucVrQCzkM0eaea0",
  "object": "member",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "display_name": "Sam Lee"
}

Resumen

Respuesta

Errores

Respuesta

Errores

Parámetros de ruta

Respuesta

Errores

Cabeceras

Respuesta

Errores

Respuesta

Errores

El objeto Me

Atributos

El objeto Team

Atributos

El objeto Member

Atributos

El objeto `Me`

El objeto `Team`

El objeto `Member`