Reporting

Reporting permite descărcarea rapoartelor de tranzacții prin API-ul Reporting.

  • Rapoartele prezintă detalii ale tranzacțiilor create sau actualizate într-o anumită perioadă de timp. Puteți specifica, câmpurile care vor forma raportul și antetul coloanelor din raportul rezultat.
  • Puteți descărca și stoca datele de tranzacții în format CSV, în vederea analizei. De exemplu, datele pot fi analizate cu ajutorul unei aplicații de business intelligence sau al unei aplicații de calcul tabelar.

Puteți obține rapoarte referitoare la comenzi și tranzacții în trei moduri diferite:

Cerințe preliminare

  • Profilul dvs. de comerciant de pe eGenius Platform trebuie să aibă activat serviciul Reporting.
  • Pentru a accesa API-ul Reporting, trebuie să generați o parolă. Consultați Generarea parolelor pentru Reporting.

Date de tranzacții într-un Raport

Reporting înregistrează toate evenimentele asociate cu o tranzacție. Când solicitați un raport de tranzacție, toate evenimentele asociate cu o anumită tranzacție dintr-o perioadă specificată de dvs. sunt introduse în raport. Acestea includ și orice evenimente de actualizare asociate cu tranzacția. Aveți, de asemenea, flexibilitatea de a filtra datele conform necesităților activității dvs.

Imaginea de mai jos ilustrează mecanismul de raportare. Un raport de tranzacții solicitat pentru perioada „1-Feb-2012” până la „29-Feb-2012” returnează Evenimentul 1 și Evenimentul 2. Ambele evenimente sunt asociate aceleiași tranzacții. Evenimentul 3, deși este, de asemenea, asociat tranzacției, a avut loc după finalul perioadei specificate, și nu va fi inclus în raport.

Date de raportare tranzacție

Descărcare rapoarte utilizând integrarea API Reporting

Crearea solicitării Reporting

Reporting necesită o solicitare http GET, precum cea prezentată mai jos.

GET /history/version/1/merchant/<merchant>/transaction?timeOfRecord.start=<starttime>&timeOfRecord.end=<endtime>&columns=<columns>&columnHeaders=<columnheaders>

Unde:

  • <merchant> este ID-ul dvs. de comerciant.
  • <starttime> și <endtime> indică intervalul de timp acoperit.
  • <columns> sunt câmpurile care vor fi incluse în raport, separate prin virgule. Numele fac diferența între majuscule și literele mici.
  • <columnheaders> este lista anteturilor coloanelor care vor fi incluse în raport, separate prin virgule.
Ore

Ora de început este incluzivă (ora tranzacției >= ora de început) și ora de finalizare este excluzivă (ora tranzacției < ora de finalizare).

Ora de început și ora de finalizare sunt transmise ca parametri în format ISO 8601: yyyy-mm-ddThh:mm:ssZ, unde Z indică faptul că ora este UTC. Dacă ora nu este UTC, trebuie specificată o diferență de fus orar ca +/-hh[:mm], de exemplu, 12:31+10 (UTC + 10 ore), sau 12:31:30-06:30 (UTC minus 6 ore 30 minute). Valorile orei care apar în raport (dacă acestea există) sunt UTC.

Primul moment al unei zile apare la ora 00:00. Ora de finalizare pentru un raport (timeOfRecord.end) este excluzivă, deci pentru a raporta până la finalul unei zile, utilizați ca oră de finalizare primul moment al zilei următoare (00:00). La fel, dacă doriți date pentru o oră, specificați un interval de timp între începutul unei ore și începutul următoarei ore.

Fus orar și format oră

În cadrul solicitării puteți specifica doi parametri opționali:

  • csv.timeZone=<+ or ->HH:MM

    Dacă acesta este specificat, ora înregistrărilor este redată în datele de ieșire conform fusului orar indicat și fără a fi precizat fusul orar. Rețineți că semnele + și - trebuie să fie înlocuite de codurile UTF-8. De exemplu, dacă setați csv.timeZone=%2B10:00 (respectiv, +10.00), orele evenimentelor apar în raport ca ore UTC+10.

    Dacă acesta este omis, datele de ieșire vor avea ca oră UTC și „Z” adăugat pentru a indica fusul orar UTC.

  • csv.timeFormat=<iso8601 or iso8601-T>

    Dacă este specificat ca iso8601-T, datele de ieșire utilizează un caracter spațiu în loc de T ca separator pentru dată-oră.

    Dacă este omis, sau specificat ca iso8601, separatorul dată-oră este „T”.

