API de Equipa #

A sua equipa é composta por todas as pessoas que trabalham na sua conta, além de si — administradores, agentes e visualizadores apenas de leitura — bem como pelos convites que enviou e pelos departamentos em que os organiza. A API de Equipa é a versão programática de Definições → Equipa: adicionar e remover pessoas, definir o que cada uma pode ver e fazer, enviar e acompanhar convites, e gerir departamentos.

Todos os endpoints abaixo são relativos ao URL base https://api.youraiconnector.com/v1. Para a versão de dashboard de tudo o que se encontra nesta página, consulte Gestão de Equipa.

Autenticação: estes endpoints requerem uma pessoa com sessão iniciada #

Esta é a única parte da API que uma chave de API não pode utilizar. Todos os endpoints /team, exceto os de departamento, têm de ser chamados com um token de ID Firebase de uma sessão com sessão iniciada:

Authorization: Bearer <Firebase ID token>

Se enviar uma chave de API, o pedido será rejeitado com um 401:

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

A razão é que estes endpoints decidem o que fazer com base em quem tem sessão iniciada: a sua função, o limite do que lhe é permitido conceder a outra pessoa e se está atualmente a trabalhar dentro de outra conta. Uma chave de API é uma integração, não uma pessoa, pelo que não existe ninguém a quem essas regras se possam aplicar.

Na prática, isto significa que a API de Equipa se destina a uma aplicação de primeira parte com um utilizador Your AI Connector com sessão iniciada (consulte Autenticação → Token de ID Firebase). Uma integração servidor-a-servidor não pode gerir membros da equipa — não existe forma de criar um destes tokens a partir de fora da aplicação.

A exceção: os quatro endpoints de departamento são endpoints de API comuns. Aceitam a sua chave de API exatamente como o resto da API, bem como uma sessão com sessão iniciada.

Todas as respostas nesta página seguem o envelope habitual: success: true mais os campos do endpoint ao nível superior, ou success: false com error e error_code quando algo corre mal.

Funções e permissões #

Cada membro da equipa tem uma função, que define o seu acesso predefinido em 12 áreas da aplicação. Pode, depois, substituir áreas individuais.

Cada área é definida para um de quatro níveis: none (oculto), view (apenas de leitura), edit (criar e alterar), full (incluindo eliminar).

Para se desviar das predefinições da função, envie permission_overrides — uma matriz de objetos { "area": ..., "level": ... }. Cada entrada substitui a predefinição da função para essa área específica; tudo o que não listar mantém a predefinição da função.

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

Quem pode chamar estes endpoints

• O proprietário da conta pode sempre fazer tudo.
• Um membro da equipa precisa de team_management em view para ler a lista de membros e a lista de convites, e em edit para adicionar, alterar, suspender, remover, convidar, cancelar ou reenviar. Os administradores têm edit por predefinição; os editores e visualizadores têm none, pelo que, por predefinição, apenas os administradores podem gerir a equipa.
• Ninguém pode conceder acesso superior ao seu próprio. Se tentar atribuir a alguém um nível que você próprio não possui — ou editar, suspender ou remover alguém cujo acesso já seja mais abrangente que o seu — o pedido é recusado com 403 e uma mensagem a indicar a área.

O objeto de membro da equipa #

GET /team/members devolve um destes por membro:

Os membros removidos não são devolvidos — a lista contém apenas membros ativos e suspensos.

Os limites de visibilidade são apenas de escrita aqui. contact_scope, contact_scope_axes e sub_account_access (ver Limitar o que um membro pode ver) podem ser definidos na criação, atualização e convite, mas este endpoint não os devolve.

Listar membros da equipa #

GET /team/members

Devolve a lista de membros mais as contagens de lugares do seu plano, para que possa mostrar “3 de 5 lugares” e saber quando um convite está prestes a ser recusado.

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()

Resposta

{
  "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 é null quando o seu plano não tem limite de lugares. seats_used conta apenas os membros ativos — suspender ou remover alguém liberta o seu lugar imediatamente.

Adicionar um membro da equipa diretamente #

POST /team/members

Coloca alguém na sua equipa imediatamente, sem um convite.

Isto não envia qualquer e-mail. Ninguém é notificado de que foi adicionado e, se ainda não tiverem um início de sessão Your AI Connector, a conta criada para eles não tem palavra-passe, pelo que não podem iniciar sessão até a reporem. Utilize Enviar um convite, a menos que tenha a sua própria forma de informar a pessoa e de a fazer iniciar sessão.

Campos do pedido

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();

Resposta — 201 Created

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

Adicionar alguém que foi anteriormente suspenso ou removido reintegra-o em vez de falhar.

Atualizar um membro da equipa #

PATCH /team/members/{memberUid}

Altera a função, permissões, visibilidade, acesso de cliente ou a participação de um membro na atribuição automática de contactos. Envie apenas os campos que pretende alterar; tudo o que omitir manterá o seu valor atual.

Campos do pedido

Este é o único endpoint onde null significa “limpar”. Enviar "contact_scope": null, "contact_scope_axes": null ou "sub_account_access": null remove esse limite totalmente e faz com que o membro volte a ver tudo. Na criação e no convite, null significa simplesmente “não fornecido”.

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

Resposta

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

Suspender um membro da equipa #

POST /team/members/{memberUid}/suspend

Suspende alguém: mantém o seu lugar na equipa, mas perde o acesso. Utilize isto em vez de remover quando a pausa for temporária — traga-os de volta com PATCH /team/members/{memberUid} e {"status": "active"}.

cURL

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

Resposta

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

Um membro suspenso liberta o seu lugar, pelo que pode convidar outra pessoa para o seu lugar. O seu acesso termina quando o seu token de sessão atual for renovado, o que pode demorar até uma hora — remova-os se precisar que seja imediato.

Remover um membro da equipa #

DELETE /team/members/{memberUid}

Remove alguém da sua equipa e liberta o seu lugar. A pessoa é terminada a sessão e perde o acesso à sua conta; o seu próprio início de sessão permanece inalterado.

cURL

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

Resposta

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

A remoção é permanente da sua parte: um membro removido não pode ser reativado com o endpoint de atualização — convide-o novamente se mudar de ideias. O seu e-mail também é removido da lista de notificações da sua conta.

Limitar o que um membro pode ver #

Três campos opcionais, aceites em adicionar, atualizar e convidar, determinam quanto da conta uma pessoa pode ver. Estes acumulam-se: um membro limitado em mais do que um é limitado por todos eles.

contact_scope — all (o padrão: todos os contactos e conversas) ou assigned (apenas os que lhes estão atribuídos). Com assigned, adicione "contact_scope_unassigned": true para também lhes permitir ver contactos que ainda não pertencem a ninguém.

contact_scope_axes — limita-os a agentes, canais ou departamentos nomeados:

Os IDs de agentes e departamentos não são verificados quando os guarda — um ID que não existe simplesmente não corresponde a nada, o que aparece como uma caixa de entrada vazia em vez de um erro. Os nomes dos canais são verificados: um nome não reconhecido é rejeitado com 400.

Nenhum destes três pode ser definido no proprietário da conta — esse pedido é recusado com 400.

Listar convites #

GET /team/invites

Os convites que enviou, do mais recente para o mais antigo, para que possa ver quem ainda não aceitou.

Parâmetros de consulta

cURL

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

Resposta

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

O token de convite nunca é devolvido — apenas existe no e-mail que foi enviado.

Enviar um convite #

POST /team/invites

Envia por e-mail um convite para alguém se juntar à sua equipa. Esta é a forma habitual de adicionar um membro: a pessoa clica na ligação, inicia sessão com a sua própria conta e aceita. Se ainda não tiver uma conta Your AI Connector, é criada uma conta para essa pessoa e o e-mail guia-a na definição de uma palavra-passe.

Campos do pedido

Definir as permissões antecipadamente significa que não precisa de editar o membro posteriormente — tudo é copiado para a sua adesão quando aceitam.

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();

Resposta — 201 Created

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

Aspetos a planear

• Os convites expiram após 7 dias. Um convite expirado pode ser reenviado, o que inicia um novo período de 7 dias.
• Os convites pendentes ocupam um lugar. Ao contrário de adicionar um membro diretamente, a verificação de lugares aqui conta os membros ativos mais os convites pendentes, pelo que uma conta com todos os lugares ocupados será recusada antes do envio do e-mail.
• 20 convites por dia, contados por conta, tanto para envios como para reenvios.

Cancelar um convite #

DELETE /team/invites/{inviteId}

Retira um convite antes de ser aceite. A ligação no e-mail deixa de funcionar.

cURL

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

Resposta

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

Tanto os convites pending como expired podem ser cancelados. Um convite que já tenha sido aceite, recusado ou cancelado devolve 400; um que não seja seu devolve 403; um ID desconhecido devolve 404.

Reenviar um convite #

POST /team/invites/{inviteId}/resend

Envia novamente o e-mail de convite — para quando este foi perdido ou foi para o spam. Funciona em convites pending e expired, e redefine a validade para 7 dias a partir de agora.

cURL

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

Resposta

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

O novo e-mail contém uma nova ligação, e a ligação antiga continua a funcionar também, pelo que uma pessoa que encontre o primeiro e-mail mais tarde não fica bloqueada. O reenvio conta para o mesmo limite de 20 por dia que o envio, e reativar um convite expirado volta a verificar os seus lugares — um plano completo é recusado com 429.

Aceitar um convite #

POST /team/invites/accept

Aceita um convite com o token do e-mail de convite, adicionando a pessoa com sessão iniciada à equipa dessa conta.

Este é um ato da sua própria identidade. Inicie sessão como si próprio — é deliberadamente recusado com 403 enquanto estiver a trabalhar dentro da conta de outra pessoa.

Campos do pedido

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…" }'

Resposta

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

Recusar um convite #

POST /team/invites/decline

Recusa um convite com o token do e-mail. Tal como aceitar, este é um ato da sua própria identidade e é recusado enquanto estiver a trabalhar dentro de outra conta.

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…" }'

Resposta

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

Departamentos #

Um departamento é um grupo nomeado da sua equipa — Vendas, Apoio ao Cliente, RH. Atribui uma equipa responsável a um lead, pode assumir novas conversações por conta própria e pode ser utilizado para limitar o que um membro vê.

Estes quatro endpoints requerem uma chave de API. Ao contrário do resto desta página, autenticam-se como qualquer outro endpoint na API (ver Autenticação). Uma sessão iniciada também funciona: a leitura requer contacts em view, e a criação, alteração ou eliminação requer team_management em edit.

O objeto departamento

Quando routing_agents e routing_channels estão ambos definidos, uma conversação tem de corresponder a ambos para ser registada aqui — é assim que atribui a uma equipa “o agente de apoio, mas apenas no WhatsApp”.

Uma conta pode ter até 50 departamentos.

Listar departamentos #

GET /team/departments

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

Resposta

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

Criar um departamento #

POST /team/departments

Campos do pedido

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

Resposta — 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"
  }
}

