Export automatico via Console API

L'API della Console è disponibile negli ambienti di test (Stage) e di produzione. Utilizzala per esportare automaticamente i dati visualizzati nei moduli Transazioni e Reportistica finanziaria della Console di HiPay. In questo articolo troverai tutte le informazioni necessarie per le esportazioni una tantum e ricorrenti effettuate tramite la nostra Console API.

Per visualizzare la documentazione tecnica degli endpoint API della Console, visitare i seguenti URL:

• Stage: https://stage-console.hipay. com/api/docs
• Produzione: https://console.hipay.com/ api/docs

Qui è possibile testare tutti gli endpoint descritti in questo documento.

Generazione di una chiave temporanea

Il primo passo consiste nel generare un token (chiave temporanea) per identificarsi. Per farlo, effettua una chiamata API POST all'URL:

• https://console.hipay.com/api/login 

Nel corpo, inserire il seguente testo:

{
    "username": "username@hipay.com",
    "password": "ChangeMe"
}

Qui un esempio di risposta:

{
    "token_type": "Bearer",
    "expires_in": "3600",

   "access_token": "TOKEN_HERE",
}

Si possono quindi chiamare i seguenti endpoint e specificare il token ottenuto nella risposta precedente nelle intestazioni delle richieste.

Creare un export

Esistono diversi tipi di export. Per iniziare, effettuare una chiamata API POST all'URL: https://console.hipay.com/api/exports.

Nell'intestazione, inserire il token ottenuto in precedenza:

{
    "x-Authorization": "Bearer [YOUR TOKEN]",
    "Content-Type": "application/json"
}

Export semplice

In un export semplice, il file viene generato direttamente dopo la sua creazione. Di seguito un esempio di corpo:

{
"filePrefix": "MY_PREFIX",
"module": "transaction",
"columns": "{\"merchant_order_id\":{\"label\":\"Order ID\"},\"trxid\":{\"label\":\"Transaction ID\"}, \"captured_amount\":{\"label\":\"Captured amount\"}}",
"filters": "{\"captured_date_interval\":\"pd\", \"payment_means\": \"mastercard\"}",
"separator": "semicolon",
"recurrence": "once",
"receiveByEmail": false,
"config": "{“granularity”: “operation”}"
}

Qui, il parametro "config" è impostato per creare un export per operazione di pagamento con il seguente JSON:

“{“granularity”: “operation”}”.

È anche possibile creare un export per transazione impostando la granularity su "transaction":

“{“granularity”: “transaction”}”.

Export ricorrente

L'export può essere ricorrente. A seconda delle impostazioni, il file può essere creato automaticamente. Per un export ricorrente, utilizzare lo stesso URL per un POST API all'indirizzo https://console.hipay.com/api/exports.

Qui un esempio di un corpo che crea un export giornaliero della durata di 30 giorni:

{
"filePrefix": "MY_PREFIX",
"module": "transaction",
"columns": "{\"merchant_order_id\":{\"label\":\"Order ID\"},\"trxid\":{\"label\":\"Transaction ID\"}, \"captured_amount\":{\"label\":\"Captured amount\"}}",
"filters": "{\"captured_date_interval\":\"pd\", \"payment_means\": \"mastercard\"}",
"separator": "semicolon",
"recurrence": "daily",
"nbOccurrence": "30",
"receiveByEmail": true,
"config": "{“granularity”: “transaction”}"
}

Impostare un export ricorrente

Un export ricorrente deve contenere un filtro data predefinito. È possibile utilizzare gli intervalli di date predefiniti:

• pd: Past day
• cw: Current week
• pw: Past week
• cm: Current month
• pm: Past month
• cq: Current quarter
• pq: Past quarter
• cy: Current year
• yy: Last twelve months
• custom: Custom

Un "intervallo" basato sulla "created date" sarà scritto come segue:

{
…
 "filters": "{\"created_date_interval\":\"pd\"}",
…
}

Per creare un export ricorrente con un intervallo personalizzato, utilizzare la colonna "authorized_by_payment_means_date" come per l'altro filtro predefinito e definire un "_interval", una "_date_from" e una "_date_to":

{
  "authorized_by_payment_means_date_interval": "custom",
  "authorized_by_payment_means_date_from": "2019-01-01",
  "authorized_by_payment_means_date_to": "2019-06-15"
}

Le esportazioni ricorrenti possono essere configurate in diversi modi.

È possibile impostare una ricorrenza infinita non specificando «nbOccurrence» o «endRecurrenceDay».

È inoltre possibile scegliere se un export mensile (con o senza ricorrenza definita) sarà generato il primo o l'ultimo giorno del mese, impostando «recurrenceDay» con i valori «first_day» o «last_day». Per un export settimanale, impostare «recurrenceDay» con un valore compreso tra 1 e 7, a seconda del giorno della settimana in cui si desidera ricevere l'export.

Infine, per determinare il numero massimo di occorrenze, configurare i parametri «nbOccurrence» indicando il numero desiderato, oppure «endRecurrenceDay» con una data finale per la generazione di esportazioni nel formato YYYY-MM-DD.

