Skip to content

API Java client Documentation

Jump to bottom
willeybryan edited this page Sep 10, 2019 · 11 revisions

Cette documentation s'adresse aux développeurs intéressés par l'utilisation de la API Java client de notification CDS-SNC pour l'envoi d'e-mails ou de messages texte.

Le système de notification CDS-SNC est basé sur le travail effectué par GOV.UK de Notify.

Remarque importante

Pour vous connecter au système de notification CDS-SNC, vous devez utiliser un client GOV.UK. Cela signifie que certains messages d'erreur que vous obtenez sont spécifiques à GOV.UK Notify et vous lient directement à leur instance. Nous en sommes conscients et nous prévoyons de changer cela à l'avenir avec le développement de nos propres clients.

Nous vous recommandons d'utiliser cette bibliothèque client plutôt que l'API directement, car il n'y a pas de documentation pour utiliser l'API de cette façon

Configurer le client

Installer le client

'notifications-java-client` se déploie à Bintray.

Aller à la page GOV.UK Notify Java page client sur Bintray [lien externe]:

  1. Sélectionnez Set me up! et utilisez les instructions de téléchargement appropriées.
  2. Allez dans la section Paramètres de construction Maven de la page et copiez l'extrait de code de dépendance approprié.

Consulter le client journal des modifications pour le numéro de version et les dernières mises à jour.

Créer une nouvelle instance du client

Ajoutez ce code à votre application :

import uk.gov.service.notify.NotificationClient;
NotificationClient client = new NotificationClient(apiKey, apiEndpoint);

Remarque: Laisser un /à la fin de votre apiEndpoint causera une erreur template missing required fields

Pour obtenir une clé API,identifiez-vous et allez à la page API integration. Vous trouverez plus d'informations dans la sectionclé API de la documentation.

Envoyer un message

Vous pouvez utiliser le système pour envoyer des messages texte ou des e-mails.

envoyer un message SMS

Méthode

SendSmsResponse response = client.sendSms(
    templateId,
    phoneNumber,
    personalisation,
    reference,
    smsSenderId
);

Modificateurs

templateId (nécessaire)

s'identifier and go to the Templates page pour rechercher l'ID de modèle..

String templateId="f33517ff-2a88-4f6e-b855-c550268ce08a";

phoneNumber (nécessaire)

Le numéro de téléphone du destinataire du SMS. Ce numéro peut être un numéro canadien ou international

String phoneNumber="555-555-5555";

personalisation (nécessaire)

Si un modèle comporte des champs réservés à des informations personnalisées telles que le nom ou le numéro de référence, vous devez fournir leurs valeurs dans une carte. Par exemple :

Map<String, Object> personalisation = new HashMap<>();
personalisation.put("first_name", "Amala");
personalisation.put("application_date", "2019-01-01");
personalisation.put("list", listOfItems); // Will appear as a comma separated list in the message

Si un modèle n'a pas de champs de remplacement pour les informations personnalisées, vous devez passer dans une carte vide ou 'null'.

reference (nécessaire)

Un identifiant unique que vous créez. Cette référence identifie un seul avis unique ou un lot d'avis. Il ne doit pas contenir d'informations personnelles telles que le nom ou l'adresse postale. Si vous n'avez pas de référence, vous devez passer dans une chaîne vide ou null.

String reference='STRING';

smsSenderId (optionnelles)

Un identificateur exclusif de l'expéditeur de la notification par SMS. Pour trouver cette information, allez à l'écran Text Message sender settings :

  1. Connectez-vous à votre compte.
  2. aller à Paramètres.
  3. Si vous devez changer de service, sélectionnez Changer de service dans le coin supérieur droit de l'écran et sélectionnez le bon.
  4. aller à les __ Paramètres du message texte__ et sélectionnez Modifier sur la ligne Envoyer des messages textes.

