Bonnes pratiques de conception des API Expense et Invoice

Bien que vous puissiez consulter les spécifications techniques de chaque API Chrome River dans la boîte à outils de mise en œuvre, cet article couvre les bonnes pratiques de conception spécifiques aux API Chrome River Expense et Invoice.

Voir l’article Présentation des intégrations d’API REST pour plus de détails sur les intégrations d’API REST de Chrome River.

Types d’entité/entité

• Type d’entité :groupe d’entités.
  • Par exemple, les entreprises, les centres de coûts, les unités commerciales et les classes de tarifs aériens sont tous des types d’entités.
  • À moins que votre conception d’API Allocation ne vous oblige à créer de nouveaux types d’entités, ceux-ci peuvent généralement être créés et gérés via l’écran d’administration des entités.
• Entités :éléments compris dans un type d’entité.
  • Par exemple, la première classe, la classe affaires et la classe économique sont toutes des entités appartenant au type d’entité Classes des tarifs aériens.

Les intégrations d’entités de données de base se concentrent généralement sur les données pour prendre en charge les données nécessaires à la conception de votre API Allocation, ainsi que les attributs qui doivent être liés à vos enregistrements Personne.

• Par exemple, les centres de coûts sont généralement utilisés à la fois pour la conception de l’API Allocation et pour la conception de l’API Personne, car une personne peut se voir attribuer un centre de coûts par défaut.

Swagger

https://petstore.swagger.io/?url=https://service.chromeriver.com/entityapi-docs#/

Ressources Entité

• GET /v2/entities
• POST /v1/entities

Ressources Type d’entité 

• GET /v1/entity-types
• POST /v1/entity-types
• GET /v1/entity-types/{code}
• PUT/v1/entity-types/{code}

Allocation

Chrome River Expense permet de rechercher facilement les allocations (votre organisation utilise peut-être les termes dossiers, codes de coût ou d’autres mots) pour l’attribution des postes individuels dans un rapport de dépenses. Ces options doivent être envoyées à Chrome River en tant qu’enregistrements d’allocation afin que les utilisateurs puissent rechercher et choisir où allouer le coût. Reportez-vous au document Spécification d’intégration de fichiers mappé lors de vos ateliers préalables avec notre équipe de mise en œuvre pour comprendre quelles données l’API Allocation doit inclure.

Swagger

https://petstore.swagger.io/?url=https://service.chromeriver.com/allocationapi-docs#/

Ressources

• GET /v3/allocations
• POST /v3/allocations
• GET /v3/allocations/search

Clôture des allocations

Assurez-vous que votre conception d’API Allocation inclut une requête POST avec la date à laquelle l’allocation doit être clôturée. Cela garantira que les utilisateurs n’utilisent pas d’allocations non valides.

[
   {
       "allocationNumber": "0153202020",
       "allocationName": "0015",
       "clientNumber": "0015",
       "clientName": "PROD-OPS",
       "parentClientNumber": "",
       "closedDate": "2025-01-21T00:00:00Z"
   }
]

Entités Allocation

Si votre conception d’API Allocation inclut le lien d’une allocation à des entités pour créer des relations dynamiques, vous devrez envoyer le nom et la valeur de chaque entité comme suit. 

• Nom : Entity1, Entity2 or Entity3
  • Ceci doit être cohérent avec le mappage d’allocation dans l’écran d’administration des entités , où vous avez spécifié quel type d’entité doit être mappé à chacune des trois options d’entité. 
• Valeur :le code de l’entité.

     "allocationEntities": [
           {
               "name": "Entity1",
               "value": "929400"
           }
       ],

udaPerson

Si votre conception d’API Allocation inclut l’affectation d’une personne utilisée dans les règles ou les rapports, vous devrez envoyer person1, person2 ou person3 dans le champ de nom, ainsi que l’ID unique de l’utilisateur souhaité. Cela affecte l’utilisateur à l’un des trois attributs de relation de personne pour l’affectation. 

• Name : person1, person2 ou person3 
• Valeur :l’ID unique de l’utilisateur.

      "udaPersons": [
           {
               "name": "person1",
               "personUniqueId": "USA00004"
           }
       ],

Personne

Swagger

https://petstore.swagger.io/?url=https://service.chromeriver.com/personapi-docs#/

Ressources principales

• GET /v4/persons
• POST /v4/persons
• POST /v4/persons/batch
• GET /v4/persons/{personUniqueId}
• PATCH /v4/persons/{personUniqueId}

Ressources de support

Les ressources de support sont utiles pour fournir des informations spécifiques sur les attributs des entités Personne et les attributs définis par l’utilisateur (UDA) des entités Personne. Ils vous permettent également d’effectuer des mises à jour de ces tableaux individuels sans avoir besoin d’envoyer des informations sur l’enregistrement Personne dans la requête.

• GET /v4/persons/{personUniqueId}/person-entities
• POST /v4/persons/{personUniqueId}/person-entities
• GET /v4/persons/{personUniqueId}/person-entities/{person-entity-id}
• PUT /v4/persons/{personUniqueId}/person-entities/{person-entity-id}
• GET /v4/persons/{personUniqueId}/udas
• POST /v4/persons/{personUniqueId}/udas

Entités Personne versus UDA Personne

L’utilisation de l’API Personne donne à votre organisation plus de flexibilité dans la façon dont les données utilisateur sont stockées. En plus des principaux champs d’enregistrement Personne disponibles, vous avez la possibilité d’ajouter deux types différents de champs personnalisés liés à l’utilisateur : les entités Personne et les UDA Personne. Ces champs sont dynamiques et n’ont pas de nombre limité comme les autres fournisseurs.

Entités Personne

Les entités Personne sont des attributs d’un profil de personne qui sont directement liés à une entité. Les entités peuvent être une entreprise, un centre de coûts ou un service. En utilisant un attribut de relation d’entité, vous vous assurez que la valeur envoyée par les RH est valide et correspond à ce que le service financier attend si les données doivent être renvoyées au système comptable.

L’utilisateur hérite également d’autres attributs de l’entité. Par exemple, si le service a stocké des champs Données supplémentaires 1 à 5, ceux-ci sont désormais liés à l’utilisateur et peuvent faire partie des options de rapport.

  "personEntities": [
       {
           "roleName": "Part Of",
           "entityTypeCode": "DEPT",
           "entityCode": "88003245"
       },

Si ces attributs de données ne sont pas envoyés à Chrome River et que vous ne souhaitez pas les gérer manuellement dans Chrome River, vous pouvez envisager d’utiliser des UDA Personne, qui ne sont pas validés par rapport aux données de l’entité.

UDA Personne

Les champs définis par l’utilisateur (User-Defined Fields, UDA) Personne vous permettent de stocker des données utilisateur qui n’ont pas besoin d’être validées par rapport aux données de l’entité. Ces attributs Personne peuvent être utilisés pour des éléments tels que les règles de gestion et les rapports analytiques. Cependant, si la source est un champ de texte qui peut varier, vous devrez en tenir compte dans les règles qui sont configurées.

Si vous souhaitez utiliser les UDA Personne, votre contact au sein de l’équipe de mise en œuvre ou d’assistance Chrome River peut vous aider à créer des UDA que vous pouvez utiliser dans cette intégration.

 "udas": [
       {
           "name": "UDF1",
           "value": "JOB123"
       },
       {
           "name": "Date_Début_Personne",
           "value": "12/15/2023"
       },
       {
           "name": "Person_DeptGroup",
           "value": "ACCOUNTING"
       }
   ]

Ordre, fréquence et chronologie des requêtes