Deutsch | English | Español | Français | Italiano | Nederlands | Polski | Português (Brasil) | Svenska

API-Endpunkt für Transaktionsvalidierung

Die Advertiser-API von Awin unterstützt Transaktionsvalidierungen. Dies gibt Ihnen die Möglichkeit, Transaktionen über die Awin-API freizugeben, abzulehnen und zu ändern.

Die API für Transaktionsvalidierungen umfasst einen Batch-Endpunkt, über den Sie mehrere Validierungsanforderungen in einer einzigen Einreichung zusammenfassen können.

Dieser API-Endpunkt ist Teil der allgemeinen API-Infrastruktur von Awin und verwendet somit ein benutzerbasiertes OAUTH2-Token. Weitere Informationen zu OAUTH2 finden Sie auf der Wiki-Seite zur Authentifizierung und Autorisierung über die API.

Batch-Verarbeitung von Transaktionsvalidierungen

Bei der Batch-Verarbeitung von Transaktionsvalidierungen kann eine Liste von einer oder mehreren als JSON formatierten Transaktionen gleichzeitig übertragen und nachfolgend verarbeitet werden. Um den Fortschritt Ihrer Validierungsanforderungen überwachen zu können, stellt Awin Ihnen eine trackbare Job-ID zur Verfügung.

So rufen Sie die API auf

Methode:
POST

URL:

https://api.awin.com/advertisers/<yourAdvertiserId>/transactions/batch

Anforderungshauptteil:
Der Anforderungshauptteil enthält ein Array von Transaktionsobjekten. Jedes Objekt stellt die auszuführende Aktion (Transaktion) dar sowie ggf. zusätzliche Parameter bereit. Transaktionen werden entweder anhand der Transaktions-ID (transactionId) oder anhand der Auftragsnummer (orderRef), dem Transaktionsdatum (transactionDate) und der Zeitzone (timezone) identifiziert.

"transactionId": "484816099",

"orderRef": "123ABC555",
"transactionDate": "2017-02-20T22:04:00",
"timezone": "Europe/Paris"

Verfügbare Operationen

Freigeben (approve)

Freigeben mit 'transactionId':

{
"action": "approve",
"transaction":
    {
        "transactionId": 1234567
    }
}

Freigeben mit 'orderRef', 'transactionDate' und 'timezone':

{
"action": "approve",
"transaction":
    {
        "orderRef": "123ABC555",
        "transactionDate": "2017-02-20T22:04:00",
        "timezone": "Europe/Paris"
    }
}

Ablehnen (decline)

Ablehnen mit 'transactionId':

{
"action": "decline",
"transaction":
    {
        "transactionId": 1234567,
        "declineReason": "order returned"
    }
}

Ablehnen mit 'orderRef', 'transactionDate' und 'timezone':

{
"action": "decline",
"transaction":
    {
        "orderRef": "123ABC555",
        "transactionDate": "2017-02-20T22:04:00",
        "timezone": "Europe/Paris",
        "declineReason": "order returned"
    }
}

Ändern (amend)

Ändern mit 'transactionId':

{
"action": "amend",
"approve": false,
"transaction":
    {
 
        "transactionId": 1234567,
        "amendReason": "partial return",
        "currency": "EUR",
        "saleAmount": 55.96,
        "transactionParts": [
          {
            "amount": 44.76,
            "commissionGroupCode": "DEFAULT"
          },
          {
            "amount": 11.20,
            "commissionGroupCode": "EXISTING"
          }
        ]
    }
}

Ändern mit 'orderRef', 'transactionDate' und 'timezone':

{
"action": "amend",
"approve": false,
"transaction":
    {
        "orderRef": "123ABC555",
        "transactionDate": "2017-02-20T22:04:00",
        "timezone": "Europe/Paris",
        "amendReason": "partial return",
        "currency": "EUR",
        "saleAmount": 55.96,
        "transactionParts": [
          {
            "amount": 44.76,
            "commissionGroupCode": "DEFAULT"
          },
          {
            "amount": 11.20,
            "commissionGroupCode": "EXISTING"
          }
        ]
    }
}

Hinweis:
Um die Integrität von Änderungstransaktionen zu gewährleisten, muss die Summe der Transaktionsteile (transactionParts) dem Sales-Betrag (saleAmount) entsprechen. Mögliche Unterschiede werden durch die automatische Anpassung der Provisionsgruppe (commissionGroup) "DEFAULT" ausgeglichen.

