Export automatique via l’API Console – Centre de support HiPay

L’API Console est accessible sur vos environnements de test (Stage) et de production. Avec elle, vous pouvez automatiquement exporter les données affichées dans les modules Transactions et Rapport financier de HiPay Console. Vous trouverez dans cet article les informations nécessaires pour vos exports uniques et récurrents effectués via notre API Console.

Pour consulter la documentation technique des endpoints de l’API Console, rendez-vous sur les URL suivantes :

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

Vous pourrez y tester tous les endpoints décrits dans ce document.

Génération d’une clé temporaire

La première étape consiste à générer un token (clé temporaire) d’accès pour vous identifier. Pour cela, générez un appel API POST à l’URL :

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

En body, entrez le contenu suivant :

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

Voici un exemple de réponse :

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

    "access_token": "ICI_LE_TOKEN",
}

Vous pourrez ensuite appeler les endpoints suivants en précisant le token récupéré ci-dessus dans les headers de vos requêtes.

Créer un export

Vous pouvez créer plusieurs types d’exports. Pour commencer, générez un appel API POST à l’URL https://console.hipay.com/api/exports.

En header, insérez le token obtenu plus tôt :

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

Export simple

Lors d’un export simple, le fichier sera généré directement après sa création. Voici un exemple de body :

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

Ici, le paramètre « config » est défini pour effectuer un export par opération de paiement avec le JSON suivant : “{“granularity”: “operation”}”.

Vous pouvez également créer un export par transaction en spécifiant la granularité à « transaction » : “{“granularity”: “transaction”}”.

Export récurrent

Votre export peut être récurrent. Suivant le paramétrage, le fichier sera créé automatiquement. Pour cela, utilisez la même URL en API POST à https://console.hipay.com/api/exports.

Voici un exemple de body permettant de créer un export quotidien pendant 30 jours :

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

Paramétrage d’export récurrent

Lorsque vous créez un export récurrent, celui-ci doit obligatoirement contenir un filtre de date prédéfini. Vous pouvez utiliser les intervalles de dates prédéfinies :

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 « interval » basé sur la « created date » s’écrira de cette façon :

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

PENSEZ À AJOUTER « _interval »

Pour créer un export récurrent sur un « interval » personnalisé (custom), basez-vous sur la colonne « authorized_by_payment_means_date » comme pour l’autre filtre prédéfini et définissez un « _interval », une « _date_from » et une « _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"
}

Les exports récurrents peuvent se configurer de plusieurs façons.

Il est possible de paramétrer une récurrence infinie en ne spécifiant pas de « nbOccurrence » ou de « endRecurrenceDay ».

Vous pouvez également choisir si un export mensuel (avec occurrence définie ou non) sera généré au premier ou au dernier jour du mois en paramétrant « recurrenceDay » avec les valeurs « first_day » ou « last_day ». Pour un export hebdomadaire, paramétrez « recurrenceDay » avec une valeur de 1 à 7 selon le jour de la semaine durant lequel vous souhaitez recevoir l’export.

Enfin, pour déterminer un nombre d’occurrences maximum, configurez les paramètres « nbOccurrence » en indiquant le nombre désiré, ou « endRecurrenceDay » avec une date de fin de génération des exports au format YYYY-MM-DD.

Par exemple :

Pour une récurrence mensuelle durant six mois, définissez le paramètre « recurrence » à « monthly » et le paramètre « nbOccurrence » à 6.
Pour une récurrence hebdomadaire qui doit se terminer à une date définie, définissez le paramètre « recurrence » à « weekly » et le paramètre « endRecurrenceDay », par exemple, au 15 juin 2023, donc à « 2023-06-15 ». Définissez le paramètre « recurrenceDay » à 3 afin de recevoir l’export tous les mercredis.

Les différents paramètres et valeurs possibles

Paramètre	Description
filePrefix	Préfixe du nom du fichier généré (30 caractères maximum)
module	Valeurs possibles : transaction / financial report / account
status	Valeur possible : active
columns	Objet JSON avec en clé les ID des colonnes (cf https://console.hipay.com/api/docs => POST /api/exports, puis model)
filters	Objet JSON avec en clé les IDs des colonnes (cf https://console.hipay.com/api/docs => POST /api/exports, puis model)
separator	Séparateur CSV Valeurs possibles : semicolon / comma
recurrence	Valeurs possibles : once / daily / weekly / monthly / monthly_day / annually
recurrenceDay	Détermine le jour de la semaine de la récurrence Valeurs possibles : 1 / 2 / 3 / 4 / 5 / 6 / 7 / first_day / last_day
receiveByEmail	Détermine si le fichier d’export sera envoyé par e-mail à la personne qui l’a généré Valeurs possibles : true / false
config	Objet JSON. Options possibles : granularity (valeurs possibles : transaction / operation), uniquement si module = transaction. Permet d’exporter une ligne par transaction ou par opération de paiement (capture, refund, chargeback, chargeback_refund)
nbOccurrence	Uniquement si occurrence != once Détermine le nombre d’occurrences après lequel l’export ne sera plus généré.
endRecurrenceDay	Uniquement si occurrence != once Date après laquelle l’export ne sera plus généré (YYYY-MM-DD)

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
}

Erreurs possibles

Lors de la création d’un export, plusieurs erreurs peuvent survenir, notamment :

> « The recurrence “daily” must be used with a predefined date interval »
Un export récurrent (recurrence != once) doit contenir un filtre de date prédéfini.
> « The recurrence “daily” must be used with a “receiveByEmail” field to true. »
Un export récurrent (recurrence != once) doit avoir le champ « receiveByEmail » à true.
> « At least one similar export is already in progress »
Le même export a déjà été lancé, mais n’est pas terminé.
> « xxxxx is not a valid slug »
Le slug du nom de la colonne (ID) ne correspond pas à une colonne existante.
> « xxxxx contains illegal characters »
Le nom d’une colonne ne doit pas contenir de caractères spéciaux.
> « xxxxx is not a valid JSON »
La valeur envoyée n’est pas un JSON (champs : filters, columns).
> « filePrefix incorrect »
Le « file prefix » doit contenir 30 caractères maximum et respecter la regex suivante : /^([\w]|[à-ú]|[À-Ú]|[-_\[\]\.]){1,30}$/

Récupération du fichier d’export

S’il s’agit d’un export récurrent, appelez l’endpoint GET/api/exports/[ID de l’export]/files.

(ID de l’export obtenu dans la réponse lors de la création) pour obtenir la liste des fichiers générés pour l’export spécifié. Récupérer l’ID de l’exportFile qui vous intéresse, puis appelez l’endpoint GET /api/export-files/[ID du fichier]?hash=[hash du fichier] avec les headers suivants :

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

Exemple d’appel CURL qui vous permet de récupérer le contenu du fichier :

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]

Si vous souhaitez récupérer le fichier par e-mail, utilisez l’URL suivante, toujours en GET : /api/export-files/[ID du fichier]/email?hash=[hash du fichier].

Attention : Les fichiers sont disponibles au téléchargement :

pendant un jour pour les exports simples et exports récurrents journaliers ;
pendant sept jours pour les exports récurrents non journaliers.

Générer de nouveau un export

Une fois par jour, vous pouvez générer de nouveau un export dans les mêmes conditions que la première fois.

Pour ce faire, appelez l’endpoint GET /api/export-files/[ID de l’export]/regenerate?hash=[hash du fichier] avec les headers suivants :

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

Exemple d’appel 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]

Renseignez le paramètre « send_by_email » pour recevoir l’export par e-mail.

Articles associés :