Dans cet écran, vous pouvez ensuite effectuer les opérations suivantes:

  • copier sender ID que vous voulez utiliser et le coller dans la méthode
  • sélectionnez Change pour changer l'expéditeur par défaut que le service utilisera, et sélectionnez Save.
String smsSenderId='8e222534-7f05-4972-86e3-17c5d9f894e2'

Si vous n'avez pas un `smsSenderId', vous pouvez omettre cet modificateur.

Réponse

Si la demande au client est réussie, le client renvoie une SendSmsResponse.:

UUID notificationId;
Optional<String> reference;
UUID templateId;
int templateVersion;
String templateUri;
String body;
Optional<String> fromNumber;

Si vous utilisez la touchetest clé API, tous vos messages reviennent avec un statut `delivered'.

Tous les messages envoyés à l'aide des touchesteam and whitelist oulive apparaissent sur votre tableau de bord.

Codes d'erreur

Si la demande n'aboutit pas, le client renvoie un NotificationClientException contenant le code d'erreur correspondant:

httpResult Message réparer
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient using a team-only API key"
]} 		Utilisez le bon type de clé API
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient when service is in trial mode"
}] 		Votre service ne peut pas envoyer cette notification en mode d'essai.
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}] 		Vérifier l'horloge de votre système
403 [{
"error": "AuthError",
"message": "Invalid token: signature, api token not found"
}] 		Utilisez le bon type de clé API
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"
}] 		Dépassement de la limite de débit API
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (LIMIT NUMBER) for today"
}] 		Refer to service limits for the limit number
500 [{
"error": "Exception",
"message": "Internal server error"
}] 		limite d'envoi dépassée

Envoyer un email

Méthode

SendEmailResponse response = client.sendEmail(
    templateId,
    emailAddress,
    personalisation,
    reference,
    emailReplyToId
);

Modificateurs

templateId (nécessaire)

s'identifier and go to the Templates page pour rechercher l'ID de modèle

String templateId="f33517ff-2a88-4f6e-b855-c550268ce08a";

emailAddress (nécessaire)

L'adresse courriel du destinataire

String emailAddress='sender@something.com';

personnalisation (nécessaire)

Si un modèle comporte des champs réservés à des informations personnalisées telles que le nom ou la date d'application, vous devez fournir leurs valeurs dans une carte. Par exemple:

Map<String, Object> personalisation = new HashMap<>();
personalisation.put("first_name", "Amala");
personalisation.put("application_date", "2018-01-01");
personalisation.put("list", listOfItems); // Will appear as a bulleted list in the message

Si un modèle n'a pas de champs de remplacement pour les informations personnalisées, vous devez passer dans une carte vide ou 'null'.

reference (nécessaire)

Un identifiant unique que vous créez. Cette référence identifie un seul avis unique ou un lot d'avis. Il ne doit pas contenir d'informations personnelles telles que le nom ou l'adresse postale. Si vous n'avez pas de référence, vous devez passer dans une chaîne vide ou 'null'.

String reference='STRING';

emailReplyToId (optionnelles)

Il s'agit d'une réponse par courriel à l'adresse que vous avez indiquée pour recevoir les réponses de vos utilisateurs. Votre service ne peut pas être mis en service tant que vous n'avez pas configuré au moins une de ces adresses courriels. A mettre en place :

  1. Connectez-vous à votre compte.
  2. aller à Paramètres.
  3. Si vous devez changer de service, sélectionnez Changer de service dans le coin supérieur droit de l'écran et sélectionnez le bon.
  4. aller à Paramètres du courriel et sélectionnez Modifier sur la ligne Adresses courriel de réponse.
  5. sélectionnez Configurer pour spécifier l'adresse e-mail de réception des réponses, puis sélectionnez Save.
String emailReplyToId='8e222534-7f05-4972-86e3-17c5d9f894e2'

Si vous n'avez pas de `emailReplyToId', vous pouvez omettre cet modificateur.

Réponse

