Zum Hauptinhalt springen

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​

Retrieves detailed information about a specific contact associated with a client.

  • HTTP Request:

    • Method: GET
    • Endpoint: /rest/v2/clients/{clientId}/contacts/{id}
    • Headers:
      {
        "accept": "application/json",
        "x-Authorization": "Basic <Base64-encoded credentials>"
      }

  • HTTP Response:

    • Status: 200 OK
    • Body:
      {
        "id": "contact-1",
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "jane.doe@example.com",
        "emailSecondary": null,
        "telephone": "+49-123-4567890",
        "mobilePhone": null,
        "street": "Musterstraße",
        "number": "42",
        "city": "Berlin",
        "postcode": "10115",
        "utmSource": null,
        "utmCampaign": null,
        "utmMedium": null,
        "utmTerm": null,
        "utmContent": null,
        "createdAt": "2024-12-01T10:15:30Z",
        "marketingConsent": true,
        "marketingConsentText": "Agreed to receive marketing emails",
        "marketingConsentDataprotectionLink": "https://example.com/privacy"
      }

  • Description:

    This endpoint retrieves detailed contact information for a given contact ID and client. The returned data includes personal details, address, marketing preferences, and UTM tracking information.

  • Request Parameters:

    • clientId (path, required): The unique identifier of the client.
    • id (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 ID or contact ID not found or invalid.
    • 500 Internal Server Error: Unexpected error occurred while processing the request.

    Get Contacts​

Retrieves a list of all contacts associated with a specific client.

  • HTTP Request:

    • Method: GET
    • Endpoint: /rest/v2/clients/{clientId}/contacts
    • Headers:
      {
        "accept": "application/json",
        "x-Authorization": "Basic <Base64-encoded credentials>"
      }

  • HTTP Response:

    • Status: 200 OK
    • Body:
      [
        {
          "id": "contact-1",
          "firstName": "Jane",
          "lastName": "Doe",
          "email": "jane.doe@example.com",
          "emailSecondary": null,
          "telephone": "+49-123-4567890",
          "mobilePhone": null,
          "street": "Musterstraße",
          "number": "42",
          "city": "Berlin",
          "postcode": "10115",
          "utmSource": null,
          "utmCampaign": null,
          "utmMedium": null,
          "utmTerm": null,
          "utmContent": null,
          "createdAt": "2024-12-01T10:15:30Z",
          "marketingConsent": true,
          "marketingConsentText": "Agreed to receive marketing emails",
          "marketingConsentDataprotectionLink": "https://example.com/privacy"
        }
      ]

  • Description:

    This endpoint retrieves all contacts associated with a specific client. The response includes detailed contact information, address, UTM tracking data, and marketing consent details.

  • 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 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.

Get Tags​

Retrieves all tags associated with a client, or a subset of tags if specific tag IDs are provided as query parameters.

  • HTTP Request:

    • Method: GET
    • Endpoint: /rest/v2/clients/{clientId}/tags
    • Query Parameters:
      • ids (array of strings, optional): A list of tag IDs to filter the response.
    • Headers:
      {
        "accept": "application/json",
        "x-Authorization": "Basic <Base64-encoded credentials>"
      }

  • HTTP Response:

    • Status: 200 OK
    • Body:
      [
        {
          "id": "tag-1",
          "name": "name-1"
        },
        {
          "id": "tag-2",
          "name": "name-2"
        }
      ]

  • Description:

    This endpoint retrieves a list of tags associated with the specified client. If ids are provided, only the tags matching those IDs will be returned.

  • Request Parameters:

    • clientId (path, required): The unique identifier of the client.
    • ids (query, optional): A list of tag IDs to filter the response.

  • 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:

    • 400 Bad Request: Invalid tag IDs provided.
    • 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 Teams​

Retrieves all teams associated with a client, or a subset of teams if specific team IDs are provided as query parameters.

  • HTTP Request:

    • Method: GET
    • Endpoint: /rest/v2/clients/{clientId}/teams
    • Query Parameters:
      • assignedTeamIds (array of strings, optional): A list of team IDs to filter the response.
    • Headers:
      {
        "accept": "application/json",
        "x-Authorization": "Basic <Base64-encoded credentials>"
      }

  • HTTP Response:

    • Status: 200 OK
    • Body:
      [
        {
          "id": "team-1",
          "name": "Installation Team",
          "users": ["user-1", "user-2"],
          "teamLeadId": "user-1",
          "childTeamIds": ["team-2"],
          "parentTeamId": null
        },
        {
          "id": "team-2",
          "name": "Electrical Subteam",
          "users": ["user-3"],
          "teamLeadId": "user-3",
          "childTeamIds": [],
          "parentTeamId": "team-1"
        }
      ]

  • Description:

    This endpoint retrieves a list of teams for a given client. You can optionally specify assignedTeamIds as a query parameter to retrieve only certain teams.

  • Request Parameters:

    • clientId (path, required): The unique identifier of the client.
    • assignedTeamIds (query, optional): A list of team IDs to filter the response.

  • 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:

    • 400 Bad Request: Invalid team IDs provided.
    • 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.