{ "components": { "parameters": { "ApplicationId": { "description": "ID da aplicação.", "example": 4417, "in": "path", "name": "applicationId", "required": true, "schema": { "type": "integer" } }, "ApplicationStatusFilter": { "description": "Status de aplicação separados por vírgula, por exemplo `IN_PROGRESS,FINISHED`.", "example": "IN_PROGRESS,FINISHED", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, "EndDate": { "description": "Data e hora final do filtro (RFC 3339).", "example": "2026-03-31T23:59:59Z", "in": "query", "name": "endDate", "required": false, "schema": { "format": "date-time", "type": "string" } }, "FormApplicationIdFilter": { "description": "Filtra por aplicação.", "in": "query", "name": "formApplicationId", "required": false, "schema": { "minimum": 0, "type": "integer" } }, "FormId": { "description": "ID do instrumento.", "example": "b1e7d9c2-4f3a-4d8e-9c1b-7a2e5f0d6c88", "in": "path", "name": "formId", "required": true, "schema": { "format": "uuid", "type": "string" } }, "FormTemplateIdFilter": { "description": "Filtra por instrumento.", "in": "query", "name": "formTemplateId", "required": false, "schema": { "format": "uuid", "type": "string" } }, "Limit": { "description": "Número máximo de resultados. Sem o parâmetro, não há limite.", "in": "query", "name": "limit", "required": false, "schema": { "minimum": 0, "type": "integer" } }, "Offset": { "description": "Quantidade de resultados a pular.", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" } }, "OrderBy": { "description": "Campo de ordenação.", "in": "query", "name": "orderBy", "required": false, "schema": { "default": "created_at", "enum": [ "created_at", "next_answer_at", "started_at", "updated_at" ], "type": "string" } }, "OrderDirection": { "description": "Direção da ordenação.", "in": "query", "name": "orderDirection", "required": false, "schema": { "default": "DESC", "enum": [ "ASC", "DESC" ], "type": "string" } }, "PatientId": { "description": "ID do paciente na HumanTrack (`humanTrackId`).", "example": "9d2e4b70-1c3a-4f6e-9b8d-5a7c0e2f4d33", "in": "path", "name": "patientId", "required": true, "schema": { "format": "uuid", "type": "string" } }, "ProfessionalId": { "description": "ID do profissional na HumanTrack (`humanTrackId`).", "example": "3f7c1a54-6b2e-4a1d-8f0c-2b5e9d3a7c11", "in": "path", "name": "professionalId", "required": true, "schema": { "format": "uuid", "type": "string" } }, "RecurrenceCycleFilter": { "description": "Ciclos de recorrência separados por vírgula, por exemplo `DAILY,WEEKLY`.", "example": "WEEKLY,MONTHLY", "in": "query", "name": "recurrenceCycle", "required": false, "schema": { "type": "string" } }, "StartDate": { "description": "Data e hora inicial do filtro (RFC 3339).", "example": "2026-01-01T00:00:00Z", "in": "query", "name": "startDate", "required": false, "schema": { "format": "date-time", "type": "string" } }, "SubmissionId": { "description": "ID da submissão.", "example": 91824, "in": "path", "name": "submissionId", "required": true, "schema": { "type": "integer" } }, "SubmissionStatusFilter": { "description": "Status de submissão separados por vírgula, por exemplo `ANSWERED,CREATED`.", "example": "ANSWERED,CREATED", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, "WebhookEventId": { "description": "Mesmo valor de `id` do envelope, exposto como header apenas para correlação em logs.\nEste header **não** é coberto pela assinatura HMAC (`X-HumanTrack-Signature`); para\ndeduplicar, use o `id` do envelope assinado, nunca este header isoladamente.\n", "in": "header", "name": "X-HumanTrack-Event-Id", "required": true, "schema": { "format": "uuid", "type": "string" } }, "WebhookSignature": { "description": "Assinatura da entrega no formato `t=,v1=`, em que `v1` é\n`HMAC-SHA256(secret, \".\" + corpo bruto)` em hexadecimal minúsculo. Verifique sobre o\ncorpo bruto, byte a byte, compare em tempo constante e recuse `t` muito distante do\nrelógio atual (5 minutos é uma folga razoável).\n", "example": "t=1754404331,v1=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "in": "header", "name": "X-HumanTrack-Signature", "required": true, "schema": { "pattern": "^t=\\d+,v1=[0-9a-f]{64}$", "type": "string" } } }, "responses": { "BadRequest": { "content": { "application/json": { "example": { "code": "VALIDATION_ERROR", "message": "professionalId: must be a valid UUID" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Parâmetro, identificador ou corpo inválido." }, "Conflict": { "content": { "application/json": { "example": { "code": "PROFESSIONAL_EMAIL_ALREADY_EXIST", "message": "email already exists" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Conflito com um registro existente, como e-mail ou celular já cadastrado." }, "Empty": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } }, "description": "Operação concluída." }, "Forbidden": { "content": { "application/json": { "example": { "code": "IP_NOT_ALLOWED", "message": "IP address not allowed for this API credential" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Acesso negado (IP fora da lista permitida da credencial, ou operação não permitida para o profissional)." }, "InternalError": { "content": { "application/json": { "example": { "code": "INTERNAL", "message": "internal server error", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Erro interno. Informe o `traceId` ao suporte." }, "NotFound": { "content": { "application/json": { "example": { "code": "INTEGRATION_NOT_FOUND", "message": "professional partner integration not found" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Recurso não encontrado, ou profissional sem vínculo ativo com o parceiro." }, "Unauthorized": { "content": { "application/json": { "example": { "code": "INVALID_API_KEY", "message": "invalid API key" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Credenciais ausentes, inválidas, inativas ou expiradas. `code` é um dos\nseguintes: `INVALID_API_KEY` (chave ausente ou par chave/segredo não\nconfere), `API_CREDENTIAL_INACTIVE` (credencial existe mas está\ninativa) ou `API_CREDENTIAL_EXPIRED` (credencial existe mas expirou).\n" }, "UnprocessableEntity": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "A operação não pode ser executada no estado atual do recurso." } }, "schemas": { "AccountLinkRequest": { "example": { "email": "ana.souza@example.com", "external_id": "psm-8842" }, "properties": { "email": { "description": "E-mail da conta HumanTrack do profissional.", "format": "email", "type": "string" }, "external_id": { "description": "Identificador do profissional no sistema do parceiro.", "type": "string" } }, "required": [ "email", "external_id" ], "type": "object" }, "AccountLinkResponse": { "properties": { "message": { "type": "string" }, "status": { "description": "`VERIFICATION_LINK_SENT` means the request was accepted; the verification e-mail\ndelivery was attempted synchronously within the same request (so latency includes the\ne-mail provider). The response is `202` whether or not that attempt succeeded, delivery\nis not guaranteed, and the professional still needs to approve the link for it to\nbecome active.\n", "enum": [ "ALREADY_LINKED", "VERIFICATION_LINK_SENT", "DISCONNECTED" ], "type": "string" } }, "required": [ "status", "message" ], "type": "object" }, "AnswerRiskFlagInfo": { "description": "Sinal de risco detectado nesta resposta. Apoia a atenção do profissional e não constitui diagnóstico.", "properties": { "flagType": { "enum": [ "SUICIDE_SELF_HARM", "HOMICIDAL_IDEATION", "NONE" ], "type": "string" }, "severity": { "enum": [ "LOW", "MODERATE", "HIGH" ], "type": "string" } }, "required": [ "flagType", "severity" ], "type": "object" }, "ApplicationCanceledIdleData": { "properties": { "applicationId": { "type": "integer" }, "canceledAt": { "description": "Instante do encerramento. Distingue ciclos de encerramento da mesma aplicação.", "format": "date-time", "type": "string" }, "createdByPartner": { "const": true, "type": "boolean" }, "externalProfessionalId": { "type": "string" }, "formTemplateId": { "format": "uuid", "type": "string" }, "formTemplateTitle": { "type": "string" }, "patientId": { "format": "uuid", "type": "string" }, "professionalId": { "format": "uuid", "type": "string" }, "reason": { "description": "`UNANSWERED_SUBMISSIONS`: submissões consecutivas sem resposta. `UNANSWERED_NOTIFICATIONS`: lembretes consecutivos sem reação.", "enum": [ "UNANSWERED_SUBMISSIONS", "UNANSWERED_NOTIFICATIONS" ], "type": "string" } }, "required": [ "professionalId", "externalProfessionalId", "patientId", "applicationId", "formTemplateId", "formTemplateTitle", "reason", "canceledAt", "createdByPartner" ], "type": "object" }, "ApplicationCanceledIdleEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/ApplicationCanceledIdleData" }, "type": { "const": "APPLICATION_CANCELED_IDLE" } }, "type": "object" } ], "example": { "apiVersion": "v1", "data": { "applicationId": 4417, "canceledAt": "2026-08-05T03:09:58.412345Z", "createdByPartner": true, "externalProfessionalId": "psm-8842", "formTemplateId": "b1e7d9c2-4f3a-4d8e-9c1b-7a2e5f0d6c88", "formTemplateTitle": "PHQ-9", "patientId": "9d2e4b70-1c3a-4f6e-9b8d-5a7c0e2f4d33", "professionalId": "3f7c1a54-6b2e-4a1d-8f0c-2b5e9d3a7c11", "reason": "UNANSWERED_SUBMISSIONS" }, "id": "5b1a7e30-2d4c-4b9f-8e6a-1c3d5f7a9b22", "occurredAt": "2026-08-05T03:09:58.412345Z", "type": "APPLICATION_CANCELED_IDLE" } }, "CalculationMethod": { "description": "Método de cálculo do escore.", "enum": [ "SUM", "AVERAGE", "SUM_MULTIPLIED_BY_2" ], "type": "string" }, "CancelFormApplicationsResult": { "example": { "canceledApplicationIds": [ 4417, 4420 ], "canceledCount": 2 }, "properties": { "canceledApplicationIds": { "description": "IDs das aplicações encerradas.", "items": { "type": "integer" }, "type": [ "array", "null" ] }, "canceledCount": { "description": "Quantidade de aplicações encerradas nesta chamada.", "type": "integer" } }, "required": [ "canceledCount", "canceledApplicationIds" ], "type": "object" }, "CreateFormApplicationRequest": { "example": { "hideFormTemplateTitle": false, "notifyWhatsApp": true, "openToAnswer": false, "patientId": "9d2e4b70-1c3a-4f6e-9b8d-5a7c0e2f4d33", "recurrenceCycle": "WEEKLY", "showFormGraphToPatient": true, "startedAt": "2026-01-06T12:00:00Z" }, "properties": { "allowPatientAnnotation": { "description": "Permite que o paciente registre uma anotação livre junto da resposta. Omitido usa o padrão da plataforma.", "type": [ "boolean", "null" ] }, "hideFormTemplateTitle": { "default": false, "description": "Oculta o título do instrumento para o paciente.", "type": "boolean" }, "notifyWhatsApp": { "default": false, "description": "Notifica o paciente por WhatsApp.", "type": "boolean" }, "openToAnswer": { "default": false, "description": "Mantém a aplicação aberta para o paciente responder a qualquer momento pelo link.", "type": "boolean" }, "patientId": { "format": "uuid", "type": "string" }, "recurrenceCycle": { "$ref": "#/components/schemas/RecurrenceCycle" }, "showFormGraphToPatient": { "default": false, "description": "Mostra ao paciente o gráfico da própria evolução.", "type": "boolean" }, "startedAt": { "description": "Data e hora da primeira solicitação de resposta.", "format": "date-time", "type": "string" } }, "required": [ "patientId", "recurrenceCycle", "startedAt" ], "type": "object" }, "CreatePatientRequest": { "example": { "cellphone": "+5511987654321", "email": "carlos.lima@example.com", "name": "Carlos", "surname": "Lima" }, "properties": { "cellphone": { "description": "Celular com DDI e DDD. Usado para notificações por WhatsApp.", "type": "string" }, "email": { "format": "email", "type": [ "string", "null" ] }, "name": { "type": "string" }, "surname": { "type": "string" } }, "required": [ "name", "surname", "cellphone" ], "type": "object" }, "CreateProfessionalRequest": { "example": { "cellphone": "+5511912345678", "email": "ana.souza@example.com", "externalId": "psm-8842", "name": "Ana", "occupation": "Psychologist", "surname": "Souza" }, "properties": { "cellphone": { "description": "Celular com DDI e DDD.", "type": [ "string", "null" ] }, "email": { "format": "email", "type": "string" }, "externalId": { "description": "Identificador do profissional no sistema do parceiro.", "type": "string" }, "name": { "type": "string" }, "occupation": { "$ref": "#/components/schemas/Occupation" }, "surname": { "type": "string" } }, "required": [ "name", "surname", "email", "externalId" ], "type": "object" }, "Education": { "description": "Escolaridade.", "enum": [ "Incomplete Elementary Education", "Complete Elementary Education", "Incomplete High School", "Complete High School", "Incomplete Higher Education", "Complete Higher Education", "Postgraduate/Specialization/MBA", "Master's Degree", "PhD" ], "type": "string" }, "EmptyResponse": { "additionalProperties": false, "description": "Objeto vazio.", "type": "object" }, "ErrorResponse": { "description": "Corpo padrão das respostas de erro.", "properties": { "code": { "description": "Código estável do erro, por exemplo `VALIDATION_ERROR` ou `INTEGRATION_NOT_FOUND`.", "type": "string" }, "details": { "additionalProperties": true, "description": "Detalhes adicionais, quando o erro os fornece.", "type": "object" }, "message": { "description": "Mensagem descritiva do erro, em inglês. Não use para lógica.", "type": "string" }, "traceId": { "description": "Identificador de rastreio da requisição, para o suporte.", "type": "string" } }, "required": [ "message", "code" ], "type": "object" }, "FillType": { "description": "`DEFAULT` para respostas no período corrente; `RETROACTIVE_INTERFACE` para registros com data retroativa.", "enum": [ "DEFAULT", "RETROACTIVE_INTERFACE" ], "type": "string" }, "FormApplication": { "example": { "allowPatientAnnotation": false, "authorId": "3f7c1a54-6b2e-4a1d-8f0c-2b5e9d3a7c11", "createdAt": "2026-01-05T12:15:00Z", "formTemplate": { "shortTitle": "PHQ-9", "templateId": "b1e7d9c2-4f3a-4d8e-9c1b-7a2e5f0d6c88", "title": "Patient Health Questionnaire-9" }, "formTemplateId": "b1e7d9c2-4f3a-4d8e-9c1b-7a2e5f0d6c88", "hideFormTemplateTitle": false, "id": 4417, "nextAnswerAt": "2026-01-13T12:00:00Z", "notifyEmail": false, "notifyWhatsApp": true, "openToAnswer": false, "patientId": "9d2e4b70-1c3a-4f6e-9b8d-5a7c0e2f4d33", "recurrenceCycle": "WEEKLY", "showFormGraphToPatient": true, "startedAt": "2026-01-06T12:00:00Z", "status": "IN_PROGRESS", "updatedAt": "2026-01-05T12:15:00Z", "urlToAnswer": "https://app.humantrack.io/submissions/validate/91824?code=abc123" }, "properties": { "allowPatientAnnotation": { "type": "boolean" }, "answerToken": { "type": [ "string", "null" ] }, "authorId": { "description": "ID do profissional que criou a aplicação.", "format": "uuid", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "formTemplate": { "$ref": "#/components/schemas/FormTemplateInfo" }, "formTemplateId": { "format": "uuid", "type": "string" }, "hideFormTemplateTitle": { "type": "boolean" }, "id": { "type": "integer" }, "lastSubmission": { "$ref": "#/components/schemas/LastSubmissionInfo" }, "nextAnswerAt": { "description": "Próxima data de solicitação de resposta.", "format": "date-time", "type": [ "string", "null" ] }, "notifyEmail": { "type": "boolean" }, "notifyWhatsApp": { "type": "boolean" }, "openToAnswer": { "type": "boolean" }, "patientId": { "format": "uuid", "type": "string" }, "recurrenceCycle": { "$ref": "#/components/schemas/RecurrenceCycle" }, "showFormGraphToPatient": { "type": "boolean" }, "startedAt": { "format": "date-time", "type": "string" }, "status": { "$ref": "#/components/schemas/FormApplicationStatus" }, "submissions": { "items": { "$ref": "#/components/schemas/FormSubmission" }, "type": "array" }, "totalSubmissions": { "type": [ "integer", "null" ] }, "updatedAt": { "format": "date-time", "type": "string" }, "urlToAnswer": { "description": "Link que o paciente usa para responder.", "type": "string" } }, "required": [ "id", "authorId", "patientId", "formTemplateId", "recurrenceCycle", "notifyWhatsApp", "notifyEmail", "hideFormTemplateTitle", "showFormGraphToPatient", "allowPatientAnnotation", "openToAnswer", "urlToAnswer", "startedAt", "nextAnswerAt", "status", "createdAt", "updatedAt" ], "type": "object" }, "FormApplicationInfo": { "description": "Dados básicos da aplicação que gerou a submissão.", "properties": { "allowPatientAnnotation": { "type": "boolean" }, "answerToken": { "type": [ "string", "null" ] }, "authorId": { "format": "uuid", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "formTemplateId": { "format": "uuid", "type": "string" }, "hideFormTemplateTitle": { "type": "boolean" }, "id": { "type": "integer" }, "nextAnswerAt": { "format": "date-time", "type": [ "string", "null" ] }, "notifyEmail": { "type": "boolean" }, "notifyWhatsApp": { "type": "boolean" }, "openToAnswer": { "type": "boolean" }, "patientId": { "format": "uuid", "type": "string" }, "recurrenceCycle": { "$ref": "#/components/schemas/RecurrenceCycle" }, "showFormGraphToPatient": { "type": "boolean" }, "startedAt": { "format": "date-time", "type": "string" }, "status": { "$ref": "#/components/schemas/FormApplicationStatus" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "authorId", "patientId", "formTemplateId", "recurrenceCycle", "startedAt", "nextAnswerAt", "status", "notifyWhatsApp", "notifyEmail", "hideFormTemplateTitle", "showFormGraphToPatient", "allowPatientAnnotation", "openToAnswer", "answerToken", "createdAt", "updatedAt" ], "type": "object" }, "FormApplicationStatus": { "enum": [ "CREATED", "IN_PROGRESS", "PAUSED", "FINISHED", "CANCELED_IDLE", "CANCELED_WHATSAPP_LIMIT", "CANCELED_STALE", "CANCELED_DELETED_PATIENT" ], "type": "string" }, "FormQuestionAnswer": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "customValue": { "description": "Texto livre da opção \"Outro\".", "type": "string" }, "formSubmissionId": { "type": "integer" }, "id": { "type": "integer" }, "question": { "$ref": "#/components/schemas/QuestionDetails" }, "questionId": { "type": "integer" }, "riskFlag": { "$ref": "#/components/schemas/AnswerRiskFlagInfo" }, "updatedAt": { "format": "date-time", "type": "string" }, "value": { "description": "Resposta de questões de valor único (MULTIPLE_CHOICE, LINEAR_SCALE, TEXT, TIME, NUMERIC).", "type": "string" }, "values": { "description": "Respostas de questões de múltiplos valores (CHECKBOXES).", "items": { "type": "string" }, "type": "array" }, "weight": { "description": "Peso da resposta no escore.", "type": [ "number", "null" ] } }, "required": [ "id", "formSubmissionId", "questionId", "value", "weight", "createdAt", "updatedAt" ], "type": "object" }, "FormSection": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "id": { "type": "integer" }, "position": { "type": "integer" }, "title": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "title", "position", "createdAt", "updatedAt" ], "type": "object" }, "FormSubScale": { "properties": { "calculationMethod": { "$ref": "#/components/schemas/CalculationMethod" }, "childSubScaleIds": { "items": { "type": "integer" }, "type": "array" }, "code": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "scoreDirection": { "$ref": "#/components/schemas/ScoreDirection" }, "scoreRanges": { "items": { "$ref": "#/components/schemas/ScoreRange" }, "type": [ "array", "null" ] }, "source": { "enum": [ "QUESTIONS", "SUBSCALES" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "calculationMethod", "scoreRanges", "createdAt", "updatedAt" ], "type": "object" }, "FormSubmission": { "example": { "answers": [ { "createdAt": "2026-01-13T14:05:41Z", "formSubmissionId": 91824, "id": 1, "questionId": 301, "updatedAt": "2026-01-13T14:05:41Z", "value": "2", "weight": 2 } ], "completedFillAt": "2026-01-13T14:05:41Z", "createdAt": "2026-01-13T12:00:00Z", "deadline": "2026-01-20T12:00:00Z", "fillType": "DEFAULT", "formApplicationId": 4417, "formTemplate": { "shortTitle": "PHQ-9", "templateId": "b1e7d9c2-4f3a-4d8e-9c1b-7a2e5f0d6c88", "title": "Patient Health Questionnaire-9" }, "formTemplateId": "b1e7d9c2-4f3a-4d8e-9c1b-7a2e5f0d6c88", "globalClassification": { "color": "#F5A623", "maxScore": 14, "minScore": 10, "title": "Moderado" }, "id": 91824, "interpretativeAnalysis": null, "notifiedAt": "2026-01-13T12:00:05Z", "patientId": "9d2e4b70-1c3a-4f6e-9b8d-5a7c0e2f4d33", "score": 12, "startedAt": "2026-01-13T12:00:00Z", "startedFillAt": "2026-01-13T14:02:10Z", "status": "ANSWERED", "updatedAt": "2026-01-13T14:05:41Z", "urlToAnswer": "https://app.humantrack.io/submissions/validate/91824?code=abc123" }, "properties": { "answers": { "items": { "$ref": "#/components/schemas/FormQuestionAnswer" }, "type": "array" }, "completedFillAt": { "description": "Quando o paciente concluiu a resposta.", "format": "date-time", "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "deadline": { "format": "date-time", "type": [ "string", "null" ] }, "fillType": { "$ref": "#/components/schemas/FillType" }, "formApplication": { "$ref": "#/components/schemas/FormApplicationInfo" }, "formApplicationId": { "type": [ "integer", "null" ] }, "formTemplate": { "$ref": "#/components/schemas/FormTemplateInfo" }, "formTemplateId": { "format": "uuid", "type": "string" }, "globalClassification": { "$ref": "#/components/schemas/ScoreClassification" }, "hasHighRisk": { "description": "Presente e `true` quando alguma resposta tem sinal de risco alto.", "type": "boolean" }, "id": { "type": "integer" }, "interpretativeAnalysis": { "description": "Análise interpretativa gerada por IA, de apoio ao profissional.", "type": [ "string", "null" ] }, "notifiedAt": { "format": "date-time", "type": [ "string", "null" ] }, "patientId": { "format": "uuid", "type": "string" }, "psychometricIndicators": { "$ref": "#/components/schemas/PsychometricIndicators" }, "riskFlagCount": { "description": "Quantidade de respostas com sinal de risco.", "type": "integer" }, "score": { "description": "Escore global.", "type": [ "number", "null" ] }, "startedAt": { "description": "Data a partir da qual a submissão pode ser respondida.", "format": "date-time", "type": "string" }, "startedFillAt": { "description": "Quando o paciente começou a responder.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/FormSubmissionStatus" }, "subscaleClassifications": { "additionalProperties": { "$ref": "#/components/schemas/ScoreClassification" }, "description": "Classificação por subescala, indexada pelo ID da subescala.", "type": "object" }, "subscaleScores": { "items": { "$ref": "#/components/schemas/SubscaleScore" }, "type": "array" }, "updatedAt": { "format": "date-time", "type": "string" }, "urlToAnswer": { "description": "Link que o paciente usa para responder. Vazio quando não há link.", "type": "string" } }, "required": [ "id", "formTemplateId", "patientId", "formApplicationId", "startedFillAt", "completedFillAt", "score", "startedAt", "deadline", "urlToAnswer", "notifiedAt", "interpretativeAnalysis", "status", "createdAt", "updatedAt", "fillType" ], "type": "object" }, "FormSubmissionStatus": { "description": "Status da submissão (ver descrição geral da API).", "enum": [ "CREATED", "IN_PROGRESS", "OPENED", "STARTED", "LATE", "CANCELED", "CANCELED_LATE", "CANCELED_IDLE", "ANSWERED" ], "type": "string" }, "FormTag": { "example": { "createdAt": "2025-03-10T12:00:00Z", "id": 4, "name": "Depressão", "updatedAt": "2025-03-10T12:00:00Z" }, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "createdAt", "updatedAt" ], "type": "object" }, "FormTemplate": { "description": "Instrumento de avaliação.", "properties": { "averageScore": { "type": "number" }, "config": { "$ref": "#/components/schemas/FormTemplateConfig" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": [ "string", "null" ] }, "developerReferences": { "type": [ "string", "null" ] }, "formattedTitle": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "instruction": { "description": "Orientações de interpretação para o profissional.", "type": [ "string", "null" ] }, "instrumentType": { "$ref": "#/components/schemas/InstrumentType" }, "isNew": { "type": "boolean" }, "isPublic": { "type": "boolean" }, "isScorable": { "description": "Indica se o instrumento gera escore.", "type": "boolean" }, "metadata": { "description": "Metadados de publicação.", "properties": { "publishedAt": { "format": "date-time", "type": "string" } }, "type": "object" }, "patientInstruction": { "description": "Orientações exibidas ao paciente.", "type": [ "string", "null" ] }, "questions": { "items": { "$ref": "#/components/schemas/Question" }, "type": "array" }, "references": { "description": "Referências bibliográficas do instrumento.", "type": [ "string", "null" ] }, "scoreRanges": { "description": "Faixas de interpretação do escore global.", "items": { "$ref": "#/components/schemas/ScoreRange" }, "type": "array" }, "sections": { "items": { "$ref": "#/components/schemas/FormSection" }, "type": "array" }, "shortTitle": { "description": "Sigla ou título curto, por exemplo PHQ-9.", "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/FormTemplateStatus" }, "subScales": { "items": { "$ref": "#/components/schemas/FormSubScale" }, "type": "array" }, "tags": { "items": { "$ref": "#/components/schemas/FormTag" }, "type": [ "array", "null" ] }, "title": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "title", "formattedTitle", "tags", "isScorable", "isPublic", "isNew", "status", "createdAt", "updatedAt" ], "type": "object" }, "FormTemplateConfig": { "properties": { "globalScoreConfig": { "properties": { "calculateGlobalScore": { "type": "boolean" }, "calculationMethod": { "$ref": "#/components/schemas/CalculationMethod" }, "scoreDirection": { "$ref": "#/components/schemas/ScoreDirection" }, "source": { "enum": [ "QUESTIONS", "SUBSCALES" ], "type": "string" } }, "type": "object" } }, "type": "object" }, "FormTemplateInfo": { "description": "Dados mínimos do instrumento.", "properties": { "shortTitle": { "type": [ "string", "null" ] }, "templateId": { "format": "uuid", "type": "string" }, "title": { "type": [ "string", "null" ] } }, "required": [ "templateId", "title", "shortTitle" ], "type": "object" }, "FormTemplateStatus": { "enum": [ "DRAFT", "PUBLISHED" ], "type": "string" }, "Gender": { "enum": [ "MALE", "FEMALE", "OTHER" ], "type": "string" }, "InstrumentSummary": { "properties": { "formattedTitle": { "type": "string" }, "id": { "format": "uuid", "type": "string" }, "instrumentType": { "type": "string" }, "score": { "description": "Similaridade com o caso (0 a 1; maior é melhor).", "type": "number" }, "shortTitle": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "title": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "title", "formattedTitle", "url", "score" ], "type": "object" }, "InstrumentType": { "description": "Categoria do instrumento.", "enum": [ "STANDARDIZED_SCALE", "SELF_MONITORING_RECORD", "INTERVIEW_ANAMNESIS", "UNKNOWN" ], "type": "string" }, "LastSubmissionInfo": { "properties": { "completedFillAt": { "format": "date-time", "type": [ "string", "null" ] }, "id": { "type": "integer" }, "score": { "type": [ "number", "null" ] } }, "required": [ "id", "completedFillAt", "score" ], "type": "object" }, "Occupation": { "description": "Ocupação do profissional.", "enum": [ "Psychologist", "Psychiatrists", "Neurologist", "Nurse", "Nutritionist", "Other" ], "type": "string" }, "Patient": { "example": { "birthday": null, "cellphone": "+5511987654321", "createdAt": "2026-01-05T12:10:00Z", "education": null, "email": "carlos.lima@example.com", "gender": null, "humanTrackId": "9d2e4b70-1c3a-4f6e-9b8d-5a7c0e2f4d33", "name": "Carlos", "relationStatus": "ACTIVE", "status": "CREATED", "surname": "Lima", "updatedAt": "2026-01-05T12:10:00Z" }, "properties": { "birthday": { "format": "date-time", "type": [ "string", "null" ] }, "cellphone": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "education": { "anyOf": [ { "$ref": "#/components/schemas/Education" }, { "type": "null" } ] }, "email": { "type": [ "string", "null" ] }, "gender": { "anyOf": [ { "$ref": "#/components/schemas/Gender" }, { "type": "null" } ] }, "humanTrackId": { "description": "ID do paciente na HumanTrack.", "format": "uuid", "type": "string" }, "name": { "type": "string" }, "relationStatus": { "description": "Estado da relação entre o profissional e o paciente.", "enum": [ "PENDING", "ACTIVE", "INACTIVE" ], "type": "string" }, "status": { "enum": [ "CREATED", "CONFIRMED" ], "type": "string" }, "surname": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "humanTrackId", "name", "surname", "email", "cellphone", "birthday", "gender", "education", "status", "relationStatus", "createdAt", "updatedAt" ], "type": "object" }, "PatientFormReport": { "properties": { "pdfBytes": { "contentEncoding": "base64", "description": "PDF do relatório em base64.", "type": "string" }, "pdfUrl": { "description": "Link HTTPS público para baixar o PDF, válido por 15 minutos. Ausente quando indisponível.", "format": "uri", "type": "string" } }, "required": [ "pdfBytes" ], "type": "object" }, "PatientLongitudinalAnalysis": { "example": { "analysisId": "7a1c9e20-5b3d-4f8a-9e6c-2d4b8f0a1c55", "formTemplateId": "b1e7d9c2-4f3a-4d8e-9c1b-7a2e5f0d6c88", "generatedAt": "2026-02-01T10:00:00Z", "historicalAnalysis": "## Trajetória\n\nOs escores indicam redução gradual entre a primeira e a última aplicação.", "patientId": "9d2e4b70-1c3a-4f6e-9b8d-5a7c0e2f4d33" }, "properties": { "analysisId": { "format": "uuid", "type": "string" }, "formTemplateId": { "format": "uuid", "type": "string" }, "generatedAt": { "format": "date-time", "type": "string" }, "historicalAnalysis": { "description": "Texto da análise, em Markdown.", "type": "string" }, "patientId": { "format": "uuid", "type": "string" } }, "required": [ "patientId", "formTemplateId", "analysisId", "generatedAt", "historicalAnalysis" ], "type": "object" }, "PatientLongitudinalAnalysisStatus": { "example": { "analysisGeneratedAt": "2026-02-01T10:00:00Z", "analysisId": "7a1c9e20-5b3d-4f8a-9e6c-2d4b8f0a1c55", "hasAnalysis": true, "isStale": false, "latestSubmissionAt": "2026-01-27T13:40:02Z" }, "properties": { "analysisGeneratedAt": { "format": "date-time", "type": "string" }, "analysisId": { "format": "uuid", "type": "string" }, "hasAnalysis": { "description": "Já existe análise gerada.", "type": "boolean" }, "isStale": { "description": "Há submissões respondidas depois da última geração. Só faz sentido quando `hasAnalysis` é `true`.", "type": "boolean" }, "latestSubmissionAt": { "description": "Data da submissão respondida mais recente. Sem análise, sua presença indica que uma análise pode ser gerada.", "format": "date-time", "type": "string" } }, "required": [ "hasAnalysis", "isStale" ], "type": "object" }, "PatientNotification": { "properties": { "channel": { "description": "Canal da notificação, por exemplo `WHATSAPP` ou `EMAIL`.", "type": "string" }, "context": { "description": "Motivo da notificação.", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "destinationEmail": { "type": "string" }, "destinationPhoneNumber": { "type": "string" }, "formApplicationId": { "type": [ "integer", "null" ] }, "formSubmissionId": { "type": [ "integer", "null" ] }, "id": { "type": "integer" }, "patientId": { "format": "uuid", "type": "string" }, "patientName": { "type": "string" }, "professionalId": { "format": "uuid", "type": "string" }, "provider": { "description": "Provedor de envio.", "type": "string" }, "sentAt": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "Estado de envio da notificação.", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "channel", "destinationPhoneNumber", "patientId", "professionalId", "formSubmissionId", "formApplicationId", "context", "status", "sentAt", "provider", "createdAt", "updatedAt" ], "type": "object" }, "Professional": { "example": { "cellphone": "+5511912345678", "createdAt": "2026-01-05T12:00:00Z", "email": "ana.souza@example.com", "externalId": "psm-8842", "humanTrackId": "3f7c1a54-6b2e-4a1d-8f0c-2b5e9d3a7c11", "name": "Ana", "occupation": "Psychologist", "status": "CREATED", "surname": "Souza", "updatedAt": "2026-01-05T12:00:00Z" }, "properties": { "cellphone": { "type": [ "string", "null" ] }, "createdAt": { "format": "date-time", "type": "string" }, "email": { "format": "email", "type": "string" }, "externalId": { "description": "Identificador do profissional no sistema do parceiro.", "type": "string" }, "humanTrackId": { "description": "ID do profissional na HumanTrack.", "format": "uuid", "type": "string" }, "name": { "type": "string" }, "occupation": { "anyOf": [ { "$ref": "#/components/schemas/Occupation" }, { "const": "", "type": "string" } ], "description": "Ocupação do profissional. Vazia quando não informada." }, "status": { "$ref": "#/components/schemas/ProfessionalStatus" }, "surname": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "humanTrackId", "name", "surname", "email", "cellphone", "occupation", "status", "externalId", "createdAt", "updatedAt" ], "type": "object" }, "ProfessionalLookupResponse": { "example": { "exists": true, "humanTrackId": "3f7c1a54-6b2e-4a1d-8f0c-2b5e9d3a7c11", "linked": false }, "properties": { "exists": { "description": "Existe profissional com o e-mail.", "type": "boolean" }, "humanTrackId": { "description": "Presente quando o profissional existe.", "format": "uuid", "type": "string" }, "linked": { "description": "O profissional tem vínculo ativo com o parceiro.", "type": "boolean" } }, "required": [ "exists", "linked" ], "type": "object" }, "ProfessionalStatus": { "description": "Estágio do cadastro do profissional visível ao parceiro. `CREATED` indica conta criada aguardando confirmação; demais estágios internos são reportados como `CONFIRMED`.", "enum": [ "CREATED", "CONFIRMED" ], "type": "string" }, "PsychometricIndicators": { "description": "Indicadores psicométricos calculados para a submissão (variação em relação à anterior\ne à linha de base, mudança de faixa, sequências, extremos, tendência). `subscales` é\nindexado pelo ID da subescala. A estrutura interna é versionada por `version`.\n", "properties": { "global": { "additionalProperties": true, "type": "object" }, "subscales": { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object" }, "version": { "type": "integer" } }, "required": [ "version" ], "type": "object" }, "Question": { "properties": { "centerEmoji": { "type": "string" }, "centerLabel": { "type": "string" }, "code": { "description": "Identificador estável da questão no instrumento, por exemplo `PSQI_Q5A`.", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "formSubScaleId": { "deprecated": true, "description": "Obsoleto; use `subScaleIds`.", "type": "integer" }, "hasWeight": { "type": [ "boolean", "null" ] }, "id": { "type": "integer" }, "leftEmoji": { "type": "string" }, "leftLabel": { "type": "string" }, "pointAnchors": { "items": { "$ref": "#/components/schemas/QuestionPointAnchor" }, "type": "array" }, "position": { "type": "integer" }, "questionOptions": { "items": { "$ref": "#/components/schemas/QuestionOption" }, "type": "array" }, "questionType": { "$ref": "#/components/schemas/QuestionType" }, "rightEmoji": { "type": "string" }, "rightLabel": { "type": "string" }, "scaleEnd": { "type": "number" }, "scaleStart": { "type": "number" }, "scaleStep": { "type": "number" }, "subScaleIds": { "items": { "type": "integer" }, "type": "array" }, "title": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "visibilityCondition": { "$ref": "#/components/schemas/QuestionCondition" } }, "required": [ "id", "questionType", "title", "position", "hasWeight", "createdAt", "updatedAt" ], "type": "object" }, "QuestionCondition": { "description": "Regra de visibilidade. A questão só é exibida quando a resposta da questão de origem satisfaz a regra.", "properties": { "operator": { "enum": [ "OPTION_SELECTED", "OPTION_NOT_SELECTED", "GT", "GTE", "LT", "LTE", "EQ" ], "type": "string" }, "optionValue": { "type": "string" }, "sourceQuestionId": { "type": "integer" }, "sourceQuestionPosition": { "type": "integer" }, "threshold": { "type": "number" } }, "required": [ "operator" ], "type": "object" }, "QuestionDetails": { "description": "Metadados da questão respondida.", "properties": { "centerEmoji": { "type": "string" }, "centerLabel": { "type": "string" }, "formSubScaleId": { "type": "integer" }, "leftEmoji": { "type": "string" }, "leftLabel": { "type": "string" }, "pointAnchors": { "items": { "$ref": "#/components/schemas/QuestionPointAnchor" }, "type": "array" }, "position": { "type": "integer" }, "questionOptions": { "items": { "$ref": "#/components/schemas/QuestionOption" }, "type": "array" }, "questionType": { "$ref": "#/components/schemas/QuestionType" }, "rightEmoji": { "type": "string" }, "rightLabel": { "type": "string" }, "scaleEnd": { "type": "number" }, "scaleStart": { "type": "number" }, "scaleStep": { "type": "number" }, "title": { "type": "string" } }, "type": "object" }, "QuestionOption": { "properties": { "createdAt": { "format": "date-time", "type": "string" }, "emoji": { "type": "string" }, "id": { "type": "integer" }, "isOther": { "description": "Opção \"Outro\", com texto livre.", "type": "boolean" }, "position": { "type": "integer" }, "updatedAt": { "format": "date-time", "type": "string" }, "value": { "type": "string" }, "weight": { "description": "Peso da opção no escore.", "type": "number" } }, "required": [ "id", "value", "position", "createdAt", "updatedAt" ], "type": "object" }, "QuestionPointAnchor": { "description": "Âncora visual de um ponto da escala linear.", "properties": { "emoji": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" } }, "required": [ "value" ], "type": "object" }, "QuestionType": { "description": "Tipo da questão. `TIME` é um horário do dia (`HH:MM`); `NUMERIC` é um número livre enviado como texto.", "enum": [ "MULTIPLE_CHOICE", "CHECKBOXES", "LINEAR_SCALE", "TEXT", "TIME", "NUMERIC" ], "type": "string" }, "RecommendationAction": { "properties": { "label": { "type": "string" }, "payload": { "description": "Dados da ação; o formato depende de `type`." }, "type": { "description": "Ação sugerida.", "enum": [ "apply", "customize", "create_custom" ], "type": "string" } }, "required": [ "type", "label", "payload" ], "type": "object" }, "RecommendationHistoryItem": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/RecommendationAction" }, "type": [ "array", "null" ] }, "case_text": { "type": "string" }, "created_at": { "description": "Data de criação.", "type": "string" }, "id": { "type": "integer" }, "mode": { "enum": [ "library", "hybrid", "no_match" ], "type": "string" }, "recommendation_text": { "type": "string" }, "used_instruments": { "items": { "$ref": "#/components/schemas/InstrumentSummary" }, "type": [ "array", "null" ] } }, "required": [ "id", "case_text", "recommendation_text", "mode", "used_instruments", "actions", "created_at" ], "type": "object" }, "RecommendationHistoryResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/RecommendationHistoryItem" }, "type": [ "array", "null" ] }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "required": [ "items", "total", "page", "page_size", "total_pages" ], "type": "object" }, "RecommendationRequest": { "example": { "case_text": "Adolescente com humor deprimido, anedonia e dificuldade para dormir há três semanas.", "top_k": 5 }, "properties": { "case_text": { "description": "Descrição do caso clínico, sem dados que identifiquem o paciente.", "minLength": 20, "type": "string" }, "top_k": { "default": 6, "description": "Número máximo de instrumentos sugeridos. Valores são limitados entre 1 e 10; o padrão é 6.", "type": "integer" } }, "required": [ "case_text" ], "type": "object" }, "RecommendationResponse": { "example": { "actions": [], "mode": "library", "recommendation_text": "O PHQ-9 é indicado para rastrear e acompanhar sintomas depressivos.", "used_instruments": [ { "formattedTitle": "PHQ-9 (Patient Health Questionnaire-9)", "id": "b1e7d9c2-4f3a-4d8e-9c1b-7a2e5f0d6c88", "score": 0.83, "shortTitle": "PHQ-9", "title": "Patient Health Questionnaire-9", "url": "https://app.humantrack.io/instruments/b1e7d9c2-4f3a-4d8e-9c1b-7a2e5f0d6c88" } ] }, "properties": { "actions": { "items": { "$ref": "#/components/schemas/RecommendationAction" }, "type": [ "array", "null" ] }, "audit_log_id": { "type": "integer" }, "mode": { "description": "`library` quando há instrumentos da biblioteca adequados, `hybrid` quando combina biblioteca e protocolo sugerido, `no_match` quando nenhum instrumento é adequado.", "enum": [ "library", "hybrid", "no_match" ], "type": "string" }, "recommendation_text": { "description": "Texto da recomendação, em Markdown.", "type": "string" }, "used_instruments": { "items": { "$ref": "#/components/schemas/InstrumentSummary" }, "type": "array" } }, "required": [ "mode", "recommendation_text", "actions" ], "type": "object" }, "RecurrenceCycle": { "description": "Recorrência da aplicação: `NOW` (imediata), `ONCE` (única, na data de início),\n`DAILY`, `WEEKLY`, `BIWEEKLY` (quinzenal) ou `MONTHLY`.\n", "enum": [ "NOW", "ONCE", "DAILY", "WEEKLY", "BIWEEKLY", "MONTHLY" ], "type": "string" }, "ScoreClassification": { "description": "Faixa de interpretação em que o escore se encontra.", "properties": { "color": { "type": "string" }, "maxScore": { "type": "number" }, "minScore": { "type": "number" }, "title": { "type": "string" } }, "required": [ "title", "color", "minScore", "maxScore" ], "type": "object" }, "ScoreDirection": { "description": "Sentido clínico do escore.", "enum": [ "HIGHER_WORSE", "HIGHER_BETTER" ], "type": "string" }, "ScoreGraphPoint": { "properties": { "classification": { "$ref": "#/components/schemas/ScoreClassification" }, "completedFillAt": { "format": "date-time", "type": "string" }, "formApplicationId": { "type": "integer" }, "indicators": { "description": "Variações do ponto em relação ao anterior e à linha de base.", "properties": { "deltaFromBaseline": { "type": "number" }, "deltaFromPrevious": { "type": "number" }, "isBestScore": { "type": "boolean" }, "isWorstScore": { "type": "boolean" }, "percentChangeFromBaseline": { "type": "number" }, "percentChangeFromPrevious": { "type": "number" }, "previousSeverityCategory": { "type": "string" }, "severityCategory": { "type": "string" } }, "type": "object" }, "score": { "type": "number" }, "submissionId": { "type": "integer" } }, "required": [ "submissionId", "completedFillAt", "score" ], "type": "object" }, "ScoreGraphResponse": { "example": { "formTemplateId": "b1e7d9c2-4f3a-4d8e-9c1b-7a2e5f0d6c88", "generatedAt": "2026-02-01T10:00:00Z", "patientId": "9d2e4b70-1c3a-4f6e-9b8d-5a7c0e2f4d33", "series": [ { "calculationMethod": "SUM", "name": "Escore global", "points": [ { "classification": { "color": "#F5A623", "maxScore": 14, "minScore": 10, "title": "Moderado" }, "completedFillAt": "2026-01-13T14:05:41Z", "formApplicationId": 4417, "score": 12, "submissionId": 91824 } ], "scoreRanges": [ { "color": "#F5A623", "maxScore": 14, "minScore": 10, "title": "Moderado" } ], "seriesId": "global", "seriesType": "GLOBAL", "source": "QUESTIONS", "yDomain": { "max": 27, "min": 0 } } ], "summary": { "firstSubmissionCompletedFillAt": "2026-01-13T14:05:41Z", "lastSubmissionCompletedFillAt": "2026-01-27T13:40:02Z", "totalAnsweredSubmissions": 3 } }, "properties": { "formTemplateId": { "format": "uuid", "type": "string" }, "generatedAt": { "format": "date-time", "type": "string" }, "patientId": { "format": "uuid", "type": "string" }, "series": { "items": { "$ref": "#/components/schemas/ScoreGraphSeries" }, "type": [ "array", "null" ] }, "summary": { "properties": { "firstSubmissionCompletedFillAt": { "format": "date-time", "type": "string" }, "lastSubmissionCompletedFillAt": { "format": "date-time", "type": "string" }, "totalAnsweredSubmissions": { "type": "integer" } }, "required": [ "totalAnsweredSubmissions" ], "type": "object" } }, "required": [ "patientId", "formTemplateId", "generatedAt", "summary", "series" ], "type": "object" }, "ScoreGraphSeries": { "description": "Uma linha do gráfico (escore global ou uma subescala).", "properties": { "calculationMethod": { "$ref": "#/components/schemas/CalculationMethod" }, "name": { "type": "string" }, "points": { "items": { "$ref": "#/components/schemas/ScoreGraphPoint" }, "type": [ "array", "null" ] }, "scoreRanges": { "items": { "properties": { "color": { "type": "string" }, "maxScore": { "type": "number" }, "minScore": { "type": "number" }, "title": { "type": "string" } }, "required": [ "title", "minScore", "maxScore", "color" ], "type": "object" }, "type": [ "array", "null" ] }, "seriesId": { "type": "string" }, "seriesType": { "enum": [ "GLOBAL", "SUBSCALE" ], "type": "string" }, "source": { "type": "string" }, "yDomain": { "description": "Limites teóricos do eixo Y.", "properties": { "max": { "type": "number" }, "min": { "type": "number" } }, "required": [ "min", "max" ], "type": "object" } }, "required": [ "seriesId", "seriesType", "name", "calculationMethod", "source", "yDomain", "scoreRanges", "points" ], "type": "object" }, "ScoreRange": { "description": "Faixa de interpretação de escore.", "properties": { "color": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "formSubScaleId": { "type": "integer" }, "formTemplateId": { "format": "uuid", "type": "string" }, "id": { "type": "integer" }, "maxScore": { "type": "number" }, "minScore": { "type": "number" }, "title": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "title", "minScore", "maxScore", "color", "createdAt", "updatedAt" ], "type": "object" }, "SubmissionAnsweredData": { "properties": { "applicationId": { "type": "integer" }, "createdByPartner": { "const": true, "description": "Sempre `true`; mantido para estabilidade do contrato.", "type": "boolean" }, "externalProfessionalId": { "description": "ID do profissional no sistema do parceiro, informado no vínculo.", "type": "string" }, "formTemplateId": { "format": "uuid", "type": "string" }, "formTemplateTitle": { "type": "string" }, "patientId": { "format": "uuid", "type": "string" }, "professionalId": { "description": "ID do profissional na HumanTrack.", "format": "uuid", "type": "string" }, "submissionId": { "type": "integer" } }, "required": [ "professionalId", "externalProfessionalId", "patientId", "submissionId", "applicationId", "formTemplateId", "formTemplateTitle", "createdByPartner" ], "type": "object" }, "SubmissionAnsweredEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/SubmissionAnsweredData" }, "type": { "const": "SUBMISSION_ANSWERED" } }, "type": "object" } ], "example": { "apiVersion": "v1", "data": { "applicationId": 4417, "createdByPartner": true, "externalProfessionalId": "psm-8842", "formTemplateId": "b1e7d9c2-4f3a-4d8e-9c1b-7a2e5f0d6c88", "formTemplateTitle": "PHQ-9", "patientId": "9d2e4b70-1c3a-4f6e-9b8d-5a7c0e2f4d33", "professionalId": "3f7c1a54-6b2e-4a1d-8f0c-2b5e9d3a7c11", "submissionId": 91824 }, "id": "0c9c2bd8-8a3a-4a2e-9a4a-4a9b7f7d1c11", "occurredAt": "2026-08-05T14:32:11Z", "type": "SUBMISSION_ANSWERED" } }, "SubscaleScore": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "score": { "type": "number" } }, "required": [ "id", "name", "score" ], "type": "object" }, "UpdateFormApplicationRecurrenceRequest": { "example": { "recurrenceCycle": "MONTHLY", "startedAt": "2026-02-01T12:00:00Z" }, "properties": { "recurrenceCycle": { "$ref": "#/components/schemas/RecurrenceCycle" }, "startedAt": { "description": "Nova data e hora da próxima solicitação de resposta (RFC 3339).", "format": "date-time", "type": "string" } }, "required": [ "recurrenceCycle", "startedAt" ], "type": "object" }, "UpdatePatientRequest": { "description": "`name`, `surname` e `cellphone` são obrigatórios e sempre substituídos\npelo valor enviado. Os campos opcionais (`email`, `birthday`, `gender`,\n`education`) são atualizados apenas quando enviados com um novo valor:\nse omitidos ou enviados como `null`, o valor já cadastrado é mantido —\nnão é possível limpar um desses campos por este endpoint. Para alterar\num campo opcional, envie o novo valor.\n", "example": { "birthday": "1990-04-12T00:00:00Z", "cellphone": "+5511987654321", "education": "Complete Higher Education", "email": "carlos.lima@example.com", "gender": "MALE", "name": "Carlos", "surname": "Lima" }, "properties": { "birthday": { "format": "date-time", "type": [ "string", "null" ] }, "cellphone": { "type": "string" }, "education": { "anyOf": [ { "$ref": "#/components/schemas/Education" }, { "type": "null" } ] }, "email": { "format": "email", "type": [ "string", "null" ] }, "gender": { "anyOf": [ { "$ref": "#/components/schemas/Gender" }, { "type": "null" } ] }, "name": { "type": "string" }, "surname": { "type": "string" } }, "required": [ "name", "surname", "cellphone" ], "type": "object" }, "WebhookEnvelope": { "description": "Envelope comum de todo evento de webhook.", "properties": { "apiVersion": { "const": "v1", "description": "Versão do contrato de webhooks.", "type": "string" }, "data": { "type": "object" }, "id": { "description": "ID do evento. Use para deduplicar; é estável entre tentativas e reenvios.", "format": "uuid", "type": "string" }, "occurredAt": { "description": "Instante do fato, em UTC.", "format": "date-time", "type": "string" }, "type": { "enum": [ "SUBMISSION_ANSWERED", "APPLICATION_CANCELED_IDLE" ], "type": "string" } }, "required": [ "id", "type", "apiVersion", "occurredAt", "data" ], "type": "object" } }, "securitySchemes": { "ApiKey": { "description": "API Key do parceiro. Deve ser enviada junto com `X-Api-Secret`.", "in": "header", "name": "X-Api-Key", "type": "apiKey" }, "ApiSecret": { "description": "API Secret do parceiro. Deve ser enviada junto com `X-Api-Key`.", "in": "header", "name": "X-Api-Secret", "type": "apiKey" } } }, "info": { "contact": { "email": "vinicius@humantrack.io", "name": "Vinicius Gabriel" }, "description": "API para parceiros integradores da HumanTrack.\n\nA HumanTrack é uma plataforma clínica para acompanhamento de pacientes. Ela permite\naplicar instrumentos psicométricos e instrumentos de avaliação clínica aos pacientes e\nacompanhar a evolução clínica por meio das submissões, gráficos e relatórios.\n\n## Autenticação\n\nTodas as requisições precisam dos dois headers de credencial, emitidos pela equipe\nHumanTrack para o seu parceiro:\n\n```\nX-Api-Key: sua-api-key\nX-Api-Secret: sua-api-secret\n```\n\nExemplo:\n\n```bash\ncurl \"https://api.humantrack.io/third-party/api/v1/forms/library\" \\\n -H \"X-Api-Key: sua-api-key\" \\\n -H \"X-Api-Secret: sua-api-secret\"\n```\n\n- **401**: API Key ou API Secret ausentes, inválidas, inativas ou expiradas.\n `code` é um dos seguintes: `INVALID_API_KEY` (chave ausente ou par\n chave/segredo não confere), `API_CREDENTIAL_INACTIVE` (credencial\n existe mas está inativa) ou `API_CREDENTIAL_EXPIRED` (credencial\n existe mas expirou).\n- **403**: a credencial é válida, mas o IP de origem não está na lista permitida\n (quando a credencial tem restrição de IP), ou a operação não é permitida para o\n profissional.\n\n## Erros\n\nToda resposta de erro usa o mesmo corpo (`ErrorResponse`):\n\n```json\n{ \"message\": \"professional partner integration not found\", \"code\": \"INTEGRATION_NOT_FOUND\", \"traceId\": \"4bf92f3577b34da6a3ce929d0e0e4736\" }\n```\n\n`code` é estável e deve ser usado para tratar o erro; `message` é informativa.\n`traceId` identifica a requisição para o suporte. Erros de validação usam\n`code: VALIDATION_ERROR`.\n\n## Entidades principais\n\n**Profissional (Professional)**: profissional de saúde mental que usa a plataforma para\nacompanhar pacientes e aplicar instrumentos. Cada profissional vinculado ao parceiro tem\num `externalId`, o identificador dele no sistema do parceiro. Todas as rotas sob\n`/professionals/{professionalId}` exigem que o profissional tenha vínculo **ativo** com\no seu parceiro; caso contrário a resposta é `404 INTEGRATION_NOT_FOUND`.\n\n**Paciente (Patient)**: pessoa sob cuidado de um profissional. Recebe instrumentos para\nresponder e tem a evolução acompanhada pelas submissões.\n\n**Instrumento (FormTemplate)**: instrumento de avaliação psicológica padronizado ou\npersonalizado, como escalas, inventários e questionários clínicos (ex.: PHQ-9, GAD-7),\nou registros de automonitoramento como diários temáticos. Contém questões, opções de\nresposta, sistema de pontuação e faixas de interpretação.\n\n**Aplicação (FormApplication)**: atribuição de um instrumento a um paciente por um\nprofissional. Define quando e com que recorrência o paciente responde (ex.: semanal,\nmensal).\n\n**Submissão (FormSubmission)**: cada solicitação de resposta gerada por uma aplicação.\nGuarda as respostas, a pontuação calculada e as datas de solicitação e resposta.\n\n### Status das submissões\n\n- `CREATED`: criada; pode estar aguardando a data de notificação.\n- `IN_PROGRESS`: aguardando resposta.\n- `OPENED`: aberta para resposta pelo paciente.\n- `STARTED`: o paciente começou a responder.\n- `LATE`: atrasada.\n- `CANCELED`: cancelada manualmente pelo profissional ou pelo parceiro.\n- `CANCELED_LATE`: cancelada por atraso; uma nova submissão já foi gerada para o próximo período.\n- `CANCELED_IDLE`: cancelada porque a aplicação foi encerrada por inatividade.\n- `ANSWERED`: respondida pelo paciente.\n\n### Status das aplicações\n\n- `CREATED`, `IN_PROGRESS`, `PAUSED`, `FINISHED`.\n- `CANCELED_IDLE`: encerrada automaticamente por inatividade do paciente.\n- `CANCELED_WHATSAPP_LIMIT`: encerrada por limite de envios de WhatsApp.\n- `CANCELED_STALE`: encerrada por expiração.\n- `CANCELED_DELETED_PATIENT`: encerrada porque o paciente foi desvinculado.\n\n## Fluxo típico\n\n1. Cadastre o profissional (`POST /professionals`) ou vincule um profissional que já usa\n a HumanTrack (`POST /connect`).\n2. Cadastre os pacientes do profissional.\n3. Aplique instrumentos aos pacientes (crie aplicações).\n4. Os pacientes recebem notificações e respondem (submissões).\n5. Acompanhe resultados e evolução pelas submissões, gráficos de escore e relatórios, ou\n receba eventos por webhook (seção *Webhooks*).\n\n## Convenções\n\n- Datas e horas em RFC 3339 / ISO 8601 (`2026-01-05T12:00:00Z`), exceto os filtros de\n notificações, que usam apenas a data (`2026-01-05`).\n- Profissionais, pacientes e instrumentos são identificados por UUID; aplicações e\n submissões, por inteiro.\n- Listas paginadas usam `limit` (padrão: sem limite) e `offset` (padrão: 0).\n", "termsOfService": "https://humantrack.io/legal/termos", "title": "HumanTrack API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/connect": { "post": { "description": "Pede o vínculo de um profissional que já tem conta na HumanTrack ao parceiro. Retorna\n`202 VERIFICATION_LINK_SENT` quando o pedido é aceito (inclusive no reenvio de um pedido\npendente); o envio do e-mail de verificação é uma tentativa síncrona dentro da mesma\nrequisição (a latência inclui o provedor de e-mail), a resposta é `202` independentemente\nde a tentativa ter tido sucesso, e a entrega não é garantida. O profissional precisa\nconcluir a aprovação pelo link para o vínculo ficar ativo. Retorna `200 ALREADY_LINKED`\nquando o vínculo já está ativo.\n", "operationId": "requestAccountLink", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountLinkRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "message": "Professional is already linked to this partner", "status": "ALREADY_LINKED" }, "schema": { "$ref": "#/components/schemas/AccountLinkResponse" } } }, "description": "Profissional já vinculado ao parceiro." }, "202": { "content": { "application/json": { "example": { "message": "Verification link requested; the professional must confirm it by e-mail", "status": "VERIFICATION_LINK_SENT" }, "schema": { "$ref": "#/components/schemas/AccountLinkResponse" } } }, "description": "Pedido aceito; o envio do e-mail de verificação ao profissional foi tentado de forma\nsíncrona dentro desta requisição. A resposta é `202` mesmo que a tentativa de envio\nfalhe, e a entrega não é garantida.\n" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Solicitar vínculo de profissional", "tags": [ "Vínculo de conta" ] } }, "/disconnect/{professionalId}": { "post": { "description": "Encerra o vínculo do profissional com o parceiro (integração passa de `ACTIVE` para `INACTIVE`). Os webhooks deste profissional deixam de ser enviados.", "operationId": "disconnectProfessional", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Professional successfully disconnected", "status": "DISCONNECTED" }, "schema": { "$ref": "#/components/schemas/AccountLinkResponse" } } }, "description": "Profissional desvinculado." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Desvincular profissional", "tags": [ "Vínculo de conta" ] } }, "/forms/library": { "get": { "description": "Lista os instrumentos públicos da biblioteca, opcionalmente filtrados por tags.", "operationId": "listFormTemplateLibrary", "parameters": [ { "description": "IDs de tags separados por vírgula, por exemplo `1,4`. Retorna instrumentos com qualquer uma das tags.", "example": "1,4", "in": "query", "name": "tags", "required": false, "schema": { "pattern": "^\\s*\\d+\\s*(,\\s*\\d+\\s*)*$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/FormTemplate" }, "type": "array" } } }, "description": "Instrumentos da biblioteca." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Listar biblioteca de instrumentos", "tags": [ "Instrumentos" ] } }, "/forms/tags": { "get": { "description": "Lista todas as tags usadas para classificar os instrumentos da biblioteca.", "operationId": "listFormTemplateTags", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/FormTag" }, "type": "array" } } }, "description": "Tags disponíveis." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Listar tags de instrumentos", "tags": [ "Instrumentos" ] } }, "/forms/{formId}": { "get": { "description": "Retorna um instrumento com questões, opções, subescalas e faixas de interpretação.\nCom `format=pdf`, retorna o instrumento em PDF.\n", "operationId": "getFormTemplate", "parameters": [ { "$ref": "#/components/parameters/FormId" }, { "description": "Use `pdf` para receber o instrumento em PDF. Qualquer outro valor retorna JSON.", "in": "query", "name": "format", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormTemplate" } }, "application/pdf": { "schema": { "format": "binary", "type": "string" } } }, "description": "Instrumento." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Obter instrumento", "tags": [ "Instrumentos" ] } }, "/professionals": { "get": { "description": "Lista os profissionais vinculados ao parceiro, opcionalmente filtrando pelo `externalId`.", "operationId": "listProfessionals", "parameters": [ { "description": "Identificador do profissional no sistema do parceiro.", "example": "psm-8842", "in": "query", "name": "externalId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Professional" }, "type": "array" } } }, "description": "Profissionais vinculados ao parceiro." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Listar profissionais", "tags": [ "Profissionais" ] }, "post": { "description": "Cadastra um novo profissional na HumanTrack e o vincula ao parceiro com o `externalId`\ninformado. Se o e-mail já pertence a um profissional vinculado ao parceiro, a chamada é\nidempotente e retorna o profissional existente. Se o e-mail pertence a um profissional\nque ainda não é vinculado ao parceiro, retorna `403 PROFESSIONAL_CLAIM_REQUIRED`: use\n`POST /connect` para pedir o vínculo.\n", "operationId": "createProfessional", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProfessionalRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Professional" } } }, "description": "Profissional cadastrado (ou já vinculado ao parceiro)." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Cadastrar profissional", "tags": [ "Profissionais" ] } }, "/professionals/check": { "get": { "description": "Informa se existe um profissional com o e-mail e se ele está vinculado ao parceiro.\nUse antes de cadastrar para decidir entre `POST /professionals` e `POST /connect`.\nEspaços no e-mail são interpretados como `+` (e-mails com `+` enviados sem codificação).\n", "operationId": "checkProfessionalExistence", "parameters": [ { "description": "E-mail do profissional.", "example": "ana.souza@example.com", "in": "query", "name": "email", "required": true, "schema": { "format": "email", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfessionalLookupResponse" } } }, "description": "Resultado da verificação." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Verificar existência de profissional", "tags": [ "Profissionais" ] } }, "/professionals/{professionalId}": { "get": { "description": "Retorna um profissional vinculado ao parceiro.", "operationId": "getProfessional", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Professional" } } }, "description": "Profissional." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Obter profissional", "tags": [ "Profissionais" ] } }, "/professionals/{professionalId}/forms/applications": { "get": { "description": "Lista as aplicações criadas pelo profissional, com filtros, ordenação e paginação.", "operationId": "listFormApplicationsByProfessional", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/ApplicationStatusFilter" }, { "$ref": "#/components/parameters/FormTemplateIdFilter" }, { "$ref": "#/components/parameters/RecurrenceCycleFilter" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/OrderBy" }, { "$ref": "#/components/parameters/OrderDirection" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/FormApplication" }, "type": "array" } } }, "description": "Aplicações do profissional." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Listar aplicações do profissional", "tags": [ "Aplicações" ] } }, "/professionals/{professionalId}/forms/applications/{applicationId}": { "get": { "description": "Retorna uma aplicação com as submissões e dados relacionados.", "operationId": "getFormApplication", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/ApplicationId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormApplication" } } }, "description": "Aplicação." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Obter aplicação", "tags": [ "Aplicações" ] } }, "/professionals/{professionalId}/forms/applications/{applicationId}/finish": { "post": { "description": "Finaliza uma aplicação em andamento.", "operationId": "finishFormApplication", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/ApplicationId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormApplication" } } }, "description": "Aplicação finalizada." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Finalizar aplicação", "tags": [ "Aplicações" ] } }, "/professionals/{professionalId}/forms/applications/{applicationId}/update-recurrence": { "post": { "description": "Altera a recorrência e a próxima data de resposta de uma aplicação. As submissões\npendentes são canceladas antes da alteração.\n", "operationId": "updateFormApplicationRecurrence", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/ApplicationId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFormApplicationRecurrenceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormApplication" } } }, "description": "Aplicação atualizada." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Alterar recorrência da aplicação", "tags": [ "Aplicações" ] } }, "/professionals/{professionalId}/forms/recommend": { "post": { "description": "Sugere instrumentos da biblioteca a partir da descrição de um caso clínico. A\nrecomendação apoia a escolha do profissional e não substitui o julgamento clínico.\nNão inclua dados que identifiquem o paciente em `case_text`.\n", "operationId": "recommendInstruments", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationResponse" } } }, "description": "Recomendação." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Recomendar instrumentos", "tags": [ "Recomendação" ] } }, "/professionals/{professionalId}/forms/recommend/history": { "get": { "description": "Lista, paginado, o histórico de recomendações do profissional. Valores inválidos de `page` e `page_size` usam o padrão.", "operationId": "getRecommendationHistory", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "description": "Página, a partir de 1.", "in": "query", "name": "page", "required": false, "schema": { "default": 1, "type": "integer" } }, { "description": "Itens por página.", "in": "query", "name": "page_size", "required": false, "schema": { "default": 10, "type": "integer" } }, { "description": "Busca no texto do caso e da recomendação.", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationHistoryResponse" } } }, "description": "Histórico paginado." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Listar histórico de recomendações", "tags": [ "Recomendação" ] } }, "/professionals/{professionalId}/forms/submissions": { "get": { "description": "Lista as submissões de todos os pacientes do profissional, com filtros e paginação.", "operationId": "listSubmissionsByProfessional", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/SubmissionStatusFilter" }, { "$ref": "#/components/parameters/FormTemplateIdFilter" }, { "$ref": "#/components/parameters/FormApplicationIdFilter" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/FormSubmission" }, "type": "array" } } }, "description": "Submissões." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Listar submissões do profissional", "tags": [ "Submissões" ] } }, "/professionals/{professionalId}/forms/submissions/{submissionId}": { "delete": { "description": "Exclui permanentemente uma submissão do histórico do paciente.", "operationId": "deleteSubmission", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/SubmissionId" } ], "responses": { "200": { "$ref": "#/components/responses/Empty" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Excluir submissão", "tags": [ "Submissões" ] }, "get": { "description": "Retorna uma submissão com respostas, escores e classificação.", "operationId": "getSubmission", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/SubmissionId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormSubmission" } } }, "description": "Submissão." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Obter submissão", "tags": [ "Submissões" ] } }, "/professionals/{professionalId}/forms/submissions/{submissionId}/cancel": { "post": { "description": "Cancela uma submissão pendente sem apagar respostas já registradas. A submissão passa a `CANCELED`.", "operationId": "cancelSubmission", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/SubmissionId" } ], "responses": { "200": { "$ref": "#/components/responses/Empty" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Cancelar submissão", "tags": [ "Submissões" ] } }, "/professionals/{professionalId}/forms/submissions/{submissionId}/renotify": { "post": { "description": "Reenvia ao paciente a notificação de uma submissão pendente.", "operationId": "renotifySubmission", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/SubmissionId" } ], "responses": { "200": { "$ref": "#/components/responses/Empty" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Reenviar notificação da submissão", "tags": [ "Submissões" ] } }, "/professionals/{professionalId}/forms/{formId}/applications": { "post": { "description": "Aplica um instrumento a um paciente do profissional. A aplicação define a recorrência,\na data de início e as preferências de notificação. A resposta traz `urlToAnswer`, o link\nque o paciente usa para responder.\n", "operationId": "createFormApplication", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/FormId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFormApplicationRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormApplication" } } }, "description": "Aplicação criada." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Criar aplicação", "tags": [ "Aplicações" ] } }, "/professionals/{professionalId}/forms/{formId}/patients/{patientId}/notifications": { "get": { "description": "Lista as notificações enviadas ao paciente para um instrumento. Datas em formato\ninválido são ignoradas (o filtro correspondente não é aplicado).\n", "operationId": "listNotifications", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/FormId" }, { "$ref": "#/components/parameters/PatientId" }, { "description": "Data inicial (`AAAA-MM-DD`).", "in": "query", "name": "startDate", "required": false, "schema": { "format": "date", "type": "string" } }, { "description": "Data final (`AAAA-MM-DD`).", "in": "query", "name": "endDate", "required": false, "schema": { "format": "date", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PatientNotification" }, "type": "array" } } }, "description": "Notificações." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Listar notificações do paciente para um instrumento", "tags": [ "Notificações" ] } }, "/professionals/{professionalId}/patients": { "get": { "description": "Lista todos os pacientes do profissional.", "operationId": "listPatientsByProfessional", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Patient" }, "type": "array" } } }, "description": "Pacientes do profissional." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Listar pacientes do profissional", "tags": [ "Pacientes" ] }, "post": { "description": "Cadastra um paciente para o profissional. Apenas `name`, `surname`, `email` e\n`cellphone` são considerados no cadastro; use `PUT` para informar dados demográficos.\n", "operationId": "createPatient", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePatientRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Patient" } } }, "description": "Paciente cadastrado." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Cadastrar paciente", "tags": [ "Pacientes" ] } }, "/professionals/{professionalId}/patients/{patientId}": { "get": { "description": "Retorna um paciente do profissional.", "operationId": "getPatient", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/PatientId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Patient" } } }, "description": "Paciente." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Obter paciente", "tags": [ "Pacientes" ] }, "put": { "description": "Atualiza os dados de contato e demográficos de um paciente do\nprofissional. `name`, `surname` e `cellphone` são obrigatórios e\nsempre substituídos; os demais campos, se omitidos ou enviados como\n`null`, mantêm o valor já cadastrado (não são limpos). Veja\n`UpdatePatientRequest` para o detalhe.\n", "operationId": "updatePatient", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/PatientId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePatientRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Patient" } } }, "description": "Paciente atualizado. Conhecido: os campos opcionais omitidos ou\nenviados como `null` no corpo da requisição podem retornar como\n`null` nesta resposta mesmo quando o valor anterior foi mantido\nno cadastro; consulte `GET` no mesmo paciente para o estado\npersistido.\n" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Atualizar paciente", "tags": [ "Pacientes" ] } }, "/professionals/{professionalId}/patients/{patientId}/forms/applications": { "get": { "description": "Lista as aplicações de um paciente do profissional, com filtros, ordenação e paginação.", "operationId": "listFormApplicationsByPatient", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/PatientId" }, { "$ref": "#/components/parameters/ApplicationStatusFilter" }, { "$ref": "#/components/parameters/FormTemplateIdFilter" }, { "$ref": "#/components/parameters/RecurrenceCycleFilter" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/OrderBy" }, { "$ref": "#/components/parameters/OrderDirection" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/FormApplication" }, "type": "array" } } }, "description": "Aplicações do paciente." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Listar aplicações do paciente", "tags": [ "Aplicações" ] } }, "/professionals/{professionalId}/patients/{patientId}/forms/submissions": { "get": { "description": "Lista as submissões de um paciente, com filtros e paginação. Indicado para a linha do tempo do paciente.", "operationId": "listSubmissionsByPatient", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/PatientId" }, { "$ref": "#/components/parameters/SubmissionStatusFilter" }, { "$ref": "#/components/parameters/FormTemplateIdFilter" }, { "$ref": "#/components/parameters/FormApplicationIdFilter" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/FormSubmission" }, "type": "array" } } }, "description": "Submissões do paciente." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Listar submissões do paciente", "tags": [ "Submissões" ] } }, "/professionals/{professionalId}/patients/{patientId}/forms/{formId}/applications": { "get": { "description": "Lista as aplicações de um instrumento para um paciente, com filtros, ordenação e paginação.", "operationId": "listFormApplicationsByPatientAndForm", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/PatientId" }, { "$ref": "#/components/parameters/FormId" }, { "$ref": "#/components/parameters/ApplicationStatusFilter" }, { "$ref": "#/components/parameters/RecurrenceCycleFilter" }, { "$ref": "#/components/parameters/StartDate" }, { "$ref": "#/components/parameters/EndDate" }, { "$ref": "#/components/parameters/OrderBy" }, { "$ref": "#/components/parameters/OrderDirection" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/FormApplication" }, "type": "array" } } }, "description": "Aplicações do paciente para o instrumento." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Listar aplicações do paciente para um instrumento", "tags": [ "Aplicações" ] } }, "/professionals/{professionalId}/patients/{patientId}/forms/{formId}/applications/cancel": { "post": { "description": "Encerra de uma vez todas as aplicações ativas de um instrumento para o paciente. Cada\naplicação encerrada passa a `FINISHED` e suas submissões pendentes são canceladas.\nAplicações já finalizadas ou canceladas são ignoradas, então a chamada é idempotente.\n", "operationId": "cancelFormApplicationsByPatientAndForm", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/PatientId" }, { "$ref": "#/components/parameters/FormId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelFormApplicationsResult" } } }, "description": "Resultado do cancelamento." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Cancelar aplicações de um instrumento para o paciente", "tags": [ "Aplicações" ] } }, "/professionals/{professionalId}/patients/{patientId}/forms/{formId}/longitudinal-analysis": { "get": { "description": "Retorna a análise longitudinal, gerada por IA, da trajetória do paciente em um\ninstrumento. Gera a análise quando ainda não existe e a regenera quando há novas\nsubmissões respondidas desde a última geração; caso contrário, retorna a análise em\ncache. Como a geração dispara uma chamada de IA, consulte antes\n`/longitudinal-analysis/status` para saber se esta chamada vai gerar uma nova análise.\nA análise apoia a interpretação clínica e não substitui o julgamento do profissional.\nRetorna `403` quando o plano do profissional não inclui análise por IA.\n", "operationId": "getPatientLongitudinalAnalysis", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/PatientId" }, { "$ref": "#/components/parameters/FormId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientLongitudinalAnalysis" } } }, "description": "Análise longitudinal." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Obter análise longitudinal", "tags": [ "Relatórios" ] } }, "/professionals/{professionalId}/patients/{patientId}/forms/{formId}/longitudinal-analysis/status": { "get": { "description": "Informa, sem disparar geração por IA, se existe análise longitudinal, se ela está\ndesatualizada e as datas relevantes. Retorna `403` quando o plano do profissional não\ninclui análise por IA.\n", "operationId": "getPatientLongitudinalAnalysisStatus", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/PatientId" }, { "$ref": "#/components/parameters/FormId" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientLongitudinalAnalysisStatus" } } }, "description": "Estado da análise." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Consultar estado da análise longitudinal", "tags": [ "Relatórios" ] } }, "/professionals/{professionalId}/patients/{patientId}/forms/{formId}/report": { "get": { "description": "Gera o relatório em PDF das submissões do paciente em um instrumento. Por padrão\nretorna o PDF binário. Com `format=json`, retorna o PDF em base64 e, quando disponível,\num link HTTPS público válido por 15 minutos (`pdfUrl`); sem o link, use `pdfBytes`.\n", "operationId": "getPatientFormReport", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/PatientId" }, { "$ref": "#/components/parameters/FormId" }, { "description": "Use `json` para receber o PDF em base64. Qualquer outro valor retorna o PDF binário.", "in": "query", "name": "format", "required": false, "schema": { "default": "pdf", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatientFormReport" } }, "application/pdf": { "schema": { "format": "binary", "type": "string" } } }, "description": "Relatório.", "headers": { "Content-Disposition": { "description": "Presente na resposta binária (`attachment; filename=patient__form__summary.pdf`).", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Gerar relatório em PDF", "tags": [ "Relatórios" ] } }, "/professionals/{professionalId}/patients/{patientId}/forms/{formId}/score-graph": { "get": { "description": "Retorna os dados prontos para gráfico da evolução dos escores do paciente em um\ninstrumento: uma série para o escore global e uma por subescala, com as faixas de\ninterpretação.\n", "operationId": "getPatientFormScoreGraph", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/PatientId" }, { "$ref": "#/components/parameters/FormId" }, { "description": "Considera respostas a partir desta data e hora (RFC 3339). Não pode ser posterior a `endDate`.", "in": "query", "name": "startDate", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Considera respostas até esta data e hora (RFC 3339).", "in": "query", "name": "endDate", "required": false, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreGraphResponse" } } }, "description": "Dados do gráfico." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Obter gráfico de escores", "tags": [ "Relatórios" ] } }, "/professionals/{professionalId}/patients/{patientId}/inactivate": { "post": { "description": "Inativa a relação entre profissional e paciente, impedindo novas aplicações.", "operationId": "inactivatePatient", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/PatientId" } ], "responses": { "200": { "$ref": "#/components/responses/Empty" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Inativar paciente", "tags": [ "Pacientes" ] } }, "/professionals/{professionalId}/patients/{patientId}/reactivate": { "post": { "description": "Reativa a relação entre profissional e paciente inativada anteriormente.", "operationId": "reactivatePatient", "parameters": [ { "$ref": "#/components/parameters/ProfessionalId" }, { "$ref": "#/components/parameters/PatientId" } ], "responses": { "200": { "$ref": "#/components/responses/Empty" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "summary": "Reativar paciente", "tags": [ "Pacientes" ] } } }, "security": [ { "ApiKey": [], "ApiSecret": [] } ], "servers": [ { "description": "Produção", "url": "https://api.humantrack.io/third-party/api/v1" }, { "description": "Desenvolvimento local", "url": "http://localhost:3000/third-party/api/v1" } ], "tags": [ { "description": "Biblioteca de instrumentos disponíveis para aplicação.", "name": "Instrumentos" }, { "description": "Cadastro e consulta de profissionais vinculados ao parceiro.", "name": "Profissionais" }, { "description": "Vínculo de profissionais que já usam a HumanTrack ao parceiro.", "name": "Vínculo de conta" }, { "description": "Pacientes de um profissional.", "name": "Pacientes" }, { "description": "Aplicações de instrumentos a pacientes.", "name": "Aplicações" }, { "description": "Submissões geradas pelas aplicações, com respostas e escores.", "name": "Submissões" }, { "description": "Gráficos, análises longitudinais e relatórios em PDF.", "name": "Relatórios" }, { "description": "Notificações enviadas aos pacientes.", "name": "Notificações" }, { "description": "Recomendação de instrumentos a partir de um caso clínico.", "name": "Recomendação" }, { "description": "Eventos que a HumanTrack envia ao endpoint do parceiro. O endpoint é cadastrado pela\nequipe HumanTrack, que entrega um secret exibido uma única vez. Cada entrega é um\n`POST` JSON assinado com HMAC-SHA256; deduplique pelo `id` do envelope (entrega\n*at-least-once*, até 8 tentativas).\n", "name": "Webhooks" } ], "webhooks": { "applicationCanceledIdle": { "post": { "description": "Enviado quando uma aplicação criada pelo parceiro é encerrada automaticamente por\ninatividade do paciente, enquanto o vínculo do profissional com o parceiro estiver\nativo. Uma aplicação pode ser reaberta por uma resposta tardia e encerrada de novo;\n`canceledAt` distingue os ciclos.\n", "operationId": "onApplicationCanceledIdle", "parameters": [ { "$ref": "#/components/parameters/WebhookEventId" }, { "$ref": "#/components/parameters/WebhookSignature" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationCanceledIdleEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Entrega aceita. Responda em até 10 segundos; o corpo é ignorado." }, "default": { "description": "Qualquer status fora de 2xx, timeout ou erro de conexão conta como falha e dispara o reenvio." } }, "security": [], "summary": "Aplicação encerrada por inatividade", "tags": [ "Webhooks" ] } }, "submissionAnswered": { "post": { "description": "Enviado quando o paciente responde uma submissão de uma aplicação criada pelo\nparceiro, enquanto o vínculo do profissional com o parceiro estiver ativo. Submissões\nde envios em lote não geram evento. O payload traz apenas identificadores; consulte o\ndetalhe pela API (`getSubmission`).\n", "operationId": "onSubmissionAnswered", "parameters": [ { "$ref": "#/components/parameters/WebhookEventId" }, { "$ref": "#/components/parameters/WebhookSignature" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionAnsweredEvent" } } }, "required": true }, "responses": { "2XX": { "description": "Entrega aceita. Responda em até 10 segundos; o corpo é ignorado." }, "default": { "description": "Qualquer status fora de 2xx, timeout ou erro de conexão conta como falha e dispara o reenvio." } }, "security": [], "summary": "Submissão respondida", "tags": [ "Webhooks" ] } } } }