Ohjeet

API kehittäjille

Yhdistä ohjelmistosi lähteiden, käsittelyn, tulosten ja hallinnan määriteltyihin toimintoihin. Tämä opas kuvaa käytettävissä olevan API:n dokumentoitujen julkaisurajoitusten puitteissa. Käyttäjä, oikeudet, tallennustila ja krediitit pysyvät Rapportly-tiliin sidottuina.

Valmistele integraatio kolmessa vaiheessa

1. 1
   Valitse käyttäjä, ympäristö ja oikeudet

   Avaa Tili → Integraatiot. Käytä testiavainta kuvitteelliseen simulaattoriin ja erillistä tuotantoavainta oikeisiin toimintoihin kuvitteellisilla tiedoilla. Ylläpitäjä myöntää vain tarvittavat oikeudet ja sopivan budjetin.

2. 2
   Harjoittele vastaanottoa ja virheitä

   Aloita simulaattorista. Tuo sitten API-sopimukset ja tarkastele synteettisiä esimerkkejä. Säilytä salaisuudet palvelimella; muutokset on oletuksena poistettu kokoelmasta käytöstä.

3. 3
   Seuraa tehtävä loppuun

   Tallenna syöte ja tehtävätunnus, tarkista aloitus ja lopputila, lue tulos, lataa saatavilla oleva tiedosto ja tarkista kulutus. Tee tämä vasta hyväksytyssä ympäristössä.

Luo API-avain

Perusosoite

https://api.rapportly.io/api/rapportly/v1

Avain kuuluu käyttäjälle

Avain delegoi yhden käyttäjän oikeudet. Ylläpitäjä määrittää ympäristön, oikeuksien ylärajan, kuukausibudjetin ja vanhenemisen. Jäsen aktivoi valmistellun avaimen ja näkee salaisuuden kerran. Jokainen pyyntö tarkistaa myös käyttäjän, paketin ja kohteen nykyiset oikeudet. Avainten hallinta käyttää käyttäjäistuntoa, tuotantotoiminnot API-avainta. Säilytä salaisuudet palvelimella ja peru kadonnut avain kohdassa Tili → Integraatiot. Zapier-tapahtumilla on oma sopimus.

GET https://api.rapportly.io/api/rapportly/v1/ping
Authorization: Bearer rply_<jouw_sleutel>

Käytä täsmällisiä sopimuksia ja esimerkkejä

Tuotannon OpenAPI kuvaa lähdekoodin sopimukset ja merkitsee osittaiset syötteet tai vastaukset. Luettelo näyttää avoimet skeemat. Postman-kokoelman osoite on virheellinen, avaimet tyhjät ja muutokset estetty oletuksena. Tuo tarkasteltavaksi ja lähetä tietoisesti kuvitteellisia tietoja hyväksytyssä ympäristössä. Tuontia ei ole vielä testattu.

• Lataa tuotannon OpenAPI-määritys
• Lataa synteettinen Postman-kokoelma
• Lataa vaiheet lähteestä tiedoston lataukseen
• Lataa skeemaluettelo ja avoimet osat

Harjoittele ensin kuvitteellisilla tehtävillä

Luo testiavain ja harjoittele keskeneräisiä tehtäviä, tuloksia, virheitä ja riittämätöntä budjettia. Simulaattori käyttää kiinteitä esimerkkejä eikä kuluta krediittejä.

1. Luo tai aktivoi kohdassa Tili → Integraatiot Test-avain haluamillasi oikeuksilla.
2. Hae GET /test/scenarios ja valitse vastauksen toiminto. Luettelo noudattaa nykyisiä oikeuksiasi.
3. Lähetä POST /test/opdrachten vain kentillä actie ja scenario: succes, verwerking_mislukt, creditbudget_bereikt tai toegang_geweigerd. Jokainen uusi harjoitus saa oman Idempotency-Key-avaimen.
4. Tallenna opdracht_id. Tilassa bezig lue GET /test/opdrachten/{id} noin viiden sekunnin kuluttua. Tarkista aina tila: HTTP200 voi sisältää myös epäonnistuneen käsittelyn.

