Uma lista, filtrada
GET /api/v1/shipments é a única coleção. Um envio existe de forma independente — tem uma relação muitos-para-muitos com marcações e pode pertencer a um pedido de kit de teste em casa — pelo que não existe nenhuma lista aninhada sob um recurso pai. Filtra a mesma lista com ?appointment_id= ou ?home_kit_order_id=, pagina-a com limit / offset e segue o array shipments inline de um recurso pai ({ id, added_at } tanto em marcações como em pedidos de kit de teste em casa) até Obter envio quando tiveres um ID.
Conteúdo e quem reservou
Cada envio contém dois dados que não são visíveis a partir das suas moradas:contents— texto livre que descreve o que está na encomenda, definido na criação ("Medizinisch freigestellte Probe","Home test kit") e mostrado ao estafeta. Apenas informativo. A direção não é um campo: se uma encomenda segue para um laboratório, isso lê-se emdestination.booked_by— quem imprimiu a etiqueta:anivaouexternal. Apenas os enviosanivaaceitam Atualizar e Cancelar; uma encomendaexternalé seguida na mesma lista, mas devolve501em ambos os casos.
paired_with.
Acesso
- Podes ler uma encomenda quando pelo menos uma marcação ou um pedido de kit de teste em casa associado está no teu contexto de acesso, ou quando partiu de um local no teu contexto de acesso.
appointmentsehome_kit_orderslistam apenas as marcações e os pedidos no teu contexto de acesso.- Atualizar, Cancelar, Associar marcações e Desassociar marcações requerem que todos os pedidos de kit de teste em casa associados estejam no teu contexto de acesso. Caso contrário, a chamada devolve
403e apenas a Aniva pode alterar a encomenda.
As leituras nunca chamam a transportadora
Cada leitura é servida a partir da nossa base de dados. Uma sincronização em segundo plano reconcilia cada envio com a respetiva transportadora (a cada 10 minutos para a GO!, de hora a hora para a DHL) e registasynced_at, que indica a antiguidade de qualquer resposta. Não existe atualização forçada — a DHL permite uma chamada de seguimento a cada cinco segundos, pelo que não seria possível oferecer uma leitura com consulta direta à transportadora.
Criar um envio
Ao criar um envio, especificas olocation_id de origem — o local de teste onde o estafeta deve fazer a recolha. Também indicas o laboratório de destino com destination_lab. O envio segue para a morada de envio registada desse laboratório.
O local tem de estar dentro do contexto de acesso da tua chave de API. Usa Listar locais para encontrar os IDs de local disponíveis.
Podes opcionalmente passar appointment_id para associar o envio a uma marcação específica no
momento da criação. A associação aparece inline em ambos os lados:
- no envio, como um array
appointmentsde entradas{ id, added_at }; - na marcação, como um array
shipmentsde entradas{ id, added_at }.
id remete para o endpoint de detalhes canónico
(Obter marcação /
Obter envio) para obter o payload completo — os parceiros que pretendam
acompanhar a evolução do estafeta por marcação seguem cada entrada no array shipments da marcação até
ao endpoint de detalhes do envio.
Um envio pode ser associado a várias marcações, e uma marcação pode ser associada a vários
envios. Após a criação, gere a associação com Associar marcações a
envio /
Desassociar marcações de envio. Cada
mutação devolve a lista de marcações do envio após a mutação.
A regra de mutação é: as associações podem ser criadas ou removidas quando OU a marcação já passou a
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 permaneçam estáveis.
Ciclo de vida
Os envios passam pelos seguintes estados:
Cada alteração de estado envia um webhook
shipment.*, por exemplo
shipment.delivered. shipment.updated dispara em cada alteração que podes ler, como uma nova leitura.
Regras de agendamento de recolha
As seguintes regras aplicam-se ao criar ou atualizar o agendamento de recolha de um envio.pickup_date
(YYYY-MM-DD) e pickup_time_from / pickup_time_till (HH:MM, 24 h) são valores de hora local
interpretados no fuso horário IANA do local de origem — não envias um fuso horário com eles.
Modificar envios
Podes atualizar o agendamento de recolha, o número de volumes, o peso e as notas de um envio usandoPATCH /api/v1/shipments/{id}. Se algum campo relevante para a logística mudar (data de recolha, hora, número de volumes ou peso), o pedido logístico existente é cancelado automaticamente e é criado um novo. Os campos que omites no corpo da atualização são mantidos do envio existente — por exemplo, atualizar apenas weight volta a criar o pedido com o mesmo agendamento de recolha. Os campos de agendamento atualizados são validados com as mesmas regras de agendamento de recolha.
Se o operador logístico rejeitar o cancelamento ou a nova criação durante uma atualização, a API devolve 502 Bad Gateway com a mensagem de erro do operador.
Cancelar envios
Cancela um envio usandoDELETE /api/v1/shipments/{id}. Isto chama a API do operador logístico para cancelar o pedido e atualiza o estado para cancelled.
O operador logístico pode também rejeitar o cancelamento por motivos próprios (por exemplo, o prazo de cancelamento já passou). Nesse caso, a API devolve 502 Bad Gateway com a mensagem de erro e o código de erro do operador.
Etiquetas de devolução
Uma etiqueta de devolução da DHL faz parte do respetivo pedido de ida. A DHL não pode cancelar a etiqueta isoladamente, pelo que cancelar a linha que acompanha uma etiqueta de devolução devolve409 Conflict. Em vez disso, cancela a encomenda de ida enquanto estiver em pending. Isso cancela a etiqueta em conjunto: cada linha do trajeto de devolução em pending da encomenda de ida passa a cancelled e recebe uma entrada RETURN_LEG_CANCELLED no seu status_updates. Uma encomenda de devolução que o paciente já enviou pelo correio continua o percurso. Depois de a encomenda de ida ser expedida, a etiqueta mantém-se válida e a Aniva fecha manualmente a linha do trajeto de devolução.
IDs de referência de envio
Cada envio tem um ID de referência de 11 caracteres: uma letra, a data e quatro caracteres,{letter}YYMMDDXXXX (por exemplo, P2611194821). A letra indica a que pertence o envio, nunca a sua direção:
Um envio de 20 a 22 de novembro de 2026 mantém o seu ID com uma palavra no início:
API, MAN, AUTO ou KIT (por exemplo, AUTO261121UWKX). Ambos os formatos continuam válidos. Não verifiques o comprimento nem a primeira letra de um ID. Usa o ID para obter, atualizar ou cancelar o envio.
Moradas de envio
Os camposorigin e destination na resposta do envio contêm objetos de morada resolvidos com a seguinte estrutura:
origin é resolvida a partir do local de análise que indicaste na
criação e destination é o laboratório que indicaste em destination_lab.
Para uma encomenda de kit para casa, a morada de entrega do paciente é o destination do kit e o
origin da devolução da amostra; o local que embala o kit é o seu origin. A
morada não inclui location_id — relaciona uma encomenda de clínica através da marcação à qual está
associada.
Janela de recolha
O campopickup na resposta do envio contém a janela de recolha agendada para o estafeta. Inclui
os timestamps from e till como instantes UTC (ISO 8601 com sufixo Z, por exemplo
2026-04-15T07:00:00Z) e uma string timezone (fuso horário IANA do local de recolha). Os valores de
hora local pickup_date / pickup_time_* que enviaste na criação ou atualização são resolvidos nestes
instantes absolutos com esse fuso horário — usa timezone para apresentar from / till de volta na
hora local do local de recolha. O campo é null quando não foi agendada nenhuma janela de recolha.
Registo de atualizações de estado
Cada envio inclui um arraystatus_updates — todos os eventos do ciclo de vida que o operador logístico
comunicou, do mais antigo para o mais recente. Cada entrada contém:
state— o evento no vocabulário de estados de envio (pending,in_transit,delivered,fault), para que possas ler uma linha temporal sem conhecer os códigos da transportadora.nullquando o evento não tem estado (criação de etiqueta, uma leitura sem informação da transportadora, entradas registadas antes de o campo existir). Nuncacancelled— um cancelamento é nosso, não um evento da transportadora.code— o próprio código de estado da transportadora (GO10,GO90,GOY001da GO!;VA,ZF,LA,ZUda DHL).nullquando a transportadora não forneceu nenhum. Estável independentemente da tradução destatus.detail_code— o código mais detalhado da transportadora quando existe:statusDetailedda DHL, por exemploCNRFC_NRQRD_ZF(redirecionada para um posto de correios),HLDCC_SERPT_LA(pronta para levantamento aí),DLVRD_SERPT_ZU(levantada).nullnos restantes casos.status— o texto legível da transportadora (por exemplo"Shipment picked up","Die Sendung wurde abgeholt.").description— uma explicação do código, ou a frase mais longa da transportadora.nullquando nenhuma existe.location— onde ocorreu a leitura, conforme o nome dado pela transportadora: um depósito da GO!, uma cidade da DHL. Texto livre, não uma coordenada.time— timestamp ISO 8601 do evento, conforme comunicado pela transportadora (com o respetivo offset).
code
RETURNED_TO_SENDER. O respetivo status contém o motivo da transportadora. O envio mantém-se então em fault, mesmo
depois de a transportadora nos devolver a encomenda.
A lista pode estar vazia se a transportadora ainda não comunicou nenhum evento.
Usa o campo status de topo para o estado atual canónico. Avança num só sentido — de pending
para in_transit e para delivered — com fault sobreposto enquanto o evento mais recente indicar um problema;
as transportadoras não ordenam os eventos por relevância (a DHL acrescenta um aviso de redirecionamento
com código pre-transit após a leitura de entrega), pelo que a entrada mais recente por si só não indica onde está a encomenda.
Exemplo de envio
Exemplo de encomendas de kit para casa
GET /api/v1/shipments?home_kit_order_id=d1e2f3a4-… devolve o kit a caminho do paciente e a amostra a caminho de volta, em par:
pending até o paciente enviar a amostra pelo correio — esse é o estado real, não uma falha.