API Reference · Área de Trabalho

Convenções

As rotas recebem Authorization: Bearer <credencial>. Todas as operações deste domínio exigem credencial válida; a régua fina depende do registro e está declarada em cada operação.

Toda operação também pode responder os erros transversais abaixo, além dos declarados em cada uma.

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Propriedade não prevista no contrato, tipo inválido ou cursor ilegível.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`ACCESS_PROFILE_UNMAPPED`	Conta sem Perfil de Acesso convertido.
429	`RATE_LIMITED`	Mais de 100 requisições em 60 segundos.

Identidade pessoal. As escritas de Trabalho, pessoas ligadas, comentários, Modelos, e todas as operações de visões salvas, agendas e preferências exigem uma identidade que represente uma Pessoa. Um Token de Sistema recebe 403 FORBIDDEN com a mensagem “Token de Sistema não representa Pessoa”. As leituras de Trabalho, pessoas ligadas, comentários, trilha, diretório de usuários e Grupos de Trabalho aceitam Token de Sistema.

As listagens paginam por cursor. limit tem padrão 50, mínimo 1 e máximo 200. cursor é opaco e vem de nextCursor da página anterior; nextCursor nulo indica o fim.

As datas e horas de entrada e saída são instantes ISO 8601. baseDate é a única data civil, no formato YYYY-MM-DD.

Corpo de erro — JSON

Campo	Tipo	Presença	Descrição
`statusCode`	number	Sempre	Repete o status HTTP.
`message`	string ou array de strings	Sempre	Mensagem legível; a validação pode retornar várias mensagens.
`errorCode`	string	Sempre nos erros da aplicação	Código estável: `VALIDATION_FAILED`, `RULE_VIOLATION`, `NOT_FOUND`, `FORBIDDEN`, `UNAUTHORIZED`, `CONFLICT`, entre outros.
`error`	string	Condicional	Nome do status HTTP.

Página com cursor — JSON

Campo	Tipo	Descrição
`items`	array	Registros da página, no tipo da operação.
`nextCursor`	string ou `null`	Cursor da próxima página; `null` indica o fim.

Trabalho — campos de saída

O objeto devolvido pelas operações de Trabalho tem os campos abaixo.

Campo	Tipo	Descrição
`id`	string	Identificador do Trabalho.
`kind`	`activity` ou `appointment`	Tipo do Trabalho.
`category`	enum de categorias	Categoria dentro do tipo.
`title`	string	Título.
`body`	string ou `null`	Descrição; no Compromisso, também a pauta.
`tags`	array de strings	Etiquetas livres.
`priority`	`low`, `medium`, `high`, `urgent` ou `null`	Prioridade declarada.
`status`	`pending`, `in_progress`, `completed`, `cancelled`, `postponed`, `no_show` ou `overdue`	Estado publicado; `overdue` é derivado na leitura.
`statusLabelId`	string ou `null`	Situação do quadro do núcleo.
`dueAt`	data-hora ou `null`	Vencimento da Atividade.
`scheduledAt`	data-hora ou `null`	Hora marcada do Compromisso.
`durationMin`	number ou `null`	Duração prevista, em minutos.
`location`	string ou `null`	Local.
`meetingUrl`	string ou `null`	Endereço do encontro remoto.
`meetingFormat`	`in_person`, `remote`, `hybrid` ou `null`	Formato do encontro.
`preclusionRule`	`calendar_days`, `business_days`, `calendar_days_business_end` ou `null`	Regra aplicada no cálculo do prazo.
`stateCode`	string ou `null`	Unidade federativa da competência do prazo.
`ibgeCode`	string ou `null`	Código do município da competência.
`templateId`	string ou `null`	Modelo de origem.
`guidelineId`	string ou `null`	Orientação reutilizável citada.
`guidanceText`	string ou `null`	Orientação própria deste Trabalho.
`parentId`	string ou `null`	Trabalho de origem.
`originRule`	string ou `null`	Regra do sistema que originou o Trabalho.
`ownerUserId`	string	Dono do Trabalho.
`nucleos`	array de strings	Siglas de núcleo e códigos de subnúcleo responsáveis, em caixa alta.
`confidential`	boolean	Marca de sigilo.
`cancelReason`	string ou `null`	Motivo do cancelamento.
`personId`	string ou `null`	Pessoa a quem o Trabalho se refere.
`caseId`	string ou `null`	Processo ligado.
`subtype`	`conciliation`, `instruction`, `medical`, `social` ou `null`	Subtipo de audiência ou perícia. Em implementação.
`presidingName`	string de até 255 caracteres ou `null`	Nome exibido de quem preside o Compromisso. Pode vir da Pessoa vinculada ou de nome livre sem cadastro. Em implementação.
`caseMovementId`	string ou `null`	Movimentação do processo vinculada ao Trabalho. Em implementação.
`consultationId`	string ou `null`	Entrevista ligada.
`associationId`	string ou `null`	Associação alcançada.
`openChildren`	array de Trabalhos	Filhos diretos pendentes ou em execução, dos mais antigos aos mais novos. Os filhos trazem o estado gravado, sem `overdue`, e não trazem `openChildren`.
`createdAt`	data-hora	Criação.
`updatedAt`	data-hora	Última alteração.

Trabalho

`POST /v1/work-items`

Cria uma Atividade ou um Compromisso. O dono é sempre a identidade autenticada e o Trabalho nasce pendente.

Autenticação e autorização: Bearer de identidade pessoal com perfil Operacional Autônomo ou superior.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`kind`	`activity` ou `appointment`	Sim	Tipo do Trabalho.
Corpo	`category`	enum de categorias	Sim	Deve pertencer ao tipo.
Corpo	`title`	string, 1 a 255 caracteres	Sim	Título do Trabalho.
Corpo	`body`	string, até 100000 caracteres	Não	Descrição.
Corpo	`tags`	array de strings, até 20 itens de 1 a 64 caracteres	Não	Etiquetas livres.
Corpo	`priority`	`low`, `medium`, `high` ou `urgent`	Não	Prioridade declarada.
Corpo	`dueAt`	data-hora	Não	Vencimento pronto; mutuamente exclusivo com `baseDate`.
Corpo	`baseDate`	data civil `YYYY-MM-DD`	Não	Data-base da contagem; exige `days`.
Corpo	`days`	inteiro de 0 a 3650	Com `baseDate`	Quantidade de dias do prazo.
Corpo	`stateCode`	string de 2 caracteres	Não	Unidade federativa da competência.
Corpo	`ibgeCode`	string de 7 caracteres	Não	Município da competência.
Corpo	`scheduledAt`	data-hora	Não	Hora marcada; apenas em Compromisso.
Corpo	`durationMin`	inteiro de 1 a 1440	Não	Duração; apenas em Compromisso.
Corpo	`location`	string, até 255 caracteres	Não	Local.
Corpo	`meetingUrl`	string, até 300 caracteres	Não	Encontro remoto; apenas em Compromisso.
Corpo	`meetingFormat`	`in_person`, `remote` ou `hybrid`	Não	Formato; apenas em Compromisso.
Corpo	`templateId`	UUID	Não	Modelo de onde vêm dias e regra de contagem; considerado apenas se habilitado.
Corpo	`guidelineId`	UUID	Não	Orientação reutilizável; mutuamente exclusiva com `guidanceText`.
Corpo	`guidanceText`	string, até 100000 caracteres	Não	Orientação própria.
Corpo	`parentId`	UUID	Não	Trabalho de origem, do mesmo tipo.
Corpo	`confidential`	boolean	Não	Restringe o Trabalho a quem tem ligação direta com ele.
Corpo	`personId`	UUID	Não	Pessoa a quem o Trabalho se refere.
Corpo	`caseId`	UUID	Não	Processo ligado.
Corpo	`subtype`	`conciliation`, `instruction`, `medical` ou `social`	Não	`conciliation` ou `instruction` só em `hearing`; `medical` ou `social` só em `expert_examination`; outra combinação responde `422`. Em implementação.
Corpo	`caseMovementId`	UUID	Não	Movimentação do mesmo processo de `caseId`; de outro processo responde `422`. Em implementação.
Corpo	`consultationId`	UUID	Não	Entrevista ligada.
Corpo	`associationId`	UUID	Não	Associação alcançada.

