Os endpoints de encomendas de kit de teste em casa requerem o scope
home_kit_orders_view (leitura) ou home_kit_orders_manage
(escrita). Ativar também aceita o scope mais restrito
home_kit_orders_activate. Obter resultados e
Enviar resultados por email requerem adicionalmente results_view — os resultados
de laboratório e os documentos estão sempre protegidos por ele.Campos
UUID gerado automaticamente pela Aniva. Usa-o para atualizar a encomenda, trocar o painel, ativá-la, cancelá-la
e obter resultados.
Estado atual do ciclo de vida. Um de
pending, dispatched, activated ou cancelled. Consulta
Ciclo de vida abaixo. A granularidade de conclusão dos resultados de laboratório (in_progress vs. completed) é
obtida em Obter resultados.A morada para onde enviar o kit — um de dois formatos:
{location_id} a referenciar um
local de testes conhecido, ou os campos de morada inline (name, street, city, postal_code,
country_code; company_name / house_number / address_line_2 / state / phone / email
opcionais — o mesmo vocabulário da API de locais). Indica exatamente um — uma referência de local
ou uma morada inline, não ambos.Packstation ou Postfiliale (apenas Alemanha): define
street como Packstation ou Postfiliale,
house_number como o número de três dígitos da estação e address_line_2 como o DHL
Postnummer do destinatário (6–10 dígitos, espaços permitidos). Sem o Postnummer, a encomenda não pode ser registada.
Um Postfach não é suportado.Timestamp ISO 8601 da atualização mais recente. Nulo se a encomenda de kit de teste em casa nunca tiver sido atualizada.
O objeto de perfil completo do paciente, incluído em todas as respostas de encomenda de kit de teste em casa.
O painel associado à encomenda de kit de teste em casa — sempre exatamente uma entrada de
{ panel_id, added_at },
porque um kit de teste em casa corresponde 1:1 a um produto de kit físico. Cruza o panel_id com
Listar painéis.Biomarcadores associados à encomenda de kit de teste em casa fora do painel. Cada entrada é
{ biomarker_id, added_at }. Cruza cada biomarker_id com
Listar biomarcadores com home_kit=true. Numa encomenda normal, são análises avulso
além do painel; num kit de substituição, são o que o laboratório
volta a analisar.A encomenda de kit de teste em casa que esta substitui, quando se trata de um kit de substituição.
null numa
encomenda normal.Endereços que recebem um email assim que todos os resultados de laboratório forem finais, em minúsculas. Sempre presente —
vazio quando desativado. Define-o em Criar ou
Atualizar. Consulta
Emails de resultados prontos.
Os teus próprios pares chave/valor, devolvidos exatamente como enviados e nunca interpretados pela Aniva. Sempre presente numa
leitura —
{} quando não defines nenhum. No máximo 20 chaves; as chaves seguem [A-Za-z0-9_-] e têm no máximo 40
caracteres; os valores são uma string, um número ou um booleano, com strings até 500 caracteres; 16 384
bytes serializados no total. As chaves que começam por aniva_ são reservadas. Em
Atualizar, os metadados são combinados: as chaves que omites mantêm-se, uma
chave enviada como null é eliminada e {} limpa tudo. A validação é tudo ou nada. Nunca coloques
dados pessoais ou clínicos em metadata — não são tratados como dados de paciente.O código da amostra de laboratório. Um código, três funções: o código sob o qual os resultados de laboratório são reportados, o que está impresso
no kit físico e o que o paciente lê na caixa como código de ativação. Atribuído quando
o kit é embalado —
null enquanto a encomenda está pending, exceto depois de a Aniva reenviar um kit (consulta
Ciclo de vida). Sempre só de leitura. Encontra a encomenda de um kit em
mão com GET /api/v1/home-kit-orders?lab_code=….O timestamp de colheita comunicado através de Ativar — o momento em que
o paciente recolheu efetivamente a amostra, como instante UTC.
null até o kit ser ativado.
Esta é a hora de colheita que consta no relatório de laboratório.Os volumes associados a esta encomenda, por ordem da associação mais antiga, cada um
{ id, added_at } — o kit a
caminho do paciente e, nos kits com devolução rastreada, a amostra a caminho de volta para
o laboratório, aparecendo mal as etiquetas são impressas. Vazio enquanto a encomenda está
pending, exceto depois de a Aniva reenviar um kit. Lê os
volumes completos numa única chamada com GET /api/v1/shipments?home_kit_order_id={id} — consulta
Envios.Ciclo de vida
As encomendas de kit de teste em casa expõem quatro estados de ciclo de vida:
Quando a Aniva reenvia um kit perdido, a encomenda volta a
pending, mas mantém o seu lab_code e os
pacotes anteriores em shipments. O novo kit leva o mesmo código. Uma etiqueta de devolução não utilizada segue na
nova caixa. Apenas a Aniva faz estas duas transições; a API não as disponibiliza. Cada transição envia um
webhook home_kit_order.pending ou home_kit_order.cancelled.
Os estados da encomenda de kit de teste em casa são intencionalmente pouco granulares. O progresso
da entrega de ida e volta do paciente é seguido nos envios da encomenda —
dispatched significa que o kit tem etiqueta e código de laboratório, não que já tenha saído; o
status do envio de ida indica se já saiu. O processamento dos resultados laboratoriais está nas
submissões. A conclusão dos resultados laboratoriais (in_progress vs completed) é exposta
através de Obter resultados — o campo status de nível
superior fica in_progress até todas as submissões fecharem, passando depois a completed — ou
fault quando todas as submissões falharam sem reportar.Seguir os pacotes
destination é o laboratório), emparelhados através de paired_with. O
pacote de devolução fica pending — com o número de seguimento já conhecido — até o paciente o enviar
pelo correio. Um kit de microbioma intestinal surge como um único envio: o kit para o paciente. O seu envelope de devolução é
pré-pago e sem seguimento, pelo que nada é reservado para o regresso. booked_by indica quem reservou a
etiqueta: "aniva" ou "external". Apenas um pacote "aniva" pode ser alterado aqui, e apenas as suas
notes depois de a etiqueta ser impressa. Cada pacote inclui os status_updates completos da transportadora,
incluindo o detail_code da DHL para um reencaminhamento para uma estação de correios.
home_kit_orders no envio lista apenas as encomendas no teu contexto de acesso. Consulta
Acesso.
Listar encomendas de kits de teste em casa
Obtém todas as encomendas de kits de teste em casa acessíveis à tua chave de API:?profile_id={uuid} para filtrar por um perfil específico, ou ?lab_code={code} para
associar um kit físico em mão à respetiva encomenda — o primeiro passo natural de um fluxo de ativação.
Criar uma encomenda de kit de teste em casa
Pede uma encomenda de kit de teste em casa para o perfil de um paciente:profile_id, uma delivery_address e um único panel_id. A encomenda é criada no estado pending.
Passa um cabeçalho Idempotency-Key opcional para que uma nova tentativa não encomende um segundo kit — consulta Idempotência.
Exatamente um painel, porque um kit de teste em casa corresponde 1:1 a um produto físico — o painel é o kit. Apenas os painéis que a Aniva configurou como kits de teste em casa podem ser encomendados; qualquer outro painel é rejeitado com 422. É obrigatório na criação porque a encomenda entra imediatamente na fila de embalagem e esta pode começar logo de seguida. Enquanto a encomenda estiver pending, podes trocar o painel através de Atualizar.
Para enviar um segundo kit por um que não conseguiu fornecer resultados, passa replaces_home_kit_order_id em vez de escolher um painel — consulta Kits de substituição.
Kits de substituição
Por vezes, um kit não consegue fornecer resultados: o paciente não conseguiu encher o tubo, a amostra chegou com pouco material, o laboratório não conseguiu analisar parte dela. Encomenda uma substituição para ele:replaces_home_kit_order_id.
A encomenda que substituis não é alterada. Mantém o seu estado, o seu código de laboratório e quaisquer resultados já registados nela, pelo que um paciente que ainda envie o primeiro kit pelo correio recebe o que o laboratório conseguir ler dele.
O painel é herdado. Deixa panel_id de fora e a substituição leva o painel da encomenda que substitui — é o que o paciente comprou e a marca da caixa. Envia um painel diferente apenas para uma substituição de painel completo; um painel e um subconjunto de marcadores em conjunto são rejeitados com 422, porque um subconjunto só faz sentido no painel de onde foi escolhido. O painel de uma substituição também não pode ser trocado depois.
Tu escolhes o que é repetido. Envia biomarker_ids com os marcadores que falharam e o laboratório repete apenas esses, pelo que o kit segue apenas com os tubos de que precisam. Deixa-o de fora para repetir todo o painel — a escolha certa quando nada foi analisado. Isto não precisa de scope adicional: repetir marcadores que o paciente já pagou não é uma seleção à la carte. Esses marcadores não podem ser removidos depois, porque constituem toda a requisição.
Os marcadores são repetidos pelos grupos do painel, não um a um. Indicar um marcador de um
grupo repete todo esse grupo, porque não é possível fazer um pedido ao laboratório que reporte
mais do que foi requisitado. Uma substituição para um único marcador pode, por isso, regressar com
mais do que um resultado, e o número de tubos pode ser maior do que a lista de marcadores sugere.
pending ou dispatched, uma segunda criação para a mesma encomenda devolve 409 indicando-a. Os resultados chegam com o lab_code da própria substituição, através do seu Obter resultados.
Uma substituição não é a forma de lidar com um pacote que nunca chegou. Avisa antes a Aniva: trata-se de um reenvio da mesma encomenda com o mesmo código de laboratório, não de uma nova.
Atualizar uma encomenda de kit de teste em casa
Altera a morada de entrega, troca o painel, atualiza os teus metadados ou substitui os emails de resultados prontos:panel_id substitui o painel associado — com exatamente um painel por kit, uma troca é a única operação de painel que faz sentido, razão pela qual não existem endpoints para adicionar ou remover painéis. A morada e o painel só podem ser alterados enquanto a encomenda estiver pending; metadata permanece editável durante toda a vida da encomenda. results_ready_emails permanece editável até a encomenda ser cancelled.
Cancelar uma encomenda de kit de teste em casa
Cancela uma encomenda de kit de teste em casa que já não seja necessária:cancelled. A encomenda de kit de teste em casa cancelada é devolvida na resposta.
Apenas uma encomenda pending pode ser cancelada. A partir de dispatched, o kit já foi embalado e etiquetado — não há retenção automática — e a chamada devolve 409. Se um kit que já foi enviado precisar de ser travado, fala diretamente com a Aniva.
Cancelar uma encomenda pending cujo kit já foi encomendado à logística cancela-o também lá, e a chamada só tem sucesso se a logística aceitar:
409— o kit já foi embalado e etiquetado, pelo que já não pode ser retido, mesmo que a encomenda ainda apareça comopending.502— a logística recusou o cancelamento (o erro inclui o motivo) ou não foi possível contactá-la. Nada foi alterado — a encomenda continua ativa e pode ser cancelada novamente.
200 é a única confirmação de que nenhum kit vai ser enviado.
Cancelar uma encomenda que já está cancelled devolve o mesmo 200, independentemente do estado a partir do qual foi cancelada.
Ativar uma encomenda de kit de teste em casa
Quando o paciente tiver recolhido a amostra, reporta-o:activated_at — o momento em que o paciente recolheu efetivamente a amostra, como um instante UTC. Esta é a hora de colheita que o relatório do laboratório vai apresentar, por isso envia o momento real da colheita, não a tua hora de processamento. A ativação é terminal: a encomenda passa para activated e já não pode ser cancelada nem alterada. O equivalente para kits de teste em casa de Confirmar colheita de sangue, sem código de barras — o código do kit é aplicado quando o kit é embalado, pelo que nunca precisas de o saber. A encomenda já tem de ter o seu lab_code nessa altura; uma encomenda sem ele devolve 409.
A ativação é também o que cria a requisição ao laboratório: o painel do kit é pedido ao laboratório com o seu lab_code, pelo que a amostra devolvida fica esperada e os resultados são associados à medida que o laboratório os reporta. Isto corre depois da resposta, e qualquer problema do lado do laboratório é tratado pela Aniva em vez de ser exposto no teu pedido.
Biomarcadores individuais
Podes associar biomarcadores individuais a uma encomenda de kit de teste em casa como análises à la carte, fora do painel. Isto é útil quando queres uma seleção à medida além do kit. Os biomarcadores associados surgem na resposta da encomenda de kit de teste em casa como um arrayindividual_biomarkers (ao mesmo nível de panels).
Ambos os endpoints de biomarcadores requerem o scope de capacidade home_kit_orders_individual_biomarker_selection além de home_kit_orders_manage — os kits de teste em casa são encomendados por painel, pelo que os marcadores avulso são ativados por parceiro. Fala com a Aniva se a tua integração precisar.
Adiciona biomarcadores (idempotente — os biomarcadores já associados são mantidos):
biomarker_ids. Usa Listar biomarcadores com home_kit=true para descobrir os IDs dos biomarcadores. Os biomarcadores só podem ser alterados enquanto o kit estiver pending (vê Ciclo de vida).
Obter resultados de laboratório
Depois de o laboratório processar a amostra devolvida, obtém os resultados clínicos e genéticos:planned) juntamente com os resultados recebidos, para que possas acompanhar o que ainda está pendente. Os resultados são registados sob o lab_code da encomenda e chegam marcador a marcador à medida que o laboratório os analisa, pelo que payloads parciais são normais. O campo status de nível superior é in_progress até ao relatório final e depois passa a completed (ou fault quando todas as ordens de laboratório falharam sem reportar) — usa-o para saber se o trabalho laboratorial da encomenda de kit de teste em casa terminou. Um webhook home_kit_order.results.completed avisa-te quando isso acontece, para não precisares de fazer polling. Os PDFs dos relatórios laboratoriais são referenciados no array documents — usa GET /api/v1/documents/{id} para os descarregar.