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 campostatus 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.nullpara um resultadoplanned.biomarker_nameecategory— 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.nullpara um resultadoplannede para resultados que o laboratório comunicou sem código.valueevalue_operator— a medição efetiva. O operador éeq(igual) para valores exatos, oult/gtquando 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 devalue. Um limite deixado em aberto pelo laboratório énull, pelo que um intervalo unilateral como< 50chega comonormal_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 qualreference_range_labénull.nullquando o intervalo existe e num resultadoplanned. Vê Quando não existe intervalo do laboratório.aniva_range— Valores de comparação compilados pela Aniva, na mesma escala devalue. 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. Usareference_range_labcomo referência para o resultado.nullquando a tua chave não tem o scopeaniva_ranges_viewou 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).nullquando o laboratório não anexou nenhuma.status_reason— o motivo pelo qual um resultadolikely_wrongé duvidoso, ou um resultadofaultouundeliverableé inutilizável.nullpara todos os outros estados. Distinto decomment, 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 deorigindo 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.nullpara um resultadoplanned.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.
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.
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
Quandoreference_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
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.nullpara um resultadoplanned.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.nullpara um resultadoplannede 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.nullquando o laboratório não anexou nenhuma.status_reason— o motivo pelo qual um resultadolikely_wrongé duvidoso, ou um resultadofaultouundeliverableé inutilizável.nullpara 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 arrayvariants. 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 comrs_id,allele,reference_allelee notação HGVS opcional.
Documentos
O arraydocuments 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 aGET /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_uploadoupartner_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;nullquando 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
emaildo perfil. Um endereço@aniva.emailprovisório é recusado. - O e-mail mostra o nome e o logótipo do grupo de perfis principal do perfil.
- O e-mail está no
languagedo perfil, inglês por predefinição. - Define
with_reportscomotruepara anexar os relatórios laboratoriais. - Adiciona
notepara mostrar uma nota pessoal no e-mail, no máximo 1 000 caracteres.
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. Defineresults_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_emailsrecebe-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_viewao paciente. Sem isso, o pedido devolve403.
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
embederesults_viewpara o paciente. Pede à Aniva o scopeembed. - 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.
routeabre uma das páginas que disponibilizamos: a lista de biomarcadores, um biomarcador ou o Twin 3D.appearancedefine o tema, a cor dos botões e das ligações e se o teu logótipo é mostrado.reportlimita a página a uma marcação, a um pedido de kit de teste em casa ou a um relatório laboratorial que carregaste comPOST /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.