# Referencia da API Neotask

Referencia completa da API para a plataforma Neotask. Este documento cobre todos os endpoints disponiveis, metodos de autenticacao, tratamento de erros e limites de taxa.

---

## Autenticacao

Todas as requisicoes de API requerem autenticacao via um dos seguintes metodos:

- **Bearer JWT**: Passe o cabecalho `Authorization: Bearer <token>`. Tokens sao obtidos dos endpoints de login descritos abaixo.
- **License HMAC**: Assinatura HMAC-SHA256 vinculada ao dispositivo usada pelo aplicativo desktop do Neotask. O cliente assina requisicoes com um segredo derivado da chave de licenca e impressao digital do dispositivo.
- **Cabecalho de Tenant**: Inclua `x-tenant-id: <tenantId>` para qualquer endpoint com escopo de tenant. Este cabecalho identifica a qual tenant (workspace) a requisicao se aplica.

Muitos endpoints combinam multiplos requisitos de autenticacao. Por exemplo, "Tenant + Admin" significa que a requisicao deve incluir tanto um JWT valido (pertencente a um usuario com a funcao Admin) quanto o cabecalho `x-tenant-id`.

---

## Endpoints de Autenticacao

Endpoints para autenticacao de usuarios em plataformas web, iOS e desktop.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| POST | `/api/auth/login` | Autenticar com email e senha. Retorna um JWT em caso de sucesso. | Nenhuma |
| POST | `/api/auth/google` | Autenticar via Google OAuth na web. Espera um codigo de autorizacao Google. | Nenhuma |
| POST | `/api/auth/google-ios` | Autenticar via Google OAuth no iOS. Espera um payload de autorizacao especifico do iOS. | Nenhuma |
| POST | `/api/auth/google-token` | Verificar um token de acesso Google e retornar um JWT do Neotask. | Nenhuma |
| POST | `/api/auth/apple` | Autenticar via Apple Sign-In. Espera um token de identidade Apple. | Nenhuma |
| GET | `/api/auth/me` | Retornar o perfil do usuario autenticado (nome, email, avatar, funcoes). | JWT |
| DELETE | `/api/auth/account` | Excluir permanentemente a conta do usuario autenticado e todos os dados associados. | JWT |

---

## Endpoints de Autenticacao do Painel

Endpoints de autenticacao especificos para o painel do Neotask, incluindo login por chave de licenca e autenticacao de dois fatores (TOTP).

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| POST | `/api/dashboard/auth/login` | Autenticar com uma chave de licenca. Retorna um JWT em caso de sucesso, ou sinaliza que TOTP e necessario. | Nenhuma |
| POST | `/api/dashboard/auth/totp-login` | Completar login fornecendo um codigo TOTP ou codigo de backup quando a autenticacao de dois fatores esta ativada. | Nenhuma |
| GET | `/api/dashboard/auth/me` | Retornar as informacoes de licenca atuais e direitos de recursos para o usuario do painel autenticado. | JWT |
| POST | `/api/dashboard/totp/setup` | Gerar um segredo TOTP e codigo QR para configurar a autenticacao de dois fatores. | JWT |
| POST | `/api/dashboard/totp/verify` | Verificar um codigo TOTP para confirmar e ativar a autenticacao de dois fatores na conta. | JWT |

---

## Endpoints de Cobranca

