Développeurs OneSpan Sign : Gérer les transactions de l'expéditeur - Partie 2

Duo Liang, février 2, 2022

OneSpan-BlogImage-Manage Sender's Transactions-Part2.jpg

Les comptes d'administration sont destinés aux personnes chargées d'administrer l'application, ce qui permet à l'administrateur d'en faire beaucoup plus que les expéditeurs ordinaires. Ces privilèges comprennent la gestion des transactions d'autres expéditeurs, la vérification de l'état de la signature, le téléchargement des documents signés, etc.

Dans le blog de la partie 1, nous avons exploré la manière d'accorder à votre utilisateur administrateur les autorisations appropriées et d'envoyer des transactions en son nom. Nous allons poursuivre là où nous nous sommes arrêtés et passer en revue d'autres opérations que vous pouvez effectuer pour gérer les transactions d'autres expéditeurs. Sans plus attendre, commençons !

Gestion des transactions des expéditeurs

Pour gérer toutes les transactions de vos expéditeurs, assurez-vous que l'utilisateur admin a reçu les autorisations nécessaires :

Si la fonction Rôles et autorisations est activée sur votre compte, assurez-vous que l'utilisateur admin s'est vu attribuer un rôle avec au moins les autorisations "Accès API" et "Gérer les transactions des utilisateurs, les modèles, les mises en page (API)"
Sinon, accordez des droits de gestionnaire à votre utilisateur administrateur, comme indiqué dans la capture d'écran ci-dessous

Si vous disposez d'un identifiant de transaction, que la transaction ait été créée par un autre expéditeur ou par un administrateur au nom de l'expéditeur, vous aurez un accès API direct à la transaction si vous authentifiez votre appel API/SDK en tant qu'utilisateur administrateur :

Demande HTTP

GET /api/packages/{packageId}

En-têtes HTTP

Authentification : Basic {api_key} / Bearer {api_token}
Accept : application/json

Comme l'utilisateur admin a un accès complet à la ressource de transaction, vous pourrez invoquer d'autres API sous le point de terminaison "/api/packages", comme la mise à jour des informations d'un signataire existant :

Requête HTTP

PUT /api/packages/{packageId}/roles/{roleId}

En-têtes HTTP

Authentification : Basic {api_key} / Bearer {api_token}
Accept : application/json   
Content-Type : application/json

Charge utile de la requête

{
  "type" : "SIGNER",
  "signers" : [
    {
      "email" : "[email protected]",
      "firstName" : "Mary",
      "lastName" : "Doe"
    }
  ]
}

Ou pour télécharger des documents signés :

Demande HTTP

GET /api/packages/{packageId}/documents/zip

En-têtes HTTP

Authentification : Basic {api_key} / Bearer {api_token}
Accept : application/zip

Lister toutes les transactions

Si vous n'avez pas enregistré l'identifiant de la transaction localement, vous pourrez néanmoins dresser la liste de toutes les transactions créées par un certain expéditeur :

Requête HTTP

GET /api/packages?from=1&to=100&ownerUserId={sender_id}
GET /api/packages?from=1&to=100&ownerEmail={sender_email}

En-têtes HTTP

Authentification : Basic {api_key} / Bearer {api_token}
Content-type : application/json
Accept : application/json

Paramètres

ownerUserId & ownerEmail: Par défaut, cet appel API ne renvoie que les transactions de l'appelant API. Toutefois, si vous spécifiez le ownerUserId ou le ownerEmail en tant que paramètre de requête, cette API renverra les transactions de l'utilisateur spécifié.

L'exemple ci-dessus vous donne une brève idée de la manière de construire l'URL de l'API. Il existe en fait d'autres paramètres qui vous permettent de récupérer les transactions d'un expéditeur avec plus de souplesse :

query: Demande un certain statut de transactions. Les valeurs disponibles sont ARCHIVED, COMPLETED, DRAFT, SENT, EXPIRED, OPTED_OUT, DECLINED et TRASHED. L'action TRASH n'est pas considérée comme un statut de transaction. Étant donné que les réponses des autres statuts excluent la transaction TRASH, vous devez toujours rechercher les transactions mises à la poubelle à l'aide de ce paramètre.
from & to: Indiquez le nombre de transactions renvoyées à des fins de pagination. Par exemple, si la taille de votre page est de 100, votre requête pourrait être "&from=1&to=100", "&from=101&to=200", etc. Un maximum de 100 transactions peut être retourné en un seul appel.
lastUpdatedStartDate & lastUpdatedEndDate: Renvoie les transactions dont la dernière mise à jour se situe dans cet intervalle de temps. Les requêtes sont précises au jour près et le format de la date doit être "aaaa-MM-jj".
search & searchtype: Le mot-clé du paramètre "search" sera utilisé pour rechercher le nom ou la description d'une transaction, ou le nom et le prénom d'un signataire ainsi que son adresse électronique. En conjonction avec "searchtype", l'appelant de l'API peut choisir d'effectuer une recherche par joker (lorsque searchtype est vide) ou une recherche plus restrictive (lorsque searchtype est "exact" ou "exactname").

Nous apprécions vos commentaires

Ceci conclut le blog d'aujourd'hui. Si vous avez accordé à l'utilisateur administrateur des autorisations suffisantes, cela vous évite de devoir récupérer la clé API de chaque expéditeur et vous permet de contrôler directement les transactions d'autres expéditeurs. L'apprentissage des meilleures pratiques présentées dans ce blog peut s'avérer extrêmement utile pour gérer les transactions des utilisateurs de votre compte.

Si vous avez des questions concernant ce blog ou tout autre sujet relatif à l'intégration de OneSpan Sign dans votre application, visitez les forums de la communauté des développeurs. Vos commentaires nous intéressent !