API für Einladungen, Bewertungen & Widgets

Authentifizierung

Erstelle einen Schlüssel unter Dashboard → API. Sende ihn als Bearer-Token. Schlüssel beginnen mit rnq_ und sind auf ein Unternehmen beschränkt.

Authorization: Bearer rnq_…

Der Schlüssel hat nur Zugriff auf das Unternehmen, für das er erstellt wurde. Niemals im Client-Code offenlegen.

API-Schlüssel verwalten →

Endpunkte

Alle v1-Endpunkte erfordern den Authorization-Header. JSON rein und raus. Die Feed-URL ist öffentlich (Token im Pfad).

Organisation

Gibt RanqaScore, durchschnittliche Bewertung, Bewertungsanzahl und bereitgestellte Widget-Links zurück.

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"
  }
}

Einladungen

Einladungen nach Lieferung oder Kauf senden. Kostenlose Pläne haben ein monatliches Kontingent; Growth und Pro sind unbegrenzt.

Einladungen erstellen

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 wendet das Badge „Verifizierter Kunde“ an. Nur mit einem Bestell-/CRM-Link verwenden. Missbrauch kann den Schlüssel widerrufen.

Alternative Kurzform mit emails[]:

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

Einladungen und Kontingent auflisten

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"
    }
  ]
}

Bewertungen

Liste veröffentlichter Bewertungen. Verwende nextCursor als Cursor für die nächste Seite.

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

Abfrage: limit (1–100), cursor (ISO-Datum), rating (1–5), target (unternehmen|produkt).

{
  "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"
}

Produkte

Produktseiten und Produkt-Einladungen erfordern Commerce oder Pro. POST erstellt ein Produkt unter deinem Unternehmen. Füge gtin/marke/mpn für den Google-Feed hinzu.

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-Startpunkte: Leite den Bestell-Webhooks deines Shops an Ranqa mit einem Commerce- oder Pro-Webhooks-Token oder API-Schlüssel.

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 */ }

Ordne Shopify product_id / Woo product_id den products.externalId zu, damit Produkt-Einladungen korrekt verlinkt werden.

Produktbewertungen-Feed

Öffentliches XML (Google-Schema 2.4) für den Merchant Center geplanten Abruf. Erstelle ein Token unter Dashboard → API.

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

Drehe das Token, wenn die URL geleakt wird. Google genehmigt den Feed separat.

API-Schlüssel verwalten → · Seller Ratings →

Widgets (iframe)

Kein API-Schlüssel für Einbettungen erforderlich — Widgets sind öffentlich. Wählen Sie einen Typ und optional einen Produkt-Slug. Snippets finden Sie im Dashboard.

<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>

Typen: Badge (Größe=sm|md|lg), mini, Karussell, Galerie, sammeln, Zitat. Badge ist im Trustpilot-Stil mit dem Ranqa-Logo. Fügen Sie &product={slug} für eine Produktseite hinzu (sammeln verlinkt zu Bewertungen — Produktbewertungen erfordern eine Kauf-Einladung).

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

Registrieren Sie HTTPS-Endpunkte im Dashboard für signierte Aufrufe, wenn Bewertungen erstellt, markiert oder Einladungen abgeschlossen werden.

Ereignisse, auf die Sie sich abonnieren können:

review.created
review.flagged
invite.completed

Überprüfen Sie X-Ranqa-Signature = HMAC-SHA256 (hex) des rohen JSON-Körpers mit Ihrem Geheimnis.

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

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

Endpunkte werden im Dashboard (Sitzung) erstellt, nicht über den v1 API-Schlüssel.

Webhooks verwalten →

Fehlercodes

Antworten sind JSON mit einem Fehlerfeld. Validierungsfehler enthalten oft Details.

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