Arendajatele

API viide.

JSON üle HTTPS, autentitud HR1 HMAC allkirjaga kanoonilise stringi peal. Igapäevase liidestuse kannavad kaks otspunkti, /v1/check ja /v1/labels. Iga päringu keha valideeritakse range lubatud nimekirja vastu, seega tundmatu väli on viga, mitte vaikselt vastu võetud uus salvestatud andmete kategooria.

Alused

Üks päritolu, üks versiooni prefiks.

Baasaadress: https://api.heatrail.eu. Lugege ta seadistusest, ärge kleepige teda koodi: see on üks väärtus, mida peaks muidu kõikjal korraga muutma.
Sisutüüp: application/json igal päringul, millel on keha. Vastused on alati JSON, ka vead.
Ainult serveripoolne: Allkirjastamise saladus ja võrgusool ei tohi kunagi jõuda brauserisse, mobiilirakendusse ega ühtegi klienti, mida te ei kontrolli. Avalikku ega publishable võtit ei ole.
Scopes: Võti kannab check, label, või mõlemat. /v1/check, explain otspunkt ja ajaloo skann vajavad check. /v1/labels ja tema tühistus vajavad label.
Latentsus: Mõõdetud produktsioonis 1. septembril 2026: ringkäigu mediaan 386 ms, 95. protsentiil 610 ms, kõige aeglasem 799 ms. Piirake oma kutse 800 ms peale ja laske tellimusel edasi minna, kui eelarve otsa saab. Selle eelarve vastu on kirjutatud kogu ülejäänud lehekülg.

Joonis 1

Ühel checkil on kolm lõppu, ja tellimus läheb läbi kõigis kolmes.

Autentimine

HR1: allkirjastage viis rida, saatke kolm päist.

Authorization:  HR1 {key_id}:{signature}
X-HR-Timestamp: 1788048000
X-HR-Nonce:     9f2b7c1a-4d3e-4a8b-9c6d-2e1f0a3b5c7d
Content-Type:   application/json

Authorization: Sõnasõnaline skeem HR1, teie key ID, koolon, ja allkiri. Key ID vastab ^[A-Za-z0-9_]{1,64}$ ja allkiri on 64 väiketähega kuueteistkümnendmärki.
X-HR-Timestamp: Unix sekundid kümnendstringina. Ta peab olema meie kellast ±300 sekundi sees, seega hoidke NTP töös. Kaldu ajatempel keelatakse sama üldise 401-ga nagu vale allkiri.
X-HR-Nonce: UUID, standardkujul 8-4-4-4-12 kuueteistkümnendmärki. Ta on ühekordne: sama nonce esitamine kaks korda tema kümne minuti säilituse sees keelatakse. Genereerige iga päringu jaoks värske, ka iga korduskatse jaoks.; Nonce hoidla ei pea taaskäivituse üle ajalugu. Päring, mille ajatempel on vanem kui hoidla viimane taaskäivitus, ei ole korduskontrollitav, seega ta keelatakse, mitte ei usaldata. See puudutab ainult päringuid, mis allkirjastati napilt enne taaskäivitust ja toimetati pärast seda. Allkirjastage uuesti praeguse ajatempli ja värske noncega, ja kordus läheb läbi.

Kanooniline string

Viis välja, ühendatud üksikute reavahetustega, täpselt selles järjekorras, ilma lõpetava reavahetuseta:

{timestamp}\n{nonce}\n{METHOD}\n{canonical_uri}\n{hex(sha256(raw_body))}

