# Hermes Publisher API > API operacional do Hermes Studio para inteligência editorial, criação, fluxo de aprovação, equipe e conexões sociais. Version: 1.3.0 Release date: 2026-08-22 Base URL: https://socialmedia.janvalellam.com.br MCP Streamable HTTP: https://socialmedia.janvalellam.com.br/api/mcp Canonical OpenAPI: https://socialmedia.janvalellam.com.br/api/ai/openapi.yaml ## Authentication and safety - Send `Authorization: Bearer ` only to routes marked as authenticated. Normal protected routes accept an active Supabase session or an `hms_live_` personal token. - Routes marked `session only` accept only a Supabase session. Personal tokens cannot create/reveal tokens, administer access, manage members, or start/disconnect OAuth connections. - Supabase Studio sessions receive capabilities exclusively from the member `access_level` role. `api_access_level` never limits or disables a Studio session. - Only personal tokens use the individual API level. They are hash-only on the server, expire in 1–90 days, reveal their secret once, and are limited by token scopes plus `api_access_level` plus the current Studio role ceiling. - Personal-token API levels are `nenhum`, `leitor`, `criador`, `lider`, and `admin`; changing them affects PATs immediately without changing Studio-session permissions. - The credential must belong to an active `team_members` record. Capabilities are enforced by the server and authorization activity is audited without request bodies or secrets. - Use `api_revision`/`updated_at` as opaque CAS tokens and `Idempotency-Key` when the operation supports it. - Never send or store provider credentials, service-role keys, `.env` contents, temporary passwords, or access tokens in prompts/logs. - Read the exact current object before a mutation. Destructive, publishing, permission, and external actions require explicit user intent. - MCP tools are an explicit allowlist; never use them to bypass route capabilities or validation. ## Operations - `GET /api/access/audit` — Consultar a trilha de auditoria da API (Supabase session; capability: team_admin) - `GET /api/access/catalog` — Consultar o catálogo de rotas e ferramentas MCP (Central da API) (Supabase session; capability: team_admin) - `GET /api/access/me` — Consultar o próprio acesso individual à API (Supabase session) - `GET /api/access/members` — Listar acessos individuais da equipe (Supabase session; capability: team_admin) - `PATCH /api/access/members/{memberId}` — Alterar o nível individual de API de um membro (Supabase session; capability: team_admin) - `DELETE /api/access/members/{memberId}/tokens/{tokenId}` — Revogar um token pessoal como administrador (Supabase session; capability: team_admin) - `GET /api/access/tokens` — Listar os próprios tokens pessoais (Supabase session) - `POST /api/access/tokens` — Criar um token pessoal com escopo e expiração (Supabase session) - `DELETE /api/access/tokens/{tokenId}` — Revogar um token pessoal próprio (Supabase session) - `GET /api/ai/SKILL.md` — Baixar a skill operacional do Hermes (public) - `GET /api/ai/chatgpt.md` — Baixar instruções para ChatGPT (public) - `GET /api/ai/claude.md` — Baixar instruções para Claude (public) - `GET /api/ai/cursor.mdc` — Baixar regras do Cursor (public) - `GET /api/ai/hermes.mjs` — Baixar a CLI Hermes (public) - `GET /api/ai/llms-full.txt` — Baixar a referência completa para LLMs (public) - `GET /api/ai/llms.txt` — Baixar o índice conciso para LLMs (public) - `GET /api/ai/manifest.json` — Baixar o manifesto verificável dos artefatos (public) - `GET /api/ai/mcp-setup.md` — Baixar instruções de conexão MCP (public) - `GET /api/ai/openapi.json` — Baixar o contrato OpenAPI 3.1 (public) - `GET /api/ai/openapi.yaml` — Baixar o contrato OpenAPI 3.1 em YAML (public) - `GET /api/ai/postman.json` — Baixar a coleção Postman gerada (public) - `GET /api/ai/skill.zip` — Baixar a skill completa e instalável (public) - `GET /api/anexaveis` — Listar eventos que aceitam mídia do membro (session or personal token; capability: art) - `GET /api/aprovacoes` — Listar conteúdos aguardando aprovação (session or personal token; capability: approve) - `POST /api/aprovar` — Aprovar ou recusar conteúdo (session or personal token; capability: approve) - `POST /api/art` — Gerar e armazenar uma arte (session or personal token; capability: art) - `POST /api/carousel` — Gerar carrossel com até dez cards (session or personal token; capability: carousel) - `GET /api/config` — Ler configuração versionada (session or personal token; capability: config_view) - `POST /api/config` — Criar nova versão de uma configuração (session or personal token; capability: config) - `GET /api/config/log` — Listar histórico de configurações (session or personal token; capability: config) - `POST /api/demanda` — Criar demanda editorial (session or personal token; capability: tasks_assign) - `POST /api/draft` — Salvar rascunho editorial (session or personal token; capability: draft_save) - `GET /api/email-drafts` — Listar metadados de rascunhos de e-mail (session or personal token; capability: email_drafts_view) - `DELETE /api/email-drafts/{templateId}` — Excluir exatamente um rascunho com CAS (session or personal token; capability: delete) - `GET /api/email-drafts/{templateId}` — Consultar um rascunho de e-mail (session or personal token; capability: email_drafts_view) - `PUT /api/email-drafts/{templateId}` — Criar ou atualizar um rascunho com CAS (session or personal token; capability: email_drafts_edit) - `POST /api/enviar` — Enviar conteúdo para aprovação (session or personal token; capability: enviar) - `GET /api/health` — Consultar saúde do serviço (public) - `GET /api/insights/horarios` — Consultar melhores horários de publicação (session or personal token; capability: analytics) - `POST /api/jornada/eventos` — Receber eventos do checkout (servidor a servidor) (session or personal token) - `POST /api/jornada/lead` — Resumo de um lead para o SiteUP CRM (compras, origem e páginas) (session or personal token) - `POST /api/jornada/perfil` — Consultar o perfil de uma pessoa pelo e-mail (dado pessoal, só Financeiro) (session or personal token; capability: vendas) - `POST /api/jornada/ses` — Receber eventos de e-mail do SES (SNS) (session or personal token) - `POST /api/jornada/sincronizar` — Sincronizar a linha do tempo (session or personal token; capability: config) - `GET /api/lancamentos` — Listar os lançamentos com dashboard (session or personal token; capability: vendas) - `PUT /api/lancamentos/{projetoId}` — Cadastrar ou editar o dashboard de um projeto (session or personal token; capability: config) - `GET /api/lancamentos/{projetoId}/compradores` — Listar os compradores de um lançamento (session or personal token; capability: vendas) - `GET /api/lancamentos/{projetoId}/decisao` — Consultar o painel de decisão de um lançamento (session or personal token; capability: vendas) - `GET /api/lancamentos/{projetoId}/disparos` — Consultar os disparos de WhatsApp de um lançamento (session or personal token; capability: vendas) - `GET /api/lancamentos/{projetoId}/funil` — Consultar o funil do CRM de um lançamento (session or personal token; capability: vendas) - `GET /api/lancamentos/{projetoId}/jornada` — Consultar o funil da linha do tempo de um lançamento (session or personal token; capability: vendas) - `GET /api/lancamentos/{projetoId}/midia` — Consultar a mídia paga de um lançamento (session or personal token; capability: vendas) - `GET /api/lancamentos/{projetoId}/origem` — Consultar a origem das vendas de um lançamento (session or personal token; capability: vendas) - `GET /api/lancamentos/{projetoId}/perfis` — Consultar os perfis agregados de quem mexeu num lançamento (session or personal token; capability: vendas) - `GET /api/lancamentos/{projetoId}/resumo` — Consultar o painel de um lançamento (session or personal token; capability: vendas) - `GET /api/lancamentos/{projetoId}/saude` — Consultar a saúde de um lançamento (session or personal token; capability: vendas) - `POST /api/mcp` — Chamar o MCP Streamable HTTP do Hermes (session or personal token) - `GET /api/me` — Consultar membro autenticado e capacidades (session or personal token) - `GET /api/membros` — Listar membros ativos (Supabase session; capability: members) - `PATCH /api/membros` — Alterar nível de acesso ou permissão financeira (Supabase session; capability: members) - `POST /api/membros` — Convidar um novo membro (Supabase session; capability: members) - `DELETE /api/membros/{memberId}` — Revogar acesso e limpar atribuições atuais (Supabase session; capability: members) - `POST /api/membros/{memberId}/senha` — Definir senha nova para um membro (Supabase session; capability: members) - `POST /api/orbum/cancelamentos` — Registrar o motivo de saída de um assinante do Orbum (session or personal token; capability: vendas) - `GET /api/orbum/resumo` — Consultar o painel da assinatura Orbum (session or personal token; capability: vendas) - `GET /api/orbum/saidas` — Listar quem está saindo do Orbum (session or personal token; capability: vendas) - `GET /api/plataformas/{platformId}/senha` — Ler a senha de uma plataforma (Supabase session; capability: team_admin) - `PUT /api/plataformas/{platformId}/senha` — Gravar ou apagar a senha de uma plataforma (Supabase session; capability: team_admin) - `GET /api/projects` — Listar projetos colaborativos (session or personal token; capability: projects_view) - `POST /api/projects` — Criar projeto colaborativo vazio (session or personal token; capability: projects_manage) - `GET /api/projects/{projectId}` — Consultar um projeto e seu token CAS (session or personal token; capability: projects_view) - `GET /api/projects/{projectId}/operations` — Listar histórico de operações do projeto (session or personal token; capability: projects_audit_view) - `POST /api/projects/{projectId}/operations` — Aplicar uma operação semântica com CAS (session or personal token; capability: projects_edit by default; projects_manage according to the documented operation type) - `POST /api/rag` — Buscar contexto e citações no Cérebro (session or personal token; capability: rag) - `POST /api/reels` — Iniciar geração assíncrona de vídeo (session or personal token; capability: video) - `GET /api/reels/{id}` — Consultar uma geração de vídeo (session or personal token; capability: reels_view) - `POST /api/roteiro` — Gerar roteiro com pesquisa e verificação (session or personal token; capability: roteiro) - `GET /api/skills` — Listar skills publicadas (session or personal token; capability: skills_view) - `POST /api/skills` — Publicar nova versão de uma skill (session or personal token; capability: config) - `GET /api/tarefas` — Listar tarefas ativas do membro (session or personal token; capability: tasks_view) - `POST /api/upload` — Enviar arquivo pronto (session or personal token; capability: art) - `GET /api/vendas/comercial` — Consultar as vendas do time comercial e a comissão (session or personal token; capability: vendas) - `GET /api/vendas/resumo` — Consultar o resumo de vendas do período (session or personal token; capability: vendas) - `GET /media/{id}` — Baixar uma mídia pelo domínio do Hermes (public) - `GET /oauth/_accounts` — Listar provedores e contas conectadas (session or personal token; capability: connections_view) - `GET /oauth/tiktok/creator-info` — Consultar restrições do criador no TikTok (session or personal token; capability: connections_view) - `POST /oauth/tiktok/publish` — Publicar conteúdo no TikTok (session or personal token; capability: publish) - `GET /oauth/{provider}/callback` — Concluir callback OAuth (public) - `POST /oauth/{provider}/disconnect` — Desconectar um provedor social (Supabase session; capability: connections) - `POST /oauth/{provider}/start` — Iniciar autorização OAuth (Supabase session; capability: connections) - `GET /oauth/{provider}/status` — Exibir diagnóstico HTML da conexão (session or personal token; capability: connections_view) ## Generated artifacts - https://socialmedia.janvalellam.com.br/api/ai/SKILL.md — Baixar a skill operacional do Hermes. - https://socialmedia.janvalellam.com.br/api/ai/chatgpt.md — Baixar instruções para ChatGPT. - https://socialmedia.janvalellam.com.br/api/ai/claude.md — Baixar instruções para Claude. - https://socialmedia.janvalellam.com.br/api/ai/cursor.mdc — Baixar regras do Cursor. - https://socialmedia.janvalellam.com.br/api/ai/hermes.mjs — Baixar a CLI Hermes. - https://socialmedia.janvalellam.com.br/api/ai/llms-full.txt — Baixar a referência completa para LLMs. - https://socialmedia.janvalellam.com.br/api/ai/llms.txt — Baixar o índice conciso para LLMs. - https://socialmedia.janvalellam.com.br/api/ai/manifest.json — Baixar o manifesto verificável dos artefatos. - https://socialmedia.janvalellam.com.br/api/ai/mcp-setup.md — Baixar instruções de conexão MCP. - https://socialmedia.janvalellam.com.br/api/ai/openapi.json — Baixar o contrato OpenAPI 3.1. - https://socialmedia.janvalellam.com.br/api/ai/openapi.yaml — Baixar o contrato OpenAPI 3.1 em YAML. - https://socialmedia.janvalellam.com.br/api/ai/postman.json — Baixar a coleção Postman gerada. - https://socialmedia.janvalellam.com.br/api/ai/skill.zip — Baixar a skill completa e instalável. ## Detailed operation reference ### GET /api/access/audit Consultar a trilha de auditoria da API Exige sessão Supabase de administrador da equipe. Lista eventos recentes de autorização e gestão sem corpo da requisição, Authorization, segredo, hash de token ou conteúdo sensível. - operationId: `listApiAccessAudit` - authentication: Supabase session bearer token (session only) - required capability: `team_admin` #### Parameters ##### query limit - required: false - description: Máximo de eventos recentes. Schema: ```json { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } ``` Example: ```json 100 ``` ##### query member_id - required: false - description: Filtrar pelo membro autor do evento. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do evento de auditoria." }, "occurred_at": { "type": "string", "description": "Data/hora do evento.", "format": "date-time" }, "request_id": { "anyOf": [ { "type": "string", "description": "Correlação segura da requisição." }, { "type": "null" } ] }, "actor_member_id": { "anyOf": [ { "type": "string", "description": "Membro autor." }, { "type": "null" } ] }, "actor_user_id": { "anyOf": [ { "type": "string", "description": "Usuário Supabase autor." }, { "type": "null" } ] }, "token_id": { "anyOf": [ { "type": "string", "description": "ID de metadados do token pessoal, nunca o segredo ou hash." }, { "type": "null" } ] }, "auth_method": { "type": "string", "description": "Método de autenticação observado.", "enum": [ "session", "personal_token", "system", "anonymous" ] }, "capability": { "anyOf": [ { "type": "string", "description": "Capability avaliada." }, { "type": "null" } ] }, "action": { "type": "string", "description": "Ação normalizada." }, "resource_type": { "anyOf": [ { "type": "string", "description": "Tipo lógico do recurso." }, { "type": "null" } ] }, "resource_id": { "anyOf": [ { "type": "string", "description": "ID lógico do recurso." }, { "type": "null" } ] }, "outcome": { "type": "string", "description": "Resultado normalizado.", "enum": [ "allowed", "denied", "succeeded", "failed" ] }, "status_code": { "anyOf": [ { "type": "integer", "description": "Status HTTP relacionado.", "minimum": 100, "maximum": 599 }, { "type": "null" } ] }, "metadata": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "id", "occurred_at", "auth_method", "action", "outcome", "metadata" ], "description": "Evento sanitizado da trilha de autorização e gestão de acesso à API." } } }, "required": [ "audit" ] } ``` Example: ```json { "audit": [ { "id": "id-exemplo", "occurred_at": "2026-08-22T15:00:00.000Z", "request_id": "request-id-exemplo", "actor_member_id": "actor-member-id-exemplo", "actor_user_id": "actor-user-id-exemplo", "token_id": "token-id-exemplo", "auth_method": "session", "capability": "string", "action": "string", "resource_type": "string", "resource_id": "resource-id-exemplo", "outcome": "allowed", "status_code": 100, "metadata": {} } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/access/catalog Consultar o catálogo de rotas e ferramentas MCP (Central da API) Catálogo da Central da API: todas as rotas do contrato com área, permissão exigida, nível mínimo que a tem (ou a flag Financeiro), se é só de sessão ou webhook, os parâmetros de caminho e de query e o nome da ferramenta MCP equivalente. Sai do mesmo contrato que gera o MCP. Só administradores, por sessão do Studio. - operationId: `getApiCatalog` - authentication: Supabase session bearer token (session only) - required capability: `team_admin` #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "total": { "type": "integer", "description": "Rotas no contrato." }, "com_ferramenta": { "type": "integer", "description": "Rotas com ferramenta MCP." }, "mcp_url": { "type": "string", "description": "Endereço do MCP." }, "rotas": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Uma entrada por rota." } }, "required": [ "total", "rotas" ], "additionalProperties": true } ``` Example: ```json { "total": 1, "com_ferramenta": 1, "mcp_url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura", "rotas": [ {} ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/access/me Consultar o próprio acesso individual à API Exige sessão Supabase interativa e nunca aceita token pessoal. Retorna a configuração destinada aos tokens pessoais do membro, o nível efetivo limitado pelo cargo do Studio e a contagem de tokens ativos; essa configuração não limita a própria sessão. - operationId: `getMyApiAccess` - authentication: Supabase session bearer token (session only) #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "member": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do membro." }, "name": { "type": "string", "description": "Nome." }, "email": { "anyOf": [ { "type": "string", "description": "E-mail.", "format": "email" }, { "type": "null" } ] }, "access_level": { "type": "string", "description": "Cargo atual no Studio; governa a sessão e funciona como teto do PAT.", "enum": [ "criador", "lider", "admin" ] }, "financeiro": { "type": "boolean", "description": "Permissão por pessoa: vê o painel de Vendas." }, "api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "effective_api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] } }, "required": [ "id", "name", "access_level", "api_access_level", "effective_api_access_level" ], "description": "Resumo da configuração de tokens pessoais do membro; não limita a sessão atual do Studio." }, "capabilities": { "type": "array", "items": { "type": "string", "description": "Capability efetiva disponível para novos tokens." } }, "token_count": { "type": "integer", "description": "Quantidade de tokens pessoais ativos.", "minimum": 0, "maximum": 10 } }, "required": [ "member", "capabilities", "token_count" ] } ``` Example: ```json { "member": { "id": "id-exemplo", "name": "Exemplo Hermes", "email": "membro@example.com", "access_level": "criador", "financeiro": true, "api_access_level": "nenhum", "effective_api_access_level": "nenhum" }, "capabilities": [ "string" ], "token_count": 0 } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/access/members Listar acessos individuais da equipe Exige sessão Supabase de administrador da equipe. Lista membros ativos, cargo do Studio e configuração exclusiva dos tokens pessoais, capabilities efetivas de PAT e metadados de tokens, sem segredo ou hash. - operationId: `listApiAccessMembers` - authentication: Supabase session bearer token (session only) - required capability: `team_admin` #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "levels": { "type": "array", "items": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "description": "Níveis configuráveis em ordem crescente." }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do membro." }, "name": { "type": "string", "description": "Nome." }, "email": { "anyOf": [ { "type": "string", "description": "E-mail.", "format": "email" }, { "type": "null" } ] }, "access_level": { "type": "string", "description": "Cargo atual no Studio; governa sessões e funciona como teto do PAT.", "enum": [ "criador", "lider", "admin" ] }, "api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "effective_api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "capabilities": { "type": "array", "items": { "type": "string", "description": "Capability efetiva disponível para tokens pessoais; não descreve nem limita a sessão do Studio." } }, "token_count": { "type": "integer", "description": "Quantidade de tokens ativos.", "minimum": 0, "maximum": 10 }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID público usado para revogação." }, "label": { "type": "string", "description": "Nome legível definido pelo usuário." }, "prefix": { "type": "string", "description": "Prefixo identificável sem a parte secreta.", "pattern": "^hms_live_[A-Za-z0-9_-]{16}$" }, "scopes": { "type": "array", "items": { "type": "string", "description": "Capability concedida ao token." }, "description": "Scopes persistidos em ordem determinística." }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "expires_at": { "type": "string", "description": "Expiração ISO.", "format": "date-time" }, "last_used_at": { "anyOf": [ { "type": "string", "description": "Último uso observado, atualizado de forma best effort.", "format": "date-time" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "description": "Revogação ISO, quando aplicável.", "format": "date-time" }, { "type": "null" } ] }, "status": { "type": "string", "description": "Estado derivado no momento da leitura.", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "id", "label", "prefix", "scopes", "created_at", "expires_at", "last_used_at", "revoked_at", "status" ], "description": "Metadados revogáveis de um token pessoal sem segredo nem hash." } } }, "required": [ "id", "name", "access_level", "api_access_level", "effective_api_access_level", "capabilities", "token_count", "tokens" ], "description": "Visão administrativa do cargo do Studio e da camada separada de tokens pessoais de um membro ativo." } } }, "required": [ "levels", "members" ] } ``` Example: ```json { "levels": [ "nenhum" ], "members": [ { "id": "id-exemplo", "name": "Exemplo Hermes", "email": "membro@example.com", "access_level": "criador", "api_access_level": "nenhum", "effective_api_access_level": "nenhum", "capabilities": [ "string" ], "token_count": 0, "tokens": [ { "id": "id-exemplo", "label": "string", "prefix": "string", "scopes": [ "string" ], "created_at": "2026-08-22T15:00:00.000Z", "expires_at": "2026-08-22T15:00:00.000Z", "last_used_at": "2026-08-22T15:00:00.000Z", "revoked_at": "2026-08-22T15:00:00.000Z", "status": "active" } ] } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### PATCH /api/access/members/{memberId} Alterar o nível individual de API de um membro Exige sessão Supabase de administrador da equipe. O nível da API nunca pode superar o cargo atual no Studio; rebaixamentos reduzem permissões imediatamente e `nenhum` revoga todos os tokens ativos. - operationId: `updateMemberApiAccess` - authentication: Supabase session bearer token (session only) - required capability: `team_admin` #### Parameters ##### path memberId - required: true - description: ID de team_members. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] } }, "required": [ "api_access_level" ] } ``` Example: ```json { "api_access_level": "leitor" } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Atualização concluída." }, "member": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do membro." }, "name": { "type": "string", "description": "Nome." }, "email": { "anyOf": [ { "type": "string", "description": "E-mail.", "format": "email" }, { "type": "null" } ] }, "access_level": { "type": "string", "description": "Cargo atual no Studio; governa sessões e funciona como teto do PAT.", "enum": [ "criador", "lider", "admin" ] }, "api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "effective_api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "capabilities": { "type": "array", "items": { "type": "string", "description": "Capability efetiva disponível para tokens pessoais; não descreve nem limita a sessão do Studio." } }, "token_count": { "type": "integer", "description": "Quantidade de tokens ativos.", "minimum": 0, "maximum": 10 }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID público usado para revogação." }, "label": { "type": "string", "description": "Nome legível definido pelo usuário." }, "prefix": { "type": "string", "description": "Prefixo identificável sem a parte secreta.", "pattern": "^hms_live_[A-Za-z0-9_-]{16}$" }, "scopes": { "type": "array", "items": { "type": "string", "description": "Capability concedida ao token." }, "description": "Scopes persistidos em ordem determinística." }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "expires_at": { "type": "string", "description": "Expiração ISO.", "format": "date-time" }, "last_used_at": { "anyOf": [ { "type": "string", "description": "Último uso observado, atualizado de forma best effort.", "format": "date-time" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "description": "Revogação ISO, quando aplicável.", "format": "date-time" }, { "type": "null" } ] }, "status": { "type": "string", "description": "Estado derivado no momento da leitura.", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "id", "label", "prefix", "scopes", "created_at", "expires_at", "last_used_at", "revoked_at", "status" ], "description": "Metadados revogáveis de um token pessoal sem segredo nem hash." } } }, "required": [ "id", "name", "access_level", "api_access_level", "effective_api_access_level", "capabilities", "token_count", "tokens" ], "description": "Visão administrativa do cargo do Studio e da camada separada de tokens pessoais de um membro ativo." } }, "required": [ "ok", "member" ] } ``` Example: ```json { "ok": true, "member": { "id": "id-exemplo", "name": "Exemplo Hermes", "email": "membro@example.com", "access_level": "criador", "api_access_level": "nenhum", "effective_api_access_level": "nenhum", "capabilities": [ "string" ], "token_count": 0, "tokens": [ { "id": "id-exemplo", "label": "string", "prefix": "string", "scopes": [ "string" ], "created_at": "2026-08-22T15:00:00.000Z", "expires_at": "2026-08-22T15:00:00.000Z", "last_used_at": "2026-08-22T15:00:00.000Z", "revoked_at": "2026-08-22T15:00:00.000Z", "status": "active" } ] } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### DELETE /api/access/members/{memberId}/tokens/{tokenId} Revogar um token pessoal como administrador Exige sessão Supabase de administrador da equipe. Revoga exatamente o token indicado de um membro, preservando metadados e trilha de auditoria. - operationId: `revokeMemberApiToken` - authentication: Supabase session bearer token (session only) - required capability: `team_admin` #### Parameters ##### path memberId - required: true - description: ID de team_members. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### path tokenId - required: true - description: ID público de metadados do token pessoal; nunca é o segredo `hms_live_` nem seu hash. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Revogação concluída." }, "token": { "type": "object", "properties": { "id": { "type": "string", "description": "ID público usado para revogação." }, "label": { "type": "string", "description": "Nome legível definido pelo usuário." }, "prefix": { "type": "string", "description": "Prefixo identificável sem a parte secreta.", "pattern": "^hms_live_[A-Za-z0-9_-]{16}$" }, "scopes": { "type": "array", "items": { "type": "string", "description": "Capability concedida ao token." }, "description": "Scopes persistidos em ordem determinística." }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "expires_at": { "type": "string", "description": "Expiração ISO.", "format": "date-time" }, "last_used_at": { "anyOf": [ { "type": "string", "description": "Último uso observado, atualizado de forma best effort.", "format": "date-time" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "description": "Revogação ISO, quando aplicável.", "format": "date-time" }, { "type": "null" } ] }, "status": { "type": "string", "description": "Estado derivado no momento da leitura.", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "id", "label", "prefix", "scopes", "created_at", "expires_at", "last_used_at", "revoked_at", "status" ], "description": "Metadados revogáveis de um token pessoal sem segredo nem hash." } }, "required": [ "ok", "token" ] } ``` Example: ```json { "ok": true, "token": { "id": "id-exemplo", "label": "string", "prefix": "string", "scopes": [ "string" ], "created_at": "2026-08-22T15:00:00.000Z", "expires_at": "2026-08-22T15:00:00.000Z", "last_used_at": "2026-08-22T15:00:00.000Z", "revoked_at": "2026-08-22T15:00:00.000Z", "status": "active" } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/access/tokens Listar os próprios tokens pessoais Exige sessão Supabase interativa. Lista somente metadados dos tokens pessoais do próprio membro; o valor secreto e o hash nunca são retornados. - operationId: `listMyApiTokens` - authentication: Supabase session bearer token (session only) #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID público usado para revogação." }, "label": { "type": "string", "description": "Nome legível definido pelo usuário." }, "prefix": { "type": "string", "description": "Prefixo identificável sem a parte secreta.", "pattern": "^hms_live_[A-Za-z0-9_-]{16}$" }, "scopes": { "type": "array", "items": { "type": "string", "description": "Capability concedida ao token." }, "description": "Scopes persistidos em ordem determinística." }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "expires_at": { "type": "string", "description": "Expiração ISO.", "format": "date-time" }, "last_used_at": { "anyOf": [ { "type": "string", "description": "Último uso observado, atualizado de forma best effort.", "format": "date-time" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "description": "Revogação ISO, quando aplicável.", "format": "date-time" }, { "type": "null" } ] }, "status": { "type": "string", "description": "Estado derivado no momento da leitura.", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "id", "label", "prefix", "scopes", "created_at", "expires_at", "last_used_at", "revoked_at", "status" ], "description": "Metadados revogáveis de um token pessoal sem segredo nem hash." } } }, "required": [ "tokens" ] } ``` Example: ```json { "tokens": [ { "id": "id-exemplo", "label": "string", "prefix": "string", "scopes": [ "string" ], "created_at": "2026-08-22T15:00:00.000Z", "expires_at": "2026-08-22T15:00:00.000Z", "last_used_at": "2026-08-22T15:00:00.000Z", "revoked_at": "2026-08-22T15:00:00.000Z", "status": "active" } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/access/tokens Criar um token pessoal com escopo e expiração Exige sessão Supabase interativa. Cria um token pessoal com validade de 1 a 90 dias e scopes dentro do acesso efetivo. O segredo `hms_live_` aparece uma única vez nesta resposta e não pode ser recuperado depois. - operationId: `createMyApiToken` - authentication: Supabase session bearer token (session only) #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Defina um rótulo, validade entre 1 e 90 dias e, opcionalmente, scopes dentro do acesso efetivo. Se scopes for omitido, o servidor usa todas as capabilities atuais. ##### application/json Schema: ```json { "type": "object", "properties": { "label": { "type": "string", "description": "Nome legível do uso ou dispositivo.", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "items": { "type": "string", "description": "Capability solicitada.", "pattern": "^[a-z][a-z0-9_.:-]{0,79}$" }, "description": "Subconjunto opcional das capabilities efetivas.", "minItems": 1, "maxItems": 64, "uniqueItems": true }, "expiresInDays": { "type": "integer", "description": "Validade do token em dias; padrão 30.", "minimum": 1, "maximum": 90, "default": 30 }, "expires_in_days": { "type": "integer", "description": "Alias compatível de expiresInDays; prefira expiresInDays em novos clientes.", "minimum": 1, "maximum": 90, "deprecated": true } }, "required": [ "label" ] } ``` Example: ```json { "label": "Automação editorial", "scopes": [ "projects_view", "projects_edit" ], "expiresInDays": 30 } ``` #### Responses ##### 201 Token criado. O campo token aparece somente nesta resposta e deve ser guardado imediatamente. ###### application/json Schema: ```json { "type": "object", "properties": { "token": { "type": "string", "description": "Segredo pessoal exibido uma única vez.", "pattern": "^hms_live_[A-Za-z0-9_-]{16}\\.[A-Za-z0-9_-]{43}$", "x-sensitive": true }, "metadata": { "type": "object", "properties": { "id": { "type": "string", "description": "ID público usado para revogação." }, "label": { "type": "string", "description": "Nome legível definido pelo usuário." }, "prefix": { "type": "string", "description": "Prefixo identificável sem a parte secreta.", "pattern": "^hms_live_[A-Za-z0-9_-]{16}$" }, "scopes": { "type": "array", "items": { "type": "string", "description": "Capability concedida ao token." }, "description": "Scopes persistidos em ordem determinística." }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "expires_at": { "type": "string", "description": "Expiração ISO.", "format": "date-time" }, "last_used_at": { "anyOf": [ { "type": "string", "description": "Último uso observado, atualizado de forma best effort.", "format": "date-time" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "description": "Revogação ISO, quando aplicável.", "format": "date-time" }, { "type": "null" } ] }, "status": { "type": "string", "description": "Estado derivado no momento da leitura.", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "id", "label", "prefix", "scopes", "created_at", "expires_at", "last_used_at", "revoked_at", "status" ], "description": "Metadados revogáveis de um token pessoal sem segredo nem hash." } }, "required": [ "token", "metadata" ] } ``` Example: ```json { "token": "hms_live_.", "metadata": { "id": "token-id", "label": "Automação editorial", "prefix": "hms_live_EXAMPLE123456789", "scopes": [ "projects_view", "projects_edit" ], "created_at": "2026-08-22T12:00:00.000Z", "expires_at": "2026-09-21T12:00:00.000Z", "last_used_at": null, "revoked_at": null, "status": "active" } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 429 Limite de dez tokens ativos por usuário atingido. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "cada usuario pode manter no maximo 10 tokens ativos", "code": "API_TOKEN_LIMIT" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### DELETE /api/access/tokens/{tokenId} Revogar um token pessoal próprio Exige sessão Supabase interativa. Revoga um token do próprio membro de forma idempotente; somente metadados seguros permanecem disponíveis para auditoria. - operationId: `revokeMyApiToken` - authentication: Supabase session bearer token (session only) #### Parameters ##### path tokenId - required: true - description: ID público de metadados do token pessoal; nunca é o segredo `hms_live_` nem seu hash. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Revogação concluída." }, "token": { "type": "object", "properties": { "id": { "type": "string", "description": "ID público usado para revogação." }, "label": { "type": "string", "description": "Nome legível definido pelo usuário." }, "prefix": { "type": "string", "description": "Prefixo identificável sem a parte secreta.", "pattern": "^hms_live_[A-Za-z0-9_-]{16}$" }, "scopes": { "type": "array", "items": { "type": "string", "description": "Capability concedida ao token." }, "description": "Scopes persistidos em ordem determinística." }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "expires_at": { "type": "string", "description": "Expiração ISO.", "format": "date-time" }, "last_used_at": { "anyOf": [ { "type": "string", "description": "Último uso observado, atualizado de forma best effort.", "format": "date-time" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "description": "Revogação ISO, quando aplicável.", "format": "date-time" }, { "type": "null" } ] }, "status": { "type": "string", "description": "Estado derivado no momento da leitura.", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "id", "label", "prefix", "scopes", "created_at", "expires_at", "last_used_at", "revoked_at", "status" ], "description": "Metadados revogáveis de um token pessoal sem segredo nem hash." } }, "required": [ "ok", "token" ] } ``` Example: ```json { "ok": true, "token": { "id": "id-exemplo", "label": "string", "prefix": "string", "scopes": [ "string" ], "created_at": "2026-08-22T15:00:00.000Z", "expires_at": "2026-08-22T15:00:00.000Z", "last_used_at": "2026-08-22T15:00:00.000Z", "revoked_at": "2026-08-22T15:00:00.000Z", "status": "active" } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/ai/SKILL.md Baixar a skill operacional do Hermes Instruções de operação segura, roteamento de repositórios e deploy. Instruções operacionais da skill oficial do Hermes. Use o ZIP quando quiser instalar também referências, metadados e scripts auxiliares. - operationId: `getAiSkill` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Skill Markdown. ###### text/markdown Schema: ```json { "type": "string" } ``` Example: ```json "# Hermes Publisher\n\nDocumentação gerada.\n" ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/ai/chatgpt.md Baixar instruções para ChatGPT Instruções para projetos e GPTs que operam o Hermes, incluindo limites de segurança, CAS e confirmação de ações destrutivas. - operationId: `getAiChatGptInstructions` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Instruções ChatGPT. ###### text/markdown Schema: ```json { "type": "string" } ``` Example: ```json "# Hermes Publisher\n\nDocumentação gerada.\n" ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/ai/claude.md Baixar instruções para Claude Instruções de projeto para Claude, geradas da mesma versão do contrato público. - operationId: `getAiClaudeInstructions` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Instruções Claude. ###### text/markdown Schema: ```json { "type": "string" } ``` Example: ```json "# Hermes Publisher\n\nDocumentação gerada.\n" ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/ai/cursor.mdc Baixar regras do Cursor Regras de projeto para configurar o Cursor com o contrato e as práticas seguras do Hermes. - operationId: `getAiCursorRules` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Cursor Rules. ###### text/plain Schema: ```json { "type": "string" } ``` Example: ```json "Operação concluída." ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/ai/hermes.mjs Baixar a CLI Hermes CLI Node.js sem dependências externas para autenticar por sessão Supabase, consultar o manifesto e instalar artefatos oficiais com verificação de integridade. Tokens pessoais são destinados ao HTTP/MCP e não são gravados automaticamente pela CLI. - operationId: `getAiCli` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 CLI Node.js. ###### text/javascript Schema: ```json { "type": "string" } ``` Example: ```json "#!/usr/bin/env node\n// Hermes CLI\n" ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/ai/llms-full.txt Baixar a referência completa para LLMs Referência expandida para LLMs, com referências locais resolvidas, corpos de requisição, respostas e exemplos de todas as operações. - operationId: `getAiLlmsFull` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operações e schemas completos gerados do OpenAPI. ###### text/plain Schema: ```json { "type": "string" } ``` Example: ```json "Operação concluída." ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/ai/llms.txt Baixar o índice conciso para LLMs Índice curto, em texto puro, para descoberta por agentes. Ele aponta para o contrato completo e resume as operações disponíveis. - operationId: `getAiLlms` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Índice conciso gerado do OpenAPI. ###### text/plain Schema: ```json { "type": "string" } ``` Example: ```json "Operação concluída." ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/ai/manifest.json Baixar o manifesto verificável dos artefatos Lista cada artefato público com URL, MIME type, tamanho e SHA-256. É a fonte para downloads verificáveis e atualização automatizada. - operationId: `getAiManifest` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Manifesto com versão, tamanho e SHA-256. ###### application/json Schema: ```json { "type": "object", "properties": { "schema_version": { "type": "integer", "description": "Versão do formato.", "const": 1 }, "release": { "type": "object", "properties": { "version": { "type": "string", "description": "Versão da camada de IA." }, "date": { "type": "string", "description": "Data ISO.", "format": "date" } }, "required": [ "version", "date" ] }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID estável." }, "path": { "type": "string", "description": "Caminho no repositório." }, "url": { "type": "string", "description": "URL pública.", "format": "uri" }, "media_type": { "type": "string", "description": "MIME." }, "bytes": { "type": "integer", "description": "Tamanho.", "minimum": 1 }, "sha256": { "type": "string", "description": "SHA-256 hexadecimal.", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "path", "url", "media_type", "bytes", "sha256" ] } }, "skills": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome da skill." }, "version": { "type": "string", "description": "Versão." }, "artifact_id": { "type": "string", "description": "ID do ZIP." }, "sha256": { "type": "string", "description": "SHA-256 do ZIP." } }, "required": [ "name", "version", "artifact_id", "sha256" ] } } }, "required": [ "schema_version", "release", "artifacts", "skills" ], "description": "Catálogo verificável dos artefatos públicos da camada de IA." } ``` Example: ```json { "schema_version": 1, "release": { "version": "string", "date": "2026-08-22" }, "artifacts": [ { "id": "id-exemplo", "path": "string", "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura", "media_type": "string", "bytes": 1, "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ], "skills": [ { "name": "Exemplo Hermes", "version": "string", "artifact_id": "artifact-id-exemplo", "sha256": "string" } ] } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/ai/mcp-setup.md Baixar instruções de conexão MCP Guia de conexão ao MCP stateless do Hermes para clientes compatíveis. Use uma sessão Supabase ativa ou um token pessoal `hms_live_` com os scopes exigidos pelas tools. - operationId: `getAiMcpSetup` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Configuração MCP para clientes compatíveis. ###### text/markdown Schema: ```json { "type": "string" } ``` Example: ```json "# Hermes Publisher\n\nDocumentação gerada.\n" ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/ai/openapi.json Baixar o contrato OpenAPI 3.1 Fonte pública das rotas, autenticação, capabilities, corpos e respostas do Hermes Publisher. Use este documento como fonte canônica para gerar clientes, validar payloads e descobrir códigos de resposta. O JSON e o YAML descrevem exatamente o mesmo contrato. - operationId: `getAiOpenApi` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Contrato OpenAPI 3.1. ###### application/json Schema: ```json { "type": "object", "properties": {}, "additionalProperties": true } ``` Example: ```json {} ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/ai/openapi.yaml Baixar o contrato OpenAPI 3.1 em YAML Versão YAML do contrato canônico, indicada para Scalar, Swagger UI, Postman, geradores de SDK e assistentes de código. - operationId: `getAiOpenApiYaml` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Contrato OpenAPI 3.1 em YAML. ###### application/yaml Schema: ```json { "type": "string" } ``` Example: ```json "openapi: 3.1.0\ninfo:\n title: Hermes Publisher API\n" ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/ai/postman.json Baixar a coleção Postman gerada Contém somente placeholders; nenhum token ou segredo é distribuído. Coleção gerada automaticamente do OpenAPI. Defina `baseUrl` e `accessToken` no ambiente do Postman; o arquivo distribuído não contém credenciais. - operationId: `getAiPostmanCollection` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Postman Collection v2.1. ###### application/json Schema: ```json { "type": "object", "properties": {}, "additionalProperties": true } ``` Example: ```json {} ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/ai/skill.zip Baixar a skill completa e instalável ZIP determinístico com SKILL.md, agents/openai.yaml, CLI e referências versionadas. Pacote determinístico da skill oficial. Confira o SHA-256 publicado no manifesto antes de instalar ou atualizar. - operationId: `getAiSkillZip` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Skill ZIP. ###### application/zip Schema: ```json { "type": "string", "contentMediaType": "application/zip" } ``` Example: ```json "" ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Artefato ausente no build. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "artefato de IA indisponivel" } ``` ### GET /api/anexaveis Listar eventos que aceitam mídia do membro Lista eventos nos quais o membro pode anexar mídia, já acompanhados das referências atualmente persistidas. - operationId: `listAttachableEvents` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `art` #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "eventos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do evento." }, "api_revision": { "type": "integer", "description": "Token CAS da API; releia o evento antes de toda mutação.", "minimum": 0 }, "clickup_id": { "anyOf": [ { "type": "string", "description": "Identificador externo/legado." }, { "type": "null" } ] }, "title": { "type": "string", "description": "Título editorial." }, "channel": { "type": "string", "description": "Canal de publicação." }, "status": { "type": "string", "description": "Estado do fluxo editorial." }, "description": { "anyOf": [ { "type": "string", "description": "Legenda ou descrição." }, { "type": "null" } ] }, "day": { "anyOf": [ { "type": "integer", "description": "Dia no horário de Brasília.", "minimum": 1, "maximum": 31 }, { "type": "null" } ] }, "month": { "anyOf": [ { "type": "integer", "description": "Mês no horário de Brasília.", "minimum": 1, "maximum": 12 }, { "type": "null" } ] }, "year": { "anyOf": [ { "type": "integer", "description": "Ano no horário de Brasília." }, { "type": "null" } ] }, "due_at": { "anyOf": [ { "type": "string", "description": "Data/hora ISO 8601 persistida.", "format": "date-time" }, { "type": "null" } ] }, "editorial_tag": { "anyOf": [ { "type": "string", "description": "Tipo/tag editorial." }, { "type": "null" } ] }, "assignee_member_ids": { "type": "array", "items": { "type": "string", "description": "ID de membro." }, "description": "Responsáveis por ID." }, "assignees_names": { "type": "array", "items": { "type": "string", "description": "Nome de membro." }, "description": "Nomes dos responsáveis." }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "url": { "type": "string", "description": "URL pública no Hermes.", "format": "uri" }, "slide_index": { "type": "integer", "description": "Ordem." }, "kind": { "type": "string", "description": "Tipo lógico." } }, "required": [ "id", "url" ], "additionalProperties": true, "description": "Referência pública e ordenável de uma mídia persistida." } } }, "additionalProperties": true } } }, "required": [ "eventos" ] } ``` Example: ```json { "eventos": [ { "id": "id-exemplo", "api_revision": 0, "clickup_id": "clickup-id-exemplo", "title": "Conteúdo editorial", "channel": "instagram", "status": "processing", "description": "Conteúdo de exemplo", "day": 1, "month": 1, "year": 1, "due_at": "2026-08-22T15:00:00.000Z", "editorial_tag": "string", "assignee_member_ids": [ "assignee-member-id-exemplo" ], "assignees_names": [ "Exemplo Hermes" ], "media": [ { "id": "id-exemplo", "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura", "slide_index": 1, "kind": "string" } ] } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/aprovacoes Listar conteúdos aguardando aprovação Lista conteúdos aguardando decisão para membros com capability `approve`, incluindo mídias e revisão atual do evento. - operationId: `listApprovals` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `approve` #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "pendentes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do evento." }, "api_revision": { "type": "integer", "description": "Token CAS da API; releia o evento antes de toda mutação.", "minimum": 0 }, "clickup_id": { "anyOf": [ { "type": "string", "description": "Identificador externo/legado." }, { "type": "null" } ] }, "title": { "type": "string", "description": "Título editorial." }, "channel": { "type": "string", "description": "Canal de publicação." }, "status": { "type": "string", "description": "Estado do fluxo editorial." }, "description": { "anyOf": [ { "type": "string", "description": "Legenda ou descrição." }, { "type": "null" } ] }, "day": { "anyOf": [ { "type": "integer", "description": "Dia no horário de Brasília.", "minimum": 1, "maximum": 31 }, { "type": "null" } ] }, "month": { "anyOf": [ { "type": "integer", "description": "Mês no horário de Brasília.", "minimum": 1, "maximum": 12 }, { "type": "null" } ] }, "year": { "anyOf": [ { "type": "integer", "description": "Ano no horário de Brasília." }, { "type": "null" } ] }, "due_at": { "anyOf": [ { "type": "string", "description": "Data/hora ISO 8601 persistida.", "format": "date-time" }, { "type": "null" } ] }, "editorial_tag": { "anyOf": [ { "type": "string", "description": "Tipo/tag editorial." }, { "type": "null" } ] }, "assignee_member_ids": { "type": "array", "items": { "type": "string", "description": "ID de membro." }, "description": "Responsáveis por ID." }, "assignees_names": { "type": "array", "items": { "type": "string", "description": "Nome de membro." }, "description": "Nomes dos responsáveis." }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "url": { "type": "string", "description": "URL pública no Hermes.", "format": "uri" }, "slide_index": { "type": "integer", "description": "Ordem." }, "kind": { "type": "string", "description": "Tipo lógico." } }, "required": [ "id", "url" ], "additionalProperties": true, "description": "Referência pública e ordenável de uma mídia persistida." } } }, "additionalProperties": true } } }, "required": [ "pendentes" ] } ``` Example: ```json { "pendentes": [ { "id": "id-exemplo", "api_revision": 0, "clickup_id": "clickup-id-exemplo", "title": "Conteúdo editorial", "channel": "instagram", "status": "processing", "description": "Conteúdo de exemplo", "day": 1, "month": 1, "year": 1, "due_at": "2026-08-22T15:00:00.000Z", "editorial_tag": "string", "assignee_member_ids": [ "assignee-member-id-exemplo" ], "assignees_names": [ "Exemplo Hermes" ], "media": [ { "id": "id-exemplo", "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura", "slide_index": 1, "kind": "string" } ] } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/aprovar Aprovar ou recusar conteúdo A aprovação é atômica e idempotente no banco; a recusa preserva o conteúdo e muda o status. Aprova ou recusa o conteúdo sem apagar o histórico. Ao recusar, informe um motivo útil; ao aprovar, a data final pode ser ajustada. - operationId: `decideApproval` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `approve` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "event_id": { "type": "string", "description": "Evento." }, "action": { "type": "string", "description": "Decisão.", "enum": [ "aprovar", "recusar" ] }, "motivo": { "type": "string", "description": "Motivo da recusa." }, "day": { "type": "integer", "description": "Dia no horário de Brasília.", "minimum": 1, "maximum": 31 }, "month": { "type": "integer", "description": "Mês no horário de Brasília.", "minimum": 1, "maximum": 12 }, "year": { "type": "integer", "description": "Ano com quatro dígitos.", "minimum": 2000 }, "hour": { "type": "string", "description": "Horário local HH:mm. O padrão do backend é 12:00.", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "caption": { "type": "string", "description": "Legenda final opcional." } }, "required": [ "event_id", "action" ] } ``` Example: ```json { "event_id": "event-id", "action": "aprovar", "day": 2, "month": 9, "year": 2026, "hour": "19:00" } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "status": { "type": "string", "description": "Estado resultante." } }, "required": [ "ok", "status" ], "additionalProperties": true } ``` Example: ```json { "ok": true, "status": "processing" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/art Gerar e armazenar uma arte Gera uma imagem, armazena o resultado e opcionalmente a anexa a um evento acessível. Use `Idempotency-Key` para repetir com segurança após timeout. - operationId: `generateArt` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `art` #### Parameters ##### header Idempotency-Key - required: false - description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409. Schema: ```json { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:~-]+$" } ``` Example: ```json "docs-20260822-001" ``` #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "prompt": { "type": "string", "description": "Prompt visual." }, "event_id": { "type": "string", "description": "Evento opcional." }, "size": { "type": "string", "description": "Tamanho aceito pelo modelo.", "default": "1024x1536" }, "slide_index": { "type": "integer", "description": "Ordem no evento.", "default": 0 }, "quality": { "type": "string", "description": "Qualidade.", "default": "medium" }, "kind": { "type": "string", "description": "Tipo lógico.", "default": "imagem" }, "style": { "type": "string", "description": "Estilo.", "default": "epico" }, "format": { "type": "string", "description": "Proporção.", "default": "2:3" } }, "required": [ "prompt" ] } ``` Example: ```json { "prompt": "Céu estrelado em verde profundo", "event_id": "event-id" } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "url": { "type": "string", "description": "URL pública.", "format": "uri" }, "storage_path": { "type": "string", "description": "Caminho interno sem credenciais." } }, "required": [ "id", "url", "storage_path" ], "description": "Resultado de mídia gerada e armazenada pelo Hermes." } ``` Example: ```json { "id": "id-exemplo", "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura", "storage_path": "string" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/carousel Gerar carrossel com até dez cards Gera de um a dez cards e os persiste como um conjunto ordenado. Se houver `event_id`, o vínculo de todas as mídias é atômico. - operationId: `generateCarousel` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `carousel` #### Parameters ##### header Idempotency-Key - required: false - description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409. Schema: ```json { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:~-]+$" } ``` Example: ```json "docs-20260822-001" ``` #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "event_id": { "type": "string", "description": "Evento opcional." }, "cards": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Texto do card." }, "prompt": { "type": "string", "description": "Prompt de fundo opcional." } }, "required": [ "text" ] }, "description": "Entre 1 e 10 cards.", "minItems": 1, "maxItems": 10 } }, "required": [ "cards" ] } ``` Example: ```json { "event_id": "event-id", "cards": [ { "text": "Primeiro insight", "prompt": "Cosmos verde escuro" } ] } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "cards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "url": { "type": "string", "description": "URL pública no Hermes.", "format": "uri" }, "slide_index": { "type": "integer", "description": "Ordem." }, "kind": { "type": "string", "description": "Tipo lógico." } }, "required": [ "id", "url" ], "additionalProperties": true, "description": "Referência pública e ordenável de uma mídia persistida." } } }, "required": [ "cards" ] } ``` Example: ```json { "cards": [ { "id": "id-exemplo", "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura", "slide_index": 1, "kind": "string" } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/config Ler configuração versionada Lê o valor mais recente de cada configuração versionada. A resposta inclui a versão para auditoria e diagnóstico. - operationId: `getConfig` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `config_view` #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "config": { "type": "object", "properties": {}, "additionalProperties": { "type": "object", "properties": { "value": {}, "version": { "type": "integer", "description": "Versão." }, "updated_at": { "anyOf": [ { "type": "string", "description": "Atualização ISO.", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "value", "version" ], "description": "Versão mais recente de uma configuração." } } }, "required": [ "config" ] } ``` Example: ```json { "config": {} } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/config Criar nova versão de uma configuração Publica uma nova versão imutável para uma chave de configuração. Exige a capability `config`; versões anteriores permanecem no histórico. - operationId: `setConfig` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `config` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "key": { "type": "string", "description": "Chave." }, "value": {} }, "required": [ "key", "value" ] } ``` Example: ```json { "key": "horarios", "value": { "segunda": [ "12:00" ] } } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "key": { "type": "string", "description": "Chave." }, "version": { "type": "integer", "description": "Nova versão." } }, "required": [ "ok", "key", "version" ] } ``` Example: ```json { "ok": true, "key": "string", "version": 1 } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/config/log Listar histórico de configurações Lista o histórico de configurações, opcionalmente filtrado por chave, para auditoria e comparação de versões. - operationId: `getConfigLog` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `config` #### Parameters ##### query key - required: false - description: Filtrar por chave. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "log": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } }, "required": [ "log" ] } ``` Example: ```json { "log": [ {} ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/demanda Criar demanda editorial Cria uma demanda no calendário e, quando informado, atribui somente um membro ativo. Datas são interpretadas no horário de Brasília. - operationId: `createDemand` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `tasks_assign` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "title": { "type": "string", "description": "Título." }, "channel": { "type": "string", "description": "Canal.", "default": "instagram" }, "assignee_id": { "type": "string", "description": "Membro ativo opcional." }, "day": { "type": "integer", "description": "Dia no horário de Brasília.", "minimum": 1, "maximum": 31 }, "month": { "type": "integer", "description": "Mês no horário de Brasília.", "minimum": 1, "maximum": 12 }, "year": { "type": "integer", "description": "Ano com quatro dígitos.", "minimum": 2000 }, "hour": { "type": "string", "description": "Horário local HH:mm. O padrão do backend é 12:00.", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "description": { "type": "string", "description": "Descrição." }, "tipo": { "type": "string", "description": "Tag editorial." } }, "required": [ "title" ] } ``` Example: ```json { "title": "Novo corte", "channel": "instagram", "assignee_id": "member-id", "day": 2, "month": 9, "year": 2026, "hour": "12:00" } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "event_id": { "type": "string", "description": "Evento criado." }, "clickup_id": { "type": "string", "description": "ID externo." }, "due_at": { "anyOf": [ { "type": "string", "description": "Data ISO.", "format": "date-time" }, { "type": "null" } ] }, "event": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do evento." }, "api_revision": { "type": "integer", "description": "Token CAS da API; releia o evento antes de toda mutação.", "minimum": 0 }, "clickup_id": { "anyOf": [ { "type": "string", "description": "Identificador externo/legado." }, { "type": "null" } ] }, "title": { "type": "string", "description": "Título editorial." }, "channel": { "type": "string", "description": "Canal de publicação." }, "status": { "type": "string", "description": "Estado do fluxo editorial." }, "description": { "anyOf": [ { "type": "string", "description": "Legenda ou descrição." }, { "type": "null" } ] }, "day": { "anyOf": [ { "type": "integer", "description": "Dia no horário de Brasília.", "minimum": 1, "maximum": 31 }, { "type": "null" } ] }, "month": { "anyOf": [ { "type": "integer", "description": "Mês no horário de Brasília.", "minimum": 1, "maximum": 12 }, { "type": "null" } ] }, "year": { "anyOf": [ { "type": "integer", "description": "Ano no horário de Brasília." }, { "type": "null" } ] }, "due_at": { "anyOf": [ { "type": "string", "description": "Data/hora ISO 8601 persistida.", "format": "date-time" }, { "type": "null" } ] }, "editorial_tag": { "anyOf": [ { "type": "string", "description": "Tipo/tag editorial." }, { "type": "null" } ] }, "assignee_member_ids": { "type": "array", "items": { "type": "string", "description": "ID de membro." }, "description": "Responsáveis por ID." }, "assignees_names": { "type": "array", "items": { "type": "string", "description": "Nome de membro." }, "description": "Nomes dos responsáveis." } }, "required": [ "id", "title", "channel", "status" ], "additionalProperties": true, "description": "Evento editorial do calendário com token de revisão CAS." } }, "required": [ "ok", "event_id", "clickup_id", "event" ] } ``` Example: ```json { "ok": true, "event_id": "event-id-exemplo", "clickup_id": "clickup-id-exemplo", "due_at": "2026-08-22T15:00:00.000Z", "event": { "id": "id-exemplo", "api_revision": 0, "clickup_id": "clickup-id-exemplo", "title": "Conteúdo editorial", "channel": "instagram", "status": "processing", "description": "Conteúdo de exemplo", "day": 1, "month": 1, "year": 1, "due_at": "2026-08-22T15:00:00.000Z", "editorial_tag": "string", "assignee_member_ids": [ "assignee-member-id-exemplo" ], "assignees_names": [ "Exemplo Hermes" ] } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/draft Salvar rascunho editorial Atualiza legenda e estado editorial usando CAS. Leia o evento imediatamente antes e envie o `api_revision` obtido como `expected_revision`. - operationId: `saveDraft` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `draft_save` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "event_id": { "type": "string", "description": "Evento." }, "expected_revision": { "type": "integer", "description": "api_revision obtida na leitura mais recente.", "minimum": 0 }, "caption": { "type": "string", "description": "Legenda opcional." }, "status": { "type": "string", "description": "Status.", "default": "em progresso" } }, "required": [ "event_id", "expected_revision" ] } ``` Example: ```json { "event_id": "event-id", "expected_revision": 4, "caption": "Nova legenda" } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "status": { "type": "string", "description": "Status persistido." }, "api_revision": { "type": "integer", "description": "Nova revisão CAS.", "minimum": 0 } }, "required": [ "ok", "status", "api_revision" ] } ``` Example: ```json { "ok": true, "status": "processing", "api_revision": 0 } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/email-drafts Listar metadados de rascunhos de e-mail A listagem não inclui HTML. Consulte o template individual quando precisar editar. Lista apenas metadados, sem transferir HTML potencialmente grande. Abra individualmente somente o template que será consultado ou editado. - operationId: `listEmailDrafts` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `email_drafts_view` #### Parameters ##### query limit - required: false - description: Máximo de rascunhos. Schema: ```json { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } ``` Example: ```json 100 ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "drafts": { "type": "array", "items": { "type": "object", "properties": { "template_id": { "type": "string", "description": "ID lógico do template." }, "metadata": { "type": "object", "properties": {}, "additionalProperties": true }, "updated_at": { "type": "string", "description": "Token CAS.", "format": "date-time" }, "updated_by": { "type": "string", "description": "Usuário editor." } }, "required": [ "template_id", "metadata", "updated_at", "updated_by" ], "description": "Metadados leves de um rascunho, sem o HTML completo." } } }, "required": [ "drafts" ] } ``` Example: ```json { "drafts": [ { "template_id": "xamanismo-boas-vindas", "metadata": {}, "updated_at": "2026-08-22T15:00:00.000Z", "updated_by": "string" } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### DELETE /api/email-drafts/{templateId} Excluir exatamente um rascunho com CAS A exclusão é destrutiva e exige o updated_at atual. Leia o rascunho e confirme o template exato antes de chamar. Exclusão destrutiva de um único template. Confirme o identificador e envie o `expected_updated_at` atual; conflitos nunca são sobrescritos. - operationId: `deleteEmailDraft` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `delete` #### Parameters ##### path templateId - required: true - description: ID lógico seguro do template. Schema: ```json { "type": "string", "pattern": "^[A-Za-z0-9._:~-]+$", "maxLength": 200 } ``` Example: ```json "string" ``` ##### query expected_updated_at - required: true - description: Token CAS da leitura mais recente. Schema: ```json { "type": "string", "format": "date-time" } ``` Example: ```json "2026-09-02T15:00:00.000Z" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "template_id": { "type": "string", "description": "Template excluído." } }, "required": [ "ok", "template_id" ] } ``` Example: ```json { "ok": true, "template_id": "xamanismo-boas-vindas" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/email-drafts/{templateId} Consultar um rascunho de e-mail Retorna o HTML completo, metadados e `updated_at`, que funciona como token CAS para a próxima edição ou exclusão. - operationId: `getEmailDraft` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `email_drafts_view` #### Parameters ##### path templateId - required: true - description: ID lógico seguro do template. Schema: ```json { "type": "string", "pattern": "^[A-Za-z0-9._:~-]+$", "maxLength": 200 } ``` Example: ```json "string" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "draft": { "type": "object", "properties": { "template_id": { "type": "string", "description": "ID lógico do template." }, "html": { "type": "string", "description": "HTML completo." }, "metadata": { "type": "object", "properties": {}, "additionalProperties": true }, "updated_at": { "type": "string", "description": "Token CAS.", "format": "date-time" }, "updated_by": { "type": "string", "description": "Usuário editor." } }, "required": [ "template_id", "html", "metadata", "updated_at", "updated_by" ], "description": "Template de e-mail completo com token CAS baseado em timestamp." } }, "required": [ "draft" ] } ``` Example: ```json { "draft": { "template_id": "xamanismo-boas-vindas", "html": "string", "metadata": {}, "updated_at": "2026-08-22T15:00:00.000Z", "updated_by": "string" } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### PUT /api/email-drafts/{templateId} Criar ou atualizar um rascunho com CAS Use expected_updated_at null somente para criar. Para editar, use exatamente o updated_at da leitura mais recente. Cria ou atualiza um template com CAS. Use `expected_updated_at: null` somente na criação e o timestamp exato da leitura mais recente nas edições. - operationId: `putEmailDraft` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `email_drafts_edit` #### Parameters ##### header Idempotency-Key - required: false - description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409. Schema: ```json { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:~-]+$" } ``` Example: ```json "docs-20260822-001" ``` ##### path templateId - required: true - description: ID lógico seguro do template. Schema: ```json { "type": "string", "pattern": "^[A-Za-z0-9._:~-]+$", "maxLength": 200 } ``` Example: ```json "string" ``` #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "html": { "type": "string", "description": "HTML do e-mail, até 2 MB.", "maxLength": 2000000 }, "metadata": { "type": "object", "properties": {}, "additionalProperties": true }, "expected_updated_at": { "anyOf": [ { "type": "string", "description": "Token CAS da leitura mais recente.", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "html", "expected_updated_at" ] } ``` Example: ```json { "html": "...", "metadata": { "campaign": "xamanismo" }, "expected_updated_at": null } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "draft": { "type": "object", "properties": { "template_id": { "type": "string", "description": "ID lógico do template." }, "html": { "type": "string", "description": "HTML completo." }, "metadata": { "type": "object", "properties": {}, "additionalProperties": true }, "updated_at": { "type": "string", "description": "Token CAS.", "format": "date-time" }, "updated_by": { "type": "string", "description": "Usuário editor." } }, "required": [ "template_id", "html", "metadata", "updated_at", "updated_by" ], "description": "Template de e-mail completo com token CAS baseado em timestamp." } }, "required": [ "ok", "draft" ] } ``` Example: ```json { "ok": true, "draft": { "template_id": "xamanismo-boas-vindas", "html": "string", "metadata": {}, "updated_at": "2026-08-22T15:00:00.000Z", "updated_by": "string" } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 413 HTML excede 2 MB. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "html excede 2 MB", "code": "EMAIL_HTML_TOO_LARGE" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/enviar Enviar conteúdo para aprovação Move um conteúdo editável para o fluxo de aprovação e pode atualizar a data proposta. Exige o `api_revision` mais recente e aceita repetição segura com `Idempotency-Key`. - operationId: `submitForApproval` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `enviar` #### Parameters ##### header Idempotency-Key - required: false - description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409. Schema: ```json { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:~-]+$" } ``` Example: ```json "docs-20260822-001" ``` #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "event_id": { "type": "string", "description": "Evento." }, "expected_revision": { "type": "integer", "description": "api_revision obtida na leitura mais recente.", "minimum": 0 }, "day": { "type": "integer", "description": "Dia no horário de Brasília.", "minimum": 1, "maximum": 31 }, "month": { "type": "integer", "description": "Mês no horário de Brasília.", "minimum": 1, "maximum": 12 }, "year": { "type": "integer", "description": "Ano com quatro dígitos.", "minimum": 2000 }, "hour": { "type": "string", "description": "Horário local HH:mm. O padrão do backend é 12:00.", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "caption": { "type": "string", "description": "Legenda." }, "tipo": { "type": "string", "description": "Tag editorial." } }, "required": [ "event_id", "expected_revision" ] } ``` Example: ```json { "event_id": "event-id", "expected_revision": 4, "day": 2, "month": 9, "year": 2026, "hour": "15:30" } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "status": { "type": "string", "description": "Sempre para agendar." }, "api_revision": { "type": "integer", "description": "Nova revisão CAS.", "minimum": 0 }, "due_at": { "anyOf": [ { "type": "string", "description": "Data ISO.", "format": "date-time" }, { "type": "null" } ] }, "proposto": { "anyOf": [ { "type": "string", "description": "Alias de due_at.", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "ok", "status", "api_revision" ] } ``` Example: ```json { "ok": true, "status": "processing", "api_revision": 0, "due_at": "2026-08-22T15:00:00.000Z", "proposto": "2026-08-22T15:00:00.000Z" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/health Consultar saúde do serviço Verificação pública e leve do processo HTTP. Um `200` confirma que o serviço responde; não garante a disponibilidade de cada provedor externo. - operationId: `getHealth` - authentication: public #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Indica que o processo HTTP está respondendo." }, "service": { "type": "string", "description": "Nome do serviço." }, "providers": { "type": "array", "items": { "type": "string", "description": "Provedor social registrado no ambiente." } } }, "required": [ "ok", "service", "providers" ] } ``` Example: ```json { "ok": true, "service": "hermes-publisher", "providers": [ "meta", "youtube" ] } ``` ### GET /api/insights/horarios Consultar melhores horários de publicação Retorna horários e sinais disponíveis para orientar o planejamento editorial. A origem do cálculo aparece no campo `fonte`. - operationId: `getPublishingTimes` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `analytics` #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "fonte": { "type": "string", "description": "Origem do cálculo." } }, "required": [ "fonte" ], "additionalProperties": true } ``` Example: ```json { "fonte": "string" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/jornada/eventos Receber eventos do checkout (servidor a servidor) Entrada servidor a servidor da linha do tempo: o checkout do Xamanismo avisa quando alguém abre o checkout, muda de etapa ou se identifica. Autentica pelo cabeçalho `x-jornada-token` (segredo compartilhado), não por sessão. Aceita de 1 a 50 eventos; e-mail vira hash e nunca é gravado em claro; eventos repetidos (mesma sessão e id) são ignorados. - operationId: `ingestJourneyEvents` - authentication: Supabase session or `hms_live_` personal bearer token #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "eventos": { "type": "array", "items": { "type": "object", "properties": { "evento": { "type": "string", "description": "abriu_checkout, etapa_checkout, identificou, respondeu_enquete ou visitou_pagina.", "enum": [ "abriu_checkout", "etapa_checkout", "identificou", "respondeu_enquete", "visitou_pagina" ] }, "sessao": { "type": "string", "description": "Id da sessão do navegador." }, "id": { "type": "string", "description": "Id único do evento na sessão." }, "email": { "type": "string", "description": "Obrigatório em identificou e respondeu_enquete; vira hash." }, "produto": { "type": "string", "description": "commerce_product." }, "lancamento": { "type": "string", "description": "launch_id." }, "ocorreu_em": { "type": "string", "description": "Instante (até 1 dia de diferença).", "format": "date-time" }, "detalhe": { "type": "object", "properties": {}, "additionalProperties": { "type": "string", "description": "Chaves permitidas: etapa, pagina, origem, lote, utm_*, votacao, opcao, peso, titulo, site, referencia, gclid e fbclid." } } }, "required": [ "evento", "sessao", "id" ] }, "description": "De 1 a 50 eventos." } }, "required": [ "eventos" ] } ``` Example: ```json { "eventos": [ { "evento": "abriu_checkout", "sessao": "sess-123456", "id": "ev-000001", "produto": "curso_kardec" } ] } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "recebidos": { "type": "integer", "description": "Eventos recebidos." }, "gravados": { "type": "integer", "description": "Eventos novos gravados." }, "recusados": { "type": "integer", "description": "Eventos inválidos ignorados." } }, "required": [ "ok", "gravados" ] } ``` Example: ```json { "ok": true, "recebidos": 1, "gravados": 1, "recusados": 1 } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/jornada/lead Resumo de um lead para o SiteUP CRM (compras, origem e páginas) Consulta servidor a servidor da aba Contexto do lead do SiteUP CRM: compras de todas as lojas (checkout do Xamanismo e loja nova), primeiro e último toque (canal, UTMs, página de entrada) e as últimas cinco páginas visitadas. Visita anônima só aparece depois que a pessoa se identificou na mesma sessão. O e-mail vai no corpo, vira hash e não é guardado; nenhum dado de cartão ou documento sai. Token só de leitura (JORNADA_LEAD_TOKEN) no cabeçalho `x-jornada-token`. - operationId: `getLeadContext` - authentication: Supabase session or `hms_live_` personal bearer token #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "email": { "type": "string", "description": "E-mail do contato. Vira hash e não é guardado.", "format": "email" } }, "required": [ "email" ] } ``` Example: ```json { "email": "contato@siteup.com.br" } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "encontrado": { "type": "boolean", "description": "Se há eventos dessa pessoa." }, "compras": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Um item por pedido, do mais novo para o mais antigo: produto, rotulo, valor_centavos, moeda, status (pago, recusado, pendente, vencido, estornado), metodo, parcelas, ocorreu_em, loja (xamanismo, loja-nova ou loja-antiga, que é a Shopify até a virada) e site." }, "total_pago": { "type": "object", "properties": {}, "additionalProperties": true }, "origem": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "paginas": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Últimas cinco páginas visitadas." }, "paginas_total": { "type": "integer", "description": "Visitas registradas." }, "paginas_dias": { "type": "integer", "description": "Dias com visita." } }, "required": [ "encontrado" ], "additionalProperties": true } ``` Example: ```json { "encontrado": true, "compras": [ {} ], "total_pago": {}, "origem": {}, "paginas": [ {} ], "paginas_total": 1, "paginas_dias": 1 } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/jornada/perfil Consultar o perfil de uma pessoa pelo e-mail (dado pessoal, só Financeiro) Perfil de uma pessoa pelo e-mail, enviado no corpo (nunca na URL): segmento, compras, lançamentos em que mexeu, canal e hora preferidos, temas e a sugestão de próximo evento com o motivo. O e-mail só vira hash para a busca e não é guardado. Dado pessoal: exige a capability `vendas` (Financeiro) e a resposta não é cacheada. - operationId: `getPersonProfile` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "email": { "type": "string", "description": "E-mail da pessoa. Vira hash e não é guardado.", "format": "email" } }, "required": [ "email" ] } ``` Example: ```json { "email": "contato@siteup.com.br" } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "encontrado": { "type": "boolean", "description": "Se há eventos dessa pessoa." }, "segmento": { "type": "string", "description": "Segmento." }, "proximo": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] } }, "required": [ "encontrado" ], "additionalProperties": true } ``` Example: ```json { "encontrado": true, "segmento": "string", "proximo": {} } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/jornada/ses Receber eventos de e-mail do SES (SNS) Entrada dos eventos de e-mail do SES (entregue, aberto, clicado, devolvido, reclamação) publicados pelo SNS do configuration set `jve-rastreio`. Autentica pelo `token` na query (JORNADA_SES_TOKEN) e confere o tópico (JORNADA_SES_TOPIC_ARN); confirma a assinatura do SNS só em URL da própria AWS. Grava na linha do tempo por pessoa (hash do e-mail). - operationId: `ingestSesEvent` - authentication: Supabase session or `hms_live_` personal bearer token #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### text/plain Schema: ```json { "type": "string", "description": "Envelope JSON do SNS." } ``` Example: ```json "string" ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Recebido." }, "status": { "type": "string", "description": "evento, assinatura_confirmada, ignorado, topico_errado ou invalido." } }, "required": [ "ok" ] } ``` Example: ```json { "ok": true, "status": "processing" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/jornada/sincronizar Sincronizar a linha do tempo Relê as fontes da linha do tempo (pedidos da Pagar.me e da Stripe em todos os status e envios de recuperação do SiteUP CRM) dos últimos `dias` (1 a 120). A mesma sincronização roda sozinha a cada 15 minutos quando `JORNADA_SYNC=on`. Exige a capability `config`. - operationId: `syncJourney` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `config` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "dias": { "type": "integer", "description": "Dias para trás (1 a 120, padrão 3; até 3650 quando fontes é só shopify)." }, "fontes": { "type": "array", "items": { "type": "string", "description": "pagarme, stripe, shopify ou crm" }, "description": "Limita as fontes lidas; sem ele lê todas. Use [\"shopify\"] para trazer o histórico da loja antiga." } } } ``` Example: ```json { "dias": 30 } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "dias": { "type": "integer", "description": "Dias lidos." }, "gravados": { "type": "integer", "description": "Eventos novos." } }, "required": [ "ok" ], "additionalProperties": true } ``` Example: ```json { "ok": true, "dias": 1, "gravados": 1 } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/lancamentos Listar os lançamentos com dashboard Lista os lançamentos com dashboard (configuração em hermes_config, chave `lancamentos`; sem ela, os quatro de fábrica) e o projeto do Studio de cada um. Exige a capability `vendas`. - operationId: `listLaunches` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "fonte": { "type": "string", "description": "padrao ou config." }, "avisos": { "type": "array", "items": { "type": "string", "description": "Aviso." }, "description": "Configurações ignoradas." }, "lancamentos": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Lançamentos com o projeto do Studio." } }, "required": [ "fonte", "lancamentos" ] } ``` Example: ```json { "fonte": "string", "avisos": [ "string" ], "lancamentos": [ {} ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### PUT /api/lancamentos/{projetoId} Cadastrar ou editar o dashboard de um projeto Cadastra ou edita o dashboard de um projeto (grupos de produto, códigos `commerce_product`, `launch_id` opcionais e janela). Grava a lista inteira em hermes_config com nova versão e histórico. Exige a capability `config`. - operationId: `putLaunch` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `config` #### Parameters ##### path projetoId - required: true - description: ID do projeto em hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "projeto_id": { "type": "string", "description": "ID do projeto." }, "nome": { "type": "string", "description": "Nome do lançamento." }, "tipo": { "type": "string", "description": "Tipo.", "enum": [ "lancamento", "perpetuo" ] }, "inicio": { "anyOf": [ { "type": "string", "description": "Primeiro dia (YYYY-MM-DD)." }, { "type": "null" } ] }, "fim": { "anyOf": [ { "type": "string", "description": "Último dia (YYYY-MM-DD)." }, { "type": "null" } ] }, "grupos": { "type": "array", "items": { "type": "object", "properties": { "chave": { "type": "string", "description": "Chave do grupo (a-z, 0-9, _)." }, "rotulo": { "type": "string", "description": "Rótulo exibido." }, "produtos": { "type": "array", "items": { "type": "string", "description": "Código commerce_product." }, "description": "Códigos do grupo." }, "launch_ids": { "type": "array", "items": { "type": "string", "description": "launch_id aceito." }, "description": "Vazio: conta pela janela de datas." } }, "required": [ "chave", "produtos" ] }, "description": "Grupos de produto." } }, "required": [ "projeto_id", "nome", "grupos" ] } ``` Example: ```json { "projeto_id": "ca185d1f-b631-4699-9bbc-4cd81169b6a9", "nome": "O Funeral da Evidência", "tipo": "lancamento", "inicio": "2026-09-01", "fim": null, "grupos": [ { "chave": "ingressos", "rotulo": "Ingressos", "produtos": [ "o_funeral_da_evidencia_ingresso" ], "launch_ids": [ "funeral-2026-10" ] } ] } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "version": { "type": "integer", "description": "Versão gravada." }, "lancamento": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "ok", "version" ] } ``` Example: ```json { "ok": true, "version": 1, "lancamento": {} } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/lancamentos/{projetoId}/compradores Listar os compradores de um lançamento Aba Compradores: pedidos pagos do lançamento no período com nome, e-mail, telefone, produto, valor, método e canal, mais recentes primeiro (até 2000). Contém dados pessoais: exige a capability `vendas` (permissão Financeiro) e a resposta nunca é cacheada. - operationId: `getLaunchBuyers` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### path projetoId - required: true - description: ID do projeto em hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query aba - required: false - description: Aba do lançamento. Schema: ```json { "type": "string", "description": "Chave da aba." } ``` Example: ```json "lancamento" ``` ##### query from - required: false - description: Início do período. Schema: ```json { "type": "string", "description": "Primeiro dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-21" ``` ##### query to - required: false - description: Fim do período. Schema: ```json { "type": "string", "description": "Último dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-23" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "status": { "type": "string", "description": "ok, sem_config ou nao_configurado." } }, "required": [ "status" ], "additionalProperties": true } ``` Example: ```json { "status": "processing" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/lancamentos/{projetoId}/decisao Consultar o painel de decisão de um lançamento Painel de decisão do lançamento: metas escritas no projeto do Studio contra o realizado, ritmo dos últimos dias (sem o dia da abertura) e projeção até o fim; comparação com o lançamento anterior no mesmo dia do ciclo (ingressos, receita, Orbum); custo de mídia (anúncio + WhatsApp) e resultado; quem já era cliente; ingressos que viraram Orbum e por qual caminho; vendas por lote com a hora da virada; e o efeito de cada onda de WhatsApp (recebeu, leu, comprou em 24 h, custo). Só números agregados; exige a capability `vendas`. Cada bloco traz `status` próprio e um erro num bloco não derruba os outros. - operationId: `getLaunchDecision` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### path projetoId - required: true - description: ID do projeto em hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query aba - required: false - description: Aba do lançamento. Schema: ```json { "type": "string", "description": "Chave da aba." } ``` Example: ```json "lancamento" ``` ##### query from - required: false - description: Início do período. Schema: ```json { "type": "string", "description": "Primeiro dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-21" ``` ##### query to - required: false - description: Fim do período. Schema: ```json { "type": "string", "description": "Último dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-23" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "periodo": { "type": "object", "properties": {}, "additionalProperties": true }, "metas": { "type": "object", "properties": {}, "additionalProperties": true }, "comparacao": { "type": "object", "properties": {}, "additionalProperties": true }, "custo": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "periodo", "metas" ], "additionalProperties": true } ``` Example: ```json { "periodo": {}, "metas": {}, "comparacao": {}, "custo": {} } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/lancamentos/{projetoId}/disparos Consultar os disparos de WhatsApp de um lançamento Aba Disparos do lançamento: cada template de WhatsApp cujo nome casa com `disparos.templates` da configuração, com enviadas, entregues, lidas, taxa de leitura e custo (USD da Meta e BRL pela PTAX), prévia da mensagem e vendas atribuídas pelo `utm_content` do botão. Cache de 30 minutos; templates que a Meta não respondeu aparecem em `incompletos`. Exige a capability `vendas`. - operationId: `getLaunchBroadcasts` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### path projetoId - required: true - description: ID do projeto em hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query aba - required: false - description: Aba do lançamento. Schema: ```json { "type": "string", "description": "Chave da aba." } ``` Example: ```json "lancamento" ``` ##### query from - required: false - description: Início do período. Schema: ```json { "type": "string", "description": "Primeiro dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-21" ``` ##### query to - required: false - description: Fim do período. Schema: ```json { "type": "string", "description": "Último dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-23" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "status": { "type": "string", "description": "ok, sem_config ou nao_configurado." } }, "required": [ "status" ], "additionalProperties": true } ``` Example: ```json { "status": "processing" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/lancamentos/{projetoId}/funil Consultar o funil do CRM de um lançamento Aba Check-in e presença: quantos cards estão em cada etapa do funil do lançamento no SiteUP CRM (config `funil`) e quantos entraram em cada etapa por dia no período. Cache de 5 minutos; exige a capability `vendas`. - operationId: `getLaunchCrmFunnel` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### path projetoId - required: true - description: ID do projeto em hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query aba - required: false - description: Aba do lançamento. Schema: ```json { "type": "string", "description": "Chave da aba." } ``` Example: ```json "lancamento" ``` ##### query from - required: false - description: Início do período. Schema: ```json { "type": "string", "description": "Primeiro dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-21" ``` ##### query to - required: false - description: Fim do período. Schema: ```json { "type": "string", "description": "Último dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-23" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "status": { "type": "string", "description": "ok, sem_config ou nao_configurado." } }, "required": [ "status" ], "additionalProperties": true } ``` Example: ```json { "status": "processing" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/lancamentos/{projetoId}/jornada Consultar o funil da linha do tempo de um lançamento Funil agregado do lançamento a partir da linha do tempo: pessoas que abriram o checkout, se identificaram, geraram pagamento e compraram, onde cada uma parou, pagamentos recusados e expirados, recuperações enviadas e quem voltou em até 7 dias. Sessões anônimas contam como a pessoa que se identificou nelas. Só números agregados; exige a capability `vendas`. - operationId: `getLaunchJourney` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### path projetoId - required: true - description: ID do projeto em hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query aba - required: false - description: Aba do lançamento. Schema: ```json { "type": "string", "description": "Chave da aba." } ``` Example: ```json "lancamento" ``` ##### query from - required: false - description: Início do período. Schema: ```json { "type": "string", "description": "Primeiro dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-21" ``` ##### query to - required: false - description: Fim do período. Schema: ```json { "type": "string", "description": "Último dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-23" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "pessoas": { "type": "integer", "description": "Pessoas distintas." }, "passos": { "type": "object", "properties": {}, "additionalProperties": { "type": "integer", "description": "Pessoas que chegaram ao passo." } } }, "required": [ "pessoas", "passos" ], "additionalProperties": true } ``` Example: ```json { "pessoas": 1, "passos": {} } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/lancamentos/{projetoId}/midia Consultar a mídia paga de um lançamento Aba Mídia do lançamento: gasto em anúncios do Meta e do Google das campanhas cujo nome casa com `midia.campanhas` da configuração, com impressões, cliques, CTR, CPC e CPM por plataforma, por grupo de produto (`midia.produtos`), por campanha (até 50), por anúncio (até 20) e por dia. Fonte: tabelas sincronizadas a cada ~5 h. Valores em reais; exige a capability `vendas`. - operationId: `getLaunchMedia` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### path projetoId - required: true - description: ID do projeto em hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query aba - required: false - description: Aba do lançamento. Schema: ```json { "type": "string", "description": "Chave da aba." } ``` Example: ```json "lancamento" ``` ##### query from - required: false - description: Início do período. Schema: ```json { "type": "string", "description": "Primeiro dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-21" ``` ##### query to - required: false - description: Fim do período. Schema: ```json { "type": "string", "description": "Último dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-23" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "status": { "type": "string", "description": "ok, sem_config ou nao_configurado." } }, "required": [ "status" ], "additionalProperties": true } ``` Example: ```json { "status": "processing" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/lancamentos/{projetoId}/origem Consultar a origem das vendas de um lançamento Aba Origem do lançamento: vendas pagas agrupadas por canal (derivado do utm_source), campanha (utm_campaign), conteúdo (utm_content) e origem_venda, com receita por moeda. Último clique, pelas marcações que o checkout grava no pedido; vendas da loja Shopify ficam de fora. Exige a capability `vendas`. - operationId: `getLaunchOrigin` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### path projetoId - required: true - description: ID do projeto em hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query aba - required: false - description: Aba do lançamento. Schema: ```json { "type": "string", "description": "Chave da aba." } ``` Example: ```json "lancamento" ``` ##### query from - required: false - description: Início do período. Schema: ```json { "type": "string", "description": "Primeiro dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-21" ``` ##### query to - required: false - description: Fim do período. Schema: ```json { "type": "string", "description": "Último dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-23" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "status": { "type": "string", "description": "ok." }, "vendas": { "type": "integer", "description": "Vendas pagas consideradas." } }, "required": [ "status" ], "additionalProperties": true } ``` Example: ```json { "status": "processing", "vendas": 1 } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/lancamentos/{projetoId}/perfis Consultar os perfis agregados de quem mexeu num lançamento Perfis agregados de quem mexeu no lançamento (Fase 4): pessoas por segmento (recorrente, comprador, quase comprou, interessado, só mensagem), canal que mais responde, hora em que mais age (Brasília), assinantes do Orbum, quem comprou em outro lançamento, temas votados e a sugestão de próximo evento com a regra usada. As chaves `funeral` e `funeral-2026-10` contam como o mesmo lançamento. Só contagens, nenhuma pessoa; exige a capability `vendas`. - operationId: `getLaunchProfiles` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### path projetoId - required: true - description: ID do projeto em hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "status": { "type": "string", "description": "ok." }, "pessoas": { "type": "integer", "description": "Pessoas que mexeram no lançamento." }, "segmentos": { "type": "array", "items": { "type": "object", "properties": { "chave": { "type": "string", "description": "Segmento." }, "rotulo": { "type": "string", "description": "Rótulo." }, "pessoas": { "type": "integer", "description": "Pessoas." } }, "required": [ "chave", "pessoas" ] }, "description": "Pessoas por segmento." }, "proximo_evento": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Sugestão de próximo evento, agregada." } }, "required": [ "status", "pessoas", "segmentos" ], "additionalProperties": true } ``` Example: ```json { "status": "processing", "pessoas": 1, "segmentos": [ { "chave": "string", "rotulo": "string", "pessoas": 1 } ], "proximo_evento": [ {} ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/lancamentos/{projetoId}/resumo Consultar o painel de um lançamento Painel de um lançamento: vendas por grupo de produto, pagamentos falhos, pendentes e quantos iniciaram o pagamento, lidos ao vivo da Pagar.me e da Stripe por `commerce_product` e `launch_id`. Sem from/to usa a janela do lançamento ou da aba pedida (30 dias no perpétuo), no máximo 400 dias. Abas separam períodos, como pré-venda e lançamento, sem misturar números. Valores desconhecidos vêm como `null`, moedas nunca são somadas e a resposta nunca inclui dados pessoais. Cache de cinco minutos no servidor. - operationId: `getLaunchSummary` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### path projetoId - required: true - description: ID do projeto em hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query aba - required: false - description: Aba com datas e grupos próprios; padrão é a primeira. Schema: ```json { "type": "string", "description": "Chave da aba do lançamento (ex.: `prevenda_livro`)." } ``` Example: ```json "lancamento" ``` ##### query from - required: false - description: Início do período; padrão é o início do lançamento. Schema: ```json { "type": "string", "description": "Primeiro dia (YYYY-MM-DD, horário de Brasília).", "format": "date" } ``` Example: ```json "2026-09-01" ``` ##### query to - required: false - description: Fim do período, no máximo amanhã. Schema: ```json { "type": "string", "description": "Último dia (YYYY-MM-DD, horário de Brasília).", "format": "date" } ``` Example: ```json "2026-09-23" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "lancamento": { "type": "object", "properties": {}, "additionalProperties": true }, "periodo": { "type": "object", "properties": { "from": { "type": "string", "description": "Início." }, "to": { "type": "string", "description": "Fim." }, "dias": { "type": "integer", "description": "Dias." } }, "required": [ "from", "to", "dias" ] }, "fontes": { "type": "object", "properties": {}, "additionalProperties": { "type": "string", "description": "ok, erro ou nao_configurado." } }, "totais": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Vendas, bruto por moeda, iniciados, falhos, pendentes, aprovação e conversão." }, { "type": "null" } ] }, "grupos": { "type": "array", "items": { "type": "object", "properties": { "chave": { "type": "string", "description": "Grupo." } }, "required": [ "chave" ], "additionalProperties": true }, "description": "Números por grupo de produto." }, "serie": { "type": "array", "items": { "type": "object", "properties": { "dia": { "type": "string", "description": "Dia." } }, "required": [ "dia" ], "additionalProperties": true }, "description": "Série diária." }, "pendencias": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Métricas sem fonte ligada." }, "avisos": { "type": "array", "items": { "type": "string", "description": "Aviso." }, "description": "Lacunas e regras aplicadas." } }, "required": [ "lancamento", "periodo", "fontes", "grupos", "serie", "avisos" ] } ``` Example: ```json { "lancamento": {}, "periodo": { "from": "string", "to": "string", "dias": 1 }, "fontes": {}, "totais": {}, "grupos": [ { "chave": "string" } ], "serie": [ { "dia": "string" } ], "pendencias": [ {} ], "avisos": [ "string" ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/lancamentos/{projetoId}/saude Consultar a saúde de um lançamento Aba Saúde: última venda, vendas e receita de hoje e o estado de cada fonte e rotina (leituras de pagamento, sincronização da linha do tempo, última recuperação enviada, último aviso do checkout e dados de anúncio). Exige a capability `vendas`. - operationId: `getLaunchHealth` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### path projetoId - required: true - description: ID do projeto em hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query aba - required: false - description: Aba do lançamento. Schema: ```json { "type": "string", "description": "Chave da aba." } ``` Example: ```json "lancamento" ``` ##### query from - required: false - description: Início do período. Schema: ```json { "type": "string", "description": "Primeiro dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-21" ``` ##### query to - required: false - description: Fim do período. Schema: ```json { "type": "string", "description": "Último dia (YYYY-MM-DD).", "format": "date" } ``` Example: ```json "2026-09-23" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "status": { "type": "string", "description": "ok, sem_config ou nao_configurado." } }, "required": [ "status" ], "additionalProperties": true } ``` Example: ```json { "status": "processing" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/mcp Chamar o MCP Streamable HTTP do Hermes Endpoint MCP oficial e stateless. Registra somente tools explícitas e encaminha cada ação para uma rota Hermes fixa com as mesmas guardas de capability, CAS e idempotência. Envie mensagens JSON-RPC 2.0 do MCP por HTTP. Cada chamada é stateless, aceita sessão Supabase ou token pessoal `hms_live_` e só expõe ferramentas explícitas com as mesmas autorizações da API REST. - operationId: `callHermesMcp` - authentication: Supabase session or `hms_live_` personal bearer token #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Mensagem JSON-RPC do protocolo MCP. ##### application/json Schema: ```json { "type": "object", "properties": {}, "additionalProperties": true } ``` Example: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } ``` #### Responses ##### 200 Resposta MCP JSON-RPC. ###### application/json Schema: ```json { "type": "object", "properties": {}, "additionalProperties": true } ``` Example: ```json {} ``` ##### 202 Notificação MCP aceita sem resposta de ferramenta. Schema: no response body. Example: no response body. ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 405 Método MCP não suportado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "string", "code": "string", "details": {} } ``` ##### 415 Content-Type precisa ser application/json. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "string", "code": "string", "details": {} } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/me Consultar membro autenticado e capacidades Primeira chamada recomendada após autenticar. Em uma sessão Supabase, as capabilities vêm exclusivamente do cargo `access_level` do Studio; em um token pessoal, vêm da interseção entre scopes, nível individual da API e teto do cargo. - operationId: `getCurrentMember` - authentication: Supabase session or `hms_live_` personal bearer token #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "member": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do membro." }, "user_id": { "type": "string", "description": "ID do usuário Supabase vinculado." }, "name": { "type": "string", "description": "Nome." }, "email": { "anyOf": [ { "type": "string", "description": "E-mail do membro.", "format": "email" }, { "type": "null" } ] }, "access_level": { "type": "string", "description": "Nível desta credencial: cargo do Studio para session; nível PAT efetivo para api_token.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "team_access_level": { "type": "string", "description": "Cargo atual no Studio; governa a sessão e serve de teto somente para PAT.", "enum": [ "criador", "lider", "admin" ] }, "api_access_level": { "type": "string", "description": "Configuração de PAT na sessão; nível PAT efetivo quando auth.kind é api_token.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] } }, "required": [ "id", "name", "access_level", "team_access_level", "api_access_level" ], "description": "Identidade e autorização da credencial atual: cargo do Studio para sessão ou nível efetivo para PAT." }, "caps": { "type": "array", "items": { "type": "string", "description": "Capability liberada." } }, "auth": { "type": "object", "properties": { "kind": { "type": "string", "description": "Método que autenticou a chamada.", "enum": [ "session", "api_token" ] }, "token_id": { "anyOf": [ { "type": "string", "description": "ID do token pessoal quando kind é api_token." }, { "type": "null" } ] } }, "required": [ "kind", "token_id" ], "description": "Método efetivamente usado para autenticar a requisição atual." } }, "required": [ "member", "caps", "auth" ] } ``` Example: ```json { "member": { "id": "id-exemplo", "user_id": "user-id-exemplo", "name": "Exemplo Hermes", "email": "membro@example.com", "access_level": "nenhum", "team_access_level": "criador", "api_access_level": "nenhum" }, "caps": [ "string" ], "auth": { "kind": "session", "token_id": "token-id-exemplo" } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/membros Listar membros ativos Lista membros ativos que podem receber atribuições, sem retornar credenciais ou registros já desativados. - operationId: `listMembers` - authentication: Supabase session bearer token (session only) - required capability: `members` #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "membros": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "name": { "type": "string", "description": "Nome." }, "email": { "type": "string", "description": "E-mail.", "format": "email" }, "role": { "anyOf": [ { "type": "string", "description": "Função." }, { "type": "null" } ] }, "access_level": { "type": "string", "description": "Cargo no Studio.", "enum": [ "criador", "lider", "admin" ] }, "api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "is_admin": { "type": "boolean", "description": "Compatibilidade com legado." }, "financeiro": { "type": "boolean", "description": "Permissão por pessoa: vê o painel de Vendas (capability `vendas`)." } }, "required": [ "id", "name", "email", "access_level" ], "description": "Membro ativo que pode receber atribuições e capabilities." } } }, "required": [ "membros" ] } ``` Example: ```json { "membros": [ { "id": "id-exemplo", "name": "Exemplo Hermes", "email": "membro@example.com", "role": "string", "access_level": "criador", "api_access_level": "nenhum", "is_admin": true, "financeiro": true } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### PATCH /api/membros Alterar nível de acesso ou permissão financeira Altera o nível de acesso (criador, líder, admin) e/ou a permissão por pessoa `financeiro`, que libera o painel de Vendas. Informe ao menos um dos dois; as capabilities efetivas são recalculadas na próxima requisição. Evite elevar privilégios sem necessidade operacional. - operationId: `updateMemberAccess` - authentication: Supabase session bearer token (session only) - required capability: `members` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "member_id": { "type": "string", "description": "Membro." }, "access_level": { "type": "string", "description": "Nível.", "enum": [ "criador", "lider", "admin" ] }, "financeiro": { "type": "boolean", "description": "Liga ou desliga o acesso ao painel de Vendas." } }, "required": [ "member_id" ] } ``` Example: ```json { "member_id": "member-id", "access_level": "lider", "financeiro": false } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "member_id": { "type": "string", "description": "Membro." }, "access_level": { "type": "string", "description": "Nível resultante." }, "financeiro": { "type": "boolean", "description": "Permissão financeira resultante." } }, "required": [ "ok", "member_id", "access_level", "financeiro" ] } ``` Example: ```json { "ok": true, "member_id": "member-id-exemplo", "access_level": "string", "financeiro": true } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/membros Convidar um novo membro O Supabase envia um link de convite para o e-mail informado. O usuário define a própria senha no fluxo de onboarding; a API nunca cria nem retorna senha provisória. Envia um convite seguro por e-mail e cria o vínculo ativo na equipe. Nenhuma senha provisória é criada ou devolvida pela API. - operationId: `createMember` - authentication: Supabase session bearer token (session only) - required capability: `members` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "name": { "type": "string", "description": "Nome." }, "email": { "type": "string", "description": "E-mail.", "format": "email" }, "access_level": { "type": "string", "description": "Nível.", "enum": [ "criador", "lider", "admin" ] }, "role": { "type": "string", "description": "Função livre." } }, "required": [ "name", "email", "access_level" ] } ``` Example: ```json { "name": "Novo membro", "email": "membro@example.com", "access_level": "criador" } ``` #### Responses ##### 201 Convite enviado e membro criado. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "member": { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "name": { "type": "string", "description": "Nome." }, "email": { "type": "string", "description": "E-mail.", "format": "email" }, "role": { "anyOf": [ { "type": "string", "description": "Função." }, { "type": "null" } ] }, "access_level": { "type": "string", "description": "Cargo no Studio.", "enum": [ "criador", "lider", "admin" ] }, "api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "is_admin": { "type": "boolean", "description": "Compatibilidade com legado." }, "financeiro": { "type": "boolean", "description": "Permissão por pessoa: vê o painel de Vendas (capability `vendas`)." } }, "required": [ "id", "name", "email", "access_level" ], "description": "Membro ativo que pode receber atribuições e capabilities." }, "invitation": { "type": "object", "properties": { "sent": { "type": "boolean", "description": "Confirma o envio do convite." }, "email": { "type": "string", "description": "Destino normalizado.", "format": "email" } }, "required": [ "sent", "email" ] } }, "required": [ "ok", "member", "invitation" ] } ``` Example: ```json { "ok": true, "member": { "id": "member-id", "name": "Novo membro", "email": "membro@example.com", "access_level": "criador" }, "invitation": { "sent": true, "email": "membro@example.com" } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### DELETE /api/membros/{memberId} Revogar acesso e limpar atribuições atuais Não exclui tarefas, conteúdos nem histórico. Preserva o usuário e o membro como âncoras de autoria/FKs; pode retornar 207 quando o acesso foi revogado, mas alguma limpeza precisa ser repetida. Revoga o login e remove apenas atribuições atuais. Conteúdos, tarefas e histórico permanecem preservados como registros de autoria. - operationId: `deactivateMember` - authentication: Supabase session bearer token (session only) - required capability: `members` #### Parameters ##### path memberId - required: true - description: ID de team_members. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Todas as limpezas terminaram." }, "accessRevoked": { "type": "boolean", "description": "Acesso revogado." }, "alreadyInactive": { "type": "boolean", "description": "Já estava inativo." }, "retryable": { "type": "boolean", "description": "Uma repetição é segura." }, "member": { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "name": { "type": "string", "description": "Nome." }, "email": { "type": "string", "description": "E-mail.", "format": "email" } }, "required": [ "id", "name", "email" ] }, "summary": { "type": "object", "properties": { "events": { "type": "integer", "description": "Eventos alterados." }, "tasks": { "type": "integer", "description": "Tarefas desatribuídas." }, "comments": { "type": "integer", "description": "Comentários alterados." }, "platforms": { "type": "integer", "description": "Plataformas alteradas." }, "projects": { "type": "integer", "description": "Projetos alterados." }, "authBan": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "events", "tasks", "comments", "platforms", "projects", "authBan" ] }, "errors": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "description": "Escopo." }, "error": { "type": "string", "description": "Erro." } }, "required": [ "scope", "error" ] } } }, "required": [ "ok", "accessRevoked", "alreadyInactive", "retryable", "member", "summary", "errors" ], "description": "Relatório do desligamento seguro e das limpezas de atribuição." } ``` Example: ```json { "ok": true, "accessRevoked": true, "alreadyInactive": true, "retryable": true, "member": { "id": "id-exemplo", "name": "Exemplo Hermes", "email": "membro@example.com" }, "summary": { "events": 1, "tasks": 1, "comments": 1, "platforms": 1, "projects": 1, "authBan": {} }, "errors": [ { "scope": "string", "error": "string" } ] } ``` ##### 207 Acesso revogado; uma ou mais limpezas falharam e são repetíveis. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Todas as limpezas terminaram." }, "accessRevoked": { "type": "boolean", "description": "Acesso revogado." }, "alreadyInactive": { "type": "boolean", "description": "Já estava inativo." }, "retryable": { "type": "boolean", "description": "Uma repetição é segura." }, "member": { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "name": { "type": "string", "description": "Nome." }, "email": { "type": "string", "description": "E-mail.", "format": "email" } }, "required": [ "id", "name", "email" ] }, "summary": { "type": "object", "properties": { "events": { "type": "integer", "description": "Eventos alterados." }, "tasks": { "type": "integer", "description": "Tarefas desatribuídas." }, "comments": { "type": "integer", "description": "Comentários alterados." }, "platforms": { "type": "integer", "description": "Plataformas alteradas." }, "projects": { "type": "integer", "description": "Projetos alterados." }, "authBan": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "events", "tasks", "comments", "platforms", "projects", "authBan" ] }, "errors": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "description": "Escopo." }, "error": { "type": "string", "description": "Erro." } }, "required": [ "scope", "error" ] } } }, "required": [ "ok", "accessRevoked", "alreadyInactive", "retryable", "member", "summary", "errors" ], "description": "Relatório do desligamento seguro e das limpezas de atribuição." } ``` Example: ```json { "ok": true, "accessRevoked": true, "alreadyInactive": true, "retryable": true, "member": { "id": "id-exemplo", "name": "Exemplo Hermes", "email": "membro@example.com" }, "summary": { "events": 1, "tasks": 1, "comments": 1, "platforms": 1, "projects": 1, "authBan": {} }, "errors": [ { "scope": "string", "error": "string" } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/membros/{memberId}/senha Definir senha nova para um membro Para quem perdeu a senha e não consegue usar o e-mail de recuperação. A senha é escolhida pelo administrador, aplicada pelo Auth Admin e nunca é armazenada, logada ou devolvida. Não se aplica à própria conta (409). - operationId: `setMemberPassword` - authentication: Supabase session bearer token (session only) - required capability: `members` #### Parameters ##### path memberId - required: true - description: ID de team_members. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "password": { "type": "string", "description": "Senha nova (8 a 72 caracteres).", "minLength": 8, "maxLength": 72, "format": "password" } }, "required": [ "password" ] } ``` Example: ```json { "password": "********" } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "member": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do membro." }, "name": { "type": "string", "description": "Nome." }, "email": { "anyOf": [ { "type": "string", "description": "E-mail.", "format": "email" }, { "type": "null" } ] } }, "required": [ "id", "name" ] } }, "required": [ "ok", "member" ] } ``` Example: ```json { "ok": true, "member": { "id": "id-exemplo", "name": "Exemplo Hermes", "email": "membro@example.com" } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/orbum/cancelamentos Registrar o motivo de saída de um assinante do Orbum Grava em `orbum_cancelamentos` o motivo, a oferta feita e o resultado (skill resgate-cancelamento-orbum). Não aceita dado pessoal: a pessoa é o hash vindo de /api/orbum/saidas. - operationId: `createOrbumCancelReason` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "pessoa": { "type": "string", "description": "Hash do e-mail (24 hex)." }, "motivo": { "type": "string", "description": "Motivo.", "enum": [ "financeiro", "tempo", "ja_vi", "insatisfacao", "reembolso", "tecnico", "outro" ] }, "oferta": { "anyOf": [ { "type": "string", "description": "Oferta feita.", "enum": [ "nenhuma", "desconto", "congelamento", "troca_plano", "outra" ] }, { "type": "null" } ] }, "resultado": { "anyOf": [ { "type": "string", "description": "Resultado.", "enum": [ "saiu", "ficou", "congelou", "pendente" ] }, { "type": "null" } ] }, "observacao": { "anyOf": [ { "type": "string", "description": "Até 500 caracteres, sem dados pessoais." }, { "type": "null" } ] } }, "required": [ "pessoa", "motivo" ] } ``` Example: ```json { "pessoa": "string", "motivo": "financeiro", "oferta": "nenhuma", "resultado": "saiu", "observacao": "string" } ``` #### Responses ##### 201 Motivo registrado. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Gravado." }, "id": { "type": "integer", "description": "Id do registro." }, "registrado_em": { "type": "string", "description": "Instante.", "format": "date-time" } }, "required": [ "ok" ] } ``` Example: ```json { "ok": true, "id": 1, "registrado_em": "2026-08-22T15:00:00.000Z" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/orbum/resumo Consultar o painel da assinatura Orbum Cruza o acesso no TheMembers com o pagamento (Hotmart, Pagar.me, Asaas) pessoa a pessoa. Assinante ativo é quem tem pagamento vigente; acesso sem pagamento, pagamento sem acesso e atraso vêm em `alertas`. Grava uma foto agregada por dia em `orbum_snapshots` e devolve o histórico. Só agregados. `atualizar=1` ignora o cache de 10 minutos. - operationId: `getOrbumSummary` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### query atualizar - required: false - description: Força uma leitura nova das fontes. Schema: ```json { "type": "string", "description": "`1` para ignorar o cache.", "enum": [ "1" ] } ``` Example: ```json "1" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Painel do Orbum. ###### application/json Schema: ```json { "type": "object", "properties": { "kpis": { "type": "object", "properties": {}, "additionalProperties": true, "description": "pagantes, com_acesso, receita_recorrente_mensal, ticket_mensal, entradas_mes, saidas_mes, churn_mes, saida_anunciada, sem_renovacao_prevista." }, "alertas": { "type": "object", "properties": {}, "additionalProperties": true, "description": "pagando_sem_acesso, acesso_sem_pagamento (pagou_antes, nunca_pagou), atraso_com_acesso, atraso_sem_acesso, sem_renovacao_prevista." }, "por_plano": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Pagantes por plano." }, "por_renovacao": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Pagantes por tipo de renovação: automatica, manual, cancelada." }, "por_fonte": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Pagantes por gateway." }, "vencimentos": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Fim do período pago em 30, 60 e 90 dias, por tipo de renovação." }, "serie": { "type": "array", "items": { "type": "object", "properties": { "mes": { "type": "string", "description": "Mês YYYY-MM." } }, "required": [ "mes" ], "additionalProperties": true }, "description": "Últimos 12 meses pelo acesso: ativos no fim do mês, entradas, saídas e churn." }, "receita": { "type": "array", "items": { "type": "object", "properties": { "mes": { "type": "string", "description": "Mês YYYY-MM." } }, "required": [ "mes" ], "additionalProperties": true }, "description": "Receita por mês: novas e renovações, em reais." }, "historico": { "type": "array", "items": { "type": "object", "properties": { "dia": { "type": "string", "description": "Dia YYYY-MM-DD." } }, "required": [ "dia" ], "additionalProperties": true }, "description": "Foto diária gravada pelo painel: pagantes, com acesso e receita recorrente." }, "atualizado_em": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Último sync de cada fonte." }, "avisos": { "type": "array", "items": { "type": "string", "description": "Aviso operacional." }, "description": "Lacunas e fallbacks aplicados." } }, "required": [ "kpis", "alertas", "serie", "receita", "avisos" ] } ``` Example: ```json { "kpis": {}, "alertas": {}, "por_plano": {}, "por_renovacao": {}, "por_fonte": {}, "vencimentos": {}, "serie": [ { "mes": "string" } ], "receita": [ { "mes": "string" } ], "historico": [ { "dia": "string" } ], "atualizado_em": {}, "avisos": [ "string" ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Recurso não configurado neste servidor. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "painel de vendas não configurado neste servidor", "code": "VENDAS_NOT_CONFIGURED" } ``` ### GET /api/orbum/saidas Listar quem está saindo do Orbum Pessoas que vão sair (acesso valendo sem cobrança futura), estão em atraso ou saíram nos últimos 60 dias, com e-mail mascarado e o motivo já registrado. `pessoa` é o hash do e-mail usado no registro do motivo. - operationId: `listOrbumExits` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Saídas do Orbum. ###### application/json Schema: ```json { "type": "object", "properties": { "saidas": { "type": "array", "items": { "type": "object", "properties": { "pessoa": { "type": "string", "description": "Hash do e-mail." }, "grupo": { "type": "string", "description": "vai_sair, atraso ou saiu." } }, "required": [ "pessoa", "grupo" ], "additionalProperties": true }, "description": "Lista ordenada por grupo e data." }, "motivos_registrados": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Contagem por motivo." }, "total_registros": { "type": "integer", "description": "Registros de motivo." } }, "required": [ "saidas" ] } ``` Example: ```json { "saidas": [ { "pessoa": "string", "grupo": "string" } ], "motivos_registrados": {}, "total_registros": 1 } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Recurso não configurado neste servidor. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "painel de vendas não configurado neste servidor", "code": "VENDAS_NOT_CONFIGURED" } ``` ### GET /api/plataformas/{platformId}/senha Ler a senha de uma plataforma Exige sessão Supabase de administrador da equipe e nunca aceita token pessoal nem MCP. Decifra e devolve a senha de uma única plataforma de Gastos de Aplicativos; o banco guarda só a cifra. A auditoria da API registra quem pediu, qual plataforma e quando, sem o valor. - operationId: `getPlatformPassword` - authentication: Supabase session bearer token (session only) - required capability: `team_admin` #### Parameters ##### path platformId - required: true - description: ID (UUID) da plataforma em Gastos de Aplicativos. Schema: ```json { "type": "string", "format": "uuid" } ``` Example: ```json "00000000-0000-4000-8000-000000000000" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "senha": { "anyOf": [ { "type": "string", "description": "Senha decifrada; null quando não há senha salva.", "format": "password" }, { "type": "null" } ] } }, "required": [ "senha" ] } ``` Example: ```json { "senha": "********" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### PUT /api/plataformas/{platformId}/senha Gravar ou apagar a senha de uma plataforma Exige sessão Supabase de administrador da equipe. Cifra e grava a senha de uma plataforma (AES-256-GCM no servidor) ou apaga a senha salva com `senha: null`. A resposta nunca devolve o valor. - operationId: `setPlatformPassword` - authentication: Supabase session bearer token (session only) - required capability: `team_admin` #### Parameters ##### path platformId - required: true - description: ID (UUID) da plataforma em Gastos de Aplicativos. Schema: ```json { "type": "string", "format": "uuid" } ``` Example: ```json "00000000-0000-4000-8000-000000000000" ``` #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "senha": { "anyOf": [ { "type": "string", "description": "Senha nova (até 500 caracteres); null ou vazio apaga a senha salva.", "maxLength": 500, "format": "password" }, { "type": "null" } ] } }, "required": [ "senha" ] } ``` Example: ```json { "senha": "********" } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "has_password": { "type": "boolean", "description": "Se a plataforma ficou com senha salva." } }, "required": [ "ok", "has_password" ] } ``` Example: ```json { "ok": true, "has_password": true } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/projects Listar projetos colaborativos Paginação determinística por created_at. Use created_after com o último timestamp recebido. Lista projetos em ordem determinística de criação. Para paginação, use o `created_at` do último item como cursor exclusivo em `created_after`. - operationId: `listProjects` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `projects_view` #### Parameters ##### query created_after - required: false - description: Cursor exclusivo de criação. Schema: ```json { "type": "string", "format": "date-time" } ``` Example: ```json "2026-09-02T15:00:00.000Z" ``` ##### query limit - required: false - description: Máximo de projetos. Schema: ```json { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } ``` Example: ```json 100 ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do projeto." }, "name": { "type": "string", "description": "Nome." }, "payload": { "type": "object", "properties": {}, "additionalProperties": true }, "api_revision": { "type": "integer", "description": "Token CAS canônico.", "minimum": 0 }, "revision": { "type": "integer", "description": "Alias de api_revision.", "minimum": 0 }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Atualização ISO.", "format": "date-time" }, "created_by": { "type": "string", "description": "Usuário criador." }, "updated_by": { "type": "string", "description": "Último usuário editor." } }, "required": [ "id", "name", "payload", "api_revision", "revision", "created_at", "updated_at", "created_by", "updated_by" ], "description": "Documento colaborativo de projeto e seus tokens de concorrência." } } }, "required": [ "projects" ] } ``` Example: ```json { "projects": [ { "id": "id-exemplo", "name": "Exemplo Hermes", "payload": {}, "api_revision": 0, "revision": 0, "created_at": "2026-08-22T15:00:00.000Z", "updated_at": "2026-08-22T15:00:00.000Z", "created_by": "string", "updated_by": "string" } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/projects Criar projeto colaborativo vazio Cria um documento de projeto vazio no formato atual. Forneça uma chave de idempotência para tornar retries de rede seguros. - operationId: `createProject` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `projects_manage` #### Parameters ##### header Idempotency-Key - required: false - description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409. Schema: ```json { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:~-]+$" } ``` Example: ```json "docs-20260822-001" ``` #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "name": { "type": "string", "description": "Nome do projeto.", "minLength": 1, "maxLength": 200 } }, "required": [ "name" ] } ``` Example: ```json { "name": "Lançamento Xamanismo" } ``` #### Responses ##### 201 Projeto criado. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "project": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do projeto." }, "name": { "type": "string", "description": "Nome." }, "payload": { "type": "object", "properties": {}, "additionalProperties": true }, "api_revision": { "type": "integer", "description": "Token CAS canônico.", "minimum": 0 }, "revision": { "type": "integer", "description": "Alias de api_revision.", "minimum": 0 }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Atualização ISO.", "format": "date-time" }, "created_by": { "type": "string", "description": "Usuário criador." }, "updated_by": { "type": "string", "description": "Último usuário editor." } }, "required": [ "id", "name", "payload", "api_revision", "revision", "created_at", "updated_at", "created_by", "updated_by" ], "description": "Documento colaborativo de projeto e seus tokens de concorrência." } }, "required": [ "ok", "project" ] } ``` Example: ```json { "ok": true, "project": { "id": "id-exemplo", "name": "Exemplo Hermes", "payload": {}, "api_revision": 0, "revision": 0, "created_at": "2026-08-22T15:00:00.000Z", "updated_at": "2026-08-22T15:00:00.000Z", "created_by": "string", "updated_by": "string" } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/projects/{projectId} Consultar um projeto e seu token CAS Retorna o projeto completo e os tokens `api_revision`/`revision`. Sempre leia esta rota antes de aplicar uma alteração semântica. - operationId: `getProject` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `projects_view` #### Parameters ##### path projectId - required: true - description: ID de hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do projeto." }, "name": { "type": "string", "description": "Nome." }, "payload": { "type": "object", "properties": {}, "additionalProperties": true }, "api_revision": { "type": "integer", "description": "Token CAS canônico.", "minimum": 0 }, "revision": { "type": "integer", "description": "Alias de api_revision.", "minimum": 0 }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Atualização ISO.", "format": "date-time" }, "created_by": { "type": "string", "description": "Usuário criador." }, "updated_by": { "type": "string", "description": "Último usuário editor." } }, "required": [ "id", "name", "payload", "api_revision", "revision", "created_at", "updated_at", "created_by", "updated_by" ], "description": "Documento colaborativo de projeto e seus tokens de concorrência." } }, "required": [ "project" ] } ``` Example: ```json { "project": { "id": "id-exemplo", "name": "Exemplo Hermes", "payload": {}, "api_revision": 0, "revision": 0, "created_at": "2026-08-22T15:00:00.000Z", "updated_at": "2026-08-22T15:00:00.000Z", "created_by": "string", "updated_by": "string" } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/projects/{projectId}/operations Listar histórico de operações do projeto Exibe o histórico imutável de operações semânticas, da revisão mais recente para a mais antiga, para auditoria e reconstrução de mudanças. - operationId: `listProjectOperations` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `projects_audit_view` #### Parameters ##### path projectId - required: true - description: ID de hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query limit - required: false - description: Máximo de operações. Schema: ```json { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } ``` Example: ```json 50 ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID da operação." }, "payload_revision": { "type": "integer", "description": "Revisão produzida.", "minimum": 0 }, "operation_type": { "type": "string", "description": "Tipo." }, "operation": { "type": "object", "properties": {}, "additionalProperties": true }, "actor_member_id": { "type": "string", "description": "Membro autor." }, "actor_user_id": { "type": "string", "description": "Usuário autor." }, "created_at": { "type": "string", "description": "Data ISO.", "format": "date-time" } }, "required": [ "id", "payload_revision", "operation_type", "operation", "created_at" ], "description": "Registro imutável de uma operação já aplicada ao projeto." } }, "revision": { "type": "integer", "description": "api_revision atual.", "minimum": 0 } }, "required": [ "operations", "revision" ] } ``` Example: ```json { "operations": [ { "id": "id-exemplo", "payload_revision": 0, "operation_type": "string", "operation": {}, "actor_member_id": "actor-member-id-exemplo", "actor_user_id": "actor-user-id-exemplo", "created_at": "2026-08-22T15:00:00.000Z" } ], "revision": 0 } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/projects/{projectId}/operations Aplicar uma operação semântica com CAS Nunca envie um snapshot inteiro. Leia o projeto, use revision/api_revision como expected_revision e aplique uma operação. Em 409, releia antes de decidir um novo payload. O servidor exige `projects_manage` para estrutura, ordem e responsáveis. Com somente `projects_edit`, task.update exige atribuição na tarefa e subtask.update exige atribuição na subtarefa ou tarefa-pai; comentários próprios continuam permitidos. Aplica uma única mudança semântica ao projeto. Criadores só atualizam tarefas atribuídas à própria conta; líderes e admins podem gerenciar a equipe. Nunca envie um snapshot inteiro e, em conflito `409`, releia o projeto. - operationId: `applyProjectOperation` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `projects_edit` - dynamic capability dispatch: `{"default":"projects_edit","projects_manage":["meta.update","goal.add","goal.update","goal.remove","goal.reorder","task.add","task.remove","task.reorder","task.assignees.set","subtask.add","subtask.remove","subtask.reorder","subtask.assignees.set"]}` #### Parameters ##### header Idempotency-Key - required: false - description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409. Schema: ```json { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:~-]+$" } ``` Example: ```json "docs-20260822-001" ``` ##### path projectId - required: true - description: ID de hermes_projects. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "expected_revision": { "type": "integer", "description": "api_revision da leitura mais recente.", "minimum": 0 }, "expected_updated_at": { "type": "string", "description": "Token timestamp adicional opcional.", "format": "date-time" }, "operation": { "type": "object", "properties": { "type": { "type": "string", "description": "Tipo semântico da operação.", "enum": [ "meta.update", "goal.add", "goal.update", "goal.remove", "goal.reorder", "task.add", "task.update", "task.remove", "task.reorder", "task.assignees.set", "subtask.add", "subtask.update", "subtask.remove", "subtask.reorder", "subtask.assignees.set", "comment.add", "comment.update", "comment.remove" ] } }, "required": [ "type" ], "additionalProperties": true } }, "required": [ "expected_revision", "operation" ], "description": "Envelope de uma alteração semântica e atômica de projeto." } ``` Example: ```json { "expected_revision": 4, "expected_updated_at": "2026-08-21T12:00:00.000Z", "operation": { "type": "task.add", "title": "Revisar copy", "status": "pending" } } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "project": { "type": "object", "properties": { "id": { "type": "string", "description": "ID do projeto." }, "name": { "type": "string", "description": "Nome." }, "payload": { "type": "object", "properties": {}, "additionalProperties": true }, "api_revision": { "type": "integer", "description": "Token CAS canônico.", "minimum": 0 }, "revision": { "type": "integer", "description": "Alias de api_revision.", "minimum": 0 }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Atualização ISO.", "format": "date-time" }, "created_by": { "type": "string", "description": "Usuário criador." }, "updated_by": { "type": "string", "description": "Último usuário editor." } }, "required": [ "id", "name", "payload", "api_revision", "revision", "created_at", "updated_at", "created_by", "updated_by" ], "description": "Documento colaborativo de projeto e seus tokens de concorrência." } }, "required": [ "ok", "project" ] } ``` Example: ```json { "ok": true, "project": { "id": "id-exemplo", "name": "Exemplo Hermes", "payload": {}, "api_revision": 0, "revision": 0, "created_at": "2026-08-22T15:00:00.000Z", "updated_at": "2026-08-22T15:00:00.000Z", "created_by": "string", "updated_by": "string" } } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/rag Buscar contexto e citações no Cérebro Pesquisa o Cérebro e devolve contexto consolidado, resultados e citações. Preserve as citações ao produzir conteúdo derivado. - operationId: `searchHermesKnowledge` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `rag` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "tema": { "type": "string", "description": "Tema; `termo` é aceito como alias." }, "termo": { "type": "string", "description": "Alias de tema." }, "n_chunks": { "type": "integer", "description": "Quantidade de chunks de contexto.", "default": 6, "minimum": 1 }, "n_resultados": { "type": "integer", "description": "Quantidade de resultados.", "default": 4, "minimum": 1 } } } ``` Example: ```json { "tema": "consciência", "n_chunks": 6, "n_resultados": 4 } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "contexto": { "type": "string", "description": "Contexto consolidado." }, "fontes": { "anyOf": [ {}, { "type": "null" } ] }, "resultados": { "type": "array", "items": { "type": "object", "properties": { "titulo": { "anyOf": [ { "type": "string", "description": "Título." }, { "type": "null" } ] }, "fonte": { "anyOf": [ { "type": "string", "description": "Fonte." }, { "type": "null" } ] }, "texto": { "type": "string", "description": "Trecho." }, "citacao": { "type": "object", "properties": { "pagina": { "type": "integer", "description": "Página detectada." } }, "additionalProperties": false } }, "required": [ "texto", "citacao" ] } } }, "required": [ "contexto", "resultados" ], "description": "Contexto e evidências retornados pela pesquisa no Cérebro." } ``` Example: ```json { "contexto": "Conteúdo de exemplo", "fontes": "string", "resultados": [ { "titulo": "Conteúdo editorial", "fonte": "string", "texto": "Conteúdo de exemplo", "citacao": { "pagina": 1 } } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/reels Iniciar geração assíncrona de vídeo Cria um job assíncrono de vídeo e retorna imediatamente o identificador para polling. Somente o criador do job ou líderes podem consultar o resultado. - operationId: `generateReel` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `video` #### Parameters ##### header Idempotency-Key - required: false - description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409. Schema: ```json { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:~-]+$" } ``` Example: ```json "docs-20260822-001" ``` #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "event_id": { "type": "string", "description": "Evento opcional." }, "prompt": { "type": "string", "description": "Cena base." }, "motion": { "type": "string", "description": "Movimento desejado." }, "duration": { "type": "string", "description": "Duração em segundos.", "default": "6" }, "resolution": { "type": "string", "description": "Resolução.", "default": "720p" } }, "required": [ "prompt" ] } ``` Example: ```json { "prompt": "Luzes sutis na floresta", "duration": "6", "resolution": "720p" } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "job_id": { "type": "string", "description": "ID do job." }, "state": { "type": "string", "description": "Estado.", "const": "processing" }, "aviso": { "type": "string", "description": "Orientação de polling." } }, "required": [ "job_id", "state", "aviso" ], "description": "Confirmação de que a geração assíncrona de vídeo entrou na fila." } ``` Example: ```json { "job_id": "job-id-exemplo", "state": "processing", "aviso": "string" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/reels/{id} Consultar uma geração de vídeo Consulta o estado de um job de vídeo. Faça polling moderado até `completed` ou `failed`; a URL só está disponível após conclusão. - operationId: `getReelJob` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `reels_view` #### Parameters ##### path id - required: true - description: ID da geração de Reel. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "state": { "type": "string", "description": "Estado." }, "error": { "anyOf": [ { "type": "string", "description": "Erro do worker." }, { "type": "null" } ] }, "url": { "type": "string", "description": "URL quando concluído.", "format": "uri" } }, "required": [ "state" ], "description": "Estado observável de uma geração de vídeo." } ``` Example: ```json { "state": "processing", "error": "string", "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/roteiro Gerar roteiro com pesquisa e verificação Gera um roteiro a partir do tema usando a camada de inteligência do Hermes. O formato detalhado pode evoluir e campos adicionais devem ser preservados pelos clientes. - operationId: `generateScript` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `roteiro` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "tema": { "type": "string", "description": "Tema do roteiro." } }, "required": [ "tema" ] } ``` Example: ```json { "tema": "O poder da curiosidade" } ``` #### Responses ##### 200 Roteiro gerado pela camada de inteligência. ###### application/json Schema: ```json { "type": "object", "properties": {}, "additionalProperties": true } ``` Example: ```json {} ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/skills Listar skills publicadas Lista as skills versionadas publicadas no backend, com filtro opcional pelo nome estável. - operationId: `listSkills` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `skills_view` #### Parameters ##### query name - required: false - description: Filtrar pelo nome exato. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "skills": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome." }, "content": { "type": "string", "description": "Conteúdo." }, "version": { "type": "integer", "description": "Versão." }, "updated_at": { "anyOf": [ { "type": "string", "description": "Atualização ISO.", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "name", "content", "version" ], "description": "Conteúdo versionado de uma skill publicada no backend." } } }, "required": [ "skills" ] } ``` Example: ```json { "skills": [ { "name": "Exemplo Hermes", "content": "Conteúdo de exemplo", "version": 1, "updated_at": "2026-08-22T15:00:00.000Z" } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/skills Publicar nova versão de uma skill Publica uma nova versão do conteúdo de uma skill. Não sobrescreve silenciosamente o histórico e exige a capability `config`. - operationId: `publishSkill` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `config` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "name": { "type": "string", "description": "Nome estável." }, "content": { "type": "string", "description": "Conteúdo integral da skill." } }, "required": [ "name", "content" ] } ``` Example: ```json { "name": "hermes-calendar", "content": "# Hermes Calendar" } ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." }, "name": { "type": "string", "description": "Nome." }, "version": { "type": "integer", "description": "Nova versão." } }, "required": [ "ok", "name", "version" ] } ``` Example: ```json { "ok": true, "name": "Exemplo Hermes", "version": 1 } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/tarefas Listar tarefas ativas do membro Lista tarefas ativas visíveis ao membro autenticado. Cada evento inclui `api_revision`, que deve ser reutilizado em mutações protegidas por CAS. - operationId: `listMyTasks` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `tasks_view` #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "tarefas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do evento." }, "api_revision": { "type": "integer", "description": "Token CAS da API; releia o evento antes de toda mutação.", "minimum": 0 }, "clickup_id": { "anyOf": [ { "type": "string", "description": "Identificador externo/legado." }, { "type": "null" } ] }, "title": { "type": "string", "description": "Título editorial." }, "channel": { "type": "string", "description": "Canal de publicação." }, "status": { "type": "string", "description": "Estado do fluxo editorial." }, "description": { "anyOf": [ { "type": "string", "description": "Legenda ou descrição." }, { "type": "null" } ] }, "day": { "anyOf": [ { "type": "integer", "description": "Dia no horário de Brasília.", "minimum": 1, "maximum": 31 }, { "type": "null" } ] }, "month": { "anyOf": [ { "type": "integer", "description": "Mês no horário de Brasília.", "minimum": 1, "maximum": 12 }, { "type": "null" } ] }, "year": { "anyOf": [ { "type": "integer", "description": "Ano no horário de Brasília." }, { "type": "null" } ] }, "due_at": { "anyOf": [ { "type": "string", "description": "Data/hora ISO 8601 persistida.", "format": "date-time" }, { "type": "null" } ] }, "editorial_tag": { "anyOf": [ { "type": "string", "description": "Tipo/tag editorial." }, { "type": "null" } ] }, "assignee_member_ids": { "type": "array", "items": { "type": "string", "description": "ID de membro." }, "description": "Responsáveis por ID." }, "assignees_names": { "type": "array", "items": { "type": "string", "description": "Nome de membro." }, "description": "Nomes dos responsáveis." } }, "required": [ "id", "title", "channel", "status" ], "additionalProperties": true, "description": "Evento editorial do calendário com token de revisão CAS." } } }, "required": [ "tarefas" ] } ``` Example: ```json { "tarefas": [ { "id": "id-exemplo", "api_revision": 0, "clickup_id": "clickup-id-exemplo", "title": "Conteúdo editorial", "channel": "instagram", "status": "processing", "description": "Conteúdo de exemplo", "day": 1, "month": 1, "year": 1, "due_at": "2026-08-22T15:00:00.000Z", "editorial_tag": "string", "assignee_member_ids": [ "assignee-member-id-exemplo" ], "assignees_names": [ "Exemplo Hermes" ] } ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /api/upload Enviar arquivo pronto Corpo binário, limite de 300 MB. Metadados seguem na query string. Recebe bytes diretamente no corpo e armazena o arquivo. Metadados ficam na query string; use `Idempotency-Key` para evitar duplicatas em repetições. - operationId: `uploadMedia` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `art` #### Parameters ##### header Idempotency-Key - required: false - description: Chave opcional de 8 a 128 caracteres seguros. Repita a mesma chave somente com o mesmo payload; reutilização com conteúdo diferente retorna 409. Schema: ```json { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:~-]+$" } ``` Example: ```json "docs-20260822-001" ``` ##### query event_id - required: false - description: Evento opcional. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query filename - required: false - description: Nome usado também para detectar vídeo. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query format - required: false - description: Proporção/formato. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query kind - required: false - description: Tipo lógico. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query slide_index - required: false - description: Ordem. Schema: ```json { "type": "integer", "default": 0 } ``` Example: ```json 0 ``` #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/octet-stream Schema: ```json { "type": "string", "contentMediaType": "application/octet-stream" } ``` Example: ```json "" ``` ##### image/* Schema: ```json { "type": "string", "contentMediaType": "image/*" } ``` Example: ```json "" ``` ##### video/* Schema: ```json { "type": "string", "contentMediaType": "video/*" } ``` Example: ```json "" ``` #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "url": { "type": "string", "description": "URL pública.", "format": "uri" }, "kind": { "type": "string", "description": "Tipo lógico." }, "bytes": { "type": "integer", "description": "Tamanho recebido.", "minimum": 1 } }, "required": [ "id", "url", "kind", "bytes" ], "description": "Resultado de um upload binário concluído." } ``` Example: ```json { "id": "id-exemplo", "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura", "kind": "string", "bytes": 1 } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 409 Operação conflita com o estado atual. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "conflito" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /api/vendas/comercial Consultar as vendas do time comercial e a comissão Vendas com UTM `comercial` na Hotmart, no checkout Pagar.me e no Asaas, pela data do pedido, com a comissão de 4 % sobre as vendas novas (recorrências ficam fora). Mesmas regras da guia Comissão Nina da planilha de acerto. Só agregados, sem dados de compradores. - operationId: `getCommercialSales` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### query from - required: true - description: Início do período. Schema: ```json { "type": "string", "description": "Primeiro dia do período (YYYY-MM-DD, horário de Brasília).", "format": "date" } ``` Example: ```json "2026-09-01" ``` ##### query to - required: true - description: Fim do período, no máximo amanhã e até 730 dias depois de `from`. Schema: ```json { "type": "string", "description": "Último dia do período (YYYY-MM-DD, horário de Brasília).", "format": "date" } ``` Example: ```json "2026-09-30" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Resumo do comercial no período. ###### application/json Schema: ```json { "type": "object", "properties": { "periodo": { "type": "object", "properties": { "from": { "type": "string", "description": "Início." }, "to": { "type": "string", "description": "Fim." }, "dias": { "type": "integer", "description": "Dias no período." } }, "required": [ "from", "to", "dias" ] }, "pct_comissao": { "type": "number", "description": "Percentual da comissão sobre a base." }, "totais": { "type": "object", "properties": {}, "additionalProperties": true, "description": "qtd, vendido, novas, recorrentes, base_comissao, comissao e ticket do período." }, "por_fonte": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Mesmo bloco por fonte: hotmart, pagarme, asaas." }, "por_mes": { "type": "array", "items": { "type": "object", "properties": { "mes": { "type": "string", "description": "Mês YYYY-MM." } }, "required": [ "mes" ], "additionalProperties": true }, "description": "Um bloco por mês do período, com o vendido por fonte." }, "produtos": { "type": "array", "items": { "type": "object", "properties": { "nome": { "type": "string", "description": "Produto." }, "fonte": { "type": "string", "description": "Fonte." } }, "required": [ "nome", "fonte" ], "additionalProperties": true }, "description": "Produtos vendidos pelo comercial, do maior para o menor." }, "fontes": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Se cada fonte respondeu nesta consulta." }, "avisos": { "type": "array", "items": { "type": "string", "description": "Aviso operacional." }, "description": "Lacunas e fallbacks aplicados." } }, "required": [ "periodo", "pct_comissao", "totais", "por_fonte", "por_mes", "produtos", "avisos" ] } ``` Example: ```json { "periodo": { "from": "string", "to": "string", "dias": 1 }, "pct_comissao": 1, "totais": {}, "por_fonte": {}, "por_mes": [ { "mes": "string" } ], "produtos": [ { "nome": "Exemplo Hermes", "fonte": "string" } ], "fontes": {}, "avisos": [ "string" ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Recurso não configurado neste servidor. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "painel de vendas não configurado neste servidor", "code": "VENDAS_NOT_CONFIGURED" } ``` ### GET /api/vendas/resumo Consultar o resumo de vendas do período Resumo financeiro consolidado do período (Hotmart, Shopify, Asaas e checkout Pagar.me) mais custos de mídia e ROAS. Exige a capability `vendas`, concedida pela permissão por pessoa `financeiro` (não pelo nível). Datas são dias em horário de Brasília, intervalo máximo de 730 dias; valores desconhecidos vêm como `null`, nunca como zero; a resposta nunca inclui dados pessoais de compradores e fica em cache por cinco minutos no servidor. - operationId: `getSalesSummary` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `vendas` #### Parameters ##### query from - required: true - description: Início do período. Schema: ```json { "type": "string", "description": "Primeiro dia do período (YYYY-MM-DD, horário de Brasília).", "format": "date" } ``` Example: ```json "2026-08-01" ``` ##### query produtos - required: false - description: Quantos produtos listar por fonte. Schema: ```json { "type": "string", "description": "`top` (padrão, 15 por fonte) ou `all` (lista completa).", "enum": [ "top", "all" ] } ``` Example: ```json "top" ``` ##### query to - required: true - description: Fim do período, no máximo amanhã e até 730 dias depois de `from`. Schema: ```json { "type": "string", "description": "Último dia do período (YYYY-MM-DD, horário de Brasília).", "format": "date" } ``` Example: ```json "2026-08-31" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Resumo agregado do período. ###### application/json Schema: ```json { "type": "object", "properties": { "periodo": { "type": "object", "properties": { "from": { "type": "string", "description": "Início." }, "to": { "type": "string", "description": "Fim." }, "dias": { "type": "integer", "description": "Dias no período." } }, "required": [ "from", "to", "dias" ] }, "gerado_em": { "type": "string", "description": "Instante de geração.", "format": "date-time" }, "cache": { "type": "object", "properties": { "hit": { "type": "boolean", "description": "Se veio do cache do servidor." }, "ttl_s": { "type": "integer", "description": "Segundos restantes de cache." } }, "required": [ "hit", "ttl_s" ] }, "atualizado_em": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string", "description": "Último sync da tabela." }, { "type": "null" } ] }, "description": "Último sync por tabela de origem." }, "totais": { "type": "object", "properties": { "bruto": { "type": "number", "description": "Faturamento bruto em BRL." }, "liquido": { "type": "number", "description": "Líquido em BRL (Hotmart valor do produtor, Shopify após descontos e reembolsos, Asaas net, Pagar.me parte do JVE)." }, "vendas": { "type": "integer", "description": "Quantidade de vendas." }, "ticket_medio": { "anyOf": [ { "type": "number", "description": "Bruto dividido por vendas." }, { "type": "null" } ] }, "investimento": { "anyOf": [ { "type": "number", "description": "Custos de mídia em BRL." }, { "type": "null" } ] }, "roas": { "anyOf": [ { "type": "number", "description": "Bruto dividido por investimento." }, { "type": "null" } ] } }, "required": [ "bruto", "liquido", "vendas" ] }, "fontes": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Bloco por fonte: hotmart, shopify_livros, shopify_eventos, shopify_outros, asaas, pagarme." }, "serie": { "type": "array", "items": { "type": "object", "properties": { "dia": { "type": "string", "description": "Dia YYYY-MM-DD." } }, "required": [ "dia" ], "additionalProperties": true }, "description": "Série diária por fonte com custo do dia." }, "categorias": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Bloco por categoria: livros, cursos (com Orbum), eventos e youtube (estimado, convertido do dólar). Cada um com bruto, liquido_jve, comissao_trismegisto, qtd, ticket, composicao por plataforma e fontes_indisponiveis." }, "totais_categorias": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Soma das quatro categorias (inclui o YouTube estimado) com ROAS sobre esse total." }, "serie_categorias": { "type": "array", "items": { "type": "object", "properties": { "dia": { "type": "string", "description": "Dia YYYY-MM-DD." } }, "required": [ "dia" ], "additionalProperties": true }, "description": "Série diária de livros, cursos e eventos; o YouTube mensal vem em categorias.youtube.por_mes." }, "produtos": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Top 15 produtos por fonte." }, "intl": { "type": "array", "items": { "type": "object", "properties": { "moeda": { "type": "string", "description": "Moeda ISO." } }, "required": [ "moeda" ], "additionalProperties": true }, "description": "Vendas Hotmart fora do BRL, por moeda." }, "custos": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Meta, Google e WhatsApp, por dia e por campanha, com ROAS." }, { "type": "null" } ] }, "avisos": { "type": "array", "items": { "type": "string", "description": "Aviso operacional." }, "description": "Lacunas e fallbacks aplicados." } }, "required": [ "periodo", "gerado_em", "totais", "fontes", "serie", "produtos", "intl", "avisos" ] } ``` Example: ```json { "periodo": { "from": "string", "to": "string", "dias": 1 }, "gerado_em": "2026-08-22T15:00:00.000Z", "cache": { "hit": true, "ttl_s": 1 }, "atualizado_em": {}, "totais": { "bruto": 1, "liquido": 1, "vendas": 1, "ticket_medio": 1, "investimento": 1, "roas": 1 }, "fontes": {}, "serie": [ { "dia": "string" } ], "categorias": {}, "totais_categorias": {}, "serie_categorias": [ { "dia": "string" } ], "produtos": {}, "intl": [ { "moeda": "string" } ], "custos": {}, "avisos": [ "string" ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ##### 503 Recurso não configurado neste servidor. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "painel de vendas não configurado neste servidor", "code": "VENDAS_NOT_CONFIGURED" } ``` ### GET /media/{id} Baixar uma mídia pelo domínio do Hermes Proxy público necessário para provedores que fazem pull da mídia por URL (Post for Me, TikTok PULL_FROM_URL). Não exige login, mas só abre com a assinatura `sig` e dentro da validade `exp` que o Hermes coloca na URL. O tipo retornado depende do asset. Entrega um asset armazenado pelo Hermes para visualização ou consumo por provedores sociais. Use sempre a URL completa devolvida pelas operações de mídia: ela leva `exp` e `sig` e vale por 7 dias. Link sem assinatura, adulterado ou vencido recebe 403; peça a mídia de novo para obter um link novo. - operationId: `getMedia` - authentication: public #### Parameters ##### path id - required: true - description: ID de media_assets. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` ##### query exp - required: true - description: Validade do link em segundos Unix, emitida pelo Hermes. Schema: ```json { "type": "string", "pattern": "^\\d{1,12}$" } ``` Example: ```json "string" ``` ##### query sig - required: true - description: Assinatura HMAC do link, emitida pelo Hermes. Schema: ```json { "type": "string" } ``` Example: ```json "string" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Bytes da mídia. ###### application/octet-stream Schema: ```json { "type": "string", "contentMediaType": "application/octet-stream" } ``` Example: ```json "" ``` ##### 403 Link sem assinatura, adulterado ou vencido. ###### text/plain Schema: ```json { "type": "string" } ``` Example: ```json "link de mídia expirado ou inválido; gere um novo pelo Hermes" ``` ##### 404 Mídia ou objeto de storage não encontrado; resposta sem corpo. Schema: no response body. Example: no response body. ##### 500 Falha interna; resposta sem corpo. Schema: no response body. Example: no response body. ### GET /oauth/_accounts Listar provedores e contas conectadas Nunca retorna tokens. Retorna provedores habilitados e metadados seguros das contas conectadas. Tokens, refresh tokens e segredos nunca aparecem na resposta. - operationId: `listOAuthAccounts` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `connections_view` #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "string", "description": "Provedor disponível no ambiente." } }, "accounts": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Contas conectadas, sem credenciais." } }, "required": [ "providers", "accounts" ] } ``` Example: ```json { "providers": [ "meta" ], "accounts": [ {} ] } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /oauth/tiktok/creator-info Consultar restrições do criador no TikTok Consulta limites e opções de publicação da conta TikTok conectada, como privacidade e recursos permitidos, antes de preparar um envio. - operationId: `getTikTokCreatorInfo` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `connections_view` #### Parameters No path, query, header, or cookie parameters. #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Resposta normalizada do TikTok Creator Info. ###### application/json Schema: ```json { "type": "object", "properties": {}, "additionalProperties": true } ``` Example: ```json {} ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /oauth/tiktok/publish Publicar conteúdo no TikTok Aceita somente IDs de mídia do Hermes; URLs arbitrárias do cliente são rejeitadas pelo desenho da rota. Publica foto ou vídeo usando exclusivamente IDs de mídia armazenados pelo Hermes. Valide antes as restrições retornadas por Creator Info. - operationId: `publishTikTokContent` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `publish` #### Parameters No path, query, header, or cookie parameters. #### Request body - required: true - description: Payload da operação. Envie somente os campos documentados e preserve os tipos indicados pelo schema. ##### application/json Schema: ```json { "type": "object", "properties": { "type": { "type": "string", "description": "Formato do post.", "enum": [ "PHOTO", "VIDEO" ], "default": "PHOTO" }, "caption": { "type": "string", "description": "Legenda." }, "mediaIds": { "type": "array", "items": { "type": "string", "description": "ID em media_assets." }, "description": "IDs na ordem de publicação." }, "privacy_level": { "type": "string", "description": "Privacidade solicitada. Em app não auditado o servidor força SELF_ONLY." }, "disable_comment": { "type": "boolean", "description": "Desabilitar comentários." }, "disable_duet": { "type": "boolean", "description": "Desabilitar duetos." }, "disable_stitch": { "type": "boolean", "description": "Desabilitar stitch." }, "brand_organic_toggle": { "type": "boolean", "description": "Marcar conteúdo promocional próprio." }, "brand_content_toggle": { "type": "boolean", "description": "Marcar conteúdo de marca." }, "auto_add_music": { "type": "boolean", "description": "Permitir música automática." } }, "required": [ "mediaIds" ] } ``` Example: ```json { "type": "PHOTO", "caption": "Legenda", "mediaIds": [ "media-id" ], "privacy_level": "SELF_ONLY", "disable_comment": false, "disable_duet": false, "disable_stitch": false, "brand_organic_toggle": false, "brand_content_toggle": false, "auto_add_music": false } ``` #### Responses ##### 200 Resposta do adaptador TikTok. ###### application/json Schema: ```json { "type": "object", "properties": {}, "additionalProperties": true } ``` Example: ```json {} ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Recurso não encontrado. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "recurso não encontrado" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### GET /oauth/{provider}/callback Concluir callback OAuth O state HMAC expira em dez minutos, contém apenas vínculos opacos com usuário/membro e exige o cookie HttpOnly/Secure/SameSite=Lax do navegador iniciador. O cookie é apagado antes da troca do código. Callback consumido pelo navegador após autorização no provedor. `state` e cookie precisam corresponder ao fluxo iniciado e expiram em dez minutos. - operationId: `completeOAuthProvider` - authentication: public #### Parameters ##### path provider - required: true - description: Provedor social potencialmente disponível no ambiente. Schema: ```json { "type": "string", "enum": [ "meta", "pinterest", "tiktok", "youtube" ] } ``` Example: ```json "meta" ``` ##### query code - required: true - description: Código emitido pelo provedor. Schema: ```json { "type": "string" } ``` Example: ```json "provider-authorization-code" ``` ##### query state - required: true - description: Estado HMAC emitido pela rota start. Schema: ```json { "type": "string" } ``` Example: ```json "signed-oauth-state" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Conta conectada; texto para a janela OAuth. ###### text/html Schema: ```json { "type": "string" } ``` Example: ```json "Conta conectada!" ``` ##### 400 Estado inválido ou expirado. ###### text/plain Schema: ```json { "type": "string" } ``` Example: ```json "Sessão de conexão inválida ou expirada." ``` ##### 404 Provedor não suportado. ###### text/plain Schema: ```json { "type": "string" } ``` Example: ```json "rede não suportada: provider" ``` ##### 500 Falha na troca do código ou persistência. ###### text/plain Schema: ```json { "type": "string" } ``` Example: ```json "Erro ao conectar: detalhe" ``` ### POST /oauth/{provider}/disconnect Desconectar um provedor social Revoga a conexão persistida do provedor para a equipe. Depois da operação, confirme o estado com a consulta de contas antes de iniciar uma nova autorização. - operationId: `disconnectOAuthProvider` - authentication: Supabase session bearer token (session only) - required capability: `connections` #### Parameters ##### path provider - required: true - description: Provedor social potencialmente disponível no ambiente. Schema: ```json { "type": "string", "enum": [ "meta", "pinterest", "tiktok", "youtube" ] } ``` Example: ```json "meta" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." } }, "required": [ "ok" ], "description": "Confirmação mínima de uma operação concluída." } ``` Example: ```json { "ok": true } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 500 Falha interna ou de integração. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da falha" } ``` ### POST /oauth/{provider}/start Iniciar autorização OAuth Exige administrador com capability connections. Cria state opaco ligado ao usuário/membro e cookie HttpOnly restrito ao callback; retorna a URL para um popup já aberto pelo front. Inicia um fluxo OAuth vinculado ao usuário e membro atuais. Abra a URL retornada no navegador que iniciou a operação para preservar o cookie seguro do callback. - operationId: `startOAuthProvider` - authentication: Supabase session bearer token (session only) - required capability: `connections` #### Parameters ##### path provider - required: true - description: Provedor social potencialmente disponível no ambiente. Schema: ```json { "type": "string", "enum": [ "meta", "pinterest", "tiktok", "youtube" ] } ``` Example: ```json "meta" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Operação concluída. ###### application/json Schema: ```json { "type": "object", "properties": { "url": { "type": "string", "description": "URL de autorização do provedor.", "format": "uri" } }, "required": [ "url" ] } ``` Example: ```json { "url": "https://socialmedia.janvalellam.com.br/media/media-id?exp=1790000000&sig=assinatura" } ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Provedor não suportado. ###### text/plain Schema: ```json { "type": "string" } ``` Example: ```json "rede não suportada: provider" ``` ##### 500 Falha ao iniciar o fluxo OAuth. ###### text/plain Schema: ```json { "type": "string" } ``` Example: ```json "Internal Server Error" ``` ### GET /oauth/{provider}/status Exibir diagnóstico HTML da conexão Página HTML de diagnóstico destinada ao navegador. Para integração programática, prefira a listagem JSON de contas conectadas. - operationId: `getOAuthProviderStatus` - authentication: Supabase session or `hms_live_` personal bearer token - required capability: `connections_view` #### Parameters ##### path provider - required: true - description: Provedor social potencialmente disponível no ambiente. Schema: ```json { "type": "string", "enum": [ "meta", "pinterest", "tiktok", "youtube" ] } ``` Example: ```json "meta" ``` #### Request body Schema: no request body. Example: no request body. #### Responses ##### 200 Página HTML de diagnóstico. ###### text/html Schema: ```json { "type": "string" } ``` Example: ```json "Operação concluída." ``` ##### 400 Entrada inválida. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "detalhe da validação" } ``` ##### 401 Token ausente, inválido ou falha de autenticação. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "não autenticado" } ``` ##### 403 Usuário fora da equipe ativa ou sem a capability necessária. ###### application/json Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "sem permissão para: capability" } ``` ##### 404 Provedor não suportado. ###### text/plain Schema: ```json { "type": "string" } ``` Example: ```json "rede não suportada: provider" ``` ##### 500 Falha na consulta ao provedor. ###### text/plain Schema: ```json { "type": "string" } ``` Example: ```json "Erro: detalhe" ``` ## Self-contained schemas ### AiManifest Schema: ```json { "type": "object", "properties": { "schema_version": { "type": "integer", "description": "Versão do formato.", "const": 1 }, "release": { "type": "object", "properties": { "version": { "type": "string", "description": "Versão da camada de IA." }, "date": { "type": "string", "description": "Data ISO.", "format": "date" } }, "required": [ "version", "date" ] }, "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID estável." }, "path": { "type": "string", "description": "Caminho no repositório." }, "url": { "type": "string", "description": "URL pública.", "format": "uri" }, "media_type": { "type": "string", "description": "MIME." }, "bytes": { "type": "integer", "description": "Tamanho.", "minimum": 1 }, "sha256": { "type": "string", "description": "SHA-256 hexadecimal.", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "path", "url", "media_type", "bytes", "sha256" ] } }, "skills": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome da skill." }, "version": { "type": "string", "description": "Versão." }, "artifact_id": { "type": "string", "description": "ID do ZIP." }, "sha256": { "type": "string", "description": "SHA-256 do ZIP." } }, "required": [ "name", "version", "artifact_id", "sha256" ] } } }, "required": [ "schema_version", "release", "artifacts", "skills" ], "description": "Catálogo verificável dos artefatos públicos da camada de IA." } ``` Example: ```json { "schema_version": 1, "release": { "version": "string", "date": "2026-09-02" }, "artifacts": [ { "id": "string", "path": "string", "url": "https://socialmedia.janvalellam.com.br/resource", "media_type": "string", "bytes": 1, "sha256": "string" } ], "skills": [ { "name": "string", "version": "string", "artifact_id": "string", "sha256": "string" } ] } ``` ### ApiAccessLevel Schema: ```json { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] } ``` Example: ```json "nenhum" ``` ### ApiAccessMember Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID do membro." }, "name": { "type": "string", "description": "Nome." }, "email": { "anyOf": [ { "type": "string", "description": "E-mail.", "format": "email" }, { "type": "null" } ] }, "access_level": { "type": "string", "description": "Cargo atual no Studio; governa sessões e funciona como teto do PAT.", "enum": [ "criador", "lider", "admin" ] }, "api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "effective_api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "capabilities": { "type": "array", "items": { "type": "string", "description": "Capability efetiva disponível para tokens pessoais; não descreve nem limita a sessão do Studio." } }, "token_count": { "type": "integer", "description": "Quantidade de tokens ativos.", "minimum": 0, "maximum": 10 }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID público usado para revogação." }, "label": { "type": "string", "description": "Nome legível definido pelo usuário." }, "prefix": { "type": "string", "description": "Prefixo identificável sem a parte secreta.", "pattern": "^hms_live_[A-Za-z0-9_-]{16}$" }, "scopes": { "type": "array", "items": { "type": "string", "description": "Capability concedida ao token." }, "description": "Scopes persistidos em ordem determinística." }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "expires_at": { "type": "string", "description": "Expiração ISO.", "format": "date-time" }, "last_used_at": { "anyOf": [ { "type": "string", "description": "Último uso observado, atualizado de forma best effort.", "format": "date-time" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "description": "Revogação ISO, quando aplicável.", "format": "date-time" }, { "type": "null" } ] }, "status": { "type": "string", "description": "Estado derivado no momento da leitura.", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "id", "label", "prefix", "scopes", "created_at", "expires_at", "last_used_at", "revoked_at", "status" ], "description": "Metadados revogáveis de um token pessoal sem segredo nem hash." } } }, "required": [ "id", "name", "access_level", "api_access_level", "effective_api_access_level", "capabilities", "token_count", "tokens" ], "description": "Visão administrativa do cargo do Studio e da camada separada de tokens pessoais de um membro ativo." } ``` Example: ```json { "id": "string", "name": "string", "access_level": "criador", "api_access_level": "nenhum", "effective_api_access_level": "nenhum", "capabilities": [ "string" ], "token_count": 0, "tokens": [ { "id": "string", "label": "string", "prefix": "string", "scopes": [ "string" ], "created_at": "2026-09-02T15:00:00.000Z", "expires_at": "2026-09-02T15:00:00.000Z", "last_used_at": "2026-09-02T15:00:00.000Z", "revoked_at": "2026-09-02T15:00:00.000Z", "status": "active" } ] } ``` ### ApiAccessSelfMember Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID do membro." }, "name": { "type": "string", "description": "Nome." }, "email": { "anyOf": [ { "type": "string", "description": "E-mail.", "format": "email" }, { "type": "null" } ] }, "access_level": { "type": "string", "description": "Cargo atual no Studio; governa a sessão e funciona como teto do PAT.", "enum": [ "criador", "lider", "admin" ] }, "financeiro": { "type": "boolean", "description": "Permissão por pessoa: vê o painel de Vendas." }, "api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "effective_api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] } }, "required": [ "id", "name", "access_level", "api_access_level", "effective_api_access_level" ], "description": "Resumo da configuração de tokens pessoais do membro; não limita a sessão atual do Studio." } ``` Example: ```json { "id": "string", "name": "string", "access_level": "criador", "api_access_level": "nenhum", "effective_api_access_level": "nenhum" } ``` ### ApiAuditEvent Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID do evento de auditoria." }, "occurred_at": { "type": "string", "description": "Data/hora do evento.", "format": "date-time" }, "request_id": { "anyOf": [ { "type": "string", "description": "Correlação segura da requisição." }, { "type": "null" } ] }, "actor_member_id": { "anyOf": [ { "type": "string", "description": "Membro autor." }, { "type": "null" } ] }, "actor_user_id": { "anyOf": [ { "type": "string", "description": "Usuário Supabase autor." }, { "type": "null" } ] }, "token_id": { "anyOf": [ { "type": "string", "description": "ID de metadados do token pessoal, nunca o segredo ou hash." }, { "type": "null" } ] }, "auth_method": { "type": "string", "description": "Método de autenticação observado.", "enum": [ "session", "personal_token", "system", "anonymous" ] }, "capability": { "anyOf": [ { "type": "string", "description": "Capability avaliada." }, { "type": "null" } ] }, "action": { "type": "string", "description": "Ação normalizada." }, "resource_type": { "anyOf": [ { "type": "string", "description": "Tipo lógico do recurso." }, { "type": "null" } ] }, "resource_id": { "anyOf": [ { "type": "string", "description": "ID lógico do recurso." }, { "type": "null" } ] }, "outcome": { "type": "string", "description": "Resultado normalizado.", "enum": [ "allowed", "denied", "succeeded", "failed" ] }, "status_code": { "anyOf": [ { "type": "integer", "description": "Status HTTP relacionado.", "minimum": 100, "maximum": 599 }, { "type": "null" } ] }, "metadata": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "id", "occurred_at", "auth_method", "action", "outcome", "metadata" ], "description": "Evento sanitizado da trilha de autorização e gestão de acesso à API." } ``` Example: ```json { "id": "string", "occurred_at": "2026-09-02T15:00:00.000Z", "auth_method": "session", "action": "string", "outcome": "allowed", "metadata": {} } ``` ### AuthContext Schema: ```json { "type": "object", "properties": { "kind": { "type": "string", "description": "Método que autenticou a chamada.", "enum": [ "session", "api_token" ] }, "token_id": { "anyOf": [ { "type": "string", "description": "ID do token pessoal quando kind é api_token." }, { "type": "null" } ] } }, "required": [ "kind", "token_id" ], "description": "Método efetivamente usado para autenticar a requisição atual." } ``` Example: ```json { "kind": "session", "token_id": "string" } ``` ### ConfigEntry Schema: ```json { "type": "object", "properties": { "value": {}, "version": { "type": "integer", "description": "Versão." }, "updated_at": { "anyOf": [ { "type": "string", "description": "Atualização ISO.", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "value", "version" ], "description": "Versão mais recente de uma configuração." } ``` Example: ```json { "value": {}, "version": 0 } ``` ### EmailDraft Schema: ```json { "type": "object", "properties": { "template_id": { "type": "string", "description": "ID lógico do template." }, "html": { "type": "string", "description": "HTML completo." }, "metadata": { "type": "object", "properties": {}, "additionalProperties": true }, "updated_at": { "type": "string", "description": "Token CAS.", "format": "date-time" }, "updated_by": { "type": "string", "description": "Usuário editor." } }, "required": [ "template_id", "html", "metadata", "updated_at", "updated_by" ], "description": "Template de e-mail completo com token CAS baseado em timestamp." } ``` Example: ```json { "template_id": "string", "html": "string", "metadata": {}, "updated_at": "2026-09-02T15:00:00.000Z", "updated_by": "string" } ``` ### EmailDraftSummary Schema: ```json { "type": "object", "properties": { "template_id": { "type": "string", "description": "ID lógico do template." }, "metadata": { "type": "object", "properties": {}, "additionalProperties": true }, "updated_at": { "type": "string", "description": "Token CAS.", "format": "date-time" }, "updated_by": { "type": "string", "description": "Usuário editor." } }, "required": [ "template_id", "metadata", "updated_at", "updated_by" ], "description": "Metadados leves de um rascunho, sem o HTML completo." } ``` Example: ```json { "template_id": "string", "metadata": {}, "updated_at": "2026-09-02T15:00:00.000Z", "updated_by": "string" } ``` ### Error Schema: ```json { "type": "object", "properties": { "error": { "type": "string", "description": "Mensagem segura para diagnóstico." }, "code": { "type": "string", "description": "Código estável opcional." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "error" ], "description": "Formato padrão de erro JSON. `code` e `details` aparecem quando existe um diagnóstico estável e acionável." } ``` Example: ```json { "error": "string" } ``` ### Event Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador do evento." }, "api_revision": { "type": "integer", "description": "Token CAS da API; releia o evento antes de toda mutação.", "minimum": 0 }, "clickup_id": { "anyOf": [ { "type": "string", "description": "Identificador externo/legado." }, { "type": "null" } ] }, "title": { "type": "string", "description": "Título editorial." }, "channel": { "type": "string", "description": "Canal de publicação." }, "status": { "type": "string", "description": "Estado do fluxo editorial." }, "description": { "anyOf": [ { "type": "string", "description": "Legenda ou descrição." }, { "type": "null" } ] }, "day": { "anyOf": [ { "type": "integer", "description": "Dia no horário de Brasília.", "minimum": 1, "maximum": 31 }, { "type": "null" } ] }, "month": { "anyOf": [ { "type": "integer", "description": "Mês no horário de Brasília.", "minimum": 1, "maximum": 12 }, { "type": "null" } ] }, "year": { "anyOf": [ { "type": "integer", "description": "Ano no horário de Brasília." }, { "type": "null" } ] }, "due_at": { "anyOf": [ { "type": "string", "description": "Data/hora ISO 8601 persistida.", "format": "date-time" }, { "type": "null" } ] }, "editorial_tag": { "anyOf": [ { "type": "string", "description": "Tipo/tag editorial." }, { "type": "null" } ] }, "assignee_member_ids": { "type": "array", "items": { "type": "string", "description": "ID de membro." }, "description": "Responsáveis por ID." }, "assignees_names": { "type": "array", "items": { "type": "string", "description": "Nome de membro." }, "description": "Nomes dos responsáveis." } }, "required": [ "id", "title", "channel", "status" ], "additionalProperties": true, "description": "Evento editorial do calendário com token de revisão CAS." } ``` Example: ```json { "id": "string", "title": "string", "channel": "string", "status": "string" } ``` ### MediaReference Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "url": { "type": "string", "description": "URL pública no Hermes.", "format": "uri" }, "slide_index": { "type": "integer", "description": "Ordem." }, "kind": { "type": "string", "description": "Tipo lógico." } }, "required": [ "id", "url" ], "additionalProperties": true, "description": "Referência pública e ordenável de uma mídia persistida." } ``` Example: ```json { "id": "string", "url": "https://socialmedia.janvalellam.com.br/resource" } ``` ### Member Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "name": { "type": "string", "description": "Nome." }, "email": { "type": "string", "description": "E-mail.", "format": "email" }, "role": { "anyOf": [ { "type": "string", "description": "Função." }, { "type": "null" } ] }, "access_level": { "type": "string", "description": "Cargo no Studio.", "enum": [ "criador", "lider", "admin" ] }, "api_access_level": { "type": "string", "description": "Nível individual configurável somente para tokens pessoais da API; não limita sessões do Studio.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "is_admin": { "type": "boolean", "description": "Compatibilidade com legado." }, "financeiro": { "type": "boolean", "description": "Permissão por pessoa: vê o painel de Vendas (capability `vendas`)." } }, "required": [ "id", "name", "email", "access_level" ], "description": "Membro ativo que pode receber atribuições e capabilities." } ``` Example: ```json { "id": "string", "name": "string", "email": "colaborador@example.com", "access_level": "criador" } ``` ### MemberIdentity Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID do membro." }, "user_id": { "type": "string", "description": "ID do usuário Supabase vinculado." }, "name": { "type": "string", "description": "Nome." }, "email": { "anyOf": [ { "type": "string", "description": "E-mail do membro.", "format": "email" }, { "type": "null" } ] }, "access_level": { "type": "string", "description": "Nível desta credencial: cargo do Studio para session; nível PAT efetivo para api_token.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] }, "team_access_level": { "type": "string", "description": "Cargo atual no Studio; governa a sessão e serve de teto somente para PAT.", "enum": [ "criador", "lider", "admin" ] }, "api_access_level": { "type": "string", "description": "Configuração de PAT na sessão; nível PAT efetivo quando auth.kind é api_token.", "enum": [ "nenhum", "leitor", "criador", "lider", "admin" ] } }, "required": [ "id", "name", "access_level", "team_access_level", "api_access_level" ], "description": "Identidade e autorização da credencial atual: cargo do Studio para sessão ou nível efetivo para PAT." } ``` Example: ```json { "id": "string", "name": "string", "access_level": "nenhum", "team_access_level": "criador", "api_access_level": "nenhum" } ``` ### MemberOffboardingResult Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Todas as limpezas terminaram." }, "accessRevoked": { "type": "boolean", "description": "Acesso revogado." }, "alreadyInactive": { "type": "boolean", "description": "Já estava inativo." }, "retryable": { "type": "boolean", "description": "Uma repetição é segura." }, "member": { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "name": { "type": "string", "description": "Nome." }, "email": { "type": "string", "description": "E-mail.", "format": "email" } }, "required": [ "id", "name", "email" ] }, "summary": { "type": "object", "properties": { "events": { "type": "integer", "description": "Eventos alterados." }, "tasks": { "type": "integer", "description": "Tarefas desatribuídas." }, "comments": { "type": "integer", "description": "Comentários alterados." }, "platforms": { "type": "integer", "description": "Plataformas alteradas." }, "projects": { "type": "integer", "description": "Projetos alterados." }, "authBan": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "events", "tasks", "comments", "platforms", "projects", "authBan" ] }, "errors": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "description": "Escopo." }, "error": { "type": "string", "description": "Erro." } }, "required": [ "scope", "error" ] } } }, "required": [ "ok", "accessRevoked", "alreadyInactive", "retryable", "member", "summary", "errors" ], "description": "Relatório do desligamento seguro e das limpezas de atribuição." } ``` Example: ```json { "ok": false, "accessRevoked": false, "alreadyInactive": false, "retryable": false, "member": { "id": "string", "name": "string", "email": "colaborador@example.com" }, "summary": { "events": 0, "tasks": 0, "comments": 0, "platforms": 0, "projects": 0, "authBan": {} }, "errors": [ { "scope": "string", "error": "string" } ] } ``` ### OkResponse Schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Sucesso." } }, "required": [ "ok" ], "description": "Confirmação mínima de uma operação concluída." } ``` Example: ```json { "ok": false } ``` ### PersonalApiTokenMetadata Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID público usado para revogação." }, "label": { "type": "string", "description": "Nome legível definido pelo usuário." }, "prefix": { "type": "string", "description": "Prefixo identificável sem a parte secreta.", "pattern": "^hms_live_[A-Za-z0-9_-]{16}$" }, "scopes": { "type": "array", "items": { "type": "string", "description": "Capability concedida ao token." }, "description": "Scopes persistidos em ordem determinística." }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "expires_at": { "type": "string", "description": "Expiração ISO.", "format": "date-time" }, "last_used_at": { "anyOf": [ { "type": "string", "description": "Último uso observado, atualizado de forma best effort.", "format": "date-time" }, { "type": "null" } ] }, "revoked_at": { "anyOf": [ { "type": "string", "description": "Revogação ISO, quando aplicável.", "format": "date-time" }, { "type": "null" } ] }, "status": { "type": "string", "description": "Estado derivado no momento da leitura.", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "id", "label", "prefix", "scopes", "created_at", "expires_at", "last_used_at", "revoked_at", "status" ], "description": "Metadados revogáveis de um token pessoal sem segredo nem hash." } ``` Example: ```json { "id": "string", "label": "string", "prefix": "string", "scopes": [ "string" ], "created_at": "2026-09-02T15:00:00.000Z", "expires_at": "2026-09-02T15:00:00.000Z", "last_used_at": "2026-09-02T15:00:00.000Z", "revoked_at": "2026-09-02T15:00:00.000Z", "status": "active" } ``` ### Project Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID do projeto." }, "name": { "type": "string", "description": "Nome." }, "payload": { "type": "object", "properties": {}, "additionalProperties": true }, "api_revision": { "type": "integer", "description": "Token CAS canônico.", "minimum": 0 }, "revision": { "type": "integer", "description": "Alias de api_revision.", "minimum": 0 }, "created_at": { "type": "string", "description": "Criação ISO.", "format": "date-time" }, "updated_at": { "type": "string", "description": "Atualização ISO.", "format": "date-time" }, "created_by": { "type": "string", "description": "Usuário criador." }, "updated_by": { "type": "string", "description": "Último usuário editor." } }, "required": [ "id", "name", "payload", "api_revision", "revision", "created_at", "updated_at", "created_by", "updated_by" ], "description": "Documento colaborativo de projeto e seus tokens de concorrência." } ``` Example: ```json { "id": "string", "name": "string", "payload": {}, "api_revision": 0, "revision": 0, "created_at": "2026-09-02T15:00:00.000Z", "updated_at": "2026-09-02T15:00:00.000Z", "created_by": "string", "updated_by": "string" } ``` ### ProjectOperationLog Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID da operação." }, "payload_revision": { "type": "integer", "description": "Revisão produzida.", "minimum": 0 }, "operation_type": { "type": "string", "description": "Tipo." }, "operation": { "type": "object", "properties": {}, "additionalProperties": true }, "actor_member_id": { "type": "string", "description": "Membro autor." }, "actor_user_id": { "type": "string", "description": "Usuário autor." }, "created_at": { "type": "string", "description": "Data ISO.", "format": "date-time" } }, "required": [ "id", "payload_revision", "operation_type", "operation", "created_at" ], "description": "Registro imutável de uma operação já aplicada ao projeto." } ``` Example: ```json { "id": "string", "payload_revision": 0, "operation_type": "string", "operation": {}, "created_at": "2026-09-02T15:00:00.000Z" } ``` ### ProjectOperationRequest Schema: ```json { "type": "object", "properties": { "expected_revision": { "type": "integer", "description": "api_revision da leitura mais recente.", "minimum": 0 }, "expected_updated_at": { "type": "string", "description": "Token timestamp adicional opcional.", "format": "date-time" }, "operation": { "type": "object", "properties": { "type": { "type": "string", "description": "Tipo semântico da operação.", "enum": [ "meta.update", "goal.add", "goal.update", "goal.remove", "goal.reorder", "task.add", "task.update", "task.remove", "task.reorder", "task.assignees.set", "subtask.add", "subtask.update", "subtask.remove", "subtask.reorder", "subtask.assignees.set", "comment.add", "comment.update", "comment.remove" ] } }, "required": [ "type" ], "additionalProperties": true } }, "required": [ "expected_revision", "operation" ], "description": "Envelope de uma alteração semântica e atômica de projeto." } ``` Example: ```json { "expected_revision": 0, "operation": { "type": "meta.update" } } ``` ### RagResponse Schema: ```json { "type": "object", "properties": { "contexto": { "type": "string", "description": "Contexto consolidado." }, "fontes": { "anyOf": [ {}, { "type": "null" } ] }, "resultados": { "type": "array", "items": { "type": "object", "properties": { "titulo": { "anyOf": [ { "type": "string", "description": "Título." }, { "type": "null" } ] }, "fonte": { "anyOf": [ { "type": "string", "description": "Fonte." }, { "type": "null" } ] }, "texto": { "type": "string", "description": "Trecho." }, "citacao": { "type": "object", "properties": { "pagina": { "type": "integer", "description": "Página detectada." } }, "additionalProperties": false } }, "required": [ "texto", "citacao" ] } } }, "required": [ "contexto", "resultados" ], "description": "Contexto e evidências retornados pela pesquisa no Cérebro." } ``` Example: ```json { "contexto": "string", "resultados": [ { "texto": "string", "citacao": {} } ] } ``` ### ReelJob Schema: ```json { "type": "object", "properties": { "state": { "type": "string", "description": "Estado." }, "error": { "anyOf": [ { "type": "string", "description": "Erro do worker." }, { "type": "null" } ] }, "url": { "type": "string", "description": "URL quando concluído.", "format": "uri" } }, "required": [ "state" ], "description": "Estado observável de uma geração de vídeo." } ``` Example: ```json { "state": "string" } ``` ### ReelJobAccepted Schema: ```json { "type": "object", "properties": { "job_id": { "type": "string", "description": "ID do job." }, "state": { "type": "string", "description": "Estado.", "const": "processing" }, "aviso": { "type": "string", "description": "Orientação de polling." } }, "required": [ "job_id", "state", "aviso" ], "description": "Confirmação de que a geração assíncrona de vídeo entrou na fila." } ``` Example: ```json { "job_id": "string", "state": "processing", "aviso": "string" } ``` ### Skill Schema: ```json { "type": "object", "properties": { "name": { "type": "string", "description": "Nome." }, "content": { "type": "string", "description": "Conteúdo." }, "version": { "type": "integer", "description": "Versão." }, "updated_at": { "anyOf": [ { "type": "string", "description": "Atualização ISO.", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "name", "content", "version" ], "description": "Conteúdo versionado de uma skill publicada no backend." } ``` Example: ```json { "name": "string", "content": "string", "version": 0 } ``` ### StoredMedia Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "url": { "type": "string", "description": "URL pública.", "format": "uri" }, "storage_path": { "type": "string", "description": "Caminho interno sem credenciais." } }, "required": [ "id", "url", "storage_path" ], "description": "Resultado de mídia gerada e armazenada pelo Hermes." } ``` Example: ```json { "id": "string", "url": "https://socialmedia.janvalellam.com.br/resource", "storage_path": "string" } ``` ### UploadedMedia Schema: ```json { "type": "object", "properties": { "id": { "type": "string", "description": "ID." }, "url": { "type": "string", "description": "URL pública.", "format": "uri" }, "kind": { "type": "string", "description": "Tipo lógico." }, "bytes": { "type": "integer", "description": "Tamanho recebido.", "minimum": 1 } }, "required": [ "id", "url", "kind", "bytes" ], "description": "Resultado de um upload binário concluído." } ``` Example: ```json { "id": "string", "url": "https://socialmedia.janvalellam.com.br/resource", "kind": "string", "bytes": 1 } ```