API Reference · Organização
Convenções
As rotas recebem Authorization: Bearer <credencial>. As listagens paginadas usam 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. asOf é uma data civil YYYY-MM-DD e, ausente, vale o dia corrente no fuso do escritório. O corpo de erro segue as convenções da API Reference da Área de Trabalho.
Situação das operações. GET /v1/organization/nuclei e GET /v1/organization/nuclei/{sigla} estão publicadas em development. As demais operações e o comando de importação estão implementados no ramo feat/gestao-nucleos da API, ainda fora de development.
Núcleo — campos de saída
| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador do núcleo. |
sigla | string | Sigla do núcleo, única, em maiúsculas. |
name | string | Nome por extenso. |
status | ativo, em_desenvolvimento, inativo ou encerrado | Situação estrutural. |
effectiveFrom | data YYYY-MM-DD | Primeiro dia de vigência. |
effectiveTo | data YYYY-MM-DD ou null | Último dia de vigência, inclusive; null enquanto vigente. |
areaSigla | string ou null | Sigla da área vigente no dia consultado; null quando não há vínculo nesse dia ou quando a área ligada não está vigente. |
createdAt | data-hora | Criação. |
updatedAt | data-hora | Última alteração. |
Núcleos
GET /v1/organization/nuclei
Lista todos os núcleos vigentes no dia consultado, sem aplicar a RN-ORGANIZACAO-002. O menu do usuário usa GET /v1/me/nuclei.
Autenticação e autorização: qualquer identidade autenticada.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Query | cursor | string | Não | Cursor da página anterior. |
| Query | limit | número de 1 a 200, padrão 50 | Sim | Tamanho da página. |
| Query | asOf | data YYYY-MM-DD | Não | Dia consultado. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | items | array de Núcleo | Núcleos vigentes no dia, conforme os campos de saída das Convenções. |
| 200 | nextCursor | string ou null | Cursor da próxima página. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | asOf ou cursor malformado. |
| 401 | UNAUTHORIZED | Sem identidade autenticada. |
| 500 | INTERNAL | Falha não tratada. |
GET /v1/me/nuclei
Lista os núcleos vigentes que a pessoa autenticada pode ver, conforme a RN-ORGANIZACAO-002, com a área e o papel dela em cada um. Alimenta a seção Núcleos do menu do usuário e a lista de /gestao.
Autenticação e autorização: qualquer identidade autenticada.
Entrada: sem parâmetros.
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | corpo | array, ordenado por sigla | Núcleos que a pessoa vê; sem paginação. |
| 200 | [].id | string | Identificador do núcleo. |
| 200 | [].sigla | string | Sigla do núcleo. |
| 200 | [].name | string | Nome do núcleo. |
| 200 | [].status | ativo, em_desenvolvimento, inativo ou encerrado | Situação estrutural. |
| 200 | [].areaSigla | string ou null | Sigla da área vigente hoje; null sem vínculo vigente. |
| 200 | [].role | member, leader ou null | Papel da pessoa no núcleo; null quando ela o vê só pelo alcance. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 401 | UNAUTHORIZED | Sem identidade autenticada. |
| 500 | INTERNAL | Falha não tratada. |
GET /v1/organization/nuclei/{sigla}
Consulta o núcleo vigente no dia indicado, com a área vigente nesse dia.
Autenticação e autorização: qualquer identidade autenticada.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | sigla | string | Sim | Sigla do núcleo. |
| Query | asOf | data YYYY-MM-DD | Não | Dia consultado. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | corpo | Núcleo | O núcleo, conforme os campos de saída das Convenções. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | asOf malformado. |
| 401 | UNAUTHORIZED | Sem identidade autenticada. |
| 404 | NOT_FOUND | Nenhuma versão do núcleo vigente no dia. |
| 500 | INTERNAL | Falha não tratada. |
GET /v1/organization/nuclei/{sigla}/members
Lista as contas ativas vinculadas ao núcleo, a liderança primeiro e depois por nome.
Autenticação e autorização: quem pode ver o núcleo, conforme a RN-ORGANIZACAO-002.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Caminho | sigla | string | Sim | Sigla do núcleo. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | corpo | array | Contas vinculadas; vazio quando o núcleo não tem vínculos. Sem paginação. |
| 200 | [].userId | string | Identificador da conta. |
| 200 | [].name | string | Nome da conta. |
| 200 | [].email | string | E-mail da conta, em minúsculas. |
| 200 | [].role | member ou leader | Papel no núcleo. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 401 | UNAUTHORIZED | Sem identidade autenticada. |
| 404 | NOT_FOUND | Núcleo inexistente ou fora do alcance de quem consulta. |
| 500 | INTERNAL | Falha não tratada. |
Tipos de reunião
GET /v1/meeting-types
Lista o catálogo de tipos de reunião importado do lsa-gestao.
Autenticação e autorização: qualquer identidade autenticada.
Entrada
| Local | Campo | Tipo | Obrigatório | Condição |
|---|---|---|---|---|
| Query | nucleusApplicable | boolean | Não | true devolve só os tipos que a Página do Núcleo agenda. |
Saída
| HTTP | Campo | Tipo | Descrição |
|---|---|---|---|
| 200 | corpo | array | Tipos de reunião, por código. Sem paginação. |
| 200 | [].code | string | Código do catálogo. |
| 200 | [].name | string | Nome do tipo. |
| 200 | [].frequency | string ou null | Frequência prevista. |
| 200 | [].format | string ou null | Formato previsto. |
| 200 | [].defaultAgenda | array de strings | Itens da pauta padrão. |
| 200 | [].nucleusApplicable | boolean | true quando a Página do Núcleo agenda o tipo. |
| 200 | [].createdAt, [].updatedAt | data-hora | Criação e última alteração. |
Erros
| HTTP | errorCode | Condição |
|---|---|---|
| 400 | VALIDATION_FAILED | Filtro fora do contrato. |
| 401 | UNAUTHORIZED | Credencial ausente ou inválida. |
| 500 | INTERNAL | Falha não tratada. |
Importação do lsa-gestao
A importação é um comando executado no servidor da API, e não uma rota HTTP. Ela lê o arquivo JSON gerado pelo script de exportação do lsa-gestao, com áreas, núcleos, subnúcleos, lideranças, lotações e o catálogo de tipos de reunião. Cada pessoa vem com o e-mail da sua identidade externa, na ordem Appwrite, Google e Projuris, ou sem e-mail.
bun run nuclei:import <arquivo.json> [--gravar --autor <e-mail>]
| Modo | Efeito |
|---|---|
Simulação (sem --gravar --autor) | Nada é gravado; o relatório lista o que seria feito. |
Gravação (--gravar --autor <e-mail>) | Aplica as alterações pelos serviços de cada cadastro, em nome do autor, com registro no histórico. |
O relatório traz as ações, os avisos (divergências, pessoas sem e-mail ou sem conta, subnúcleos não criados, unidades encerradas não criadas) e as contagens de núcleos ativos, líderes, pessoas, pessoas reconhecidas e não reconhecidas. As regras da importação estão em RN-ORGANIZACAO-003 a RN-ORGANIZACAO-007.