Gerenciar assinaturas, sessoes de checkout e compras in-app pelo Stripe e RevenueCat.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| POST | `/api/billing/checkout` | Criar uma sessao Stripe Checkout para o plano Pro. Retorna uma URL de checkout. | Tenant + Admin |
| POST | `/api/billing/checkout/enterprise` | Criar uma sessao Stripe Checkout para o plano Enterprise. Retorna uma URL de checkout. | Tenant + Admin |
| GET | `/api/billing/status` | Retornar o plano atual, contagem de mensagens e limites de uso para o tenant. | Tenant + Viewer |
| POST | `/api/billing/portal` | Criar uma sessao do Portal do Cliente Stripe para gerenciar metodos de pagamento e faturas. | Tenant + Admin |
| POST | `/api/billing/agent-addon` | Comprar um slot adicional de agente add-on para o tenant. | Tenant + Admin |
| POST | `/api/billing/webhook` | Handler de webhook Stripe. Valida a assinatura Stripe e processa eventos do ciclo de vida da assinatura. | Stripe Signature |
| POST | `/api/billing/revenuecat-sync` | Verificar uma compra in-app do iOS via RevenueCat e sincronizar direitos ao tenant. | Tenant + Admin |
| POST | `/api/billing/revenuecat-webhook` | Handler de webhook RevenueCat. Processa eventos de assinatura originados da App Store. | Bearer |

---

## Endpoints de Chat

Enviar e receber mensagens, gerenciar sessoes e consultar resultados de trabalhos assincronos.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| POST | `/api/chat/init` | Auto-provisionar um tenant, agente e sessao para o usuario autenticado. Use isso para inicializar o ambiente de chat de um novo usuario em uma unica chamada. | JWT |
| POST | `/api/chat/send` | Enviar uma mensagem ao agente. A mensagem e processada de forma assincrona; um ID de trabalho e retornado imediatamente. | Tenant + Admin |
| GET | `/api/chat/jobs/:jobId` | Consultar o status e resultado de um trabalho de chat assincrono pelo seu ID. | Tenant + Viewer |
| GET | `/api/chat/messages` | Buscar todas as mensagens de uma sessao. Passe o ID da sessao como parametro de consulta. | Tenant + Viewer |
| GET | `/api/chat/sessions` | Listar todas as sessoes de chat do tenant. | Tenant + Viewer |
| POST | `/api/chat/sessions` | Criar uma nova sessao de chat. | Tenant + Admin |

---

## Endpoints de Agentes e Atividades

Navegar por agentes, sessoes, ferramentas, arquivos, skills, canais, trabalhos agendados e equipes associados ao tenant.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| GET | `/api/activity/agents` | Listar todos os agentes pertencentes ao tenant. | Tenant |
| GET | `/api/activity/sessions` | Listar sessoes. Suporta filtragem por `agentId`, `status` e parametros de intervalo de datas. | Tenant |
| GET | `/api/activity/sessions/:id/entries` | Obter todas as entradas (mensagens e eventos) de uma sessao especifica. | Tenant |
| GET | `/api/activity/tools` | Listar todas as ferramentas disponiveis para os agentes do tenant. | Tenant |
| GET | `/api/activity/files` | Listar todos os arquivos associados aos agentes do tenant. | Tenant |
| GET | `/api/activity/skills` | Listar todas as skills associadas aos agentes do tenant. | Tenant |
| GET | `/api/activity/channels` | Listar todos os canais associados aos agentes do tenant. | Tenant |
| GET | `/api/activity/cron-jobs` | Listar todos os trabalhos agendados (cron) do tenant. | Tenant |
| GET | `/api/activity/teams` | Listar todas as equipes dentro do tenant. | Tenant |

---

## Endpoints de Skills

