Saltar para o conteúdo principal
Depois de a colheita de sangue ser confirmada e de o laboratório processar as amostras, os resultados ficam disponíveis na marcação. Os resultados são obtidos através de GET /api/v1/appointments/{id}/results e incluem resultados de biomarcadores clínicos, resultados de biomarcadores genéticos e documentos de relatórios do laboratório para transferência.

Estado dos resultados

O campo status de nível superior na resposta dos resultados indica o progresso geral do processamento: Os resultados individuais na resposta têm o seu próprio estado por resultado (vê abaixo), por isso podes mostrar resultados parciais enquanto o estado geral ainda está em in_progress. Para saberes quando os resultados mudam, subscreve os webhooks. appointment.results.updated é acionado em cada alteração do corpo dos resultados e appointment.results.completed é acionado quando o estado de nível superior passa para completed. As encomendas de kit de teste em casa enviam os mesmos eventos com o prefixo home_kit_order.. Cada evento inclui o URL dos resultados a obter. Podes continuar a consultar este endpoint periodicamente para reconciliar. O array submissions divide o estado de nível superior por requisição de laboratório. Uma colheita de sangue que abranja vários tubos ou vários laboratórios tem várias entradas, cada uma com o lab_code (código de barras do tubo) com que foi registada e o seu próprio estado in_progress / completed / fault. Uma entrada fault foi rejeitada ou abandonada no laboratório e nunca vai enviar resultados: muitas vezes a amostra foi transferida para outro laboratório, que regista então a sua própria entrada. O estado de nível superior fica completed quando todas as entradas estiverem encerradas e pelo menos uma tiver enviado resultados. Cada resultado recebido e cada documento inclui o mesmo lab_code, para que saibas de que tubo veio um valor.

Resultados clínicos

Os resultados clínicos representam medições padrão de biomarcadores sanguíneos — como níveis de vitamina D, colesterol, hormonas da tiroide, entre outros. Cada resultado clínico inclui:
  • id — o identificador da linha de resultado do laboratório. Mantém-se igual quando o laboratório corrige essa linha, por isso usa-o para fazer upsert. null para um resultado planned.
  • biomarker_name e category — o que foi medido e o seu grupo (por exemplo, Vitaminas, Hormonas).
  • lab_code — o código de laboratório (código de barras do tubo) com que o resultado foi registado, um dos códigos de laboratório da encomenda. null para um resultado planned e para resultados que o laboratório comunicou sem código.
  • value e value_operator — a medição efetiva. O operador é eq (igual) para valores exatos, ou lt/gt quando o laboratório comunica um valor abaixo ou acima do intervalo mensurável.
  • unit — a unidade de medição (por exemplo, ng/mL, µIU/mL).
  • reference_range_lab — limites mínimo/máximo normais e ótimos comunicados pelo laboratório para este resultado, convertidos para a mesma escala de value. Um limite deixado em aberto pelo laboratório é null, pelo que um intervalo unilateral como < 50 chega como normal_min: null, normal_max: 50. Cada resultado inclui o intervalo com o qual foi medido, para que um paciente com resultados de várias colheitas de sangue ou laboratórios tenha o intervalo certo para cada resultado.
  • reference_range_lab_absent_reason — o motivo pelo qual reference_range_lab é null. null quando o intervalo existe e num resultado planned. Vê Quando não existe intervalo do laboratório.
  • aniva_range — Valores de comparação compilados pela Aniva, na mesma escala de value. Variam consoante a idade, o sexo e a semana de gravidez. normal_* é o intervalo geral. optimal_* é um intervalo mais restrito. Os valores são apenas informativos. Não são aconselhamento médico, não são um diagnóstico nem uma avaliação do resultado. A Aniva não define nenhum indicador com base neles. Usa reference_range_lab como referência para o resultado. null quando a tua chave não tem o scope aniva_ranges_view ou quando a Aniva não tem valores para este biomarcador.
  • tested_at — a data em que a análise foi realizada.
  • comment — anotação em texto livre do laboratório sobre este resultado específico (por exemplo, orientações sobre o intervalo de referência, avisos sobre a qualidade da amostra). null quando o laboratório não anexou nenhuma.
  • status_reason — o motivo pelo qual um resultado likely_wrong é duvidoso, ou um resultado fault ou undeliverable é inutilizável. null para todos os outros estados. Distinto de comment, que é a própria nota do laboratório e está muitas vezes vazia em resultados com erro.
  • origin — quem entregou o documento de onde vem o valor, com os mesmos valores de origin do documento abaixo. Um valor de um documento carregado (member_upload, staff_upload, partner_upload) resulta da leitura do ficheiro pela Aniva, e não de um relatório do laboratório: verifica-o face ao ficheiro antes de uso clínico. null para um resultado planned.
  • lab_reported — a linha do relatório do laboratório executor, tal como impressa e sem conversão. Vê abaixo.

