API pentru dezvoltatori

API pentru dezvoltatori

Conectează aplicația prin acțiuni explicite pentru surse, procesare, rezultate și administrare. Acest ghid descrie API-ul disponibil în limitele documentate ale versiunii. Utilizatorul, drepturile, stocarea și creditele rămân legate de contul Rapportly.

Pregătește integrarea în trei pași

1. 1
   Alege utilizatorul, mediul și drepturile

   Deschide Cont → Integrări. Folosește o cheie de test pentru simulator și una separată de producție pentru acțiuni reale cu date fictive. Administratorul acordă doar drepturile necesare și un buget potrivit.

2. 2
   Exersează primirea și erorile

   Începe cu simulatorul. Importă apoi contractele API și analizează exemplele sintetice. Păstrează secretele pe server; modificările sunt dezactivate implicit în colecție.

3. 3
   Urmărește o cerere completă

   Salvează datele și identificatorul, verifică pornirea și starea finală, citește rezultatul, descarcă un fișier disponibil și verifică consumul. Fă această probă doar într-un mediu autorizat.

Creează cheia API

Adresă de bază

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

Cheia aparține unui utilizator

O cheie deleagă drepturile unui utilizator. Administratorul stabilește mediul, plafonul drepturilor, bugetul lunar și expirarea. Membrul activează cheia pregătită și vede secretul o singură dată. Fiecare cerere verifică și drepturile actuale ale utilizatorului, pachetului și obiectului. Administrarea cheilor folosește o sesiune de utilizator; acțiunile de producție folosesc o cheie API. Păstrează secretele pe server și revocă o cheie pierdută din Cont → Integrări. Evenimentele Zapier au un contract propriu.

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

Folosește contracte și exemple concrete

OpenAPI pentru producție descrie contractele din cod și marchează intrările sau răspunsurile parțiale. Inventarul arată schemele deschise. Colecția Postman pornește cu adresă invalidă, chei goale și modificări dezactivate. Importă pentru analiză și trimite intenționat date fictive într-un mediu autorizat. Importul nu este încă testat.

• Descarcă specificația OpenAPI pentru producție
• Descarcă colecția Postman sintetică
• Descarcă pașii de la sursă la descărcare
• Descarcă inventarul schemelor deschise

Exersează mai întâi cu cereri fictive

Creează o cheie de test și exersează cereri în curs, rezultate, erori și buget insuficient. Simulatorul folosește exemple fixe și nu consumă credite.

1. În Cont → Integrări creează sau activează o cheie Test cu drepturile de exersat.
2. Cere GET /test/scenarios și alege o acțiune din răspuns. Lista respectă drepturile tale actuale.
3. Trimite POST /test/opdrachten doar cu actie și scenario: succes, verwerking_mislukt, creditbudget_bereikt sau toegang_geweigerd. Fiecare exercițiu nou are propriul Idempotency-Key.
4. Păstrează opdracht_id. La bezig, citește GET /test/opdrachten/{id} după aproximativ cinci secunde. Verifică mereu starea: HTTP200 poate conține și un eșec de procesare.

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"
}

Exemplul cere rapport.start în lista ta. După o problemă de conexiune repetă aceleași date și Idempotency-Key.

• Descarcă ghidul simulatorului
• Descarcă colecția Postman de exerciții
• Descarcă OpenAPI pentru simulator

Preia doar ce ai nevoie

Caută dosare de clienți, conversații și rapoarte accesibile. /acties arată acțiunile și drepturile, /gebruik bugetul și rezervările, /verzoeken istoricul tehnic. Procesarea în curs nu are încă rezultat. Linkurile rapoartelor sunt valabile 15 minute; citește din nou raportul pentru un link nou.

Actualizează gestionarea clienților

Software-ul tău poate modifica șabloanele biroului, salva căutări personale, înregistra o vizită și crea un parcurs. Folosește drepturile de administrare corespunzătoare și confirmă fiecare modificare. Citește mai întâi versiunea actuală și păstrează același identificator al cererii dacă răspunsul se pierde. Repetarea unei cereri vechi nu trebuie să anuleze o modificare mai recentă. Testul în producție verifică căutările, vizitele și parcursurile, inclusiv curățarea și revocarea cheilor. Șabloanele biroului au fost doar citite; scrierea a fost testată local și în CI. Ghidul descărcabil descrie cele patru rute și limitele dovezilor aferente.

Compară două versiuni salvate

Compară două numere de versiune existente ale aceluiași câmp de text salvat dintr-un raport sau ale aceluiași câmp salvat dintr-o conversație, fără o nouă procesare AI. Acest contract a fost testat local și în CI; testul CRM în producție nu dovedește comportamentul comparației în producție. Istoricul lipsă nu este completat cu textul actual. Diferențele lungi sunt trunchiate vizibil la maximum 8000 de caractere pe fiecare parte. Comparația nu include PowerPoint, calculele ofertelor, scrisorile de însoțire sau formatarea. Drepturile actuale de citire și condițiile de confidențialitate rămân aplicabile.

Cere o estimare de cost înainte de pornire

POST /generatieplan arată pașii și creditele estimate pentru raport, ofertă sau conversație. Folosește gebruik:lezen. Calculul și setările echipei corespund site-ului.

Estimarea nu pornește procesare și nu debitează credite. Nu este un preț maxim garantat. Afișează incertitudinile, precum costurile încă necunoscute de citire a fișierelor. Pornirea reverifică drepturile și creditele.

Descarcă ghidul de estimare și exemplele

Pornește procesarea din aplicația ta

