Getting Started with Emerit Services API

Welcome to the Emerit API documentation. Our API allows third-party applications to connect with our GraphQL interface, providing comprehensive access to all Emerit services. Whether you're looking to integrate single features or leverage the full suite of services we offer, this guide will help you get started.

Understanding GraphQL

GraphQL is a query language for APIs and a runtime for executing those queries by using a type system you define for your data. Unlike REST APIs, GraphQL APIs allow clients to request only the data they need, making it an efficient choice for web and mobile applications. Queries in GraphQL are sent as strings and can be made for specific data, which means less loading time and a more seamless integration into your application.

Setting Up Your Environment

Before you can start using the Emerit API, you need to set up your development environment. This involves getting an API key for authentication and setting up your application to make requests to our GraphQL endpoint.

Getting Your API Key

1. Navigate to https://app.emerit-services.com.
2. Log in to access to My Company page : app.emerit-services.com/my-company
3. Navigate to the API keys section and display your API key.

Authenticating Your Requests

All requests to the Emerit API must be authenticated using your API key. Include your API key in the header of your requests like so:

apiKey: YOUR_API_KEY

Making Your First GraphQL Query

Here's a simple example to fetch the integrator's information, you can add more fields to the query to get more information about the integrator, its users and end customers.

 query GET_MY_INTEGRATOR_INFOS {
    getMyIntegratorInfos {
      id
      name
      users {
        id
        email
      }
      endCustomers {
        id
        companyName
        sites {
          id
          name
          devices {
            id
            deviceModel {
              uid
            }
            softwareVersion {
              versionNumber
            }
          }
        }
      }
    }
}

To execute this query, send a POST request to https://api.emerit-services.com/graphql with the query in the body, and don't forget to include your ApiKey header.

The response will contain the data you requested in the query. You can then use this data for further processing in your application.

Here an example of a response:

{
    "data": {
        "getMyIntegratorInfos": {
            "id": "110b7167-7f95-499b-b827-996add5297e0",
            "name": "Integrator name",
            "users": [
                {
                    "id": "4f25e02e-ea24-4c73-97eb-576e9bc7eaaf",
                    "email": "test@test.fr"
                },
                {
                    "id": "c0d6d6aa-c8e7-4fac-b04b-0f69c5a14344",
                    "email": "admin@company.com"
                }
            ],
            "distributor": null,
            "endCustomers": [
                {
                    "id": "250b7167-7f95-499b-b827-996add5297e0",
                    "companyName": "Apollo Inc.",
                    "sites": [
                        {
                            "id": "210b7167-7f95-499b-b827-996add5297e0",
                            "name": "Site de Paris",
                            "devices": [
                                {
                                    "id": "514a9257-3195-4799-a5ef-23a79983935a",
                                    "deviceModel": {
                                        "uid": "E-WG100"
                                    },
                                    "softwareVersion": {
                                        "versionNumber": "1.0.0"
                                    }
                                },
                                {
                                    "id": "a3a9a340-bdba-47cf-86a9-b1efd7bc38b1",
                                    "deviceModel": {
                                        "uid": "E-RG655"
                                    },
                                    "softwareVersion": {
                                        "versionNumber": "1.0.0"
                                    }
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}