Intervalos Aniva

aniva_range contém valores de comparação que a Aniva compilou a partir de fontes publicadas e da sua própria curadoria. Os intervalos variam consoante a idade, o sexo e a semana de gravidez. sources lista as fontes publicadas que a Aniva registou para os valores. A lista pode estar vazia.
Os valores são informação geral. Não são aconselhamento médico, não são um diagnóstico, não são um achado médico nem uma avaliação de um resultado. A Aniva não os fornece como dispositivo médico. A Aniva não compara um resultado com eles nem define nenhum indicador com base neles. reference_range_lab e a avaliação por um médico continuam a ser a referência para um resultado.
Regras para o teu produto:
  • Mostra o intervalo Aniva apenas em complemento ao intervalo do laboratório, nunca em seu lugar.
  • Se derivares um indicador, um aviso ou uma recomendação a partir do intervalo Aniva, fazes isso em teu próprio nome e sob a tua própria responsabilidade.
  • Mostra o aviso do teu contrato com a Aniva sempre que mostrares o intervalo Aniva.
Para obteres acesso, assina o breve contrato sobre os intervalos Aniva. Depois adicionamos o scope aniva_ranges_view à tua chave. Os valores podem mudar sem aviso prévio.

Valores normalizados versus a linha própria do laboratório

value, unit e reference_range_lab estão normalizados: convertemos cada medição para a unidade canónica do biomarcador e apresentamo-la com o nosso próprio nome de biomarcador, para que o mesmo analito seja comparável entre laboratórios e ao longo do tempo. É isso que queres para analisar tendências e comparar entre laboratórios, e não é o que um médico vê no PDF do laboratório — a fosfatase alcalina impressa como 48 U/l (40 - 129) chega-te como 0.8 µkat/L. lab_reported traz essa linha impressa em paralelo: o nome e o código do analito do laboratório, o valor e a unidade tal como impressos, o intervalo de referência tanto em texto (< 50, > 55, 40 - 129) como nos próprios limites não convertidos do laboratório, além do indicador de valor anormal, do estado do resultado e da nota. Usa lab_reported quando um humano estiver a reconciliar os teus dados com o relatório do laboratório, e os campos canónicos para tudo o que for calculado. Só os campos que o laboratório realmente enviou são preenchidos; nada em lab_reported é inferido, preenchido por omissão ou convertido, e todo o objeto é null quando não temos registo bruto para um resultado.

Quando não existe intervalo do laboratório

Quando reference_range_lab é null, reference_range_lab_absent_reason indica-te porquê: Alguns laboratórios imprimem um alvo ou um nível de risco em vez de um intervalo de referência, por exemplo Ziel: <200. >240 hoch ou <5.7 neg >=6.5 pos. Estes não entram em reference_range_lab, pelo que os seus limites são null e o motivo é lab_text_only. Mostra o texto impresso tal como está. Um intervalo unilateral como < 20 é um intervalo. Chega em reference_range_lab com um limite null e o motivo é null. Mantém o lado aberto sem o fechar quando o mostrares.

Estados dos resultados clínicos

Ao mostrares resultados aos pacientes, usa diretamente o campo value — já reflete o valor corrigido quando existe.
Nunca apresentes um resultado fault como um achado — o seu value está preenchido, mas confirmado como incorreto.

Resultados genéticos

Os resultados genéticos representam achados ao nível do gene a partir de análises de ADN. Cada resultado corresponde a um gene (por exemplo, APOE, MTHFR) e inclui:
  • id — o identificador da linha de resultado do laboratório. Mantém-se igual quando o laboratório corrige essa linha, por isso usa-o para fazer upsert. null para um resultado planned.
  • gene — o símbolo do gene.
  • lab_code — o código de laboratório (código de barras do tubo) com que o resultado foi registado. null para um resultado planned e para resultados que o laboratório comunicou sem código.
  • genotype — o genótipo detetado (por exemplo, E3/E4).
  • clinical_significance — uma classificação do achado baseada no ACMG.
  • risk_description — uma explicação legível por humanos do que significa o genótipo.
  • comment — anotação em texto livre do laboratório sobre este resultado específico. null quando o laboratório não anexou nenhuma.
  • status_reason — o motivo pelo qual um resultado likely_wrong é duvidoso, ou um resultado fault ou undeliverable é inutilizável. null para todos os outros estados.
  • origin — quem entregou o documento de onde vem o valor, tal como nos resultados clínicos.
  • variants — as variantes genéticas específicas detetadas, cada uma com detalhe ao nível de SNV.

Valores de significado clínico

Estados de resultados genéticos

Estrutura da variante