Saída

HTTP	Campo	Tipo	Descrição
201	corpo	Trabalho	O Trabalho criado, conforme os campos de saída das Convenções.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Perfil abaixo de Operacional Autônomo.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Orientação reutilizável (`guidelineId`) inexistente.
422	`RULE_VIOLATION`	Categoria fora do tipo; prazo declarado duas vezes; `baseDate` sem `days`; `baseDate` que não é uma data civil existente; orientação declarada em duas formas; campo de hora marcada em Atividade; categoria sem contagem de prazo; Pessoa inexistente; Trabalho de origem inexistente, de outro tipo ou fora do limite da árvore.
422	`RULE_VIOLATION`	Subtipo que não pertence à categoria; `caseMovementId` de outro processo. Em implementação.
500	`INTERNAL`	Falha ao gravar ou ao consultar o calendário.

Condições: com templateId de um Modelo habilitado, days e a regra de contagem vêm do Modelo e prevalecem sobre days do corpo. Um Modelo desabilitado é ignorado, e a regra volta a sair da categoria. Os demais campos do Modelo não são copiados para o Trabalho. presidingName não pertence à criação genérica; quem preside é definido pelo PUT /v1/work-items/{id}/people/presiding.

`GET /v1/work-items`

Lista os Trabalhos que a identidade alcança. O alcance, os filtros, a busca e a ordenação são resolvidos na própria consulta.

Autenticação e autorização: Bearer de qualquer identidade autenticada. O alcance por registro é aplicado na consulta.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Query	`cursor`	string	Não	Cursor da página anterior.
Query	`limit`	inteiro de 1 a 200	Não	Tamanho da página; padrão `50`.
Query	`kind`	`activity` ou `appointment`	Não	Ausente, traz os dois tipos.
Query	`category`	array de categorias	Não	Valores do eixo combinam por união.
Query	`status`	array de estados publicados	Não	Aceita `overdue`, traduzido em Compromisso pendente com hora marcada no passado.
Query	`priority`	array de prioridades	Não	Combina por união.
Query	`tags`	array de strings, até 20 itens	Não	Casa quem tem qualquer uma das etiquetas.
Query	`nucleusSigla`	string, 1 a 40 caracteres	Não	Sigla de núcleo ou código de subnúcleo, comparado em caixa alta e de forma literal com `nucleos`: a sigla de um núcleo não traz Trabalhos carimbados apenas com o código de um subnúcleo dele.
Query	`statusLabelId`	UUID	Não	Situação do quadro.
Query	`ownerUserId`	UUID	Não	Dono do Trabalho.
Query	`assigneeUserId`	UUID	Não	Quem responde pelo Trabalho.
Query	`groupId`	UUID	Não	Grupo de trabalho ligado.
Query	`parentId`	UUID	Não	Trabalho de origem.
Query	`templateId`	UUID	Não	Modelo de origem.
Query	`personId`	UUID	Não	Pessoa referida.
Query	`caseId`	UUID	Não	Processo ligado.
Query	`caseMovementId`	UUID	Não	Movimentação do processo vinculada ao Trabalho. Em implementação.
Query	`consultationId`	UUID	Não	Entrevista ligada.
Query	`search`	string, até 120 caracteres	Não	Busca por prefixo em título, descrição, local e etiquetas; termo com menos de dois caracteres é ignorado.
Query	`dueBefore` / `dueAfter`	data-hora	Não	Janela exclusiva sobre o vencimento.
Query	`from` / `to`	data-hora	Não	Janela inclusiva sobre a hora marcada.
Query	`completedFrom` / `completedTo`	data-hora	Não	Janela inclusiva sobre a conclusão.
Query	`createdFrom` / `createdTo`	data-hora	Não	Janela inclusiva sobre a criação.
Query	`updatedFrom` / `updatedTo`	data-hora	Não	Janela inclusiva sobre a última alteração.
Query	`trashed`	boolean	Não	`true` lista a lixeira, com régua própria; padrão `false`.
Query	`orderBy`	`dueAt`, `scheduledAt`, `priority`, `status` ou `title`	Não	Ausente, ordena pela criação.
Query	`orderDir`	`asc` ou `desc`	Não	Padrão `desc`.

Saída

HTTP	Campo	Tipo	Descrição
200	`items`	array de Trabalhos	Página já restrita ao alcance da identidade.
200	`nextCursor`	string ou `null`	Cursor da próxima página.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Consulta fora do contrato ou cursor ilegível.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
500	`INTERNAL`	Falha na consulta.

`GET /v1/work-items/{id}`

Devolve o Trabalho com o estado derivado e os filhos diretos ainda abertos.

Autenticação e autorização: Bearer de identidade que alcança o Trabalho. Quem não alcança recebe 404.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	Trabalho	O Trabalho, com `openChildren`.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
404	`NOT_FOUND`	Trabalho inexistente, na lixeira ou fora do alcance.
500	`INTERNAL`	Falha na consulta.

`PATCH /v1/work-items/{id}`

Altera o Trabalho. Com status, executa a transição de estado.

Autenticação e autorização: Bearer de identidade que alcança e pode alterar o Trabalho.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho.
Corpo	`status`	`pending`, `in_progress`, `completed`, `cancelled`, `postponed` ou `no_show`	Não	A transição precisa ser admitida a partir do estado atual, e o estado precisa pertencer ao tipo: `in_progress` é da Atividade, `postponed` e `no_show` são do Compromisso.
Corpo	`cancelReason`	string, 1 a 500 caracteres	Com `status: cancelled`	Motivo do cancelamento.
Corpo	demais campos	iguais aos de `POST /v1/work-items`	Não	Os campos da criação são aceitos, exceto a mudança de `kind`; `presidingName` também não é aceito. `baseDate`, `days` e `templateId` não recalculam o prazo nem a regra de contagem; o vencimento muda por `dueAt`.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	Trabalho	O Trabalho alterado.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	A identidade alcança o Trabalho mas não pode alterá-lo; Token de Sistema.
404	`NOT_FOUND`	Trabalho inexistente, na lixeira ou fora do alcance; orientação reutilizável inexistente.
409	`CONFLICT`	Transição de estado não admitida.
422	`RULE_VIOLATION`	Mudança de tipo; categoria fora do tipo; estado que não pertence ao tipo; orientação declarada em duas formas; cancelamento sem motivo; não comparecimento fora do atendimento; Trabalho de origem inválido.
422	`RULE_VIOLATION`	Subtipo que não pertence à categoria; `caseMovementId` de outro processo. Em implementação.
500	`INTERNAL`	Falha ao gravar.

Condições: a transição é conferida nesta ordem: mapa de transições (409), estado do tipo, não comparecimento fora do atendimento e cancelamento sem motivo (422). A trilha registra work_item.updated, ou work_item.<estado> quando há transição.

`POST /v1/work-items/{id}/advance`

Conclui o Trabalho. Na Atividade, também avança a Situação do quadro do núcleo.

Autenticação e autorização: Bearer de identidade que alcança e pode alterar o Trabalho.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho.
Corpo	`from`	`pending`, `in_progress`, `completed`, `cancelled`, `postponed` ou `no_show`	Sim	Precisa corresponder ao estado gravado; `overdue` não é aceito. Apenas Trabalho pendente ou em execução avança.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	Trabalho	O Trabalho concluído, com os selos preenchidos.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou `from` fora do vocabulário.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	A identidade alcança o Trabalho mas não pode alterá-lo; Token de Sistema.
404	`NOT_FOUND`	Trabalho inexistente, na lixeira ou fora do alcance.
409	`CONFLICT`	`from` diferente do estado atual, ou Trabalho que não está pendente nem em execução.
500	`INTERNAL`	Falha ao gravar.

