# Partner-API (https://webmetic.de/docs/partner/partner-api)

Die Partner-API verbindet Ihr eigenes System mit Ihrem [Partnerbereich](https://webmetic.de/docs/partner).

Die Endpunkte liegen wie die übrige [API](https://webmetic.de/docs/api) unter `https://hub.webmetic.de`. Sie stehen auch in der [API-Referenz](https://webmetic.de/docs/api/referenz/partner/create-customer), und dort probieren Sie jeden Endpunkt im Playground aus.

Im Playground brauchen Sie den Schlüssel Ihres Partnerkontos. Die Partner-Endpunkte lehnen den vorausgefüllten [Demo-Schlüssel](https://webmetic.de/docs/api/schnellstart#ohne-konto-testen) mit Status `403` ab. Mit Ihrem Schlüssel ist jede Anfrage echt: `POST /partner/create-customer` legt einen echten Kunden an, und `DELETE` entfernt eine Website wirklich.

## Zugang [#zugang]

Die Partner-API braucht ein Konto mit Partnerbereich. Wie Sie Partner werden, steht unter [Partner](https://webmetic.de/docs/partner).

Die Partner-API nutzt den Schlüssel **Visitor Intelligence** Ihres Partnerkontos und keinen eigenen Partner-Schlüssel. Nur Admins finden ihn unter [**Menü** > **Integrationen** > **API**](https://app.webmetic.de/?menu=api_details).

Senden Sie den Schlüssel unverändert im Header `Authorization`, ohne `Bearer` davor. [Authentifizierung](https://webmetic.de/docs/api/authentifizierung) beschreibt Format und Fehler.

Wenn der Schlüssel zu einem Konto ohne Partnerbereich gehört, antwortet die API mit `NOT_A_PARTNER`.

Wenn Sie den Schlüssel neu generieren, gilt der alte nicht mehr. Das betrifft Ihre Partner-Abfragen und den Abruf Ihrer eigenen Besuchsdaten.

Die Partner-Endpunkte kosten keine Credits.

## Endpunkte [#endpunkte]

| Methode und Pfad | Zweck | Anfragen pro Minute |
|---|---|---|
| [`POST /partner/create-customer`](https://webmetic.de/docs/api/referenz/partner/create-customer) | Kunden anlegen | 10 |
| [`GET /partner/customers`](https://webmetic.de/docs/api/referenz/partner/customers) | Kunden auflisten | 60 |
| [`GET /partner/customers/KUNDEN_ACCOUNT_ID`](https://webmetic.de/docs/api/referenz/partner/customers-account-id) | Einen Kunden abrufen | 60 |
| [`POST /partner/customers/KUNDEN_ACCOUNT_ID/websites`](https://webmetic.de/docs/api/referenz/partner/customers-account-id-websites) | Website hinzufügen | 30 |
| [`DELETE /partner/customers/KUNDEN_ACCOUNT_ID/websites/DOMAIN`](https://webmetic.de/docs/api/referenz/partner/customers-account-id-websites-domain) | Website entfernen | 30 |

Die Limits gelten je Endpunkt. Wenn Sie ein Limit überschreiten, antwortet die API mit Status `429`, und Sie wiederholen die Anfrage nach einer Pause.

## Neuer Kunde [#neuer-kunde]

`POST /partner/create-customer` legt ein Konto für Ihren Kunden an und erwartet einen JSON-Body mit diesen Feldern:

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `email` | String | ja | E-Mail-Adresse des ersten Benutzers. Sie darf noch zu keinem Webmetic-Konto gehören |
| `website` | String | ja | Domain oder volle Adresse der Website |
| `whitelabel` | Boolean | nein | `true` legt einen [White-Label-Kunden](https://webmetic.de/docs/partner/white-label) an. Standard ist `false` |

Webmetic kürzt `website` auf die Hauptdomain und speichert die Domain in Kleinbuchstaben. Aus `https://www.Kunde-Beispiel.de/preise` wird `kunde-beispiel.de`, aus `shop.kunde-beispiel.de` ebenfalls.

```bash tab="cURL"
curl -X POST "https://hub.webmetic.de/partner/create-customer" \
  -H "Authorization: wmtc_IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{"email": "kontakt@kunde-beispiel.de", "website": "kunde-beispiel.de", "whitelabel": true}'
```

```js tab="JavaScript"
const res = await fetch('https://hub.webmetic.de/partner/create-customer', {
  method: 'POST',
  headers: {
    Authorization: 'wmtc_IHR_API_SCHLUESSEL',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'kontakt@kunde-beispiel.de',
    website: 'kunde-beispiel.de',
    whitelabel: true,
  }),
});
const customer = await res.json();
```

```python tab="Python"
import requests

res = requests.post(
    "https://hub.webmetic.de/partner/create-customer",
    headers={"Authorization": "wmtc_IHR_API_SCHLUESSEL"},
    json={
        "email": "kontakt@kunde-beispiel.de",
        "website": "kunde-beispiel.de",
        "whitelabel": True,
    },
)
customer = res.json()
```

Die Antwort enthält die Zugangsdaten des neuen Kontos:

```json
{
  "account_id": "KUNDEN_ACCOUNT_ID",
  "email": "kontakt@kunde-beispiel.de",
  "password": "pX7kTq2mWb9R",
  "api_key": "wmtc_KUNDEN_API_SCHLUESSEL",
  "status": "partner_trial",
  "account_type": "partner_customer",
  "website": "kunde-beispiel.de",
  "whitelabel": true
}
```

Das Konto hat einen Benutzer mit der Rolle Admin und ein zufälliges Passwort.

Speichern Sie das Passwort sofort, denn Webmetic gibt es kein zweites Mal aus.

Weil Webmetic beim Anlegen über die API keine Zugangsdaten sendet, geben Sie E-Mail-Adresse und Passwort selbst an Ihren Kunden weiter.

Der Kunde kann sich damit sofort anmelden, auch auf Ihrer [White-Label-Domain](https://webmetic.de/docs/partner/white-label-domain).

Sie rechnen den neuen Kunden ab. Ein White-Label-Kunde sieht die Funktionen, die Sie unter [Funktionen für Kunden festlegen](https://webmetic.de/docs/partner/funktionen-fuer-kunden) freischalten.

Über die API setzen Sie `whitelabel` nur beim Anlegen, und später ändern Sie den Wert auf der Kundenseite im Dashboard.

Daten kommen erst an, wenn der Tracking-Code mit der Account-ID des Kunden auf seiner Website läuft. Wie Sie den Code übergeben, steht unter [Kunden anlegen](https://webmetic.de/docs/partner/kunden-anlegen).

## Kundenliste und einzelner Kunde [#kundenliste-und-einzelner-kunde]

`GET /partner/customers` liefert alle Kunden Ihres Partnerkontos, die neuesten zuerst. Die Liste enthält auch Kunden, die Sie im Dashboard angelegt haben.

| Parameter | Typ | Standard | Beschreibung |
|---|---|---|---|
| `limit` | Integer | `100` | Kunden pro Seite, 1 bis 500 |
| `offset` | Integer | `0` | Wie viele Kunden die Antwort überspringt |

`count` ist die Zahl der Kunden auf dieser Seite, `total` die Zahl aller Kunden. Um weiterzublättern, erhöhen Sie `offset` um `limit`, bis `offset` mindestens `total` erreicht.

```json
{
  "customers": [
    {
      "account_id": "KUNDEN_ACCOUNT_ID",
      "account": "kunde-beispiel",
      "email": "kontakt@kunde-beispiel.de",
      "status": "partner_trial",
      "account_type": "partner_customer",
      "api_key": "wmtc_KUNDEN_API_SCHLUESSEL",
      "websites": ["kunde-beispiel.de"],
      "usage": [],
      "whitelabel": true,
      "created_at": "2026-10-22T09:14:03.512000"
    }
  ],
  "count": 1,
  "total": 1,
  "limit": 100,
  "offset": 0,
  "partner_account_id": "IHRE_ACCOUNT_ID"
}
```

`GET /partner/customers/KUNDEN_ACCOUNT_ID` liefert einen Kunden mit denselben Feldern. Für eine unbekannte Account-ID und für Kunden eines anderen Partners antwortet die API gleich: `404` mit `CUSTOMER_NOT_FOUND`.

## Felder eines Kunden [#felder-eines-kunden]

| Feld | Beschreibung |
|---|---|
| `account_id` | Account-ID des Kunden |
| `account` | Name der Website ohne Endung, beim Anlegen gesetzt |
| `email` | E-Mail-Adresse des ersten Benutzers, sonst `null` |
| `status` | Stand des Kontos. Ein über die API angelegter Kunde hat `partner_trial`. Wenn Webmetic den Kunden abrechnet, kommen andere Werte vor, zum Beispiel `trial` |
| `account_type` | Wer abrechnet: `partner_customer` heißt Sie, `partner_direct` heißt Webmetic |
| `api_key` | Eigener API-Schlüssel des Kunden |
| `websites` | Domains des Kunden in der gespeicherten Schreibweise |
| `usage` | Monatsvolumen pro Abrechnungszeitraum, bei neuen Kunden leer |
| `whitelabel` | Ob der Kunde ein White-Label-Kunde ist. Das wirkt nur, solange Sie ihn abrechnen |
| `created_at` | Zeitpunkt der Anlage in ISO 8601 ohne Zeitzone |

Steuern Sie Ihre Logik über `account_type`, nicht über `status`, denn nur `account_type` sagt, wer abrechnet.

Ein Eintrag in `usage` enthält unter anderem diese Felder:

| Feld | Beschreibung |
|---|---|
| `period` | Abrechnungszeitraum als `YYYY-MM-DD_YYYY-MM-DD` |
| `company_count` | Erkannte Unternehmen im Zeitraum bis jetzt |
| `estimate` | Erwartete Unternehmen für 30 Tage. Nur im laufenden Zeitraum |
| `confidence` | Verlässlichkeit der Schätzung von `excellent` bis `very_low`, oder `no_data`. Nur im laufenden Zeitraum |

Das Dashboard zeigt Account-ID und API-Schlüssel eines Kunden ebenfalls unter [**Menü** > **Partnerbereich** > **Kunden**](https://app.webmetic.de/?menu=partner_customers), auf der Kundenseite unter **Kontodaten**.

## Websites eines Kunden [#websites-eines-kunden]

`POST /partner/customers/KUNDEN_ACCOUNT_ID/websites` fügt eine Website hinzu, mit dem Body `{"website": "kunde-beispiel.de"}`. Webmetic kürzt die Angabe wie beim Anlegen auf die Hauptdomain.

Wenn der Kunde diese Domain schon hat oder ein anderes Webmetic-Konto sie nutzt, antwortet die API mit `409`. Das gilt auch für Subdomains, denn Webmetic erfasst sie unter der Hauptdomain, siehe [Subdomains erfassen](https://webmetic.de/docs/installation/sonderfaelle#subdomains-erfassen).

`DELETE /partner/customers/KUNDEN_ACCOUNT_ID/websites/DOMAIN` entfernt eine Domain, die Sie genau so schreiben, wie `websites` sie zeigt.

Webmetic entfernt nur den Eintrag und löscht keine Besuchsdaten. Das Konto bleibt auch ohne Website bestehen.

Beide Endpunkte antworten mit der vollständigen Liste:

`{"account_id": "KUNDEN_ACCOUNT_ID", "websites": ["kunde-beispiel.de"]}`

## Besuchsdaten Ihrer Kunden [#besuchsdaten-ihrer-kunden]

Mit Ihrem Schlüssel lesen Sie die Besuchsdaten jeder Domain, die in `websites` eines Ihrer Kunden steht. Das gilt für `/company-sessions`, `/company`, `/company_nace`, `/session`, `/session_user_data`, `/intensive-visits`, `/returning-visits` und `/new-visits`.

Sie erhalten dieselben Daten wie mit dem Schlüssel des Kunden. Parameter, Blättern und Antworten sind dieselben wie in der [API-Referenz](https://webmetic.de/docs/api/referenz/visitor-intelligence/company-sessions).

Es gilt dasselbe Limit von einer Anfrage pro Sekunde je Endpunkt, und zusätzlich gelten diese Regeln:

- Geben Sie `domain` genau in der gespeicherten Schreibweise an: ohne `https://`, ohne `www.`, in derselben Groß- und Kleinschreibung. Sonst antwortet die API mit `403` und `API_KEY_NOT_AUTHORIZED`.
- `/company` nimmt `domain` mehrfach an und fasst die Unternehmen mehrerer Kunden zusammen. Die Antwort zeigt nicht, zu welchem Kunden ein Unternehmen gehört.
- Es gelten die Grenzen des Kundenkontos. Wenn Webmetic den Kunden abrechnet und er im Free-Plan ist, sind manche Unternehmen verborgen.
- Nach dem Entfernen einer Domain antworten Abfragen dazu mit `API_KEY_NOT_AUTHORIZED`, mit Ihrem Schlüssel und mit dem des Kunden.

Mit Ihrem Schlüssel erreichen Sie Ansprechpartner und Enrichment nicht. Für [Contacts](https://webmetic.de/docs/api/referenz/contacts/search) nutzen Sie deshalb den `api_key` des Kunden.

Die Suche nach Ansprechpartnern braucht die Einrichtung der Ansprechpartner im Dashboard des Kunden. Das Freischalten von E-Mail-Adresse oder Telefonnummer kostet seine Credits.

[Enrichment](https://webmetic.de/docs/api/referenz/enrichment/company) nutzt den Enrichment-Schlüssel des jeweiligen Kontos.

## Fehler [#fehler]

Fehler haben dasselbe Format wie bei der übrigen API, zum Beispiel bei einer unbekannten Account-ID mit Status `404`:

```json
{
  "detail": {
    "error": "CUSTOMER_NOT_FOUND",
    "message": "No customer with this account id."
  }
}
```

Werten Sie den Code in `detail.error` aus. Der englische Text in `detail.message` ist für Menschen gedacht und kann sich ändern. Mehr dazu unter [Fehler](https://webmetic.de/docs/api/fehler).

| Status | `detail.error` | Bedeutung |
|---|---|---|
| `400` | `INVALID_WEBSITE` | Keine Domain mit gültiger Endung, zum Beispiel `localhost` oder eine IP-Adresse |
| `403` | `API_KEY_MISSING` | Kein Header `Authorization` |
| `403` | `API_KEY_INVALID` | Falsches Format, zum Beispiel `Bearer` davor |
| `403` | `API_KEY_NOT_FOUND` | Den Schlüssel gibt es nicht, etwa weil er neu generiert wurde |
| `403` | `NOT_A_PARTNER` | Der Schlüssel gehört zu einem Konto ohne Partnerbereich |
| `404` | `CUSTOMER_NOT_FOUND` | Unbekannte Account-ID oder Kunde eines anderen Partners |
| `404` | `WEBSITE_NOT_FOUND` | Der Kunde hat diese Domain nicht |
| `409` | `EMAIL_ALREADY_EXISTS` | Ein Webmetic-Konto nutzt die E-Mail-Adresse bereits |
| `409` | `WEBSITE_ALREADY_EXISTS` | Beim Anlegen: ein anderes Webmetic-Konto nutzt die Website. Beim Hinzufügen: der Kunde hat sie schon, oder ein anderes Webmetic-Konto nutzt sie |
| `422` | `VALIDATION_ERROR` | Pflichtfeld fehlt, E-Mail-Adresse ungültig, `limit` oder `offset` außerhalb des Bereichs. Die Liste `errors` nennt jede Stelle |
| `429` | `RATE_LIMITED` | Mehr Anfragen pro Minute, als der Endpunkt annimmt. Warten Sie und wiederholen Sie die Anfrage |
| `500` | `INTERNAL_ERROR` | Fehler bei Webmetic. Wiederholen Sie die Anfrage später |

## Grenzen [#grenzen]

- Die Partner-API sendet keine Webhooks, und Sie fragen neue Daten pro Domain ab. Webhooks stehen pro Webmetic-Konto bereit. Mehr dazu unter [Webhooks](https://webmetic.de/docs/api/webhooks).
- Sie richten White-Label-Domain, Branding und Funktionen für Kunden im Dashboard ein.
- Auf der Kundenseite im Dashboard ändern Sie, wer einen Kunden abrechnet.
- Nur die Antwort beim Anlegen enthält das Passwort eines Kunden.

## Nächste Schritte [#nächste-schritte]

- [Kunden anlegen](https://webmetic.de/docs/partner/kunden-anlegen): Den Tracking-Code mit der Account-ID des Kunden übergeben.
- [Kunden verwalten](https://webmetic.de/docs/partner/kunden-verwalten): Monatsvolumen, Abrechnung und Benutzer Ihrer Kunden im Dashboard prüfen.
- [Authentifizierung](https://webmetic.de/docs/api/authentifizierung): Format des Schlüssels und alle Fehler beim Schlüssel nachlesen.