# Ferramentas · Encomendas

> Ferramentas MCP do módulo Encomendas (coworking): registrar cartas e pacotes com foto, a fila, retirada, devolução, descarte, reabertura, exclusão e o "tenho encomenda?" do membro.

O módulo [Encomendas](/espacos/encomendas) pelo assistente: registrar a encomenda com foto e avisar o membro, acompanhar a fila, mexer nas fotos, marcar a retirada, devolver, descartar, reabrir e excluir, e o membro perguntar se tem algo esperando. São **16 ferramentas**.

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 na hora, 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 |
|---|---|---|---|
| [`get_parcels_overview`](#get-parcels-overview) | O espaço de relance: a configuração e quantas aguardam | Qualquer que veja o espaço | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`get_parcel`](#get-parcel) | Uma encomenda, com as fotos | Qualquer (a sua); equipe (qualquer) | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`do_i_have_parcels`](#do-i-have-parcels) | As suas encomendas, pendentes e histórico, com o local e o código | Qualquer | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`mark_parcel_picked_up`](#mark-parcel-picked-up) | Marca a retirada | Qualquer (a sua); moderador ou financeiro (de outros) | <span class="tool-kind tool-kind-write">Altera</span> |
| [`search_parcel_recipients`](#search-parcel-recipients) | Acha o destinatário pelo nome | Moderador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`register_parcel`](#register-parcel) | Registra a encomenda e avisa o destinatário por e-mail | Moderador ou financeiro | <span class="tool-kind tool-kind-write">Altera</span> |
| [`list_pending_parcels`](#list-pending-parcels) | A fila das que aguardam retirada | Moderador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_parcels`](#list-parcels) | O histórico, com qualquer situação | Moderador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`update_parcel`](#update-parcel) | Corrige os dados e o código do locker | Moderador ou financeiro (aguardando); administrador (encerrada) | <span class="tool-kind tool-kind-write">Altera</span> |
| [`add_parcel_photo`](#add-parcel-photo) | Adiciona uma foto | Moderador ou financeiro | <span class="tool-kind tool-kind-write">Altera</span> |
| [`replace_parcel_photo`](#replace-parcel-photo) | Troca uma foto | Moderador ou financeiro | <span class="tool-kind tool-kind-write">Altera</span> |
| [`return_parcel`](#return-parcel) | Devolve ao remetente | Moderador ou financeiro | <span class="tool-kind tool-kind-write">Altera</span> |
| [`remove_parcel_photo`](#remove-parcel-photo) | Remove uma foto de vez | Moderador ou financeiro | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`discard_parcel`](#discard-parcel) | Descarta uma encomenda não retirada | Administrador | <span class="tool-kind tool-kind-write">Altera</span> |
| [`reopen_parcel`](#reopen-parcel) | Desfaz um fechamento | Administrador | <span class="tool-kind tool-kind-write">Altera</span> |
| [`delete_parcel`](#delete-parcel) | Exclui um registro feito por engano | Administrador | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |

O espaço se cria com [`create_space`](/mcp/ferramentas-comunidade#create-space) e `module: "parcels"`, com o argumento `parcels` para a configuração; [`update_space`](/mcp/ferramentas-comunidade#update-space) muda só o que você mandar e mantém o resto.

A equipe, aqui, é o proprietário, o administrador, o moderador e o financeiro. Os papéis são os das rotas: o assistente nunca faz mais do que a pessoa conectada faria na tela. O proprietário e o administrador veem as 16 ferramentas; o moderador e o financeiro, 13 (sem descartar, reabrir e excluir); o membro, 4 (`get_parcels_overview`, `get_parcel`, `do_i_have_parcels` e `mark_parcel_picked_up`, nas próprias encomendas).

**O código do locker é um segredo.** Nenhuma resposta da equipe o traz, e ele fica oculto no registro de auditoria do MCP; só `do_i_have_parcels` e `get_parcel` o mostram, ao próprio destinatário. Quem registra ou corrige pode **definir** o código, nunca lê-lo, e o assistente não o repete.

## A configuração do espaço

O argumento `parcels` de `create_space` e `update_space` aceita:

| Campo | Tipo | Descrição |
|---|---|---|
| `locker_mode` | `none` ou `free` | `none`: tudo fica na recepção; `free`: a equipe escreve onde deixou cada encomenda |
| `locker_pickup_code` | verdadeiro ou falso | A equipe pode definir um código de retirada por encomenda; só o destinatário o vê |
| `email_includes_photo` | verdadeiro ou falso | O e-mail de aviso leva uma miniatura da foto (padrão: sim) |
| `require_staff_confirmation` | verdadeiro ou falso | Verdadeiro: só a equipe marca a retirada. Falso (padrão): o membro também |
| `reminder_after_days`, `reminder_max_count` | números, ou `null` | Prazo de parada e teto de lembretes. Já são aceitos, mas o lembrete ainda não roda |

## `get_parcels_overview`

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

**O espaço de relance.** A configuração (modo de locker e se o membro confirma a própria retirada), quantas encomendas aguardam **você** (`mine.pendingCount`) e, para a equipe, quantas estão pendentes e paradas. *Papel mínimo: qualquer que veja o espaço.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | O espaço Encomendas |

**Peça assim:** *"Quantas encomendas estão paradas na Unidade Centro?"*

## `get_parcel`

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

**Uma encomenda.** Com as fotos, em links assinados que valem 1 hora. A equipe lê qualquer encomenda da comunidade, sem o código; o destinatário lê a sua, com o local e o código enquanto ela aguarda. Qualquer outra pessoa recebe "não encontrada". *Papel mínimo: qualquer.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `parcel_id` | id | Sim | A encomenda (de `list_pending_parcels`) |

**Peça assim:** *"Mostre a encomenda da Maria."*

## `do_i_have_parcels`

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

**"Tenho encomenda?"** Só as **suas**: as pendentes (todas) e o histórico (as últimas), com onde retirar, o código do locker enquanto aguarda e as fotos (links de 1 hora). Mostre o código só à própria pessoa. *Papel mínimo: qualquer.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Não | Um espaço específico; sem ele, todos |
| `history_limit` | número | Não | Quantas do histórico (1 a 100) |

**Peça assim:** *"Tenho alguma encomenda esperando?"*

## `mark_parcel_picked_up`

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

**Marcar a retirada.** A equipe marca como `STAFF` (padrão, com o nome de quem veio em `picked_up_by_name`, que por padrão é o destinatário) ou `THIRD_PARTY` (o nome é obrigatório). O próprio destinatário marca como `SELF`, só se o espaço não exige a confirmação da equipe (senão, recusado). O código do locker é apagado. É **idempotente**: numa encomenda já encerrada, devolve `already_closed: true`. *Papel mínimo: qualquer (a sua); moderador ou financeiro (de outros).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `parcel_id` | id | Sim | A encomenda (de `list_pending_parcels`) |
| `method` | `STAFF`, `SELF` ou `THIRD_PARTY` | Não | Como foi retirada |
| `picked_up_by_name` | texto | Não | Quem veio buscar (obrigatório em `THIRD_PARTY`) |

**Peça assim:** *"Marque como retirada a encomenda da Maria."* · *"Já peguei a minha encomenda."*

## `search_parcel_recipients`

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

**Quem recebe.** Os membros do espaço cujo nome começa com `q` (pelo menos 3 letras, até 8 resultados), só com id, nome e iniciais. O `id` é o `recipient_profile_id` de `register_parcel`. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | O espaço Encomendas |
| `q` | texto | Sim | O começo do nome |

**Peça assim:** *"Procure a Maria Souza para registrar uma encomenda."*

## `register_parcel`

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

**Registrar a encomenda.** Para um membro com acesso ao espaço. **Envia ao destinatário o e-mail de aviso** (com a miniatura, se o espaço está assim), no fuso da comunidade: o assistente diz isso. `kind` é `LETTER`, `PACKAGE` ou `OTHER` (este pede `kind_label`). `locker_label` e `locker_pickup_code` (de 4 a 12 caracteres, um segredo) só valem se o espaço permite. `client_request_id` faz uma chamada repetida devolver a mesma encomenda, sem segundo e-mail. Mesmo destinatário, tipo e rastreio em 24 horas é recusado (409), a menos que `force` seja verdadeiro. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | O espaço Encomendas |
| `recipient_profile_id` | id | Sim | De `search_parcel_recipients` |
| `kind` | `LETTER`, `PACKAGE` ou `OTHER` | Sim | O tipo |
| `kind_label` | texto | Com `OTHER` | Até 60 caracteres |
| `sender_name`, `carrier`, `tracking_code` | texto | Não | Remetente, transportadora e rastreio |
| `notes` | texto | Não | Até 200 caracteres |
| `locker_label`, `locker_pickup_code` | texto | Não | Onde ficou e o código |
| `photos` | lista | Não | Até 5, cada uma com `image_url` ou `image_base64` |
| `client_request_id`, `force` | texto, verdadeiro/falso | Não | Idempotência e registro de duplicata |

**Peça assim:** *"Chegou um pacote da Amazon para a Maria Souza, no armário 12. Foto: [link]."*

## `list_pending_parcels`

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

**A fila.** As que aguardam retirada, da mais nova à mais antiga, com destinatário, tipo, remetente, local, há quanto tempo esperam e `stalled_days` quando passaram do prazo. Filtros: `kind`, `q` (destinatário, remetente, transportadora ou rastreio), `stalled`, `recipient_profile_id`, `from` e `to` (AAAA-MM-DD, no fuso da comunidade). Nunca o código (só `has_locker_code`). *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | O espaço Encomendas |
| `kind`, `q`, `stalled`, `recipient_profile_id`, `from`, `to` | vários | Não | Os filtros |
| `page`, `limit` | números | Não | Paginação (até 100) |

**Peça assim:** *"O que está parado na recepção há mais de 3 dias?"*

## `list_parcels`

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

**O histórico.** Igual a `list_pending_parcels`, mas com qualquer situação (`RECEIVED`, `PICKED_UP`, `RETURNED`, `DISCARDED`), filtrável por `status`. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `space` | id ou link | Sim | O espaço Encomendas |
| `status` | situação | Não | Filtra pela situação |
| os filtros de `list_pending_parcels` | vários | Não | |

**Peça assim:** *"Quais encomendas foram devolvidas este mês?"*

## `update_parcel`

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

**Corrigir.** Tipo, remetente, transportadora, rastreio, observação, local e código do locker (que se define de novo, nunca se lê) de uma encomenda que aguarda. Uma encomenda encerrada só é corrigida por proprietário ou administrador, e nunca o código. Cada correção entra no registro. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `parcel_id` | id | Sim | A encomenda (de `list_pending_parcels`) |
| `kind`, `kind_label`, `sender_name`, `carrier`, `tracking_code`, `notes`, `locker_label`, `locker_pickup_code` | vários | Não | Só o que mudar |

**Peça assim:** *"Corrija o rastreio da encomenda da Maria para BR123456789."*

## `add_parcel_photo`

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

**Adicionar uma foto.** Até 5 por encomenda, em armazenamento privado. A equipe; em encomenda encerrada, só proprietário e administrador. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `parcel_id` | id | Sim | A encomenda (de `list_pending_parcels`) |
| `image_url` ou `image_base64` (+ `image_type`) | texto | Sim | A foto: um link público ou o arquivo em base64. Fica em armazenamento privado |

**Peça assim:** *"Anexe esta foto à encomenda da Maria."*

## `replace_parcel_photo`

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

**Trocar uma foto.** Troca uma foto pelo arquivo novo; o antigo é apagado. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `parcel_id` | id | Sim | A encomenda (de `list_pending_parcels`) |
| `photo_id` | id | Sim | A foto (de `get_parcel`) |
| `image_url` ou `image_base64` (+ `image_type`) | texto | Sim | A foto: um link público ou o arquivo em base64. Fica em armazenamento privado |

**Peça assim:** *"Troque a primeira foto da encomenda por esta."*

## `return_parcel`

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

**Devolver ao remetente.** Exige o motivo. Nada é apagado: a encomenda fica no histórico como `RETURNED` e o código do locker é apagado. Uma encomenda já encerrada responde 409. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `parcel_id` | id | Sim | A encomenda (de `list_pending_parcels`) |
| `reason` | texto | Sim | O motivo, até 200 caracteres; fica no registro |

**Peça assim:** *"Devolva ao remetente a encomenda da Maria: recusada."*

## `remove_parcel_photo`

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

**Remover uma foto.** O arquivo é apagado de vez. Na primeira chamada devolve o resumo e o código de confirmação. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `parcel_id` | id | Sim | A encomenda (de `list_pending_parcels`) |
| `photo_id` | id | Sim | A foto (de `get_parcel`) |

**Peça assim:** *"Remova a segunda foto da encomenda; ela mostra o endereço."*

## `discard_parcel`

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

**Descartar.** Para a que ninguém retirou. Exige o motivo. Nada é apagado: fica como `DISCARDED` no histórico, e `reopen_parcel` desfaz. Não pede confirmação, por ser reversível. *Papel mínimo: administrador (proprietário ou administrador).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `parcel_id` | id | Sim | A encomenda (de `list_pending_parcels`) |
| `reason` | texto | Sim | O motivo, até 200 caracteres; fica no registro |

**Peça assim:** *"Descarte a encomenda da Maria: vencida sem retirada."*

## `reopen_parcel`

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

**Reabrir.** Desfaz uma retirada, devolução ou descarte por engano: volta a `RECEIVED`, com o motivo. O código apagado não volta; defina outro com `update_parcel`. *Papel mínimo: administrador (proprietário ou administrador).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `parcel_id` | id | Sim | A encomenda (de `list_pending_parcels`) |
| `reason` | texto | Sim | O motivo, até 200 caracteres; fica no registro |

**Peça assim:** *"Reabra a encomenda da Maria: a retirada foi marcada por engano."*

## `delete_parcel`

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

**Excluir um registro feito por engano.** Sai das listas e as fotos são apagadas; o registro guarda quem e por quê. Para encerrar uma encomenda de verdade, use `mark_parcel_picked_up`, `return_parcel` ou `discard_parcel`. 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 |
|---|---|---|---|
| `parcel_id` | id | Sim | A encomenda (de `list_pending_parcels`) |
| `reason` | texto | Sim | O motivo, até 200 caracteres; fica no registro |

**Peça assim:** *"Exclua o registro da encomenda do João: registrei para a pessoa errada."*

## Relacionados

- [Encomendas](/espacos/encomendas)
- [Ferramentas](/mcp/ferramentas)
- [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao)
- [Receitas](/mcp/receitas)