Saltar para o conteúdo principal
POST
Faz uma encomenda de kit de teste em casa para um perfil de paciente. Uma encomenda de kit de teste em casa envia um kit de teste para fazer em casa por correio — a Aniva envia o kit para a morada de entrega, o paciente recolhe a amostra em casa e envia-a de volta por correio. Isto é diferente de uma marcação, que é uma colheita de sangue venoso num local de análise. É obrigatório exatamente um painel. Um kit de teste em casa corresponde 1:1 a um kit físico — o painel é o kit — e a encomenda entra na fila de embalamento assim que é criada, pelo que a composição tem de ser definitiva à partida. Ainda podes trocar o painel através de Atualizar encomenda de kit de teste em casa enquanto a encomenda estiver em pending.

Kits de substituição

Quando um kit não consegue fornecer os resultados — o paciente não conseguiu encher o tubo, a amostra chegou com material insuficiente, o laboratório não a conseguiu analisar — encomenda uma substituição enviando replaces_home_kit_order_id. 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 não é possível distinguir duas amostras com o mesmo código. A encomenda que substituis não é alterada — mantém o seu próprio estado, o seu próprio código de laboratório e quaisquer resultados já registados nela. Daqui resultam duas coisas:
  • O painel é herdado. Omite panel_id e a substituição leva o painel da encomenda que substitui, que é o que o paciente comprou e o que identifica a caixa.
  • 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 necessários. Omite-o para repetir todo o painel.
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 solicitado. Uma substituição de um único marcador pode, portanto, chegar com mais de um resultado, e o número de tubos pode ser superior ao que a lista de marcadores sugere. Só pode estar a caminho uma substituição por kit de cada vez.
Se fizeste a integração antes de estes campos existirem, a Aniva também lê metadata.original_kit_id e metadata.replacement_reason na criação e trata a encomenda como uma substituição. Este é o único local onde os metadados são interpretados, existe apenas para manter essa integração anterior e os campos acima prevalecem sempre. Envia os campos.
Um 201 significa que a encomenda está confirmada e será encaminhada para expedição — não precisas de fazer mais nada para o kit ser embalado e enviado. Requer o âmbito home_kit_orders_manage. Envia um cabeçalho opcional Idempotency-Key para tornar esta criação segura para repetir — repetir a mesma chave devolve a resposta original em vez de criar outra. Vê Idempotência.

Pedido

Parâmetros do corpo