Per esempio:

• Per una ricorrenza mensile della durata di sei mesi, impostare il parametro "recurrence" su "monthly" e il parametro "nbOccurrence" su 6.
• Per una ricorrenza settimanale che termina in una data definita, impostare il parametro "recurrence" su "weekly" e il parametro "endRecurrenceDay" sul 15 giugno 2023, cioè "2023-06-15". Impostare il parametro "recurrenceDay" su 3 per ricevere l'export ogni mercoledì.

I diversi parametri e valori possibili

Exemple de réponse

{
  "exportId": 1234,
  "dateCreated": "2020-01-01T11:00:00+01:00",
  "dateUpdated": null,
  "exportFiles": [
      {
          "fileId": 5801,
          "dateCreated": "2020-01-01T11:00:00+01:00",
          "filename": "MY_PREFIX_20230125-110006_91",
          "hash": "5813580648388153ec741b3816704b858b71253d494cd6a47c6d2782d5b75293a942a7d35b343b88c8b2c8fa19c8b3ad1ddf0a65f4f9a8658afe746e31960b1a",
          "status": "created",
          "nbItems": null
      }
  ],
  "filePrefix": "ALL_ACCOUNTS_CAPT",
  "emails": null,
  "module": "transaction",
  "status": "active",
  "columns": "{\"merchant_order_id\":{\"label\":\"Order ID\"},\"trxid\":{\"label\":\"Transaction ID\"}, \"captured_amount\":{\"label\":\"Captured amount\"}}",
  "filters": "{\"captured_date_interval\":\"pd\", \"payment_means\": \"mastercard\"}",
  "urlFilters": null,
  "separator": "semicolon",
  "recurrence": "once",
  "recurrenceDay": null,
  "nbOccurrence": 5,
  "endRecurrenceDay": null,
  "receiveByEmail": false,
  "user": "/api/users/123",
  "userId": 123,
  "config": "{“granularity”: “operation”}",
  "error": null
}

Errori possibili

Quando si crea un export, possono verificarsi diversi errori, come ad esempio:

• > “The recurrence “daily” must be used with a predefined date interval”
  Un export ricorrente (recurrence != once) deve avere un filtro data predefinito.
• “The recurrence “daily” must be used with a “receiveByEmail” field to true.”
  Un export ricorrente (recurrence != once) deve avere il campo “receiveByEmail” impostato su “true”.
• > “At least one similar export is already in progress”
  Lo stesso export è già stato avviato, ma non è ancora terminato.
• > “xxxxx is not a valid slug”
  Lo slug del nome della colonna (ID) non corrisponde a una colonna esistente.
• > “xxxxx contains illegal characters”
  L'etichetta di una colonna non deve contenere caratteri speciali.
• > “xxxxx is not a valid JSON”
  Il valore inviato non è un JSON (campo: filters, columns).
• > “filePrefix incorrect”
  Il “file prefix” deve contenere un massimo di 30 caratteri e rispettare la seguente regex: /^([\w]|[à-ú]|[À-Ú]|[-_\[\]\.]){1,30}$/
  

Recupero del file di export

Se si tratta di un export ricorrente, chiama l'endpoint GET/api/exports/[ID export]/files.

(ID export ottenuto nella risposta durante la creazione) per ottenere un elenco di file generati per l'export specificato. Ottieni l'ID dell'exportFile che ti interessa, poi chiama l'endpoint GET /api/export-files/[ID del file]?hash=[hash del file] con le seguenti intestazioni:

{
    "x-Authorization": "Bearer [VOTRE TOKEN]",
    "Content-Type": "application/zip"
}

Esempio di chiamata CURL che consente di recuperare il contenuto del file:

curl -X GET "https://console.hipay.com/api/export-files/1234?hash=123" -H "accept: application/zip" -H "X-Authorization: Bearer [MON TOKEN]" --output [DOSSIER DE DESTINATION]

Se desideri recuperare il file via e-mail, utilizza il seguente URL, sempre in GET: /api/export-files/[ID del file]/email?hash=[hash del file].

Attenzione: i file sono disponibili per il download:

• per un giorno per le esportazioni semplici e le esportazioni ricorrenti giornaliere;
• per sette giorni per le esportazioni ricorrenti non giornaliere.

Generare di nuovo un export

Una volta al giorno, è possibile generare nuovamente un export alle stesse condizioni della prima volta.

Per farlo bisogna chiamare l'endpoint GET /api/export-files/[ID dell’export]/regenerate?hash=[hash del file] con le seguenti intestazioni:

{
    "x-Authorization": "Bearer [VOTRE TOKEN]",
    "Content-Type": "application/zip"
}

Esempio di chiamata CURL:

curl -X GET "https://console.hipay.com/api/export-files/1234/regenerate?hash=123" -H "accept: application/zip" -H "X-Authorization: Bearer [MON TOKEN]" --output [DOSSIER DE DESTINATION]

Compilare il parametro «send_by_email» per ricevere l'export via e-mail.

 Articoli associati: 

• Export semplice
• Lista degli export ricorrenti