Arendajatele

Kiire algus.

Üheksa sammu tühjast poest hinnatud kassani. Volitused tulevad esimesena, sest iga järgmine samm allkirjastatakse nendega. Lepingu, mida need sammud teostavad, esitab integratsioonikeskus.

Joonis 1

Kaks seadistussammu, siis kutse, mis jookseb iga tellimuse peal, ja vastus, mille ta tagastab.

Volitused

Hankige kolm saladust.

Volitused väljastatakse poe kaupa partnerportaalist: key ID, API key secret päringu allkirjastamiseks, ja network salt identifikaatorite räsimiseks. Registreerumine on koht, kus võetakse vastu Teenusetingimused ja Andmetöötlusleping, ja kolm väärtust väljastatakse siis, kui taotlus on üle vaadatud ja tellimus on aktiivne. Mida iga väärtus teeb ja milleks teda kasutada ei tohi, on kirjas integratsioonikeskuses.

Pange kõik kolm oma serveri keskkonda. Ükski neist ei tohi kunagi jõuda brauserisse, ehitusartefakti ega kliendipoolsesse kimpu.

HEATRAIL_API_BASE=https://api.heatrail.eu
HEATRAIL_KEY_ID=hk_9f4c1e08b7a2d631
HEATRAIL_API_SECRET=…64 hex characters…
HEATRAIL_NETWORK_SALT=…the network-wide hashing salt…

Ülalolev baasaadress on produktsiooni host. Lugege ta seadistusest, ärge kirjutage teda koodi sisse: see on üks väärtus, mida muidu peaks igas failis korraga muutma.

Paigaldus

Võtke SDK, või jätke ta vahele.

WooCommerce peal lõpetage siin lugemine ja minge lisa lehele. Lisa sisaldab SDK-d ja teeb kogu selle lehe teie eest ära.

Kohandatud PHP kassas kasutage SDK-d. Tal ei ole Composer sõltuvusi, ta vajab ainult ext-curl ja ext-json, ja jookseb PHP 7.3 kuni 8.5 peal. Pakkige meie saadetud arhiiv lahti ja registreerige talle PSR-4 autolaadur:

spl_autoload_register(function (string $class): void {
    $prefix = 'Heatrail\\Sdk\\';

    if (strncmp($class, $prefix, strlen($prefix)) !== 0) {
        return;
    }

    $relative = substr($class, strlen($prefix));
    $file = __DIR__ . '/vendor-sdk/' . str_replace('\\', '/', $relative) . '.php';

    if (is_file($file)) {
        require $file;
    }
});

Igas teises keeles kutsute te otse REST API-t. Siis kuuluvad allkirjastamine, ajalimiit ja fail-open käitumine teile, ja leping integratsioonikeskuses on see, mida teie klient peab teostama. Lugege ta läbi enne, kui kliendi kirjutate.

Tõendus

Tõestage, et volitused töötavad, enne kui kassat puudutate.

GET /v1/health allkirjastatakse nagu iga teine päring, seega õnnestunud ringkäik tõestab, et teie key ID, saladus ja kell on kõik õiged. Tehke see esimesena. Katkine seadistus, mis siin välja tuleb, maksab minuti, ja seesama seadistus kassas avastatuna maksab päeva vaikselt degradeerunud kontrolle.

<?php

use Heatrail\Sdk\HeatrailClient;

$client = HeatrailClient::forShop(
    getenv('HEATRAIL_KEY_ID'),
    getenv('HEATRAIL_API_SECRET'),
    getenv('HEATRAIL_API_BASE'),
    ['network_salt' => getenv('HEATRAIL_NETWORK_SALT')]
);

var_dump($client->health());   // ['status' => 'up']

['status' => 'degraded'] tähendab, et kas teenus on degradeerunud või teie päringut ei võetud vastu. Health ei tagasta teadlikult kunagi 401, et teda ei saaks kasutada võtme kehtivuse testimiseks. Kui te saate siin degraded, kontrollige key ID-d, saladust, ja et teie serveri kell on tegelikust ajast viie minuti sees.

Räsi

Räsige identifikaatorid oma serveri sees.

hashEmail() ja hashPhone() normaliseerivad väärtuse ja rakendavad esimese astme HMAC-i teie võrgusoolaga. Nad tagastavad null, kui kasutatavat väärtust ei ole, ja null tähendab jäta väli ära. Ärge saatke tühja stringi. Ärge räsige varuväärtust. Tühja räsi reegel ütleb, mida jagatud näidise räsi võrguga teeks.

$payload = ['order_ref' => 'ord-10241'];

$emailHash = $client->hashEmail($order->billingEmail());

if ($emailHash !== null) {
    $payload['email_h'] = $emailHash;
}

// The country is your shop's base country, ISO 3166-1 alpha-2.
$phoneHash = $client->hashPhone($order->billingPhone(), 'EE');

if ($phoneHash !== null) {
    $payload['phone_h'] = $phoneHash;
}

Sõltuvusteta SDK normaliseerib Eesti numbreid. Number, mida ta parsida ei suuda, tagastab null ja väli jäetakse ära, mitte ei arvata.

Kontroll

Üks kutse, seal kus tellimus luuakse.

Lisage kliendi IP, mida teie server nägi, see on nõutav, ja jämedakoeline tellimuse kontekst. Siis kutsuge check() deterministliku idempotentsusvõtmega, et sama tellimuse kordus ei saaks kunagi kaks korda loetud.

$payload['ip'] = $order->customerIp();          // required
$payload['context'] = [
    'product_risk_class' => 'physical',        // physical | digital | gift_card
    'qty'                => 3,
    'amount_bucket'      => '100-250',
    'account_age_class'  => 'existing',        // new | existing
];

