AI Commerce GraphQL -integraation perussopimus

AI Commerce GraphQL tarjoaa partnereille yhden tenant-kohtaisesti tunnistautuvan rajapinnan kyselyille ja mutaatioille. Tuotannon yhteyspiste on:

https://api.aicommerce.fi/graphql

Skeeman julkinen referenssi on osoitteessa [https://docs.aicommerce.cloud](https://docs.aicommerce.cloud). Dokumentaatio ja tuotannon API ovat tarkoituksella eri verkkotunnuksissa: tarkista kyselyt, mutaatiot, tyypit, argumentit ja esimerkit dokumentaatiossa, mutta lähetä integraation pyynnöt vain tuotannon GraphQL-yhteyspisteeseen.

API käyttää yhtä versiotonta endpointia. Polkuja /v1 tai /v2 ja version kiinnittävää otsaketta ei ole. Integraatio pitää siksi rakentaa dokumentoidun skeeman, dynaamisesti haettavien tenant-arvojen ja sovitun muutoskäytännön varaan.

Hanki tunnukset onboardingissa

GraphQL-tunnukset myönnetään onboardingissa integraatiolle ja oikealle tenantille. Jokainen pyyntö tarvitsee seuraavat HTTP-otsakkeet:

| Otsake | Arvo | | --- | --- | | Content-Type | application/json | | X-GraphQL-Secret | onboardingissa myönnetty API-käyttöoikeustunniste | | X-Tenant-ID | onboardingissa myönnetty tenant-tunniste | | X-Tenant-Secret | onboardingissa myönnetty tenant-kohtainen salaisuus |

Säilytä kaikki kolme tunnistetta vain palvelinpuolen salaisuuksienhallinnassa. Älä kirjoita niitä selainkoodiin, julkiseen repositorioon, tikettiin, dokumenttiin, kuvakaappaukseen tai komentohistoriaan. Rajaa tunnusten käyttö vain integraation ajonaikaiselle palvelulle ja kierrätä vuotanut tunnus heti sovitun tukikanavan kautta.

API-pääsyä, tenant-tunnuksia, integraatiotukea tai rate limit -muutosta pyydetään osoitteesta info@petrosoft.fi. Älä käytä toisen tenantin tunnuksia testaukseen.

Muodosta GraphQL-pyyntö

GraphQL-pyyntö lähetetään HTTP POST -pyyntönä JSON-rungolla. Runko sisältää merkkijonon query ja tarvittaessa olion variables. Integraatio valitsee kyselyyn vain käyttämänsä kentät, ja onnistuneen vastauksen data seuraa samaa kenttärakennetta.

Seuraava kysely hakee viisi tuotetta alusta alkaen:

query Tuotteet($limit: Int, $offset: Int) {
  products(limit: $limit, offset: $offset) {
    id
    name
    price
  }
}

Muuttujat pidetään erillään kyselytekstistä:

{
  "limit": 5,
  "offset": 0
}

Käytä muuttujia käyttäjän tai taustajärjestelmän arvojen välittämiseen. Älä kokoa arvoja merkkijonoliitoksilla GraphQL-kyselyyn. Tarkista dokumentaatiosta argumenttien pakollisuus, tyypit, enum-arvot ja palautettavat kentät ennen toteutusta.

Lähetä pyyntö ilman tunnusten vuotamista

GraphQL-pyynnön voi tarkistaa komentoriviltä ympäristömuuttujien avulla. Aseta muuttujat hyväksytyssä salaisuuksienhallinnassa tai suojatussa prosessiympäristössä; älä tallenna oikeita arvoja skriptiin.

curl --fail-with-body -X POST \
  'https://api.aicommerce.fi/graphql' \
  -H 'Content-Type: application/json' \
  -H "X-Tenant-ID: ${AICC_TENANT_ID}" \
  -H "X-Tenant-Secret: ${AICC_TENANT_SECRET}" \
  -H "X-GraphQL-Secret: ${AICC_GRAPHQL_SECRET}" \
  --data '{
    "query": "query Tuotteet($limit: Int, $offset: Int) { products(limit: $limit, offset: $offset) { id name price } }",
    "variables": {
      "limit": 5,
      "offset": 0
    }
  }'

Onnistunut vastaus sisältää pyydetyt tiedot data-kentässä:

{
  "data": {
    "products": [
      {
        "id": "632",
        "name": "Example product",
        "price": 89.9
      }
    ]
  }
}

Esimerkin ympäristömuuttujien nimet ovat paikallisen kutsun apunimiä, eivät selaimeen vietäviä asetuksia. Varmista, ettei CI-loki tulosta otsakkeita tai komentoa laajennettuine arvoineen.

Käsittele GraphQL-vastaus oikein

GraphQL-vastaus pitää tarkistaa sekä HTTP-tilakoodin että JSON-rungon perusteella. HTTP 200 ei yksin tarkoita, että operaatio onnistui.

• Onnistunut operaatio palauttaa tavallisesti data-olion.

• Tenant-tunnisteen tai tenant-salaisuuden virhe voi palauttaa HTTP 200 sekä data: null ja errors[].

• Validointi- ja resolverivirheet palautuvat GraphQL-muodossa errors[]-taulukkona.

• Osittain onnistunut kysely voi sisältää sekä osittaisen data-olion että errors[]-taulukon.

• Palvelinvirhe voi palauttaa HTTP 500 ja yleisen GraphQL-virherungon.

