Pular para conteúdo

OTIDOC

Padrão técnico para integração com o sistema OTIMUS (gestão clínica / agendamento) em chatbots WhatsApp operados pela AgentProIA.

Para quem é esta documentação

Esta é a fonte única da verdade sobre como integrar com OTIMUS. Foi escrita para ser consumida por outros agentes Claude ao iniciarem um novo projeto de chatbot clínico, e por desenvolvedores humanos revisando ou estendendo um dos projetos existentes.

O que é o padrão OTIMUS

O OTIMUS (otimusclinic.com) é o ERP/sistema de gestão usado pelas clínicas parceiras. Cada clínica roda uma instância isolada do OTIMUS, com subdomínio próprio, credenciais próprias e IDs próprios para convênios, especialidades, agendas e procedimentos.

Um chatbot AgentProIA integrado com OTIMUS consegue:

  • Consultar horários disponíveis de um médico/procedimento
  • Cadastrar paciente (quando não existe) ou buscá-lo por CPF
  • Confirmar agendamento de consulta/exame
  • Transferir conversas fora do escopo para atendimento humano

Projetos que usam este padrão

Projeto Domínio OTIMUS Especialidade Médicos Referência
MEDCENTER medcenteracai-node.otimusclinic.com Clínica multi-especialidade 7 Ver
CLINFETO clinfeto.otimusclinic.com:9100 Ultrassonografia / Medicina fetal 5 Ver

Stack compartilhada

flowchart LR
    WA[WhatsApp] --> WTS[WTS Chat / FlowChat]
    WTS -->|webhook| API[FastAPI server.py]
    API --> WF[LangGraph workflow]
    WF --> MED[Processadores de mídia<br/>Gemini + Whisper]
    WF --> AG[Agente ReAct<br/>GPT-4.1 / GPT-4.1-mini]
    AG -->|tools| OT[(OTIMUS API)]
    AG -->|resposta| WTS
    WF --> PG[(PostgreSQL<br/>fila + chat history<br/>+ telemetria)]
  • Runtime: Python 3.12, FastAPI, Uvicorn, Docker
  • LLM: OpenAI (GPT-4.1 ou GPT-4.1-mini) via LangChain
  • Orquestração: LangGraph Functional API + ReAct agent
  • Persistência: PostgreSQL + PostgresSaver (LangGraph checkpointer)
  • Mídia: Google Gemini (imagem/PDF), OpenAI Whisper (áudio)
  • Canal: WTS Chat / FlowChat (WhatsApp Business)

Roteiro de leitura recomendado

  1. Visão geral — o que o sistema faz ponta-a-ponta
  2. Arquitetura — componentes e fluxo
  3. Endpoints OTIMUS — os 4 endpoints que importam
  4. Cliente OTIMUS — como encapsular as chamadas
  5. Primeiro nome do doutor — ⚠ armadilha crítica
  6. Checklist novo projeto — operacional

Princípios

Contratos que todo projeto OTIMUS deve honrar

  1. Nunca invente horários. Se o OTIMUS falhar, transfira para humano.
  2. Resolva IDs por nome (médico, procedimento, convênio) antes de bater na API. OTIMUS fala em IDs numéricos.
  3. Normalize nomes (remove acentos, uppercase) antes de comparar.
  4. Valide o agendaNome de retorno — uma request com agenda_id de médico X pode retornar horários se o OTIMUS estiver inconsistente; o nome precisa bater.
  5. Busque paciente por CPF antes de cadastrar. Nunca cadastre cego.
  6. CPF e telefone só com dígitos. Normalize antes de mandar.
  7. Datas vão para o OTIMUS em DD-MM-YYYY. O restante do sistema usa ISO YYYY-MM-DD internamente.
  8. Timezone é America/Sao_Paulo sempre.

Licença e uso

Documento interno AgentProIA. Replicar para novos projetos da mesma organização é permitido — manter referência a esta fonte e reportar divergências.