API pour la récupération de données — Formulaires GC

Effectuer des demandes

L’API de Formulaires GC vous permet de récupérer des soumissions de formulaire sous forme de fichiers JSON. Vous pouvez obtenir jusqu’à 100 soumissions de formulaire par lot, et celles-ci sont accessibles jusqu’à 30 jours après la soumission, compte tenu de nos périodes actuelles de rétention des données. Les soumissions de formulaire sont chiffrées à l’aide d’une clé publique et peuvent être déchiffrées localement par vous.

Paramètres de requête

Les demandes d’API pour les données de soumission de Formulaires GC sont possibles à l’aide de paramètres de requête tels que :

• {formID} L’identifiant de formulaire est une chaîne alphanumérique de 25 caractères trouvée à la fin de l’URL du formulaire ou au début du nom de fichier de la clé API. Par exemple : clzvj8fzb00226o90r2b7l1gt.
• {SubmissionName} Le nom de la soumission est une chaîne alphanumérique de 11 caractères, y compris les tirets, parfois appelée identifiant de soumission dans l’application Formulaires GC.
  Par exemple : e02-08-d732.
• {ConfirmationCode} Le code de confirmation est une chaîne alphanumérique de 36 caractères, y compris les tirets, parfois appelée code de réception dans l’application Formulaires GC.
  Par exemple : 620b203c-9836-4000-bf30-1c3bcc26b834.

Exemples d’intégration

Nous avons élaboré quelques exemples auxquels vous pouvez vous référer, ou pour lesquels vous pouvez exécuter le programme, et qui, nous l’espérons, faciliteront l’intégration. Voici les langages de programmation disponibles à l’heure actuelle :

• .NET / C#
• Node.JS / Typescript
• Python
• Bash /Curl

Travaillez avec votre équipe de développement pour tester une ébauche de formulaire et vous assurer que l’intégration de l’API reçoit des réponses, qu’elle est capable de décrypter, de vérifier le hachage et de confirmer les réponses ou de signaler un problème. Une fois ce processus terminé, vous êtes prêt à publier votre formulaire avec cette méthode de livraison des données.

Récupérer des nouvelles soumissions de formulaires

Demande HTTP

Ce chemin d’URL renvoie une liste de soumissions qui comprend les 100 plus anciennes soumissions de formulaire ayant le statut « Nouveautés » :

GET /forms/{formID}/submission/new

Remarque : Le statut de ces soumissions de formulaire ne passera pas à « Téléchargé ».

Statut de la réponse

Récupérer des soumissions de formulaires spécifiques

Obtenir la soumission du formulaire

Demande HTTP

Ce chemin d’URL renvoie une soumission de formulaire par demande en fonction du nom de soumission respectif : GET /forms/{formID}/submission/{submissionName}

Remarque : La récupération n’est possible que pour une soumission, avec un téléchargement par demande. Le statut de ces soumissions de formulaire ne passera pas à « Téléchargé ». Pour modifier le statut des soumissions de formulaires, faites une demande de confirmation des soumissions de formulaire une fois qu’elles ont été correctement reçues.

Statut de la réponse

Déchiffrement des données

La sécurité du système est primordiale et elle est renforcée par le chiffrement des soumissions de formulaires. Bien que le chiffrement soit effectué en HTTPS, nous avons ajouté une autre couche de sécurité avec le chiffrement AES-256-GSM. Lorsque vous recevrez une soumission de formulaire, elle sera chiffrée et elle comprendra une clé chiffrée, un nonce chiffré et un élément AuthTag chiffré. Ceux-ci peuvent être déchiffrés par l’intermédiaire d’une clé privée.

Confirmer des soumissions de formulaires

L’étape de confirmation permet de s’assurer que les formulaires soumis sont exploitables et s’affichent comme prévu avant qu’ils ne soient définitivement retirés de la base de données du système Formulaires GC.

Demande HTTP

Le chemin d’URL confirme que les soumissions de formulaires ont bien été récupérées à partir du système et les supprime :

PUT /forms/{formID}/submission/{submissionName}/confirm/{confirmationCode}

Remarque : La confirmation n’est possible que pour une soumission à la fois, avec un code de confirmation par requête. Le statut de cette soumission passera de « Nouveautés » à « Confirmations ». Il s’agit d’un processus similaire au processus en deux étapes de téléchargement et d’approbation de la suppression dans l’application.

Statut de la réponse

Signaler un problème avec la soumission de formulaire

Demande HTTP

Ce chemin d’URL identifie une soumission de formulaire comme ayant un problème si un évènement inattendu se produit :

POST /forms/{formID}/submission/{submissionName}/problem

Remarque : Le signalement d’un problème n’est possible que pour une seule soumission à la fois. Vous pouvez signaler un problème avec les soumissions de formulaires portant le statut « Nouveautés » ou « Confirmations » tant qu’elles n’ont pas été supprimées du système. Cela changera le statut en « Problème » et bloquera la suppression de la soumission du système jusqu’à ce que le problème soit résolu.

Exemple de charge utile pour le signalement d’un problème

Pour signaler un problème, incluez un message au format similaire à celui ci-dessous dans le corps de la requête HTTP POST :

{ “contactEmail”: “nom@ministere.gc.ca”, “description”: “Voici mon problème”, “preferredLanguage”: “fr” (soit “en” ou “fr”) }

Remarque : Ce message sera transmis à notre équipe de soutien.

Statut de la réponse

Obtenir les questions du formulaire

Demande HTTP

Ce chemin d’URL récupère les questions qui ont été posées au format JSON afin qu’elles puissent être plus facilement associées aux réponses récupérées :

GET /forms/{formID}/template

Remarque : Les questions seront dans une structure de données au format JSON lorsqu’elles seront récupérées. Cela est utile si vous transformez les données et que vous devez faire correspondre les réponses aux questions.

Statut de la réponse