Passer au contenu principal
POST
Demande une commande de kit à domicile pour un profil patient. Une commande de kit à domicile envoie un kit de test à faire soi-même par courrier — Aniva expédie le kit à l’adresse de livraison, le patient prélève son échantillon chez lui et le renvoie par courrier. Cela se distingue d’un rendez-vous, qui consiste en une prise de sang veineuse sur un lieu de test. Un seul panel exactement est requis. Un kit à domicile correspond 1 pour 1 à un kit physique — le panel est le kit — et la commande rejoint la file de préparation dès sa création, donc sa composition doit être définitive dès le départ. Tu peux encore changer de panel via Mettre à jour une commande de kit à domicile tant que la commande est pending.

Kits de remplacement

Lorsqu’un kit ne peut pas fournir ses résultats — le patient n’a pas pu remplir le tube, l’échantillon est arrivé avec trop peu de matériel, le laboratoire n’a pas pu l’analyser — commande un remplacement en envoyant replaces_home_kit_order_id. Un remplacement est une nouvelle commande avec un nouveau code laboratoire, même lorsque le premier kit n’a jamais été activé : le laboratoire a besoin d’une nouvelle demande d’analyse, et deux échantillons portant le même code ne peuvent pas être distingués. La commande que tu remplaces n’est pas modifiée — elle conserve son propre statut, son propre code laboratoire et tous les résultats déjà enregistrés sous cette commande. Deux choses en découlent :
  • Le panel est hérité. Ne renseigne pas panel_id et le remplacement reprend le panel de la commande qu’il remplace, soit ce que le patient a acheté et l’habillage de la boîte.
  • Tu choisis ce qui est réanalysé. Envoie biomarker_ids avec les marqueurs qui ont échoué et le laboratoire ne réanalyse que ceux-là, pour que le kit n’envoie que les tubes nécessaires. Ne le renseigne pas pour réanalyser tout le panel.
Les marqueurs sont réanalysés par groupes du panel, pas un par un. Indiquer un marqueur d’un groupe réanalyse tout ce groupe, car une commande laboratoire qui renvoie plus que ce qui a été demandé ne peut pas être passée. Un remplacement pour un seul marqueur peut donc arriver avec plusieurs résultats, et son nombre de tubes peut être supérieur à ce que la liste des marqueurs laisse penser. Un seul remplacement par kit peut être en route à la fois.
Si tu as intégré l’API avant l’existence de ces champs, Aniva lit aussi metadata.original_kit_id et metadata.replacement_reason lors d’une création et traite la commande comme un remplacement. C’est le seul endroit où les métadonnées sont interprétées, il existe uniquement pour maintenir cette ancienne intégration, et les champs ci-dessus l’emportent toujours. Envoie les champs.
Un 201 signifie que la commande est validée et va être transmise à la logistique — tu n’as rien d’autre à faire pour que le kit soit préparé et expédié. Requiert le scope home_kit_orders_manage. Envoie un en-tête facultatif Idempotency-Key pour pouvoir relancer cette création sans risque — répéter la même clé renvoie la réponse d’origine au lieu d’en créer un second. Voir Idempotence.

Requête

Paramètres du corps

string
requis
UUID du profil patient pour lequel créer la commande de kit à domicile.
string
requis
UUID du panel du catalogue à commander. Un seul exactement — un kit à domicile correspond 1 pour 1 à un kit physique, donc le panel est le kit. Les identifiants de panel sont fournis par Aniva pour ton compte partenaire ; voir Lister les panels. Facultatif pour un remplacement, où il reprend par défaut le panel de la commande que tu remplaces.
string
UUID de la commande de kit à domicile que celle-ci remplace. L’envoyer en fait un kit de remplacement — voir Kits de remplacement ci-dessus. La commande doit appartenir au même profil et ne doit pas déjà avoir un remplacement en route.
string
Raison du remplacement, en une phrase (par exemple Zu wenig Material, HbA1c nicht auswertbar). Requis lorsque tu envoies replaces_home_kit_order_id, et ignoré sinon. 500 caractères maximum.
integer[]
Pour un remplacement, les marqueurs que le laboratoire réanalyse — normalement ceux que le premier kit n’a pas pu fournir. Chacun doit faire partie de ce que demandait la commande que tu remplaces ; vérifie la correspondance avec Lister les biomarqueurs avec home_kit=true. Ne le renseigne pas pour réanalyser tout le panel. Accepté uniquement avec replaces_home_kit_order_id, et jamais avec un panel_id différent. Cela ne nécessite aucun scope supplémentaire : réanalyser des marqueurs que le patient a déjà payés n’est pas une sélection à la carte.
object
Tes propres paires clé/valeur, renvoyées telles quelles à chaque lecture et jamais interprétées par Aniva. Utilise ce champ pour transmettre ta référence de commande et faire le lien sans stocker nos identifiants. 20 clés maximum ; les clés correspondent à [A-Za-z0-9_-] et font 40 caractères maximum ; les valeurs sont des chaînes, des nombres ou des booléens, avec des chaînes de 500 caractères maximum ; 16 384 octets sérialisés au total. Les clés commençant par aniva_ sont réservées. Ne mets jamais de données personnelles ou cliniques dans metadata — ce champ n’est pas traité comme des données patient.
string[]
Jusqu’à 5 adresses qui reçoivent chacune un e-mail dès que tous les résultats de laboratoire sont définitifs. L’e-mail renvoie vers la page des résultats dans le panneau d’administration Aniva. Ta clé doit disposer de l’accès results_view pour le patient, sinon 403. Omets ce champ pour utiliser les adresses par défaut définies pour le groupe du patient. Une liste vide désactive les e-mails. Voir E-mails de résultats prêts.
object
requis
L’adresse à laquelle envoyer le kit — sous l’une des deux formes suivantes : soit { location_id } référençant un lieu de test connu, soit les champs d’adresse intégrés (name, street, city, postal_code, country_code ; company_name / house_number / address_line_2 / state / phone / email facultatifs — le même vocabulaire que l’API des lieux). Fournis exactement une des deux options — une référence de lieu ou une adresse intégrée, pas les deux.
Packstation ou Postfiliale (Allemagne uniquement) : définis street sur Packstation ou Postfiliale, house_number sur le numéro de station à trois chiffres, et address_line_2 sur le DHL Postnummer du destinataire (6 à 10 chiffres, espaces autorisés). Sans le Postnummer, le colis ne peut pas être enregistré. Un Postfach n’est pas pris en charge.

Réponse

En cas de succès, l’API renvoie 201 Created avec la nouvelle commande de kit à domicile.
string
requis
Identifiant unique de la commande de kit à domicile (UUID).
string
requis
UUID du profil auquel appartient cette commande de kit à domicile.
string
requis
Statut actuel de la commande de kit à domicile. L’une des valeurs pending, dispatched, activated ou cancelled. Une commande nouvellement créée démarre à pending.
object
requis
L’adresse à laquelle envoyer le kit — deux formats possibles : soit { location_id } faisant référence à un lieu de test connu, soit les champs d’adresse directe (name, street, city, postal_code, country_code ; company_name / house_number / address_line_2 / state / phone / email facultatifs — le même vocabulaire que l’API des lieux). Indique exactement un format — une référence de lieu ou une adresse directe, pas les deux.
object
requis
Les paires clé/valeur que tu as fournies. Toujours présent — {} lorsque tu n’en définis aucune.
string
La commande de kit à domicile que celle-ci remplace. null sur une commande normale.
string
La raison que tu as fournie. null sur une commande normale.
string[]
requis
Adresses en minuscules qui reçoivent chacune un e-mail une fois tous les résultats de laboratoire définitifs. Vide si désactivé. Voir E-mails de résultats prêts.
string
Code d’échantillon de laboratoire sous lequel les résultats sont enregistrés — imprimé sur le kit physique, et que le patient lit sur la boîte comme code d’activation. null tant que le kit n’est pas emballé. En lecture seule.
string
requis
Horodatage du prélèvement transmis via Activer. null tant que le kit n’est pas activé.
string
requis
Horodatage ISO 8601 de la création de la commande de kit à domicile.
string
Horodatage ISO 8601 de la dernière mise à jour. Peut être null.
object
requis
Le profil patient associé à cette commande de kit à domicile.
HomeKitOrderPanel[]
requis
Le panel rattaché à cette commande de kit à domicile — celui que tu as fourni dans panel_id, horodaté avec l’heure de création de la commande. Toujours un seul exactement. Consulte les détails du panel (nom, biomarqueurs) via Lister les panels.
HomeKitOrderIndividualBiomarker[]
requis
Biomarqueurs ajoutés en dehors du panel. Vide lors d’une création normale — les commandes de kit à domicile se font par panel, et modifier cette liste par la suite nécessite le scope de capacité home_kit_orders_individual_biomarker_selection. Sur un remplacement, ce champ contient les biomarker_ids que tu as envoyés, qui correspondent à ce que le laboratoire réanalyse.
HomeKitOrderShipmentLink[]
requis
Colis liés à cette commande de kit à domicile, du lien le plus ancien au plus récent. Toujours vide à la création — consulte les colis complets avec Lister les expéditions et ?home_kit_order_id=.

Réponses d’erreur