Introdução
Inteligência clínica dentro da sua plataforma
Plataforma de inteligência clínica para saúde mental. Pela HumanTrack API, o seu produto aplica instrumentos e devolve ao profissional escores e evolução longitudinal.
A HumanTrack é uma plataforma de inteligência clínica para saúde mental: transforma o que o paciente responde em dados clínicos estruturados e longitudinais, que o profissional consegue ler, comparar e discutir. A HumanTrack API abre essa infraestrutura para produtos brasileiros de saúde mental. Com ela, a sua plataforma aplica instrumentos aos pacientes dos profissionais que você atende, coleta as respostas e devolve ao profissional escores, séries de evolução, análise longitudinal e relatórios, sem que a sua equipe precise implementar cálculo de escores, faixas de interpretação ou o envio das solicitações de resposta.
A decisão clínica continua com o profissional. As análises e recomendações geradas por IA apoiam a interpretação e não substituem o julgamento clínico.
Organização por módulos
A API é organizada em módulos sobre uma base comum de profissionais, pacientes, vínculo de conta e webhooks. Hoje ela expõe o módulo Instrumentos: biblioteca, aplicação, submissões, escores, gráficos, análise longitudinal, relatórios e recomendação de instrumentos. Nexo, Registro de Sessão e Artemi vêm em breve, ainda sem endpoints nem data. Veja o que cada módulo cobre em Módulos.
Para quem é
Esta documentação é para as equipes técnicas das empresas parceiras que integram a própria plataforma à HumanTrack. As credenciais de acesso são fornecidas pela equipe HumanTrack; não há autocadastro.
URL base
Produção: https://api.humantrack.ioTodos os endpoints ficam sob o caminho base:
/third-party/api/v1Os servidores de cada operação também aparecem na Referência da API, a partir do campo servers da especificação OpenAPI.
Versionamento
A versão da API faz parte do caminho (/v1). A versão atual do contrato é a v1.0. O portal é reconstruído a cada nova versão publicada, e a Referência da API e a especificação para download refletem o contrato vigente naquele momento. O Changelog resume as mudanças relevantes junto com essas versões.
Comunicação nos dois sentidos
Pela API, a sua plataforma chama a HumanTrack. Para saber quando um paciente respondeu uma submissão ou quando uma aplicação foi encerrada por inatividade, sem consultar a API periodicamente, use os Webhooks: neles, a HumanTrack chama a sua plataforma.
Visão geral da integração
Em texto: a sua plataforma chama a HumanTrack API com a API Key e a API Secret. A HumanTrack envia ao paciente a solicitação de resposta, por link, WhatsApp ou e-mail, conforme a aplicação. O paciente responde o instrumento, e a HumanTrack avisa a sua plataforma por um webhook assinado com HMAC-SHA256. Os detalhes da resposta (respostas, escores, gráficos) continuam sendo consultados pela API.
Fluxo típico
Cadastre o profissional
POST /professionals cadastra o profissional e o vincula a você com o externalId dele na sua plataforma.
Vincule a conta, se o profissional já usa a HumanTrack
Se o e-mail já pertence a uma conta HumanTrack, o cadastro responde 403 PROFESSIONAL_CLAIM_REQUIRED. Peça o vínculo com POST /connect; ele fica ativo depois que o profissional confirma pelo e-mail de verificação. Veja Vínculo de conta.
Cadastre o paciente
POST /professionals/{professionalId}/patients cadastra um paciente do profissional.
Aplique um instrumento
POST /professionals/{professionalId}/forms/{formId}/applications cria a aplicação com a recorrência e as preferências de notificação. A resposta traz urlToAnswer, o link que o paciente usa para responder. Os conceitos estão em Conceitos.
Receba o webhook
Quando o paciente responde, a HumanTrack envia SUBMISSION_ANSWERED ao seu endpoint, com os identificadores da submissão e da aplicação. Veja Webhooks.
Consulte a submissão e os escores
GET /professionals/{professionalId}/forms/submissions/{submissionId} traz as respostas e a pontuação. O gráfico de escores, a análise longitudinal e o relatório em PDF estão na Referência da API.