POST https://api.rapportly.io/api/rapportly/v1/test/opdrachten
Authorization: Bearer rply_test_<jouw_testsleutel>
Idempotency-Key: test-rapport-0001
Content-Type: application/json

{
  "actie": "rapport.start",
  "scenario": "succes"
}

Esimerkki vaatii rapport.start-toiminnon luetteloosi. Yhteysongelman jälkeen toista samat tiedot ja Idempotency-Key.

• Lataa simulaattorin opas
• Lataa Postman-harjoituskokoelma
• Lataa simulaattorin OpenAPI

Hae vain tarvitsemasi tiedot

Etsi käytettävissä olevia asiakaskansioita, keskusteluja ja raportteja. /acties näyttää toiminnot ja oikeudet, /gebruik budjetin ja varaukset, /verzoeken teknisen historian. Keskeneräisellä käsittelyllä ei vielä ole tulosta. Raporttilinkit ovat voimassa 15 minuuttia; lue raportti uudelleen saadaksesi uuden linkin.

Päivitä asiakashallintaa

Ohjelmistosi voi muokata toimiston malleja, tallentaa henkilökohtaisia hakuja, kirjata käynnin ja luoda asiakasprosessin. Käytä asianmukaisia hallintaoikeuksia ja vahvista jokainen muutos. Lue ensin nykyinen versio ja säilytä sama pyynnön tunniste, jos vastaus katoaa. Vanhan pyynnön toistaminen ei saa kumota uudempaa muutosta. Tuotantotesti tarkistaa haut, käynnit ja asiakasprosessit sekä siivouksen ja avainten mitätöinnin. Toimiston malleja ainoastaan luettiin; kirjoittamista testattiin paikallisesti ja CI:ssä. Ladattava opas kuvaa neljä reittiä ja niiden todisteiden rajat.

Vertaa kahta tallennettua versiota

Vertaa saman tallennetun raporttitekstikentän tai keskustelukentän kahta olemassa olevaa versionumeroa ilman uutta tekoälykäsittelyä. Tämä sopimus on testattu paikallisesti ja CI:ssä; CRM:n tuotantotesti ei osoita vertailun toimintaa tuotannossa. Puuttuvaa historiaa ei täydennetä nykyisellä tekstillä. Pitkät erot lyhennetään enintään 8000 merkkiin kummallakin puolella, ja lyhentäminen merkitään näkyvästi. Vertailu ei koske PowerPointia, tarjouslaskelmia, saatekirjeitä tai muotoilua. Nykyiset lukuoikeudet ja tietosuojaehdot ovat edelleen voimassa.

Pyydä kustannusarvio etukäteen

POST /generatieplan näyttää raportin, tarjouksen tai keskustelupaketin odotetut vaiheet ja krediitit. Käytä gebruik:lezen-oikeutta. Laskenta ja tiimiasetukset vastaavat verkkosivustoa.

Arvio ei käynnistä käsittelyä eikä veloita krediittejä. Se ei ole taattu enimmäishinta. Näytä epävarmuudet, kuten vielä tuntemattomat tiedostojen lukukulut. Aloitus tarkistaa oikeudet ja krediitit uudelleen.

Lataa arvio-opas ja esimerkit

Aloita käsittely omasta ohjelmistostasi

API yhdistää asiakirjakokonaisuudet, dokumentit, lataukset, äänen, litteroinnin, asiakaskansiot, tyylit, tulosteet, työnkulut, Excelin ja kohdennetut viestit. Jokaisella reitillä on omat syötteet, oikeudet, vahvistukset ja versiotarkistukset. Nykyinen käsittely ja krediittien laskenta pätevät. Aloitusvastaus vahvistaa vastaanoton; lue tämän jälkeen tila. Luettelo osoittaa keskeneräiset sopimukset.

Luo ensin asiakirjakokonaisuus

