Teknisk specifikation

Bilbetyg Feed v1

Ett JSON-dokument per anläggning med hela det aktuella lagret. Levereras som en URL vi hämtar (pull) eller som en POST till oss (push). Registrera på /anslut.

Grundregler

Snapshot. Dokumentet är hela lagret. En bil som saknas i nästa dokument markeras som borttagen hos oss. Inga deltan, inga sålt-events.
Stabila id:n. items[].id är samma för samma bil varje gång. Nytt id = ny bil (prishistorik nollställs).
Regnr på allt. licence_plate är nyckeln för dubblettskydd och prishistorik.
Enheter. Kilometer (inte mil), SEK inkl. moms, hästkrafter, ISO 8601-datum.
Storlek. Max 5000 bilar och 4 MB per dokument. Större lager delas per anläggning.
Frekvens. Pull hämtas var 12:e timme. Push tas emot när som helst, max 30 anrop per minut; vi läser senaste dokumentet vid nästa körning (inom en timme).
Versionering. Inom v1 läggs fält bara till. Okända fält ignoreras.

Dokument

Fält	Typ	Krav	Beskrivning
version	string	obligatoriskt	Alltid "1". t.ex. "1"
generated_at	date	obligatoriskt	När dokumentet skapades (ISO 8601 med tidszon). t.ex. "2026-09-05T06:00:00+02:00"
dealer	object	obligatoriskt	Anläggningen bilarna står hos. Se Dealer nedan. Flera anläggningar = flera feeds (en per anläggning).
items	object	obligatoriskt	Hela det aktuella lagret som en lista av Item (max 5000). Tom lista = handlaren har inget till salu.

Dealer

Fält	Typ	Krav	Beskrivning
name	string	obligatoriskt	Anläggningens namn som kunden ser det. t.ex. "Bosses Bil & Motor AB"
orgnr	string	obligatoriskt	Organisationsnummer, 10 siffror med eller utan bindestreck. Nyckeln som kopplar feeden till rätt handlarsida. t.ex. "556123-4567"
street	string	valfritt	Gatuadress. t.ex. "Industrivägen 4"
zip	string	obligatoriskt	Postnummer, 5 siffror. t.ex. "572 35"
city	string	obligatoriskt	Ort. t.ex. "Oskarshamn"
website	url	valfritt	Handlarens egen webbplats. t.ex. "https://www.bossesbil.se"
phone	string	valfritt	Telefon till försäljningen.
email	string	valfritt	E-post till försäljningen (visas inte publikt, används för kontaktformulär).

Item (en bil)

Fält	Typ	Krav	Beskrivning
id	string	obligatoriskt	Stabilt id i partnerns system. Samma bil ska ha samma id i varje snapshot; byts id:t räknas bilen som ny. t.ex. "19363711"
url	url	valfritt	Länk till bilen hos handlaren (egen sajt). Saknas den länkar vi till handlarens webbplats, och saknas även den visas bilen på en Bilbetyg-sida med kontaktformulär. t.ex. "https://www.bossesbil.se/bil/subaru-outback-2-5/"
licence_plate	string	obligatoriskt	Registreringsnummer utan mellanslag. Används för dubblettskydd mellan källor och för prishistorik. t.ex. "ABC123"
vin	string	valfritt	Chassinummer, 17 tecken.
brand	string	obligatoriskt	Märke som handlaren skriver det. t.ex. "Subaru"
model	string	obligatoriskt	Modell/serie utan märke. t.ex. "Outback"
variant	string	valfritt	Utförande, motor, paket — resten av titeln. t.ex. "2.5 Adventure Xfuel E85"
model_year	integer	obligatoriskt	Årsmodell. t.ex. 2021
first_registration	date	valfritt	Datum i trafik första gången (YYYY-MM-DD). Slår årsmodell för ålder och generation. t.ex. "2021-03-12"
price	integer	obligatoriskt	Fast kontantpris i SEK inkl. moms. 0 eller null = pris på begäran (bilen visas utan pris och ingår inte i jämförelser). t.ex. 289900
odometer_km	integer	obligatoriskt	Miltal i KILOMETER (inte mil). t.ex. 48200
fuel	string	obligatoriskt	Drivmedel. bensin \| diesel \| el \| elhybrid \| laddhybrid \| etanol \| gas \| vätgas t.ex. "bensin"
transmission	string	valfritt	Växellåda. automat \| manuell t.ex. "automat"
body	string	valfritt	Kaross. halvkombi \| kombi \| sedan \| suv \| coupe \| cabriolet \| minibuss \| pickup \| skåpbil \| annan t.ex. "kombi"
drive	string	valfritt	Drivning. fwd \| rwd \| awd t.ex. "awd"
power_hp	integer	valfritt	Effekt i hästkrafter. t.ex. 169
color	string	valfritt	Färg som handlaren anger den. t.ex. "Grå metallic"
towbar	boolean	valfritt	Dragkrok. Utelämna om okänt.
co2_g_per_km	integer	valfritt	CO2 blandad körning, WLTP.
electric_range_km	integer	valfritt	Elräckvidd WLTP (el/laddhybrid).
battery_kwh	number	valfritt	Batterikapacitet netto.
equipment	string[]	valfritt	Utrustningslista, en post per rad. t.ex. ["Dragkrok", "Navigation", "Värmare"]
description	string	valfritt	Säljtext. Visas men används inte för jämförelser. Max 5 000 tecken.
images	string[]	obligatoriskt	Bild-URL:er, första bilden = huvudbild. Minst 1, max 30. HTTPS, minst 800 px bred rekommenderas.
vehicle_history_url	url	valfritt	Länk till fordonshistorik (Carfax e.d.).
warranty	string	valfritt	Garanti i klartext. t.ex. "MRF-garanti 12 mån"
published_at	date	valfritt	När bilen lades ut till försäljning. Saknas den räknas dagar-på-marknaden från första gången vi ser bilen.

