Ilmoitukset

Tilat

Tila	Merkitys
draft	Luonnos
preview	Esikatselu, kentät validoitu, voidaan julkaista
waiting	Julkaistu, myyntiaika alkaa myöhemmin
open	Myynnissä
closed	Suljettu

draft   → PUT status: preview   → preview
preview → PUT status: published → open
preview → PUT status: published → waiting, jos listTime myöhemmin
open    → PUT status: closed    → closed

Luo ilmoitus

POST/1.1/itemsVaatii tokenin

Luo ilmoituksen tilaan preview. Rungolla {"status": "draft"} luodaan tyhjä luonnos ilman validointia.

Parametri	Tyyppi	Pakollinen	Kuvaus
title	string	kyllä	Otsikko, 1–60 merkkiä
description	string	kyllä	Kuvaus, HTML sallittu
categoryId	int	kyllä	Kolmannen tason osasto, katso Osastot ja suodattimet
condition	string	kyllä	new, like-new, good, acceptable tai weak
saleMethod	string	kyllä	buy-now tai auction
buyNowPrice	number	Osta heti	Hinta¹
startingPrice	number	huutokauppa	Lähtöhinta¹
quantity	int	Osta heti	Määrä 1–32767, huutokaupassa aina 1
openDays	int	kyllä²	Myyntiaika päivinä, katso Myyntiaika
listTime	string	²	Alkamisaika ISO 8601 -muodossa, enintään 2 h menneisyydessä
closingTime	string	²	Päättymisaika ISO 8601 -muodossa, tulevaisuudessa
postalCode	string	kyllä³	Postinumero, paikkakunta päätellään siitä
isLocationAbroad	int	ei	1 = tuote on ulkomailla
country	string	ei	Maa, kun isLocationAbroad on 1
deliveryMethods	string[]	ei	shipment, pickup tai seller-delivers. Viimeinen vain kun isHuutoturva on päällä.
deliveryPrice	number	ei	Toimituskulut¹
deliveryTerms	string	ei	Toimitusehdot
paymentMethods	string[]	ei	wire-transfer tai cash
paymentTerms	string	ei	Maksuehdot, enintään 1000 merkkiä
offersAllowed	int	ei	1 sallii hintaehdotukset, 0 estää
identificationRequired	int	ei	1 = vain tunnistautuneet ostajat
filters	object	ei	Tuotetiedot, katso Suodattimet
republish	int	ei	1 = automaattinen uusinta⁴
vat	number	ei	ALV-prosentti 0–100⁴
marginalTax	int	ei	1 = voittomarginaaliverotus⁴
minimumIncrease	number	ei	Huutokaupan minimikorotus⁴
minimumFeedback	int	ei	Ostajan vähimmäispalaute⁴
isHuutoturva	bool	ei	true tai 1 = Huutoturva-ilmoitus, katso Huutoturva
hturPackageCode, packageWeight		ei	Katso Huutoturva

¹ Euroina, enintään 2 desimaalia, ei negatiivinen. ² Anna joko openDays tai sekä listTime että closingTime. Jos openDays on mukana, ajat jätetään huomiotta. ³ Ei tarvita, jos isLocationAbroad on 1. ⁴ Vain osalle tilityypeistä, katso omat asetukset.

curl -X POST https://api.huuto.net/1.1/items \
  -H 'X-HuutoApiToken: <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Taru Sormusten herrasta -elokuvatrilogia",
    "description": "<p>Kaikki kolme elokuvaa.</p>",
    "categoryId": 847,
    "condition": "good",
    "saleMethod": "buy-now",
    "buyNowPrice": 24.90,
    "quantity": 1,
    "openDays": 30,
    "postalCode": "00100",
    "deliveryMethods": ["shipment", "pickup"],
    "paymentMethods": ["wire-transfer"],
    "filters": { "year": 2003 }
  }'

Vastaus on 201 ja sama olio kuin kutsussa Hae ilmoitus.

Tila	Syy
400	Validointivirhe. field kertoo kentän, myös kun tilisi ei saa käyttää kenttää.
400	Omista tiedoista puuttuu nimi, puhelinnumero tai osoite
400	Luonnoksia on jo 10. Koskee vain luonnoksen luontia ja uudelleenlistausta.

Myyntiaika

Myyntitapa	Tavallinen tili	Yritys, kauppa, HuutoPlus, PowerSeller
Huutokauppa	1–60 päivää	1–60 päivää
Osta heti	1–60 päivää	1–120 päivää

openDays lasketaan luonti- tai muokkaushetkestä, ei julkaisusta.

Listaa uudelleen

POST/1.1/itemsVaatii tokenin

Kopioi oman suljetun ilmoituksen tiedot ja kuvat uuteen luonnokseen. Hintavarausta ei kopioida.

Parametri	Tyyppi	Pakollinen	Kuvaus
originalId	int	kyllä	Suljetun ilmoituksen id

{ "originalId": 123456789 }

Vastaus on 201 ja uusi ilmoitus tilassa draft. Muokkaa se tilaan preview ja julkaise.

Tila	Syy
400	Luonnoksia on jo 10, tai omista tiedoista puuttuu osoite
404	Alkuperäistä ilmoitusta ei löydy

Huomio

Jos rungossa on myös "status": "draft", syntyy tyhjä luonnos eikä tietoja kopioida.

Hae ilmoitus

GET/1.1/items/{id}Token valinnainen

Avoimet ja suljetut ilmoitukset ovat julkisia. Tiloissa draft, preview ja waiting ilmoituksen näkee vain myyjä omalla tokenillaan.

{
  "id": 123456789,
  "title": "Taru Sormusten herrasta -elokuvatrilogia",
  "status": "open",
  "saleMethod": "buy-now",
  "buyNowPrice": 24.9,
  "currentPrice": 24.9,
  "quantity": 1,
  "listTime": "2026-10-26T14:20:36+0200",
  "closingTime": "2026-11-25T14:20:36+0200",
  "category": { "id": 847, "name": "Blu-ray - Muut" },
  "deliveryMethods": ["shipment", "pickup"],
  "paymentMethods": ["wire-transfer"],
  "isHuutoturva": false,
  "republishRemainingCount": null,
  "links": {
    "self": "https://api.huuto.net/1.1/items/123456789",
    "alternative": "https://www.huuto.net/kohteet/…/123456789",
    "images": "https://api.huuto.net/1.1/items/123456789/images",
    "purchases": null
  }
}

• alternative on ilmoituksen osoite Huuto.netissä.
• purchases on null, kunnes ilmoitus on suljettu ja myyty.
• republishRemainingCount on null muille kuin myyjälle.

Vanhat arvot

Vanhoissa ilmoituksissa deliveryMethods ja paymentMethods voivat sisältää poistuneita arvoja, kuten itella, matkahuolto, fetch, credit-transfer ja cash-on-delivery.

Muokkaa ennen julkaisua

PUT/1.1/items/{id}Vaatii tokenin

Muokkaa ilmoitusta tilassa draft tai preview. Kentät ovat samat kuin luonnissa, ja lähettämättömät kentät säilyvät. Kenttä status arvolla draft tai preview vaihtaa samalla tilan.

{ "buyNowPrice": 22.90, "openDays": 30, "status": "preview" }

Jokainen muokkaus validoidaan

Myös luonnoksen muokkaus tarkistaa kaikki pakolliset kentät, tallennetut mukaan lukien. Lähetä aina openDays tai listTime ja closingTime, koska yli 2 h vanha tallennettu listTime hylätään.

Julkaise

PUT/1.1/items/{id}Vaatii tokenin

{ "status": "published" }

Ilmoituksen pitää olla tilassa preview. Myyjä saa vahvistuksen sähköpostiin.

Tila	Syy
400	code on IDENTIFICATION_REQUIRED: myyjä ei ole tunnistautunut pankkitunnuksilla tai mobiilivarmenteella
400	Ilmoitus ei ole tilassa preview

Huomio

Julkaisupyyntö muuttaa vain tilan, muita samassa kutsussa lähetettyjä kenttiä ei tallenneta. Julkaisun jälkeen voi muuttaa vain määrää.

Päivitä määrä

PUT/1.1/items/{id}Vaatii tokenin

Ainoa muutos, joka avoimeen ilmoitukseen voidaan tehdä. Runko on JSON, jossa on täsmälleen yksi kenttä.

{ "quantity": 3 }

Tila	Syy
400	Rungossa on muitakin kenttiä: Only quantity can be updated for published items.
400	Määrä on alle 1, tai huutokaupan määrä ei ole 1
403	Ilmoitus ei ole sinun

Katso Saldo ja hinta.

Sulje

PUT/1.1/items/{id}Vaatii tokenin

{ "status": "closed" }

Päättää avoimen ilmoituksen heti ja poistaa automaattisen uusinnan. Huutokaupassa korkein huuto voittaa, jos ehdot täyttyvät.

Vinkki

Sulkeminen käsitellään taustalla, joten tila muuttuu arvoon closed pienellä viiveellä. Tilassa waiting oleva ilmoitus poistetaan.

Poista

DELETE/1.1/items/{id}Vaatii tokenin

Poistaa ilmoituksen tilassa draft tai preview. Vastaus on 204.

Tila	Syy
403	Ilmoitus ei ole sinun
404	Ilmoitusta ei löydy, tai se on muussa tilassa