API v1 → v2 migratie

Doel en scope

Dit document beschrijft de breaking changes tussen:

• API v1 (Swagger/OpenAPI: HeatTransformers Partner API v0.6, server: /api/v1, OpenAPI 3.0.0)
• API v2 (Swagger/OpenAPI: HeatTransformers Partner Suite API v2.0.0, server: /api/v2, OpenAPI 3.1.1)

Het is bedoeld voor partners die al integreren met v1 endpoints en willen migreren naar v2.

De belangrijkste updates op een rij

• Base URL: /api/v1 → /api/v2.
• OpenAPI versie: 3.0.0 → 3.1.1 (Bij gebruik van codegen tooling moet deze OpenAPI 3.1 ondersteunen).
• API keys: API keys van versie 1 zijn niet geldig in versie 2, een nieuwe API key moet worden aangemaakt. Daarnaast kunnen er nu meerdere API keys tegelijk actief zijn.
• Webhooks: Alle webhook routes zijn hernoemd naar Notifications routes onder /notifications/webhook.
• Leads:
  • Lead create endpoints zijn niet meer async: POST /lead en POST /leads returnen nu 200 i.p.v. 202 met een id in de response.
  • Bulk create response is veranderd.
• Logs: GET /logs is niet meer beschikbaar in versie 2.
• Errors: HTTP errors zijn nu gestandaardiseerd in de response body.
• Meer velden, meer routes: In versie 2 hebben we in veel routes meer velden toegevoegd. Deze zijn te bekijken in de API documentatie.

Nieuwe versie van de API

Versie 1 van de API blijft nog beschikbaar maar upgraden wordt aanbevolen. Versie 1 zal op termijn niet meer worden ondersteund en verwijderd worden.

• v1: prefix via server: /api/v1.
• v2: prefix via server: /api/v2

Authenticatie

API keys die zijn aangemaakt in versie 1 kunnen niet meer gebruikt worden in versie 2. Een nieuwe API key moet worden aangemaakt. Dit kan via de nieuwe API key endpoints in de API documentatie of via de interface in de partner suite.

v1

• Mechanisme: API key via header.
• Header: Authorization: [your_api_key].

API keys kunnen worden aangemaakt met de POST /generate-api-key endpoint of via de interface in de oude partner api portal. Maximaal 1 api key kan actief zijn, een nieuwe key invalideert de vorige direct.

v2

• Mechanisme: API key via header.
• Header: X-API-Key: [your_api_key].

API keys kunnen worden aangemaakt met de POST /api-key endpoint of via de interface in de partner suite. Gebruik de andere api routes om api keys te beheren/verwijderen. Je kan meerdere API keys tegelijk actief hebben.

Endpoint mapping

Error handling

v1

v1 gebruikt een error schema:

{
  "message": "Validation Error",
  "errors": ["Email is a required field"]
}

v2

v2 gebruikt een gestandaardiseerde error envelope met:

• defined: boolean
• code: string (bijv. UNAUTHORIZED, FORBIDDEN, INTERNAL_SERVER_ERROR)
• status: number
• message: string
• data: object (optioneel / leeg)

Voorbeeld 401:

{
  "defined": true,
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "Unauthorized",
  "data": {}
}

Migratieadvies:

• Stop met het parsen van errors: string[].
• Gebruik status + code voor programmatic handling.
• Log ook message (menselijk leesbaar).

Webhooks (Notifications)

Webhooks zijn verplaatst naar de Notifications namespace. Hier vallen ook email notificaties onder. Het aanpassen van het pad van deze endpoints is vereist.

Endpoint mapping

Response body

• v1 create response: { message, webhookId }
• v2 create response: { message, id }

Leads

Create lead (POST /lead) - breaking response

v1:

• Response 202:

{ "message": "Lead creation process started" }

v2:

• Response 200:

{
  "message": "...",
  "id": "..."
}

Bulk create leads (POST /leads) - breaking response + limiet

v1:

• Response 202 en een aparte 400 body met per-lead errors.

v2:

• Response 200 en leads bevat een lijst met basisvelden (externalId, firstName, lastName, email).
• Maximaal 100 leads per request.

Logs

• v1: GET /logs
• v2: verwijderd

Logs supporten we in versie 2 niet meer.

Meer velden, meer routes

In versie 2 hebben we in veel routes meer velden toegevoegd. Deze zijn te bekijken in de API documentatie.

Kom je er niet uit?

Neem contact met ons op via it_installation@heattransformers.com.