Rakentajaoutlet.fi — Public API v1

Base URL: https://rakentajaoutlet.fi/api/v1 Version: v1 Authentication: None (public read-only) CORS: Access-Control-Allow-Origin: * Cache: 300 s (unless overridden per endpoint) Machine-readable spec: /api/v1/openapi.json

Toteutus: blueprints/public_api.py. Suunniteltu 3rd party -integraattoreille: ChatGPT-kauppa, Google Merchant API, MCP-kumppanit, muut agentit.

Sopimus (contract)

Additive-only in v1 — kentät voivat lisääntyä, mutta olemassa olevat kentät eivät poistu eivätkä muuta tyyppiään
Rikkovat muutokset julkaistaan uudessa versiossa (/api/v2/*)
Legacy-polut /api/* (ilman versiota, toteutus blueprints/api.py) ovat sisäisiä ja voivat muuttua ilman ennakkoilmoitusta. Älä käytä integraatiossa.

Endpoints

`GET /api/v1/openapi.json`

Täysi OpenAPI 3-spec — kaikki endpointit, parametrit, kenttätyypit machine-readable.

`GET /api/v1/products`

Tuotelistaus, haku ja tarkat tunniste-lookupit.

Parametrit:

Nimi	Tyyppi	Kuvaus
`q`	string	Vapaamuotoinen haku (jaetaan sanoiksi, kaikki sanat AND, sanat matchaavat nimestä, kuvauksesta, SKU:sta, EAN:sta, kategoriasta)
`sku`	string	Tarkka SKU-lookup. Palauttaa 0–1 tuotetta.
`ean`	string	Tarkka EAN-lookup raakadatana (voi olla GTIN tai osanumero). Palauttaa 0–1 tuotetta.
`gtin`	string	Semanttinen alias `ean`:lle — käytä kun etsit vain aitoja GTIN-koodeja
`brand`	string	Tarkka brändisuodatin (esim. `ABB`, `Ensto`, `Schneider`)
`updated_since`	ISO-8601	Inkrementaalisynkka: vain viime kerran jälkeen muuttuneet. Käytä `updated_at`-kenttää cursor:iksi (esim. `?updated_since=2026-08-05T00:00:00`)
`since_id`	int	Kursorisivutus: palauttaa tuotteet joilla `id > since_id`, järjestys id ASC. Vakaampi kuin page-sivutus kun katalogi muuttuu. Ohittaa `page`/`sort`. Vastauksessa `pagination.next_since_id` = viimeisen tuotteen id → anna seuraavaan pyyntöön. `null` = end of stream.
`category`	int	Kategoria-ID
`in_stock`	bool	Oletus `true` (suodattaa vain saatavilla). `false` näyttää kaikki.
`page`	int	Sivunumero, 1-alkava (oletus 1)
`per_page`	int	Tuloksia per sivu, 1–100 (oletus 24)
`sort`	string	`name` (oletus) · `price_asc` · `price_desc` · `newest`

Vastaus (product-objektin muoto):

{
  "id": 5758,
  "sku": "3660170",
  "ean": "OXP12X395",
  "gtin": null,
  "mpn": "OXP12X395",
  "name": "Akseli Abb Oxp12X395",
  "brand": "ABB",
  "category": "Kytkimet ja pistorasiat",
  "description": "Akseli pistoolivääntimille OHB/OHY_J12_...",
  "price_gross": 32.83,
  "price_net": 26.16,
  "vat_percent": 25.5,
  "currency": "EUR",
  "in_stock": false,
  "stock_quantity": 0,
  "supplier_in_stock": true,
  "supplier_stock_quantity": 5,
  "available_for_order": true,
  "availability_status": "supplier_stock",
  "estimated_delivery_min_days": 2,
  "estimated_delivery_max_days": 5,
  "weight_kg": 0.1,
  "unit": "kpl",
  "image_url": "https://rakentajaoutlet.fi/static/images/products/ahlsell_3660170.webp",
  "product_url": "https://rakentajaoutlet.fi/tuote/5758/akseli-abb-oxp12x395",
  "updated_at": "2026-08-05T13:30:15"
}

Esimerkkejä:

# Tuotelistaus, sivu 1 (default 24/sivu)
curl 'https://rakentajaoutlet.fi/api/v1/products'

# Haku "abb"
curl 'https://rakentajaoutlet.fi/api/v1/products?q=abb'

# Tarkka SKU-lookup
curl 'https://rakentajaoutlet.fi/api/v1/products?sku=3660170'

# Tarkka EAN-lookup
curl 'https://rakentajaoutlet.fi/api/v1/products?ean=6416240834239'

# Kategoria + iso sivukoko
curl 'https://rakentajaoutlet.fi/api/v1/products?category=42&per_page=100'

`GET /api/v1/products/<id>`

Yhden tuotteen täydet tiedot ID:llä. Kaksi kuvakenttää:

images — legacy: ["url", "url", ...] (pelkät URL:t)
media — 5.8.2026: strukturoitu [{url, alt, position}, ...] alt-teksteillä

{
  "id": 5758,
  ...kaikki muut kentät kuten yllä...,
  "images": [
    "https://rakentajaoutlet.fi/static/images/products/ahlsell_3660170.webp"
  ],
  "media": [
    {
      "url": "https://rakentajaoutlet.fi/static/images/products/ahlsell_3660170.webp",
      "alt": "Akseli Abb Oxp12X395",
      "position": 0
    }
  ]
}

Alt-tekstit generoidaan automaattisesti tuotenimen pohjalta (SEO + saavutettavuus). Käytä media-kenttää uusissa integraatioissa; images säilyy taaksepäin yhteensopivuutta varten.

Virheet: - 404 — {"error": "Product not found"}

`GET /api/v1/products/<id>/availability`

Kevyt saatavuustarkistus ilman koko tuotetietoa.

Vastaus:

{
  "id": 5758,
  "name": "Akseli Abb Oxp12X395",
  "in_stock": false,
  "stock_quantity": 0,
  "supplier_in_stock": true,
  "supplier_stock_quantity": 5,
  "availability_status": "supplier_stock",
  "estimated_delivery_min_days": 7,
  "estimated_delivery_max_days": 14,
  "unit": "kpl"
}

`POST /api/v1/products/lookup`

Bulkki-lookup useille tunnisteille yhdellä pyynnöllä. Halvempi kuin N × GET.

Payload (kaikki avaimet valinnaisia, yhdistetään OR:lla):

{
  "gtins": ["7333123856609", "4099854305962"],
  "eans":  ["osanumero123"],
  "skus":  ["3660170", "5001"],
  "ids":   [1234, 5678]
}

Max 200 tunnistetta yhteensä.

Vastaus (KO-kanoninen muoto, 5.8.2026 yhtenäistys):

{
  "found": 4,
  "products": [<product>, <product>, ...],
  "not_found": ["4099854305962", "5001"],
  "requested": 5
}

Sama koodi toimii KO:lla (okunkoneosa.fi) ja RO:lla (rakentajaoutlet.fi).

Virheet: - 400 — {"error":"no_lookups", ...} — vaadittu vähintään yksi lista - 413 — {"error":"too_many_lookups", ...} — yli 200 tunnistetta

`GET /api/v1/categories`

Koko kategoriapuu.

Konventiot (huomioi ennen integraation rakentamista)

Hinnat

price_gross on ALV mukana (Suomessa yleensä 25,5%)
price_net on valmiiksi laskettu ALV0 — käytä tätä suoraan
vat_percent kertoo tarkan ALV-prosentin per tuote

Saatavuus (5 kenttää saman asian ympärillä)

Kenttä	Merkitys
`in_stock`	true = oma varasto
`stock_quantity`	oma saldo (nyt aina 0 — Rakentaja Outlet on Ahlsell-dropship)
`supplier_in_stock`	true = Ahlsell-toimittajalla saldoa
`supplier_stock_quantity`	Ahlsell-saldo
`available_for_order`	käyttökelpoisin: true jos joko oma tai toimittaja
`availability_status`	`"in_stock"` \| `"supplier_stock"` \| `"out_of_stock"`
`estimated_delivery_min_days` / `_max_days`	Arvioitu toimitusaika päivissä

Sama tieto myös rakenteisesti availability-objektissa (5.8.2026 additive):

"availability": {
  "status": "supplier_stock",
  "available_for_order": true,
  "stock_own": 0,
  "stock_supplier": 110,
  "estimated_delivery": {
    "min_days": 2,
    "max_days": 5,
    "unit": "business_days"
  }
}

EAN / GTIN / MPN

Kolme kenttää saman datan ympärillä:

Kenttä	Kuvaus
`ean`	Raakadata DB:stä. Voi olla aito EAN tai valmistajan osanumero.
`gtin`	Validoitu GTIN-8/12/13/14 GS1 mod-10 -tarkistuksella. `null` jos ei kelpaa.
`mpn`	Valmistajan osanumero (Manufacturer Part Number). Täytetty kun `ean` on osanumero eikä GTIN.

Käyttö: - Feed Googlen Merchant API:iin? → käytä gtin-kenttää suoraan (ei tarvitse validoida uudelleen) - Kaupan haku EAN:lla? → ?gtin=6416240834239 tai ?ean= (sama tietokantahaku) - Vastaava tuote hakemalla? → yhdistä brand + mpn

Data: ~21 % tuotteista on aito GTIN, ~79 % vain osanumero (mpn). null on odotettava tulos jos ei löydy.

Kuvat ja URL:t

image_url on absoluuttinen URL (https://rakentajaoutlet.fi/static/...)
product_url on absoluuttinen URL tuotesivulle (rakentaja voi käyttää suoraan)

Rate limiting

Ei kovaa API-tason rajoitusta v1:ssä
CORS sallii selainkutsut

Muutosloki

v1 (2026-07) — Ensimmäinen julkaisu (ChatGPT-kaupparjaan)
2026-08-05 — Additive-lisäykset (kaikki taaksepäin yhteensopivia):
Uudet parametrit ?sku=, ?ean=, ?gtin=, ?brand=, ?updated_since=
Uudet vastauskentät gtin (GS1-validoitu), mpn (Manufacturer Part Number), updated_at (inkrementaalisynkka)
Uusi kenttä media [{url, alt, position}] — strukturoitu vaihtoehto images:iin, mutta legacy images:[str] säilyy sopimuksen mukaan
2026-08-05 (myöhemmin päivä) — KO-yhtenäistys (Macbook-suositus, ei integraattoreita ehtinyt):
/api/v1/products vastauskuori poistettu litteät page/per_page/total/total_pages root-kentät — kaikki metadata pagination-objektissa (KO-kanoninen)
pagination.next_since_id populoitu aina kun has_more=true (aiemmin vain kursorimoodissa)
pagination.has_more boolean lisätty
/api/v1/products/lookup vastausrakenne yhtenäistetty KO:n kanssa: {found, products, not_found flat, requested} (aiemmat matches/match_count/requested_count ja per-tyyppinen not_found poistettu)
created_at kenttä lisätty product-objektiin
Toimitusaika-korjaus: supplier_stock on nyt 2-5 pv (aiemmin 7-14) — yhdenmukainen verkkokaupan luvatun kanssa
docs/API_V1.md -dokumentaatio repoon (ihmisluettava, täydentää /api/v1/openapi.json:ia)

Yhteystiedot

Tekniset kysymykset: support@miamo.fi
Rakentaja Outlet: info@rakentajaoutlet.fi