Condições: na Atividade, a próxima Situação é procurada na sequência do primeiro núcleo de nucleos. A trilha registra work_item.completed.

`POST /v1/work-items/{id}/postpone`

Adia o Trabalho e registra na trilha a data anterior, a nova data e o motivo.

Autenticação e autorização: Bearer de identidade que alcança e pode alterar o Trabalho.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho.
Corpo	`newDate`	data-hora	Sim	Precisa ser posterior à data vigente.
Corpo	`reason`	string, 1 a 500 caracteres	Sim	Motivo do adiamento.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	Trabalho	O Trabalho adiado, com a nova data. O Compromisso volta com `status` em `postponed`; a Atividade mantém o estado que tinha.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	A identidade alcança o Trabalho mas não pode alterá-lo; Token de Sistema.
404	`NOT_FOUND`	Trabalho inexistente, na lixeira ou fora do alcance.
409	`CONFLICT`	Trabalho encerrado.
422	`RULE_VIOLATION`	Nova data anterior ou igual à vigente.
500	`INTERNAL`	Falha ao gravar.

Condições: sem data vigente, a nova data não é comparada. A trilha registra work_item.postponed, com a alteração de dueAt ou scheduledAt em changes e o motivo.

`DELETE /v1/work-items/{id}`

Exclusão suave. Com cascade, exclui também a árvore de filhos vivos.

Autenticação e autorização: Bearer de identidade com autoridade de selo: dono, líder de núcleo responsável ou Acesso Global. Com cascade, a autoridade é conferida sobre toda a árvore antes de qualquer gravação.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho.
Query	`cascade`	boolean	Não	`true` exclui a árvore; padrão `false`.

Saída

HTTP	Campo	Tipo	Descrição
204	—	—	Resposta sem corpo.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Sem autoridade de selo sobre o Trabalho ou sobre algum Trabalho da árvore; Token de Sistema.
404	`NOT_FOUND`	Trabalho inexistente, na lixeira ou fora do alcance.
409	`CONFLICT`	Trabalho com filhos vivos e sem `cascade`.
500	`INTERNAL`	Falha ao gravar.

`POST /v1/work-items/{id}/restore`

Devolve às listas um Trabalho que está na lixeira.

Autenticação e autorização: Bearer de identidade com autoridade de selo sobre o Trabalho.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho excluído.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	Trabalho	O Trabalho restaurado.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema.
404	`NOT_FOUND`	Trabalho inexistente, vivo ou fora do alcance da régua de selo.
409	`CONFLICT`	O Trabalho de origem continua excluído.
500	`INTERNAL`	Falha ao gravar.

Pessoas ligadas ao Trabalho

`GET /v1/work-items/{id}/people`

Lista as ligações do Trabalho, por papel e pela ordem declarada.

Autenticação e autorização: Bearer de identidade que alcança o Trabalho.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	array de ligações	Lista completa, sem paginação.
200	`[].id`	string	Identificador da ligação.
200	`[].workItemId`	string	Trabalho da ligação.
200	`[].role`	enum de papéis	Papel da ligação.
200	`[].targetType`	`user`, `person`, `org_unit` ou `work_group`	Natureza do alvo.
200	`[].targetId`	string	Identificador do alvo.
200	`[].position`	number	Ordem declarada dentro do papel.
200	`[].senderUserId`	string ou `null`	Quem criou a ligação.
200	`[].senderKind`	`user`, `machine`, `system` ou `null`	Natureza de quem criou a ligação.
200	`[].senderTokenId`	string ou `null`	Credencial de integração que criou a ligação.
200	`[].createdAt`	data-hora	Criação da ligação.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
404	`NOT_FOUND`	Trabalho inexistente, na lixeira ou fora do alcance.
500	`INTERNAL`	Falha na consulta.

`POST /v1/work-items/{id}/people`

Liga alguém ao Trabalho no papel declarado.

Autenticação e autorização: Bearer de identidade pessoal que alcança e pode alterar o Trabalho.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho.
Corpo	`role`	`assignee`, `involved`, `observer`, `participant`, `guest`, `witness` ou `presiding`	Sim	Papel da ligação.
Corpo	`targetType`	`user`, `person`, `org_unit` ou `work_group`	Sim	Precisa ser admitida pelo papel.
Corpo	`targetId`	UUID	Sim	Alvo existente no cadastro que a natureza nomeia: `user` em usuários, `person` em Pessoas, `org_unit` em núcleos (`/v1/nuclei`) ou subnúcleos (`/v1/organization/subnuclei`), `work_group` em Grupos de Trabalho.
Corpo	`position`	inteiro de 0 a 999	Não	Ordem dentro do papel; padrão `0`.

Saída

HTTP	Campo	Tipo	Descrição
201	corpo	ligação	A ligação criada, com os mesmos campos da listagem.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	A identidade alcança o Trabalho mas não pode alterá-lo; Token de Sistema.
404	`NOT_FOUND`	Trabalho inexistente, na lixeira ou fora do alcance.
409	`CONFLICT`	A ligação já existe, ou `role: presiding` exige o `PUT` dedicado.
422	`RULE_VIOLATION`	Papel incompatível com a natureza do alvo, ou alvo inexistente; inclui identificador de matriz ou filial em `org_unit`.
500	`INTERNAL`	Falha ao gravar.

Condições: uma ligação org_unit com papel assignee ou involved recalcula nucleos com a sigla do núcleo ou o código do subnúcleo. Apenas o usuário designado com targetType: user é avisado. A trilha registra work_item.assigned. O papel presiding não é criado por esta operação: o servidor responde 409 CONFLICT e orienta o PUT /v1/work-items/{id}/people/presiding.

`PUT /v1/work-items/{id}/people/presiding`

Substitui quem preside um Compromisso, mantendo nome e eventual vínculo com Pessoa como um único estado atômico. Em implementação.

Autenticação e autorização: Bearer de identidade pessoal que alcança e pode alterar o Trabalho.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Compromisso.
Corpo	`personId`	UUID	Exatamente um entre `personId` e `name`	Pessoa existente; o nome exibido é derivado do cadastro. Não envie `name` junto.
Corpo	`name`	string de 1 a 255 caracteres	Exatamente um entre `personId` e `name`	Nome livre, aparado antes da validação e gravação. Não cria vínculo com Pessoa nem aceita `personId` junto.

Saída

HTTP	Campo	Tipo	Descrição
200	`workItemId`	UUID	Compromisso alterado.
200	`presidingName`	string	Nome exibido de quem preside.
200	`personId`	UUID ou `null`	Pessoa vinculada; `null` na variante de nome livre.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido, campo fora do contrato, `personId` fora do formato UUID ou `name` vazio ou acima de 255 caracteres após aparar.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	A identidade alcança o Trabalho mas não pode alterá-lo; Token de Sistema.
404	`NOT_FOUND`	Trabalho inexistente, na lixeira ou fora do alcance.
422	`RULE_VIOLATION`	O Trabalho não é Compromisso; as duas variantes foram enviadas ou ambas estão ausentes; Pessoa inexistente ou sem nome.
500	`INTERNAL`	Falha não tratada ao substituir o estado.

Condições: o servidor substitui, na mesma transação, presidingName e a única ligação presiding/person. Com name, remove a ligação e mantém somente o texto livre; com personId, deriva o nome e mantém uma única ligação. Repetir o mesmo estado é seguro para retry concorrente, não duplica a ligação nem o histórico e devolve o mesmo resultado.

`DELETE /v1/work-items/{id}/people/{linkId}`

Desliga alguém do Trabalho e recalcula os núcleos responsáveis pelo Trabalho.

Autenticação e autorização: Bearer de identidade pessoal que alcança e pode alterar o Trabalho.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho.
Caminho	`linkId`	UUID	Sim	Identificador da ligação.

