ConnectWiz + API ja webhookit

Live-integraatio

Myymämme API on se API, jota itse käytämme

Koko alusta on määritelty yhdessä OpenAPI-sopimuksessa, josta oma paneelimme ja mobiilisovelluksemme generoidaan – ei varjopäätepisteitä, ei dokumentaation ajautumista. Sen päällä: rajatut Commerce API -avaimet, suojatut webhook-liipaisimet ja työnkulut, jotka kutsuvat järjestelmiäsi.

Aloita ilmaiseksi Kaikki integraatiot
Yksi OpenAPI-sopimus Rajatut API-avaimet HMAC-varmennetut webhookit
API ja webhookit × ConnectWiz
Hyötykuormat ovat dataa, eivät käskyjä
Rajattu avain: katalogin luku · tilausten kirjoitus
Webhook → HMAC varmennettu → työnkulku käynnistyy
Työnkulun REST-askel kutsuu omaa API:tasi
1
OpenAPI-sopimus, joka on totuuden lähde – sama tiedosto, josta oma paneelimme ja mobiilisovelluksemme generoituvat
3
Commerce-rajausta – katalogin luku, tilausten luku, tilausten kirjoitus – myönnetään avainkohtaisesti
100
riviä enintään yhtä lukua kohden, rajattuna palvelimen päässä – limit-parametri validoidaan, siihen ei koskaan luoteta
50
rivi tilausta kohden API:n kautta – julkilausuttu raja, ei jälkikäteen löydetty

Kehittäjät

Mitä se tekee – täsmälleen

Yksi sopimus, joka on totuuden lähde

Yksi OpenAPI 3 -dokumentti määrittelee alustan, ja omat TypeScript-asiakkaamme generoidaan siitä – dokumentaatio ei voi ajautua erilleen todellisuudesta, koska todellisuus rakennetaan dokumentaatiosta.

Commerce API -avaimet

Tenantin myöntämät avaimet, joilla on eksplisiittiset rajaukset – katalogin luku, tilausten luku, tilausten kirjoitus – pyörittävät omaa verkkokauppaasi tai sovellustasi saman tilausmoottorin päällä, ja hinnat ratkaistaan aina palvelimen päässä.

Saapuvat webhookit, suojattuina

Jokaisella työnkulun webhook-liipaisimella on oma URL-osoitteensa ja salaisuutensa, HMAC-varmennus raakaa runkoa vastaan sekä toistosuojaus. Hyötykuorma voi nimetä ihmisen, mutta se ei voi koskaan ohjata työnkulun sisuksia.

Ulospäin työnkulkujen kautta

REST-askel kutsuu järjestelmiäsi täsmälleen niinä hetkinä, jotka piirrät kankaalle – tilaus tehty, suostumus annettu, varaus vahvistettu.

Tekninen puoli

API:n suunnitteluvalinnat, sanottuna ääneen

Hinnat eivät koskaan tule asiakasohjelmalta

Tilauspyyntö kertoo mitä ja kuinka monta – nimi ja hinta luetaan katalogista sillä hetkellä, palvelimen päässä, ja kirjoitetaan riville tilannekuvana. Peukaloitu pyyntö ei voi keksiä alennusta.

Kyvyt ennen kutsuja

Jokainen integraatiopinta julkaisee kykysopimuksen – osaako se tunnistaa puhelinnumeron perusteella, listata vieraiden tilauksia, luoda tilauksia? – ja jos kutsu ylittää julkilausutun kiellon, se heittää virheen välittömästi sen sijaan, että kaatuisi jossain syvällä.

Virheet, jotka merkitsevät jotain

Siirtokerros erottaa ”ei oikeuksia” -virheen ”palvelu alhaalla” -virheestä – joten ”kauppaan ei saada yhteyttä” ei koskaan näy muodossa ”tämä asiakas ei ole ostanut mitään”. Nimetyt virheet ovat ero API:n ja arvausleikin välillä.

Toistonkestävät webhookit

Jokainen sisääntuleva tapahtuma varaa yksilöllisen avaimen idempotenssin tapahtumakirjasta ennen käsittelyä – uudelleen yritetty tai toistettu toimitus kuolee tietokantakerrokseen, ei automaatioosi.

Avaimet tiivisteinä, salaisuudet rajattuina

API-avaimet tallennetaan tiivisteinä, ja ovella ratkaistaan vain tiiviste ja rajaukset – vuotanut tietokantarivi ei nimeä mitään työtilaa eikä avaa mitään rajaustensa ulkopuolelta.

Luonnokset ja vahvistukset ovat eksplisiittisiä

Tilauksen luonti ottaa vastaan nimenomaisen confirm-parametrin – julkinen API olettaa vahvistetun, paneelin työnkulut voivat valmistella luonnoksia – joten ”onko tämä oikea tilaus?” on kenttä eikä hiljainen sopimus.