Gerenciar o catalogo de skills, instalar e configurar skills, e publicar skills personalizadas.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| GET | `/api/skills/catalog` | Navegar pelo catalogo completo de skills. Retorna todas as skills publicadas disponiveis para instalacao. | Tenant |
| GET | `/api/skills/list` | Listar as skills atualmente instaladas pelo usuario. | Tenant + Viewer |
| POST | `/api/skills/sync` | Sincronizar skills do sistema de arquivos. Use isso apos implantar novos arquivos de skill para atualizar o registro. | Tenant + Admin |
| POST | `/api/skills/register` | Registrar (instalar) uma skill do catalogo. | Tenant + Viewer |
| DELETE | `/api/skills/register/:skillId` | Desregistrar (desinstalar) uma skill pelo seu ID. | Tenant + Viewer |
| POST | `/api/skills/:skillId/publish` | Publicar uma skill para torna-la disponivel no catalogo. | Tenant + Admin |
| POST | `/api/skills/:skillId/unpublish` | Despublicar uma skill, removendo-a do catalogo. | Tenant + Admin |
| GET | `/api/skills/all` | Listar todas as skills incluindo as nao publicadas. Endpoint somente para admin para gerenciamento de skills. | Tenant + Admin |
| PUT | `/api/skills/:skillId/env-schema` | Definir ou atualizar o esquema de variaveis de ambiente de uma skill. Isso controla quais campos de configuracao sao apresentados aos usuarios. | Tenant + Admin |
| POST | `/api/skills/:skillId/configure` | Salvar valores de configuracao para uma skill instalada. | Tenant + Viewer |
| DELETE | `/api/skills/:skillId/configure` | Remover toda configuracao de uma skill, redefinindo para padroes. | Tenant + Viewer |

---

## Endpoints de Canais

Vincular, configurar, ativar e desconectar canais de mensagens (ex.: Slack, Discord, WhatsApp).

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| GET | `/api/channels/` | Listar todos os canais e seus status atuais. | Tenant + Viewer |
| GET | `/api/channels/:channel/status` | Obter o status detalhado de um canal especifico. | Tenant + Viewer |
| POST | `/api/channels/:channel/link` | Iniciar o processo de vinculacao de um canal. Retorna uma URL de link ou token de sessao dependendo do tipo de canal. | Tenant + Admin |
| GET | `/api/channels/:channel/link/wait` | Long-poll para a conclusao de um fluxo de vinculacao de canal. Retorna quando o canal e vinculado com sucesso ou a operacao expira. | Tenant + Admin |
| GET | `/api/channels/:channel/jobs/:jobId` | Obter o resultado de um trabalho assincrono especifico do canal. | Tenant + Admin |
| POST | `/api/channels/:channel/enable` | Ativar um canal vinculado para que o agente comece a receber mensagens dele. | Tenant + Admin |
| POST | `/api/channels/:channel/disable` | Desativar um canal sem desvincular-lo. O agente para de receber mensagens, mas a conexao do canal e preservada. | Tenant + Admin |
| POST | `/api/channels/:channel/disconnect` | Desconectar e desvincular completamente um canal. | Tenant + Admin |
| GET | `/api/channels/:channel/config` | Obter a configuracao atual de um canal. | Tenant + Admin |
| POST | `/api/channels/:channel/config` | Atualizar a configuracao de um canal. | Tenant + Admin |

---

## Endpoints Google OAuth

Iniciar e gerenciar fluxos Google OAuth para conectar servicos Google ao Neotask.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| GET/POST | `/oauth/google/start` | Iniciar um fluxo Google OAuth. Aceita parametros opcionais para especificar quais servicos Google solicitar acesso. | Opcional |
| GET | `/oauth/google/services` | Listar todas as definicoes de servicos Google suportadas pelo Neotask, agrupadas por categoria. | Nenhuma |
| GET | `/oauth/google/callback` | Handler de callback OAuth. O Google redireciona aqui apos o usuario conceder ou negar acesso. | Nenhuma |
| GET | `/oauth/google/status` | Consultar o status de um fluxo OAuth em andamento. Retorna se o fluxo esta pendente, concluido ou falhou. | Nenhuma |

### Servicos Google Disponiveis

O Neotask suporta conexao com 25 servicos Google, organizados por categoria:

| Categoria | Servicos |
|-----------|----------|
| **Core** | Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Keep, Tasks |
| **Comunicacao** | People/Contacts, Chat, Meet, YouTube, Photos |
| **Localizacao** | Places API, Routes/Directions, Business Profile |
| **Especializados** | Classroom, Play Developer, AdSense, Google Ads |

---

## Endpoints de Chaves de Provedor