API-ul conectează dosare, documente, încărcări, audio, transcriere, dosare de clienți, stiluri, rezultate, fluxuri, Excel și mesaje direcționate. Fiecare rută are date, drepturi, confirmări și verificări de versiune proprii. Procesarea și contabilizarea creditelor existente rămân valabile. Răspunsul inițial confirmă primirea; citește apoi starea. Inventarul arată contractele încă deschise.

Creează mai întâi un dosar

Generează și păstrează un UUID. Trimite PUT /dossiers/{id} doar cu naam, maximum 200 de caractere. 201 înseamnă creare, 200 repetare identică. Dosarul aparține utilizatorului și organizației cheii și nu costă credite. Date diferite returnează 409; un dosar inaccesibil sau șters, 404. GET /dossiers/{id} citește naam și klant_id cu drept de citire.

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" }

Raport, ofertă sau prezentare

Începe cu dossierId și notities. tier este opțional: basis, standaard sau max. Fără profil de stil se folosește un aspect neutru. Poți adăuga stijlprofielId, klantId, bronOpnameIds și taal accesibile. Stilul trebuie să corespundă documentului. Ofertele folosesc setările firmei și numerotare sigură; API-ul nu le trimite clientului.

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"
}

Păstrează versie_id și urmărește GET /rapporten/{versie_id}, inclusiv pentru oferte și prezentări. La klaar, resultaat conține fișierele disponibile: export_url pentru PDF, export_url_docx pentru Word, export_url_pptx pentru PowerPoint. Linkurile durează 15 minute. La mislukt, verifică procesarea și consumul înainte de a porni automat o cerere nouă cu altă cheie.

Descarcă pașii de la sursă la descărcare

Încarcă propriile exemple de stil

Trimite între unul și trei fișiere ca set complet. Rapportly folosește aceleași verificări de fișiere și stil ca site-ul. Stocarea și creditele aparțin utilizatorului asociat.

1. Trimite fișiere, nume, tip de document, domeniu personal sau echipă, confirmare explicită și identificator fix. Stilul de echipă cere administrator sau coordonator.
2. Păstrează identificatorul de primire și citește starea. Primit înseamnă că setul complet este salvat; verificarea și aprobarea pot urma ulterior.
3. După întrerupere repetă exact cererea fără a crea alt stil. Încărcările incomplete pot fi repetate treizeci de zile, apoi sunt curățate controlat.

Descarcă ghidul multipart pentru exemple de stil și erori

Conectează calendarul sau căsuța poștală

Utilizatorul își dă personal acordul la Google sau Microsoft. Aplicația urmărește cererea și poate opri intenționat conexiunea. Parolele și tokenurile furnizorului nu apar în răspuns.

Folosește verbindingen:beheren pentru conexiuni și agenda:lezen pentru întâlniri. Trimiterea cere și drept de expediere și o cerere explicită.

Păstrează numărul cererii, identificatorul și baza actuală. Repetă exact o cerere pierdută; o deconectare veche nu trebuie să elimine o conexiune ulterioară.

API-ul poate alege căsuța implicită cu drepturi de administrare și trimitere. Citește întâi selecția și conexiunea actuale. O repetare veche nu schimbă o selecție mai nouă; trimiterile existente își păstrează expeditorul.

Descarcă pașii pentru acord, întâlniri, deconectare și recuperare

Rezultate de conversație din text

Trimite o transcriere de cel puțin o sută de caractere. Urmărește rezultatul cu gesprek_id. Opțional: titel, tier, klantId și 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"
}

Citește variante lingvistice existente

Citește rezultatele lingvistice existente. Rutele de flux de lucru descrise pentru pornire, pauză, reluare și recuperare au fost testate local și în CI; testul CRM în producție nu verifică această procesare lingvistică. Folosește-le numai într-un mediu aprobat în acest scop. Utilizatorul, cheia, sursa și costurile inițiale rămân asociate cererii. Starea actuală a sursei, drepturile, bugetul și decontarea verificată rămân necesare; o sursă expirată sau ștearsă nu acordă dreptul la o nouă pornire. Procesarea în lot cu o a doua limbă activată rămâne blocată, inclusiv când setările sunt moștenite. Completarea contra cost a unui singur rezultat de traducere lipsă rămâne exclusă.

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

Primește o notificare când procesarea se termină

Rapportly poate trimite referințe tehnice serverului tău. Preia apoi conținutul cu drepturile de citire potrivite, fără să întrebi continuu despre progres.

1. Creează un receptor HTTPS și înregistrează-l prin POST /webhooks cu webhooks:beheren. Folosește aceeași cheie de producție pentru procesările vizate.
2. Verifică semnătura pe octeții originali și păstrează fiecare identificator de eveniment o singură dată. Confirmă după stocarea sigură împreună cu sarcina următoare. O repetare nu trebuie să creeze o a doua cerere.
3. Citește GET /webhook-afleveringen și detaliile. Erorile temporare sunt reîncercate de maximum opt ori; poți solicita o rundă suplimentară. Acceptat înseamnă primit de serverul tău: verifică acolo procesarea ulterioară.

• Descarcă ghidul webhook cu limite și recuperare
• Descarcă exemplul Node.js pentru verificarea semnăturii

Simulatorul nu trimite notificări reale. Testează receptorul cu date fictive și o conexiune de producție separată. Exemplul verifică notificarea; serverul tău gestionează stocarea și acțiunile ulterioare.

Ce înseamnă codul de eroare?

Protejează cheia și datele clienților

• Folosește cheia doar pe server, niciodată în cod public de browser.
• Folosește o cheie pentru fiecare integrare și revocă-le pe cele vechi.
• Nu pune chei, rezultate sau linkuri temporare în jurnale ori conversații publice.
• Păstrează datele preluate conform regulilor de acces ale sistemului tău.