METHOD: Suurtäheline ASCII: POST, GET.
canonical_uri: Tee täpselt nii, nagu ta juhtmel paistab, mitte kunagi protsendikodeeringust lahti võetud, mitte kunagi uuesti kodeeritud, ja mitte kunagi hosti ega skeemi sisaldav.; Kui on päringustring, lisage ? ja kanooniline päring. Tükeldage toores päring & pealt. Osa ilma = märgeta käsitletakse kui key=. Sorteerige paarid baitide kaupa esmalt kodeeritud võtme, siis kodeeritud väärtuse järgi, hoides duplikaadid eraldi paaridena, ja ühendage tagasi &ga. Midagi ei dekodeerita teel.; Tühik tuleb kodeerida kui %20, mitte kunagi kui +. Allkirjastaja ei normaliseeri nende vahel, seega kaks annaksid erinevad allkirjad.
hex(sha256(raw_body)): Väiketäheline hex SHA-256 toore päringu keha baitidest, täpselt need baidid, mis te juhtmele panite, mitte uuestiserialiseerimine. Tühi keha räsitakse ikka, väärtuseks e3b0c442…b7852b855.
Allkiri: HMAC-SHA256(key = your API secret, message = canonical string), väiketäheline hex.

Avaldatud testvektor

Need on ühised fixture'id, mille vastu SDK ja API mõlemad kinnitavad. Implementatsioon, mis reprodutseerib allpool oleva allkirja, on õige.

<?php

function heatrail_sign(
    string $secret,
    string $timestamp,
    string $nonce,
    string $method,
    string $uri,
    string $body
): string {
    $canonical = implode("\n", [
        $timestamp,
        $nonce,
        strtoupper($method),
        $uri,                      // path (+ canonical query), never the host
        hash('sha256', $body),     // an empty body still hashes
    ]);

    return hash_hmac('sha256', $canonical, $secret);
}

$signature = heatrail_sign(
    's3cr3t-alpha',
    '1788048000',
    '9f2b7c1a-4d3e-4a8b-9c6d-2e1f0a3b5c7d',
    'POST',
    '/v1/check',
    '{"order_ref":"o1"}'
);

// 853010ed8094da1839a701ddb4a06b0baf1dfb51f0d2777944d2002f7ba045a6

Kanooniline string, mis ta toodab, reavahetused nähtavaks tehtud:

1788048000
9f2b7c1a-4d3e-4a8b-9c6d-2e1f0a3b5c7d
POST
/v1/check
83946f872d419e30de623c62e8719ae14ae9cc59e38a81308e691837954e739c

Iga autentimistõrge on üks üldine 401

Tundmatu võti, vale allkiri, kaldu kell, korduv nonce ja ulatuse mitteklappimine vastavad kõik 401 unauthorized, ilma detailita. Eraldi „insufficient scope“ vastus kinnitaks ründajale, et allkiri oli muidu kehtiv, mis on oraakel. Silumisel kontrollige selles järjekorras: key ID, saladus, kell, ja kas te allkirjastasite täpselt need baidid, mis te saatsite.

Idempotentsus

Iga POST kannab võtit. See ei ole valikuline.

Saatke Idempotency-Key igal POST-il. Ta peab vastama ^[A-Za-z0-9_-]{16,128}$, pange tähele, et lubatud märgid on kitsamad kui tellimuse viitel, seega tuletage võti, ärge kleepige viidet temasse. Võtmed on ulatusega teie poe, meetodi ja tee peale, ja neid hoitakse 24 tundi.

Sama võti, sama keha, vastus hoitud: Hoitud vastus tagastatakse muutmata, päisega Idempotency-Replayed: true. Kõrvalmõjud jooksevad täpselt üks kord.
Sama võti, erinev keha: 409 idempotency_key_reuse. See on kutsuja viga: võti nimetab konkreetset päringut, ja erinev keha sama võtme all tähendab, et kaks eri päringut põrkusid.
Sama võti, esimene päring veel pooleli: 409 idempotency_in_progress. Me ei blokeeri kaksikpäringu ootamiseks. Proovige uuesti, kui ta on maandunud.
Serveri viga: 5xx vabastab pretensiooni, selle asemel et teda hoida, et mööduv tõrge ei lukustaks võtit 24 tunniks. Proovige uuesti.
Puuduv või vigane: Päist üldse ei ole on 400 idempotency_key_required. Päis, mis mustriga ei klapi, on 422 idempotency_key_invalid.