Saída

HTTP	Campo	Tipo	Descrição
204	—	—	Resposta sem corpo.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	A identidade alcança o Trabalho mas não pode alterá-lo; Token de Sistema.
404	`NOT_FOUND`	Trabalho ou ligação inexistente.
409	`CONFLICT`	A ligação tem papel `presiding` e exige substituição pelo `PUT` dedicado.
500	`INTERNAL`	Falha ao gravar.

Condições: a trilha registra work_item.unassigned. Uma ligação presiding não é removida por esta operação: o servidor responde 409 CONFLICT para preservar a atomicidade entre nome e vínculo.

`GET /v1/work-items/people`

Lê numa chamada as ligações de vários Trabalhos. Atende à fila, que mostra responsáveis, núcleos e grupos de cada linha.

Autenticação e autorização: Bearer de qualquer identidade autenticada, inclusive Token de Sistema. Cada Trabalho passa pela mesma régua da listagem: identificadores inexistentes, na lixeira ou fora do alcance são omitidos da resposta, sem erro.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Query	`workItemIds`	array de UUID v4, de 1 a 200 itens	Sim	Repetível (`?workItemIds=a&workItemIds=b`); um único valor é tratado como lista. Repetições são descartadas.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	array de ligações	Lista sem paginação, com os campos de `GET /v1/work-items/{id}/people`, ordenada por Trabalho, papel, posição e criação. Lista vazia quando nenhum Trabalho do lote é alcançado.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Lista ausente ou vazia, mais de 200 itens, ou identificador que não é UUID v4.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
500	`INTERNAL`	Falha na consulta.

Comentários do Trabalho

`GET /v1/work-items/{id}/comments`

Lista os comentários do Trabalho, dos mais antigos aos mais novos.

Autenticação e autorização: Bearer de identidade que alcança o Trabalho.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho.
Query	`cursor`	string	Não	Cursor da página anterior.
Query	`limit`	inteiro de 1 a 200	Não	Tamanho da página; padrão `50`.

Saída

HTTP	Campo	Tipo	Descrição
200	`items[].id`	string	Identificador do comentário.
200	`items[].workItemId`	string	Trabalho comentado.
200	`items[].body`	string	Texto do comentário.
200	`items[].authorUserId`	string ou `null`	Autor.
200	`items[].authorKind`	`user`, `machine`, `system` ou `null`	Natureza do autor.
200	`items[].authorTokenId`	string ou `null`	Credencial de integração autora.
200	`items[].editedAt`	data-hora ou `null`	Marca de edição.
200	`items[].createdAt`	data-hora	Publicação.
200	`nextCursor`	string ou `null`	Cursor da próxima página.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou cursor ilegível.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
404	`NOT_FOUND`	Trabalho inexistente, na lixeira ou fora do alcance.
500	`INTERNAL`	Falha na consulta.

`POST /v1/work-items/{id}/comments`

Publica um comentário no Trabalho.

Autenticação e autorização: Bearer de identidade pessoal que alcança o Trabalho. Comentar não exige poder de alteração.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho.
Corpo	`body`	string, 1 a 10000 caracteres	Sim	Texto do comentário.

Saída

HTTP	Campo	Tipo	Descrição
201	corpo	comentário	O comentário publicado.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Trabalho inexistente, na lixeira ou fora do alcance.
500	`INTERNAL`	Falha ao gravar.

`PATCH /v1/work-items/{id}/comments/{commentId}`

Reescreve o próprio comentário e marca a edição.

Autenticação e autorização: Bearer do autor do comentário; o Acesso Global também alcança.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho.
Caminho	`commentId`	UUID	Sim	Identificador do comentário.
Corpo	`body`	string, 1 a 10000 caracteres	Sim	Novo texto.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	comentário	O comentário alterado, com `editedAt` preenchido.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	O comentário é de outra pessoa; Token de Sistema.
404	`NOT_FOUND`	Trabalho ou comentário inexistente.
500	`INTERNAL`	Falha ao gravar.

`DELETE /v1/work-items/{id}/comments/{commentId}`

Apaga o próprio comentário.

Autenticação e autorização: Bearer do autor do comentário; o Acesso Global também alcança.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Trabalho.
Caminho	`commentId`	UUID	Sim	Identificador do comentário.

Saída

HTTP	Campo	Tipo	Descrição
204	—	—	Resposta sem corpo.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	O comentário é de outra pessoa; Token de Sistema.
404	`NOT_FOUND`	Trabalho ou comentário inexistente.
500	`INTERNAL`	Falha ao gravar.

Modelos de Trabalho

`GET /v1/work-templates`

Lista os Modelos. Sem o parâmetro de habilitação, traz apenas os habilitados.

Autenticação e autorização: Bearer de qualquer identidade autenticada.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Query	`cursor`	string	Não	Cursor da página anterior.
Query	`limit`	inteiro de 1 a 200	Não	Tamanho da página; padrão `50`.
Query	`kind`	`activity` ou `appointment`	Não	Tipo do Trabalho gerado.
Query	`category`	enum de categorias	Não	Categoria do Trabalho gerado.
Query	`orgUnitId`	UUID	Não	Setor dono do Modelo.
Query	`enabled`	boolean	Não	Ausente, traz apenas os habilitados.

Saída

HTTP	Campo	Tipo	Descrição
200	`items[].id`	string	Identificador do Modelo.
200	`items[].code`	string ou `null`	Código curto do Modelo.
200	`items[].name`	string	Nome no seletor.
200	`items[].kind`	`activity` ou `appointment`	Tipo gerado.
200	`items[].category`	enum de categorias	Categoria gerada.
200	`items[].titleTemplate`	string ou `null`	Título sugerido.
200	`items[].bodyTemplate`	string ou `null`	Descrição sugerida.
200	`items[].guidelineId`	string ou `null`	Orientação herdada.
200	`items[].days`	number ou `null`	Dias do prazo.
200	`items[].countingRule`	regra de contagem ou `null`	Regra que substitui a da categoria.
200	`items[].priority`	prioridade ou `null`	Prioridade sugerida.
200	`items[].durationMin`	number ou `null`	Duração sugerida.
200	`items[].pendingFields`	array de strings	Campos que a interface deve solicitar.
200	`items[].defaultPeople`	array de designações padrão	Cada item traz `role`, `targetType` e `targetId`; a compatibilidade entre papel e natureza é conferida, a existência do alvo não.
200	`items[].orgUnitId`	string ou `null`	Setor dono.
200	`items[].ownerUserId`	string ou `null`	Quem cadastrou.
200	`items[].enabled`	boolean	Habilitação no seletor.
200	`items[].createdAt` / `updatedAt`	data-hora	Datas de registro.
200	`nextCursor`	string ou `null`	Cursor da próxima página.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Consulta fora do contrato ou cursor ilegível.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
500	`INTERNAL`	Falha na consulta.

`GET /v1/work-templates/{id}`

Devolve o Modelo, habilitado ou não.

Autenticação e autorização: Bearer de qualquer identidade autenticada.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Modelo.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	Modelo	Os mesmos campos da listagem.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
404	`NOT_FOUND`	Modelo inexistente.
500	`INTERNAL`	Falha na consulta.

`POST /v1/work-templates`

Cadastra um Modelo.

