API new year!

A l’occasion de cette nouvelle année je vous souhaite plein de POST, GET, PATCH et autres « bound actions »!

Avec cette série d’articles plus techniques qu’à l’accoutumée,  poursuivons notre immersion dans le monde merveilleux des APIs.

Si vous avez raté les précédents épisodes, retrouvez :

• API birthday! – Wanamics
• API, ma première requête – Wanamics
• API, webhook – Wanamics

L’utilisation des APIs de Business Central depuis une application tierce, ne présente pas de particularité.

Elles sont de type REST assorties des actions CRUD (Create, Read, Update, Delete) et règles de gestion correspondantes.

Authentification

Voir aussi Montrez patte blanche avec OAuth2 – Wanamics

S’il s’agit d’une interaction avec un utilisateur authentifié, les autorisations de celui-ci sont appliquées (« on behalf of »).

S’il s’agit d’un échange entre applications (Service to Service), l’authentification relève de son inscription dans Azure Entra ID (anciennement Azure Active Directory) et des droits qui lui sont accordés (recherchez « Applications Microsoft Entra »).

Nommage

Vous noterez que les noms des champs exposés via l’API, outre le fait qu’ils débutent par une minuscule conformément aux conventions, ne correspondent pas exactement aux champs utilisés dans Business Central.

Ainsi par exemple, pour l’API customers, les champs « number », « displayName », « addressLine1 », « addressLine2 », « postalCode » correspondent respectivement aux champs « No. », « Name », « Address », « Address 2 », « Post Code » de Business Central (ou encore « N° »,  « Nom », « Adresse », « Adresse (2ème ligne) », « Code postal » en langue ‘French’ !).

Remarquez aussi que l’identifiant interne « id » utilisé par l’API, correspond au champ « SystemId » de Business Central (invariant contrairement au « N° » qui peut être renommé).

Exemples

Voici quelques exemples de requêtes (via PostMan) avec l’API customers https://api.businesscentral.dynamics.com/v2.0/{{tenantId}}/{{environmentName}}/api/v2.0/companies({{companyId}})/customers

POST

Création d’un client, avec en ‘Response’ « number » (« No. »/ »N° ») et « id » (SystemId) attribués

Notez que, outre les règles de gestion habituelles (identiques à celles appliquées en saisie manuelle), des contrôles propres à l’API peuvent être appliqués.

Ainsi, si vous avez omis de préciser le nom du client (displayName), vous obtiendrez une erreur : 400 Bad Request

{
    « error »: {
        « code »: « Application_DialogException »,
        « message »: « A \ »displayName\ » must be provided.  CorrelationId:  188d7182-b2c8-42f8-b954-c0dc41730c85. »
    }
}

GET

Lecture de ce même client en précisant son « id » (…/customers(afbf5d63-4e9b-ee11-be36-6045bd19ad41)

PATCH

Modification de ce même client (ayant déménagé de Lille à Paris)

Les champs modifiés sont définis en Body :

{
    « addressLine1 »: « rue de Lille »,
    « postalCode »: « 75007 »,
    « city »: « PARIS »
} 

Attention : l’information « @odata.etag » obtenue par le GET préalable doit être reprise en Header ‘If-Match’ (à l’exception des caractères superflus \ et des guillemets de début et fin) :

« @odata.etag »: « W/\« JzE4Ozk2NjY1MTQzNzE3MzM0OTI4ODE7MDA7Jw==\« « 
If-Match : W/ »JzE4Ozk2NjY1MTQzNzE3MzM0OTI4ODE7MDA7Jw== »

« @odata.etag » est une version (ou TimeStamp) de l’enregistrement, modifiée à chaque mise à jour, pour gérer les mises à jour concurrentes.

Suite au PATCH, cette information a donc été modifiée :

« @odata.etag »: « W/\ »JzIwOzExNTkyNzIwNTE5ODQ5NDUyNTc1MTswMDsn\ » »,

C’est pourquoi, si vous tentez une nouvelle modification sans modifier le « If-Match », vous obtiendrez une erreur (Status: 409 : Conflict) :

{
    « error »: {
        « code »: « Request_EntityChanged »,
        « message »: « Another user has already changed the record.  CorrelationId:  96df28a4-151e-43c3-89e4-273a979e197e. »
    }
}

DELETE

Le « Status » : 204 No Content, confirme que le client a été supprimé :

Notez que le Header ‘If-Match’ est ici désactivé.

S’il reste actif, la valeur doit correspondre à celle de la dernière mise à jour.

Autres actions

Outre les actions classiques ‘CRUD’ illustrées ci-dessus, certaines APIs disposent de ‘Bound actions’ ou méthodes associées, bien décrites dans ces articles :

• Dynamics 365 Business Central: How to use Standard/Custom API Bound Actions | Dynamics 365 Lab (yzhums.com)
• What Are Bound Actions In Business Central APIs – Business Central Geek

Ainsi par exemple, après avoir créé une facture, vous pouvez déclencher sa validation.

Ces actions pourront en particulier être utilisées via Power Automate.