string
obrigatório
UUID do perfil de paciente para o qual criar a encomenda de kit de teste em casa.
string
obrigatório
UUID do painel do catálogo a encomendar. Exatamente um — um kit de teste em casa corresponde 1:1 a um kit físico, pelo que o painel é o kit. Os IDs de painel são fornecidos pela Aniva para a tua conta de parceiro; consulta Listar painéis. Opcional numa substituição, onde assume por predefinição o painel da encomenda que substituis.
string
UUID da encomenda de kit de teste em casa que esta substitui. Ao enviá-lo, esta passa a ser um kit de substituição — consulta Kits de substituição acima. A encomenda tem de pertencer ao mesmo perfil e não pode já ter uma substituição a caminho.
string
O motivo pelo qual a substituição é necessária, numa frase (por exemplo, Zu wenig Material, HbA1c nicht auswertbar). Obrigatório quando envias replaces_home_kit_order_id e ignorado nos restantes casos. No máximo 500 caracteres.
integer[]
Numa substituição, os marcadores que o laboratório repete — normalmente os que o primeiro kit não conseguiu fornecer. Cada um tem de fazer parte do que a encomenda que substituis pediu; confirma com Listar biomarcadores com home_kit=true. Omite-o para repetir todo o painel. Só é aceite em conjunto com replaces_home_kit_order_id e não em conjunto com um panel_id diferente. Isto não requer nenhum scope adicional: repetir marcadores que o paciente já pagou não é uma seleção à la carte.
object
Os teus próprios pares chave/valor, devolvidos exatamente como enviados em cada leitura e nunca interpretados pela Aniva. Usa este campo para incluir a tua referência de encomenda e correlacionares sem guardares os nossos IDs. No máximo 20 chaves; as chaves têm de corresponder a [A-Za-z0-9_-] e ter no máximo 40 caracteres; os valores são uma string, um número ou um booleano, com strings de no máximo 500 caracteres; 16 384 bytes serializados no total. As chaves que começam por aniva_ estão reservadas. Nunca coloques dados pessoais ou clínicos em metadata — não é tratado como dados de paciente.
string[]
Até 5 endereços que recebem um e-mail cada assim que todos os resultados laboratoriais forem finais. O e-mail inclui uma ligação para a página de resultados no painel de administração da Aniva. A tua chave precisa de acesso results_view ao paciente, caso contrário devolve 403. Omite este campo para usar os endereços predefinidos para o grupo do paciente. Uma lista vazia desativa os e-mails. Vê E-mails de resultados prontos.
object
obrigatório
A morada para a qual enviar o kit por correio — tem um de dois formatos: { location_id }, que referencia um local de análise conhecido, ou os campos de morada diretamente (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 direta, 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, não é possível registar o envio. Não é suportado Postfach.

Resposta

Em caso de sucesso, a API devolve 201 Created com a nova encomenda de kit de teste em casa.
string
obrigatório
Identificador único da encomenda de kit de teste em casa (UUID).
string
obrigatório
UUID do perfil a que pertence esta encomenda de kit de teste em casa.
string
obrigatório
Estado atual da encomenda de kit de teste em casa. Um de pending, dispatched, activated ou cancelled. Uma encomenda recém-criada começa em pending.
object
obrigatório
A morada para onde enviar o kit — um de dois formatos: { location_id }, que referencia um local de teste 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 localizações). Indica exatamente um — uma referência de localização ou uma morada inline, não ambos.
object
obrigatório
Os pares chave/valor que indicaste. Sempre presente — {} quando não defines nenhum.
string
A encomenda de kit de teste em casa que esta substitui. null numa encomenda normal.
string
O motivo que indicaste. null numa encomenda normal.
string[]
obrigatório
Endereços que recebem um e-mail assim que todos os resultados laboratoriais forem definitivos, em minúsculas. Vazio quando desativado. Consulta E-mails de resultados prontos.
string
Código de amostra de laboratório sob o qual os resultados são comunicados — impresso no kit físico e o que o paciente lê na caixa como código de ativação. null até o kit ser embalado. Só de leitura.
string
obrigatório
Data e hora da colheita comunicadas através de Ativar. null até o kit ser ativado.
string
obrigatório
Data e hora ISO 8601 de criação da encomenda de kit de teste em casa.
string
Data e hora ISO 8601 da última atualização. Pode ser null.
object
obrigatório
O perfil do paciente associado a esta encomenda de kit de teste em casa.
HomeKitOrderPanel[]
obrigatório
O painel associado a esta encomenda de kit de teste em casa — o que indicaste como panel_id, com o registo da hora de criação da encomenda. Sempre exatamente um. Consulta os detalhes do painel (nome, biomarcadores) através de Listar painéis.
HomeKitOrderIndividualBiomarker[]
obrigatório
Biomarcadores associados fora do painel. Vazio numa criação normal — as encomendas de kits de teste em casa são feitas por painel e alterar esta lista depois requer o scope de capacidade home_kit_orders_individual_biomarker_selection. Numa substituição contém os biomarker_ids que enviaste, que são os que o laboratório repete.
HomeKitOrderShipmentLink[]
obrigatório
Envios associados a esta encomenda de kit de teste em casa, por ordem da associação mais antiga primeiro. Sempre vazio na criação — consulta os envios completos com Listar envios e ?home_kit_order_id=.

Respostas de erro