Tuletage võti tellimusest deterministlikult, näiteks 'chk-' . substr(hash('sha256', $orderRef . '|' . $keyId), 0, 32). Nii tunneb korduv kontroll ära sama päringu, selle asemel et kaks korda loetud saada.

POST /v1/check

Hinnake üks kassa. Ulatus: check.

Tundmatud võtmed lükatakse tagasi, nii tipus, context sees, kui device_vector sees. Kõik valideerimisprobleemid kogutakse ja tagastatakse koos, ja sõnumid nimetavad välju, ilma et nad kunagi teie saadetud väärtusi kordaksid.

Keha

order_ref, session_ref: Stringid, mis vastavad ^[A-Za-z0-9._:-]{1,128}$. Vähemalt üks peab olema kohal ja mitte null. Iga kontroll on ankurdatud päris kassa külge, mille kohta teilt saab küsida, ja just see peatab API-l olemast tasuta otsinguoraakel jagatud signaali üle.
ip: Nõutav. Kliendi IP-aadress, mida teie enda server nägi, IPv4 või IPv6. Ta võetakse kehast ja mitte kunagi edastamise päisest: meie servas olete teie server puhver.
email_h, phone_h: Valikulised. Esimese astme räsi: täpselt 64 väiketähega kuueteistkümnendmärki, või null, või puuduvad. Mitte kunagi tühi string, ja mitte kunagi kohatäite räsi. Need keelatakse veaga 422 placeholder_hash.
persist_id: Valikuline naasva brauseri pseudonüüm, vastab ^[a-f0-9]{16,64}$.
context: Valikuline objekt. Lubatud võtmed: product_risk_class, qty, amount_bucket, account_age_class, referrer_class. qty on mittenegatiivne täisarv, ülejäänud on stringid kuni 64 märki, või null.; Need on vabas vormis kategooria stringid, ja reeglid klapivad täpse väärtuse pealt, seega saatke oma poe täpne klassifikatsioon selle sõnavara järgi, mitte oma kirjaviisiga: product_risk_class kui physical, digital või gift_card ning account_age_class kui new või existing. Saatke iga väli, mis teil on. Millistel neist praegused reeglid tegutsevad, ja kui palju kumbki loeb, ei ole avaldatud, ja väli, mis täna vaikib, ei pruugi homme vaikida.
device_vector: Valikuline objekt, kõige rohkem 2 KB serialiseerituna. Lubatud võtmed, ja ainult need: screen_w, screen_h, dpr, cores, memory, touch, tz, languages, platform, ua_class, canvas_hash, webgl_hash.; Väärtused on skalaarid kuni 64 märki, välja arvatud languages, mis on massiiv kuni 8 stringi. Toorel user-agent stringil ei ole lubatud võtit ja teda ei saa saata.

Päring

POST /v1/check HTTP/1.1
Authorization: HR1 hk_9f4c1e08b7a2d631:{signature}
X-HR-Timestamp: 1788048000
X-HR-Nonce: 9f2b7c1a-4d3e-4a8b-9c6d-2e1f0a3b5c7d
Idempotency-Key: chk-6b1d0a94c7e25f38a0d41b7c9e3f5028
Content-Type: application/json

{
  "order_ref": "ord-10241",
  "session_ref": "sess-7f3c1b9e2a6d",
  "email_h": "64520c679c209de4dd56c590782e441fcfcd37ef6e3222a61da6d360b131de23",
  "ip": "203.0.113.42",
  "context": {
    "product_risk_class": "digital",
    "qty": 3,
    "amount_bucket": "100-250",
    "account_age_class": "new"
  },
  "device_vector": {
    "screen_w": 390,
    "screen_h": 844,
    "dpr": 3,
    "touch": true,
    "tz": "Europe/Tallinn",
    "languages": ["et", "en"],
    "ua_class": "mobile-ios",
    "canvas_hash": "1f4b9c07"
  }
}

Vastus, 200

{
  "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,
  "plan": "pro",
  "network_signals_withheld": false
}