Atualizar um departamento #

PATCH /team/departments/{departmentId}

Altera um departamento. Apenas os campos que enviar são alterados.

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 }'

Resposta

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

O envio de campos não reconhecidos devolve 400; um departamento desconhecido devolve 404; um nome que entra em conflito com outro departamento devolve 409.

Eliminar um departamento #

DELETE /team/departments/{departmentId}

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

Resposta

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

A eliminação de um departamento ao qual alguém está limitado é recusada. A resposta 400 indica os membros cuja visibilidade está restringida a esse departamento, para que possa alterar o âmbito dos mesmos primeiro. Isto é deliberado: remover silenciosamente a limitação dar-lhes-ia acesso a toda a sua base de clientes sem qualquer aviso de que tal aconteceu.

Os contactos arquivados num departamento eliminado não são reescritos — simplesmente deixam de apresentar um departamento e, da próxima vez que os arquivar, a alteração será aplicada.

Verificar as suas próprias permissões #

GET /team/permissions

Devolve o que a pessoa com sessão iniciada tem permissão para fazer na conta em que está a trabalhar atualmente. Utilize-o para ocultar botões que um membro não pode utilizar, em vez de deixar que descubram a limitação através de um erro.

cURL

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

Resposta — o proprietário da conta

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

Resposta — um membro da equipa a trabalhar dentro de uma conta

{
  "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 é owner quando a pessoa com sessão iniciada é o proprietário da conta; caso contrário, é a sua função na equipa. member só está presente no modo de equipa e contém contact_scope, contact_scope_unassigned e contact_scope_axes quando a sua adesão os inclui.

Tokens de sessão #

Cinco endpoints criam um token de início de sessão único para alternar entre contas. Todos respondem da mesma forma:

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

O token é trocado por uma sessão com o SDK de cliente Firebase. Não é uma chave de API e não pode ser enviado como tal, razão pela qual estes endpoints só são úteis dentro de uma aplicação própria.

Cada um recusa com 403 quando a sessão não tem direito a isso: não é membro dessa conta, não é pessoal, essa subconta não pertence à sua agência ou não lhe foi concedida, ou a sessão não está atualmente no modo que o endpoint termina.

Atribuir uma função de plataforma #

POST /team/users/{targetUid}/role

Define a função de plataforma de um utilizador — User, Dev, Support ou Agency. Isto não é a adesão à equipa: é o tipo de conta Your AI Connector que alguém possui.

Este endpoint está restrito a pessoal Your AI Connector, e o último Dev restante não pode ser despromovido. Listado por uma questão de integridade; não faz parte da gestão da sua própria equipa.

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

Erros da API de equipa #

Os endpoints de equipa devolvem o envelope de erro padrão, sempre com error_code juntamente com o estado HTTP:

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

Os códigos partilhados que todos os endpoints podem devolver — 429 (limite de taxa) e 500 — estão listados com orientações de repetição em Erros e Paginação.

Relacionado #

• Gestão de Equipas — as mesmas funcionalidades no painel de controlo, com capturas de ecrã.
• Autenticação — como enviar um token de ID Firebase em vez de uma chave de API.
• API de Contactos — os contactos aos quais se aplicam os limites de visibilidade de um membro.