Gerenciar chaves de API de terceiros (ex.: para provedores de LLM). As chaves sao criptografadas em repouso e podem ser resolvidas (descriptografadas) sob demanda.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| PUT | `/api/provider-keys/:provider` | Salvar ou atualizar uma chave de API para o provedor especificado. A chave e criptografada antes do armazenamento. | HMAC + Auth |
| GET | `/api/provider-keys/` | Listar todas as chaves de provedor salvas. Valores das chaves sao mascarados (apenas os ultimos quatro caracteres sao mostrados). | Auth |
| DELETE | `/api/provider-keys/:provider` | Remover uma chave de API salva para o provedor especificado. | HMAC + Auth |
| GET | `/api/provider-keys/:provider/resolve` | Descriptografar e retornar a chave de API completa para o provedor especificado. | Auth |
| GET | `/api/provider-keys/mode` | Obter o modo de chave atual (fornecido pelo usuario vs. creditos da plataforma) e o saldo de creditos restante. | Auth |

### Provedores Permitidos

O parametro de caminho `:provider` deve ser um dos seguintes valores:

- `anthropic`
- `openai`
- `openai-codex`
- `openrouter`
- `google-ai`

---

## Endpoints de Uso

Rastrear uso, consultar analytics, monitorar gastos e gerenciar orcamentos.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| POST | `/api/usage/ingest` | Ingerir um registro de dados de uso (ex.: contagens de tokens, modelo usado). | Auth |
| GET | `/api/usage/query` | Consultar analytics de uso com filtros flexiveis (intervalo de datas, modelo, agente). | Auth |
| GET | `/api/usage/summary` | Obter um resumo de uso para um periodo. Passe `period` como parametro de consulta (ex.: `day`, `week`, `month`). | Auth |
| GET | `/api/usage/analytics` | Recuperar analytics detalhados de uso incluindo discriminacoes por modelo e agente. | Auth |
| GET | `/api/usage/spending` | Obter dados de gastos para um periodo. Passe `period` como parametro de consulta. | Auth |
| GET | `/api/usage/budget` | Obter informacoes de orcamento incluindo o limite total, valor usado e valor restante. | Auth |
| POST | `/api/usage/cron-runs` | Registrar a execucao de um trabalho agendado (cron) para rastreamento de uso. | Auth |
| POST | `/api/usage/budget-snapshot` | Capturar um snapshot pontual do estado atual do orcamento. | Auth |

---

## Endpoints de Onboarding

Guiar novos usuarios pela configuracao inicial, incluindo selecao de provedor de modelo e configuracao de chave de API.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| POST | `/api/onboarding/init` | Inicializar a configuracao de onboarding para o usuario autenticado. Cria configuracoes padrao e retorna o estado de onboarding. | JWT |
| GET | `/api/onboarding/models` | Listar provedores de modelos disponiveis e seus modelos suportados. Este endpoint e publico e nao requer autenticacao. | Nenhuma |
| POST | `/api/onboarding/setup` | Configurar uma chave de API de provedor durante o onboarding. Valida a chave antes de salvar. | Tenant + Admin |
| POST | `/api/onboarding/complete` | Marcar o onboarding como completo para o usuario atual. | Dashboard Auth |

---

## Endpoints de Tenant

Criar e gerenciar tenants (workspaces), armazenar segredos criptografados e criar sessoes e trabalhos diretamente.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| POST | `/api/tenants/` | Criar um novo tenant (workspace). Retorna o ID do tenant e configuracoes padrao. | JWT |
| GET | `/api/tenants/:tenantId` | Obter detalhes de um tenant especifico, incluindo configuracoes e contagem de membros. | JWT |
| POST | `/api/tenants/secrets` | Armazenar um segredo criptografado associado ao tenant. Usado para integracoes de servicos. | Tenant + Admin |
| POST | `/api/tenants/sessions` | Criar uma nova sessao dentro do tenant. | Tenant + Admin |
| POST | `/api/tenants/jobs` | Criar um novo trabalho assincrono dentro do tenant. | Tenant + Admin |

