Saltar para o conteúdo principal
Uma marcação é uma colheita de sangue agendada para um perfil de paciente num local de teste físico, realizada por um profissional de saúde. Os kits enviados por correio a um paciente não são marcações — vê Encomendas de kits de teste em casa.

Campos

string
obrigatório
UUID gerado automaticamente pela Aniva. Usa-o para adicionar painéis, confirmar a colheita de sangue e obter resultados.
string
obrigatório
O UUID do perfil a que esta marcação pertence.
string
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.
string
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).
string
obrigatório
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.
string
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.
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
obrigatório
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.
string
obrigatório
Data e hora ISO 8601 da criação da marcação.
string
Timestamp ISO 8601 da atualização mais recente. Nulo se a marcação nunca tiver sido atualizada.
string[]
obrigatório
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.
object[]
obrigatório
Painéis associados a esta marcação, como entradas { panel_id, added_at }. Vê Adicionar painéis.
object[]
obrigatório
Biomarcadores avulsos associados a esta marcação, como entradas { biomarker_id, added_at }. Vê Biomarcadores individuais.
object[]
obrigatório
Envios associados a esta marcação, como entradas { id, added_at }, com a associação mais antiga primeiro. Vê Associar envios.
object
obrigatório
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 status de nível superior é in_progress ou completed.
  • Progressão do envio (em trânsito, entregue, etc.) → segue cada entrada no array shipments incorporado na marcação até Obter envio — cada envio tem o seu próprio status e um registo de eventos status_updates.
Cada alteração de estado envia um webhook appointment.*, por exemplo appointment.confirmed. Uma nova hora ou local envia appointment.rescheduled.
Confirmar uma marcação (passá-la para blood_drawn) é irreversível. Assim que submeteres o(s) código(s) de laboratório, o fluxo de pedidos laboratoriais é acionado e não pode ser revertido. As atualizações e os cancelamentos só são permitidos enquanto a marcação estiver no estado pending ou confirmed.

Listar marcações

Obtém todas as marcações acessíveis à tua chave API:
Passa opcionalmente ?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:
Passa qualquer combinação de 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 um draw_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:
Isto define o estado da marcação como 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:
Passa um array de UUIDs de painéis no campo 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:
Passa um array de UUIDs de painéis no campo 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 array individual_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):
Remove biomarcadores (idempotente — os biomarcadores que não estejam associados são ignorados):
Ambos os endpoints aceitam um array 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:
O array 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:
Envia 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

POST /api/v1/appointments/pickup foi removido, juntamente com o estado de marcação shipment_picked_up. Agora responde 405 Method Not Allowed, porque o caminho cai na rota de marcação por ID. O endpoint passou a sua fase final como um no-op que aceitava a chamada e não fazia nada, pelo que a sua remoção não altera nenhum comportamento de que dependesses.
Para acompanhares a progressão após a colheita de sangue, segue cada entrada do array shipments 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 shipments de entradas { id, added_at };
  • no envio, como um array appointments de entradas { id, added_at }.
Ambos os arrays apresentam primeiro a associação mais antiga. Cada 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.
Fora dessa janela, a associação fica bloqueada para que os registos históricos se mantenham estáveis.

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:
A resposta inclui análises planeadas (estado 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.

Exemplo de marcação