Saltar para o conteúdo principal
POST
Agenda uma marcação de colheita de sangue para um perfil de paciente num local de análise específico. Depois de criada, a marcação fica no estado confirmed por predefinição (alguns locais podem usar pending por predefinição — esta é uma definição por local). Usa Adicionar painéis para associar painéis de análises ao sangue antes de confirmar a colheita de sangue.
Um perfil pode ter no máximo uma marcação por local e horário. Criar uma marcação para um horário que o perfil já ocupa devolve 409 com o appointment_id existente em vez de uma segunda marcação — assim, um pedido reenviado ou repetido por engano nunca duplica uma marcação. Vê Marcações duplicadas.
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. Requer o scope appointments_schedule.

Pedido

Parâmetros do corpo

string
obrigatório
UUID do perfil de paciente para o qual criar a marcação.
string
obrigatório
UUID do local de análise onde a colheita de sangue vai decorrer. Usa Listar locais para encontrar os IDs de locais disponíveis.
string
obrigatório
Data e hora da marcação no formato ISO 8601 (por exemplo, 2026-05-15T10:30:00Z ou 2026-05-15T12:30:00+02:00). Tem de incluir um indicador de fuso horário — Z ou um desfasamento explícito como +02:00; datas e horas sem fuso horário são rejeitadas. Tem de ser no futuro.Tem de corresponder ao início exato de um horário na grelha do local e esse horário ainda tem de ter vagas — consulta primeiro Obter disponibilidade. Horários fora da grelha devolvem 400; um horário já esgotado devolve 409. Nos locais geridos pela Aniva, tem também de ter pelo menos 12 horas de antecedência — vê Antecedência mínima.
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.
string
Como o sangue é colhido: capillary ou venous. Omite este campo para usar o default_draw_method do local. O local tem de incluir o método em draw_methods, caso contrário devolve 400.

Resposta

Em caso de sucesso, a API devolve 201 Created com a nova marcação.
string
obrigatório
Identificador único da marcação (UUID).
string
obrigatório
UUID do perfil a que pertence esta marcação.
string
UUID do local de teste onde decorre a colheita de sangue.
string
Data e hora agendada da marcação como instante UTC (ISO 8601 com sufixo Z, p. ex., 2026-05-15T10:30:00Z). Pode ser null.
string
obrigatório
Estado atual da marcação. Um de pending, confirmed, blood_drawn ou cancelled. O detalhe sobre a conclusão dos resultados laboratoriais obtém-se em Obter resultados; a progressão detalhada dos envios obtém-se a partir de cada entrada no array shipments incorporado (vê abaixo) seguindo para 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.
object
obrigatório
O perfil do paciente associado a esta marcação.
AppointmentPanel[]
obrigatório
Painéis atualmente associados a esta marcação. Vazio em marcações recém-criadas — associa através de Adicionar painéis. Consulta os detalhes dos painéis (nome, biomarcadores) em Listar painéis.
AppointmentIndividualBiomarker[]
obrigatório
Biomarcadores avulsos associados a esta marcação fora de qualquer painel. Vazio em marcações recém-criadas — associa através de Adicionar biomarcadores individuais. Cruza cada biomarker_id com Listar biomarcadores para obter os dados de apresentação.
AppointmentShipmentLink[]
obrigatório
Envios associados a esta marcação, começando pela associação mais antiga. Vazio em marcações recém-criadas — associa através de Criar envio (com appointment_id) ou Associar marcações a um envio.
string[]
obrigatório
Códigos de laboratório (códigos de barras dos tubos) registados para esta marcação, por ordem de leitura. Vazio até a colheita de sangue ser confirmada. Uma colheita venosa tem um código impresso em todos os tubos; uma colheita capilar tem um código por microtubo. Os resultados e documentos em Obter resultados referenciam estes códigos através de lab_code.

Antecedência mínima

As marcações em locais geridos pela Aniva têm de ser feitas com pelo menos 12 horas de antecedência; marcar dentro desse prazo devolve 400. Obter disponibilidade já omite esses horários, pelo que tudo o que leres nessa grelha pode ser marcado. Os locais que geres diretamente não têm antecedência mínima — as marcações para o próprio dia e na hora mantêm-se inalteradas.

Marcações duplicadas

Um perfil pode ter no máximo uma marcação não cancelada por local e instante — uma pessoa não pode fazer duas colheitas de sangue no mesmo local ao mesmo tempo, por muitas cadeiras que o local tenha. Criar uma marcação para um horário que o perfil já ocupa devolve 409 com um appointment_id que indica a marcação já existente:
Trata o erro considerando o pedido já aplicado: obtém a marcação com Obter marcação, altera-a com Atualizar marcação ou cancela-a com Cancelar marcação. Não voltes a tentar a criação — vai continuar a devolver 409. Isto torna seguras as criações repetidas: um pedido que reenvies após um timeout, ou um formulário submetido duas vezes, não pode gerar duas marcações para o mesmo paciente à mesma hora.
appointment_id só está presente no 409 de duplicado. O 409 de capacidade — o horário está cheio porque outros pacientes o ocupam — devolve apenas error, e a solução correta nesse caso é escolher outro horário em Obter disponibilidade.

Respostas de erro