score: Täisarv, 0 kuni 100, toodetud reeglitega. 70 ja üle selle on lävi, millel Heatrail hoiatab poodi, kes tellimuse vormistas.
reasons: Inimesele loetavad tõendiread arvude ja värskusega, mõeldud inimesele lugemiseks ja teie enda koodile logimiseks, mitte parsimiseks. Nad on laused, mitte koodid, ja nende sõnastus ei ole stabiilne liides. Põhjus võib öelda, mis laadi klapp rakendus, mitme poe peale, ja kui ammu jämedates ühikutes. Ta ei kanna kunagi identifikaatorit, räsi, teise poe tõendit ega ühegi poe identiteeti. Arv ulatub teiste poodide peale ja ei nimeta neist ühtegi, mis teeb temast kategooria, mitte kirje.
trail_alias: 16-märgiline läbipaistmatu pideme sobitatud jäljele, või null, kui kontroll ei sobinud millegagi. Ta on teie jaoks stabiilne ja igale teisele poele, kes sama jälge vaatab, erinev. Free plaanil alati null: pideme kuulub võrguvaatele.
plan: "free" või "pro", plaan, millel see pood kontrolli hetkel on. Mõlemad plaanid jooksutavad sama kontrolli samas sekundis. Mis erineb, on see, kas teiste poodide panustatud signaalid on vastuse osa.
network_signals_withheld: Kohal ainult siis, kui päring kandis order_ref. Pro peal on ta alati false, sest Prolt ei hoita midagi tagasi ja iga võrgu põhjus on juba reasons sees. Free peal tähendab true, et võrk hoidis selle tellimuse kohta midagi ja teie plaan ei näidanud seda. Ta on üks boolean ja ta ei kanna kunagi arvu, vanust, poodi ega identifikaatorit.
test: true, kui see oli simuleeritud testirežiimi vastus: kuumust ei ole, kiirust ei ole, graafi ei ole, hoiatust ei ole, arveldust ei ole.

Vastus, 422

{
  "error": "invalid_payload",
  "details": [
    "unknown field \"customer_name\"",
    "ip is required",
    "device_vector contains unknown key \"userAgent\""
  ]
}

POST /v1/labels

Raporteerige tulemus. Ulatus: label.

order_ref: Nõutav. ^[A-Za-z0-9._:-]{1,128}$. Tellimus teie enda poes.
label: Nõutav. Üks fraud, chargeback, real. Ainult kaks esimest tekitavad kuumust, real ei tekita midagi.
labelled_by: Nõutav. Prinditavad märgid, kõige rohkem 128, kes teie organisatsioonis otsuse tegi. Saatke see, mida teie enda auditijälg vajab, konto nimi või personali viide pigem kui e-posti aadress, kui sellest teile piisab. Me ei saa väärtust kontrollida, seega ta jääb kirja väitena, mitte kontrollitud identiteedina.

Püsiv, ainult lisatav ahel salvestab läbipaistmatu aktori viite ja mitte kunagi väärtust ennast. Loetav väärtus, mille te saadate, hoitakse ahela kõrval eraldi provenance kirjes, 90 päeva säilitusaknaga, pärast mida ta kustutatakse, samal ajal kui ahel ja tema tervikluse tõend jäävad. Väärtus püsib ka intsidendi enese peal nii kaua, kuni see intsident on aktiivne tõend.
evidence_type: Nõutav. Üks merchant_confirmation, chargeback, psp_event, merchant_workflow, manual_review.
reason_code: Nõutav fraud ja chargeback jaoks, ignoreeritakse real puhul. Üks stolen_card, chargeback_received, account_takeover, reseller_abuse, other.
order_value_bucket: Valikuline. ^[A-Za-z0-9._:-]{1,32}$. Vahemik, mitte kunagi täpne summa.

POST /v1/labels

{
  "order_ref": "ord-10241",
  "label": "fraud",
  "labelled_by": "anna.tamm",
  "reason_code": "stolen_card",
  "evidence_type": "merchant_confirmation",
  "order_value_bucket": "100-250"
}

