REST

This documentation provides an overview of the available REST API endpoints for integration with residential plannings in Reonic. All endpoints require an API key that can be generated in the settings under Settings > Integrations.

Authentication

All API requests must include a valid API key in the header:

X-Authorization: <API_KEY>

Endpoints

Get Offers

Retrieves information about offers and requests.

• HTTP Request:

  • Method: GET
  • Endpoint: /rest/v2/clients/{clientId}/h360/offers
  • Query Parameters:
    • page (integer, optional): Specifies the page number for paginated results. Starts at 0.
  • Headers:

    {
      "accept": "application/json",
      "x-Authorization": "Basic <Base64-encoded credentials>"
    }

• HTTP Response:

  • Status: 200 OK

  • Body:

    {
      "results": [
        {
          "id": "xxxxxxxx",
          "status": "Pending Feedback",
          "archived": false,
          "offerArchived": false,
          "requestArchived": false,
          "customer": {
            "id": "xxxxxxxx"
          },
          "kfWTotalConfirmationId": null,
          "kfWRequestConfirmationId": null,
          "signaturePlannedUntil": null,
          "leadSource": "",
          "lat": "xxxxxxxx",
          "lng": "xxxxxxxx",
          "notes": [
            {
              "message": "Offer signed and synchronized",
              "createdAt": "2024-10-29T13:28:29Z",
              "createdById": null
            }
          ],
          "demand": {
            "annualEnergyDemandWh": 4500000,
            "energyPrice": 0.00039,
            "energyPriceIncrease": 0.03
          },
          "options": [
            {
              "id": "xxxxxxxx",
              "solarPlanned": {
                "totalSizeWp": 440,
                "totalNumberOfModules": 1,
                "components": [
                  {
                    "id": "xxxxxxxx",
                    "componentId": "xxxxxxxx",
                    "quantity": 23,
                    "netPrice": 16445,
                    "vatPerc": 0,
                    "vat": 0,
                    "name": "Solar Module",
                    "brand": "Generic",
                    "type": "Module"
                  }
                ]
              },
              "sesPlanned": {
                "storageSize": 5000,
                "components": [
                  {
                    "id": "xxxxxxxx",
                    "componentId": "xxxxxxxx",
                    "quantity": 1,
                    "netPrice": 5375,
                    "vatPerc": 0.19,
                    "vat": 1021.25,
                    "name": "Battery Storage",
                    "brand": "Generic",
                    "type": "BatteryStorage"
                  }
                ]
              },
              "wallboxPlanned": {
                "components": [
                  {
                    "id": "xxxxxxxx",
                    "componentId": "xxxxxxxx",
                    "quantity": 1,
                    "netPrice": 980,
                    "vatPerc": 0,
                    "vat": 0,
                    "name": "Wallbox",
                    "brand": "Generic",
                    "type": "Wallbox"
                  }
                ]
              },
              "heatpumpPlanned": {
                "components": []
              },
              "additionalPlanned": {
                "components": []
              }
            }
          ],
          "totalPlannedPrice": 25356,
          "assignedToId": null,
          "assignedToUsers": [],
          "lostReason": null,
          "lostAt": null,
          "solarPackage": {
            "name": "Starter Solar Package"
          },
          "sesPackage": {
            "name": "Starter Energy Storage Package"
          },
          "heatpumpPackage": {},
          "wallboxPackage": {
            "name": "Smart Wallbox Package"
          },
          "offerCreatedById": "xxxxxxxx",
          "offerCreatedAt": "2024-10-29T13:07:13Z",
          "offerLastEditedById": "xxxxxxxx",
          "offerLastEditedAt": "2024-10-29T13:23:43Z",
          "existingSolar": {
            "solarExistingAngle": null,
            "solarExistingSize": null,
            "solarExistingOrientation": null
          },
          "currentSignature": {
            "signatureRequestCreatedAt": "2024-10-29T13:23:42Z",
            "state": "Signed",
            "expiryAt": "2024-11-12T13:23:42Z",
            "signedAt": "2024-10-29T13:24:21Z",
            "signedPdfUrl": "https://private-static.reonic.de/.../signed.pdf",
            "signedOptionId": "xxxxxxxx"
          }
        }
      ],
      "hasNextPage": false
    }

• Description:

  This endpoint retrieves all offers associated with a specific client. Each offer includes details such as customer ID, location, energy demand, configuration options, and signature status. Results are paginated. The field 'hasNextPage' indicates whether there is offers left to be fetched.

