API de equipo #

Tu equipo es todo aquel que trabaja dentro de tu cuenta además de ti (administradores, agentes y espectadores de solo lectura), además de las invitaciones que has enviado y los departamentos en los que los organizas. La API de equipo es la versión programática de Configuración → Equipo: añade y elimina personas, establece lo que cada una puede ver y hacer, envía y gestiona invitaciones, y administra departamentos.

Todos los endpoints a continuación son relativos a la URL base https://api.youraiconnector.com/v1. Para la versión del panel de control de todo lo que aparece en esta página, consulta Gestión de equipo.

Autenticación: estos endpoints requieren una persona que haya iniciado sesión #

Esta es la única parte de la API que no puede utilizar una clave de API. Todos los endpoints /team, excepto los de departamento, deben llamarse con un token de ID de Firebase de una sesión iniciada:

Authorization: Bearer <Firebase ID token>

Si envías una clave de API, la solicitud será rechazada con un 401:

{
  "success": false,
  "error_code": 401,
  "error": "This endpoint requires a Firebase ID token (Authorization: Bearer <token>)."
}

La razón es que estos endpoints deciden qué hacer basándose en quién ha iniciado sesión: tu rol, el límite de lo que tienes permitido conceder a otra persona y si actualmente estás trabajando dentro de otra cuenta. Una clave de API es una integración, no una persona, por lo que no hay nadie a quien aplicar esas reglas.

En la práctica, esto significa que la API de equipo es para una aplicación propia con un usuario Your AI Connector que haya iniciado sesión (consulta Autenticación → Token de ID de Firebase). Una integración servidor a servidor no puede gestionar miembros del equipo; no hay forma de generar uno de estos tokens desde fuera de la aplicación.

La excepción: los cuatro endpoints de departamento son endpoints de API ordinarios. Aceptan tu clave de API exactamente igual que el resto de la API, así como una sesión iniciada.

Cada respuesta en esta página sigue el sobre habitual: success: true más los campos del endpoint en el nivel superior, o success: false con error y error_code cuando algo sale mal.

Roles y permisos #

Cada miembro del equipo tiene un rol, que establece su acceso predeterminado en 12 áreas de la aplicación. Luego puedes anular áreas individuales.

Cada área se establece en uno de cuatro niveles: none (oculto), view (solo lectura), edit (crear y cambiar), full (incluyendo eliminar).

Para apartarse de los valores predeterminados del rol, envíe permission_overrides: una matriz de objetos { "area": ..., "level": ... }. Cada entrada reemplaza el valor predeterminado del rol para esa área específica; todo lo que no incluya en la lista mantendrá el valor predeterminado del rol.

"permission_overrides": [
  { "area": "analytics", "level": "full" },
  { "area": "billing", "level": "none" }
]

Quién puede llamar a estos endpoints

• El propietario de la cuenta siempre puede hacerlo todo.
• Un miembro del equipo necesita team_management en view para leer la lista de miembros y la lista de invitaciones, y en edit para añadir, cambiar, suspender, eliminar, invitar, cancelar o reenviar. Los administradores tienen edit de forma predeterminada; los editores y los visores tienen none, por lo que, de forma predeterminada, solo los administradores pueden gestionar el equipo.
• Nadie puede conceder un acceso superior al suyo propio. Si intenta asignar a alguien un nivel que usted mismo no posee, o editar, suspender o eliminar a alguien cuyo acceso ya es más amplio que el suyo, la solicitud será rechazada con 403 y un mensaje indicando el área.

El objeto de miembro del equipo #

GET /team/members devuelve uno de estos por miembro:

Los miembros eliminados no se devuelven; la lista solo incluye a los miembros activos y suspendidos.

Los límites de visibilidad son de solo escritura aquí. contact_scope, contact_scope_axes y sub_account_access (consulte Limitar lo que un miembro puede ver) se pueden establecer al crear, actualizar e invitar, pero este endpoint no los devuelve.

