Saltar para o conteúdo principal
Uma encomenda de kit de teste em casa envia um kit de autoteste pelo correio a um paciente. A Aniva envia o kit, o paciente recolhe ele próprio uma amostra em casa e envia-a de volta pelo correio. Isto é diferente de uma marcação, que é uma colheita de sangue venoso realizada num local de testes físico por um profissional de saúde.
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

string
obrigatório
UUID gerado automaticamente pela Aniva. Usa-o para atualizar a encomenda, trocar o painel, ativá-la, cancelá-la e obter resultados.
string
obrigatório
O UUID do perfil a que pertence esta encomenda de kit de teste em casa.
string
obrigatório
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.
object
obrigatório
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.
string
obrigatório
Data e hora ISO 8601 de criação da encomenda de kit de teste em casa.
string
Timestamp ISO 8601 da atualização mais recente. Nulo se a encomenda de kit de teste em casa nunca tiver sido atualizada.
object
O objeto de perfil completo do paciente, incluído em todas as respostas de encomenda de kit de teste em casa.
object[]
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.
object[]
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.
string
A encomenda de kit de teste em casa que esta substitui, quando se trata de um kit de substituição. null numa encomenda normal.
string
O motivo do envio da substituição, numa frase. null numa encomenda normal.
string[]
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.
object
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.
string
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=….
string
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.
object[]
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

O que é devolvido depende do kit. Um kit de sangue surge como dois envios assim que a Aniva o embala: o pacote da Aniva para o paciente e o do paciente para o laboratório (o seu 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.
A composição de uma encomenda de kit de teste em casa só pode ser alterada enquanto estiver pending. Assim que a encomenda fica dispatched (ou mais tarde — activated/cancelled), as trocas de painel e os endpoints /biomarkers devolvem 409 Conflict: o kit físico é embalado a partir do painel selecionado, pelo que o seu conteúdo fica bloqueado no momento em que parte para o paciente. Se precisares mesmo de alterar as análises numa encomenda já bloqueada, fala diretamente com a Aniva — normalmente ainda é possível, e fazemos a alteração por ti para manter o conteúdo do kit consistente. Se o kit já foi usado e não conseguiu fornecer resultados, encomenda um kit de substituição.

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:
Opcionalmente, passa ?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:
Passa o 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:
Uma substituição é uma nova encomenda com um novo código de laboratório, mesmo quando o primeiro kit nunca foi ativado: o laboratório precisa de uma nova requisição e duas amostras com o mesmo código não podem ser distinguidas. Ambas as encomendas continuam legíveis, ligadas através de 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.
Apenas uma substituição por kit pode estar a caminho de cada vez — enquanto uma substituição estiver 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:
Inclui apenas os campos que queres alterar. 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:
Isto define o estado da encomenda de kit de teste em casa como 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 como pending.
  • 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.
Um cancelamento que devolve um erro deixa a encomenda exatamente como estava, pelo que um 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:
Passa 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 array individual_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):
Remover biomarcadores (idempotente — um ID que não esteja associado é ignorado):
Ambos os endpoints recebem um array 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:
A resposta inclui análises planeadas (estado 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.

Exemplo de encomenda de kit de teste em casa