Sincronizzare il tuo sistema con una fonte personalizzata

Una fonte personalizzata collega un sistema che non ha un connettore integrato: la tua wiki, il tuo strumento di ticketing, un database, un’esportazione da qualsiasi parte. Il tuo codice invia i documenti a Sursa e Sursa li trasforma in schede nella raccolta e nelle cartelle per cui la fonte è configurata, con la stessa ricerca, le stesse risposte, la stessa verifica e gli stessi permessi delle schede di qualsiasi altra fonte.

A differenza della scrittura diretta delle schede, una fonte personalizzata tiene traccia di ciò che hai inviato. Alla fine di una sincronizzazione completa, Sursa archivia ogni documento che non hai inviato, così le eliminazioni nel tuo sistema arrivano in Sursa senza lavoro aggiuntivo.

Configurare la fonte

Un amministratore crea la fonte in Sursa in Sources → New source → Custom source (fonti, nuova fonte, fonte personalizzata) e sceglie:

• la raccolta e, facoltativamente, una cartella per le sue schede;
• la modalità delle cartelle: tutte le schede nella cartella scelta, oppure sottocartelle che riproducono il path di ogni documento;
• i permessi: i permessi della raccolta, oppure “come nella fonte”, dove ogni documento elenca chi può vederlo.

La pagina della fonte ne mostra l’ID; gli esempi usano 42.

Scegliere una chiave

La chiave della fonte è la scelta più sicura per una singola integrazione, soprattutto se funziona su una piattaforma di terzi. Una chiave dell’organizzazione con import:write è adatta a un servizio che alimenta più fonti.

Entrambe le chiavi si inviano allo stesso modo, e ogni endpoint di invio si trova in /v1/push/sources/{source_id}. Controlla la chiave e lo stato della fonte con GET /v1/push/sources/{source_id}:

curl https://api.sursa.com/v1/push/sources/42 \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY"

{"source_id": 42, "name": "Helpdesk articles", "documents": 1840, "open_sync": null}

Il documento

Invece di content, un singolo documento può portare un file fino a 100 MB in una richiesta multipart/form-data: il file nella parte file, i campi precedenti in JSON nella parte document. I caricamenti in parti per upload_id e attachments si creano con una chiave dell’organizzazione che ha l’ambito import:write e la finalità import_attachment; una chiave della fonte non può crearli.

Due modi di inviare

Gli aggiornamenti diretti sono adatti ai sistemi che ti segnalano ogni modifica, come un webhook del tuo helpdesk o un passaggio in Zapier. Invia un documento quando viene creato o modificato ed eliminalo quando viene rimosso:

Le modifiche diventano schede entro circa un minuto; più modifiche consecutive vengono elaborate insieme.

Le sincronizzazioni sono adatte alle esportazioni periodiche: invii tutto, o tutto ciò che è cambiato, e Sursa riconcilia. Il resto di questa guida riguarda le sincronizzazioni.

Eseguire una sincronizzazione completa

Una sincronizzazione ha tre passaggi: aprire, inviare, chiudere.

1. Aprire

POST /v1/push/sources/{source_id}/syncs apre una sincronizzazione e ne restituisce il numero:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Idempotency-Key: sync-2026-10-24" \
  -H "Content-Type: application/json" \
  -d '{"type": "initial", "max_minutes": 180}'

{"sync_number": 7, "type": "initial", "status": "open", "opened_at": "2026-10-24T02:00:00Z",
 "expires_at": "2026-10-24T05:00:00Z", "pushed": 0, "removed": 0}

• type è initial per la prima sincronizzazione della fonte e incremental dopo che una sincronizzazione si è completata. Una sincronizzazione incremental prima di una completata restituisce sources.push_initial_required.
• Si può aprire una sola sincronizzazione alla volta: una seconda restituisce 409 sources.push_sync_open.
• Una sincronizzazione resta aperta per max_minutes (60 per impostazione predefinita, fino a 1440). Poi scade: non viene archiviato nulla e il suo numero non è più accettato. Scegli un tempo ben più lungo di quello che richiede la tua esportazione.

2. Inviare i documenti

Invia i documenti in batch di massimo 500, con il numero della sincronizzazione. Il corpo di un batch può arrivare a 50 MiB; i file all’interno di un batch si passano come upload_id.

curl -X POST https://api.sursa.com/v1/push/sources/42/documents/batch \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Idempotency-Key: sync-7-batch-1" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_number": 7,
    "documents": [
      {"external_id": "faq-shipping", "title": "Shipping", "content_type": "markdown",
       "content": "# Shipping\n\nWe ship worldwide within 5 days.", "path": ["Support"]},
      {"external_id": "faq-refunds", "title": "Refunds", "content_type": "html",
       "content": "<p>Refunds take 14 days.</p>", "path": ["Support", "Billing"],
       "permissions": {"groups": ["Support"]}, "metadata": {"article_id": "1042"}}
    ]
  }'