Exempel

{
  "version": "1",
  "generated_at": "2026-09-05T06:00:00+02:00",
  "dealer": {
    "name": "Bosses Bil & Motor AB",
    "orgnr": "556123-4567",
    "street": "Industrivägen 4",
    "zip": "572 35",
    "city": "Oskarshamn",
    "website": "https://www.bossesbil.se",
    "phone": "0491-123 45"
  },
  "items": [
    {
      "id": "19363711",
      "url": "https://www.bossesbil.se/bil/subaru-outback-2-5-adventure/",
      "licence_plate": "ABC123",
      "brand": "Subaru",
      "model": "Outback",
      "variant": "2.5 Adventure Xfuel E85",
      "model_year": 2021,
      "first_registration": "2021-03-12",
      "price": 289900,
      "odometer_km": 48200,
      "fuel": "bensin",
      "transmission": "automat",
      "body": "kombi",
      "drive": "awd",
      "power_hp": 169,
      "color": "Grå metallic",
      "towbar": true,
      "equipment": [
        "Dragkrok",
        "Navigation",
        "Motorvärmare"
      ],
      "images": [
        "https://www.bossesbil.se/bilder/19363711-1.jpg",
        "https://www.bossesbil.se/bilder/19363711-2.jpg"
      ],
      "warranty": "MRF-garanti 12 mån",
      "published_at": "2026-08-31T15:51:37+02:00"
    }
  ]
}

Endpoints

POST	/api/feed/v1/register	Registrera en feed. Body: partner, contact_email, dealer_name, dealer_orgnr, dealer_website, mode (pull\|push), feed_url, feed_auth_header. Svar: slug, token (visas en gång), push_url, status_url.
POST	/api/feed/v1/push/{slug}	Push av hela lagret. Header Authorization: Bearer {token}. Body: dokumentet. 200 = sparat, 422 = valideringsfel per fält (inget sparas), 401 = fel token, 413 = för stort.
GET	/api/feed/v1/status/{slug}	Status. Header Authorization: Bearer {token}. Svar: status (pending\|review\|approved\|rejected\|paused), intake-rapport, antal aktiva annonser, senaste fel.
GET	/api/feed/v1/schema	JSON Schema (draft 2020-12) för dokumentet.

Validering och godkännande

Varje dokument valideras mot fälten ovan. Därefter matchas bilarna mot vår modellkatalog och feeden får en rapport: andel matchade bilar, fyllnadsgrad för pris, miltal och bilder, median km/år, och hur många regnr som redan finns aktiva från andra källor. Grindar: minst 60 % matchade, 70 % med pris, 80 % med miltal och bild, median 3 000–40 000 km/år. En feed som passerar godkänns normalt inom en arbetsdag. Rapporten syns alltid i status-endpointen, även när något fallerar, så att ni kan rätta och skicka igen.

Snabbstart (push)

curl -X POST https://bilbetyg.se/api/feed/v1/register \
  -H 'Content-Type: application/json' \
  -d '{"partner":"Mitt system","contact_email":"dev@exempel.se","dealer_name":"Bosses Bil & Motor AB","dealer_orgnr":"556123-4567","mode":"push"}'
# → {"slug":"bosses-bil-motor-ab","token":"…","push_url":"…"}

curl -X POST https://bilbetyg.se/api/feed/v1/push/bosses-bil-motor-ab \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  --data-binary @lager.json

curl https://bilbetyg.se/api/feed/v1/status/bosses-bil-motor-ab -H 'Authorization: Bearer <token>'