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:
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
Parametro | Descrizione |
filePrefix | Prefisso del nome del file generato (massimo 30 caratteri) |
module | Valori possibili: transazione / reportistica finanziaria / account |
status | Valore possibile: attivo |
columns |
Oggetto JSON con gli ID delle colonne come chiave (vedi https://console.hipay.com/api/docs => POST /api/exports, poi model) |
filters | Oggetto JSON con gli ID delle colonne come chiave (vedi https://console.hipay.com/api/docs => POST /api/exports, poi model) |
separator |
Separatore CSV |
recurrence | Valori possibili: once / daily / weekly / monthly / monthly_day / annually |
recurrenceDay |
Determina il giorno della settimana della ricorrenza Valori possibili: 1 / 2 / 3 / 4 / 5 / 6 / 7 / first_day / last_day |
receiveByEmail |
Determina se il file di export verrà inviato via e-mail alla persona che lo ha generato. Valori possibili: true / false |
config |
Oggetto JSON. Opzioni possibili:
|
nbOccurrence |
Solo se occurrence != once Determina il numero di occorrenze dopo le quali l'export non verrà più generato. |
endRecurrenceDay |
Solo se occurrence != once |
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:
Commenti
0 commenti
Questo articolo è chiuso ai commenti.