Listar miembros del equipo #

GET /team/members

Devuelve la lista de miembros junto con el recuento de plazas de su plan, para que pueda mostrar “3 de 5 plazas” y saber cuándo se rechazará una invitación.

cURL

curl "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  headers: { Authorization: `Bearer ${idToken}` },
});
const { members, seat_limit, seats_used } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/team/members",
    headers={"Authorization": f"Bearer {id_token}"},
)
data = res.json()

Respuesta

{
  "success": true,
  "members": [
    {
      "account_owner_uid": "owner_uid_123",
      "member_uid": "uid_alice",
      "member_email": "alice@example.com",
      "member_display_name": "Alice Chen",
      "role": "admin",
      "permission_overrides": [],
      "status": "active",
      "auto_assign_enabled": true,
      "created_by": "owner_uid_123",
      "created_at": "2026-05-01T10:00:00.000Z",
      "updated_at": "2026-06-02T09:15:00.000Z"
    }
  ],
  "seat_limit": 5,
  "seats_used": 3
}

seat_limit es null cuando su plan no tiene límite de plazas. seats_used cuenta solo a los miembros activos; suspender o eliminar a alguien libera su plaza inmediatamente.

Añadir un miembro del equipo directamente #

POST /team/members

Incorpora a alguien a su equipo de inmediato, sin necesidad de una invitación.

Esto no envía ningún correo electrónico. Nadie recibe aviso de que ha sido añadido y, si aún no tenían un inicio de sesión en Your AI Connector, la cuenta creada para ellos no tiene contraseña, por lo que no podrán iniciar sesión hasta que la restablezcan. Utilice Enviar una invitación a menos que tenga su propia forma de informar a la persona y ayudarla a iniciar sesión.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "role": "editor"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "sam@example.com",
    display_name: "Sam Rivera",
    role: "editor",
  }),
});
const { member_uid } = await res.json();

Respuesta — 201 Created

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "member_uid": "uid_sam",
  "message": "Team member created successfully."
}

Añadir a alguien que fue suspendido o eliminado anteriormente los restablece en lugar de fallar.

Actualizar un miembro del equipo #

PATCH /team/members/{memberUid}

Cambia el rol, los permisos, la visibilidad, el acceso a clientes o la participación en la asignación automática de contactos de un miembro. Envíe solo los campos que desea cambiar; todo lo que omita mantendrá su valor actual.

Campos de la solicitud

Este es el único endpoint donde null significa “borrar”. Enviar "contact_scope": null, "contact_scope_axes": null o "sub_account_access": null elimina ese límite por completo y hace que el miembro vuelva a verlo todo. Al crear e invitar, null simplemente significa “no suministrado”.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "permission_overrides": [{ "area": "billing", "level": "none" }]
  }'

Respuesta

{
  "success": true,
  "message": "Team member updated successfully."
}

Suspender a un miembro del equipo #

POST /team/members/{memberUid}/suspend

Suspende a alguien: mantienen su lugar en el equipo pero pierden el acceso. Utilice esto en lugar de eliminar cuando la pausa sea temporal; devuélvalos con PATCH /team/members/{memberUid} y {"status": "active"}.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members/uid_sam/suspend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Respuesta

{
  "success": true,
  "message": "Team member suspended successfully."
}

Un miembro suspendido libera su plaza, por lo que puede invitar a otra persona en su lugar. Su acceso finaliza cuando su token de sesión actual se actualice, lo que puede tardar hasta una hora; elimínelos si necesita que sea inmediato.

Eliminar a un miembro del equipo #

DELETE /team/members/{memberUid}

Elimina a alguien de tu equipo y libera su puesto. Se cierra su sesión y pierde el acceso a tu cuenta; su propio inicio de sesión permanece intacto.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Respuesta

{
  "success": true,
  "message": "Team member removed successfully."
}

La eliminación es permanente por tu parte: un miembro eliminado no puede ser reactivado con el endpoint de actualización; invítalo de nuevo si cambias de opinión. Su correo electrónico también se elimina de la lista de notificaciones de tu cuenta.

Limitar lo que un miembro puede ver #

Tres campos opcionales, aceptados en agregar, actualizar e invitar, deciden cuánto de la cuenta puede ver una persona. Se acumulan: un miembro limitado en más de uno está limitado por todos ellos.

contact_scope — all (el valor predeterminado: todos los contactos y conversaciones) o assigned (solo los que tienen asignados). Con assigned, añade "contact_scope_unassigned": true para permitirles también ver los contactos que aún no tienen propietario.

contact_scope_axes — los limita a agentes, canales o departamentos específicos:

Los IDs de agente y departamento no se verifican al guardarlos; un ID que no existe simplemente no coincide con nada, lo que se muestra como una bandeja de entrada vacía en lugar de un error. Los nombres de canal sí se verifican: uno no reconocido se rechaza con 400.

Ninguno de estos tres puede configurarse para el propietario de la cuenta; esa solicitud se rechaza con 400.

Listar invitaciones #

GET /team/invites

Las invitaciones que has enviado, de la más reciente a la más antigua, para que puedas ver quién aún no ha aceptado.

Parámetros de consulta

cURL

curl "https://api.youraiconnector.com/v1/team/invites?status=pending" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Respuesta

{
  "success": true,
  "invites": [
    {
      "id": "inv_abc123",
      "account_owner_uid": "owner_uid_123",
      "account_owner_display_name": "Acme Ltd",
      "invitee_email": "sam@example.com",
      "invitee_uid": null,
      "role": "editor",
      "permission_overrides": [],
      "status": "pending",
      "created_by": "owner_uid_123",
      "created_at": "2026-06-10T12:00:00.000Z",
      "expires_at": "2026-06-17T12:00:00.000Z",
      "responded_at": null
    }
  ]
}

El token de invitación nunca se devuelve; solo existe en el correo electrónico que se envió.

Enviar una invitación #

POST /team/invites

Envía por correo electrónico una invitación a alguien para que se una a tu equipo. Esta es la forma habitual de añadir a un compañero de equipo: hacen clic en el enlace, inician sesión con su propia cuenta y aceptan. Si aún no tienen una cuenta de Your AI Connector, se crea una para ellos y el correo electrónico los guía para establecer una contraseña.

Campos de la solicitud

Configurar los permisos por adelantado significa que no tienes que editar al miembro después; todo se copia en su membresía cuando aceptan.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "sam@example.com", "role": "editor" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/invites", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "sam@example.com", role: "editor" }),
});
const { invite_id } = await res.json();

Respuesta — 201 Created

{
  "success": true,
  "invite_id": "inv_abc123",
  "message": "Team invite sent successfully."
}

Cosas a tener en cuenta

• Las invitaciones caducan después de 7 días. Una invitación caducada puede volver a enviarse, lo que inicia un nuevo periodo de 7 días.
• Las invitaciones pendientes ocupan un asiento. A diferencia de añadir a un miembro directamente, el recuento de asientos aquí incluye a los miembros activos más las invitaciones pendientes, por lo que se rechazará una cuenta con todos los asientos ocupados antes de que se envíe el correo electrónico.
• 20 invitaciones por día, contadas por cuenta tanto al enviar como al reenviar.

Cancelar una invitación #

DELETE /team/invites/{inviteId}

Retira una invitación antes de que sea aceptada. El enlace en el correo electrónico deja de funcionar.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/invites/inv_abc123" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Respuesta

{
  "success": true,
  "message": "Team invite cancelled."
}

Tanto las invitaciones pending como las expired pueden cancelarse. Una invitación que ya fue aceptada, rechazada o cancelada devuelve 400; una que no es tuya devuelve 403; un ID desconocido devuelve 404.

Reenviar una invitación #

POST /team/invites/{inviteId}/resend