Si la demande au client est réussie, le client renvoie une SendEmailResponse:

UUID notificationId;
Optional<String> reference;
UUID templateId;
int templateVersion;
String templateUri;
String body;
String subject;
Optional<String> fromEmail;

Codes d'erreur

Si la demande n'aboutit pas, le client renvoie un 'NotificationClientException' contenant le code d'erreur correspondant:

httpResult Message réparer
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient using a team-only API key"
]} 		Utiliser le bon type de clé API
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"
}] 		Votre service ne peut pas envoyer cette notification en mode d'essai.
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}] 		Vérifier l'horloge de votre système
403 [{
"error": "AuthError",
"message": "Invalid token: signature, api token not found"
}] 		Utilisez la bonne clé API.
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"
}] 		Vous avez dépassé votre limite de débit API
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (LIMIT NUMBER) for today"
}] 		Vous avez dépassé votre limite de débit API
500 [{
"error": "Exception",
"message": "Internal server error"
}] 		Notify n'a pas été en mesure de traiter la demande, envoyez à nouveau votre notification.

Envoyer un fichier par email

Envoyez des fichiers sans avoir besoin de pièces jointes.

Il s'agit d'une fonction sur invitation seulement. Contactez-nous pour l'activer.

Pour envoyer un fichier par courriel, ajoutez un champ de remplacement au modèle, puis téléchargez un fichier. Le champ de l'espace réservé contiendra un lien sécurisé pour télécharger le fichier.

Ajouter un champ de caractère de remplissage au modèle

  1. Connectez-vous à votre compte.
  2. aller à Modèles et sélectionnez le modèle de courriel approprié.
  3. Ajoutez un champ de caractère de remplissage au modèle de courriel à l'aide de crochets doubles. Par exemple :

"trouvez votre dossier ici: ((link_to_document))"

Téléchargez votre fichier

Le fichier que vous téléchargez doit être un fichier PDF plus petit que 2MB.

  1. Convertir le PDF en un fichier byte[].
  2. Passez byte[] à l'argument de personnalisation.
  3. Appelez le sendEmail method.

Par exemple:

ClassLoader classLoader = getClass().getClassLoader();
File file = new File(classLoader.getResource("document_to_upload.pdf").getFile());
byte [] fileContents = FileUtils.readFileToByteArray(file);

HashMap<String, Object> personalisation = new HashMap();
personalisation.put("link_to_document", client.prepareUpload(fileContents));
client.sendEmail(templateId,
                 emailAddress,
                 personalisation,
                 reference,
                 emailReplyToId);

Codes d'erreur

Si la requête n'aboutit pas, le client renvoie un HTTPError contenant le code d'erreur correspondant.

error.status_code error.message réparer
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient using a team-only API key"
]} 		Utilisez la bonne clé API)
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"
}] 		Impossible de l'envoyer à ce destinataire lorsque le service est en mode d'essai
400 [{
"error": "BadRequestError",
"message": "Unsupported document type '{}'. Supported types are: {}"
}] 		Le document que vous téléchargez doit être un fichier PDF
400 [{
"error": "BadRequestError",
"message": "Document didn't pass the virus scan"
}] 		Le document que vous téléchargez doit être exempt de virus.
400 [{
"error": "BadRequestError",
"message": "Service is not allowed to send documents"
}] 		Contactez l'équipe SNC Notify
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}] 		vérifier l'horloge de votre système
403 [{
"error": "AuthError",
"message": "Invalid token: signature, api token not found"
}] 		Utilisez la bonne clé API
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"
}] 		Dépassement de la limite de débit de l'API
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (LIMIT NUMBER) for today"
}] 		Dépassement de la limite d'envoi
500 [{
"error": "Exception",
"message": "Internal server error"
}] 		Notify n'a pas été en mesure de traiter la demande, envoyez à nouveau votre notification.
N\A Document is larger than 2MB Le document est plus grand que 2MB

Statut - texte et courriel

Statut Renseignements
Created Notify a placé le message dans une file d'attente, prêt à être envoyé au fournisseur. Il ne devrait rester dans cet état que quelques secondes.
Sending Notify a envoyé le message au fournisseur. Le fournisseur tentera de transmettre le message au destinataire. Notify attend les informations de livraison.
Delivered Le message a été transmis avec succès.
Failed Ceci couvre tous les états de défaillance:
- permanent-failure - "Le fournisseur n'a pas pu livrer le message parce que l'adresse électronique ou le numéro de téléphone était erroné. Vous devez supprimer ces adresses e-mail ou numéros de téléphone de votre base de données. Vous serez toujours facturé pour les messages texte à des numéros qui n'existent pas."
- temporary-failure - "Le fournisseur n'a pas pu livrer le message après avoir essayé pendant 72 heures. Cela peut se produire lorsque la boîte de réception du destinataire est pleine ou lorsque son téléphone est éteint. Vous pouvez réessayer d'envoyer le message. Vous devrez quand même payer des frais pour l'envoi de messages texte à des téléphones qui n'acceptent pas les messages."
- technical-failure - "Votre message n'a pas été envoyé parce qu'il y avait un problème entre Notify et le fournisseur.
Vous devrez réessayer d'envoyer vos messages. Vous ne serez pas facturé pour les messages texte qui sont affectés par une panne technique."

Statut - texte seulement

Statut Renseignements
Pending GOV.UK Notify is waiting for more delivery information.
GOV.UK Notify received a callback from the provider but the recipient's device has not yet responded. Another callback from the provider determines the final status of the notification.
Sent / Sent internationally Le message a été envoyé à un numéro international. Dans certains pays, les réseaux mobiles ne fournissent plus d'informations de livraison. L'API Notify client renvoie cet état sous la forme " envoyé ". L'application Notify client renvoie ce statut comme Envoyé à l'international.

Obtenir le statut d'un message

Méthode

Notification notification = client.getNotificationById(notificationId);

Modificateurs

notificationId (nécessaire)

ID de l'avis. Vous pouvez trouver l'ID de notification dans la réponse à l'appel de la méthode de notification originale).

Vous pouvez aussi le trouver dans votre Tableau de bord.

  1. Connectez-vous à votre compte. Sélectionnez Tableau de bord.
  2. sélectionnez courriels envoyé ou messages textes envoyé
  3. Sélectionnez l'avis approprié.
  4. Copiez l'ID de notification à partir de l'URL de fin de page, par exemple https://notification.alpha.canada.ca/services/af90d4cb-ae88-4a7c-a197-5c30c7db423b/notification/ID.

Response

Si la demande est acceptée, le client retourne un Notification:

UUID id;
Optional<String> reference;
Optional<String> emailAddress;
Optional<String> phoneNumber;
Optional<String> line1;
Optional<String> line2;
Optional<String> line3;
Optional<String> line4;
Optional<String> line5;
Optional<String> line6;
Optional<String> postcode;
Optional<String> postage;
String notificationType;
String status;
UUID templateId;
int templateVersion;
String templateUri;
String body;
Optional<String subject;
DateTime createdAt;
Optional<DateTime> sentAt;
Optional<DateTime> completedAt;
Optional<DateTime> estimatedDelivery;
Optional<String> createdByName;

codes d'erreur

Si la demande n'aboutit pas, le client renvoie un NotificationClientException contenant le code d'erreur correspondant.:

httpResult Message réparer
400 [{
"error": "ValidationError",
"message": "id is not a valid UUID"
}] 		vérifiez la ID de la notification
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}] 		Vérifier l'horloge de votre système
403 [{
"error": "AuthError",
"message": "Invalid token: signature, api token not found"
}] 		Utiliser la bonne clé API.
404 [{
"error": "NoResultFound",
"message": "No result found"
}] 		vérifiez la ID de la notification

Obtenir l'état de plusieurs messages

Cet appel API renvoie une page de 250 messages et statuts au maximum. Vous pouvez obtenir soit les messages les plus récents, soit des messages plus anciens en spécifiant un ID de notification particulier dans le modificateur olderThanId.

Vous ne pouvez obtenir l'état des messages que s'ils datent de sept jours ou plus récents.

méthode

NotificationList notification = client.getNotifications(
    status,
    notificationType,
    reference,
    olderThanId
);

Pour obtenir les messages les plus récents, vous devez passer un argument olderThanId' ou null' vide.

Pour obtenir des messages plus anciens, passez l'ID d'une notification plus ancienne dans l'argument `olderThanId'. Ceci renvoie les messages les plus anciens suivants de l'ID d'avis spécifié.

modificateur

Vous pouvez passer en arguments vides ou `null' pour ignorer ces filtres

statut (optionnelles)

| status | descriptif | textes | courriel | |:--- |:--- |:--- |:--- |:--- |:--- | |created|GOV.UK Notify has placed the message in a queue, ready to be sent to the provider. It should only remain in this state for a few seconds.|Yes|Yes| |sending|GOV.UK Notify has sent the message to the provider. The provider will try to deliver the message to the recipient. GOV.UK Notify is waiting for delivery information.|Yes|Yes| |delivered|The message was successfully delivered|Yes|Yes| |sent / sent internationally|The message was sent to an international number. The mobile networks in some countries do not provide any more delivery information.|Yes|| |pending|GOV.UK Notify is waiting for more delivery information.
GOV.UK Notify received a callback from the provider but the recipient's device has not yet responded. Another callback from the provider determines the final status of the notification.|Yes|| |failed|This returns all failure statuses:
- permanent-failure
- temporary-failure
- technical-failure|Yes|Yes| |permanent-failure|The provider could not deliver the message because the email address or phone number was wrong. You should remove these email addresses or phone numbers from your database. You’ll still be charged for text messages to numbers that do not exist.|Yes|Yes| |temporary-failure|The provider could not deliver the message after trying for 72 hours. This can happen when the recipient's inbox is full or their phone is off. You can try to send the message again. You’ll still be charged for text messages to phones that are not accepting messages.|Yes|Yes| |technical-failure|Email / Text: Your message was not sent because there was a problem between Notify and the provider.
You’ll have to try sending your messages again. You will not be charged for text messages that are affected by a technical failure.

You can leave out this argument to ignore this filter.|Yes|Yes|

notificationType (optional)

You can filter by:

  • email
  • sms

reference (optional)

A unique identifier you create if necessary. This reference identifies a single unique notification or a batch of notifications. It must not contain any personal information such as name or postal address.

String reference='STRING';

olderThanId (optional)

Input the ID of a notification into this argument. If you use this argument, the client returns the next 250 received notifications older than the given ID.

String olderThanId='8e222534-7f05-4972-86e3-17c5d9f894e2'

If you pass in an empty argument or null, the client returns the most recent 250 notifications.

Response

If the request to the client is successful, the client returns a NotificationList:

List<Notification> notifications;
String currentPageLink;
Optional<String> nextPageLink;

Error codes

If the request is not successful, the client returns a NotificationClientException containing the relevant error code:

httpResult Message
400 [{
"error": "ValidationError",
"message": "bad status is not one of [created, sending, sent, delivered, pending, failed, technical-failure, temporary-failure, permanent-failure, accepted, received]"
}] 		Contact the GOV.UK Notify team
400 [{
"error": "ValidationError",
"message": "Applet is not one of [sms, email, letter]"
}] 		Contact the GOV.UK Notify team
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}] 		Check your system clock
403 [{
"error": "AuthError",
"message": "Invalid token: signature, api token not found"
}] 		Use the correct API key. Refer to API keys for more information

Get a template

Get a template by ID

Method

This returns the latest version of the template.

Template template = client.getTemplateById(templateId);

Arguments

templateId (required)

Sign in and go to the Templates page to find the template ID.

String templateId='f33517ff-2a88-4f6e-b855-c550268ce08a';

Response

If the request to the client is successful, the client returns a Template:

UUID id;
String name;
String templateType;
DateTime createdAt;
Optional<DateTime> updatedAt;
String createdBy;
int version;
String body;
Optional<String> subject;
Optional<Map<String, Object>> personalisation;

Error codes

If the request is not successful, the client returns a NotificationClientException containing the relevant error code:

httpResult Message How to fix
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}] 		Check your system clock
403 [{
"error": "AuthError",
"message": "Invalid token: signature, api token not found"
}] 		Use the correct API key. Refer to API keys for more information
404 [{
"error": "NoResultFound",
"message": "No Result Found"
}] 		Check your template ID

Get a template by ID and version

Method

Template template = client.getTemplateVersion(templateId, version);

Arguments

templateId (required)

Sign in and go to the Templates page to find the template ID.

String templateId='f33517ff-2a88-4f6e-b855-c550268ce08a';

version (required)

The version number of the template.

Response

If the request to the client is successful, the client returns a Template:

UUID id;
String name;
String templateType;
DateTime createdAt;
Optional<DateTime> updatedAt;
String createdBy;
int version;
String body;
Optional<String> subject;
Optional<Map<String, Object>> personalisation;

Error codes

If the request is not successful, the client returns a NotificationClientException containing the relevant error code:

httpResult message How to fix
400 [{
"error": "ValidationError",
"message": "id is not a valid UUID"
}] 		Check the notification ID
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}] 		Check your system clock
403 [{
"error": "AuthError",
"message": "Invalid token: signature, api token not found"
}] 		Use the correct API key. Refer to API keys for more information
404 [{
"error": "NoResultFound",
"message": "No Result Found"
}] 		Check your template ID and version

Get all templates

Method

This returns the latest version of all templates.

TemplateList templates = client.getAllTemplates(templateType);

Arguments

templateType (optional)

If you don’t use templateType, the client returns all templates. Otherwise you can filter by:

  • email
  • sms

Response

If the request to the client is successful, the client returns a TemplateList:

List<Template> templates;

If no templates exist for a template type or there are no templates for a service, the templates list is empty.

Generate a preview template

Method

This generates a preview version of a template.

TemplatePreview templatePreview = client.getTemplatePreview(
    templateId,
    personalisation
);

The parameters in the personalisation argument must match the placeholder fields in the actual template. The API notification client ignores any extra fields in the method.

Arguments

templateId (required)

Sign in and go to the Templates page to find the template ID.

String templateId='f33517ff-2a88-4f6e-b855-c550268ce08a';

personalisation (required)

If a template has placeholder fields for personalised information such as name or application date, you must provide their values in a map. For example:

Map<String, Object> personalisation = new HashMap<>();
personalisation.put("first_name", "Amala");
personalisation.put("application_date", "2018-01-01");

If a template does not have any placeholder fields for personalised information, you must pass in an empty map or null.

Response

If the request to the client is successful, the client returns a TemplatePreview:

UUID id;
String templateType;
int version;
String body;
Optional<String> subject;
Optional<String> html;

Error codes

If the request is not successful, the client returns a NotificationClientException containing the relevant error code:

httpResult message How to fix
400 [{
"error": "BadRequestError",
"message": "Missing personalisation: [PERSONALISATION FIELD]"
}] 		Check that the personalisation arguments in the method match the placeholder fields in the template
400 [{
"error": "NoResultFound",
"message": "No result found"
}] 		Check the template ID
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}] 		Check your system clock
403 [{
"error": "AuthError",
"message": "Invalid token: signature, api token not found"
}] 		Use the correct API key. Refer to API keys for more information
Clone this wiki locally