Conceitos
As entidades da base comum e do módulo Instrumentos, os status de aplicação e submissão e o fluxo típico de integração.
Profissional e paciente formam a base comum da API. Instrumento, aplicação e submissão são os conceitos do módulo Instrumentos.
Modelo de entidades
Em texto: um profissional acompanha vários pacientes, e um paciente pode estar associado a mais de um profissional. O profissional cria aplicações; cada aplicação liga um paciente a um instrumento, e um mesmo paciente ou instrumento pode ter várias aplicações. Cada aplicação gera uma submissão por solicitação de resposta. Profissionais, pacientes e instrumentos são identificados por UUID; aplicações e submissões, por inteiro.
Profissional
Profissional de saúde mental que usa a HumanTrack para acompanhar pacientes e aplicar instrumentos. O profissional cria pacientes, aplica instrumentos e acompanha a evolução clínica pelos resultados.
Cada profissional vinculado a você tem um externalId, o identificador dele na sua plataforma. Todas as rotas sob /professionals/{professionalId} exigem que o profissional tenha vínculo ativo com você; caso contrário, a resposta é 404 INTEGRATION_NOT_FOUND.
Paciente
Pessoa sob o cuidado de um profissional. O paciente recebe instrumentos para responder e tem a evolução acompanhada pelas submissões.
Cada paciente está associado a um ou mais profissionais e pode ter várias aplicações de instrumentos ao longo do tempo.
Instrumento
Instrumento de avaliação psicológica, padronizado ou personalizado: escalas, inventários e questionários clínicos (por exemplo, PHQ-9 e GAD-7) ou registros de automonitoramento, como diários temáticos. Cada instrumento contém questões, opções de resposta, regras de pontuação e faixas de interpretação; o resultado de uma resposta é uma pontuação e a interpretação dessa pontuação.
forms nos caminhos da API
Nos caminhos e identificadores da API, instrumento aparece como forms e form template
(/forms/library, formTemplateId, formId). É sempre o mesmo conceito: instrumento.
O caminho-base /third-party/api/v1 também é histórico e estável: o nome do produto é HumanTrack API.
Aplicação
Atribuição de um instrumento a um paciente específico por um profissional. A aplicação define quando e com que frequência o paciente responde o instrumento (por exemplo, semanalmente ou mensalmente). É pela aplicação que se controla a recorrência e o agendamento.
Ciclos de recorrência aceitos: NOW (imediata), ONCE (única, na data de início), DAILY, WEEKLY, BIWEEKLY (quinzenal) e MONTHLY.
Status da aplicação
| Status | Significado |
|---|---|
CREATED | Criada. |
IN_PROGRESS | Em andamento. |
PAUSED | Pausada. |
FINISHED | Finalizada. |
CANCELED_IDLE | Encerrada automaticamente por inatividade do paciente. |
CANCELED_WHATSAPP_LIMIT | Encerrada por limite de envios de WhatsApp. |
CANCELED_STALE | Encerrada por expiração. |
CANCELED_DELETED_PATIENT | Encerrada porque o paciente foi desvinculado. |
Em texto: enquanto não é encerrada, a aplicação está em CREATED, IN_PROGRESS ou PAUSED; o contrato não detalha a passagem entre esses três status. POST .../finish finaliza uma aplicação em andamento, e POST .../applications/cancel encerra as aplicações ativas de um instrumento para o paciente; nos dois casos o status passa a FINISHED. A plataforma encerra a aplicação sozinha por inatividade do paciente (CANCELED_IDLE), por limite de envios de WhatsApp (CANCELED_WHATSAPP_LIMIT), por expiração (CANCELED_STALE) ou porque o paciente foi desvinculado (CANCELED_DELETED_PATIENT). Uma aplicação encerrada por inatividade pode ser reaberta por uma resposta tardia e encerrada de novo; o campo canceledAt do webhook distingue esses ciclos.
Submissão
Cada solicitação de resposta gerada por uma aplicação. Sempre que a plataforma solicita ao paciente que responda um instrumento, uma nova submissão é criada; ela guarda as respostas, a pontuação calculada e a data e hora da solicitação e da resposta.
As submissões de um paciente em um instrumento formam a série longitudinal dele: é delas que saem o gráfico de escores, a análise longitudinal e o relatório em PDF.
Status da submissão
| Status | Significado |
|---|---|
CREATED | Criada; pode estar aguardando a data de notificação. |
IN_PROGRESS | Aguardando resposta. |
OPENED | Aberta para resposta pelo paciente. |
STARTED | O paciente começou a responder. |
LATE | Atrasada. |
CANCELED | Cancelada manualmente pelo profissional ou pelo parceiro. |
CANCELED_LATE | Cancelada por atraso; uma nova submissão já foi gerada para o próximo período. |
CANCELED_IDLE | Cancelada porque a aplicação foi encerrada por inatividade. |
ANSWERED | Respondida pelo paciente. |
Em texto: cada solicitação de resposta gera uma submissão, que fica aguardando resposta em CREATED (inclusive antes da data de notificação), IN_PROGRESS, OPENED ou STARTED (o paciente começou a responder); o contrato não detalha a passagem entre esses quatro status. Quando o paciente responde, ela passa a ANSWERED. POST .../submissions/{submissionId}/cancel cancela uma submissão pendente (CANCELED), sem apagar respostas já registradas. Uma submissão atrasada fica LATE; cancelada por atraso, passa a CANCELED_LATE, e uma nova submissão já foi gerada para o próximo período. Se a aplicação for encerrada por inatividade, a submissão passa a CANCELED_IDLE.
Formatos
- Datas: ISO 8601. Data e hora completas (
2024-01-01T00:00:00Z); apenas data nas notificações (2024-01-01). - IDs: UUID para profissionais, pacientes e instrumentos (
550e8400-e29b-41d4-a716-446655440000); números inteiros para aplicações e submissões (1,123).
Paginação, ordenação e filtros
A paginação vale apenas para as listagens abaixo; as demais listagens (profissionais, pacientes, biblioteca e tags de instrumentos, notificações) não são paginadas e devolvem todos os resultados.
limiteoffset: aceitos pelas cinco listagens de aplicações e submissões: aplicações do profissional (GET /professionals/{professionalId}/forms/applications), submissões do profissional (GET /professionals/{professionalId}/forms/submissions), aplicações do paciente (GET /professionals/{professionalId}/patients/{patientId}/forms/applications), aplicações do paciente para um instrumento (GET /professionals/{professionalId}/patients/{patientId}/forms/{formId}/applications) e submissões do paciente (GET /professionals/{professionalId}/patients/{patientId}/forms/submissions).limitnão tem padrão (sem o parâmetro, não há limite) eoffsettem padrão0. Por exemplo,limit=10&offset=20retorna os resultados de 21 a 30.pageepage_size: usados só pelo histórico de recomendações (GET /professionals/{professionalId}/forms/recommend/history).pagecomeça em1(padrão1) epage_sizetem padrão10.
Nas três listagens de aplicações, use orderBy (created_at, next_answer_at, started_at ou updated_at; padrão created_at) e orderDirection (ASC ou DESC; padrão DESC).
Filtros por status aceitam listas separadas por vírgula, como status=IN_PROGRESS,FINISHED. Os parâmetros aceitos por cada endpoint estão na Referência da API.
Fluxo típico de integração
- Cadastre o profissional (
POST /professionals) ou vincule um profissional que já usa a HumanTrack (POST /connect, veja Vínculo de conta). - Cadastre os pacientes do profissional.
- Aplique instrumentos aos pacientes (crie aplicações).
- Os pacientes recebem notificações e respondem os instrumentos (geram submissões).
- Acompanhe resultados e evolução pelas submissões, pelo gráfico de escores e pelos relatórios, ou receba os eventos por webhook.