API kutsuille, arvosteluille ja widgeteille

Autentikointi

Luo avain Hallintapaneeli → API. Lähetä se Bearer-tokenina. Avaimet alkavat rnq_ ja ne on rajattu yhteen yritykseen.

Authorization: Bearer rnq_…

Avain pääsee vain siihen yritykseen, jolle se on luotu. Älä koskaan paljasta sitä asiakaspään koodissa.

Hallitse API-avaimia →

Päätepisteet

Kaikki v1 päätepisteet vaativat Authorization-otsikon. JSON sisään ja ulos. Syötteen URL on julkinen (token polussa).

Organisaatio

Palauttaa RanqaScore, keskiarvoarvosanan, arvostelujen määrän ja valmiit widget-linkit.

GET https://ranqa.me/api/v1/organization
Authorization: Bearer rnq_…

{
  "id": "…",
  "name": "Example AB",
  "slug": "example-ab",
  "primaryDomain": "example.com",
  "plan": "pro",
  "ranqaScore": 4.6,
  "averageRating": 4.4,
  "reviewCount": 128,
  "publicUrl": "https://ranqa.me/example.com",
  "widgets": {
    "badge": "https://ranqa.me/widget/example-ab?type=badge",
    "mini": "https://ranqa.me/widget/example-ab?type=mini",
    "carousel": "https://ranqa.me/widget/example-ab?type=carousel",
    "gallery": "https://ranqa.me/widget/example-ab?type=gallery",
    "collect": "https://ranqa.me/widget/example-ab?type=collect",
    "quote": "https://ranqa.me/widget/example-ab?type=quote"
  }
}

Kutsut

Lähetä kutsuja toimituksen tai oston jälkeen. Ilmaisilla suunnitelmilla on kuukausikiintiö; Kasvu ja Pro ovat rajattomia.

Luo kutsuja

POST https://ranqa.me/api/v1/invites
Content-Type: application/json
Authorization: Bearer rnq_…

{
  "recipients": [
    {
      "email": "[email protected]",
      "name": "Anna",
      "orderId": "ORD-123",
      "productId": null,
      "verifiedPurchase": true
    }
  ],
  "sendEmail": true
}

verifiedPurchase: true myöntää Vahvistettu asiakas -merkin. Käytä vain tilauksen/CRM-linkin kanssa. Väärinkäyttö voi peruuttaa avaimen.

Vaihtoehtoinen lyhyt muoto sähköposteilla[]:

{
  "emails": ["[email protected]", "[email protected]"],
  "verifiedPurchase": false,
  "sendEmail": false
}

Listaa kutsut ja kiintiö

GET https://ranqa.me/api/v1/invites
Authorization: Bearer rnq_…

{
  "quota": { "used": 42, "limit": null, "remaining": null },
  "invites": [
    {
      "id": "…",
      "email": "[email protected]",
      "verifiedPurchase": true,
      "used": false,
      "expiresAt": "2026-08-15T00:00:00.000Z"
    }
  ]
}

Arvostelut

Listaa julkaistut arvostelut. Käytä nextCursoria seuraavan sivun kursoriin.

GET https://ranqa.me/api/v1/reviews?limit=20&rating=1&target=company
Authorization: Bearer rnq_…

Kysely: raja (1–100), kursori (ISO-päivämäärä), arvio (1–5), kohde (yritys|tuote).

{
  "reviews": [
    {
      "id": "…",
      "rating": 5,
      "title": null,
      "body": "Fast delivery",
      "authorName": "Anna",
      "source": "invite",
      "language": "sv",
      "createdAt": "2026-07-30T12:00:00.000Z"
    }
  ],
  "nextCursor": "2026-07-29T10:00:00.000Z"
}

Tuotteet

Tuotesivut ja tuotekutsut vaativat Commerce- tai Pro-paketin. POST luo tuotteen yrityksesi alle. Sisällytä gtin/merkki/mpn Google-syötteeseen.

GET https://ranqa.me/api/v1/products
Authorization: Bearer rnq_…