Käyttöönotto

Miten yhteys muodostuu

01

Myönnä avain

Luo paneelissa rajattu Commerce API -avain; peru se yhtä helposti.

02

Kytke webhook

Luo työnkulku, jolla on webhook-liipaisin, ja allekirjoita pyynnöt sen salaisuudella.

03

Kutsu takaisin ulos

Lisää REST-askeleita sinne, missä järjestelmiesi pitää kuulla asiasta.

Parempi yhdessä

Mihin se yhdistyy

Flows

Webhook-liipaisimet käynnistävät työnkulut; REST-askeleet kutsuvat järjestelmiäsi takaisin niinä hetkinä, jotka piirrät – sisään- ja ulospäin suuntautuva automaatio jakavat saman kankaan.

Commerce

API:n takana oleva katalogi- ja tilausmoottori on sama, jota chat-kauppa ja tekoäly käyttävät – yksi tilaustotuus, neljä ovea.

Oma verkkokauppasi

Tiimit ajavat headless-kauppoja Commerce API:n päällä jo tänään – juuri sitä polkua suosittelee Shopify-sivu rehellisesti, kunnes natiivikonnektori on valmis.

Tietoturva ja takuut

Tylsät takuut

HMAC raa’an rungon yli

Webhookin varmennus allekirjoittaa pyynnön raa’an rungon liipaisinkohtaisella salaisuudella ja vertailee vakioajassa – jäsennys tapahtuu vasta todistuksen jälkeen.

Hyötykuormat ovat dataa, eivät käskyjä

Webhookin hyötykuorma voi viitata ihmiseen, mutta se ei voi koskaan ohjata työnkulun sisuksia, kirjoittaa kehotteita uusiksi eikä kutsua työkaluja. Raja datan ja ohjeiden välillä on arkkitehtuurissa, ei käyttäytymisessä.

Kutsurajat jokaisella ovella

Julkiset päätepisteet kulkevat tavallisen kuristuksen läpi, ja lukurajat rajataan palvelimen päässä – huonosti käyttäytyvä asiakasohjelma heikentää itseään, ei alustaa.

Rehellinen pikkupräntti

Rajat, sanottuna ääneen

Ei vielä täyttä tapahtumavirtaa

Yleistä tilaa-kaikki-webhooksyötettä ei ole rakennettu – ulospäin lähtevät tapahtumat kulkevat tänään työnkulkujen askelten kautta. Tämä sanotaan tässä, jottei yhdenkään myyntipuhelun tarvitse vihjata muuta.

Rajatut luvut, tarkoituksella

Luku palauttaa enintään 100 riviä kursorilla – API on rakennettu operatiiviseen integraatioon, ei massavientiin. Massatarpeet ovat keskustelun aihe, eivät porsaanreikä.

API:n ja webhookien FAQ

Suorat vastaukset

Lisää löydät osiosta FAQ, tai kysy meiltä suoraan.

Alusta on määritelty yhdessä OpenAPI 3 -sopimuksessa – samassa tiedostossa, josta verkkopaneelimme ja mobiilisovelluksemme generoivat tyyppinsä. Se, mitä vasten integroit, on se, jolla itse ajamme.

Liipaisinkohtaiset salaisuudet, HMAC-varmennus raakaa runkoa vastaan ja toistosuojaus idempotenssin tapahtumakirjan kautta. Ja sääntönä: hyötykuormat ovat dataa – ne voivat viitata ihmiseen, mutta eivät koskaan komentaa automaatiota.

Työnkulkujen REST-askelten kautta, laukaistuna niinä hetkinä, jotka valitset kankaalla. Yleinen ulospäin lähtevä webhooksyöte on tiekartalla, eikä sitä tarkoituksella luvata ennen kuin se on julkaistu.

Kyllä – katalogin luku ja tilausten kirjoitus ovat tuettu polku, hinnat ratkaistaan palvelimen päässä ja rajatut avaimet voi perua pinnoittain. 50 tilausrivin ja 100 tulosrivin rajat kerrotaan, jotta suunnittelet niitä vasten etkä kompastu niihin.

Toimitukset ovat meidän päässämme idempotentteja – tapahtumakirja tunnistaa toiston ja pudottaa sen, joten järjestelmäsi voivat yrittää uudelleen turvallisesti. Työnkulkujen ulospäin lähtevillä REST-askelilla on oma uudelleenyrityskäytäntönsä, ja virheet näkyvät työnkulun ajossa.

Rehellisesti kytketty voittaa äänekkäästi kytketyn.

Jokainen integraatio on kuvattu sillä, mitä se oikeasti tekee – suunta, omistajuus ja rajat mukaan lukien.

Aloita ilmaiseksi Kaikki integraatiot