Envía de nuevo el correo electrónico de invitación, para cuando se perdió o fue a la carpeta de spam. Funciona en invitaciones pending y expired, y restablece la fecha de caducidad a 7 días a partir de ahora.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/inv_abc123/resend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Respuesta

{
  "success": true,
  "message": "Team invite resent successfully."
}

El nuevo correo electrónico contiene un nuevo enlace, y el enlace antiguo también sigue funcionando, por lo que una persona que encuentre el primer correo electrónico más tarde no tendrá problemas. El reenvío cuenta para el mismo límite de 20 al día que el envío, y reactivar una invitación caducada vuelve a comprobar tus plazas: un plan completo se rechaza con 429.

Aceptar una invitación #

POST /team/invites/accept

Acepta una invitación con el token del correo electrónico de invitación, uniendo a la persona que ha iniciado sesión al equipo de esa cuenta.

Este es un acto de tu propia identidad. Inicia sesión como tú mismo; se rechaza deliberadamente con 403 mientras trabajas dentro de la cuenta de otra persona.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/accept" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

Respuesta

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "account_owner_uid": "owner_uid_123",
  "message": "Team invite accepted successfully."
}

Rechazar una invitación #

POST /team/invites/decline

Rechaza una invitación con el token del correo electrónico. Al igual que al aceptar, este es un acto de tu propia identidad y se rechaza mientras trabajas dentro de otra cuenta.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/decline" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

Respuesta

{
  "success": true,
  "message": "Team invite declined."
}

Departamentos #

Un departamento es un grupo con nombre dentro de tu equipo: Ventas, Atención al cliente, RR. HH. Asigna un equipo responsable a un cliente potencial, puede reclamar nuevas conversaciones por sí mismo y se puede utilizar para limitar lo que ve un miembro.

Estos cuatro endpoints requieren una clave API. A diferencia del resto de esta página, se autentican como cualquier otro endpoint de la API (consulta Autenticación). Una sesión iniciada también funciona: la lectura requiere contacts en view, y la creación, modificación o eliminación requiere team_management en edit.

El objeto departamento

Cuando se establecen tanto routing_agents como routing_channels, una conversación debe coincidir con ambos para registrarse aquí; así es como le das a un equipo “el agente de soporte, pero solo en WhatsApp”.

Una cuenta puede tener hasta 50 departamentos.

Listar departamentos #

GET /team/departments

curl "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY"

Respuesta

{
  "success": true,
  "departments": [
    {
      "id": "dep_abc123",
      "name": "Sales",
      "color": "#2f6fed",
      "member_uids": ["uid_alice", "uid_bob"],
      "auto_assign_enabled": true,
      "routing_agents": [],
      "routing_channels": ["whatsapp"],
      "created_by": "owner_uid_123"
    }
  ]
}

Crear un departamento #

POST /team/departments

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "routing_channels": ["whatsapp"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/departments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Sales",
    color: "#2f6fed",
    member_uids: ["uid_alice", "uid_bob"],
    routing_channels: ["whatsapp"],
  }),
});
const { department } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/team/departments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Sales",
        "color": "#2f6fed",
        "member_uids": ["uid_alice", "uid_bob"],
        "routing_channels": ["whatsapp"],
    },
)
department = res.json()["department"]

Respuesta — 201 Created

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "auto_assign_enabled": true,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

Actualizar un departamento #

PATCH /team/departments/{departmentId}

Modifica un departamento. Solo se cambian los campos que envíes.

curl -X PATCH "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "member_uids": ["uid_alice"], "auto_assign_enabled": false }'

Respuesta

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice"],
    "auto_assign_enabled": false,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

Si no se envían campos reconocidos, se devuelve 400; un departamento desconocido devuelve 404; un nombre que entra en conflicto con otro departamento devuelve 409.

Eliminar un departamento #

DELETE /team/departments/{departmentId}

curl -X DELETE "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY"

Respuesta