Cada resultado genético contém um array variants. Cada variante inclui:
  • name — nome comum (p. ex., APOE E4).
  • clinical_significance — significado ao nível da variante (pode diferir do significado ao nível do gene).
  • conditions — doenças/condições associadas com descrições.
  • snvs — as variantes de nucleótido único subjacentes, cada uma com rs_id, allele, reference_allele e notação HGVS opcional.

Documentos

O array documents na resposta de resultados contém referências a ficheiros de relatórios laboratoriais para transferência. Cada documento tem:
  • id — um UUID de ficheiro. Passa este valor a GET /api/v1/documents/{id} para transferir o ficheiro.
  • file_name — o nome do ficheiro, o mesmo que a transferência envia (p. ex., 20260405 - Quade Befund - 7642001234.pdf).
  • original_file_name — o nome do ficheiro exatamente como foi entregue pelo laboratório ou por quem o carregou (p. ex., 7642001234_B0012_FA_E.pdf).
  • origin — quem entregou o ficheiro: lab, member_upload, staff_upload ou partner_upload (carregaste-o com Carregar documento).
  • content_type — o tipo de média do ficheiro (p. ex., application/pdf). A maioria dos relatórios são PDFs. Digitalizações carregadas podem ser imagens ou ficheiros CSV.
  • etag — a versão do conteúdo do ficheiro; muda sempre que os bytes mudam. Guarda-a e transfere novamente apenas quando mudar. É a entity tag HTTP padrão, tal como usada no S3 ou no Google Cloud Storage.
  • size_bytes — o tamanho do ficheiro em bytes.
  • lab_code — o código de laboratório (código de barras do tubo) a que o relatório pertence; null quando o laboratório não registou nenhum.
O acesso aos documentos é validado com base no perfil a que o documento pertence.

Enviar resultados por e-mail ao cliente

Podes avisar o cliente por e-mail de que os resultados estão prontos. Chama Enviar resultados por e-mail para uma marcação ou Enviar resultados por e-mail para um pedido de kit de teste em casa. Cada chamada envia um e-mail. As chamadas não são deduplicadas.
  • O e-mail vai para o email do perfil. Um endereço @aniva.email provisório é recusado.
  • O e-mail mostra o nome e o logótipo do grupo de perfis principal do perfil.
  • O e-mail está no language do perfil, inglês por predefinição.
  • Define with_reports como true para anexar os relatórios laboratoriais.
  • Adiciona note para mostrar uma nota pessoal no e-mail, no máximo 1 000 caracteres.
Se o perfil tiver desativado os e-mails transacionais, a chamada devolve 409 com o motivo unsubscribed. Para voltar a ativá-los, define transactional_emails_enabled como true com Atualizar perfil.

E-mails de resultados prontos

Podes receber um e-mail quando os resultados de uma reserva estiverem prontos. Define results_ready_emails com até 5 endereços em Criar marcação ou Criar pedido de kit de teste em casa. Altera a lista mais tarde com Atualizar marcação ou Atualizar pedido de kit de teste em casa; [] desativa os e-mails.
  • Pede-nos para definirmos endereços de e-mail predefinidos para o teu grupo de perfis. Uma reserva criada sem results_ready_emails recebe-os. Uma lista substitui-os nessa reserva, por isso inclui o teu endereço de e-mail predefinido para o manter. [] não envia nenhum e-mail.
  • Cada endereço recebe um e-mail assim que todos os resultados laboratoriais da reserva forem finais.
  • Um endereço adicionado depois de os resultados serem finais recebe o e-mail de imediato.
  • O e-mail tem uma ligação para a página de resultados no painel de administração da Aniva. O cliente não o recebe.
  • A tua chave precisa de acesso results_view ao paciente. Sem isso, o pedido devolve 403.

Mostrar resultados na tua app

Criar sessão incorporada devolve um URL de utilização única para uma página de resultados só de leitura. Abre-o numa WebView da tua app para que o paciente veja os resultados sem iniciar sessão.
  • A tua chave precisa dos scopes embed e results_view para o paciente. Pede à Aniva o scope embed.
  • Chama-o a partir do teu servidor sempre que o paciente abrir os resultados. O URL funciona uma vez e durante 5 minutos, e a página mantém depois uma sessão de 60 minutos.
  • route abre uma das páginas que disponibilizamos: a lista de biomarcadores, um biomarcador ou o Twin 3D.
  • appearance define o tema, a cor dos botões e das ligações e se o teu logótipo é mostrado.
  • report limita a página a uma marcação, a um pedido de kit de teste em casa ou a um relatório laboratorial que carregaste com POST /api/v1/documents. O paciente vê então apenas os resultados desse relatório.
  • A página mostra apenas resultados laboratoriais, tal como esta API. Não mostra ficheiros, chat nem definições.

Exemplo de resposta de resultados