POST https://ranqa.me/api/v1/products
Content-Type: application/json
Authorization: Bearer rnq_…

{
  "name": "Vitamin D 90 caps",
  "sku": "VD-90",
  "externalId": "shopify-123",
  "gtin": "0735001234567",
  "brand": "Example",
  "mpn": "VD-90-MPN",
  "imageUrl": "https://cdn.example.com/vd.png"
}

Shopify & WooCommerce

HTTP-aloitukset: ohjaa kauppasi tilauksen webhook Ranqalle Commerce- tai Pro-webhook-tokenilla tai API-avaimella.

Shopify → · WooCommerce →

POST https://ranqa.me/api/v1/commerce/shopify/orders
Authorization: Bearer rnq_…
Content-Type: application/json

{ /* Shopify order webhook JSON */ }

POST https://ranqa.me/api/v1/commerce/woocommerce/orders
Authorization: Bearer rnq_…
Content-Type: application/json

{ /* WooCommerce order webhook JSON */ }

Kartuta Shopify product_id / Woo product_id tuotteiden.externalId:hen, jotta tuotekutsut linkittyvät oikein.

Tuotearvostelujen syöte

Julkinen XML (Google-skeema 2.4) Merchant Centerin aikataulutettuun hakuun. Luo token Dashboard → API:n alla.

GET https://ranqa.me/feeds/{token}/product-reviews.xml

Käännä token, jos URL vuotaa. Google hyväksyy syötteen erikseen.

Hallitse API-avaimia → · Seller Ratings →

Widgetit (iframe)

Upotuksiin ei tarvita API-avainta — widgetit ovat julkisia. Valitse tyyppi ja valinnainen tuote-slug. Koodinpätkät löytyvät hallintapaneelista.

<iframe
  src="https://ranqa.me/widget/{slug}?type=badge&size=md"
  width="280"
  height="64"
  style="border:0;overflow:hidden;border-radius:999px"
  title="RanqaScore"
  loading="lazy"
></iframe>

Tyypit: badge (size=sm|md|lg), mini, carousel, gallery, collect, quote. Badge on Trustpilot-tyylinen Ranqa-merkillä. Lisää &product={slug} tuotesivulle (collect vie arvosteluihin — tuotearviot vaativat ostokutsun).

https://ranqa.me/widget/{slug}?type=badge&size=sm   # email / compact
https://ranqa.me/widget/{slug}?type=badge&size=md   # website (default)
https://ranqa.me/widget/{slug}?type=badge&size=lg   # large
https://ranqa.me/widget/{slug}?type=mini
https://ranqa.me/widget/{slug}?type=carousel
https://ranqa.me/widget/{slug}?type=gallery
https://ranqa.me/widget/{slug}?type=collect
https://ranqa.me/widget/{slug}?type=quote
https://ranqa.me/widget/{slug}?type=carousel&product={productSlug}
https://ranqa.me/widget/{slug}?type=collect&product={productSlug}

Webhooks

Rekisteröi HTTPS-päätteet hallintapaneelissa allekirjoitettujen kutsujen varten, kun arvosteluja luodaan, merkitään tai kutsuja suoritetaan.

Tapahtumat, joihin voit tilata:

review.created
review.flagged
invite.completed

Vahvista X-Ranqa-Signature = HMAC-SHA256 (hex) raaka JSON-ruumiin kanssa salaisuudellasi.

X-Ranqa-Signature: <hex hmac-sha256 of raw body>

{
  "type": "review.created",
  "reviewId": "…",
  "organizationId": "…",
  "rating": 2,
  "status": "published"
}

Päätteet luodaan hallintapaneelissa (istunto), ei v1 API-avaimen kautta.

Hallitse webhooks →

Virhekoodit

Vastaukset ovat JSON, jossa on virhekenttä. Vahvistusvirheet sisältävät usein yksityiskohtia.

401 Unauthorized — missing or invalid API key
403 Forbidden — plan/quota restriction
400 Bad Request — validation error (Zod details)
429 Too Many Requests — rate limited
500 Server error