{
  "success": true,
  "deleted": "dep_abc123"
}

Se rechaza la eliminación de un departamento al que alguien está limitado. La respuesta 400 indica los miembros cuya visibilidad está restringida a dicho departamento, para que pueda cambiar su alcance primero. Esto es deliberado: eliminar la limitación de forma silenciosa les daría acceso a toda su base de clientes sin que quedara constancia de ello.

Los contactos archivados bajo un departamento eliminado no se modifican; simplemente dejan de mostrar un departamento, y la próxima vez que los archive, se guardarán correctamente.

Comprobar sus propios permisos #

GET /team/permissions

Devuelve lo que la persona que ha iniciado sesión tiene permitido hacer en la cuenta en la que está trabajando actualmente. Úselo para ocultar botones que un miembro no puede utilizar, en lugar de dejar que descubran la limitación a través de un error.

cURL

curl "https://api.youraiconnector.com/v1/team/permissions" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Respuesta: el propietario de la cuenta

{
  "success": true,
  "role": "owner",
  "is_team_mode": false,
  "permissions": {
    "campaigns": "full",
    "contacts": "full",
    "messages": "full",
    "appointments": "full",
    "settings": "full",
    "billing": "full",
    "team_management": "full",
    "analytics": "full",
    "phone_numbers": "full",
    "integrations": "full",
    "faqs": "full",
    "daily_summaries": "full"
  }
}

Respuesta: un miembro del equipo trabajando dentro de una cuenta

{
  "success": true,
  "role": "editor",
  "is_team_mode": true,
  "permissions": { "campaigns": "edit", "billing": "none", "…": "…" },
  "member": {
    "uid": "uid_sam",
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "account_owner_uid": "owner_uid_123"
  }
}

role es owner cuando la persona que ha iniciado sesión es el propietario de la cuenta; de lo contrario, es su rol en el equipo. member solo está presente en el modo de equipo y contiene contact_scope, contact_scope_unassigned y contact_scope_axes cuando su membresía los incluye.

Tokens de sesión #

Cinco endpoints generan un token de inicio de sesión de un solo uso para cambiar entre cuentas. Todos responden de la misma manera:

{
  "success": true,
  "customToken": "eyJhbGciOi…"
}

El token se intercambia por una sesión con el SDK de cliente de Firebase. No es una clave de API y no puede enviarse como tal, por lo que estos endpoints solo son útiles dentro de una aplicación propia.

Cada uno rechaza con 403 cuando la sesión no tiene derecho a ello: no es miembro de esa cuenta, no es personal, esa subcuenta no pertenece a su agencia o no se le ha concedido, o la sesión no se encuentra actualmente en el modo en que termina el endpoint.

Asignar un rol de plataforma #

POST /team/users/{targetUid}/role

Establece el rol de plataforma de un usuario: User, Dev, Support o Agency. Esto no es la pertenencia a un equipo: es el tipo de cuenta Your AI Connector que tiene alguien.

Este endpoint está restringido al personal de Your AI Connector, y el último Dev restante no puede ser degradado. Se enumera por completitud; no forma parte de la gestión de su propio equipo.

{
  "success": true,
  "targetUid": "uid_sam",
  "role": "Agency",
  "claimUpdated": true
}

Errores de la API de equipos #

Los endpoints de equipos devuelven el sobre de error estándar, siempre con error_code junto al estado HTTP:

{
  "success": false,
  "error_code": 403,
  "error": "Cannot grant \"full\" access to \"billing\" — exceeds your own permissions."
}

Los códigos compartidos que puede devolver cualquier endpoint — 429 (límite de tasa) y 500 — se enumeran con orientación sobre reintentos en Errores y paginación.

Relacionado #

• Gestión de equipos — las mismas funciones en el panel de control, con capturas de pantalla.
• Autenticación — cómo enviar un token de ID de Firebase en lugar de una clave de API.
• API de contactos — los contactos a los que se aplican los límites de visibilidad de un miembro.