Einrichtung und Verwendung der REST API v1
AffiliateWP verfügt über eine Reihe von schreibgeschützten REST-Endpunkten, die auf der Infrastruktur von WordPress 4.4 und neuer aufbauen.
In diesem Artikel zeigen wir Ihnen, wie Sie die REST API v1 einrichten und verwenden, um auf AffiliateWP-Daten zuzugreifen.
REST API – Authentifizierung
Um die Kern-REST-Endpunkte nutzen zu können, müssen sich alle API-Konsumenten mit API-Schlüsseln authentifizieren, die aus einem neuen Tab API-Schlüssel unter Affiliates → Tools → API-Schlüssel generiert werden.
Die REST API verwendet die Basisauthentifizierung mit einer Kombination aus einem öffentlichen Schlüssel und einem Token.
Bevor Sie eine API-Anfrage authentifizieren können, benötigen Sie ein Set von API-Schlüsseln. Diese sind benutzerspezifisch und können unter Affiliates → Tools → API-Schlüssel erstellt werden:
Um ein neues Set von API-Schlüsseln zu generieren, geben Sie den Benutzernamen des Benutzers ein, zu dem die Schlüssel gehören sollen, und klicken Sie auf Neue API-Schlüssel generieren.
Hinweis: Das Benutzerkonto, mit dem die API-Schlüssel verknüpft sind, muss über die entsprechenden Berechtigungen verfügen, damit die API funktioniert. Typischerweise bedeutet dies, dass der Benutzer die Rolle Administrator haben muss. Weitere Informationen finden Sie in unserer Dokumentation zu Rollen und Berechtigungen.
Sobald die API-Schlüssel erstellt sind, können Sie sich mit der REST API authentifizieren, indem Sie die Schlüssel in den Authentifizierungsheader aufnehmen. Der öffentliche Schlüssel sollte als Benutzer und das Token als Passwort übergeben werden.
Zum Beispiel, mit Postman, würde unsere authentifizierte Anfrage wie folgt aussehen:
Wenn Sie curl verwenden, würde eine authentifizierte Anfrage wie folgt aussehen:
curl -u 229c1d4292800a4fdaa1099a4c646c9a:c7fd218923e058e1637698e5257855de http://local.wp/woo/wp-json/affwp/v1/affiliates
Der Autorisierungsheader muss bei jeder API-Anfrage enthalten sein, um sich ordnungsgemäß bei der API zu authentifizieren. Wenn die Basisauthentifizierung nicht angegeben wird oder die Anmeldedaten falsch sind, wird eine Fehlermeldung zurückgegeben:
{
"code": "rest_forbidden",
"message": "Sorry, you are not allowed to do that.",
"data": {
"status": 403
}
}
Routen und Endpunkte
AffiliateWP bietet fünf Routen und mehrere zugrunde liegende Endpunkte. Diese fünf Routen sind:
Klicken Sie auf die oben genannten Routennamen, um mehr über ihre jeweiligen Endpunkte, Beispielanfragen und mehr zu erfahren.
Hinweis: Vollständige Create-, Read-, Update- und Delete- (CRUD) Operationen können über das REST API Extended Add-on aktiviert werden. Siehe die REST API Extended Dokumentation für Informationen zu Create-, Update- und Delete-Operationen.
1. Affiliate-Endpunkte
AffiliateWP Core 1.9+ bietet zwei schreibgeschützte REST-Endpunkte für Affiliates:
- affiliates – Ruft Antwortobjekte für alle Affiliates auf der aktuellen Website ab
- affiliates/{ID} – Ruft ein Antwortobjekt für einen Affiliate mit der angegebenen Affiliate-ID ab
Die Affiliate-Endpunkte können über GET-Anfragen an den folgenden Speicherorten aufgerufen werden:
http://example.com/wp-json/affwp/v1/affiliates http://example.com/wp-json/affwp/v1/affiliates/ID
Alle Affiliate-Endpunkte und ihre verschiedenen Optionen sind auch durch direkten Besuch des AffiliateWP REST-Namespaces auffindbar:
http://example.com/wp-json/affwp/v1/
Endpunkte
Der Affiliates-Endpunkt akzeptiert alle gültigen get_affiliates()-Argumente:
- number – Die Anzahl der abzurufenden Ergebnisse (falls verfügbar)
- offset – Die Anzahl der zu überspringenden Ergebnisse in der Abfrage. Standard ist 0 (kein Offset)
- affiliate_id – Die Affiliate-ID oder ein Array von IDs, nach denen abgefragt werden soll.
- user_id – Die Benutzer-ID oder ein Array von IDs, nach denen Auszahlungen abgefragt werden sollen.
- exclude – Affiliate-ID oder ein Array von IDs, die von der Anfrage ausgeschlossen werden sollen.
- search – Begriffe, nach denen Affiliates gesucht werden sollen. Akzeptiert eine Affiliate-ID oder eine Zeichenkette.
- status – Der Affiliate-Status. Akzeptiert 'active', 'inactive', 'pending' oder 'rejected'.
- order – Wie die Ergebnisse sortiert werden sollen. Akzeptiert 'ASC' (aufsteigend) oder 'DESC' (absteigend).
- orderby – Nach welchem Feld die Antwort-Ergebnisse sortiert werden sollen. Standard ist 'date'
- fields – Bestimmte Felder, die für jeden Affiliate in der Antwort zurückgegeben werden sollen. Standard '*' (alle). Akzeptiert 'ids' oder jede gültige Spalte
Zusätzliche Argumente:
- user – Wenn user als true übergeben wird, werden für jeden Affiliate in der Antwort benutzerdefinierte Benutzerobjekte "on the fly" abgerufen. Bei Verwendung dieser Option ist Vorsicht geboten, da die Anzahl der Datenbankabfragen mit jedem Affiliate um 1:1 steigt.
- meta – Wenn als true übergeben, wird für jeden Affiliate in der Antwort ein Array von Affiliate-Metadaten "on the fly" abgerufen. Genau wie bei user ist Vorsicht geboten, da die Leistung beeinträchtigt wird.
Alle gültigen Argumente können auch durch Senden einer OPTIONS-Anfrage an einen der Endpunkte abgeleitet werden.
Der affiliates/{ID}-Endpunkt akzeptiert jede gültige Affiliate-ID. Zusätzlich, wenn user und/oder meta als true übergeben werden, wird ein benutzerdefiniertes Benutzerobjekt und/oder ein Array von Affiliate-Metadaten "on the fly" abgerufen, um sie in die Antwort aufzunehmen.
Sichtbarkeit
Alle Endpunkte erfordern den API-Schlüssel und das Token, mit Ausnahme des Haupt-affwp/v1-Endpunkts.
Antwort
Antworten werden im JSON-Format zurückgegeben.
Beispiel affiliates Antwort:
[
{
"affiliate_id": 2736,
"user_id": 1336,
"rate": "",
"rate_type": "",
"payment_email": "",
"status": "active",
"earnings": 6,
"unpaid_earnings": 0,
"referrals": 6,
"visits": 0,
"date_registered": "2016-08-17 19:46:25",
"id": 2736
},
{
"affiliate_id": 2737,
"user_id": 1337,
"rate": "",
"rate_type": "",
"payment_email": "",
"status": "inactive",
"earnings": 1,
"unpaid_earnings": 3145.59,
"referrals": 1,
"visits": 0,
"date_registered": "2016-08-17 19:46:25",
"id": 2737
}
]
Beispiel affiliates/{ID} Antwort:
{
"affiliate_id": 2737,
"user_id": 1337,
"rate": "",
"rate_type": "",
"payment_email": "",
"status": "inactive",
"earnings": 1,
"unpaid_earnings": 3145.59,
"referrals": 1,
"visits": 0,
"date_registered": "2016-08-17 19:46:25"
}
Beispiel affiliates{ID}?user=1 Antwort:
{
"affiliate_id": 2737,
"user_id": 1337,
"rate": "",
"rate_type": "",
"payment_email": "",
"status": "inactive",
"earnings": 1,
"unpaid_earnings": 3145.59,
"referrals": 1,
"visits": 0,
"date_registered": "2016-08-17 19:46:25",
"user": {
"ID": "1337",
"user_login": "user_1_11",
"user_nicename": "user_1_11",
"user_url": "",
"user_registered": "2016-08-17 19:46:25",
"user_status": "0",
"display_name": "User 11",
"spam": "0",
"deleted": "0",
"first_name": "",
"last_name": ""
}
}
Beispiel affiliates{ID}?meta=1 Antwort:
{
"affiliate_id": 2737,
"user_id": 1337,
"rate": "",
"rate_type": "",
"payment_email": "[email protected]",
"status": "active",
"earnings": 32039.07,
"unpaid_earnings": 3145.59,
"referrals": 3192,
"visits": 0,
"date_registered": "2016-08-17 19:46:25",
"meta": {
"some_key": [
"some_value"
]
},
"id": 2737
}<br>
.
2. Creatives Endpunkte
AffiliateWP Core 1.9+ bietet zwei schreibgeschützte REST-Endpunkte für Creatives:
- creatives – Ruft Antwortobjekte für alle Creatives auf der aktuellen Website ab
- creatives/{ID} – Ruft ein Antwortobjekt für ein Creative mit der angegebenen Creative-ID ab
Die Creative-Endpunkte können über GET-Anfragen an den folgenden Speicherorten aufgerufen werden:
http://example.com/wp-json/affwp/v1/creatives http://example.com/wp-json/affwp/v1/creatives/ID
Alle kreativen Endpunkte und ihre verschiedenen Optionen sind auch durch direkten Besuch des AffiliateWP REST-Namespace discoverbar:
http://example.com/wp-json/affwp/v1/
Endpunkte
Der creatives Endpunkt akzeptiert alle gültigen get_creatives()-Argumente:
- number – Die Anzahl der abzurufenden Ergebnisse (falls verfügbar)
- offset – Die Anzahl der zu überspringenden Ergebnisse in der Abfrage. Standard ist 0 (kein Offset)
- creative_id – Die kreative ID oder ein Array von IDs, nach denen gesucht werden soll.
- status – Der kreative Status. Akzeptiert 'active' oder 'inactive'.
- order – Wie die Ergebnisse sortiert werden sollen. Akzeptiert 'ASC' (aufsteigend) oder 'DESC' (absteigend).
- orderby – Spalte der Creatives-Tabelle, nach der sortiert werden soll.
- fields – Spezifische Felder, die für jedes Creative in der Antwort zurückgegeben werden sollen. Standard ist '*' (alle). Akzeptiert 'ids' oder jede gültige Spalte.
Alle gültigen Argumente können auch durch Senden einer OPTIONS-Anfrage an einen der Endpunkte abgeleitet werden.
Der creatives/{ID} Endpunkt akzeptiert jede gültige kreative ID.
Sichtbarkeit
Alle Endpunkte erfordern den API-Schlüssel und das Token, mit Ausnahme des Haupt-affwp/v1 Endpunkts.
Antwort
Antworten werden im JSON-Format zurückgegeben.
Beispiel creatives Antwort:
{
"creative_id": 2,
"name": "My Other Creative",
"description": "",
"url": "http://affiliate.dev",
"text": "AffiliateWP Plugin Testing",
"image": "",
"status": "inactive",
"date": "2016-05-11 23:35:58",
"id": 2
},
{
"creative_id": 3,
"name": "Special Case",
"description": "",
"url": "http://affiliate.dev",
"text": "AffiliateWP Plugin Testing",
"image": "https://affwp.dev/wp-content/images/brand-assets/affiliatewp-1v.png",
"status": "active",
"date": "2016-05-11 23:43:02",
"id": 3
},
Beispiel creatives/{ID} Antwort:
{
"creative_id": 2,
"name": "My Other Creative",
"description": "",
"url": "http://affiliate.dev",
"text": "AffiliateWP Plugin Testing",
"image": "",
"status": "inactive",
"date": "2016-05-11 23:35:58",
"id": 2
}
.
3. Auszahlungs-Endpunkte
AffiliateWP Core 1.9+ bietet zwei schreibgeschützte REST-Endpunkte für Auszahlungen:
- payouts – Ruft Antwortobjekte für alle Auszahlungen auf der aktuellen Website ab
- payouts/{ID} – Ruft ein Antwortobjekt für eine Auszahlung mit der angegebenen Auszahlungs-ID ab
Die Auszahlungs-Endpunkte können über GET-Anfragen an folgenden Orten aufgerufen werden:
http://example.com/wp-json/affwp/v1/payouts http://example.com/wp-json/affwp/v1/payouts/ID
Alle Auszahlungs-Endpunkte und ihre verschiedenen Optionen sind auch durch direkten Besuch des AffiliateWP REST-Namespace discoverbar:
http://example.com/wp-json/affwp/v1/
Endpunkte
Der payouts Endpunkt akzeptiert alle gültigen get_payouts()-Argumente:
- number – Die Anzahl der abzurufenden Ergebnisse (falls verfügbar)
- offset – Die Anzahl der zu überspringenden Ergebnisse in der Abfrage. Standard ist 0 (kein Offset)
- payout_id – Die Auszahlungs-ID oder ein Array von IDs, nach denen gesucht werden soll.
- affiliate_id – Die Affiliate-ID oder ein Array von IDs, nach denen Auszahlungen gesucht werden sollen.
- referrals – Empfehlungs-ID oder Array von Empfehlungs-IDs, um Auszahlungen abzurufen.
- amount – Auszahlungsbetrag (float) oder Min/Max-Bereich (Array), um Auszahlungen abzurufen.
- amount_compare – Vergleichsoperator, der mit amount verwendet wird. Akzeptiert '>', '<', '>=', '<=', '=' oder '!='.
- status – Der Auszahlungsstatus. Akzeptiert 'paid' oder 'failed'.
- date – Das Datums-Array oder die Zeichenkette, innerhalb derer Auszahlungen gesucht werden sollen.
- order – Wie die Ergebnisse sortiert werden sollen. Akzeptiert 'ASC' (aufsteigend) oder 'DESC' (absteigend).
- orderby – Nach welchem Feld die Antwort-Ergebnisse sortiert werden sollen. Standard ist 'date'
- fields – Spezifische Felder, die für jede Auszahlung in der Antwort zurückgegeben werden sollen. Standard ist '*' (alle). Akzeptiert 'ids' oder jede gültige Spalte.
Alle gültigen Argumente können auch durch Senden einer OPTIONS-Anfrage an einen der Endpunkte abgeleitet werden.
Der payouts/{ID} Endpunkt akzeptiert jede gültige Auszahlungs-ID.
Sichtbarkeit
Alle Endpunkte erfordern den API-Schlüssel und das Token, mit Ausnahme des Haupt-affwp/v1 Endpunkts.
Antwort
Antworten werden im JSON-Format zurückgegeben.
Beispiel payouts Antwort:
[
{
"payout_id": 1,
"affiliate_id": 22,
"referrals": "2,3",
"amount": 1,
"payout_method": "manual",
"status": "paid",
"date": "2016-08-04 16:54:21",
"owner": 0,
"id": 1
},
{
"payout_id": 2,
"affiliate_id": 22,
"referrals": "2,3",
"amount": 1,
"payout_method": "manual",
"status": "paid",
"date": "2016-08-04 16:54:24",
"owner": 0,
"id": 2
},
Beispiel payouts/{ID} Antwort:
{
"payout_id": 2,
"affiliate_id": 22,
"referrals": "2,3",
"amount": 1,
"payout_method": "manual",
"status": "paid",
"date": "2016-08-04 16:54:24",
"owner": 0,
"id": 2
}<br>
.
4. Empfehlungs-Endpunkte
AffiliateWP Core 1.9+ bietet zwei schreibgeschützte REST-Endpunkte für Empfehlungen:
- Überweisungen – Ruft Antwortobjekte für alle Überweisungen auf der aktuellen Website ab
- Überweisungen/{ID} – Ruft ein Antwortobjekt für eine Überweisung mit der angegebenen Überweisungs-ID ab
Auf die Überweisungs-Endpunkte kann über GET-Anfragen an den folgenden Speicherorten zugegriffen werden:
http://example.com/wp-json/affwp/v1/referrals http://example.com/wp-json/affwp/v1/referrals/ID
Alle Überweisungs-Endpunkte und ihre verschiedenen Optionen können auch entdeckt werden, indem Sie direkt den AffiliateWP REST-Namespace besuchen:
http://example.com/wp-json/affwp/v1/
Endpunkte
Der Endpunkt Überweisungen akzeptiert alle gültigen Argumente von get_referrals():
- number – Die Anzahl der abzurufenden Ergebnisse (falls verfügbar)
- offset – Die Anzahl der zu überspringenden Ergebnisse in der Abfrage. Standard ist 0 (kein Offset)
- referral_id – Die Überweisungs-ID oder ein Array von IDs, nach denen gesucht werden soll.
- affiliate_id – Die Affiliate-ID oder ein Array von IDs, nach denen abgefragt werden soll.
- reference – Referenzinformationen (Produkt-ID) für die Überweisung.
- ref_context – Der Kontext, unter dem die Überweisung erstellt wurde (Integration).
- campaign – Die zugehörige Kampagne.
- status – Der Überweisungsstatus oder ein Array von Status. Akzeptiert 'paid', 'unpaid', 'pending' oder 'rejected'.
- order – Wie die Ergebnisse sortiert werden sollen. Akzeptiert 'ASC' (aufsteigend) oder 'DESC' (absteigend).
- orderby – Nach welchem Feld die Antwort-Ergebnisse sortiert werden sollen. Standard ist 'date'
- search – Eine Überweisungs-ID oder der Suchbegriff, nach dem Überweisungen gesucht werden sollen.
- date – Das Datums-Array oder die Zeichenkette, innerhalb derer nach Überweisungen gesucht werden soll.
- fields – Bestimmte Felder, die für jede Überweisung in der Antwort zurückgegeben werden sollen. Standard ist '*' (alle). Akzeptiert 'ids' oder jede gültige Spalte
Alle gültigen Argumente können auch durch Senden einer OPTIONS-Anfrage an einen der Endpunkte abgeleitet werden.
Der Endpunkt referrals/{ID} akzeptiert jede gültige Überweisungs-ID.
Sichtbarkeit
Alle Endpunkte erfordern den API-Schlüssel und das Token, mit Ausnahme des Haupt-affwp/v1 Endpunkts.
Antwort
Antworten werden im JSON-Format zurückgegeben.
Beispielantwort für referrals :
{
"referral_id": 21,
"affiliate_id": 0,
"visit_id": 0,
"description": "",
"status": "",
"amount": "",
"currency": "",
"custom": "",
"context": "",
"campaign": "",
"reference": "",
"products": "",
"date": "2016-08-17 19:57:30",
"payout_id": "102",
"id": 21
},
{
"referral_id": 22,
"affiliate_id": 2736,
"visit_id": 0,
"description": "",
"status": "paid",
"amount": "1.00",
"currency": "USD",
"custom": "",
"context": "",
"campaign": "",
"reference": "",
"products": "",
"date": "2016-08-17 19:57:43",
"payout_id": "81",
"id": 22
},
Beispielantwort für referrals/{ID}:
{
"referral_id": 21,
"affiliate_id": 0,
"visit_id": 0,
"description": "",
"status": "",
"amount": "",
"currency": "",
"custom": "",
"context": "",
"campaign": "",
"reference": "",
"products": "",
"date": "2016-08-17 19:57:30",
"payout_id": "102",
"id": 21
}
.
5. Besucher-Endpunkte
AffiliateWP Core 1.9+ bietet zwei schreibgeschützte REST-Endpunkte für Besucher:
- visits – Ruft Antwortobjekte für alle Besucher auf der aktuellen Website ab
- visits/{ID} – Ruft ein Antwortobjekt für einen Besucher mit der angegebenen Besucher-ID ab
Auf die Besucher-Endpunkte kann über GET-Anfragen an den folgenden Speicherorten zugegriffen werden:
http://example.com/wp-json/affwp/v1/visits http://example.com/wp-json/affwp/v1/visits/ID
Alle Besucher-Endpunkte und ihre verschiedenen Optionen können auch entdeckt werden, indem Sie direkt den AffiliateWP REST-Namespace besuchen:
http://example.com/wp-json/affwp/v1/
Endpunkte
Der Endpunkt visits akzeptiert alle gültigen Argumente von get_visits():
- number – Die Anzahl der abzurufenden Ergebnisse (falls verfügbar)
- offset – Die Anzahl der zu überspringenden Ergebnisse in der Abfrage. Standard ist 0 (kein Offset)
- visit_id – Die Besucher-ID oder ein Array von IDs, nach denen Besucher gesucht werden sollen.
- affiliate_id – Die Affiliate-ID oder ein Array von IDs, nach denen Besucher gesucht werden sollen.
- referral_id – Die Überweisungs-ID oder ein Array von IDs, nach denen Besucher gesucht werden sollen.
- referral_status – Der Überweisungsstatus oder ein Array von Status, nach denen Besucher abgerufen werden sollen.
- campaign – Die zugehörige Kampagne.
- order – Wie die Besucher in der Antwort sortiert werden sollen. Standard ist 'ASC' (aufsteigend).
- orderby – Nach welchem Feld die Antwort-Ergebnisse sortiert werden sollen. Standard ist 'date'
- fields – Bestimmte Felder, die für jeden Besucher in der Antwort zurückgegeben werden sollen. Standard ist '*' (alle). Akzeptiert 'ids' oder jede gültige Spalte
Alle gültigen Argumente können auch durch Senden einer OPTIONS-Anfrage an einen der Endpunkte abgeleitet werden.
Der Endpunkt visits/{ID} akzeptiert jede gültige Besucher-ID.
Sichtbarkeit
Alle Endpunkte erfordern den API-Schlüssel und das Token, mit Ausnahme des Haupt-affwp/v1 Endpunkts.
Antwort
Antworten werden im JSON-Format zurückgegeben.
Beispiel Besuche Antwort:
{
"visit_id": 1,
"affiliate_id": 5464,
"referral_id": 0,
"url": "http://google.com",
"referrer": "https://affiliatewp.com",
"campaign": "test",
"ip": "",
"date": "2016-09-20 21:58:09",
"id": 1
},
{
"visit_id": 2,
"affiliate_id": 5464,
"referral_id": 0,
"url": "http://google.com",
"referrer": "https://affiliatewp.com",
"campaign": "test",
"ip": "",
"date": "2016-09-18 21:58:11",
"id": 2
},
Beispiel Besuche/{ID} Antwort:
{
"visit_id": 2,
"affiliate_id": 5464,
"referral_id": 0,
"url": "http://google.com",
"referrer": "https://affiliatewp.com",
"campaign": "test",
"ip": "",
"date": "2016-09-18 21:58:11",
"id": 2
}
.