B2B-dokumentaatio

B2B API – hae tilaus- ja tuotetietoja automatisoidusti

REST-API:mme on jokaisen asiakastilin omaavan asiakkaan käytettävissä ja mahdollistaa tilaus- ja tuotetietojen automatisoidun hakemisen sekä integroinnin omiin järjestelmiin.

vpn_key Avaa API-pääsy tilillä Yritysasiakkaat-sivu

Todennus

Kaikki API-pyynnöt edellyttävät voimassa olevaa API-avainta, joka lähetetään mukana HTTP-otsikossa. API-pääsy on sidottu asiakastiliisi ja on lähtökohtaisesti asiakastilien käytettävissä.

info Et tarvitse erillistä B2B-hakemusta: kirjaudu sisään asiakastililläsi, avaa API-välilehti ja luo siellä API-avaimesi. API-pääsyyn →

Otsikkomuoto

HTTP Request Header

X-API-Key: YOUR_API_KEY_HERE
Content-Type: application/json
Accept: application/json

Esimerkki cURL:lla

cURL

curl -X GET "https://artumos.com/api/v1/orders" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -H "Accept: application/json"

Base URL

Kaikki päätepisteet ovat suhteessa seuraavaan Base URL:iin:

Base URL

https://artumos.com/api/v1

Kaikki vastaukset palautetaan muodossa JSON palautetaan (Content-Type: application/json).

Rate Limits

Plan	Pyyntöä / minuutti	Pyyntöä / päivä
Asiakastili	60	5.000
Laajennettu raja	pyynnöstä	pyynnöstä

Ylityksessä palautetaan HTTP 429 Too Many Requests palautetaan. Otsikko Retry-After sisältää odotusajan sekunteina.

Virhekoodit

HTTP-Code	Merkitys
`200 OK`	Pyyntö onnistui
`400 Bad Request`	Virheelliset parametrit
`401 Unauthorized`	Puuttuva tai virheellinen API-avain
`403 Forbidden`	Ei käyttöoikeutta tähän resurssiin
`404 Not Found`	Resurssia ei löytynyt
`429 Too Many Requests`	Rate Limit ylitetty
`500 Internal Server Error`	Palvelinvirhe – ota yhteyttä tukeen

Virhe-Response-muoto

JSON

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

Päätepiste: Tilaukset

GET /api/v1/orders Kaikki tilin tilaukset

Parameter	Tyyppi	Kuvaus
`page`	integer	Sivu (oletus: 1)
`per_page`	integer	Merkintöjä per sivu (maks. 100)
`status`	string	`paid` \| `pending` \| `all`

Beispiel-Response

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "ORD-12345",
        "status": "paid",
        "total": 49.99,
        "currency": "EUR",
        "created_at": "2026-01-15T10:30:00Z",
        "items_count": 2
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 42
    }
  }
}

GET /api/v1/orders/{order_id} Hae yksittäinen tilaus

Päätepiste: Tuote- ja tilaustiedot

GET /api/v1/orders/{order_id}/codes Kaikki tilauksen tuotetiedot

Beispiel-Response

{
  "success": true,
  "data": {
    "order_id": "ORD-12345",
    "codes": [
      {
        "id": "CODE-789",
        "product_name": "Beispielprodukt vom Marktplatz",
        "product_sku": "ART-PRODUCT-001",
        "product_info": "Hinweise laut Verkäuferangaben",
        "delivery_url": "https://...",
        "delivered_at": "2026-01-15T10:31:00Z",
        "status": "active"
      }
    ]
  }
}

GET /api/v1/codes/{code_id} Hae yksittäinen tuotetieto

warning Tuote- ja tilaustietoja saa käyttää vain kyseisen tilauksen ja myyjätietojen puitteissa. Väärinkäyttöinen edelleenluovutus voi rikkoa käyttöehtoja.

Päätepiste: Tuotteet

GET /api/v1/products Hae tuoteluettelo

Parameter	Tyyppi	Kuvaus
`category`	string	Suodata kategoria-slugilla
`in_stock`	boolean	Vain saatavilla olevat tuotteet
`page`	integer	Sivu

Beispiel-Response

{
  "success": true,
  "data": {
    "products": [
      {
        "id": 42,
        "sku": "ART-PRODUCT-001",
        "name": "Beispielprodukt vom Marktplatz",
        "price": 49.99,
        "currency": "EUR",
        "in_stock": true,
        "category": "handmade"
      }
    ]
  }
}

Webhooks

Webhookit mahdollistavat reaaliaikaisten ilmoitusten vastaanottamisen, kun tilauksia tai koodeja toimitetaan. Webhook-URL:t voidaan tallentaa asiakastilille.

Saatavilla olevat tapahtumat

Event	Kuvaus
`order.paid`	Tilaus on maksettu
`codes.delivered`	Koodit on toimitettu
`order.refunded`	Tilaus on hyvitetty

Webhook Payload

POST – Sinun Webhook-päätepisteesi

{
  "event": "codes.delivered",
  "timestamp": "2026-01-15T10:31:05Z",
  "data": {
    "order_id": "ORD-12345",
    "codes_count": 2
  },
  "signature": "sha256=..."
}

Varmenna allekirjoitus Webhook-salaisuudellasi: HMAC-SHA256(payload, webhook_secret)

Usein kysytyt kysymykset

Kuka voi käyttää B2B API:a?

Jokainen asiakas, jolla on asiakastili, voi käyttää API-pääsyä. Kirjaudu sisään asiakastilillesi ja käytä siihen liittyvää API-avainta todennettuihin pyyntöihin.

Missä muodossa vastaukset ovat?

Kaikki vastaukset palautetaan JSON-muodossa. Root-objekti sisältää aina success: true/false sekä joko data tai error.

Voinko tehdä tilauksia API:n kautta?

Ensimmäisessä versiossa API palvelee tilausten, tilaus- ja tuotetietojen hakemista. Kirjoittavat tilaus-päätepisteet otetaan erikseen käyttöön heti, kun ne ovat saatavilla.

Onko olemassa Sandbox-ympäristöä?

Kyllä. Sandbox voidaan aktivoida asiakastilillä välilehdellä „API-pääsy“ ja se on suoraan sidottu kyseiseen API-avaimeen.