Ora de vară

Vă recomandăm să ignorați ora de vară pentru descărcările de rapoarte. Totuși, dacă doriți ca descărcările de rapoarte să aibă intervale de timp conform orei de vară, trebuie să realizați aceasta prin:

  • modificarea fusului orar pe care îl specificați
  • ținând cont de faptul că veți pierde o oră de înregistrări la începutul orei de vară și veți primi o oră de înregistrări duble la finalul orei de vară.

Pentru a evita complicațiile legate de ora de vară, utilizați fusul orar UTC pentru a specifica intervalul de timp.

Coloane

Parametrul coloane specifică, câmpurile care apar în raport. Câmpurile care pot fi specificate sunt descrise în operațiunea Retrieve Transaction pentru versiunea de APIpe care o utilizați. Rețineți că versiunea API raportare este diferită de versiunea API. Câmpurile disponibile pentru a fi selectate, utilizând ultima versiune a API pot fi găsite aici.

API raportare acceptă doar câmpurile disponibile în API versiunea 14 sau o versiune mai recentă. Nu puteți recupera, descărca sau stoca datele din câmpurile vectoriale; de exemplu, order.item[n].detail.

Dacă procesați tranzacții utilizând mai multe versiuni API, puteți specifica câmpuri comune versiunilor utilizate, sau câmpuri unice unei anumite versiuni. Datele care nu sunt prezente pentru o anumită înregistrare vor apărea ca valoare goală în fișierul CSV. Totuși, fiecare nume de câmp trebuie să fie valid pentru cel puțin o versiune API.

Antet coloane

Dacă furnizați propriile dvs. anteturi pentru coloane în parametrul columnHeaders, lista numelor corespunde listei câmpurilor din lista „columns”. Atât &columnHeaders cât și &columns trebuie să aibă același număr de elemente.

Dacă în solicitare nu sunt incluse anteturile (este omis parametrul &columnHeaders), anteturile coloanelor vor fi numele câmpurilor. Dacă este furnizat un parametru antet fără nicio valoare (&columnHeaders=) fișierul rezultat nu va conține nicio linie de antet.

Trimiterea solicitării Reporting

După ce ați stabilit câmpurile pe care doriți să le includeți în solicitare, le puteți transmite către eGenius Platform. Solicitarea este trimisă către gateway-ul de plăți printr-o solicitare HTTPS GET. eGenius Platform presupune o codificare UTF-8 a solicitării URL și acceptă toate caracterele utile Unicode. Trebuie să respectați regulile de codificare pentru adrese URL (consultați standardul RFC 3986).

Anteturi HTTP

Implicit, tipul conținutului descărcat este CSV cu codificare ISO8859-1. Puteți să specificați oricare dintre următoarele valori utilizând tipul mime corespunzător în antetul Content-Type:

  • ASCII
  • UTF-8
  • Big5
  • GB18030
  • Shift-JIS
  • KOI8-R
  • EUC-JP
  • EUC-KR
  • ISO8859-1

De exemplu, pentru a descărca în UTF-8, specificați "Accept-Charset : UTF-8".

Autentificarea solicitărilor

ID comerciant este în adresa URL. Autentificarea prin parolă este realizată prin autentificare de bază HTTP. Parola este parola Reporting pentru profilul comerciantului, configurată în Administrare cont comerciant (notă: aceasta este diferită de parola API). Consultați Generarea parolelor pentru Reporting.

Numele de utilizator pentru autentificarea de bază este „merchant.default”.

Exemplu de script bash