Wenn Sie den Parameter "approve" auf "true" setzen, ändert die API zunächst die Transaktion und gibt sie dann anschließend sofort frei.

Anforderungshauptteil

Sie müssen Aktionen des Anforderungshauptteils mit dem endgültigen Anforderungshauptteil für die Batch-Verarbeitung verbinden. Nachfolgend finden Sie ein Beispiel für einen Batch mit drei Transaktionen: einer Transaktion des Typs 'approve', einer Transaktion des Typs 'amend' und einer Transaktion des Typs 'decline'.

[
  {
    "action": "amend",
    "approve": false,
    "transaction": {
        "transactionId": "484816099",
        "amendReason": "partial return",
        "currency": "EUR",
        "saleAmount": 44.76,
        "transactionParts": [{
            "amount": 44.76,
            "commissionGroupCode": "DEFAULT"
        }]
    }
  },
 
  {
    "action": "decline",
    "transaction":
      {
          "transactionId": 1234567,
          "declineReason": "order returned"
      }
  },
 
  {
  "action": "approve",
  "transaction":
      {
          "orderRef": "123ABC555",
          "transactionDate": "2017-02-20T22:04:00",
          "timezone": "Europe/Paris"
      }
  }
 
]

Um die erforderlichen Daten, wie die 'transactionId', abzurufen, verwenden Sie die Methode GET für diesen Endpunkt. Weitere Informationen finden Sie unter GET-Transaktionen (Liste).

Antworthauptteil

{
 "jobId": "5cbefc8646e0fb0001c4670e"
}

Mit der Job-ID (jobId) können Sie den Status aller aktiven Jobs für bis zu 60 Tage nach der Erstellung des entsprechenden Jobs überprüfen.

Endpunkt für Jobstatus

Allgemeiner Jobstatus

Methode:
GET

URL:

https://api.awin.com/advertisers/<yourAdvertiserId>/transactions/jobs/<jobId>

Antworthauptteil

{
    "jobId": 5cbefc8646e0fb0001c4670e,
    "status": "DONE",
    "transactionCount": 100,
    "allTransactions": null,
    "errorCount": 0,
    "failedTransactions": null,
    "creationDate": "2017-02-20T22:04:00",
    "completionDate": "2017-02-20T22:24:00"
}

Wenn Sie keine detaillierte Transaktionsliste oder Fehlerliste für einen Job abfragen, wird die Standardeinstellung "null" auf die Objekte allTransactions und failedTransactions angewendet.

Detaillierte Fehlerliste

Um eine zusätzliche Liste der Transaktionen bereitzustellen, die während der Validierung einen Fehler generiert haben, fügen Sie den Parameter "output=errors" zur URL hinzu. Die API listet dann die einzelnen Transaktionen innerhalb des Objekts failedTransactions auf. Um eine vollständige Liste aller Transaktionen innerhalb des Objekts allTransactions zu generieren, fügen Sie stattdessen der URL den Parameter "output=all" hinzu.

Methode:
GET

URL:

https://api.awin.com/advertisers/<yourAdvertiserId>/transactions/jobs/<jobId>?output=errors
 
https://api.awin.com/advertisers/<yourAdvertiserId>/transactions/jobs/<jobId>?output=all

Antworthauptteil

{
    "jobId":"5cb8290460b59a6e7ae22d0b",
    "status":"DONE",
    "transactions":2,
    "allTransactions":null, 
    "errors":2,
    "failedTransactions":
    [
      {
         "transactionId":1234567,
         "orderRef":null,
         "transactionDate":null,
         "timezone":"",
         "code":"[404 NOT_FOUND]",
         "description":null
      },
      {
         "transactionId":1234568,
         "orderRef":null,
         "transactionDate":null,
         "timezone":"",
         "code":"[404 NOT_FOUND]",
         "description":null
      }
    ],
    "creationDate":"2019-04-18T09:49:35.558",
    "completionDate":"2019-04-18T09:49:36.513"
}

Jobliste

Um eine Liste aller Ihrer Jobs der letzten 60 Tage zu generieren, rufen Sie den Job-Endpunkt auf, ohne dabei eine dedizierte Job-ID anzugeben.

Methode:
GET

URL:

https://api.awin.com/advertisers/<yourAdvertiserId>/transactions/jobs

Gängige Antwortcodes

Die folgende Tabelle enthält eine Liste möglicher Gründe für Antworten für gängige Antwortcodes, die bei der Verwendung der API angezeigt werden können: