Saltar para o conteúdo principal
Um envio é uma encomenda física: uma recolha por estafeta que transporta amostras de sangue de um local de teste para um laboratório, o kit a caminho de um paciente de kit de teste em casa ou a amostra que esse paciente envia de volta por correio. A API de Envios permite-te criar, seguir, modificar e cancelar pedidos de envio, e lista todas as encomendas num só lugar, independentemente de quem as reservou.

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 em destination.
  • booked_by — quem imprimiu a etiqueta: aniva ou external. Apenas os envios aniva aceitam Atualizar e Cancelar; uma encomenda external é seguida na mesma lista, mas devolve 501 em ambos os casos.
Uma encomenda que levou uma etiqueta de devolução e a encomenda que essa etiqueta traz de volta apontam uma para a outra através de 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.
  • appointments e home_kit_orders listam 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 403 e 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 regista synced_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 o location_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 appointments de entradas { id, added_at };
  • na marcação, como um array shipments de entradas { id, added_at }.
Ambos os arrays estão ordenados da associação mais antiga para a mais recente. Cada 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 usando PATCH /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.
Os envios não podem ser modificados depois de o estafeta recolher a encomenda. Tentativas de atualizar um envio nos estados in_transit, delivered ou fault devolvem 409 Conflict.
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 usando DELETE /api/v1/shipments/{id}. Isto chama a API do operador logístico para cancelar o pedido e atualiza o estado para cancelled.
Os envios não podem ser cancelados após a recolha. Tentativas de cancelar um envio que já está em in_transit, delivered ou fault devolvem 409 Conflict. Cancelar um que já está cancelled não tem efeito e devolve 200 com o envio — vê Idempotência.
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 devolve 409 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 campos origin e destination na resposta do envio contêm objetos de morada resolvidos com a seguinte estrutura:
Para uma encomenda de clínica, a morada 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 campo pickup 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 array status_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. null quando o evento não tem estado (criação de etiqueta, uma leitura sem informação da transportadora, entradas registadas antes de o campo existir). Nunca cancelled — um cancelamento é nosso, não um evento da transportadora.
  • code — o próprio código de estado da transportadora (GO10, GO90, GOY001 da GO!; VA, ZF, LA, ZU da DHL). null quando a transportadora não forneceu nenhum. Estável independentemente da tradução de status.
  • detail_code — o código mais detalhado da transportadora quando existe: statusDetailed da DHL, por exemplo CNRFC_NRQRD_ZF (redirecionada para um posto de correios), HLDCC_SERPT_LA (pronta para levantamento aí), DLVRD_SERPT_ZU (levantada). null nos 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. null quando 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).
Quando a transportadora devolve a encomenda ao remetente, a linha temporal recebe uma entrada com 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:
A linha do trajeto de devolução existe desde o momento em que a etiqueta de devolução é impressa e mantém-se em pending até o paciente enviar a amostra pelo correio — esse é o estado real, não uma falha.