# Equipe

Estas rotas devolvem a **equipe** da empresa: quem são os colaboradores, quem trabalha em qual evento e quantos eventos cada um fez. Servem para folha e ponto externos, escala em planilha e aviso de convocação por outro canal.

**Escopo exigido:** `team:read`. Sem ele, as rotas respondem [`scope_missing`](https://developers.festero.com.br/errors.md#scope_missing).

O colaborador é pessoa física: sai só o **nome, o tipo e a função**. Nunca saem documento, e-mail, telefone, endereço, diária combinada, chave Pix nem anotações.

[Testar na referência interativa](https://developers.festero.com.br/referencia/)

## Colaboradores

### `GET /v1/team/collaborators`

Lista os colaboradores, da alteração mais antiga para a mais recente. [Paginação por cursor](https://developers.festero.com.br/paginacao.md).

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `type` | texto | `employee`, `freelancer` ou `contractor`. Outro valor responde `400`. |
| `updatedSince`, `limit`, `cursor` | | Como nas demais listas. |

Campos: `id`, `name`, `type`, `role`, `createdAt` e `updatedAt`.

### `GET /v1/team/collaborators/{id}`

Devolve um colaborador pelo identificador. `404` se não existe ou é de outra empresa. Traz `ETag`.

## Escala

### `GET /v1/team/schedule`

Mostra quem trabalha em qual evento num período de **até 62 dias** (como a tela de Escala). Eventos cancelados não aparecem.

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `from` | data `yyyy-MM-dd` | Primeiro dia. Obrigatório. |
| `to` | data `yyyy-MM-dd` | Último dia (inclusive). Obrigatório. |

Cada item de `assignments` traz o vínculo (`staffId`), o `event` (`id` e título), `eventDate`, `eventTime`, `durationHours`, `eventStatus`, `isRental`, `rentalReturnDate`, o `collaborator` (nulo quando a pessoa foi alocada sem cadastro), o `name` na escala, a `role` neste evento e o `status` do convite (`pending`, `confirmed`, `paid` ou `cancelled`). Não traz valor combinado, cliente nem local do evento.

## Desempenho

### `GET /v1/team/performance`

Os mesmos números da aba **Equipe** dos relatórios: `totalStaff`, `activeStaff` (com ao menos uma alocação) e, para cada colaborador (até 500), `eventsAssigned`, `eventsCompleted` e `completionRate` (de 0 a 100). Soma toda a história: a tela só aplica o período à contagem de ativos, e por isso esta rota não tem período.