• Request Parameters:

  • clientId (path, required): The unique identifier of the client.

• Headers:

  • accept (string, required): Specifies the response format. Must be application/json.
  • x-Authorization (string, required): Basic authorization header containing Base64-encoded credentials.

• Error Codes:

  • 401 Unauthorized: Invalid or missing authorization credentials.
  • 404 Not Found: Client ID not found or invalid.
  • 500 Internal Server Error: Unexpected error occurred while processing the request.

Get Offer

Retrieves information about a specific offer.

• HTTP Request:

  • Method: GET
  • Endpoint: /rest/v2/clients/{clientId}/h360/offers/{id}
  • Headers:

    {
      "accept": "application/json",
      "x-Authorization": "Basic <Base64-encoded credentials>"
    }

• HTTP Response:

  • Status: 200 OK

  • Body:

    {
      "id": "xxxxxxxx",
      "status": "Pending Feedback",
      "archived": false,
      "offerArchived": false,
      "requestArchived": false,
      "customer": {
        "id": "xxxxxxxx"
      },
      "kfWTotalConfirmationId": null,
      "kfWRequestConfirmationId": null,
      "signaturePlannedUntil": null,
      "leadSource": "",
      "lat": "xxxxxxxx",
      "lng": "xxxxxxxx",
      "notes": [
        {
          "message": "Offer signed and synchronized",
          "createdAt": "2024-10-29T13:28:29Z",
          "createdById": null
        }
      ],
      "demand": {
        "annualEnergyDemandWh": 4500000,
        "energyPrice": 0.00039,
        "energyPriceIncrease": 0.03
      },
      "options": [
        {
          "id": "xxxxxxxx",
          "solarPlanned": {
            "totalSizeWp": 440,
            "totalNumberOfModules": 1,
            "components": [
              {
                "id": "xxxxxxxx",
                "componentId": "xxxxxxxx",
                "quantity": 23,
                "netPrice": 16445,
                "vatPerc": 0,
                "vat": 0,
                "name": "Solar Module",
                "brand": "Generic",
                "type": "Module"
              }
            ]
          },
          "sesPlanned": {
            "storageSize": 5000,
            "components": [
              {
                "id": "xxxxxxxx",
                "componentId": "xxxxxxxx",
                "quantity": 1,
                "netPrice": 5375,
                "vatPerc": 0.19,
                "vat": 1021.25,
                "name": "Battery Storage",
                "brand": "Generic",
                "type": "BatteryStorage"
              }
            ]
          },
          "wallboxPlanned": {
            "components": [
              {
                "id": "xxxxxxxx",
                "componentId": "xxxxxxxx",
                "quantity": 1,
                "netPrice": 980,
                "vatPerc": 0,
                "vat": 0,
                "name": "Wallbox",
                "brand": "Generic",
                "type": "Wallbox"
              }
            ]
          },
          "heatpumpPlanned": {
            "components": []
          },
          "additionalPlanned": {
            "components": []
          }
        }
      ],
      "totalPlannedPrice": 25356,
      "assignedToId": null,
      "assignedToUsers": [],
      "lostReason": null,
      "lostAt": null,
      "solarPackage": {
        "name": "Starter Solar Package"
      },
      "sesPackage": {
        "name": "Starter Energy Storage Package"
      },
      "heatpumpPackage": {},
      "wallboxPackage": {
        "name": "Smart Wallbox Package"
      },
      "offerCreatedById": "xxxxxxxx",
      "offerCreatedAt": "2024-10-29T13:07:13Z",
      "offerLastEditedById": "xxxxxxxx",
      "offerLastEditedAt": "2024-10-29T13:23:43Z",
      "existingSolar": {
        "solarExistingAngle": null,
        "solarExistingSize": null,
        "solarExistingOrientation": null
      },
      "currentSignature": {
        "signatureRequestCreatedAt": "2024-10-29T13:23:42Z",
        "state": "Signed",
        "expiryAt": "2024-11-12T13:23:42Z",
        "signedAt": "2024-10-29T13:24:21Z",
        "signedPdfUrl": "https://private-static.reonic.de/.../signed.pdf",
        "signedOptionId": "xxxxxxxx"
      }
    }

• Description:

  This endpoint retrieves detailed information about a specific offer. The response includes all offer details such as customer ID, location, energy demand, configuration options, and signature status.

• Request Parameters:

  • clientId (path, required): The unique identifier of the client.
  • id (path, required): The unique identifier of the offer.

