Campos
UUID gerado automaticamente pela Aniva. Usa-o para adicionar painéis, confirmar a colheita de sangue e obter resultados.
O UUID do local de teste onde a colheita de sangue vai decorrer. Os kits de teste em casa não são marcações — vê
Encomendas de kits de teste em casa.
Data e hora agendadas para a colheita de sangue no formato ISO 8601. Devolvida sempre como um instante UTC com um
sufixo
Z (p. ex., 2026-04-15T08:30:00Z). Na criação / atualização, o valor tem de incluir um indicador
de fuso horário (Z ou um desvio explícito como +02:00) — datas e horas sem fuso horário são rejeitadas. Tem
de estar no futuro e, nos locais geridos pela Aniva, com pelo menos 12 horas de antecedência (antecedência
mínima).Estado atual do ciclo de vida. Um de
pending, confirmed, blood_drawn ou cancelled. Vê
Ciclo de vida abaixo. O detalhe da conclusão dos resultados laboratoriais (in_progress vs. completed)
obtém-se em Obter resultados; a progressão mais detalhada do envio (em
trânsito, entregue, etc.) obtém-se seguindo cada entrada no array shipments incorporado até
Obter envio.Motivo em texto livre registado quando a marcação foi cancelada (p. ex., falta de comparência, cancelamento tardio,
‘Falhou. Repetição necessária’).
null, exceto quando status é cancelled.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.
Como o sangue é colhido:
capillary (ponta do dedo ou parte superior do braço, em microtubos) ou venous (na veia,
em tubos). É o método definido na marcação ou, caso contrário, o default_draw_method do respetivo
local. Após a colheita de sangue, é o método que foi utilizado.Timestamp ISO 8601 da atualização mais recente. Nulo se a marcação nunca tiver sido atualizada.
Códigos de laboratório (códigos de barras dos tubos) registados em Confirmar colheita de sangue,
por ordem de leitura. Vazio até a colheita de sangue ser confirmada. Uma colheita de sangue venoso tem um código impresso em todos
os tubos; uma colheita capilar tem um código por microtubo. Os resultados e documentos referenciam-nos através de
lab_code.Painéis associados a esta marcação, como entradas
{ panel_id, added_at }. Vê
Adicionar painéis.Biomarcadores avulsos associados a esta marcação, como entradas
{ biomarker_id, added_at }. Vê
Biomarcadores individuais.Envios associados a esta marcação, como entradas
{ id, added_at }, com a associação mais antiga primeiro. Vê
Associar envios.O objeto completo do perfil do paciente, incorporado em todas as respostas de marcação. Os campos abaixo
são um subconjunto. Obter marcação lista todos.
Ciclo de vida
As marcações expõem quatro estados de ciclo de vida:O estado da marcação é intencionalmente abrangente — a progressão mais detalhada é exposta
através de endpoints dedicados:
- Conclusão dos resultados laboratoriais →
Obter resultados — o campo
statusde nível superior éin_progressoucompleted. - Progressão do envio (em trânsito, entregue, etc.) → segue cada entrada no array
shipmentsincorporado na marcação até Obter envio — cada envio tem o seu própriostatuse um registo de eventosstatus_updates.
appointment.*, por exemplo
appointment.confirmed. Uma nova hora ou local envia appointment.rescheduled.Listar marcações
Obtém todas as marcações acessíveis à tua chave API:?profile_id={uuid} para filtrar por um perfil específico. Sem este parâmetro, é aplicada uma janela temporal predefinida (dos últimos 2 meses até daqui a 1 mês).
Atualizar uma marcação
Antes de a colheita de sangue ser confirmada, podes reagendar ou alterar o local de teste:scheduled_at, location_id, draw_method e results_ready_emails para atualizar. Inclui apenas os campos que queres alterar.
Método de colheita
Cada marcação tem umdraw_method: capillary (ponta do dedo ou parte superior do braço, para microtubos) ou
venous (da veia, para tubos). Aplica-se apenas à colheita de sangue. Urina, zaragatoa e outras
amostras não sanguíneas são recolhidas da mesma forma com qualquer um dos métodos.
Por predefinição, é o default_draw_method do local. Define draw_method na criação ou atualização para
usar outro método, ou define-o como null para voltar à predefinição do local. O local tem de listar
o método nos seus draw_methods e os testes marcados têm de ser possíveis com esse método; caso contrário, o pedido
devolve 400. Não podes alterá-lo após a colheita de sangue. Após a colheita de sangue, draw_method é o
método que foi usado.
Uma marcação por perfil, local e hora
Um perfil tem, no máximo, uma marcação não cancelada por par(location_id, scheduled_at) — uma
pessoa não pode fazer duas colheitas de sangue no mesmo local ao mesmo tempo, independentemente de quantas marcações paralelas o
local aceite.
Tanto Criar marcação como
Atualizar marcação aplicam esta regra, devolvendo 409 com um
appointment_id que aponta para a marcação já existente. Trata essa resposta como uma marcação já
existente em vez de um erro para tentar novamente: obtém, reagenda ou cancela a marcação indicada.
O efeito prático é que criações repetidas são seguras. Uma criação que reenvies após um timeout de rede,
ou que um utilizador acione duas vezes, resulta numa única marcação em vez de duas — o que também
significa que nunca precisas de reconciliar marcações duplicadas para o mesmo paciente mais tarde.
As atualizações só são permitidas antes da colheita de sangue — ou seja, enquanto a marcação
estiver no estado
pending ou confirmed. Assim que a marcação passa para blood_drawn ou fica
cancelled, não pode ser modificada. A única exceção é results_ready_emails: ainda podes
alterá-lo isoladamente após a colheita de sangue.Cancelar uma marcação
Cancela uma marcação que já não é necessária:cancelled. A marcação cancelada é devolvida na resposta.
Opcionalmente, envia um cancellation_reason (até 500 caracteres) no corpo para registar o motivo.
É guardado na marcação e devolvido como cancellation_reason em leituras posteriores.
O cancelamento só é permitido antes da colheita de sangue — ou seja, enquanto a marcação estiver
no estado
pending ou confirmed. As marcações que já passaram para blood_drawn não podem ser
canceladas.Adicionar painéis
Antes de confirmares a colheita de sangue, adiciona os painéis de análises ao sangue que queres realizar chamando:panel_ids. Os IDs dos painéis são fornecidos pela Aniva para a tua conta de parceiro.
Os painéis têm de ser adicionados antes da colheita de sangue — ou seja, enquanto a marcação
estiver no estado
pending ou confirmed. Não podes adicionar nem alterar painéis depois de a
marcação passar para blood_drawn.Remover painéis
Se precisares de remover painéis antes da colheita de sangue, chama:panel_ids. A remoção é idempotente: um painel que não esteja associado é ignorado.
Tal como a adição de painéis, a remoção só é permitida antes da colheita de sangue — ou seja,
enquanto a marcação estiver no estado
pending ou confirmed. Os painéis não podem ser removidos
depois de a marcação passar para blood_drawn.Biomarcadores individuais
Podes associar biomarcadores individuais a uma marcação como análises à la carte, fora de qualquer painel pré-configurado. Isto é útil quando um profissional de saúde quer uma seleção à medida em vez de um pacote pré-definido. Os biomarcadores associados aparecem na resposta da marcação como um arrayindividual_biomarkers (ao mesmo nível de panels). As decisões de encaminhamento são tomadas a jusante pelo pipeline de logística de pedidos com base nos mapeamentos por laboratório de cada biomarcador.
Adiciona biomarcadores (idempotente — os biomarcadores já associados são mantidos):
biomarker_ids e validam o conjunto resultante segundo as regras de fecho de cada laboratório — um pedido que não possa ser submetido corretamente (p. ex., um rácio CRP/HDL sem CRP e HDL) devolve 400 com os biomarcadores que terias de adicionar e não guarda nada. Usa Listar biomarcadores para descobrir os IDs dos biomarcadores.
Tal como as alterações de painéis, os biomarcadores individuais só podem ser adicionados ou
removidos antes da colheita de sangue — ou seja, enquanto a marcação estiver no estado
pending ou
confirmed. Assim que a marcação passa para blood_drawn, o snapshot personalizado fica congelado.Pré-visualizar requisitos de recipientes
Depois de adicionares painéis ou biomarcadores individuais, pré-visualiza os recipientes físicos de colheita de espécimes que serão necessários para a recolha da amostra:containers da resposta inclui o tipo, nome, cor da tampa, volume, número de artigo do fabricante e quantidade de cada recipiente necessário. Isto ajuda os profissionais de saúde a preparar os materiais corretos antes da colheita de sangue. A resposta inclui também um objeto pricing — a conta total do carrinho da marcação (as posições aplicadas, os painéis associados e uma linha por biomarcador entregue, com o preço da tua tabela e o preço de retalho ao lado; consulta Preços), preenchido quando a marcação tem análises associadas e a tua chave tem o scope prices_view, caso contrário null. De forma intencional, routing nunca é exposto e é sempre null.
A pré-visualização reflete os painéis e biomarcadores associados no momento. Se adicionares ou
removeres painéis após a pré-visualização, volta a chamar o endpoint de pré-visualização para
obteres os requisitos de recipientes atualizados.
Confirmar a colheita de sangue
Depois da colheita de sangue, submete os códigos de laboratório (códigos de barras dos tubos) para acionar o pipeline de pedidos de laboratório:lab_code quando o mesmo código está impresso em todos os tubos (colheita venosa), ou
lab_codes com uma entrada por código — cada uma com os panel_ids que abrange — quando cada
painel é colhido nos seus próprios tubos com o seu próprio código (colheita capilar). Cada painel
passa então a ser a sua própria requisição de laboratório sob o respetivo código. Os códigos são
devolvidos como lab_codes na marcação.
Numa colheita capilar, a colheita é acondicionada em microtainers. Os painéis vão primeiro, por ordem
de marcação. Os biomarcadores individuais preenchem depois o espaço livre dos microtainers dos
painéis. Quando precisam de mais espaço, abrem novos microtainers. Distribuímo-los de forma uniforme.
Cada microtainer suporta no máximo 150 µl de biomarcadores individuais. As chamadas que alteram
painéis ou biomarcadores respondem 400 quando o conjunto resultante viola esta regra.
Isto altera o estado da marcação para blood_drawn e inicia o processamento em laboratório. Esta ação é irreversível.
Recolha do envio
Para acompanhares a progressão após a colheita de sangue, segue cada entrada do arrayshipments
inline da marcação até Obter envio — cada envio tem o seu próprio
status e um histórico status_updates.
Associar envios
Uma marcação pode estar associada a um ou mais envios (e vice-versa — a relação é de muitos para muitos). O conjunto atual de associações aparece inline em ambos os lados:- na marcação, como um array
shipmentsde entradas{ id, added_at }; - no envio, como um array
appointmentsde entradas{ id, added_at }.
id remete para o endpoint
canónico de detalhes (Obter envio /
Obter marcação) para obter o payload completo.
Os envios são associados no momento da criação através do campo appointment_id em
Criar envio. Após a criação, gere as associações a partir do envio
com Associar marcações ao envio e
Desassociar marcações do envio; cada um devolve
a lista de marcações após a alteração para esse envio. Para leres na íntegra as encomendas de uma
marcação, usa Listar envios com ?appointment_id=.
A regra de alteração é: as associações podem ser criadas ou removidas quando se verifica QUALQUER UMA das condições
- a marcação já passou pela colheita de sangue (
blood_drawn), ou - o envio foi criado há menos de 24 horas.
Obter resultados de laboratório
Assim que o laboratório tiver processado as amostras de sangue, obtém os resultados clínicos e genéticos:planned) juntamente com os resultados recebidos, para poderes
acompanhar o que ainda está pendente. O campo status de nível superior é in_progress até todas as submissões
fecharem, passando depois a completed (ou fault quando nenhuma reportou) — usa-o para determinar se o
trabalho de laboratório da marcação terminou. Um webhook appointment.results.completed
avisa-te quando isso acontece, para não precisares de fazer polling. O
array submissions detalha isto por requisição de laboratório, cada uma com o seu lab_code. Cada
resultado e documento recebido inclui o lab_code sob o qual foi registado. Os PDFs dos relatórios de laboratório estão
referenciados no array documents — usa GET /api/v1/documents/{id} para os transferir.