Allgemeines zur API Nutzung
Mit Hilfe der be.ENERGISED API haben Sie die Möglichkeit, Funktionen der Software über Drittsysteme zu automatisieren und zu steuern. In be.ENERGISED unter Einstellungen/Systemeinstellungen/API-Einstellungen können Sie die notwendigen Einstellungen vornehmen.
Bitte beachten Sie, dass die API eine kostenpflichtige Lizenz erfordert. |
Für den Zugriff auf die API stehen Nutzer- und System-Token zur Verfügung. Nutzer-Token haben jeweils nur begrenzten Datenzugriff auf die Daten des Benutzers, System-Token haben Zugriff auf alle Informationen in Ihrer Instanz.
Was ist die Fleet API?
Die Fleet API bietet die Möglichkeit, CRM-Kontakte, Portal User und Identifikationsmedien zu erstellen. Flottenkunden können auf Basis dieser API eigene Anmeldeformulare für ihre individuellen Flotten erstellen. Die Flottenfahrer können sich dann mit diesem Benutzer in der jeweiligen Flotten-APP registrieren und bekommen sofort den richtigen Vertrag zugewiesen. Die API ist mit einem Token gesichert, der auf der Einstellungsseite in Ihrer be.ENERGISED-Instanz ausgelesen werden kann. Der Token muss bei jeder Anfrage als Header x-api-token übergeben werden.
Voraussetzungen, um die Fleet API zu nutzen
- Sie haben ein API-Token im be.ENERGISED Backend erstellt
- Sie haben in be.ENERGISED unter Benutzerverwaltung/Unternehmen/Unternehmensliste ein Unternehmen konfiguriert (Flottenkunde)
- Sie haben einen Rechnungskontakt hinterlegt
- Sie haben einen Tarif konfiguriert
Endpunkte
Die Fleet API bietet zwei Endpunkte: einen um dem Fahrer Zugang zum Erstellen von CRM-Kontakt, Portal User und Identifikationsmedium zu gewähren (Register Endpoint), und einen für die Aktivierung von Portal User und Identifikationsmedium (Confirm Endpoint).
Register Endpoint
Der Register Endpoint erstellt einen CRM-Kontakt, einen Portal User und ein Identifikationsmedium. Der Endpunkt akzeptiert die folgenden Parameter:
Request Parameter
Parameter | Erforderlich | Beschreibung |
---|---|---|
company_id | Ja | einzigartige company ID |
contact | Ja | contact object mit allen erforderlichen Feldern sowie den optionalen Feldern |
user | Ja | user object mit allen erforderlichen Feldern sowie den optionalen Feldern |
card | Ja | card object mit allen erforderlichen Feldern sowie den optionalen Feldern |
Contact Object Parameter
Parameter | Erforderlich | Beschreibung |
---|---|---|
name | Ja | Name des Kontaktes |
first_name | Nein | Vorname des Kontaktes |
gender | Nein | Geschlecht des Kontaktes, 0 = Firma, 1 = männlich, 2 = weiblich |
street | Nein | Straße des Kontaktes |
zip | Nein | Postleitzahl des Kontaktes |
city | Nein | Stadt des Kontaktes |
country | Nein | Zweistelliger Ländercode des Kontakts |
Nein | E-Mail des Kontaktes | |
phone | Nein | Telefonnummer des Kontaktes |
customer_number | Nein | Kundennummer des Kontaktes |
comment | Nein | Kommentar des Kontaktes |
User Object Parameter
Parameter | Erforderlich | Beschreibung |
---|---|---|
Ja | E-Mail des Portal User Accounts | |
password | Ja | Passwort des Portal User Accounts |
account_locale | Nein | Account Standort, z.B. de_DE |
Card Object Parameter
Parameter | Erforderlich | Beschreibung |
---|---|---|
card_no | Ja | Kartennummer |
rate_id | Ja | UUID für den in be.ENERGISED angezeigten Tarif im Tarifmanagement |
billing_contact_id | Ja | Eindeutige Kennung des Rechnungskontaktes |
label | Nein | Kartenbezeichnung |
customer_reference | Nein | Kunden Referenz |
comment | Nein | Kommentar |
emp | Nein | EMP (z. B. AT-HTB), das der Karte zugewiesen wird |
Sample Request
curl --location --request POST 'https://yourinstancename.beenergised.cloud/api/fleet/v1/register' \ --header 'x-api-token: your_token' \ --header 'Content-Type: application/json' \ --data-raw '{ "company_id": "Company UUID", "contact": { "name": "Name", "gender": "Gender", "city": "City", "customer_number": "Customer Number", "comment": "Comment" }, "user": { "email": "Email", "password": "Password", "locale": "Locale" }, "card": { "card_no": "Card Number", "rate_id": "Rate UUID", "billing_contact_id": "Billing Contact UUID" } }'
Sample Response
{ "status": "success", "data": { "contact_id": "created_contact_id", "user_id": "created_user_id", "card_id": "created_card_id" } }
Confirm Endpoint
Der Confirm Endpoint aktiviert den Portal User und das Identifikationsmedium. Der Endpunkt akzeptiert die folgenden Parameter:
Request Parameter
Parameter | Erforderlich | Beschreibung |
---|---|---|
card_id | Ja | Eindeutige Kartenkennung |
user_id | Ja | Eindeutige Benutzerkennung |
Sample Request
curl --location --request PUT 'https://yourinstancename.beenergised.cloud/api/fleet/v1/confirm' \ --header 'x-api-token: your_token' \ --header 'Content-Type: application/json' \ --data-raw '{ "user_id": user_id_to_activate "card_id": card_id_to_activate, }'
Sample Response
{ "status": "success", "data": { "user_id": "activated_user_id", "card_id": "activated_card_id" } }
Version: 2022-09-15 15:58:39 UTC