Implementation Patterns

This guide covers common use cases and implementation patterns for the entervo infinite API, focusing on practical scenarios for integrating with the parking management system. It describes example patterns (based on the Customer & Contract API) how to synchronize data, e.g. initial load, incremental updates, batch updates.

Minimal Use Case for Data Feed (Sync) from 3rd Party System

The synchronization of consumers (who are parking in a car park) is based on CRUD operations for a single consumer or a list of consumers using solely the Consumer API.

tip

If a POST method is called and the consumer is found in the parking system, the existing record is updated with the new data.

Scenario: 3rd Party System as the Source of Truth

When your 3rd party system is the leading system, and a minimal data set is synced to the parking management system:

• Use externalReference for synchronization with 3rd party systems
• Note: If not all fields are populated, some parking management functions may not be available

Scenario: Syncing for a Single Customer (Company)

When you're only managing one customer entity:

1. Use pre-configured values from the Parking management system:

   • Pre-configured Tenant Name
   • Pre-configured CustomerBusinessID
   • Pre-configured ContractBusinessID

2. For each operation, include these pre-configured values in your API calls

Common Operations

Initial Load (of Consumers)

Create Consumers for the given Customer (Company):

• Use CustomerBusinessID plus externalReference (to be unique for each consumer)
• Recommendation: Use this operation at very low frequency

POST https://pm.preprod.parking.scheidt-bachmann.net/customers-contracts/v2/yourproject/customers/{customerBusinessID}/consumers/regular/aggregates

{
  "firstName": "First",
  "lastName": "Last",
  "email": "test@mail.de",
  "externalReference": "EMP12345", // Your system's unique identifier
  "costCenter": "Cost center",
  "mediums": [
    {
      "type": "LICENSEPLATE",
      "value": "MM5478",
      "encoding": "HEX",
      "licencePlateRegion": {
        "code": "M",
        "country": "DEU"
      }
    }
  ],
  "contract": {
    "businessId": "A2024XW3pYsa2f", // Pre-configured ContractBusinessID
    "products": [
      "PP000053" // Product ID
    ]
  }
}

Incremental Update (of Consumers)

Update Consumers for the given Customer (Company):

• Use CustomerBusinessID plus externalReference (to be unique for each consumer)
• This is the most common operation for ongoing synchronization

PUT https://pm.preprod.parking.scheidt-bachmann.net/customers-contracts/v2/yourproject/customers/{customerBusinessID}/consumers/regular/aggregates/{consumerBusinessID}

{
  "businessId": "N20243gOoi3ef",
  "firstName": "First",
  "lastName": "Last",
  "email": "test@mail.de",
  "externalReference": "EMP12345",
  "costCenter": "Cost center",
  "mediums": [
    {
      "businessId": "MPliczWk",
      "revision": 0,
      "type": "LICENSEPLATE",
      "value": "MM54785",
      "encoding": "HEX",
      "licencePlateRegion": {
        "code": "M",
        "country": "DEU"
      }
    }
  ],
  "contract": {
    "businessId": "A2024XW3pYsa2f",
    "products": [
      "PP000053"
    ]
  },
  "revision": 0
}

Search for a Consumer by externalReference

Search by External reference and/or email (in all customers):

POST https://pm.preprod.parking.scheidt-bachmann.net/customers-contracts/v2/yourproject/consumers

{
  "page": 0,
  "size": 100,
  "sortDirection": "DESC",
  "and": {
    "consumer": {
      "consumerEmail": null,
      "regular": {
        "externalReference": "EMP12345"
      }
    }
  }
}

Delete Consumer for the given Customer (Company)

Remove a consumer from the system:

DELETE https://pm.preprod.parking.scheidt-bachmann.net/customers-contracts/v2/yourproject/customers/{customerBusinessID}/consumers/regular/aggregates/{consumerBusinessID}

Implementation Patterns

Pattern 1: Full Synchronization

This pattern is suitable for initial setup or periodic full refreshes:

1. Retrieve all employee records from your system
2. For each employee:
   • Search for existing consumer by externalReference
   • If found, update the consumer
   • If not found, create a new consumer
3. Optionally, identify and remove consumers that no longer exist in your system

Pattern 2: Event-Driven Synchronization

This pattern is suitable for real-time updates:

1. Set up event listeners in your system for employee changes (create, update, delete)
2. When an event occurs:
   • For creation: Create a new consumer
   • For updates: Update the existing consumer
   • For deletion: Delete the consumer

Pattern 3: Batch Processing

This pattern is suitable for systems with many changes:

1. Collect employee changes over a period (e.g., hourly, daily)
2. Process changes in batches
3. Log and report any synchronization issues

Best Practices

1. Use Idempotent Operations: Design your integration to be idempotent, meaning the same operation can be performed multiple times without changing the result
2. Implement Error Handling: Handle API errors gracefully and implement retry logic for transient failures
3. Monitor Synchronization: Set up monitoring to track successful and failed synchronizations
4. Validate Data: Validate data before sending it to the API to ensure it meets the requirements
5. Use Pagination: When retrieving large sets of data, use pagination to avoid timeouts

By following these patterns and best practices, you can create a robust integration with the entervo infinite API that efficiently synchronizes data between your system and the parking management system.