{
  "ok": true,
  "incident_id": "b4e1c7d2-90a3-4f16-8e75-2c0d9a3b6f41",
  "label": "fraud",
  "status": "active"
}

Sildi semantika

Üks aktiivne silt tellimuse kohta. Sildid asendavad, mitte ei kuhju. Sama sildi uuesti saatmine on tühitegevus, mis loeb ikkagi otsuse taaskinnitamiseks. Liikumine fraud pealt chargeback peale on asendus, kindlus tõuseb, ja kuumust ei võeta vahepeal maha.

fraud või chargeback panemine olemasoleva real peale keelatakse veaga 409 label_blocked_by_real. Õigeks tunnistatud tellimus tuleb esmalt selgelt tühistada, et kliendi õigeks tunnistamist ei võetaks juhuslikult tagasi.

Silt fraud või chargeback teeb ostja seadme ja IP-aadressi kuumaks kõigile Pro poodidele korraga. E-post ja telefon saavad teistes poodides täiskaalu alles siis, kui need on kinnitatud või seotud sama seadmega. Võrgu kuumus vajab kahte sõltumatult omatud poodi. Operaator ei saa võrgu kuumust kirjutada.

Teised otspunktid

Tühistus, explain, health, ajaloo skann.

POST /v1/labels/{incident}/reverse: Ulatus label. Tühistab ühe teie enda intsidendi, paranduse, ja tee real bloki tühjendamiseks enne uuestmärgistamist. Idempotentne: teine tühistus on 200 tühitegevus. Teise poe intsidendi identifikaator vastab 404 not_found ja ei kinnita kunagi, et ta olemas on.
GET /v1/orders/{order_ref}/explain: Ulatus check. Tagastab order_ref, score, reasons ja ISO 8601 checked_at selle tellimuse kõige värskema kontrolli kohta, admini „details“ vaate jaoks.; Ulatus on teie enda pood, ja tundmatu või võõras tellimuse viide vastab alati 404 not_found, mitte 403, et kaks oleksid eristamatud. Protsendikodeerige viide teesse ja allkirjastage kodeeritud tee baitide kaupa nii, nagu ta saadetakse.
GET /v1/health: Avalik. Vastab {"status": "up"} või {"status": "degraded"} ja ei midagi muud. Ta ei tagasta kunagi 401, isegi kehtetu allkirja peale, et teda ei saaks kasutada võtme kehtivuse testimiseks.; Allkirjastatuna kehtiva check ulatusega võtmega kannab vastus lisaks ledger_seq teie enda seireks. See väli ei ole avalik, sest ta lekiks võrgu mahtu.
POST /v1/history-scan/sessions: Ulatus check, Pro plaan. Pood teeb oma elu jooksul ühe ajaloo skanni. sessions avab ta, sessions/{scan_ref}/rows saadab minevikutellimusi kuni 100 rida päringus, ja sessions/{scan_ref}/complete sulgeb ta. Katkenud seanss jätkub seitse päeva, ja üks skann võrdleb võrguga kuni 250 000 minevikutellimust.; Iga rida saab vastuse strong, weak või none teie saadetud row_ref kohta, kategooriates, mitte tõendina. Ühtegi rida alles ei hoita. Teine skann nõuab operaatori lähtestust, ja selle põhjus läheb meie auditilogisse.

Vead

Iga viga on JSON väljaga `error`.

