Guida

API per sviluppatori

Collega il tuo software con azioni esplicite per fonti, elaborazioni, risultati e gestione. Questa guida descrive l’API disponibile entro i limiti documentati della versione. Utente, permessi, spazio e crediti rimangono legati all’account Rapportly.

Prepara l’integrazione in tre passaggi

1. 1
   Scegli utente, ambiente e permessi

   Apri Account → Integrazioni. Usa una chiave di test per il simulatore e una chiave di produzione distinta per azioni reali con dati fittizi. L’amministratore assegna solo i permessi necessari e un budget adeguato.

2. 2
   Prova ricezioni ed errori

   Inizia dal simulatore, poi importa le contratti API e valuta gli esempi sintetici. Conserva i segreti sul server; le modifiche sono disattivate per impostazione predefinita nella raccolta.

3. 3
   Segui una richiesta completa

   Salva dati e identificativo, controlla avvio e stato finale, leggi il risultato, scarica un file disponibile e verifica il consumo. Esegui questa prova solo in un ambiente autorizzato.

Crea la tua chiave API

Indirizzo di base

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

La chiave appartiene a un utente

Una chiave delega i permessi di un utente. L’amministratore definisce ambiente, limite dei permessi, budget mensile e scadenza. Il membro attiva la chiave predisposta e vede il segreto una volta. Ogni chiamata verifica anche i permessi attuali di utente, piano e oggetto. La gestione delle chiavi usa una sessione utente; le azioni di produzione una chiave API. Conserva i segreti sul server e revoca una chiave persa in Account → Integrazioni. Gli eventi Zapier seguono un contratto separato.

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

Usa contratti ed esempi concreti

L’OpenAPI di produzione descrive i contratti del sorgente e segnala input o risposte parziali. L’inventario mostra gli schemi aperti. La raccolta Postman parte con indirizzo non valido, chiavi vuote e modifiche disattivate. Importa per esaminare e invia consapevolmente dati fittizi in un ambiente autorizzato. L’importazione non è ancora testata.

• Scarica la specifica OpenAPI di produzione
• Scarica la raccolta Postman sintetica
• Scarica il percorso dalla fonte al download
• Scarica l’inventario degli schemi aperti

Esercitati prima con richieste fittizie

Crea una chiave di test e prova richieste in corso, risultati, errori e budget insufficiente. Il simulatore usa esempi fissi senza costi in crediti.

1. In Account → Integrazioni crea o attiva una chiave Test con i permessi da provare.
2. Richiedi GET /test/scenarios e scegli un’azione dalla risposta. La lista segue i tuoi permessi attuali.
3. Invia POST /test/opdrachten solo con actie e scenario: succes, verwerking_mislukt, creditbudget_bereikt o toegang_geweigerd. Ogni nuova prova usa un Idempotency-Key distinto.
4. Conserva opdracht_id. Con bezig, leggi GET /test/opdrachten/{id} dopo circa cinque secondi. Controlla sempre lo stato: HTTP200 può contenere un’elaborazione fallita.

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

L’esempio richiede rapport.start nella tua lista. Dopo un problema di connessione ripeti stessi dati e Idempotency-Key.

• Scarica la guida del simulatore
• Scarica la raccolta Postman di esercitazione
• Scarica l’OpenAPI del simulatore

Recupera solo ciò che serve

Cerca cartelle cliente, conversazioni e rapporti accessibili. /acties mostra azioni e permessi, /gebruik budget e prenotazioni, /verzoeken la cronologia tecnica. Un’elaborazione in corso non ha ancora un risultato. I link dei rapporti durano 15 minuti; rileggi il rapporto per un nuovo link.

Aggiornare la gestione dei clienti

Il tuo software può modificare i modelli dello studio, salvare ricerche personali, registrare una visita e creare un percorso. Usa le autorizzazioni di gestione appropriate e conferma ogni modifica. Leggi prima la versione attuale e conserva lo stesso identificativo della richiesta se la risposta va persa. La ripetizione di una vecchia richiesta non deve annullare una modifica più recente. Il test in produzione verifica ricerche, visite e percorsi di gestione, comprese la pulizia e la revoca delle chiavi. I modelli dello studio sono stati soltanto letti; la scrittura è stata testata localmente e in CI. La guida scaricabile descrive le quattro rotte e i limiti delle relative prove.

Confrontare due versioni salvate

Confronta due numeri di versione esistenti dello stesso campo di testo salvato di un rapporto o dello stesso campo salvato di una conversazione, senza nuova elaborazione tramite IA. Questo contratto è stato testato localmente e in CI; il test CRM in produzione non dimostra il comportamento del confronto in produzione. La cronologia mancante non viene sostituita dal testo attuale. Le differenze lunghe vengono troncate a un massimo di 8000 caratteri per lato, con un’indicazione visibile. Il confronto non riguarda PowerPoint, calcoli di preventivi, lettere di accompagnamento o formattazione. Restano validi i diritti di lettura e le condizioni di riservatezza attuali.

Richiedi una stima dei costi

POST /generatieplan mostra passaggi e crediti previsti per rapporto, preventivo o conversazione. Usa gebruik:lezen. Calcolo e impostazioni del team coincidono con il sito.

La stima non avvia elaborazioni né addebita crediti. Non è un prezzo massimo garantito. Mostra le incertezze, ad esempio costi di lettura dei file ancora ignoti. L’avvio ricontrolla permessi e crediti.

Scarica la guida alla stima e gli esempi

Avvia un’elaborazione dal tuo software