• Headers:

  • accept (string, required): Specifies the response format. Must be application/json.
  • x-Authorization (string, required): Basic authorization header containing Base64-encoded credentials.

• Error Codes:

  • 401 Unauthorized: Invalid or missing authorization credentials.
  • 404 Not Found: Client ID or offer ID not found or invalid.
  • 500 Internal Server Error: Unexpected error occurred while processing the request.

Add Note to Offer

Adds a note to a specific offer.

• HTTP Request:

  • Method: POST
  • Endpoint: /rest/v2/clients/{clientId}/h360/offers/notes
  • Headers:

    {
      "accept": "application/json",
      "content-type": "application/json",
      "x-Authorization": "Basic <Base64-encoded credentials>"
    }
  • Body:

    {
      "offerId": "123e4567-e89b-12d3-a456-426614174000",
      "text": "Customer requested additional information about solar panel efficiency"
    }

• HTTP Response:

  • Status: 200
  • Body:

    {
      "id": "xxxxxxxx",
      "text": "Customer requested additional information about solar panel efficiency",
    }

• Description:

  This endpoint adds a new note to a specific offer. The note will be associated with the offer and visible in the offer's history.

• Request Parameters:

  • clientId (path, required): The unique identifier of the client.
  • offerId (body, required): The UUID of the offer to add the note to.
  • text (body, required): The content of the note.

• Headers:

  • accept (string, required): Specifies the response format. Must be application/json.
  • content-type (string, required): Specifies the request body format. Must be application/json.
  • x-Authorization (string, required): Basic authorization header containing Base64-encoded credentials.

• Error Codes:

  • 400 Bad Request: Invalid request body or offer ID format.
  • 401 Unauthorized: Invalid or missing authorization credentials.
  • 404 Not Found: Client ID or offer ID not found or invalid.
  • 500 Internal Server Error: Unexpected error occurred while processing the request.

Create Request

Creates a new request (lead) in the system.

• HTTP Request:

  • Method: POST
  • Endpoint: /integrations/{clientId}/h360/request/create
  • Headers:

    {
      "accept": "application/json",
      "content-type": "application/json",
      "x-Authorization": "Basic <Base64-encoded credentials>"
    }
  • Body:

    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+49123456789",
      "country": "Germany",
      "postcode": "10115",
      "city": "Berlin",
      "street": "Hauptstraße",
      "streetNumber": "123",
      "message": "Interested in solar installation",
      "note": "Customer prefers morning call",
      "leadSourceId": "source123",
      "leadSourceName": "Website Contact Form",
      "totalDemandkWh": 4500,
      "energyPriceCtPerKwh": 35,
      "latLng": {
        "lat": 52.520008,
        "lng": 13.404954
      },
      "addressToGeocode": {
        "country": "Germany",
        "postcode": "10115",
        "city": "Berlin",
        "street": "Hauptstraße",
        "streetNumber": "123"
      }
    }

• HTTP Response:

  • Status: 200 OK

• Description:

  This endpoint creates a new request (lead) in the system. The request can include personal information, contact details, address and energy consumption data. Either latLng or addressToGeocode must be provided, but not both at the same time.

• Request Parameters:

  • clientId (path, required): The unique identifier of the client.
  • Body Parameters:
    • firstName (string, required): First name of the contact (1-100 characters)
    • lastName (string, required): Last name of the contact (1-100 characters)
    • email (string, optional): Email address of the contact
    • phone (string, optional): Phone number of the contact (1-100 characters)
    • country (string, optional): Country of the address
    • postcode (string, optional): Postal code of the address
    • city (string, optional): City of the address
    • street (string, optional): Street name of the address
    • streetNumber (string, optional): Street number of the address
    • message (string, optional): Message from the contact (max 10,000 characters)
    • note (string, optional): Internal note about the contact (max 10,000 characters)
    • leadSourceId (string, optional): Identifier of the lead source
    • leadSourceName (string, optional): Name of the lead source
    • totalDemandkWh (number, optional): Total energy demand in kWh (0-200,000, default: 4000)
    • energyPriceCtPerKwh (number, optional): Energy price in cents per kWh (0-500, default: 30)
    • latLng (object, optional): Geographic coordinates. Must be provided if addressToGeocode is not set.
      • lat (number): Latitude
      • lng (number): Longitude
    • addressToGeocode (object, optional): Address for geocoding. Must be provided if latLng is not set.
      • country (string, optional): Country
      • postcode (string, optional): Postal code
      • city (string, optional): City
      • street (string, optional): Street name
      • streetNumber (string, optional): Street number

