Best Practices für das Design der Ausgaben- und Rechnungs-API

Sie können zwar technische Spezifikationen für jede Chrome River-API im Implementierungs-Toolkit einsehen, dieser Artikel befasst sich jedoch mit Best Practices für das Design der Chrome River Expense- und Rechnungs-APIs.

Ausführliche Informationen zu den REST-API-Integrationen von Chrome River finden Sie unter Übersicht über die REST-API-Integrationen.

Listentypen/Listen

• Listentyp:Beispiel:
  • Unternehmen, Kostenstellen, Geschäftseinheiten und Flugpreisklassen sind beispielsweise alle Listentypen.
  • Sofern Ihr Zuordnungs-API-Design nicht erfordert, dass Sie neue Listentypen erstellen, können diese in der Regel über den Bildschirm Listen-Admin erstellt und verwaltet werden.
• Listen: Einzelne Elemente in einem Listentyp.
  • Beispiel: Innerhalb des Listentyps „Serviceklassen im Flugwesen“ gibt es die First-, die Business- sowie die Economy-Class, die alle einzelne Listen innerhalb des übergreifenden Listentyps sind.

Die Integration von Stammdatenlisten konzentriert sich in der Regel auf Daten, die für das Design Ihrer Zuordnungs-API benötigt werden, sowie auf die Attribute, die mit Ihren Personendatensätzen verknüpft werden müssen.

• Kostenstellen werden beispielsweise normalerweise sowohl für das Design der Zuordnungs-API als auch für das Design der Personen-API verwendet, da einer Person eine Standardkostenstelle zugewiesen werden kann.

Swagger

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

Listen-Ressourcen

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

Listentyp-Ressourcen 

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

Zuordnung

Bei der Zuordnung von Belegpositionen zu einer Spesenabrechnung ermöglicht Chrome River Expense es Ihnen, einfach nach Zuordnungen (die Ihr Unternehmen neben Zuordnung unter anderem auch als Kostencode bezeichnen kann) zu suchen. Diese Optionen müssen als Zuordnungsdatensätze an Chrome River gesendet werden, damit die Benutzer suchen und auswählen können, wo die Kosten zugeordnet werden sollen. Welche Daten die Zuordnungs-API enthalten soll, entnehmen Sie bitte dem Dokument „Datei-Integrationsspezifikation“, das Sie in den Workshops mit unserem Implementierungsteam vor der Implementierung erhalten haben.

Swagger

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

Ressourcen

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

Abschließen von Zuordnungen

Stellen Sie sicher, dass Ihr Zuordnungs-API-Design eine Post-Anforderung mit dem Datum enthält, an dem die Zuordnung geschlossen werden soll. Dadurch wird sichergestellt, dass Benutzer keine ungültigen Zuordnungen verwenden.

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

Zuordnungs-Listen

Wenn Ihr Zuordnungs-API-Design die Verknüpfung einer Zuordnung mit Listen vorsieht, um dynamische Beziehungen zu erstellen, müssen Sie den Namen und den Wert jeder Liste wie folgt senden. 

• Name: Liste1, Liste2 oder Liste3
  • Dies sollte mit der Zuordnung im Bildschirm Listen-Admin übereinstimmen, wo Sie angegeben haben, welcher Listentyp jeder der drei Listenoptionen zugeordnet werden soll. 
• Wert: Listentypen-Code.

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

udaPerson

Wenn Ihr Zuordnungs-API-Design die Zuordnung einer Person beinhaltet, die in Regeln oder Berichten verwendet wird, müssen Sie Person1, Person2 oder Person3 im Namensfeld zusammen mit der einzigartigen ID des gewünschten Benutzers senden. Dadurch wird dem Benutzer eines der drei Personenbeziehungsattribute für die Zuordnung zugeordnet. 

• Name: Pperson1, person2 oder person3 
• Wert: Einzigartige ID des Benutzers.

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

Person

Swagger

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

Primäre Ressourcen

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

Unterstützende Ressourcen

Die unterstützenden Ressourcen sind hilfreich, um spezifische Informationen für Personenlisten-Attribute und Personen-UDAs bereitzustellen. Sie ermöglichen es Ihnen auch, Aktualisierungen an diesen einzelnen Arrays vorzunehmen, ohne dass Sie andere Personendatensätze in der Anfrage senden müssen.

• 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

Personenlisten vs. Personen-UDAs

Die Verwendung der Personen-API gibt Ihrem Unternehmen mehr Flexibilität bei der Speicherung von Benutzerdaten. Zusätzlich zu den verfügbaren Feldern für den Hauptpersonendatensatz haben Sie die Möglichkeit, zwei verschiedene Arten von benutzerdefinierten Feldern hinzuzufügen, die mit dem Benutzer verknüpft sind: Personenlisten und Personen-UDAs. Diese sind dynamisch und haben keine begrenzte Anzahl wie andere Anbieter.

Personenlisten

Personenlisten sind Attribute eines Personenprofils, die direkt mit einer Liste verknüpft sind. Listen können Unternehmen, Kostenstellen oder Abteilungen umfassen. Durch die Verwendung eines Listenbeziehungsattributs stellen Sie sicher, dass der von der Personalabteilung gesendete Wert gültig ist und dem entspricht, was die Finanzabteilung erwartet, wenn die Daten an das Buchhaltungssystem zurückgesendet werden müssen.

Der Benutzer erbt auch andere Attribute der Liste. Wenn die Abteilung beispielsweise zusätzliche Datenfelder 1–5 gespeichert hat, sind diese nun mit dem Benutzer verknüpft und können Teil der Berichtsoptionen sein.

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

Wenn diese Datenattribute nicht an Chrome River gesendet werden und Sie sie nicht manuell in Chrome River verwalten möchten, sollten Sie die Verwendung von Personen-UDAs in Betracht ziehen, die nicht gegen Listendaten validiert sind.

Personen-UDAs

Personen-UDAs (User-Defined Fields) ermöglichen es Ihnen, Benutzerdaten zu speichern, die nicht anhand von Listendaten validiert werden müssen. Diese Personenattribute können für Dinge wie Geschäftsregeln und Analyseberichte verwendet werden. Wenn es sich bei der Quelle jedoch um ein Textfeld handelt, das variieren kann, müssten Sie dies bei den Regeln berücksichtigen.

Wenn Sie an der Verwendung von Personen-UDAs interessiert sind, kann Ihnen Ihr Chrome River-Implementierungs- oder Support-Ansprechpartner bei der Erstellung von UDAs helfen, die Sie für diese Integration verwenden können.

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

Bestellung, Häufigkeit und Zeitpunkt von Anforderungen