Acest exemplu de script Bash utilizează curl pentru a descărca rapoarte (consultați http://curl.haxx.se/). Curl necesită ca parola să fie setată în fișierul .netrc. Acesta trebuie creat în directorul de bază al utilizatorului. Trebuie să adăugați următoarea linie în fișierul .netrc; <password> trebuie înlocuită cu parola dvs.:

machine egenius.unicredit.ro login merchant.default password <password>		
	  

Exemplu Windows PowerShell

Parola api este salvată în format criptat în fișierul reportingPassword în folderul dvs. de bază ($HOME). Pentru a genera fișierul reportingPassword, rulați scriptul setpassword.ps1 inclus în pachetul descărcat.

Pentru mai multe detalii referitoare la setarea acreditărilor, faceți clic aici.

Dacă nu trimiteți o parolă cu solicitarea sau scriptul dvs. de descărcare, vi se va solicita (dacă clientul dvs. https/browserul acceptă această opțiune) să furnizați o parolă în momentul realizării apelului.

Descărcare scripturi exemplu

Temporizarea solicitărilor dvs.

Pentru a automatiza descărcările, sistemul dvs. poate emite o serie de apeluri de descărcare, utilizând un limbaj de scripturi declanșat de un proces de temporizare (de exemplu, cron în Linux sau Scheduled Task în Windows) . Produsele Managed File Transfer dispun, de asemenea, de această funcție. 

Puteți să alegeți cât de frecvent descărcați datele. Un interval de zece minute ar menține datele dvs. la un nivel aproape de timp real, dar un interval zilnic ar putea fi mai eficient. Descărcările ar trebui să fie destul de frecvente încât să împiedice ca fișierele să devină prea mari sau neactuale – ambele probleme sporesc importanța unei descărcări eșuate și necesitatea remedierii acesteia.

În mod ideal, setați ora de început (timeOfRecord.start) al fiecărui apel ca fiind ora de finalizare (timeOfRecord.end) a ultimului apel care a avut succes. Aceasta garantează faptul că obțineți toate înregistrările exact o dată. Utilizați codul de stare HTTP pentru a verifica dacă ultimul apel a eșuat. În caz de eșec, scriptul ar trebui să aștepte câteva minute și să încerce din nou. eGenius Platform prezintă câteva minute de întârziere între momentul când procesează o tranzacție și momentul când aceasta este disponibilă pentru descărcare. Dacă încercați să descărcați înregistrări din acea perioadă, eGenius Platform respinge solicitarea cu un răspuns DATA_AVAILABLE_AFTER și ultima oră de finalizare permisă.

Scripturi exemplu

Pachetul de scripturi exemplu include următoarele scripturi:

  • basicreportexample.sh / basicreportexample.ps1 - Un script simplu configurat prin parametri din linia de comandă; acesta descarcă un raport pentru intervalul de timp precizat.
  • downloadreport.sh / downloadreport.ps1 - Un script conceput pentru a rula nesupravegheat pe baza unui temporizator; acesta descarcă orice evenimente noi de tranzacție apărute din momentul ultimei sale rulări.
  • setpassword.ps1 - Un script Windows PowerShell care solicită o parolă și o criptează în fișierul reportingPassword. Acesta utilizează o caracteristică de criptare disponibilă doar în Windows.

În cazul exemplului de script Bash, scriptul presupune că ați configurat parola dvs. Reporting în fișierul .netrc.

Descărcare scripturi exemplu

Procesarea răspunsului Reporting
Succes

Ca răspuns la o solicitare validă. autentificată GET, Reporting furnizează un fișier CSV care conține toate înregistrările tranzacțiilor API, filtrate pe baza tuturor câmpurilor specificate de dvs. în solicitare, care au fost create sau actualizate în intervalul de timp definit de datele de început și finalizare. Înregistrările sunt ordonate crescător de la cea mai veche tranzacție până la cea mai recentă.

Numerele de carduri sunt mascate în raport.

Reporting generează o înregistrare de tranzacție atunci când starea tranzacției se modifică. De exemplu, dacă o tranzacție de Autorizare este evaluată din punctul de vedere al riscului și apoi este decontată, raportul de tranzacție va prezenta înregistrări pentru toate cele trei evenimente — Autorizare, Răspuns de risc, Răspuns de decontare.

Mai jos este prezentat un exemplu de raport de tranzacție:

time,order id,transaction id,card number,card expiry month,card expiry year,amount,currency,type,acquirer,acquirerCode
2012-05-14T06:23:10.859Z,11336976611,1,345678xxxxx4564,5,13,60.00,USD,AUTHORIZATION,AMEXGWS,000
2012-05-16T01:25:19.694Z,11337131511,1,345678xxxxx4564,5,13,36.00,USD,AUTHORIZATION,AMEXGWS,000
2012-05-16T06:33:31.709Z,11337150032,1,345678xxxxx4564,5,13,36.00,USD,AUTHORIZATION,AMEXGWS,000
2012-05-16T22:15:53.276Z,11337206569,1,345678xxxxx4564,5,13,75.00,USD,AUTHORIZATION,AMEXGWS,000
2012-05-17T00:22:14.516Z,11337214154,1,345678xxxxx4564,5,13,72.00,USD,AUTHORIZATION,AMEXGWS,000
2012-05-17T01:41:17.447Z,11337218888,1,345678xxxxx4564,5,13,60.00,USD,AUTHORIZATION,AMEXGWS,000
2012-05-17T01:41:43.533Z,11337218921,1,345678xxxxx4564,5,13,78.00,USD,AUTHORIZATION,AMEXGWS,000
2012-05-21T11:15:00.093Z,11337598863,1,345678xxxxx4564,5,13,39.00,USD,AUTHORIZATION,AMEXGWS,000
2012-05-21T12:29:52.954Z,11337603409,1,345678xxxxx4564,5,13,39.00,USD,AUTHORIZATION,AMEXGWS,000
2012-05-22T01:51:09.996Z,11337651486,1,345678xxxxx4564,5,13,36.00,USD,AUTHORIZATION,AMEXGWS,000
Eșuat

Dacă solicitarea este nevalidă sau dacă ID comerciant și parola trimise de dvs. sunt nevalide sau nu sunt autorizate pentru a accesa API raportare, este returnat un mesaj de eroare cu detalii.

Dacă trimiteți două solicitări, și Data/Ora de finalizare a primei solicitări este Data/Ora de început a celei de a doua solicitări, nu vor exista înregistrări de tranzacții care să lipsească sau să fie dublate. Dacă nu există înregistrări până la Data/Ora de finalizare, este returnat un mesaj de eroare, care indică ultima dată/oră de finalizare posibilă.

Dacă pentru perioada de raportare specificată de dvs. nu există înregistrări, va fi returnat un fișier CSV cu antet dar fără nicio linie de înregistrare.

Descărcare rapoarte utilizând un browser web

Puteți solicita direct rapoarte utilizând un browser web. Rapoartele pot fi configurate în adresa URL furnizată în solicitare.

Configurarea adresei URL pentru Raportare

Creați o adresă URL pe baza șablonului de mai jos:

https://YOUR_GATEWAY_SERVER/history/version/1/merchant/
YOUR_MERCHANT_ID/
transaction?REPORT_CONTENTS_AND_FORMAT

REPORT_CONTENTS_AND_FORMAT example: columns=merchant,order.id,transaction.id, transaction.amount,transaction.amount& columnHeaders=Merchant,OrderID,TransactionID,Currency,Amount
&timeOfRecord.end=2015-01-24T18:43:54
&timeOfRecord.start=2015-01-12T18:38:40

Această solicitare returnează un raport care conține comerciant, ID comandă, ID tranzacție, monedă tranzacție și sumă tranzacție pentru tranzacții realizate între 15 Ian 2015 18:43:54h și 24 Ian 2015 18:38:40h. Anteturile coloanelor vor afișa "Merchant", "OrderID", "TransactionID", "Currency" și "Amount".

Pentru mai multe detalii referitoare la opțiunile de raportare disponibile, consultați Referința API Retrieve Transaction.

Lipiți adresa URL în browserul dvs. Vi se va solicita să introduceți parola. Parola este parola Reporting pentru profilul comerciantului, configurată în Administrare cont comerciant (notă: aceasta este diferită de parola API). Consultați Generarea parolelor pentru Reporting. Pentru username (nume utilizator), introduceți merchant.default.

Generare parolă pentru Reporting

Reporting necesită o solicitare autentificată prin parolă către eGenius Platform. Puteți genera parola în Administrare cont comerciant.

Operatorul trebuie să aibă dreptul "Poate configura setări de integrare pentru API de raportare" pentru a genera parola.
  1. Navigați la Administrare > Reporting Setări de integrare API > Editare.
  2. Apăsați Generare nou.
  3. Selectați caseta Activare acces la API Reporting integrare pe bază de parolă.
  4. Copiați parola în clipboard și/sau un fișier text. Veți avea nevoie de aceasta mai târziu.
  5. Apăsați Trimitere.

Parola generată de sistem este o valoare de 16 octeți, generată aleator, care este codificată ca șir de caractere hexazecimale. Deși această parolă are o lungime și o calitate suficiente pentru a rezista unui atac de tip forță brută, ar trebui securizată în același mod în care sunt securizate parolele de utilizator și alte date sensibile.

Trebuie să aveți întotdeauna cel puțin o parolă generată și activată, dar puteți să aveți configurate până la două parole. Pentru securitate, ar trebui să modificați periodic parola. Pentru a realiza aceasta, generați o parolă nouă și actualizați scriptul de descărcare pentru rapoarte. În decursul acestei modificări ambele parole vor fi funcționale.

Copyright © 2021 UniCredit Bank