Autenticação e autorização: Bearer de identidade pessoal com Acesso de Núcleo ou superior.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`name`	string, 1 a 255 caracteres	Sim	Nome no seletor.
Corpo	`kind`	`activity` ou `appointment`	Sim	Tipo gerado.
Corpo	`category`	enum de categorias	Sim	Deve pertencer ao tipo.
Corpo	`code`	string, 1 a 32 caracteres	Não	Código curto e único; a coluna guarda até 32 caracteres.
Corpo	`titleTemplate`	string, até 255 caracteres	Não	Título sugerido.
Corpo	`bodyTemplate`	string, até 100000 caracteres	Não	Descrição sugerida.
Corpo	`guidelineId`	UUID	Não	Orientação herdada pelo Trabalho gerado.
Corpo	`days`	inteiro de 1 a 3650	Não	Exige `countingRule`; o cadastro exige valor maior que zero.
Corpo	`countingRule`	`calendar_days`, `business_days` ou `calendar_days_business_end`	Com `days`	Regra que substitui a da categoria.
Corpo	`priority`	prioridade	Não	Prioridade sugerida.
Corpo	`durationMin`	inteiro de 1 a 1440	Não	Duração sugerida.
Corpo	`pendingFields`	array de strings, até 50 itens	Não	Campos que a interface deve solicitar.
Corpo	`defaultPeople`	array de até 20 designações	Não	Cada item exige `role`, `targetType` e `targetId`, com papel e natureza compatíveis.
Corpo	`orgUnitId`	UUID	Não	Setor dono do Modelo.
Corpo	`enabled`	boolean	Não	Padrão `true`.

Saída

HTTP	Campo	Tipo	Descrição
201	corpo	Modelo	O Modelo cadastrado.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Perfil abaixo de Acesso de Núcleo; Token de Sistema.
409	`CONFLICT`	Já existe Modelo com o mesmo código.
404	`NOT_FOUND`	Orientação reutilizável inexistente.
422	`RULE_VIOLATION`	Categoria fora do tipo; `days` sem `countingRule` ou o contrário; designação padrão com papel incompatível com a natureza do alvo.
500	`INTERNAL`	Falha ao gravar.

`PATCH /v1/work-templates/{id}`

Altera o Modelo. A alteração não retroage a prazos já calculados.

Autenticação e autorização: Bearer de identidade pessoal com Acesso de Núcleo ou superior.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Modelo.
Corpo	campos	iguais aos de `POST /v1/work-templates`	Não	Todos opcionais; os informados substituem os atuais.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	Modelo	O Modelo alterado.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Perfil abaixo de Acesso de Núcleo; Token de Sistema.
404	`NOT_FOUND`	Modelo inexistente.
409	`CONFLICT`	Já existe Modelo com o mesmo código.
422	`RULE_VIOLATION`	Forma do Modelo inválida.
500	`INTERNAL`	Falha ao gravar.

`POST /v1/work-templates/{id}/disable`

Retira o Modelo do seletor sem apagá-lo.

Autenticação e autorização: Bearer de identidade pessoal com Acesso de Núcleo ou superior.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do Modelo.

Saída

HTTP	Campo	Tipo	Descrição
201	corpo	Modelo	O Modelo com `enabled` em `false`.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Perfil abaixo de Acesso de Núcleo; Token de Sistema.
404	`NOT_FOUND`	Modelo inexistente.
500	`INTERNAL`	Falha ao gravar.

Visões salvas

`GET /v1/saved-views`

Lista as visões do titular.

Autenticação e autorização: Bearer de identidade pessoal. A listagem devolve apenas as visões da própria identidade.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Query	`cursor`	string	Não	Cursor da página anterior.
Query	`limit`	inteiro de 1 a 200	Não	Tamanho da página; padrão `50`.

Saída

HTTP	Campo	Tipo	Descrição
200	`items[].id`	string	Identificador da visão.
200	`items[].ownerUserId`	string	Titular.
200	`items[].name`	string	Nome da visão.
200	`items[].folder`	string ou `null`	Agrupamento livre.
200	`items[].position`	string	Chave de ordenação entre as visões do titular.
200	`items[].kind`	`manual` ou `query`	Natureza da visão.
200	`items[].category`	categoria ou `null`	Pré-filtro por categoria.
200	`items[].queryJson`	string ou `null`	Critérios salvos, devolvidos sem interpretação.
200	`items[].labels`	array de strings	Rótulos da visão.
200	`items[].itemIds`	array de strings	Trabalhos da lista manual, na ordem informada.
200	`items[].createdAt` / `updatedAt`	data-hora	Datas de registro.
200	`nextCursor`	string ou `null`	Cursor da próxima página.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Cursor ilegível.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
500	`INTERNAL`	Falha na consulta.

`GET /v1/saved-views/{id}`

Devolve uma visão do titular.

Autenticação e autorização: Bearer de identidade pessoal titular da visão. A visão de outra pessoa responde 404, inclusive para o Acesso Global.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da visão.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	visão	Os mesmos campos da listagem.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Visão inexistente ou de outra pessoa.
500	`INTERNAL`	Falha na consulta.

`POST /v1/saved-views`

Cria uma visão pessoal.

Autenticação e autorização: Bearer de identidade pessoal. O titular é sempre a identidade autenticada.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`name`	string, 1 a 120 caracteres	Sim	Nome da visão.
Corpo	`kind`	`manual` ou `query`	Sim	Natureza da visão.
Corpo	`queryJson`	string, até 4000 caracteres	Com `kind: query`	Texto estruturado válido; proibido na visão manual.
Corpo	`itemIds`	array de UUID v4, até 500 itens	Não	Lista da visão manual; repetições são descartadas.
Corpo	`folder`	string, 1 a 120 caracteres	Não	Agrupamento livre.
Corpo	`position`	string numérica	Não	Ordenação entre as visões do titular; padrão `0`.
Corpo	`category`	enum de categorias	Não	Pré-filtro por categoria.
Corpo	`labels`	array de strings, até 20 itens de 1 a 64 caracteres	Não	Rótulos da visão.

Saída

HTTP	Campo	Tipo	Descrição
201	corpo	visão	A visão criada.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
422	`RULE_VIOLATION`	Visão de consulta sem critérios; critérios ilegíveis; natureza misturada com o conteúdo da outra forma.
500	`INTERNAL`	Falha ao gravar.

`PATCH /v1/saved-views/{id}`

Altera uma visão do titular.

Autenticação e autorização: Bearer de identidade pessoal titular da visão.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da visão.
Corpo	campos	iguais aos de `POST /v1/saved-views`	Não	Todos opcionais; `kind` só é aceito com o valor atual.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	visão	A visão alterada.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Visão inexistente ou de outra pessoa.
422	`RULE_VIOLATION`	Mudança da natureza da visão, ou forma incompatível com ela.
500	`INTERNAL`	Falha ao gravar.

`DELETE /v1/saved-views/{id}`

Apaga uma visão do titular. Não há lixeira para preferência de uso.

Autenticação e autorização: Bearer de identidade pessoal titular da visão.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da visão.

Saída

HTTP	Campo	Tipo	Descrição
204	—	—	Resposta sem corpo.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Visão inexistente ou de outra pessoa.
500	`INTERNAL`	Falha ao gravar.

Prazo e medição

`GET /v1/workspace/deadline-preview`

Simula o vencimento de um prazo sem criar registro nenhum.

Autenticação e autorização: Bearer de qualquer identidade autenticada.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Query	`category`	enum de categorias	Sim	Precisa ser uma categoria que conta prazo.
Query	`baseDate`	data civil `YYYY-MM-DD`	Sim	Data-base da contagem; a contagem começa no dia seguinte.
Query	`days`	inteiro de 0 a 3650	Sim	Quantidade de dias.

Saída

HTTP	Campo	Tipo	Descrição
200	`dueDate`	data-hora	Vencimento apurado, no fim do dia civil.
200	`preclusionRule`	`calendar_days`, `business_days` ou `calendar_days_business_end`	Regra aplicada, derivada da categoria.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Consulta fora do contrato, quantidade de dias negativa ou data inexistente.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
422	`RULE_VIOLATION`	Categoria que não conta prazo; `baseDate` que não é uma data civil existente.
500	`INTERNAL`	Falha na leitura do calendário.

`GET /v1/workspace/completion-metrics`

Conta os Trabalhos concluídos na janela, dentro do alcance de quem consulta, agrupados por categoria.

