API Usage Guidelines

1. Introduction

The Zaptec API allows developers to interact with Zaptec charging stations and installations, enabling functionalities such as monitoring charger state, retrieving installation and charger data and dynamically adjusting charging parameters, among others. This guideline outlines the recommended practices for utilising the API effectively.

2. Authentication

Access to the Zaptec API is secured using OAuth 2.0. To authenticate, you typically obtain a bearer token by sending a POST request to the token endpoint https://api.zaptec.com/oauth/token with the grant_type set to password, providing your Zaptec portal username and password.

The obtained access token must be included in the Authorization header of all subsequent API requests in the format Authorization: Bearer {access_token}.

Ensure you handle tokens securely and refresh them as needed according to the token's expiry time. Read more on Authentication

3. Making Requests

The Zaptec API is REST-based and utilises standard HTTP methods (GET, POST, PUT, DELETE).

• Base URL: The API base URL is https://api.zaptec.com/.
• Endpoints: Key endpoints include:
  • /api/installation: Retrieve a list of installations accessible to your account.
  • /api/chargers: Retrieve a list of chargers accessible to your account.
  • /api/installation/{id}/hierarchy: Retrieve the hierarchy of chargers within a specific installation.
  • /api/installation/{id}/update: Update settings for a specific installation (e.g., adjusting available current). A complete list of endpoints can be found in API reference
• Data Format: Requests and responses typically use JSON format. Ensure your application correctly formats requests and parses responses.

4. Handling Responses

• Status Codes: Pay attention to HTTP status codes to understand the outcome of your requests. Common codes include:
  • 200 OK: The request was successful.
  • 201 Created: A resource was successfully created.
  • 204 No Content: The request was successful, but there is no response body.
  • 400 Bad Request: The request was malformed.
  • 401 Unauthorized: Authentication failed or is required.
  • 403 Forbidden: You do not have permission to access the resource.
  • 404 Not Found: The requested resource was not found.
  • 429 Too Many Requests: You have exceeded the rate limit.
  • 500 Internal Server Error: An error occurred on the API server.
• Error Handling: Implement robust error handling in your application to ensure stability and a smooth user experience. Always interpret HTTP status codes correctly and, when available, parse the response body for more detailed error information. This enables your application to respond appropriately to various types of issues.

5. Real-Time Updates and Efficiency

• Avoid Aggressive Polling: Do not use the API for aggressive polling of charger or installation states.
• Utilise Message Subscriptions: For near real-time updates on charger states and other events, we strongly advice utilising the Zaptec Service Bus message subscriptions. This provides a push-based mechanism for receiving updates, significantly reducing the need for frequent API polling. Connection details for message subscriptions can be retrieved via the API. Remember that subscriptions may be automatically removed after a period of inactivity. If you encounter scenarios where Service Bus messages do not fully meet your needs, please provide feedback to Zaptec and us help improve the service. Implementing logic to better correlate session data from Service Bus events can also help reduce reliance on direct API calls. Read more on Message subscription
• Efficient Data Fetching: When fetching lists of installations , chargers or session data, be mindful of pagination. The API has limits on page size, a maximum of 100 records per page is enforced. Implement pagination correctly to retrieve large datasets.
• Cache Data Locally: For data that doesn't change often, such as charger details like MaxCurrent, Phases and Voltage, consider caching this information locally in your application. Refresh this cached data periodically rather than fetching it with every API call. If you need charger connection details after a reboot or deployment, stagger or batch these requests instead of requesting all at once.

❗

6. Rate Limits

Zaptec enforces rate limits to ensure the stability and performance of the API for all users. A peak rate limit of 10 requests per second per account is in place. Design your application to respect these limits. If hitting the rate limit is a concern, implement a request queue to manage outgoing API calls. For handling rate-limited responses (e.g., 429 Too Many Requests), implement retry logic with exponential backoff to avoid overwhelming the API further. Prioritise critical API calls over less time-sensitive ones to ensure essential operations are completed even during periods of higher usage.

7. Permissions

The level of access and control you have via the API depends on the permissions associated with your Zaptec account on specific installations and chargers. Ensure your account has the necessary permissions for the operations you intend to perform. Refer to the Zaptec documentation for details on different permission types.

8. Dynamic Load Balancing

When implementing dynamic load balancing or adjusting charging current, it is recommended to make changes at the installation level using endpoints like /api/installation/{id}/update. This allows the Zaptec load balancer to effectively distribute the available power among the chargers within the installation. Zaptec recommends updating installation current settings no more than once every 15 minutes to ensure a stable charging experience. Read more on Dynamic Load balancing

9. Upcoming Changes

Stay informed about upcoming API changes announced by Zaptec. You can monitor for service status at any time using the Zaptec System status page. These changes may include updates to error handling, pagination or available data. Adjust your integration accordingly to maintain compatibility.

10. Support

If you encounter issues or have questions regarding the Zaptec API, refer to the official Zaptec help center and documentation. If you require further assistance, contact Zaptec support through Zaptec help center.

By following these guidelines, you can build robust, efficient and reliable integrations with the Zaptec API.