// Deterministic per order: same order, same key, on every retry.
$idempotencyKey = 'ord-10241-' . substr(
    hash('sha256', 'ord-10241|' . getenv('HEATRAIL_KEY_ID')),
    0,
    16
);

$result = $client->check($payload, $idempotencyKey);

check() ei viska kunagi ja on piiratud 800 ms peale. Kui midagi läheb valesti, tagastab ta degradeerunud kuju, logib selle, ja paneb kontrolli korduseks järjekorda, kui te andsite kliendile järjekorra. Teie kassa jätkab igal juhul.

Lugemine

Lugege vastus, ja salvestage ta tellimuse külge.

{
  "check_id": "3f7a1c02-5b4e-4a19-8c3d-9e0b6d2f4a71",
  "score": 72,
  "reasons": [
    "Customer identifier matched a network-confirmed fraud trail, 2 shop(s) affected, 3 d ago",
    "Same identifier seen in 3 shops within 24 h"
  ],
  "trail_alias": "9c1d4e7b0a52f83e",
  "test": false
}

score: Täisarv 0 kuni 100, toodetud reeglitega, mitte mudeliga. 70 ja üle selle on see, mida Heatrail käsitleb poe hoiatamise väärilisena.
reasons: Inimesele loetavad tõendiread, mis kirjeldavad, mis rakendus, koos arvude ja värskusega. Nad ei sisalda kunagi identifikaatorit, räsi ega teise poe andmeid.
trail_alias: Läbipaistmatu poepõhine pide sobitatud jäljele, või null, kui kontroll ei sobinud millegagi. Sama jälg näitab igale poele teist aliast, et teda ei saaks võrgu sondeerimiseks kasutada.
degraded: Kohal ja true ainult SDK fail-open kujul. Salvestage ta. Käsitlege teda kui „me ei tea“, mitte kui „madal risk“.
test: true, kui kontroll oli simuleeritud testirežiimi vastus. Testkontrollid ei tekita kuumust, ei puutu võrgugraafi ja neid ei arveldata kunagi.

Püsistage skoor, põhjused ja degradeerunud lipp tellimuse külge. Teie operaatorid peavad nägema, mida Heatrail sel hetkel ütles, ka nendel kordadel, kui ta ei öelnud midagi.

Silt

Saatke tulemus tagasi.

Kontroll, millele ei järgne tulemust, ei õpeta võrgule midagi. Kui tellimus osutub pettuseks, või saabub chargeback, pange silt. Märgistamine on ainus operatsioon, mis tõrkel viskab: silt on inimese otsus, ja SDK ei ütle teile kunagi, et silt rakendati, kui API seda ei kinnitanud.

use Heatrail\Sdk\HeatrailLabelException;

try {
    $confirmed = $client->label(
        'ord-10241',                       // order_ref
        'fraud',                           // fraud | chargeback | real
        'anna.tamm',                       // who decided, for your own audit trail
        'label-ord-10241-fraud',           // idempotency key, deterministic
        [
            'reason_code'   => 'stolen_card',
            'evidence_type' => 'merchant_confirmation',
        ]
    );

    // ['ok' => true, 'incident_id' => '…']
} catch (HeatrailLabelException $e) {
    // Show the operator that it failed. Never record it as applied.
}

real ei tekita kuumust üldse. Ta on olemas selleks, et hea klient jääks kirja heana ja et saaksite viga parandada. Ainult fraud ja chargeback jätavad jälje. Pettuse silt teeb ostja seadme ja IP-aadressi kuumaks kõigile Pro poodidele korraga. E-post ja telefon saavad mujal täiskaalu alles siis, kui need on kinnitatud või seotud sama seadmega, ja võrgu kuumus vajab kahte sõltumatult omatud poodi. Operaator ei saa võrgu kuumust kirjutada.

Tühjendus

Korrake seda, mis avanes fail-open.

Andke kliendile järjekorra hoidla ja iga ebaõnnestunud kontroll kirjutatakse sinna, selle asemel et kaduda. Taustatöö kordab neid, sondides esmalt health(), et taastuv API ei saaks peksma, allkirjastades iga katse värske ajatempli ja noncega, ja taaskasutades algset idempotentsusvõtit, et kontroll, mis tegelikult esimesel korral kohale jõudis, ei saaks kaks korda loetud.

use Heatrail\Sdk\Queue\FileQueueStore;

$queue = new FileQueueStore('/var/lib/heatrail/queue.jsonl');

$client = HeatrailClient::forShop($keyId, $secret, $baseUrl, [
    'network_salt' => $salt,
    'queue'        => $queue,
]);

// From cron, every minute:
$drained = $client->drainQueue($queue);

FileQueueStore on viiterakendus, ühe hosti oma ja piirideta. Produktsioonis toetage sama väikest QueueStore liidest oma tabeliga ja lisage säilitus. SDK leht ütleb täpselt, mida see tähendab.

Testirežiim

Näete punast riba ilma päris pettust ootamata.

Paluge meil teie poele testirežiim sisse lülitada. Kassa, mis on tehtud võlu e-postiga fraud-test@heatrail.eu või võlutelefoniga +372 55550666, tagastab siis simuleeritud kõrge skoori 85, põhjustega, mille ees on TEST MODE:, ja lipuga test.

Midagi muud ei juhtu. Testkontroll ei tekita kuumust, ei kirjuta kiirust, ei puutu võrgugraafi, ei saada hoiatust ja teda ei arveldata kunagi. Ta käitub nii ainult siis, kui lipp on meie poolel sees. Ilma selleta käsitletakse neid võlu väärtusi täpselt nagu kohatäiteid ja need visatakse ära, et nad ei saaks elus poes juhuslikult valet hoiatust teha.

Siis minge sügavamale.

API viide PHP SDK Küsi küsimus