Kehittäjille · Suomi · fi-FI · EUR

Tarjouspyyntö-API: ohje tekoälyavustajille

Tekoälyavustaja voi lähettää asiakkaan hyväksymän tarjouspyynnön kontista tai työmaatilasta Suomessa. Rajapinta on julkinen, ja sitä voi käyttää ilman tiliä tai API-avainta.

Asiakkaan suostumuksella pyyntö ja yhteystiedot välitetään Quotboxin kautta enintään viidelle rekisteröityneelle yritykselle. Tarjouksen laatii toimittaja. Rajapinta ei anna hintaa, tee tilausta tai takaa tarjouksen saamista.

Rajapinnan osoite ja käyttö

GET — lue rajapinnan kuvaus

/api/agents/v1/fi/devis

GET palauttaa ajantasaisen JSON-kuvauksen: kentät, sallitut arvot, ehdot, suostumustekstin ja esimerkin. Linkin avaaminen ei lähetä tarjouspyyntöä.

POST — lähetä asiakkaan pyyntö

https://containerfjord.com/api/agents/v1/fi/devis

Lähetä UTF-8-koodattu JSON samaan osoitteeseen ja määritä sisältötyyppi HTTP-otsakkeessa.

Content-Type: application/json

Rajapinnan versionumero on 1. JSON-rungon enimmäiskoko on 32 KiB (32 768 tavua), ja rungon lukemisen aikaraja on 10 sekuntia. Osoitteen maatunnus fi valitsee Suomen rajapinnan (kieli- ja aluetunnus fi-FI, valuutta EUR). Kenttien nimet ja koodiarvot ovat yhteisiä eri maissa: älä käännä niitä.

  1. Lue ajantasainen JSON-kuvaus ja täytä sen kentät asiakkaan tiedoilla.
  2. Näytä asiakkaalle suostumusteksti ja odota nimenomaista hyväksyntää.
  3. Lähetä pyyntö ja käsittele vastaus alla olevan ohjeen mukaan.

Näytä suostumusteksti asiakkaalle ennen lähettämistä

Näytä asiakkaalle Suomen JSON-kuvauksen suostumusteksti kokonaan. Älä aseta hyväksyntää asiakkaan puolesta. Lähetä tiedot vasta, kun asiakas on nimenomaisesti hyväksynyt niiden välittämisen kuvattuun tarkoitukseen.

Hyväksyn, että ContainerFjord välittää tarjouspyyntöni ja yhteystietoni Quotboxin kautta enintään 5 rekisteröityneelle ammattilaisyritykselle, jotka voivat laatia tarjouksia hankkeestani Suomessa. Tämä pyyntö ei rekisteröi minua mainoskampanjoihin.
consentement
Totuusarvo true, ei merkkijono "true".
consentementQuotboxAgent
Täsmällinen versio:quotbox-marketplace-v1

Käytä aina GET-kuvauksen nykyistä tekstiä ja versiota. Katso tietosuojaseloste ja rekisterinpitäjän yhteystiedot.

Jokaisessa pyynnössä vaadittavat kentät

Lähetä yksi JSON-objekti, jossa ovat kaikki taulukon kentät. Vuokraukseen ja tiettyihin tuoteryhmiin tarvitaan myös lisätietoja. Tuntemattomat kentät hylätään.

KenttäArvo ja käyttötarkoitus
familleTuoteryhmän koodi. Merikontin koodi on achat. Katso muut tuoteryhmät JSON-kuvauksesta.
modeachat = osto, location = vuokraus.
formatKokokoodi, esimerkiksi 20DRY, 40DRY tai 40HC. Käytä arvoa aDefinir, jos kokoa ei ole vielä valittu.
quantiteKappalemäärä kokonaislukuna 1–50.
codePostalSuomen postinumero merkkijonona: viisi numeroa, esimerkiksi "00100". Arvo 00000 ei kelpaa.
prenomAsiakkaan etunimi, 1–80 merkkiä. Pelkkä välilyönti ei kelpaa.
nomAsiakkaan sukunimi, 1–80 merkkiä. Pelkkä välilyönti ei kelpaa.
emailAsiakkaan sähköpostiosoite, enintään 254 merkkiä. Osoitteen pitää sisältää myös kelvollinen verkkotunnus.
consentementTotuusarvo true vasta asiakkaan nimenomaisen hyväksynnän jälkeen.
consentementQuotboxAgentKopioi suostumuksen version tunniste GET-kuvauksesta sellaisenaan.
telephoneAsiakkaan puhelinnumerossa on oltava 6–15 numeroa ja yhteensä enintään 30 merkkiä. Välilyönnit, sulkeet, pisteet ja yhdysmerkit ovat sallittuja. Plusmerkkiä voi käyttää numeron alussa. Alun ja lopun välilyöntejä ei lasketa merkkirajaan.

Anna quantite ja dureeMois JSON-lukuina. Anna postinumero merkkijonona, jotta alkunolla säilyy. Palvelu tarkistaa puhelinnumeron myös silloin, kun pyyntö täyttää JSON-skeeman ehdot.

Milloin tarvitaan lisätietoja?

Vuokraus

Kun mode on location, anna vuokra-aika kuukausina kentässä dureeMois. Käytä kokonaislukua väliltä 1–120.

Työmaatilojen kokonaisuus

Kun famille on baseVie ja usageBungalow puuttuu, anna osto- ja vuokrauspyynnössä dureeMois kuukausina sekä chantier. Ilmoita chantier-objektissa miesten määrä (effectifHommes) ja naisten määrä (effectifFemmes). Kummankin arvon on oltava kokonaisluku väliltä 0–2 000, ja henkilöitä on oltava yhteensä vähintään yksi.