L’API collega fascicoli, documenti, caricamenti, audio, trascrizioni, cartelle cliente, stili, output, workflow, Excel e messaggi mirati. Ogni route mantiene input, permessi, conferme e controlli di versione propri. Elaborazione e contabilizzazione dei crediti esistenti restano valide. La risposta iniziale prova la ricezione; leggi poi lo stato. L’inventario indica i contratti aperti.

Crea prima un fascicolo

Genera e conserva un UUID. Invia PUT /dossiers/{id} solo con naam, massimo 200 caratteri. 201 indica creazione, 200 ripetizione identica. Il fascicolo appartiene all’utente e all’organizzazione della chiave e non costa crediti. Dati diversi restituiscono 409, un fascicolo inaccessibile o eliminato 404. GET /dossiers/{id} legge naam e klant_id con permesso di lettura.

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

Rapporto, preventivo o presentazione

Inizia con dossierId e notities. tier è facoltativo: basis, standaard o max. Senza profilo di stile si usa un formato neutro. Puoi aggiungere stijlprofielId, klantId, bronOpnameIds e taal accessibili. Lo stile deve corrispondere al documento. I preventivi usano impostazioni aziendali e numerazione sicura; l’API non li invia al cliente.

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

Salva versie_id e segui GET /rapporten/{versie_id}, anche per preventivi e presentazioni. Con stato klaar, resultaat contiene i file disponibili: export_url per PDF, export_url_docx per Word, export_url_pptx per PowerPoint. I link scadono dopo 15 minuti. In caso di mislukt, verifica elaborazione e consumo prima di avviare automaticamente una nuova richiesta con un’altra chiave.

Scarica il percorso dalla fonte al download

Carica esempi del tuo stile

Invia da uno a tre file come insieme completo. Rapportly usa gli stessi controlli di file e stile del sito. Spazio e crediti appartengono all’utente associato.

1. Invia file, nome, tipo di documento, ambito personale o team, conferma esplicita e identificativo fisso. Lo stile di team richiede amministratore o responsabile.
2. Conserva l’ID di ricezione e consulta lo stato. Ricevuto significa insieme completo salvato; verifica dell’anteprima e approvazione possono seguire.
3. Dopo un’interruzione ripeti esattamente la richiesta, senza creare un secondo stile. I caricamenti incompleti possono essere ripetuti per trenta giorni, poi vengono rimossi in modo controllato.

Scarica la guida multipart agli esempi di stile e agli errori

Collega calendario o casella e-mail

L’utente autorizza personalmente Google o Microsoft. Il software segue la richiesta e può interrompere consapevolmente il collegamento. Password e token del fornitore non compaiono nella risposta.

Usa verbindingen:beheren per i collegamenti e agenda:lezen per gli appuntamenti. L’invio richiede anche permesso dedicato e richiesta esplicita.

Conserva numero richiesta, identificativo e base attuale. Ripeti esattamente una richiesta persa; una vecchia disconnessione non deve eliminare un collegamento successivo.

L’API può scegliere la casella predefinita con permessi di gestione e invio. Leggi prima scelta e collegamento attuali. Una vecchia ripetizione non cambia una scelta successiva; gli invii esistenti conservano il mittente.

Scarica i passaggi per consenso, appuntamenti, disconnessione e recupero

Risultati di conversazione da testo

Invia una trascrizione di almeno cento caratteri. Segui il risultato con gesprek_id. Facoltativi: titel, tier, klantId e 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"
}

Leggere varianti linguistiche esistenti

Leggi i risultati linguistici esistenti. Le rotte del flusso di lavoro descritte per avvio, pausa, ripresa e ripristino sono state testate localmente e in CI; il test CRM in produzione non verifica questa elaborazione linguistica. Usale soltanto in un ambiente autorizzato a questo scopo. L’utente, la chiave, la fonte e i costi originali restano associati alla richiesta. Restano necessari lo stato attuale della fonte, i permessi, il budget e la liquidazione verificata; una fonte scaduta o eliminata non autorizza un nuovo avvio. L’elaborazione in blocco con una seconda lingua attivata resta bloccata, anche con impostazioni ereditate. Il completamento a pagamento di un singolo risultato di traduzione mancante resta escluso.

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

Ricevi un avviso al termine dell’elaborazione

Rapportly può inviare riferimenti tecnici al tuo server. Recupera poi il contenuto con i permessi di lettura necessari, senza interrogare continuamente lo stato.

1. Crea un ricevitore HTTPS e registralo tramite POST /webhooks con webhooks:beheren. Usa la stessa chiave di produzione per le elaborazioni interessate.
2. Verifica la firma sui byte originali e conserva ciascun ID evento una sola volta. Conferma dopo aver salvato in sicurezza avviso e attività successiva. Una ripetizione non deve creare una seconda richiesta.
3. Leggi GET /webhook-afleveringen e i dettagli. Rapportly riprova gli errori temporanei al massimo otto volte; puoi richiedere un ciclo aggiuntivo. Accettato significa ricevuto dal tuo server: controlla lì l’elaborazione successiva.

• Scarica la guida webhook con limiti e recupero
• Scarica l’esempio Node.js per verificare la firma

Il simulatore non invia avvisi reali. Prova il ricevitore con dati fittizi e collegamento di produzione separato. L’esempio verifica l’avviso; il tuo server gestisce archiviazione e azioni successive.

Cosa significa un codice di errore?

Proteggi chiave e dati dei clienti

• Usa la chiave solo sul tuo server, mai nel codice pubblico del browser.
• Usa una chiave per integrazione e revoca quelle vecchie.
• Non inserire chiavi, risultati o link temporanei in log o chat pubblici.
• Conserva i dati recuperati secondo le regole di accesso del tuo sistema.