diff --git a/Acesso-Externo-e-Integracao.md b/Acesso-Externo-e-Integracao.md new file mode 100644 index 0000000..0659a63 --- /dev/null +++ b/Acesso-Externo-e-Integracao.md @@ -0,0 +1,52 @@ +# Guia de Acesso Externo e Integração de Dados + +Este documento descreve como consumir os dados do projeto **apitdn** a partir de qualquer localidade, utilizando a infraestrutura de VPN Mesh (Tailscale) e as interfaces do Gitea. + +## 🌐 1. Infraestrutura de Conexão (Tailscale) +Para acessar o Gitea fora da rede local (192.168.x.x), você deve utilizar o IP atribuído pelo Tailscale ao Raspberry Pi. + +* **Pré-requisito**: A máquina cliente deve estar logada na mesma rede Tailscale. +* **IP do Servidor (Exemplo)**: Substitua `192.168.0.63` pelo IP `100.x.x.x` do seu Raspberry Pi no painel do Tailscale. + +## 🛠️ 2. Métodos de Consumo de Dados + +### A. Clonagem via Git (Ideal para Sincronização) +Recomendado para baixar toda a base de documentação (~640MB) para processamento local. +```bash +git clone http://[IP-TAILSCALE]:3000/rodolpho/apitdn.git +``` + +### B. Download de Snapshot (ZIP) +Ideal para obter uma cópia rápida sem histórico de versões. +* **URL**: `http://[IP-TAILSCALE]:3000/rodolpho/apitdn/archive/master.zip` + +### C. Acesso Raw (Arquivos Individuais) +Para leitura direta de um arquivo Markdown específico. +* **URL**: `http://[IP-TAILSCALE]:3000/rodolpho/apitdn/raw/branch/master/[CAMINHO_DO_ARQUIVO].md` + +## 🤖 3. Integração com LLMs Externas (RAG) +Se você estiver conectando uma LLM externa (ex: OpenAI, Anthropic) ou um agente de IA à sua rede privada via Tailscale, siga este protocolo: + +### Passo 1: Gerar Token de Acesso (PAT) +Em vez de usar sua senha, gere um token em: +`Configurações > Aplicativos > Gerar Novo Token` + +### Passo 2: Consumo via API REST +A LLM ou o Agente deve realizar requisições autenticadas para buscar o conteúdo dos arquivos: + +**Endpoint de Conteúdo:** +`GET /api/v1/repos/rodolpho/apitdn/contents/[CAMINHO]` + +**Exemplo de Header:** +```http +Authorization: token [SEU_TOKEN_PAT] +Accept: application/json +``` + +### Passo 3: Decodificação +A API retornará o conteúdo em **Base64**. O agente deve decodificar a string para obter o Markdown puro para processamento de contexto. + +## 🔒 Segurança +* Mantenha o Tailscale ativo no Raspberry Pi. +* Nunca exponha a porta 3000 diretamente no roteador sem VPN. +* Sempre prefira Tokens de Acesso Pessoal (PAT) com escopo limitado para integrações externas.