Simples Agenda Download

Simples Agenda Download Automation Skill

Overview

This skill automates the download of appointment schedules from Simples Agenda, a Brazilian scheduling and financial management system. Instead of manually logging in, navigating to filters, and exporting the file, users can simply request the skill to download appointments for a specific period with optional filters.

Key point: This is a wrapper/integrator skill — it does NOT recreate the download functionality. It calls the same endpoints that the agendamento.php screen calls (crud.php com acao=exporta_agendamentos) and automates the process.

What This Skill Does

1. Authenticates with Simples Agenda (login/password)
2. Applies filters to the native export function:
   • Mandatory: Date range (dd/mm/yyyy format)
   • Optional: Professional(s), Service(s), Client(s)
3. Downloads the Excel file generated by Simples Agenda
4. Saves to the user's Downloads folder with timestamp to avoid overwrites
5. Validates the downloaded file and confirms success to the user

Flow

User defines parameters (periodo + filtros opcionais)
    ↓
GET  autenticacao_usuario.php      -> cookie PHPSESSID
    ↓
POST crud_autenticacao.php         -> acao=autentica_usuario
    ↓                                 (UsuarioSA / SenhaSA)
POST crud.php                      -> acao=exporta_agendamentos
    ↓                                 <nome_excel>caminho</nome_excel>
GET  <nome_excel>                  -> .xls binario
    ↓
Skill valida magic bytes & salva em Downloads/
    ↓
Sincroniza no MySQL e gera planilha ordenada (import-db-agenda)
    ↓
Envia a planilha por email (email-sender)
    ↓
User receives confirmation message

How to Use

When the user asks to download or export appointment data from Simples Agenda, follow these steps:

1. Gather Parameters

Collect from the user:

Required:

• Email (Simples Agenda login) — e-mail de acesso ao sistema

Optional (com defaults automáticos):

• Start Date (Data Início) — in dd/mm/yyyy format

  • Example: "01/01/2024"
  • DEFAULT se omitido: hoje - 7 dias
  • Validation: Reject other formats (mm/dd/yyyy, yyyy-mm-dd, text, etc.)

• End Date (Data Fim) — in dd/mm/yyyy format

  • Example: "31/01/2024"
  • DEFAULT se omitido: hoje - 1 dia
  • Validation: Must be >= Start Date

Outros opcionais:

