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

Endpoint API per la convalida delle transazioni

Awin Advertiser API supporta la convalida delle transazioni e quindi, con Awin API le puoi approvare, respingere e modificare.

L’API convalida delle transazioni presenta un endpoint batch che ti permette di raggruppare insieme richieste multiple di convalida in un’unica trasmissione.

L’endpoint API per la convalida delle transazioni fa parte dell’infrastruttura generale di Awin API. Come tale, l’endpoint si serve di un token utente OAUTH2. Per ulteriori informazioni su OAUTH2 consulta la pagina wiki sull’autenticazione e autorizzazione dell’API.

Convalida delle transazioni in lotti

La convalida delle transazioni in lotti ti permette di trasferire e quindi processare contemporaneamente un elenco di una o più transazioni formattate JSON. Awin fornisce un jobID tracciabile che ti permette di monitorare l’avanzamento delle tue richieste di convalida.

Come aprire l’API

Metodo:
POST

URL:

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

Corpo della richiesta:
Il corpo della richiesta comprende un array di oggetti di transazione. Ogni oggetto rappresenta l’azione da eseguire, cioè la transazione, e, se necessario, parametri addizionali. Le transazioni vengono identificate con transactionId, orderRef, transactionDate e timezone.

"transactionId": "484816099",

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

Operazioni disponibili

Approva

Approva con transactionId:

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

Approva con orderRef, transactionDate e timezone:

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

Respingi

Respingi con transactionId:

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

Respingi con orderRef, transactionDate e timezone:

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

Modifica

Modifica con 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"
          }
        ]
    }
}

Modifica con orderRef, transactionDate e 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"
          }
        ]
    }
}

Nota:
Per garantire l’integrità delle transazioni modificate, la loro somma deve essere identica al saleAmount altrimenti, per compensare possibili differenze il "DEFAULT" commissionGroup viene regolato automaticamente.

Se imposti il parametro di approvazione su "true", l’API prima modifica la transazione e poi la approva subito dopo.

Corpo della richiesta

Devi abbinare alle azioni del corpo della richiesta il corpo della richiesta del lotto finale. Sotto abbiamo riportato un esempio di un lotto con tre transazioni: una transazione “approva”, una “modifica” e una “respingi”:

[
  {
    "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"
      }
  }
 
]

Per accedere ai dati necessari quali transactionId, utilizza il metodo GET di questo endpoint. Per ulteriori informazioni consulta GET transactions (elenco).

Corpo della risposta

{
 "jobId": "5cbefc8646e0fb0001c4670e"
}

jobId ti permette di visualizzare lo stato dei job in corso fino a 60 giorni dopo la creazione del job stesso.

Endpoint stato job

Stato generale job

Metodo:
GET

URL:

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

Corpo della risposta

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

Se non richiedi un elenco dettagliato o un elenco di errori di un job gli oggetti allTransactions e failedTransactions saranno impostati su "null". Per ulteriori informazioni consulta la sezione Elenco dettagliato errori di questa pagina.

Elenco dettagliato errori

Per creare un elenco addizionale delle transazioni che hanno generato un errore durante la convalida aggiungi al URL il parametro "output=errors". L’API riporta le singole transazioni che sono nell’ambito dell’oggetto failedTransactions. Per generare un elenco completo di tutte le transazioni nell’ambito dell’oggetto allTransactions, aggiungi al URL il parametro "output=all".

Metodo:
GET

URL:

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

Corpo della risposta

{
    "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"
}

Elenco job

To generate a list of all your jobs from the last 60 days, call the job endpoint without providing a dedicated job ID.

Metodo:
GET

URL:

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

Codici risposta comune

La tabella sotto presenta un elenco di possibili motivi di risposta per i codici risposta comune che vengono visualizzati con l’API: