Interface UPIServices

UPIServices est un bouquet de services permettant à une application informatique d’interagir avec la base de données UPI.

Ces services permettent d’interroger UPI sur la base d’un numéro AVS ou
alternativement à l’aide de caractères d’identification usuels. Ils permettent également de s’informer sur les mutations dans UPI durant une période donnée, comme les changements de statut de numéros AVS, les personnes ayant changé de nom ou les décès survenus (service dit de broadcast des mutations). Ils permettent aussi à une organisation souhaitant introduire le numéro AVS en masse dans leur registre de personnes de les obtenir en tout autonomie et à leur guise en interrogeant la base de données UPI. Enfin, ils offrent une fonction de comparaison globale d’un registre de personnes avec le contenu d’UPI, signalant en retour les différences constatées dans les caractères d’identification.

La mise en œuvre de ces services au sein d’une application informatique
nécessite des travaux de programmation spécifiques, et donc l’intervention d’experts en développement logiciel.

La version 1 des UPIServices sera abandonnée au 31 décembre 2025 et la version 2, non compatible avec la version 1, sera disponible à partir du 1er janvier 2024. Si vous souhaitez implémenter les UPIServices, nous vous recommandons donc la version 2 des interfaces. Elle sera disponible pour les premiers tests dès le début du mois de juillet 2023. Pour plus d’informations, veuillez consulter la page Harmonisation des caractères spéciaux dans les registres officiels de personnes.

Obtenir un accès

Avant toute demande d'accès à UPIServices, l'organisation à laquelle vous appartenez doit obligatoirement avoir été reconnue par la Centrale en tant qu'utilisateur systématique du NAVS13 dans le domaine d'activité pour lequel vous allez utiliser le NAVS13. Nous vous demandons par conséquent de bien vouloir vérifier son statut en consultant l'annuaire des utilisateurs systématiques du NAVS13. Si votre organisation n'y figure pas ou y est déclarée sous une autre activité, nous vous invitons à faire remplir en ligne l'annonce de l'utilisation systématique du NAVS13 par la personne de votre organisation agréée à produire une telle démarche (typiquement un membre de la Direction de votre organisation). Une fois ces conditions remplies, vous pourrez faire une demande d'accès à UPIServices en complétant le formulaire ci-dessous et en l’envoyant par e-mail à : [e-mail]

Formulaire de demande d’accès aux services UPI (PDF, 279 kB, 23.09.2021)

Modes d’utilisation

Le service de broadcast des mutations dans UPI n’est disponible qu’en mode asynchrone via Sedex (un service d’échange de données sécurisé proposé par l’Office fédéral de la statistique OFS).

Les autres services peuvent être exploités selon les deux modes suivants :

• Mode synchrone, dédié à l'interrogation ponctuelle et requérant une réponse immédiate par l'application cliente.
• Mode asynchrone, dédié aux consultations de masse. A partir d'un volume dépassant 100 interrogations consécutives l'utilisation de ce mode est obligatoire.

Conditions d'utilisation

Les utilisateurs des UPIServices doivent impérativement respecter les règles d'utilisation définies ci-dessous :

Mode synchrone

Mode de traitement « temps réel », dédié à l'interrogation ponctuelle et requérant une réponse immédiate par l'application cliente. Ce mode est soumis aux restrictions suivantes :

a) En cas de requêtes multiples, celles-ci doivent être sérialisées: vous devez attendre la réponse de la requête numéro N avant d'émettre la requête numéro N+1.

b) Pas plus de 30 personnes par minute ne doivent être interrogées / recherchées / comparées (tolérance de 10). Par exemple, en cas de requêtes en rafale contenant une personne par requête, cette limitation peut être implémentée simplement, en introduisant un temps d'inactivité de 1.5 à 2 secondes entre 2 requêtes consécutives.

c) Au cours d'une année civile, le nombre total de requêtes ne doit pas excéder 12 fois la taille de votre « base de données client ». Autant que possible, les requêtes doivent être réparties uniformément sur l'année.

L'utilisation du mode synchrone exige le respect conjoint des points a)+b)+c). Si cela n'est pas possible, le mode différé (asynchrone) est obligatoire.

Mode asynchrone

Mode de traitement différé, dédié aux consultations par lot. Ce mode est soumis à la restriction suivante :

En l'absence d'accord préalable de la CdC (s'adresser au service de support à la clientèle UPI), le volume total soumis sur une plage de 24h ne doit pas excéder 300'000 requêtes.

De plus, la CdC émet les recommandations suivantes pour le mode asynchrone :

a) la taille de lot ne devrait pas excéder 1'000'000 requêtes.

b) dans le cas particulier de l'opération listOfSearchPerson du service implémentant la norme eCH-0085, la taille de lot de devrait pas excéder 10'000 requêtes.

Le but de ces recommandations est d'éviter des problèmes liés à la manipulation de très gros fichiers et de garantir un temps de traitement raisonnable.

---

Spécifications techniques

La communication avec UPI au travers des UPIServices s'opère à l'aide de messages au format XML. La syntaxe de ces messages est définie au moyen de documents dits « schémas XML », exprimés dans le langage technique XSDL (XML Schema Definition Language).

Les schémas dédiés au fonctionnement d'UPI ont été reconnus par l'association eCH (www.ech.ch) et intègrent pleinement les standards reconnus en matière d'e-government. Les numéros eCH attribués à ces schémas sont :

• Annonce (écriture) à UPI : eCH-0084
• Interrogation (lecture) d'UPI : eCH-0085
• Comparaison (lecture) avec UPI : eCH-0086
• Annonces de mutations dans UPI à des tiers (broadcast) : eCH-0212

Les dernières versions intégrées des schémas eCH-0084, eCH-0085, eCH-0086 et des WSDL sont disponibles ci-dessous. Vous y trouverez également quelques exemples de messages XML.

schema-UPI_20210430.zip (ZIP, 150 kB, 21.05.2021)

wsdl_20210430.zip (ZIP, 5 kB, 21.05.2021)

La description des trois interfaces d'applications basées sur un protocole Request/Response orienté messages que le système UPI implémente est disponible dans le document ci-dessous.

Spécifications de l’interface UPI (Unique Person Identification) V1.10 (PDF, 1 MB, 30.08.2021)

La dernière version du schéma eCH-0212 et la documentation qui l’accompagne sont disponibles sur le site de l’association eCH.

Caractéristiques des services UPI

Le tableau ci-dessous décrit les caractéristiques des services UPI disponibles en mode synchrone.

Nom	eCH	Sedex wsproxy
UPI eCH-0084 Master Certif	84	X (1)
UPI eCH-0085 Master Certif	85	X
UPI eCH-0086 Master Certif	86	X

(1) Nécessite une configuration spéciale qui peut être demandée à l’adresse e-mail suivante : [e-mail]

En outre, un service est proposé pour permettre l'échange de fichiers avec UPI, via un canal sedex (par l’intermédiaire du réseau interne de la Confédération), en mode asynchrone.

Nom	eCH	Sedex ID
UPI Daemon Master	84,85,86,212	(T)3-CH-24

Le service de broadcast des mutations dans UPI n’est disponible qu’en mode asynchrone via sedex.

Description des colonnes

• Nom : indique le nom du service.
• eCH : contient la liste des normes eCH implémentées par le service (par exemple 84 signifie que la norme eCH-0084 est implémentée).
• Sedex wsproxy : une croix dans cette colonne indique que ce service peut être atteint via le wsproxy fourni avec sedex. Pour faciliter la gestion des certificats, la CdC recommande l’utilisation du wsproxy.
• Sedex-ID : Dans le cas de services asynchrones où la transmission de données se fait via la plateforme sedex, cette colonne indique le sedex ID du destinataire à mettre dans l'enveloppe d'un message sedex envoyé à ce service.

Mise à jour des certificats serveur

Les certificats ayant une durée de vie limitée, il est nécessaire de les remplacer périodiquement. Ceci concerne aussi bien les certificats utilisés par les clients que ceux installés sur le serveur hébergeant les webservices. Un renouvellement du certificat serveur n'affecte pas les utilisateurs des UPIServices passant uniquement sedex ou le wsproxy de sedex. C’est notamment pour cette raison que la CdC déconseille tout autre chemin d’accès aux UPIServices.

Dernière modification 09.02.2023