Luo ja säilytä UUID. Lähetä PUT /dossiers/{id}, jossa on vain naam, enintään 200 merkkiä. 201 tarkoittaa luontia, 200 samanlaista toistoa. Kohde kuuluu avaimen käyttäjälle ja organisaatiolle eikä maksa krediittejä. Eri syöte palauttaa 409, saavuttamaton tai poistettu kohde 404. GET /dossiers/{id} lukee naam- ja klant_id-kentät lukuoikeudella.

PUT https://api.rapportly.io/api/rapportly/v1/dossiers/00000000-0000-4000-8000-000000000002
Authorization: Bearer rply_<jouw_sleutel>
Content-Type: application/json

{ "naam": "Voorbeeldproject" }

Raportti, tarjous tai esitys

Aloita kentillä dossierId ja notities. tier on valinnainen: basis, standaard tai max. Ilman tyyliprofiilia käytetään neutraalia ulkoasua. Voit lisätä käytettävissä olevat stijlprofielId, klantId, bronOpnameIds ja taal. Tyylin on vastattava dokumenttityyppiä. Tarjoukset käyttävät yritysasetuksia ja turvallista numerointia; API ei lähetä niitä asiakkaalle.

POST https://api.rapportly.io/api/rapportly/v1/rapporten
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-rapport-2026-0001
Content-Type: application/json

{
  "dossierId": "00000000-0000-4000-8000-000000000002",
  "notities": "Team Atlas besprak de training. Noor plant de volgende bijeenkomst op donderdag.",
  "tier": "standaard"
}

Tallenna versie_id ja seuraa GET /rapporten/{versie_id}, myös tarjouksissa ja esityksissä. Tilassa klaar resultaat sisältää saatavilla olevat tiedostot: export_url PDF:lle, export_url_docx Wordille ja export_url_pptx PowerPointille. Linkit ovat voimassa 15 minuuttia. Tilassa mislukt tarkista käsittely ja kulutus ennen automaattista uutta aloitusta toisella avaimella.

Lataa vaiheet lähteestä tiedoston lataukseen

Lataa omat tyyliesimerkkisi

Lähetä yhdestä kolmeen esimerkkitiedostoa täydellisenä kokonaisuutena. Rapportly käyttää samoja tiedosto- ja tyylitarkistuksia kuin verkkosivusto. Tallennustila ja krediitit kuuluvat liitetylle käyttäjälle.

1. Lähetä tiedostot, nimi, dokumenttityyppi, henkilökohtainen tai tiimin käyttö, selkeä vahvistus ja kiinteä tehtävätunnus. Tiimityylit vaativat ylläpitäjän tai tiiminvetäjän.
2. Tallenna vastaanottotunnus ja lue tila. Vastaanotettu tarkoittaa koko aineiston tallennusta; esimerkin tarkistus ja hyväksyntä voivat seurata myöhemmin.
3. Toista katkoksen jälkeen täsmälleen sama pyyntö luomatta toista tyyliä. Puutteellisia latauksia voi toistaa kolmenkymmenen päivän ajan, minkä jälkeen ne siivotaan hallitusti.

Lataa tyyliesimerkkien, multipart-latauksen ja virheiden opas

Yhdistä kalenteri tai sähköpostilaatikko

Käyttäjä antaa itse suostumuksensa Googlelle tai Microsoftille. Ohjelmistosi seuraa pyyntöä ja voi tietoisesti katkaista yhteyden. Palveluntarjoajan salasanat ja tunnisteet eivät sisälly vastaukseen.

Käytä yhteyksille verbindingen:beheren ja tapaamisille agenda:lezen. Lähettäminen vaatii lisäksi lähetysoikeuden ja nimenomaisen pyynnön.

Tallenna pyyntönumero, tehtävätunnus ja nykyinen pohjaversio. Toista kadonneet pyynnöt täsmälleen; vanha katkaisupyyntö ei saa poistaa myöhempää yhteyttä.

API voi valita oletuspostilaatikon hallinta- ja lähetysoikeuksilla. Lue ensin nykyinen valinta ja yhteys. Vanha toisto ei muuta uudempaa valintaa; nykyiset lähetystehtävät säilyttävät lähettäjänsä.