La risposta contiene un risultato per ogni documento, nell’ordine in cui li hai inviati:

{
  "results": [
    {"external_id": "faq-shipping", "result": "unchanged", "status": "indexed", "card_id": "8c1d…", "version": "5e0f…"},
    {"external_id": "faq-refunds", "result": "updated", "status": "pending", "card_id": "3f2c…", "version": "a91b…"}
  ]
}

Per impostazione predefinita, ogni documento di un batch viene applicato da solo: un documento errato non blocca gli altri.

I documenti che non sono cambiati dall’ultima sincronizzazione non vanno inviati di nuovo. Confermali per ID con POST /v1/push/sources/{source_id}/syncs/{sync_number}/touch, fino a 1000 ID per richiesta, così la riconciliazione completa li mantiene:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs/7/touch \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ids": ["faq-contact", "faq-hours"]}'

3. Chiudere

POST /v1/push/sources/{source_id}/syncs/{sync_number}/close termina la sincronizzazione:

curl -X POST https://api.sursa.com/v1/push/sources/42/syncs/7/close \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "complete"}'

Chiudi con failed ogni volta che la tua esportazione si ferma a metà: un complete dopo un’esportazione parziale archivierebbe ogni documento a cui non sei arrivato. Ripetere la stessa chiusura restituisce lo stesso risultato.

Dopo la chiusura, Sursa trasforma i documenti in schede entro circa un minuto. La pagina della fonte mostra ogni sincronizzazione con il numero di documenti inviati e archiviati, e GET /v1/push/sources/{source_id}/syncs/{sync_number} restituisce gli stessi contatori.

Sincronizzazioni incrementali

Tra una sincronizzazione completa e l’altra, invia solo ciò che è cambiato:

1. Apri con "type": "incremental".
2. Invia i documenti modificati e metti gli ID di quelli rimossi in deletes (più avanti).
3. Chiudi con complete_incremental.

Esegui di tanto in tanto una sincronizzazione completa, per esempio ogni settimana, per recuperare ciò che un’esecuzione incrementale ha perso.

Eliminare documenti in un batch

Un batch può rimuovere documenti insieme a quelli che scrive. Elenca i loro ID in deletes:

{
  "sync_number": 8,
  "documents": [{"external_id": "faq-shipping", "title": "Shipping", "content": "…"}],
  "deletes": ["faq-old-returns", "faq-fax"]
}

Ogni ID eliminato riceve una propria voce in results, con result deleted, oppure not_found se la fonte non ha quel documento. Eliminare di nuovo lo stesso ID non ha conseguenze.

Batch atomici

Alcune modifiche hanno senso solo insieme, per esempio un documento e quello che lo sostituisce. Invia "atomic": true e il batch viene applicato per intero o per niente: se un documento qualsiasi non supera i controlli, non viene applicato nulla del batch e la risposta è 422 con il codice sources.push_batch_rejected e il risultato di ogni documento in error.details.results: i documenti che non sono riusciti hanno error, gli altri skipped.

{"sync_number": 8, "atomic": true, "documents": […], "deletes": ["faq-old-returns"]}

Senza atomic, un batch viene applicato documento per documento. Usa i batch atomici per le modifiche correlate e i batch normali per i caricamenti massivi, dove un documento errato non deve bloccare il resto.

Controllare il risultato di ogni documento

La risposta del batch ti dice come è stato scritto ogni documento. La trasformazione in scheda avviene dopo, quindi status può essere ancora pending. Per trovare i documenti di una sincronizzazione che non sono diventati schede:

curl "https://api.sursa.com/v1/push/sources/42/syncs/7/documents?status=failed" \
  -H "Authorization: Bearer $SURSA_SOURCE_KEY"

Ogni voce ha external_id, title, status, card_id, version e reason, e l’elenco si pagina con cursor. status accetta anche pending, processing, indexed e removed.

Puoi anche ricevere una notifica invece di chiedere: gli eventi import.sync_completed (una sincronizzazione è chiusa ed elaborata, con i suoi totali) e import.document_failed (un documento non è diventato una scheda, con il suo reason) arrivano via webhook e nel feed degli eventi.

Nuovi tentativi

• Invia una Idempotency-Key con ogni POST. Un batch ripetuto con la stessa chiave restituisce il primo risultato.
• Anche senza la chiave, un documento con lo stesso external_id non diventa mai una seconda scheda: è unchanged o updated.
• Se il processo si ferma a metà di una sincronizzazione, aprine una nuova dopo che quella vecchia è scaduta, oppure chiudi la vecchia con failed se ne hai ancora il numero, ed esegui di nuovo la sincronizzazione.

Limiti

Un documento oltre il limite di documenti della fonte non riesce con il motivo limit_reached in un batch; una richiesta con un solo documento risponde 409 con il codice sources.push_too_many_documents. I limiti di frequenza si applicano come a qualsiasi altra richiesta; vedi Limiti di frequenza e quote.

Errori comuni