• Headers:

  • accept (string, required): Specifies the response format. Must be application/json.
  • content-type (string, required): Specifies the request body format. Must be application/json.
  • x-Authorization (string, required): Basic authorization header containing Base64-encoded credentials.

• Error Codes:

  • 400 Bad Request: Invalid request body or validation error.
  • 401 Unauthorized: Invalid or missing authorization credentials.
  • 404 Not Found: Client ID not found or invalid.
  • 500 Internal Server Error: Unexpected error occurred while processing the request.

Get Contact/Customer

Retrieves information about a single contact/customer.

• HTTP Request:

  • Method: GET
  • Endpoint: /rest/v2/clients/{clientId}/contacts/{contactId}
  • Headers:

    {
      "accept": "application/json",
      "x-Authorization": "Basic <Base64-encoded credentials>"
    }

• HTTP Response:

  • Status: 200 OK
  • Body:

    {
      "id": "0c057402-4707-42e5-8881-77472cedf9b7",
      "firstName": "Kajo",
      "lastName": "Zapier",
      "email": "kajo.deffner@reonic.de",
      "emailSecondary": null,
      "telephone": "34234524353453",
      "mobilePhone": null,
      "street": "Rosenstraße",
      "number": "15",
      "city": "Berlin",
      "postcode": "12487",
      "createdAt": "2025-01-14T14:02:15.207Z"
    }

• Description:

  This endpoint retrieves detailed information about a specific contact associated with a client. The response includes personal details, address information, and metadata about the contact creation.

• Request Parameters:

  • clientId (path, required): The unique identifier of the client.
  • contactId (path, required): The unique identifier of the contact.

• Headers:

  • accept (string, required): Specifies the response format. Must be application/json.
  • x-Authorization (string, required): Basic authorization header containing Base64-encoded credentials.

• Error Codes:

  • 401 Unauthorized: Invalid or missing authorization credentials.
  • 404 Not Found: Client or contact ID not found or invalid.
  • 500 Internal Server Error: Unexpected error occurred while processing the request.

Get Users

Retrieves information about all users associated with a client.

• HTTP Request:

  • Method: GET
  • Endpoint: /rest/v2/clients/{clientId}/users
  • Headers:

    {
      "accept": "application/json",
      "x-Authorization": "Basic <Base64-encoded credentials>"
    }

• HTTP Response:

  • Status: 200 OK
  • Body:

    {
      "results": [
        {
          "id": "xxxxxxxx",
          "email": "user@example.com",
          "fullName": "John Doe",
          "role": "ADMIN"
        },
        {
          "id": "yyyyyyyy",
          "fullName": "Jane Smith",
          "role": "USER"
        }
      ]
    }

• Description:

  This endpoint retrieves a list of all users associated with a specific client. Each user includes their ID, email (if available), full name, and role.

• Request Parameters:

  • clientId (path, required): The unique identifier of the client.

• Headers:

  • accept (string, required): Specifies the response format. Must be application/json.
  • x-Authorization (string, required): Basic authorization header containing Base64-encoded credentials.

• Error Codes:

  • 401 Unauthorized: Invalid or missing authorization credentials.
  • 404 Not Found: Client ID not found or invalid.
  • 500 Internal Server Error: Unexpected error occurred while processing the request.

Get User

Retrieves information about a specific user.

• HTTP Request:

  • Method: GET
  • Endpoint: /rest/v2/clients/{clientId}/users/{id}
  • Headers:

    {
      "accept": "application/json",
      "x-Authorization": "Basic <Base64-encoded credentials>"
    }

• HTTP Response:

  • Status: 200 OK
  • Body:

    {
      "id": "xxxxxxxx",
      "email": "user@example.com",
      "fullName": "John Doe",
      "role": "ADMIN"
    }

• Description:

  This endpoint retrieves detailed information about a specific user associated with a client. The response includes the user's ID, email (if available), full name, and role.

• Request Parameters:

  • clientId (path, required): The unique identifier of the client.
  • id (path, required): The unique identifier of the user.

• Headers:

  • accept (string, required): Specifies the response format. Must be application/json.
  • x-Authorization (string, required): Basic authorization header containing Base64-encoded credentials.

• Error Codes:

  • 401 Unauthorized: Invalid or missing authorization credentials.
  • 404 Not Found: Client ID or user ID not found or invalid.
  • 500 Internal Server Error: Unexpected error occurred while processing the request.