Saltar para o conteúdo principal
GET
Obtém os envios acessíveis à tua chave de API, mais recentes primeiro. Todos os pacotes estão nesta única lista: uma recolha por estafeta num consultório, o kit a caminho de um paciente de kit de teste em casa e a amostra no caminho de volta. Filtra por um registo principal com appointment_id ou home_kit_order_id. Requer o âmbito shipments_view ou shipments_manage. A resposta vem da nossa base de dados e nunca chama a transportadora. Uma sincronização em segundo plano atualiza cada envio (a cada 10 minutos para a GO!, de hora a hora para a DHL) e synced_at em cada linha indica-te quando a transportadora foi consultada pela última vez.

Pedido

Parâmetros de consulta

string
Apenas envios associados a esta marcação (UUID). 404 quando a marcação não existe, 403 quando está fora do teu contexto de acesso.
string
Apenas envios associados a esta encomenda de kit de teste em casa (UUID). Normalmente são devolvidas duas linhas — o kit a caminho do paciente e a amostra de volta para o laboratório (o seu destination é o laboratório). As mesmas regras de 404 / 403 que em appointment_id.
string
Apenas envios neste estado. Um de pending, in_transit, delivered, fault, cancelled.
integer
Número máximo de envios a devolver. Predefinição: 100, máximo: 500.
integer
Número de envios a ignorar. Predefinição: 0. A ordenação é estável (created_at decrescente e depois referência), pelo que as páginas não se sobrepõem.

Resposta

Em caso de sucesso, a API devolve 200 OK com um array de objetos de envio.
string
obrigatório
Identificador de referência do envio.
string
obrigatório
Estado do ciclo de vida do envio. Um dos seguintes: pending, in_transit, delivered, fault ou cancelled.
string
obrigatório
Operador logístico. Um de go, dhl_parcel, dhl_warenpost, rotrunner, rapido, ups ou dhl_express. Uma encomenda de kit para casa é dhl_parcel, ou dhl_warenpost quando segue para o estrangeiro como Warenpost International.
string
Número de seguimento externo do operador logístico. Pode ser null.
string
Descrição em texto livre do conteúdo da encomenda, conforme indicado na criação (por ex., "Medizinisch freigestellte Probe", "Home test kit"). Apenas informativo — se uma encomenda segue para um laboratório verifica-se em destination, e a respetiva contraparte em paired_with. Pode ser null.
string
obrigatório
Quem imprimiu a etiqueta: aniva ou external. Só os envios aniva aceitam Atualizar e Cancelar; um pacote external tem seguimento, mas devolve 501 em ambos os casos.
string
Referência do outro pacote de uma remessa de dois pacotes — o pacote que levou uma etiqueta de devolução e o pacote que essa etiqueta traz de volta. Definida em ambos. null para um pacote só de ida.
object
Morada de recolha. Pode ser null.
object
Morada de entrega. Mesma estrutura que origin. Pode ser null.
object
Janela de recolha agendada. Pode ser null.
string
Notas opcionais. Pode ser null.
object[]
obrigatório
Eventos cronológicos do ciclo de vida enviados pelo fornecedor de logística (mais antigos primeiro). Array vazio se o fornecedor ainda não comunicou eventos. Usa isto para UI por evento, auditoria e sinais mais detalhados da transportadora; baseia-te em status para o estado atual canónico.
ShipmentAppointmentLink[]
obrigatório
Marcações associadas a este envio, pela ligação mais antiga primeiro. Cada entrada é { id, added_at }; cruza cada id com Obter marcação para obteres o payload completo da marcação. Array vazio quando não há marcações associadas. Só são listadas as marcações no teu contexto de acesso.
ShipmentHomeKitOrderLink[]
obrigatório
Encomendas de kit de teste em casa associadas a este envio, pela ligação mais antiga primeiro, no mesmo formato { id, added_at }. Cruza cada id com Obter encomenda de kit de teste em casa. Array vazio para pacotes de consultório. Só são listadas as encomendas no teu contexto de acesso. Consulta Acesso.
string
Quando o envio foi conciliado pela última vez com a transportadora, como instante UTC. As leituras nunca chamam a transportadora — uma sincronização em segundo plano mantém os envios atualizados — por isso isto mostra quão antiga é a resposta. null até à primeira sincronização.
string
obrigatório
Data e hora de criação (ISO 8601).
string
Data e hora da última atualização (ISO 8601). Pode ser null.

Chamadas repetidas

A Aniva guarda a resposta deste endpoint durante 5 minutos por cada chave API. Uma chamada repetida dentro deste período recebe a resposta guardada. Os cabeçalhos Cache-Status e Age mostram que a resposta está guardada e há quanto tempo. Para saberes de uma alteração de imediato, subscreve os eventos de webhook shipment.created e shipment.updated. Consulta Leituras repetidas.

Respostas de erro