400 idempotency_key_required: POST saabus ilma Idempotency-Key päiseta.
401 unauthorized: Iga autentimistõrge: tundmatu võti, vale allkiri, ajatempel väljaspool ±300 sekundi akent, korduv nonce, puuduv või vigane päis, või võti ilma nõutava ulatuseta. Teadlikult eristamata.
403 key_frozen: Allkiri klappis, aga võti on ülevaatuse ootel külmutatud. See on ainus autentimistulemus, mis on eristatav, ja ainult pärast seda, kui allkiri tõestas, et te hoiate saladust.
404 not_found: Explain või tühistuse sihtmärk, mida ei ole, või mis kuulub teisele poele. Kaks juhtu on teadlikult eristamatud.
409 idempotency_key_reuse: Võtit hoiab päring teise kehaga.
409 idempotency_in_progress: Võti on hõivatud ja esimene päring ei ole lõppenud. Proovige uuesti.
409 label_blocked_by_real: fraud või chargeback silt pandi aktiivse real peale. Tühistage real esmalt.
422 invalid_payload: Valideerimine ebaõnnestus. details loetleb iga probleemi korraga, nimetades välju, aga mitte kunagi kordamata saadetud väärtusi.
422 placeholder_hash: Saadetud identifikaatori räsi on tuntud kohatäite räsi. Jätke väli ära. Vastus ei ütle, milline väli see oli.
422 idempotency_key_invalid: Idempotency-Key päis ei vasta ^[A-Za-z0-9_-]{16,128}$.
429 rate_limited: Kiiruspiir ületatud. Vastus kannab Retry-After.

Kiiruspiirid

/v1/check on piiratud API võtme kohta 20 päringuni ühe sekundi sees ja 60 päringuni ühe minuti sees. Keelatud päringud loevad mõlemasse aknasse. See on pidur API kasutamisele masina kiirusel, mitte müügimahtude lagi: ta istub kaugel üle liikluse, mida pood teeb, kutsudes meid üks kord tellimuse kohta.

Üle lagede saab võtme ka ülevaatuseks külmutada, mis vastab 403 key_frozen, mitte 429. Kohelge teda samamoodi nagu iga teist viga siin, degradeerunud kontrollina, ja kirjutage meile: külmutuse võtab maha inimene, mitte ootamine.

Kui te ootate õigustatult ületamist, suur kolimine, hulgi tagasitäide, öelge meile enne aadressil hello@heatrail.eu, selle asemel et piir produktsioonis avastada.

Iga viga siin on degradeerunud kontroll

Püüdke nad kõik kinni, hoidke kutse osas 01 nimetatud 800 ms eelarve sees, ja laske tellimusel edasi minna. Viga sellest API-st ei ole kunagi põhjus müüki peatada, ja liidestus, mis suudab temast peatatud müügi teha, kannab viga, mis tasub esimesena parandada. PHP SDK hoiab seda lepingut teie eest.

Allalaadimised

Kontrollige oma allalaadimist.

PHP SDK ja WooCommerce lisa serveeritakse partnerportaalist versioonitud ZIP arhiividena. Igaüks ehitatakse sildistatud commitist, reprodutseeritavalt, nii et samad lähtekoodid toodavad alati samad baidid, ja tema SHA-256 kontrollsumma avaldatakse siin ja saadetakse iga allalaadimisega X-Checksum-Sha256 päises. Enne kui te kumbagi arhiivi oma poodi vendorite, kontrollige, et fail, mille te saite, on fail, mille me ehitasime:

sha256sum heatrail-php-sdk-<version>.zip
# macOS: shasum -a 256 heatrail-php-sdk-<version>.zip

Väljund peab alltoodud väärtusega täpselt klappima. Kui ei, ärge paigaldage arhiivi: laadige ta portaalist uuesti, ja kui lahknevus kordub, öelge meile aadressil hello@heatrail.eu. Ebaõnnestunud kontrollsumma on ehitis, mida te ei saanud meilt, mitte rikutud allalaadimine, millest mööda töötada.

heatrail-php-sdk-0.3.0.zip: 7f6e5ca552e95eb8bbfd1d9cb3b27c1f2eff7d31aeb1aecd8c593db3f8765a32
heatrail-woocommerce-0.3.0.zip: 54e90feb6b3c5c957e93f0e4b800544e667349c6604d25e109a0b22a984fc262

Portaali AI paigaldusprompt kannab sama SDK kontrollsummat, seega agent, kes paigaldab Heatraili teie eest, kontrollib allalaadimist enne, kui ta ühegi faili vendorib.

Või laske SDK-l leping teie eest hoida.

PHP SDK Kiire algus Turvalisus ja arhitektuur