# Ferramentas · Empresas

> Ferramentas MCP das empresas da comunidade (com o bloco opcional de coworking, as ofertas e os dados de faturação): listar, registar, editar e encerrar empresas, a sua empresa com as subscrições e os créditos, a equipa, convidar por e-mail, os convites com aceite, marcar o admin da empresa e remover.

As [Empresas](/membros/empresas) pelo assistente: registar a empresa (e, no coworking, o tipo, os planos e produtos que ela pode contratar, os dados de faturação e as datas), editar, encerrar, ver a sua empresa, a equipa, convidar por e-mail, acompanhar, aceitar e recusar convites, marcar o admin da empresa e remover. São **14 ferramentas**.

> [!NOTE]
> Até 2026-10-18 estas ferramentas chamavam-se `*_resident_company*` (por exemplo `get_my_resident_company`). Os nomes antigos já não existem: o assistente que ainda os chama recebe "ferramenta desconhecida" e deve usar os nomes desta página.

Cada ferramenta traz um selo: <span class="tool-kind tool-kind-read">Só consulta</span> não muda nada, <span class="tool-kind tool-kind-write">Altera</span> cria ou muda algo de imediato, e <span class="tool-kind tool-kind-confirm">Pede confirmação</span> só age depois do seu sim a um resumo. Ver [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao).

## Em resumo

| Ferramenta | O que faz | Papel mínimo | Tipo |
|---|---|---|---|
| [`list_companies`](#list-companies) | As empresas, com tipo, situação e tamanho da equipa | Moderador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`get_company`](#get-company) | Uma empresa | Moderador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`get_my_company`](#get-my-company) | A empresa em que está, com a equipa e o que tem através dela | Qualquer | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`create_company`](#create-company) | Regista uma empresa, com o bloco de coworking opcional | Administrador | <span class="tool-kind tool-kind-write">Altera</span> |
| [`update_company`](#update-company) | Edita o nome e o bloco de coworking | Administrador | <span class="tool-kind tool-kind-write">Altera</span> |
| [`close_company`](#close-company) | Encerra a empresa, com ou sem a equipa | Administrador | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`list_company_members`](#list-company-members) | A equipa de uma empresa | Qualquer (a API confere o vínculo) | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`invite_company_member`](#invite-company-member) | Inclui alguém na equipa pelo e-mail | Qualquer (a API confere o vínculo) | <span class="tool-kind tool-kind-write">Altera</span> |
| [`update_company_member`](#update-company-member) | Marca ou retira o admin da empresa | Administrador | <span class="tool-kind tool-kind-write">Altera</span> |
| [`remove_company_member`](#remove-company-member) | Retira alguém da equipa | Qualquer (a API confere o vínculo) | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`list_company_invitations`](#list-company-invitations) | Os convites pendentes que o admin da empresa enviou | Qualquer (a API confere o vínculo) | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_my_company_invitations`](#list-my-company-invitations) | Os seus convites de empresa | Qualquer | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`accept_company_invitation`](#accept-company-invitation) | Aceita o seu convite e entra na equipa | Qualquer (o seu convite) | <span class="tool-kind tool-kind-write">Altera</span> |
| [`decline_company_invitation`](#decline-company-invitation) | Recusa o seu convite, de vez | Qualquer (o seu convite) | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |

Os papéis são os das rotas: o assistente nunca faz mais do que a pessoa ligada faria no ecrã. O proprietário e o administrador veem as 14; o moderador e o financeiro, 10 (as duas de leitura da equipa da comunidade e as oito abertas a qualquer papel); o membro, 8 (`get_my_company`, `list_company_members`, `invite_company_member`, `remove_company_member`, `list_company_invitations`, `list_my_company_invitations`, `accept_company_invitation` e `decline_company_invitation`).

**Oito ferramentas aparecem para qualquer papel** porque o admin de uma empresa costuma ser um membro comum, e qualquer pessoa pode receber um convite. A API decide pelo vínculo: a equipa só é lida por quem é da equipa da comunidade ou da própria empresa, e só convidam e removem o proprietário, o administrador ou o admin daquela empresa, este enquanto ela está ativa. Os outros recebem "sem permissão".

**O convite do admin da empresa depende do aceite.** Nunca vincula de imediato, nem quem já é da comunidade: a pessoa recebe o convite por e-mail e entra na equipa só quando aceitar (`accept_company_invitation`). O proprietário e o administrador da comunidade continuam a vincular diretamente.

**O bloco de coworking fica com a gestão.** O tipo de residência, as datas, as ofertas (`offers`), os dados de faturação (`billing`) e o link de compra (`purchaseLink`) vêm para o proprietário, o administrador e o financeiro; o moderador só sabe se a empresa tem coworking (`coworking`). `get_my_company` traz as ofertas e o link para toda a equipa, e a faturação só para o admin da empresa.

**A empresa subscreve e paga, mas não pelo assistente.** Registar as ofertas e os dados de faturação não cobra nada. A compra é do admin da empresa, na app, pelo `purchaseLink` (o assistente nunca recebe cartão): o assistente entrega o link. Depois, o admin da empresa trata da cobrança pelas ferramentas de [Subscrições](/mcp/ferramentas-assinaturas) (`list_my_subscriptions` e `list_my_purchases` com `company_id`, `pay_my_subscription_now`, `quote_my_add_on` e `add_my_add_on`, `quote_plan_change` e `change_my_plan`, `manage_my_subscription`), com PIX ou boleto, e lê a carteira de créditos em [Créditos](/mcp/ferramentas-creditos) (`get_company_credit_balance`, `list_company_credit_entries`).

**Sair da equipa suspende a cobrança.** Ao remover alguém ou encerrar a empresa com a equipa, o resumo avisa que a cobrança da pessoa removida é suspensa; a subscrição fica registada até ao cancelamento, que se faz em [Subscrições](/mcp/ferramentas-assinaturas).

## `list_companies`

<span class="tool-kind tool-kind-read">Só consulta</span>

**As empresas**, por ordem de nome, com `coworking` (se o bloco de coworking está ligado), a situação (`active`, ou `ended` quando encerrada ou com a saída prevista no passado) e quantas pessoas há na equipa. As empresas não são membros e nunca aparecem nas listas de membros. O proprietário, o administrador e o financeiro recebem também o bloco (tipo de residência, início e saída), a data de encerramento, as ofertas, os dados de faturação e o `purchaseLink`, tudo vazio com o coworking desligado; o moderador recebe só `coworking`. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `status` | `active` ou `ended` | Não | Filtra pela situação |
| `search` | texto | Não | Parte do nome |

**Peça assim:** *"Que empresas estão ativas hoje?"*

## `get_company`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Uma empresa.** Com o bloco de coworking, as ofertas, os dados de faturação e o `purchaseLink` para o proprietário, o administrador e o financeiro, que recebem também as subscrições da empresa (`subscriptions`) e o saldo da carteira de créditos (`credit_balance`); as compras da empresa estão em `list_purchases` (`buyer.companyId`). O moderador recebe só `coworking`. Empresa de outra comunidade: "não encontrada". O admin de uma empresa usa `get_my_company`. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa (de `list_companies`) |

**Peça assim:** *"A Acme está em dia com o plano? Quantos créditos tem?"*

## `get_my_company`

<span class="tool-kind tool-kind-read">Só consulta</span>

**A sua empresa.** A empresa em que a pessoa ligada está, se ela é admin da empresa, a equipa e `canManageTeam`, verdadeiro para o admin de uma empresa ativa (falso depois de encerrada), mais as ofertas, `canPurchase` e `purchaseLink`. Para **qualquer pessoa da equipa** de uma empresa ativa, traz `benefits`: o que ela tem através da empresa, sem preço. Em `items`, os planos e produtos ativos da empresa (subscrição ativa ou compra ativa: `title`, `isPlan`, `kind`, `source`, `plan`) com os `spaces` e os `contents` que cada um liberta; em `credits`, o saldo da carteira (`balance`) e o próximo vencimento (`expiringSoon`). Com a empresa encerrada, `benefits` vem `null`. Para o admin da empresa, traz também os dados de faturação (`billing`), as subscrições (`subscriptions`, com a renovação pendente), as compras (`purchases`) e o saldo de créditos (`credit_balance`); com uma subscrição em atraso, o próximo passo sugerido é `pay_my_subscription_now`. Sem empresa, devolve `company: null`; os convites pendentes estão em `list_my_company_invitations`. *Papel mínimo: qualquer.*

Sem parâmetros.

**Peça assim:** *"O que tenho através da minha empresa?"* · *"Quem está na minha empresa?"* · *"A subscrição da minha empresa está em dia?"*

## `create_company`

<span class="tool-kind tool-kind-write">Altera</span>

**Registar uma empresa.** Só o nome é obrigatório: sem os campos de coworking, a empresa é só nome e equipa. No bloco de coworking, `offer_product_ids` lista os planos e produtos que a empresa pode contratar (só produtos digitais) e `billing`, os dados de faturação. Nada é cobrado aqui e não pede confirmação: a resposta traz o `purchaseLink`, a página em que o admin da empresa contrata, e o assistente entrega o link. Produto de outra comunidade: "não encontrado"; produto que não é digital: recusado. A empresa não ganha login; as pessoas entram com `invite_company_member`. `parcel_notice_admins_only` faz só os administradores da empresa receberem o aviso de [encomenda](/espacos/encomendas#encomenda-para-uma-empresa) (predefinição: todos os funcionários com acesso ao espaço). *Papel mínimo: administrador (proprietário ou administrador).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `name` | texto | Sim | O nome, até 120 caracteres |
| `coworking` | verdadeiro/falso | Não | Liga ou desliga o bloco de coworking. Omitido, liga quando algum campo do bloco vem preenchido |
| `residence_type` | `PRIVATE_OFFICE`, `FIXED_DESK` ou `VIRTUAL_OFFICE` | Não | Sala privada, secretária fixa ou escritório virtual |
| `offer_product_ids` | lista de ids, até 20 | Não | Os planos e produtos digitais que a empresa pode contratar (de `list_plans` ou `list_products`) |
| `billing` | `legal_name`, `tax_id` (CNPJ), `email` | Não | Os dados de faturação; cada campo é opcional e `null` apaga |
| `starts_at` | AAAA-MM-DD | Não | O início no coworking |
| `ends_at` | AAAA-MM-DD | Não | A saída prevista, não antes do início |
| `parcel_notice_admins_only` | verdadeiro/falso | Não | Só os administradores da empresa recebem o aviso de encomenda (predefinição: falso) |

**Peça assim:** *"Registe a Acme Tecnologia no coworking, sala privada, desde 1/11, podendo contratar o plano Sala privada mensal. Denominação social Acme Tecnologia Ltda, e-mail de faturação financeiro@memberfy.net."* · *"Registe a empresa Contábil Silva."*

## `update_company`

<span class="tool-kind tool-kind-write">Altera</span>

**Editar.** Só o que enviar: nome, `coworking`, tipo, ofertas, dados de faturação, início ou saída. A lista `offer_product_ids` enviada substitui a anterior (`[]` ou `null` limpa). `null` apaga um campo do bloco; preencher um campo liga o coworking; `coworking: false` desliga e apaga o bloco inteiro. Para encerrar já, use `close_company`. *Papel mínimo: administrador (proprietário ou administrador).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa |
| `name`, `coworking`, `residence_type`, `offer_product_ids`, `billing`, `starts_at`, `ends_at`, `parcel_notice_admins_only` | vários | Não | Só o que mudar |

**Peça assim:** *"A Acme sai a 31/12. Atualize a saída prevista."* · *"Na Acme, avise só os administradores quando chegar uma encomenda."*

## `close_company`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Encerrar a empresa já.** A empresa deixa de aceitar convites, de dar acesso à equipa e de ser cobrada; o registo e o bloco de coworking continuam guardados. Não há reabertura. Com `remove_members` (predefinição: verdadeiro), todos saem da equipa, e quem entrou na comunidade através da empresa e ainda é membro sai também da comunidade. O resumo lista quem sai e avisa que a cobrança dessas pessoas é suspensa e a subscrição fica registada até ao cancelamento. Empresa já encerrada: recusado. Na primeira chamada devolve o resumo e o código de confirmação. *Papel mínimo: administrador (proprietário ou administrador).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa |
| `remove_members` | verdadeiro/falso | Não | Predefinição: verdadeiro. Falso mantém a equipa vinculada à empresa encerrada |

**Peça assim:** *"Encerre a Acme e retire a equipa dela."*

## `list_company_members`

<span class="tool-kind tool-kind-read">Só consulta</span>

**A equipa de uma empresa**, com os admins primeiro: nome, cargo, se é admin da empresa, se entrou através da empresa e, para a equipa da comunidade e o admin da empresa, o e-mail. Leem-na quem é da equipa da comunidade ou da própria empresa. *Papel mínimo: qualquer (a API confere o vínculo).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa (de `list_companies` ou `get_my_company`) |

**Peça assim:** *"Mostre a equipa da Acme."*

## `invite_company_member`

<span class="tool-kind tool-kind-write">Altera</span>

**Incluir na equipa pelo e-mail.** Pelo **proprietário ou administrador**, vincula de imediato: quem já é da comunidade só ganha o vínculo, sem e-mail (`linked`); quem não é entra na comunidade como membro e **recebe o convite por e-mail** (`invited`): o assistente avisa antes. Pelo **admin da empresa**, nunca vincula: a resposta é sempre `invited` com `pending: true` e o `invitation_id`, seja quem for a pessoa, e o assistente diz *"Convite enviado. A pessoa entra na equipa quando aceitar."*, sem afirmar se ela já era da comunidade. Recusado se a comunidade não está a aceitar novos membros, se a pessoa pediu para não participar, se ela já está nesta equipa ou se a empresa está encerrada; para o proprietário e o administrador, também se ela já está noutra empresa. Convidam o proprietário, o administrador e o admin daquela empresa enquanto ela está ativa; `is_admin` só o proprietário e o administrador. O admin da empresa envia até 30 convites por hora (acima disso, 429 com `Retry-After`); o proprietário e o administrador não têm esse limite. *Papel mínimo: qualquer (a API confere o vínculo).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa |
| `email` | texto | Sim | O e-mail da pessoa |
| `name` | texto | Não | O nome, se a conta for criada agora |
| `is_admin` | verdadeiro/falso | Não | Já entra como admin da empresa (proprietário ou administrador) |

**Peça assim:** *"Convide joao@memberfy.net para a equipa da minha empresa."*

## `update_company_member`

<span class="tool-kind tool-kind-write">Altera</span>

**Marcar ou retirar o admin da empresa.** O admin da empresa convida e remove a própria equipa. *Papel mínimo: administrador (proprietário ou administrador).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa |
| `member_id` | id | Sim | A pessoa (de `list_company_members`) |
| `is_admin` | verdadeiro/falso | Sim | Verdadeiro marca; falso retira |

**Peça assim:** *"Deixe a Maria como admin da Acme."*

## `remove_company_member`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Retirar alguém da equipa.** Se a pessoa entrou na comunidade através da empresa e ainda é membro, sai também da comunidade e perde o acesso; se já era da comunidade, só perde o vínculo. O resumo diz qual dos dois e avisa que a cobrança da pessoa removida é suspensa e a subscrição fica registada até ao cancelamento. Removem o proprietário, o administrador e o admin daquela empresa enquanto ela está ativa. Na primeira chamada devolve o resumo e o código de confirmação. *Papel mínimo: qualquer (a API confere o vínculo).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa |
| `member_id` | id | Sim | A pessoa (de `list_company_members`) |

**Peça assim:** *"Retire o João da equipa da Acme; ele saiu da empresa."*

## `list_company_invitations`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Os convites pendentes da empresa**: os que o admin da empresa enviou e ninguém respondeu, do mais recente ao mais antigo, com o e-mail escrito e a data. Nunca diz quem é a pessoa nem se ela já era da comunidade. Os convites do proprietário e do administrador vinculam de imediato e não aparecem aqui. Leem-nos a equipa da comunidade e o admin daquela empresa enquanto ela está ativa. *Papel mínimo: qualquer (a API confere o vínculo).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa |

**Peça assim:** *"Quem convidei para a minha empresa e ainda não aceitou?"*

## `list_my_company_invitations`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Os seus convites.** Os convites pendentes da pessoa ligada para entrar numa equipa (*"foi convidado para a empresa X"*), do mais recente ao mais antigo, com a empresa, quem convidou e a data. Só empresas ativas desta comunidade; sem convites, lista vazia. *Papel mínimo: qualquer.*

Sem parâmetros.

**Peça assim:** *"Tenho algum convite de empresa?"*

## `accept_company_invitation`

<span class="tool-kind tool-kind-write">Altera</span>

**Aceitar o seu convite.** A pessoa entra na equipa (sem ser admin da empresa). Não pede confirmação. Convite de outra pessoa, já respondido ou de outra comunidade: "não encontrado". Empresa encerrada depois do convite, ou pessoa já na equipa de outra empresa: recusado, com a mensagem da API. *Papel mínimo: qualquer (o seu convite).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `invitation_id` | id | Sim | O convite (de `list_my_company_invitations`) |

**Peça assim:** *"Aceite o convite da Acme."*

## `decline_company_invitation`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Recusar o seu convite.** Nenhum vínculo é criado e o convite desaparece de vez: para entrar depois, só com um convite novo. Na primeira chamada devolve o resumo e o código de confirmação. *Papel mínimo: qualquer (o seu convite).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `invitation_id` | id | Sim | O convite (de `list_my_company_invitations`) |

**Peça assim:** *"Recuse o convite da Acme."*

## Receitas sugeridas

- **Registar uma empresa:** registar a empresa com as ofertas (`create_company`), entregar o `purchaseLink`, convidar quem vai tratar dela (`invite_company_member`) e marcar essa pessoa como admin da empresa (`update_company_member`, ou `is_admin` logo no convite). Passo a passo em [Receitas](/mcp/receitas#69-registar-uma-empresa).
- **O admin convida e a pessoa aceita:** o admin da empresa convida o colega (`invite_company_member`) e acompanha em `list_company_invitations`; o colega vê o convite (`list_my_company_invitations`) e aceita (`accept_company_invitation`). Passo a passo em [Receitas](/mcp/receitas#70-convidar-um-colega-para-a-sua-empresa).
- **O que tenho através da empresa:** qualquer pessoa da equipa pergunta, e o assistente responde com o `benefits` de `get_my_company` (planos, conteúdos e créditos da empresa, sem preço). Passo a passo em [Receitas](/mcp/receitas#72-o-que-tenho-atraves-da-minha-empresa).

## Relacionados

- [Empresas](/membros/empresas)
- [Ferramentas](/mcp/ferramentas)
- [Ferramentas · Membros](/mcp/ferramentas-membros)
- [Ferramentas · Subscrições](/mcp/ferramentas-assinaturas)
- [Ferramentas · Créditos](/mcp/ferramentas-creditos)
- [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao)
- [Receitas](/mcp/receitas)