• Professionals — select one or more (IDs or names, depending on what Simples Agenda returns)
• Services — select one or more
• Clients — select one or more
• EnviarPara (Melhoria #3) — email(s) de destino (destinatários) da planilha ordenada final, separados por vírgula. O remetente NÃO é este parâmetro: é a conta configurada na skill email-sender para o serviço simples-agenda (ver seção 8). Todo destinatário precisa estar na allowlist daquele serviço. Default: amazonasterapiafisio@gmail.com (não é preciso perguntar ao usuário se ele não mencionar email).
• NaoEnviarEmail — se o usuário pedir explicitamente para não enviar email, pule o envio (ver seção 8).

Comportamento com defaults:

Se o usuário não informar -DataIni e -DataFim, o script usa automaticamente:

• DataIni = hoje - 7 dias
• DataFim = hoje - 1 dia

Isso permite executar sem datas: .\baixar_agenda.ps1 -Email seu@email.com busca os últimos 7 dias.

2. Validate Inputs

Before proceeding:

Date Format Validation:

• ✓ Date format is strictly dd/mm/yyyy
• ✗ Reject formats like: 01-01-2024, 2024/01/01, 1/1/2024, "January 2024"
• ✗ Reject invalid dates like: 01/13/2024 (no month 13), 32/01/2024 (no day 32)

Date Range Validation:

• ✗ Reject: Data Início > Hoje (não pode pedir data futura)
  • Example: "Hoje: 02/01/2024, Data Início: 03/01/2024" → REJEITAR
• ✗ Reject: Data Fim > Hoje (não pode pedir data futura)
  • Example: "Hoje: 02/01/2024, Data Fim: 31/01/2024" → REJEITAR
• ✓ Accept: Data Início ≤ Hoje (pode ser hoje ou passado)
  • Example: "Hoje: 02/01/2024, Data Início: 02/01/2024" → ACEITAR
  • Example: "Hoje: 02/01/2024, Data Início: 01/01/2024" → ACEITAR
• ✓ Accept: Data Fim ≤ Hoje (pode ser hoje ou passado)
  • Example: "Hoje: 02/01/2024, Data Fim: 02/01/2024" → ACEITAR
  • Example: "Hoje: 02/01/2024, Data Fim: 25/12/2023" → ACEITAR
• ✗ Reject: Data Fim < Data Início (range invertido)
  • Example: "Data Início: 31/01/2024, Data Fim: 01/01/2024" → REJEITAR
• ✓ Accept: Data Fim ≥ Data Início (mesmo dia é válido)
  • Example: "Data Início: 02/01/2024, Data Fim: 02/01/2024" → ACEITAR

If validation fails, inform the user with the exact issue: "Invalid format. Use dd/mm/yyyy (example: 01/01/2024)" or "Data Início não pode ser no futuro" or "Data Fim deve ser >= Data Início"

3. Authenticate (Melhoria #1 — implementada)

Credenciais NAO sao geridas por esta skill diretamente: ela chama a skill separada credential-manager (../credential-manager), que guarda a senha de forma criptografada no cofre do SO (DPAPI no Windows via credential_manager.ps1).

1. 1a execucao: usuario informa email + senha. A senha e usada E salva automaticamente via credential-manager — nao ha flag extra para lembrar.
2. Proximas execucoes: basta informar o email (+ periodo). A senha e carregada sozinha do credential-manager; o usuario nao digita nada.
3. Logout: -Logout remove a senha salva para aquele email.
4. Se a senha carregada estiver errada (credenciais mudaram no site), a autenticacao falha com AUTH_FAILED normalmente — o usuario deve rodar de novo informando a senha nova, que substitui a antiga no cofre.

Chamada interna: baixar_agenda.ps1 invoca ..\..\credential-manager\scripts\credential_manager.ps1 diretamente (splatting via hashtable).

Validado (testes reais nesta maquina, 01/09/2026): salvar, carregar automaticamente, isolar por service_name, e logout — todos via credential_manager.ps1 (ver credential-manager/SKILL.md).

4. Login, Export, Download

Step 5a: Login — HTTP puro, sem navegador

Sao duas chamadas:

GET  https://www.simplesagenda.com.br/autenticacao_usuario.php
     -> so para obter o cookie PHPSESSID inicial

POST https://www.simplesagenda.com.br/crud_autenticacao.php
  acao=autentica_usuario
  login=<email>          <-- e "login", NAO "email"
  senha=<senha>
  conectado=1
  captcha_resposta=      (vazio quando nao ha captcha)

Resposta XML:

<data>
  <endereco>agendamento.php</endereco>
  <mostraToast>N</mostraToast>
  <houve_erro>N</houve_erro>
</data>

houve_erro == "N" = sucesso; so entao os cookies UsuarioSA e SenhaSA sao definidos. Em falha vem <mensagem> (com HTML embutido, limpe antes de exibir) e, as vezes, <requer_captcha>S</requer_captcha> + <captcha_pergunta>.

NAO faca POST de login em autenticacao_usuario.php. Aquele endpoint responde HTTP 200, define apenas PHPSESSID e nao autentica. Era por causa desse engano que a versao antiga da skill precisava de Selenium/Chrome. O endpoint correto esta declarado em assets/pages/scripts/login.js (crudPadrao: "crud_autenticacao.php", acao: "autentica_usuario").

Atencao: /index.php redireciona para /site/index.php, que e a pagina de marketing com um formulario de cadastro ("Experimente Gratis") — nao e login. A pagina de login e autenticacao_usuario.php.

O campo captcha_resposta fica oculto (display:none) em condicoes normais, mas o servidor pode exigi-lo apos erros de senha. Se requer_captcha == "S", ABORTAR e pedir login manual — nunca tentar resolver.

Step 5b: Export Request (POST)

POST https://www.simplesagenda.com.br/crud.php

  acao=exporta_agendamentos    <-- acao correta para gerar o Excel
  dataIni=04/08/2026           (dd/mm/yyyy)
  dataFim=31/08/2026           (dd/mm/yyyy)
  cod_usuario_array=           (opcional: IDs de profissionais, separados por virgula)
  cod_cliente=                 (opcional)
  cod_produto=                 (opcional: ID do servico)

Resposta: XML contendo o caminho real do arquivo:

<nome_excel>excel/excel71400/Agendamentos_DDMMYYYYHHMMSS.xls</nome_excel>

acao=filtraResumido apenas renderiza a tabela na tela e NAO gera Excel. Nunca adivinhe o nome do arquivo — leia sempre <nome_excel> da resposta.

Step 5c: Download (GET)

GET https://www.simplesagenda.com.br/<nome_excel>

Retorna: arquivo .xls binario (OLE2, magic D0CF11E0A1B11AE1).

5. Validate and Save the File

When Simples Agenda returns the .xls file:

1. Validate file integrity:

   • Check file extension: .xls
   • Verify magic bytes (should start with D0CF11E0 for .xls format)
   • File size > 0 bytes

2. Naming:

   • Preserve original filename from Simples Agenda + add timestamp
   • Pattern: agenda_[original]_YYYYMMDD_HHMMSS.xls
   • Example: agenda_2024_20240115_143025.xls

3. Handle conflicts:

   • If file already exists, append numeric suffix
   • Example: agenda_2024_20240115_143025_1.xls

4. Save location:

   • Windows: C:\Users\[username]\Downloads\
   • macOS: /Users/[username]/Downloads/
   • Linux: /home/[username]/Downloads/

6. Confirm to User

On success:

✓ "Arquivo 'agenda_2024_20240115_143025.xls' baixado com sucesso em C:\Users\[username]\Downloads"

On error:

• "Falha de conexão. Verifique sua internet e tente novamente."
• "Credenciais inválidas. Verifique login e senha."
• "Nenhum agendamento encontrado para: 01/01/2024 até 31/01/2024"
• "Erro ao processar resposta do servidor. Contate suporte."

7. Sync com Banco e Planilha Ordenada (Melhoria #2 — delegada à skill import-db-agenda)

Depois do download do .xls original, baixar_agenda.ps1 chama a skill import-db-agenda para:

1. Validar (init-schema) que a tabela sbx990 e as referências (empresa/filial) existem no MySQL, criando a UNIQUE KEY de dedup se ainda não existir
2. Sincronizar os agendamentos baixados nessa tabela (sync)
3. Gerar a planilha ordenada final (.xlsx) a partir do banco, na ordem pedida em -SortBy (cliente+data por padrão)

O .xls original do Simples Agenda é apagado depois que os dados estão no banco e a planilha ordenada foi gerada com sucesso — a planilha ordenada é o entregável, não o .xls bruto.

-NoSyncToDb pula só a sincronização (passo 2); a exportação ordenada (passo 3) sempre acontece a partir do que já estiver no banco. Sem a skill import-db-agenda disponível, o .xls original é mantido e a skill encerra (a planilha ordenada não pode ser gerada sem ela).

Destino (desde 07/09/2026): tabela sbx990 no banco 4clinics (localhost:3306) — sistema externo, não gerenciado por esta skill. A tabela tem colunas com nomes próprios (dataAgenda, dataAcao, executadoPor) e campos obrigatórios sem equivalente no Simples Agenda (empresaId, filialId, filialOrigemId), preenchidos com valor fixo. Ver import-db-agenda/manifest.json → schema.column_mapping e schema.fixed_identifiers para o mapeamento completo.

Parâmetros de conexão: -DbHost (127.0.0.1), -DbPort (3306), -DbUser (root), -Database (4clinics), -DbPassword (opcional — carregada do credential-manager se omitida), -EmpresaId (001), -FilialId (01), -FilialOrigemId (01).

8. Send Email (Melhoria #3 — delegada à skill email-sender)

O Passo 9 do baixar_agenda.ps1 envia a planilha ordenada por email chamando a skill email-sender. O script faz isso sozinho: não há sinalização para o orquestrador nem passo manual.

baixar_agenda.ps1  ──chama──>  email-sender/scripts/send_email.ps1
                                   -Service 'simples-agenda'
                                   -To <EnviarPara>
                                   -Subject "Agenda Ordenada: <periodo>"
                                   -Body  <periodo, ordenacao, arquivo, timestamp>
                                   -Attachment <planilha .xlsx>

Toda a segurança vive na email-sender: SMTP+TLS obrigatório, allowlist de destinatários, credencial em DPAPI sem texto plano. Esta skill não manipula senha de email nem abre conexão SMTP.

Histórico: por que não é Gmail MCP

O desenho anterior emitia linhas [EMAIL] para que o Claude Code enviasse via conector Gmail MCP. Foi abandonado por limite de tamanho no anexo. Testes em 05/09/2026 mostraram:

Uma planilha real sempre passa desse tamanho, e períodos maiores só pioram. O erro (Tool execution failed) não trazia detalhe, então não foi possível atribuir o limite ao servidor do Google, ao transporte MCP ou a timeout — mas o efeito prático era o mesmo: o anexo nunca chegava.

Remetente x destinatário

• -EnviarPara define o destinatário.
• O remetente é a conta configurada no setup da email-sender para o serviço simples-agenda. Trocar o remetente = rodar o setup daquela skill de novo.

Configuração (uma única vez)

Enquanto a email-sender não estiver configurada para o serviço simples-agenda, a planilha continua sendo gerada normalmente e o script apenas avisa como configurar (exit 0 — não é falha).

powershell -ExecutionPolicy Bypass -File .claude/skills/email-sender/scripts/send_email.ps1 -Action setup -Service simples-agenda

Allowlist: o destinatário precisa estar autorizado no serviço simples-agenda, senão o envio é bloqueado. Isso é proposital — a planilha carrega dado pessoal de pacientes, e destinatário errado é incidente de vazamento. Para autorizar:

powershell -ExecutionPolicy Bypass -File .claude/skills/email-sender/scripts/send_email.ps1 -Action add-recipient -Service simples-agenda -Recipient alguem@dominio.com

Tratamento de falha (não bloqueante)

A planilha já foi gerada quando o envio acontece. Qualquer falha de envio vira [AVISO] com instrução de correção, a planilha é preservada em Downloads e a skill encerra com exit 0. Nunca reverta nem apague a planilha por falha de email.

Se -NaoEnviarEmail for passado, o passo inteiro é pulado.

Default de destinatário: sem -EnviarPara, o script usa amazonasterapiafisio@gmail.com (ver seção 1).

Error Scenarios

Guardrails (Prevent Common Mistakes)

1. Date Format Validation

✗ Reject:  01/13/2024 (month out of range)
✗ Reject:  2024-01-01 (ISO format)
✗ Reject:  1/1/2024    (no zero-padding)
✗ Reject:  janeiro de 2024 (text format)
✓ Accept:  01/01/2024 (dd/mm/yyyy)
✓ Accept:  31/12/2024 (dd/mm/yyyy)

2. Date Range Validation

✗ Reject:  Start 31/01/2024, End 01/01/2024 (reversed / End < Start)
✗ Reject:  Today 02/01/2024, Start 03/01/2024 (Start > Today / future date)
✗ Reject:  Today 02/01/2024, Start 01/01/2024, End 31/01/2024 (End > Today / future date)
✓ Accept:  Today 02/01/2024, Start 01/01/2024, End 02/01/2024 (End <= Today)
✓ Accept:  Today 02/01/2024, Start 02/01/2024, End 02/01/2024 (today is OK)
✓ Accept:  Today 02/01/2024, Start 01/01/2024, End 25/12/2023 (all in past)

3. File Type Validation

✗ Reject:  Attempting to parse as CSV
✗ Reject:  Assuming text/plain format
✓ Accept:  Binary .xls file from Simples Agenda

4. Session Management

✓ Reuse:   Valid token/session from previous call
✗ Don't:   Ask for credentials if session is still valid
✓ Ask:     Only when token is expired or invalid

5. Data Cleanup

✓ Remove:  Trailing blank rows
✓ Remove:  Extra spaces in column headers
✓ Keep:    Original data integrity

Mapped Parameters & Confirmed Behavior

✅ ALL PARAMETERS CONFIRMED (execucao real em 31/08/2026)

1. Parameter Mapping ✅ (verificado em execucao real)

• crud.php:
  • Acao de exportacao: acao=exporta_agendamentos
  • Data inicial: dataIni (dd/mm/yyyy)
  • Data final: dataFim (dd/mm/yyyy)
  • Profissionais: cod_usuario_array (IDs separados por virgula, ou vazio)
  • Servico: cod_produto
  • Cliente: cod_cliente
• A resposta traz o caminho do arquivo em <nome_excel>

2. Authentication Mechanism ✅ (corrigido em 31/08/2026)

• Endpoint real: crud_autenticacao.php (POST), acao=autentica_usuario
• Campos: login (email), senha, conectado=1, captcha_resposta
• Resposta XML: <houve_erro>, <endereco>, <mensagem>, <requer_captcha>, <captcha_pergunta>
• Cookies obtidos: PHPSESSID (na pagina), UsuarioSA + SenhaSA (no login)
• Selenium removido — HTTP puro (requests ou Invoke-WebRequest) basta
• autenticacao_usuario.php NAO autentica por POST: responde 200, define so PHPSESSID. Esse era o motivo real da dependencia de navegador.
• Campo captcha_resposta fica oculto; se requer_captcha=S, abortar

3. File Response Details ✅

• Caminho: lido de <nome_excel> (ex.: excel/excel71400/Agendamentos_31082026095116.xls)
• Formato: OLE2 / BIFF (D0CF11E0A1B11AE1)
• Planilha AGENDAMENTOS, 10 colunas: Data, Cliente, Telefone, Email, Servico, Observacao, Profissional, Status, Data Acao, Executado por
• Tamanho observado: ~152 KB para 786 linhas (04/08/2026–31/08/2026)
• Nota: xlrd exige ignore_workbook_corruption=True para abrir o arquivo

4. Runtime / Ambiente ✅

• scripts/baixar_agenda.ps1 cobre o fluxo inteiro com PowerShell 5.1, sem dependencias externas

5. Rate Limiting & SLA ✅ (parcial)

• Rate limiting CONFIRMADO: apos varias requisicoes/logins em poucos segundos o servidor responde HTTP 429 Too Many Requests
• Tratamento: abortar com mensagem clara, sem retry automatico (codigo RATE_LIMITED / exit 6)
• Janela exata do limite: nao medida
• SLA: Not documented
• Timeouts: 30s conexao/login, 120s exportacao, 180s download

Triggering Phrases

This skill should activate when users mention:

• "download agenda from Simples Agenda"
• "export appointments"
• "baixar agenda" (Portuguese)
• "extract appointment data"
• "get appointments for [date range]"
• "download Simples Agenda"
• "exportar agendamentos"
• "baixe minha agenda" (português, sem datas — usa defaults)
• When user mentions Simples Agenda or appointments (com ou sem datas explícitas)

Limitations & Out of Scope

• ✗ Cannot modify, delete, or create appointments in Simples Agenda
• ✗ So os endpoints do fluxo de exportacao: autenticacao_usuario.php (GET), crud_autenticacao.php (login), crud.php (exporta_agendamentos) e o caminho retornado em <nome_excel>
• ✗ Cannot access other Simples Agenda features (financial, invoicing, etc.)
• ✗ Must not block system on errors — all failures graceful and non-blocking
• ✗ Navegador/Selenium nao e mais usado nem necessario — o fluxo e HTTP puro
• ✗ CAPTCHA nunca e resolvido automaticamente: abortar e pedir login manual
• ✗ Nao repetir chamadas apos HTTP 429 — aguardar

Permissions Required

• ✓ Network access to https://www.simplesagenda.com.br
• ✓ Credential storage: OS Credential Manager (Windows) / Keychain (macOS) / Secret Manager (Linux)
• ✓ File system write access to Downloads folder
• ✓ No arbitrary file creation outside of Downloads

Testing Strategy

Test Cases to Validate

1. Happy path: Valid date range, no filters → Download succeeds
2. With filters: Date range + specific professional → Download with filtered results
3. Date validation: Reject invalid formats (01-01-2024, 2024-01-01, etc.)
4. Date range: Reject End Date < Start Date
5. No results: Valid filters but no appointments → Clear message
6. Connection error: Timeout after 30s → Graceful error message
7. Authentication retry: Expired session → Re-authenticate and retry
8. File handling: Multiple downloads → Timestamps prevent overwrites
9. Large volume: Download 1 year of appointments → Performance acceptable

Implementation Status

✅ IMPLEMENTATION COMPLETE — validada em execucao real (31/08/2026)

Scripts

• baixar_agenda.ps1 — fluxo completo: login, export, download, sync BD, planilha ordenada, email
• README.md — documentacao de uso

Contrato de saida

Via exit codes: 0 OK, 1 AUTH_FAILED, 2 NO_RESULTS, 3 CORRUPTED_FILE, 4 INVALID_INPUT, 5 CONNECTION_ERROR, 6 RATE_LIMITED, 7 falha na sincronizacao/ exportacao do banco (skill import-db-agenda).

Resolvido nesta versao

• ✅ Endpoint de login corrigido (crud_autenticacao.php)
• ✅ Selenium/Chrome eliminado
• ✅ HTTP 429 detectado e reportado
• ✅ Datas de calendario invalidas (31/02) agora rejeitadas
• ✅ Nome do arquivo lido de <nome_excel> (nunca adivinhado)
• ✅ Validacao de magic bytes com remocao do arquivo corrompido
• ✅ Erros viram excecao/exit code — nada de None silencioso
• ✅ Senha removida dos arquivos de documentacao
• ✅ Saida em ASCII (emoji quebrava no console cp1252 do Windows)

Next Steps

1. Credential Storage: Windows Credential Manager / Keychain
2. Retry: backoff exponencial no 429
3. Logging: log estruturado para depuracao
4. Testing: testes automatizados dos caminhos de erro
5. Monitoring: vigiar mudancas no Simples Agenda (login.js e o canario)

Known Limitations

• Sem cache de credenciais (pede login a cada execucao)
• Sem retry automatico em 429 ou falha transitoria
• Janela exata do rate limiting desconhecida
• Somente entrada manual de credenciais (sem OAuth)
• O caminho NO_RESULTS esta implementado mas nao foi exercitado contra o servidor: a tentativa de testa-lo com um periodo vazio esbarrou no rate limiting (HTTP 429)

The skill is designed to be robust against future changes to Simples Agenda — if they update their system, the skill will fail gracefully with clear error messages rather than silently producing incorrect results.