Parakki tiettyyn käyttöön

Kun käytät baseVie-ryhmässä usageBungalow-kenttää, jätä chantier pois. Jos ilmoitat kunnon etat-kentässä, sallitut arvot ovat neuf, occasion ja peuImporte.

Tuoteryhmän omat tiedot

Käytä lieuStockage-kenttää vain, kun famille on stockage. Jos ilmoitat kentän oston yhteydessä, käytä arvoa surSite. Kentät projetAmenage ja usageAmenage kuuluvat vain ryhmään amenage. Kentät regimeFroid ja temperatureCible kuuluvat vain ryhmään frigorifique. Työmaatiedot kuuluvat vain ryhmään baseVie.

Käytä etat-kentässä arvoa peuImporte, jos asiakas ei rajaa kontin kuntoa. JSON-kuvauksessa arvo näkyy nimellä ”Suositeltava”.

Muut kentät ja niiden ehdot

Kuvaus sisältää myös seuraavat kentät. Osa niistä on yllä mainituissa tilanteissa pakollisia. Tarkista kunkin kentän tyyppi, pituus, sallitut arvot ja ehdot ajantasaisesta JSON-kuvauksesta.

  • etat
  • usageBungalow
  • lieuStockage
  • projetAmenage
  • usageAmenage
  • regimeFroid
  • temperatureCible
  • dureeMois
  • chantier
  • commune
  • dateSouhaitee
  • acces
  • levageSurPlace
  • raccordElec
  • raccordEau
  • raccordAssainissement
  • precisions
  • societe

Ilmoita tavoitelämpötila celsiusasteina merkkijonona kentässä temperatureCible, esimerkiksi "-18". Käytä enintään kahta desimaalia. Sallittu vaihteluväli on −80…+40 °C. Hyväksytty arvo ei takaa tietyn kylmäkontin suorituskykyä.

JSON-esimerkki: 20 jalan kontin osto

Alla on GET-kuvauksen esimerkkipyyntö. Korvaa esimerkkitiedot asiakkaan hyväksymillä tiedoilla ennen lähettämistä. Älä lähetä esimerkkiä sellaisenaan. Tuotantorajapinnan POST-pyyntö voi tallentaa oikean tarjouspyynnön.

Vieritä koodia tarvittaessa sivusuunnassa.

{
  "famille": "achat",
  "mode": "achat",
  "format": "20DRY",
  "quantite": 1,
  "codePostal": "00100",
  "commune": "Helsinki",
  "prenom": "Test",
  "nom": "Example",
  "email": "test\u0040example.com",
  "consentement": true,
  "consentementQuotboxAgent": "quotbox-marketplace-v1",
  "telephone": "+358400000000"
}

JSONissa @-merkin voi kirjoittaa myös muodossa \u0040. Jäsennetty sähköpostiosoite on sama kummallakin tavalla. Rajapinta ei edellytä tätä esitystapaa.

Käsittele vastaus ennen uutta yritystä

Lue sekä HTTP-koodi että vastauksen JSON-sisältö. Kenttä reference yksilöi tallennetun pyynnön. Erityisesti 202- ja 502-vastauksissa pyyntö on jo tallessa, vaikka välitystä ei ole vahvistettu.

200

Quotbox on vahvistanut vastaanoton

Pyyntö on tallennettu ja välitetty Quotboxille. Säilytä pyynnön viite (reference). Vastaus ei ole toimittajan tarjous eikä vahvista saatavuutta.

202

Pyyntö on tallennettu ja odottaa välitystä

Vastauksessa enregistree on true, transmis on false ja etat on en_attente. Säilytä pyynnön viite (reference). Älä luo samaa pyyntöä uudelleen.

400

Pyynnön sisältöä ei voitu lukea

Tarkista, että pyynnön sisältö on kelvollista UTF-8-koodattua JSONia. Tarkista myös mahdollinen Content-Length-otsake.

408

Pyynnön lukemisen aikaraja ylittyi

Tarkista yhteys. Palvelimen on saatava luettua pyynnön sisältö 10 sekunnissa.

413

Pyyntö on liian suuri

Pyynnön sisältö saa olla enintään 32 KiB (32 768 tavua).

415

Sisältötyyppi tai merkistökoodaus ei kelpaa

Käytä Content-Type: application/json ja UTF-8-koodausta.

422

Kentissä on korjattavaa

Tarkista vaaditut kentät, arvot ja tuoteryhmän ehdot. Jos vastauksessa on champs-lista, se kertoo, missä kentissä on virheitä. Lue myös vastauksen viesti.

429

Pyyntöjä on tullut liian tiheästi

Odota Retry-After-otsakkeen ilmoittama sekuntimäärä ennen uutta yritystä.

502

Pyyntö on tallennettu, mutta välitys vaatii toimenpiteitä

Vastauksessa enregistree on true ja etat on action_requise. Säilytä pyynnön viite (reference) ja ota yhteyttä ContainerFjordiin. Älä luo samaa pyyntöä uudelleen.

503

Vastaanotto ei ole käytettävissä

Vastaanotto voi olla poissa käytöstä tai tallennus voi epäonnistua. Tarkista vastauksen tiedot. Jos pyynnön tila jää epäselväksi, ota yhteyttä ContainerFjordiin.

Jos et saa vastausta, pyyntö on silti voinut tallentua. Selvitä sen tila ContainerFjordin kanssa ennen kuin lähetät saman pyynnön uudelleen. Ilmoita pyynnön viite, jos se on tiedossasi.

Päivitetty . Tarkista rajapinnan ajantasaiset ehdot GET-kuvauksesta.