Tarkista aina errors[] ennen kuin merkitset ajon onnistuneeksi. Osittaisessa vastauksessa käytä vain ne data-kentät, jotka ovat mukana ja kelvollisia, ja kirjaa jokainen virheviesti ilman tunnuksia tai henkilötietoja. Älä yritä automaattisesti uudelleen validointi-, tunnistus- tai liiketoimintavirhettä muuttamatta pyyntöä.

Käsittele WAF- ja rate limit -virheet

WAF- ja rate limit -virheet syntyvät ennen tavallista GraphQL-resolverivastausta, joten niiden muoto poikkeaa errors[]-mallista.

Virheellinen tai puuttuva X-GraphQL-Secret hylätään reunalla tyypillisesti HTTP 403 -vastauksena ilman GraphQL-runkoa. Jos vastaus ei ole JSON-muotoinen, käsittele se reunatason estona ja tarkista käyttöoikeustunniste sekä kutsun kohde.

Tenant-kohtainen raja on 100 pyyntöä / 5 minuuttia. Kun raja ylittyy, API palauttaa HTTP 429 Too Many Requests ja rungon:

{ "error": "Too many requests, please try again later." }

429 on ainoa tässä sopimuksessa kuvattu vastaus, joka käyttää ylätason error-kenttää GraphQLin errors[]-taulukon sijasta. Keskeytä uudet kutsut, odota rajoitusikkunan vaihtumista ja yritä hallitusti uudelleen. Tasoita kuorma, sivuta suuret haut ja vältä samaan tenanttiin kohdistuvaa rajatonta rinnakkaisuutta.

Käytä skeemaa ja tenant-arvoja dynaamisesti

GraphQL-skeeman kentät, argumentit ja tyypit tarkistetaan julkisesta dokumentaatiosta. Tuotantoendpointissa on myös introspektio käytössä, joten skeemageneraattorit, Apollo Codegen ja IDE-työkalut voivat lukea ajantasaisen skeeman suoraan hyväksytyillä tunnuksilla.

API on versioimaton. Uusien tyyppien, kyselyiden, mutaatioiden, kenttien tai valinnaisten argumenttien lisääminen on yhteensopiva muutos. Tyypin, kentän tai pakollisen argumentin poistaminen tai nimeäminen uudelleen on rikkova muutos, josta AI Commerce koordinoi vaikutuksen piirissä olevien integraatioiden kanssa.

Älä kovakoodaa tenant-kohtaisia tila-, kieli-, valuutta-, maksu- tai toimitustapatunnisteita. Hae arvot niiden kyselyistä, kuten orderStatuses, quoteStatuses, languages, currencies ja configurations, ja käsittele tuntematon merkkijono läpinäkymättömänä arvona. Pidä integraation yhteyshenkilö ajan tasalla onboarding-kanavassa, jotta rikkovien muutosten ilmoitus tavoittaa oikean omistajan.

Valitse suora GraphQL tai storefrontin REST-palvelu

Suora GraphQL-yhteys käyttää onboardingissa myönnettyjä tenant-tunnisteita ja dokumentoitua koko skeemaa. Se sopii ERP- ja taustajärjestelmäintegraatioihin, jotka tarvitsevat asiakas-, tilaus- tai muuta yksityistä dataa tai hyväksyttyjä mutaatioita.

Kauppiaskohtainen storefrontin /rest/*-palvelu voi kutsua executePublicGraphQL(query, variables)-asiakasta. Tämä asiakas sallii vain hyväksytyn julkisen, vain luku -osajoukon: esimerkiksi tuotteita, kategorioita, valmistajia ja sisältödataa. Se hylkää mutaatiot, subscriptionit, introspektion, aliakset, fragmentit ja hyväksymättömät kentät koodilla REST_GRAPHQL_OPERATION_NOT_ALLOWED.

Storefrontin turvallisen asiakkaan kautta ei ole saatavilla asiakas-, tilaus-, maksu-, ylläpitäjä- tai salaisuusdataa. Älä kierrä rajausta tuomalla storefront-palveluun raakaa GraphQL-siirtoa. Valitse suora integraatio, kun käyttötapa tarvitsee koko skeemaa; valitse /rest/*, kun palvelu tarvitsee vain julkista storefront-dataa ja kuuluu storefrontin julkaisuun.

Vertaa GraphQL- ja REST-sopimusta

GraphQL- ja REST-sopimukset eroavat siinä, kuka määrittää vastauksen rakenteen. GraphQL-kutsussa asiakas valitsee tarvitsemansa kentät, joten yksi kysely voi hakea toisiinsa liittyvää dataa ilman tarpeettomia kenttiä. Tämä ei poista sivutuksen, virheenkäsittelyn tai skeemamuutosten hallintaa.

REST-yhteyspiste puolestaan määrittää oman kiinteän vastausrakenteensa. Useita endpoint-kutsuja voidaan tarvita, mutta sopimus voi olla yksittäiselle tehtävälle yksinkertaisempi. Storefrontin /rest/*-palvelu on lisäksi eri asia kuin suora AI Commerce GraphQL: se on kauppiaskohtainen sovitin, jonka tietorajat ja julkaisu kuuluvat storefront-projektiin.

Valitse rajapinta käyttötapauksen, tietoluokan, kirjoitustarpeen ja omistajuuden perusteella. Älä valitse GraphQL:ää vain siksi, että sillä voi pyytää useita kenttiä, äläkä valitse storefrontin REST-palvelua yksityisen taustajärjestelmädatan oikotieksi.