Autenticação e autorização: Bearer de qualquer identidade autenticada. A contagem usa o alcance de leitura da identidade.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Query	`from`	data-hora	Sim	Início da janela.
Query	`to`	data-hora	Sim	Fim da janela; não pode anteceder `from` nem ultrapassar um ano.

Saída

HTTP	Campo	Tipo	Descrição
200	`from`	data-hora	Início da janela aplicada.
200	`to`	data-hora	Fim da janela aplicada.
200	`total`	number	Soma de todos os grupos.
200	`buckets[].category`	enum de categorias	Categoria do grupo.
200	`buckets[].count`	number	Quantidade concluída na categoria; apenas grupos maiores que zero.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Consulta fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
422	`RULE_VIOLATION`	Janela ausente, incompleta, invertida ou maior que um ano.
500	`INTERNAL`	Falha na consulta.

Trilha do Trabalho

`GET /v1/history/{resourceType}/{resourceId}`

Devolve a trilha do Trabalho, do evento mais antigo ao mais novo. A Área de Trabalho usa resourceType igual a work-item; o histórico é um serviço compartilhado entre domínios.

Autenticação e autorização: Bearer de qualquer identidade autenticada. Para work-item, a trilha segue a leitura do Trabalho: quem não lê o Trabalho recebe 404. A trilha de um Trabalho na lixeira não é lida, nem pelo dono.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`resourceType`	string	Sim	`work-item`.
Caminho	`resourceId`	UUID	Sim	Identificador do Trabalho.
Query	`cursor`	string	Não	Cursor da página anterior.
Query	`limit`	inteiro de 1 a 200	Não	Tamanho da página; padrão `50`.
Query	`resourceType`	string, padrão `^[a-z][a-z0-9-]{0,63}$`	Não	Filtra as entradas pelo tipo de recurso registrado.

Saída

HTTP	Campo	Tipo	Descrição
200	`items[].id`	string	Identificador da entrada.
200	`items[].resourceType`	string	`work-item`.
200	`items[].resourceId`	string	Trabalho da entrada.
200	`items[].resourceLabel`	string ou `null`	Título do Trabalho no momento do evento.
200	`items[].action`	`created`, `updated`, `deleted`, `restored`, `transitioned`, `linked`, `unlinked`, `imported` ou `action`	Natureza do evento.
200	`items[].eventType`	string	Evento do domínio, conforme a tabela abaixo.
200	`items[].summary`	string	Resumo legível.
200	`items[].changes`	array	Alterações registradas; vazio quando o evento não guarda diferença.
200	`items[].metadata`	objeto	Dados complementares do evento.
200	`items[].actorKind`	`user`, `machine` ou `system`	Natureza do autor.
200	`items[].actorUserId`	string ou `null`	Usuário autor.
200	`items[].actorLabel`	string	Nome do autor.
200	`items[].occurredAt`	data-hora	Instante do evento.
200	`items[].createdAt`	data-hora	Gravação da entrada.
200	`nextCursor`	string ou `null`	Cursor da próxima página.

Itens das listas de saída

Lista	Campo	Tipo	Descrição
`changes[]`	`field`	string	Campo alterado.
`changes[]`	`label`	string	Rótulo do campo.
`changes[]`	`before`	string ou `null`	Valor anterior.
`changes[]`	`after`	string ou `null`	Valor novo.
`changes[]`	`beforeTruncated`	boolean	Indica valor anterior truncado.
`changes[]`	`afterTruncated`	boolean	Indica valor novo truncado.

Eventos do Trabalho

`eventType`	`action`	Origem
`work_item.created`	`created`	Criação, inclusive da orientação gerada pela regra do ato.
`work_item.updated`	`updated`	Alteração sem mudança de estado.
`work_item.<estado>`	`updated`	Alteração com mudança de estado, como `work_item.cancelled`.
`work_item.completed`	`updated`	Avanço que conclui o Trabalho.
`work_item.postponed`	`updated`	Adiamento, com a data anterior e a nova em `changes`.
`work_item.deleted`	`deleted`	Exclusão.
`work_item.restored`	`restored`	Restauração.
`work_item.assigned`	`linked`	Criação de ligação.
`work_item.unassigned`	`unlinked`	Remoção de ligação.

Comentários não entram na trilha. Quando o Trabalho se refere a uma Pessoa, suas entradas também compõem o histórico dessa Pessoa para quem lê o Trabalho.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido, cursor ilegível, `limit` fora do intervalo ou filtro inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
404	`NOT_FOUND`	Trabalho inexistente, na lixeira ou fora do alcance; tipo de recurso sem trilha legível.
500	`INTERNAL`	Falha na consulta.

Grupos de Trabalho

O Grupo de Trabalho reúne usuários que respondem juntos por Trabalhos. O objeto devolvido pelas operações tem os campos abaixo.

Campo	Tipo	Descrição
`id`	string	Identificador do grupo.
`name`	string	Nome do grupo.
`description`	string ou `null`	Descrição.
`ownerUserId`	string ou `null`	Dono do grupo.
`enabled`	boolean	`false` indica grupo desabilitado.
`members[].id`	string	Identificador do vínculo de membro.
`members[].workGroupId`	string	Grupo do vínculo.
`members[].userId`	string	Usuário membro.
`createdAt` / `updatedAt`	data-hora	Datas de registro.

`GET /v1/work-groups`

Lista os Grupos de Trabalho, com seus membros.

Autenticação e autorização: Bearer de qualquer identidade autenticada, inclusive Token de Sistema. A leitura não depende de vínculo com o grupo.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Query	`cursor`	string	Não	Cursor da página anterior.
Query	`limit`	inteiro de 1 a 200	Não	Tamanho da página; padrão `50`.
Query	`search`	string, até 120 caracteres	Não	Trecho do nome, sem distinção de caixa; termo vazio é ignorado.
Query	`enabled`	`true` ou `false`	Não	Ausente, traz grupos habilitados e desabilitados.

Saída

HTTP	Campo	Tipo	Descrição
200	`items`	array de Grupos de Trabalho	Página ordenada pela criação.
200	`nextCursor`	string ou `null`	Cursor da próxima página.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Consulta fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
500	`INTERNAL`	Falha na consulta.

`GET /v1/work-groups/{id}`

Devolve um Grupo de Trabalho, habilitado ou não.

Autenticação e autorização: Bearer de qualquer identidade autenticada, inclusive Token de Sistema.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do grupo.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	Grupo de Trabalho	O grupo, com seus membros.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
404	`NOT_FOUND`	Grupo inexistente.
500	`INTERNAL`	Falha na consulta.

`POST /v1/work-groups`

Cria um Grupo de Trabalho. Quem cria é o dono e sempre integra o grupo.

Autenticação e autorização: Bearer de qualquer identidade autenticada.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`name`	string, 1 a 120 caracteres	Sim	Nome do grupo.
Corpo	`description`	string, até 500 caracteres	Não	Descrição.
Corpo	`memberUserIds`	array de UUID, até 200 itens	Não	Usuários membros; repetições são descartadas e o dono é incluído.

Saída

HTTP	Campo	Tipo	Descrição
201	corpo	Grupo de Trabalho	O grupo criado, com seus membros.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
500	`INTERNAL`	Falha ao gravar, inclusive por usuário membro inexistente.

Condições: a criação entra no histórico como work-group.created.

`PATCH /v1/work-groups/{id}`

Altera nome, descrição, membros ou habilitação do grupo.

Autenticação e autorização: Bearer do dono do grupo ou de identidade com Acesso de Núcleo ou superior.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do grupo.
Corpo	`name`	string, 1 a 120 caracteres	Não	Novo nome.
Corpo	`description`	string, até 500 caracteres	Não	Nova descrição.
Corpo	`memberUserIds`	array de UUID, até 200 itens	Não	Substitui os membros; o dono permanece no grupo.
Corpo	`enabled`	boolean	Não	Habilitação do grupo.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	Grupo de Trabalho	O grupo alterado.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	A identidade não é dona do grupo e tem perfil abaixo de Acesso de Núcleo.
404	`NOT_FOUND`	Grupo inexistente.
500	`INTERNAL`	Falha ao gravar, inclusive por usuário membro inexistente.

Condições: a alteração entra no histórico como work-group.updated, com as diferenças.

`DELETE /v1/work-groups/{id}`

Desabilita o Grupo de Trabalho, sem apagar o registro nem os membros. Um grupo desabilitado deixa de dar alcance aos Trabalhos em que está ligado.

Autenticação e autorização: Bearer do dono do grupo ou de identidade com Acesso de Núcleo ou superior.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador do grupo.

Saída

HTTP	Campo	Tipo	Descrição
204	—	—	Resposta sem corpo.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	A identidade não é dona do grupo e tem perfil abaixo de Acesso de Núcleo.
404	`NOT_FOUND`	Grupo inexistente.
500	`INTERNAL`	Falha ao gravar.

Condições: a operação é idempotente e registra work-group.disabled a cada chamada.

Diretório de usuários

`GET /v1/users/directory`

Lista as contas ativas com identificador e nome, para escolher quem designar ou incluir num grupo.

Autenticação e autorização: Bearer de qualquer identidade autenticada, inclusive Token de Sistema.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Query	`cursor`	string	Não	Cursor da página anterior.
Query	`limit`	inteiro de 1 a 200	Não	Tamanho da página; padrão `50`.
Query	`search`	string, até 120 caracteres	Não	Trecho do nome, sem distinção de caixa; termo em branco é ignorado.

Saída

HTTP	Campo	Tipo	Descrição
200	`items[].id`	string	Identificador do usuário.
200	`items[].name`	string	Nome do usuário.
200	`nextCursor`	string ou `null`	Cursor da próxima página.

E-mail, perfil e Pessoa vinculada não são publicados pelo diretório.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Consulta fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
500	`INTERNAL`	Falha na consulta.

Preferências de uso

`GET /v1/workspace/labels`

Devolve o vocabulário pessoal de etiquetas da identidade.

Autenticação e autorização: Bearer de identidade pessoal. Cada pessoa lê apenas o próprio vocabulário; o Acesso Global não amplia a leitura.

Entrada: sem parâmetros.

Saída

HTTP	Campo	Tipo	Descrição
200	`items[].slug`	string, 1 a 64 caracteres	Identificador da etiqueta.
200	`items[].name`	string, 1 a 120 caracteres	Nome exibido.
200	`items[].symbol`	string, 1 a 16 caracteres	Símbolo da etiqueta.
200	`items[].color`	string, 1 a 32 caracteres	Cor da etiqueta.
200	`items[].lastUsedISO`	string ISO 8601	Último uso.

Quem nunca salvou o vocabulário recebe items vazio.

Erros

HTTP	errorCode	Condição
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
500	`INTERNAL`	Falha na consulta.

`PUT /v1/workspace/labels`

Substitui de uma vez o vocabulário pessoal de etiquetas.

Autenticação e autorização: Bearer de identidade pessoal; grava apenas o vocabulário da própria identidade.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`items`	array, até 200 itens	Sim	Vocabulário completo.
Corpo	`items[].slug`	string, 1 a 64 caracteres	Sim	Identificador da etiqueta.
Corpo	`items[].name`	string, 1 a 120 caracteres	Sim	Nome exibido.
Corpo	`items[].symbol`	string, 1 a 16 caracteres	Sim	Símbolo.
Corpo	`items[].color`	string, 1 a 32 caracteres	Sim	Cor.
Corpo	`items[].lastUsedISO`	string ISO 8601	Sim	Último uso.

Saída

HTTP	Campo	Tipo	Descrição
200	`items`	array de etiquetas	O vocabulário gravado, com os campos de `GET /v1/workspace/labels`.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
500	`INTERNAL`	Falha ao gravar.

`GET /v1/workspace/habits`

Devolve os hábitos de uso da identidade, dos mais frequentes aos menos frequentes.

Autenticação e autorização: Bearer de identidade pessoal; lê apenas os próprios hábitos.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Query	`kind`	string, 1 a 32 caracteres	Não	Natureza do hábito; não pode começar com `lia.`. Ausente, traz todas as naturezas, exceto as reservadas à Lia.
Query	`limit`	inteiro de 1 a 100	Não	Quantidade de hábitos; padrão `10`.

Saída

HTTP	Campo	Tipo	Descrição
200	`[].id`	string	Identificador do hábito.
200	`[].ownerUserId`	string	Titular.
200	`[].kind`	string	Natureza do hábito.
200	`[].ref`	string	Referência usada.
200	`[].count`	number	Quantidade de usos.
200	`[].lastUsedAt`	data-hora	Último uso.
200	`[].createdAt`	data-hora	Primeiro registro.

A lista não é paginada e vem ordenada por quantidade de usos e, em seguida, pelo uso mais recente.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Consulta fora do contrato ou `kind` reservado à Lia.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
500	`INTERNAL`	Falha na consulta.

`POST /v1/workspace/habits`

Registra um uso. Cada chamada soma um à contagem do par natureza e referência e atualiza o último uso.

Autenticação e autorização: Bearer de identidade pessoal; registra apenas os próprios hábitos.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`kind`	string, 1 a 32 caracteres	Sim	Natureza do hábito; não pode começar com `lia.`.
Corpo	`ref`	string, 1 a 64 caracteres	Sim	Referência usada.

Saída

HTTP	Campo	Tipo	Descrição
201	corpo	hábito	O hábito após o registro, com os campos de `GET /v1/workspace/habits`, inclusive quando apenas incrementa um hábito existente.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Corpo fora do contrato ou `kind` reservado à Lia.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
500	`INTERNAL`	Falha ao gravar.

Agendas e listas

As agendas organizam a Área de Trabalho de cada pessoa em listas. Todas as operações exigem identidade pessoal e alcançam apenas as agendas da própria identidade: a agenda de outra pessoa responde 404, inclusive para o Acesso Global. Um Token de Sistema recebe 403 FORBIDDEN.

Agenda — campos de saída

Campo	Tipo	Descrição
`id`	string	Identificador da agenda.
`name`	string	Nome da agenda.
`ownerUserId`	string	Titular.
`position`	number	Ordem entre as agendas do titular.
`createdAt` / `updatedAt`	data-hora	Datas de registro.

Lista — campos de saída

Campo	Tipo	Descrição
`id`	string	Identificador da lista.
`agendaId`	string	Agenda da lista.
`name`	string	Nome da lista.
`ownerUserId`	string	Titular.
`position`	number	Ordem dentro da agenda.
`listKind`	`manual` ou `query`	Lista de Trabalhos escolhidos ou lista de consulta.
`activityType`	`task`, `judicial_deadline`, `extrajudicial_deadline` ou `null`	Pré-filtro por categoria de Atividade.
`queryJson`	string ou `null`	Critérios da lista de consulta.
`labels`	array de strings	Rótulos da lista.
`createdAt` / `updatedAt`	data-hora	Datas de registro.

Item da lista — campos de saída

Campo	Tipo	Descrição
`id`	string	Identificador do item.
`listId`	string	Lista do item.
`itemRef`	string	Referência `work-items:<uuid>` do Trabalho.
`position`	number	Ordem na lista.
`createdAt` / `updatedAt`	data-hora	Datas de registro.

`GET /v1/agendas`

Lista as agendas da identidade, pela ordem de criação.

Autenticação e autorização: Bearer de identidade pessoal.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Query	`cursor`	string	Não	Cursor da página anterior.
Query	`limit`	inteiro de 1 a 200	Não	Tamanho da página; padrão `50`.

Saída

HTTP	Campo	Tipo	Descrição
200	`items`	array de agendas	Página de agendas do titular.
200	`nextCursor`	string ou `null`	Cursor da próxima página.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Consulta fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
500	`INTERNAL`	Falha na consulta.

