Betygo API-dokumentation

Komplett guide för att integrera med Betygo recensionsplattform. Skicka recensionsinbjudningar och hämta recensioner programmatiskt.

Komma igång

Bas-URL

Alla API-anrop görs mot följande bas-URL

https://betygo.se/api/v1

Autentisering

Alla förfrågningar kräver en API-nyckel i Authorization header

Authorization: Bearer btg_din_api_nyckel_här
Content-Type: application/json

Endpoints

POST/invitations

Skapa recensionsinbjudan

Skapa en ny recensionsinbjudan som automatiskt skickas till din kund efter angiven fördröjning.

Parametrar

Parameter	Typ	Krävs	Beskrivning
`brandId`	string	Ja	ID för ditt varumärke
`orderId`	string	Nej	Din interna orderreferens
`customer.name`	string	Ja	Kundens fullständiga namn
`customer.email`	string	Ja	Kundens e-postadress
`products`	array	Nej	Lista över köpta produkter
`purchaseDate`	string	Ja	ISO 8601 datum när köpet gjordes
`scheduledDaysAfterPurchase`	number	Nej	Dagar att vänta innan utskick (0-14, standard: 3)

Exempel förfrågan

{
  "brandId": "cm123abc456def789",
  "orderId": "ORDER-2025-001", 
  "customer": {
    "name": "Anna Andersson",
    "email": "anna@example.com"
  },
  "products": [
    {
      "sku": "SHOE-RUN-42",
      "name": "Premium löparskor"
    }
  ],
  "purchaseDate": "2025-08-18T14:30:00Z",
  "scheduledDaysAfterPurchase": 3
}

Framgångsrikt svar

{
  "success": true,
  "timestamp": "2025-08-20T12:00:00Z",
  "data": {
    "id": "cm123invitation456",
    "brandId": "cm123abc456def789",
    "orderId": "ORDER-2025-001",
    "customerEmail": "anna@example.com",
    "scheduledSendDate": "2025-08-21T14:30:00Z",
    "status": "PENDING",
    "createdAt": "2025-08-20T12:00:00Z"
  }
}

GET/reviews

Hämta recensioner

Hämta godkända recensioner för ditt varumärke med filtrering och paginering.

Query-parametrar

Parameter	Typ	Krävs	Beskrivning
`brandId`	string	Ja	ID för ditt varumärke
`limit`	number	Nej	Antal recensioner (1-100, standard: 50)
`offset`	number	Nej	Recensioner att hoppa över (standard: 0)
`startDate`	string	Nej	Filtrera recensioner efter detta datum (ISO 8601)
`endDate`	string	Nej	Filtrera recensioner före detta datum (ISO 8601)
`rating`	number	Nej	Filtrera efter betyg (1-5)
`source`	string	Nej	VERIFIED, INVITED, eller UNVERIFIED

Exempel förfrågan

GET /api/v1/reviews?brandId=cm123abc456def789&limit=5&rating=5

Framgångsrikt svar

{
  "success": true,
  "timestamp": "2025-08-20T12:00:00Z",
  "data": {
    "reviews": [
      {
        "id": "cm123review789",
        "brandId": "cm123abc456def789",
        "rating": 5,
        "title": "Fantastisk service!",
        "content": "Jag är verkligen nöjd...",
        "author": "Anna A.",
        "source": "INVITED",
        "createdAt": "2025-08-18T14:30:00Z",
        "product": {
          "name": "Premium löparskor",
          "sku": "SHOE-RUN-42"
        }
      }
    ],
    "total": 156,
    "limit": 5,
    "offset": 0,
    "hasMore": true
  }
}

Felhantering

Vanliga felkoder

HTTP-statuskoder och felmeddelanden

Kod	Beskrivning
`MISSING_AUTHORIZATION`	Ingen Authorization header angiven
`INVALID_API_KEY`	API-nyckel hittas inte eller inaktiv
`BRAND_ACCESS_DENIED`	Varumärke tillhör inte ditt företag
`VALIDATION_ERROR`	Valideringsfel i förfrågan
`INVALID_SCHEDULE_DATE`	Schemalagt datum är i det förflutna

Exempel felsvar

Så ser felsvar ut

{
  "success": false,
  "timestamp": "2025-08-20T12:00:00Z",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Valideringsfel i förfrågan",
    "details": {
      "issues": [
        {
          "path": ["customer", "email"],
          "message": "Ogiltigt e-postformat"
        }
      ]
    }
  }
}

Kodexempel

cURL

Kommandoradsexempel

# Skapa recensionsinbjudan
curl -X POST https://betygo.se/api/v1/invitations \
  -H "Authorization: Bearer btg_din_api_nyckel" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "cm123abc456def789",
    "orderId": "ORDER-2025-001",
    "customer": {
      "name": "Anna Andersson", 
      "email": "anna@example.com"
    },
    "products": [{"sku": "SHOE-RUN-42", "name": "Löparskor"}],
    "purchaseDate": "2025-08-18T14:30:00Z",
    "scheduledDaysAfterPurchase": 3
  }'

# Hämta recensioner
curl "https://betygo.se/api/v1/reviews?brandId=cm123abc456def789&limit=10" \
  -H "Authorization: Bearer btg_din_api_nyckel"

JavaScript

Frontend/Node.js exempel

const API_KEY = 'btg_din_api_nyckel';
const BASE_URL = 'https://betygo.se/api/v1';

// Skapa recensionsinbjudan
const createInvitation = async (data) => {
  const response = await fetch(`${BASE_URL}/invitations`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });
  
  return await response.json();
};

// Hämta recensioner
const getReviews = async (brandId, options = {}) => {
  const params = new URLSearchParams({
    brandId,
    ...options
  });
  
  const response = await fetch(`${BASE_URL}/reviews?${params}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  
  return await response.json();
};

Bästa praxis & Support

Bästa praxis

Följ dessa riktlinjer för optimal integration

✓Förvara API-nycklar säkert - Exponera aldrig dem i klient-kod
✓Hantera fel elegant - Kontrollera alltid svarsstatus och hantera fel lämpligt
✓Använd paginering - Begär inte stora mängder data i enstaka anrop
✓Validera indata - Se till att e-postadresser och datum är korrekt formaterade
✓Övervaka framgång - Spåra e-postleveranser och recensionsfullföljande

Support

Behöver du hjälp med API:et?

Kontakta vårt utvecklingsteam eller skapa en issue i projektets repository för teknisk support.

Obs: Recensionsinbjudningar skickas automatiskt under kontorstid (8:30-20:00 CET) på ojämna minuter för att verka naturliga. Kunder får personliga e-postmeddelanden med säkra recensionslänkar som upphör efter 30 dagar.