Dados do Tesouro Direto automaticamente no Ghostfolio 🇧🇷👻

Um script em Python dockerizado que sincroniza automaticamente os preços e históricos do Tesouro Direto (via Tesouro Transparente/CKAN) diretamente para a sua instância do Ghostfolio.

Como o Ghostfolio não suporta ativos brasileiros sem ticker internacional de forma nativa, este script automatiza a atualização de preços baseada na marcação a mercado oficial do Governo Federal, dispensando o uso de APIs pagas.

🚀 Como funciona?

Ao iniciar o container, o script executa uma sincronização imediata. Depois disso, ele fica rodando silenciosamente em background através de um agendador (cron do Linux), executando as atualizações de segunda a sexta-feira (após o fechamento do mercado). Durante a execução, ele:

1. Conecta-se à sua instância do Ghostfolio e autentica via API.
2. Procura ativos manuais que tenham um padrão específico no campo Symbol (ou definidos via arquivo de mapeamento).
3. Busca a URL dinâmica e baixa a planilha oficial atualizada do Tesouro Direto.
4. Processa os dados de compra e traduz as nomenclaturas.
5. Envia o histórico limpo para o Ghostfolio.
6. Notifica o usuário em caso de erros (se configurado).

---

⚙️ Configurando no Ghostfolio

Para que o script saiba quais títulos atualizar, você deve criar os ativos manualmente no Ghostfolio seguindo um padrão rígido de nomenclatura no campo Symbol. Como o Ghostfolio não aceita espaços ou caracteres especiais, usamos pontos e traços:

Formato exigido: TD.TIPO_DO_TITULO.DD-MM-YYYY

(Nota: O Ghostfolio adicionará automaticamente o prefixo GF_ ao salvar. Não se preocupe, o script lida com isso automaticamente).

Passo a passo:

1. Vá em Admin > Market Data no seu Ghostfolio.
2. Adicione um novo ativo com Data Source: MANUAL.
3. Defina a classe (BOND) e a moeda (BRL).
4. No campo Symbol, insira a string no formato exigido. Para espaços no nome do título, use o underline (_).

Exemplos reais:

• Tesouro Selic 2027: TD.LFT.01-03-2027
• Tesouro IPCA+ 2045: TD.NTN-B_Principal.15-05-2045

Tabela de Tipos de Títulos:

• Tesouro Selic = LFT
• Tesouro IPCA+ = NTN-B_Principal
• Tesouro IPCA+ com Juros Semestrais = NTN-B
• Tesouro Prefixado = LTN
• Tesouro Prefixado com Juros Semestrais = NTN-F

---

🔄 Mantendo Ativos Antigos (mapping.json)

Se você já possui ativos do Tesouro Direto cadastrados manualmente no seu Ghostfolio com nomes próprios (ex: GF_Minha_Reserva), você não precisa deletá-los e perder seu histórico de transações!

Basta criar um arquivo chamado mapping.json na mesma pasta do seu docker-compose.yml e mapear o seu nome antigo para a estrutura lógica do script.

Exemplo de mapping.json:

{
  "GF_Meu_Tesouro_IPCA": "TD.NTN-B_Principal.15-05-2045",
  "GF_Reserva_Emergencia": "TD.LFT.01-03-2027"
}

---

🔔 Notificações (Opcional)

Para não falhar silenciosamente, o script pode te alertar em tempo real caso encontre algum erro de conexão, mudança na API do governo ou falhas de configuração.

Atualmente suportamos nativamente os seguintes serviços (basta adicionar as variáveis correspondentes no seu docker-compose.yml):

• Webhooks (Discord / Slack): Preencha a variável WEBHOOK_URL.
• Telegram: Preencha as variáveis TELEGRAM_TOKEN e TELEGRAM_CHAT_ID.
• ntfy (ntfy.sh ou self-hosted): Preencha NTFY_URL e, se sua instância for protegida, NTFY_TOKEN.

---

🐳 Instalação (Docker Compose)

Você pode rodar este sincronizador junto com a sua stack do Ghostfolio (ou separadamente) usando o docker-compose.yml.

1. Pegue a URL do seu Ghostfolio e seu token de acesso (Account > Security > Security Token).
2. Crie a pasta data_cache e o arquivo mapping.json (opcional).
3. Use o arquivo docker-compose.yml abaixo:

version: '3.8'

services:
  tesouro-ghostfolio:
    image: ghcr.io/fkupper/ghostfolio-tesouro-sync:latest
    container_name: tesouro-ghostfolio-sync
    restart: unless-stopped
    environment:
      - GHOSTFOLIO_URL=http://seu-ip-ou-dominio:3333
      - GHOSTFOLIO_TOKEN=seu_security_token_de_acesso
      - TZ=America/Sao_Paulo
      
      # --- NOTIFICAÇÕES (Descomente o que for usar) ---
      # - WEBHOOK_URL=[https://discord.com/api/webhooks/](https://discord.com/api/webhooks/)...
      # - TELEGRAM_TOKEN=seu_token_do_bot
      # - TELEGRAM_CHAT_ID=seu_chat_id
      # - NTFY_URL=[https://ntfy.sh/seu_topico_secreto](https://ntfy.sh/seu_topico_secreto)
      # - NTFY_TOKEN=seu_token_de_acesso (se self-hosted protegido)
      
    #volumes:
      # Opcional: cache local para evitar baixar os arquivos do tesouro repetidas vezes
      # - ./data_cache:/app/cache
      # Opcional: Arquivo para vincular nomes customizados existentes ao padrão do script
      # - ./mapping.json:/app/mapping.json

4. Execute o container:

docker compose up -d

Pronto! Ele fará a primeira sincronização na hora e depois agendará as próximas atualizações noturnas automaticamente.