`GET /v1/agendas/{id}`

Devolve uma agenda da identidade.

Autenticação e autorização: Bearer de identidade pessoal titular da agenda.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da agenda.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	agenda	A agenda.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Agenda inexistente ou de outra pessoa.
500	`INTERNAL`	Falha na consulta.

`POST /v1/agendas`

Cria uma agenda para a identidade.

Autenticação e autorização: Bearer de identidade pessoal; o titular é sempre a identidade autenticada.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Corpo	`name`	string, 1 a 120 caracteres	Sim	Nome da agenda.
Corpo	`position`	number	Não	Ordem entre as agendas; padrão `0`.

Saída

HTTP	Campo	Tipo	Descrição
201	corpo	agenda	A agenda criada.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
500	`INTERNAL`	Falha ao gravar.

`PATCH /v1/agendas/{id}`

Renomeia ou reposiciona a agenda.

Autenticação e autorização: Bearer de identidade pessoal titular da agenda.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da agenda.
Corpo	`name`	string, 1 a 120 caracteres	Não	Novo nome.
Corpo	`position`	number	Não	Nova ordem.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	agenda	A agenda alterada.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Agenda inexistente ou de outra pessoa.
500	`INTERNAL`	Falha ao gravar.

`DELETE /v1/agendas/{id}`

Apaga a agenda com suas listas e itens. Os Trabalhos citados não são afetados.

Autenticação e autorização: Bearer de identidade pessoal titular da agenda.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da agenda.

Saída

HTTP	Campo	Tipo	Descrição
204	—	—	Resposta sem corpo.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Agenda inexistente ou de outra pessoa.
500	`INTERNAL`	Falha ao gravar.

`GET /v1/agendas/{id}/lists`

Lista as listas da agenda, pela ordem de criação.

Autenticação e autorização: Bearer de identidade pessoal titular da agenda.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da agenda.
Query	`cursor`	string	Não	Cursor da página anterior.
Query	`limit`	inteiro de 1 a 200	Não	Tamanho da página; padrão `50`.

Saída

HTTP	Campo	Tipo	Descrição
200	`items`	array de listas	Página de listas da agenda.
200	`nextCursor`	string ou `null`	Cursor da próxima página.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou consulta fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Agenda inexistente ou de outra pessoa.
500	`INTERNAL`	Falha na consulta.

`POST /v1/agendas/{id}/lists`

Cria uma lista na agenda.

Autenticação e autorização: Bearer de identidade pessoal titular da agenda.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da agenda.
Corpo	`name`	string, 1 a 120 caracteres	Sim	Nome da lista.
Corpo	`listKind`	`manual` ou `query`	Sim	Natureza da lista.
Corpo	`position`	number	Não	Ordem dentro da agenda.
Corpo	`activityType`	`task`, `judicial_deadline` ou `extrajudicial_deadline`	Não	Pré-filtro por categoria de Atividade.
Corpo	`queryJson`	string JSON, até 4000 caracteres	Não	Critérios da lista de consulta.
Corpo	`labels`	array de strings, até 32 itens de 1 a 64 caracteres	Não	Rótulos da lista.

Saída

HTTP	Campo	Tipo	Descrição
201	corpo	lista	A lista criada.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido, corpo fora do contrato ou `queryJson` que não é JSON válido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Agenda inexistente ou de outra pessoa.
500	`INTERNAL`	Falha ao gravar.

`PATCH /v1/agendas/{id}/lists/{listId}`

Renomeia, reposiciona ou move a lista para outra agenda do mesmo titular.

Autenticação e autorização: Bearer de identidade pessoal titular da agenda e da agenda de destino.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da agenda.
Caminho	`listId`	UUID	Sim	Identificador da lista.
Corpo	`name`	string, 1 a 120 caracteres	Não	Novo nome.
Corpo	`position`	number	Não	Nova ordem.
Corpo	`agendaId`	UUID	Não	Agenda de destino, do mesmo titular.
Corpo	`listKind`, `activityType`, `queryJson`, `labels`	iguais aos da criação	Não	Aceitos pelo contrato; pendentes de persistência quando enviados sem `name`, `position` ou `agendaId`.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	lista	A lista alterada.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou corpo fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Agenda de destino de outra pessoa; Token de Sistema.
404	`NOT_FOUND`	Agenda ou lista inexistente, ou de outra pessoa.
500	`INTERNAL`	Falha ao gravar.

`DELETE /v1/agendas/{id}/lists/{listId}`

Apaga a lista e seus itens. Os Trabalhos citados não são afetados.

Autenticação e autorização: Bearer de identidade pessoal titular da agenda.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da agenda.
Caminho	`listId`	UUID	Sim	Identificador da lista.

Saída

HTTP	Campo	Tipo	Descrição
204	—	—	Resposta sem corpo.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Agenda ou lista inexistente, ou de outra pessoa.
500	`INTERNAL`	Falha ao gravar.

`GET /v1/agendas/{id}/lists/{listId}/items`

Lista os itens de uma lista. A ordem de exibição é dada por position; a página segue a ordem de criação.

Autenticação e autorização: Bearer de identidade pessoal titular da agenda.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da agenda.
Caminho	`listId`	UUID	Sim	Identificador da lista.
Query	`cursor`	string	Não	Cursor da página anterior.
Query	`limit`	inteiro de 1 a 200	Não	Tamanho da página; padrão `50`.

Saída

HTTP	Campo	Tipo	Descrição
200	`items`	array de itens	Página de itens da lista.
200	`nextCursor`	string ou `null`	Cursor da próxima página.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou consulta fora do contrato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Agenda ou lista inexistente, ou de outra pessoa.
500	`INTERNAL`	Falha na consulta.

`PUT /v1/agendas/{id}/lists/{listId}/order`

Inclui Trabalhos na lista e define suas posições. É a operação que acrescenta itens a uma lista manual.

Autenticação e autorização: Bearer de identidade pessoal titular da agenda.

Entrada — JSON

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da agenda.
Caminho	`listId`	UUID	Sim	Identificador da lista.
Corpo	`items`	array, 1 a 500 itens	Sim	Itens com a nova posição; uma referência não se repete no lote.
Corpo	`items[].itemRef`	string, até 64 caracteres	Sim	Referência no formato `work-items:<uuid>`, com o UUID em minúsculas.
Corpo	`items[].position`	number	Sim	Posição do item na lista.

Saída

HTTP	Campo	Tipo	Descrição
200	corpo	array de itens	Todos os itens da lista, na ordem resultante.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido, corpo fora do contrato, referência fora do formato ou repetida.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Agenda ou lista inexistente, ou de outra pessoa.
500	`INTERNAL`	Falha ao gravar.

Condições: quando duas posições ficam próximas demais para receber um item entre elas, as posições da lista são renumeradas em sequência.

`DELETE /v1/agendas/{id}/lists/{listId}/items/{itemRef}`

Retira um Trabalho da lista, sem afetar o Trabalho.

Autenticação e autorização: Bearer de identidade pessoal titular da agenda.

Entrada

Local	Campo	Tipo	Obrigatório	Condição
Caminho	`id`	UUID	Sim	Identificador da agenda.
Caminho	`listId`	UUID	Sim	Identificador da lista.
Caminho	`itemRef`	string	Sim	Referência `work-items:<uuid>`.

Saída

HTTP	Campo	Tipo	Descrição
204	—	—	Resposta sem corpo.

Erros

HTTP	errorCode	Condição
400	`VALIDATION_FAILED`	Identificador inválido ou referência fora do formato.
401	`UNAUTHORIZED`	Credencial ausente ou inválida.
403	`FORBIDDEN`	Token de Sistema, que não representa Pessoa.
404	`NOT_FOUND`	Agenda, lista ou item inexistente, ou de outra pessoa.
500	`INTERNAL`	Falha ao gravar.