---

## Endpoints de Memoria

Gerenciar configuracao de memoria do agente, arquivos e conteudo. A memoria permite que agentes persistam informacoes entre sessoes.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| GET | `/api/memory/config` | Buscar a configuracao de memoria atual (estado ativado, politica de retencao, limites). | Auth |
| POST | `/api/memory/config` | Atualizar configuracoes de memoria como periodo de retencao e limites de armazenamento. | Auth |
| GET | `/api/memory/files` | Listar todos os arquivos de memoria armazenados para o agente. | Auth |
| GET | `/api/memory/files/:filename` | Recuperar o conteudo de um arquivo de memoria especifico pelo nome. | Auth |
| DELETE | `/api/memory/files/:filename` | Excluir um arquivo de memoria especifico pelo nome. | Auth |
| GET | `/api/memory/content` | Recuperar conteudo de memoria armazenado. | Auth |
| POST | `/api/memory/content` | Armazenar novo conteudo de memoria para o agente. | Auth |

---

## Endpoints de Contas Google

Gerenciar contas Google que foram conectadas ao Neotask via OAuth.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| GET | `/api/google-accounts/` | Listar todas as contas Google conectadas com seus escopos de servico e status. | Auth |
| POST | `/api/google-accounts/:accountId/activate` | Ativar uma conta Google conectada, permitindo que o agente use seus servicos autorizados. | Auth |
| DELETE | `/api/google-accounts/:accountId` | Remover uma conta Google conectada e revogar seus tokens armazenados. | Auth |

---

## Endpoints de Contato e Suporte

Enviar e gerenciar solicitacoes de contato de suporte.

| Metodo | Endpoint | Descricao | Autenticacao |
|--------|----------|-----------|--------------|
| POST | `/api/contact/` | Enviar uma mensagem do formulario de contato. Limitado a 5 requisicoes por 15 minutos por endereco IP. | Nenhuma |
| GET | `/api/contacts/` | Listar todos os envios de contato com suporte a paginacao. Somente admin. | Admin |
| PATCH | `/api/contacts/:id` | Atualizar o status de um envio de contato (ex.: marcar como resolvido). | Admin |
| DELETE | `/api/contacts/:id` | Excluir um envio de contato. | Admin |

---

## Limites de Taxa

O Neotask aplica limites de taxa em certos endpoints para proteger a estabilidade do servico. Quando um limite de taxa e excedido, a API retorna uma resposta `429 Too Many Requests`.

| Categoria de Endpoint | Limite |
|-----------------------|--------|
| Formulario de contato | 5 requisicoes por 15 minutos por IP |
| Tentativas de login | 10 requisicoes por 15 minutos por IP |
| Rastreamento/analytics | 30 requisicoes por 60 segundos por IP |

---

## Respostas de Erro

Todas as respostas de erro seguem um formato JSON consistente:

```json
{
  "error": "Descricao da mensagem de erro",
  "status": 400
}
```

### Codigos de Status

| Codigo | Significado |
|--------|-------------|
| 400 | **Bad Request** -- A requisicao estava malformada ou continha parametros invalidos. |
| 401 | **Unauthorized** -- Autenticacao esta faltando ou o token fornecido e invalido. |
| 402 | **Payment Required** -- Os creditos do tenant foram esgotados. Faca upgrade do seu plano ou adicione creditos para continuar. |
| 403 | **Forbidden** -- O usuario autenticado nao tem permissoes suficientes para esta acao. |
| 404 | **Not Found** -- O recurso solicitado nao existe. |
| 429 | **Rate Limited** -- Muitas requisicoes. Aguarde e tente novamente apos o periodo indicado nos cabecalhos da resposta. |
| 500 | **Internal Server Error** -- Um erro inesperado ocorreu no servidor. Se isso persistir, entre em contato com o suporte do Neotask. |