Integrációt segítő könyvtár (v2)

Az Utánvét Ellenőr API-jához való könnyebb csatlakozás érdekében elérhető az utanvet-ellenor/client-php nevű, integrációt segítő PHP könyvtár.

Telepítés

Legegyszerűbben Composer-rel telepíthető:

composer require utanvet-ellenor/client-php

Használat

Vásárló megbízhatóságának lekérdezése API-n keresztül

Lekérés csak e-mail alapján:

<?php 
  use UtanvetEllenor/Client;

  $client = new Client('publicApiKey', 'privateApiKey');
  $client->email = '[email protected]';
  $client->threshold = 0.8;

  $response = $client->sendRequest();

Lekérés több adat alapján:

<?php 
  use UtanvetEllenor/Client;

  $client = new Client('publicApiKey', 'privateApiKey');
  $client->email = '[email protected]';
  $client->countryCode = 'HU';
  $client->postalCode = '8640';
  $client->phoneNumber = '+36209238883';
  $client->addressLine = 'Szigligeti utca 10.';
  $client->threshold = 0.8;

  $response = $client->sendRequest();

Az API válasza erre egy JSON string lesz, melyet a client->sendRequest() egy object-ként ad vissza:

{
    "status": 200,
    "result": {
        "good": 3,
        "bad": 5,
        "reputation": -0.25,
        "blocked": true,
        "reason": "Total rate did not meet the minimum threshold set."
    }
}

Kötelező paraméterek

Alap ellenőrzés esetén az email és a threshold, kiterjesztett ellenőrzés esetén minden paraméter használata kötelező.

Eredmények felhasználása

Az utánvét elrejtéséhez/a vásárló szűréséhez a válasz blocked adattagjának értékét javasolt használni.

Eredmények megjelenítése

Ha ezeket az értékeket valamilyen felhasználói felületen (pl. admin felületen) meg szeretnéd jeleníteni, használd a reputation és/vagy good és bad értékek számszerű értékét. Próbáld elkerülni, hogy valamilyen leírással elfedd ezeket az értékeket, mert az félrevezetheti a felhasználókat.

Példák az API válaszok felhasználói felületen való megjelenítésére

Jó:

• 3 sikeres, 2 sikertelen (kézbesítés), reputáció: 0.2
• Sikeres kézbesítés: 60%
• A válasz reason fordításának megjelenítése (pl.: A vásárló reputációja nem érte el a beállított küszöbértéket.)

Rossz:

• A rendelés teljesítése nem javasolt (Miért? Nincs egyértelmű indoklás.)
• Túl sok át nem vett rendelés. (Mi számít túl soknak?)
• Rossz megbízhatósági mutató. (Mi számít "rossznak"?)

Javasolt fordítások az API által adott reason értékhez

Rendelés kimenetel (visszajelzés) küldése az API-nak:

A visszajelzések küldésének ideális ideje a rendelés állapotának megváltozása.

<?php
  use UtanvetEllenor/Client;

  $client = new Client('publicApiKey', 'privateApiKey');
  $client->email = '[email protected]';
  $client->outcome = 1;
  $client->orderId = 'order-123456';
  $client->countryCode = 'HU';
  $client->postalCode = '8640';
  $client->phoneNumber = '+36209238883';
  $client->addressLine = 'Szigligeti utca 10.';

  $response = $client->sendSignal();

Adatcsomag tagjainak részletei:

Teszt környezet

A Client példány sandbox tulajdonságának true-ra állításával a könyvtár a teszt környezetet fogja használni a kérés végrehajtása során.

<?php 
  use UtanvetEllenor/Client;

  $client = new Client('publicApiKey', 'privateApiKey');
  $client->email = '[email protected]';
  $client->threshold = 0.8;
  $client->sandbox = true;

  $response = $client->sendRequest();

A teszt környezet API-ja az élessel megegyezően viselkedik, azonban az általa szolgáltatott adatok véletlenszerűen – semmiképpen se használd éles környezetben!