Lataa suostumuksen, tapaamisten, katkaisun ja palautuksen vaiheet

Keskustelutulokset tekstistä

Lähetä vähintään sadan merkin litterointi. Seuraa tulosta gesprek_id-tunnuksella. Valinnaiset kentät: titel, tier, klantId ja taal.

POST https://api.rapportly.io/api/rapportly/v1/gesprekken
Authorization: Bearer rply_<jouw_sleutel>
Idempotency-Key: crm-gesprek-2026-0001
Content-Type: application/json

{
  "transcript": "Team Atlas bespreekt uitsluitend een fictieve oefening. Het team plant een training en verzamelt algemene voorbeeldvragen zonder klantgegevens.",
  "titel": "Kennismaking"
}

Lue olemassa olevia kieliversioita

Lue olemassa olevat kielitulokset. Kuvatut työnkulkureitit käynnistämiseen, keskeyttämiseen, jatkamiseen ja palautumiseen on testattu paikallisesti ja CI:ssä; CRM:n tuotantotesti ei vahvista tätä kielikäsittelyä. Käytä niitä vain tähän tarkoitukseen hyväksytyssä ympäristössä. Alkuperäinen käyttäjä, avain, lähde ja kustannukset pysyvät sidottuina pyyntöön. Lähteen ajantasainen tila, käyttöoikeudet, budjetti ja todennettu laskutuksen täsmäytys ovat edelleen pakollisia; vanhentunut tai poistettu lähde ei anna oikeutta uuteen käynnistykseen. Eräkäsittely, jossa toinen kieli on käytössä, pysyy suljettuna myös perittyjä asetuksia käytettäessä. Yhden puuttuvan käännöstuloksen maksullinen täydentäminen on edelleen poissuljettu.

GET https://api.rapportly.io/api/rapportly/v1/gesprekken/00000000-0000-4000-8000-000000000001/taalvarianten
Authorization: Bearer rply_<jouw_sleutel>

Saa ilmoitus käsittelyn valmistumisesta

Rapportly voi lähettää tekniset viittaukset palvelimellesi. Hae sitten sisältö oikeilla lukuoikeuksilla ilman jatkuvaa etenemiskyselyä.

1. Luo HTTPS-vastaanotin ja rekisteröi se kutsulla POST /webhooks käyttäen webhooks:beheren-oikeutta. Käytä samaa tuotantoavainta kyseisiin käsittelyihin.
2. Tarkista allekirjoitus alkuperäisistä viestitavuista ja tallenna kukin tapahtumatunnus vain kerran. Kuittaa vasta turvallisen tallennuksen ja jatkotehtävän kirjaamisen jälkeen. Toisto ei saa luoda toista tehtävää.
3. Lue GET /webhook-afleveringen ja toimitustiedot. Väliaikaisia virheitä yritetään uudelleen enintään kahdeksan kertaa; lisäkierroksen voi pyytää. Hyväksytty tarkoittaa vastaanottoa palvelimellasi. Tarkista jatkokäsittely siellä.

• Lataa webhook-opas rajoista ja palautuksesta
• Lataa Node.js-esimerkki allekirjoituksen tarkistukseen

Simulaattori ei lähetä oikeita ilmoituksia. Kokeile vastaanotinta kuvitteellisilla tiedoilla ja erillisellä tuotantoyhteydellä. Esimerkki tarkistaa ilmoituksen; palvelimesi hoitaa tallennuksen ja jatkotoimet.

Mitä virhekoodi tarkoittaa?

Suojaa avain ja asiakastiedot

• Käytä avainta vain palvelimellasi, älä julkisessa selainkoodissa.
• Käytä eri avainta jokaiselle integraatiolle ja peru vanhat avaimet.
• Älä lisää avaimia, tuloksia tai väliaikaisia linkkejä julkisiin lokeihin tai keskusteluihin.
• Tallenna haetut asiakastiedot oman järjestelmäsi käyttöoikeussääntöjen mukaan.