Dopo questo articolo il tuo sito preleverà da solo i materiali pronti del progetto — testo, immagini, video — e li pubblicherà. Al proprietario servono pochi minuti per generare la chiave; allo sviluppatore, il tempo di scrivere tre richieste. Il sito non genera nulla, riceve solo ciò che è già pronto.
Come funziona
Telematic non ottiene alcun accesso al tuo sito. È il sito che ogni tanto chiede i materiali nuovi e li riceve in formato JSON. Dopo aver pubblicato un materiale, lo comunica, e nel progetto il materiale passa a pubblicato.
A un progetto si possono collegare più siti. Ognuno ha la sua chiave e il suo segno di ciò che ha già pubblicato; i materiali che tutti i siti vedono sono invece gli stessi.
Crea il collegamento e copia la chiave
- Apri la sezione «Integrations» e premi «Aggiungi feed del sito».
- Nella finestra «Collega un sito esterno» compila «Nome del sito».
- Nel blocco «Quali stati esporre nel feed» lascia gli stati che ti servono: «Accettato», «Programmato», «Pubblicato». Bozze, materiali rifiutati e archiviati non vengono mai consegnati al sito.
- Scegli «Ritmo di consegna»: se ne parla più sotto.
- Premi «Genera chiave».
Compare il blocco «La tua chiave segreta». La chiave comincia con tlmf_.
Importante. La chiave viene mostrata una volta sola: il servizio ne conserva solo l'impronta. Copiala subito e passala allo sviluppatore in modo sicuro. Se la perdi, generane una nuova.
Più in basso, nella stessa finestra, c'è «Guida all’integrazione»: comandi pronti con la tua chiave e il tuo indirizzo.
Preleva i materiali: le richieste per lo sviluppatore
L'indirizzo dell'API è https://<indirizzo indicato nella guida>/api/feed/v1. La parte /api è obbligatoria: senza, la richiesta finisce sul sito normale. Ogni richiesta porta l'intestazione Authorization: Bearer <chiave>.
| Richiesta | Cosa fa |
|---|---|
GET /me | verifica la chiave, restituisce il progetto e le impostazioni del feed |
GET /content?since=&limit= | i materiali pronti che questo sito non ha ancora confermato; prima i più vecchi |
GET /content/{id} | un singolo materiale, anche già confermato, per aggiornarne la copia |
POST /content/{id}/ack | conferma la pubblicazione sul sito |
POST /content/{id}/stats | invia visualizzazioni e reazioni |
GET /openapi.json | descrizione dell'API leggibile dalle macchine |
BASE="https://<indirizzo indicato nella guida>/api/feed/v1"
KEY="tlmf_..."
curl -H "Authorization: Bearer $KEY" "$BASE/content?limit=20"
Nella risposta ci sono items, nextCursor e il blocco pacing. limit va da 1 a 100, di base è 20. Salva nextCursor e passalo come since nella richiesta successiva.
Conferma la pubblicazione e invia le statistiche
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"externalId":"123","url":"https://mio-sito.it/p/123"}' \
"$BASE/content/<ID>/ack"
Tutti i campi sono facoltativi: externalId, url, publishedAt. Dopo la conferma il materiale sparisce dalla consegna di questo sito e nel progetto passa allo stato «Pubblicato», oppure resta «Parzialmente pubblicato» finché lo aspettano altre piattaforme. Ripetere la chiamata non crea problemi.
Perché i numeri del sito arrivino nelle Statistiche, invia views, reactions, comments, shares a /content/<ID>/stats. Prima della conferma del materiale questa richiesta restituisce 404. Noi i numeri dal sito non li preleviamo.
Ritmo di consegna: un materiale per intervallo
È il sito a fare le richieste, quindi la velocità la decidi tu. In un intervallo il feed consegna al massimo un materiale, qualunque limit ci sia nella richiesta, e non consegna in blocco quanto si è accumulato mentre il sito era fermo. L'intervallo si conta dall'ultima conferma.
- L'opzione «Come la pianificazione del progetto» prende intervallo, finestra oraria e limite giornaliero dalla pianificazione delle pubblicazioni del progetto. Il limite si conta a parte per il sito. Se la pianificazione non c'è, non ci sono limiti.
- «Ritmo personalizzato» ha un intervallo proprio da 5 minuti a 30 giorni, una finestra oraria e un limite da 1 a 1000 al giorno.
- «Senza limiti» consegna al sito tutto quello che chiede: fino a 100 materiali per volta.
Quando un materiale non «spetta» ancora, la risposta arriva vuota e il blocco pacing spiega il motivo:
{ "items": [],
"pacing": { "reason": "interval", "intervalSeconds": 3600,
"nextAvailableAt": "2026-09-19T13:00:00.000Z" } }
reason può valere interval (l'intervallo non è trascorso), window (adesso sei fuori dalla finestra oraria), daily-cap (il limite di oggi è esaurito), ready, unlimited. Nel blocco ci sono anche i campi enabled, source, timeFrom, timeTo, maxPerDay, allowance. La finestra si calcola sull'ora del server: fai riferimento a nextAvailableAt.
I campi del materiale
id,title,excerpt— identificatore, titolo, breve descrizione.bodyMarkdown— il testo principale con titoli, elenchi e immagini. Convertilo in HTML e impaginalo con gli stili del sito.bodyè lo stesso testo senza formattazione, rimasto per i collegamenti vecchi.topics— di solito 3–7 tag nella lingua del materiale.sourceUrl,createdAt,updatedAt.media[]— i file:type(IMAGE,VIDEO,AUDIO,OTHER),url,width,height,duration,thumbnail. I link sono assoluti.
La prima immagine in media è la copertina e non è inserita nel testo. Anche video e audio vanno presi da media: non più di un filmato per orientamento. I filmati che aspettano la tua conferma non entrano nel feed.
Nella pagina del materiale la scheda del sito mostra lo stato — «In attesa del prelievo da parte del sito», «Confermato dal sito» o «Non nel feed» — e l'ora dell'ultima richiesta del sito. Il pulsante «Anteprima» apre il testo esattamente come lo riceverà il sito.
Pausa e nuova chiave
- Pausa. Nella sezione «Integrations» premi il pulsante di pausa sulla scheda del sito. Compare il messaggio «Integrazione in pausa» e il sito comincia a ricevere l'errore 401. Lo stesso pulsante riattiva la consegna.
- Nuova chiave. Premi sulla scheda del sito e nella finestra «Feed del sito» scegli «Rigenera chiave». Anche la nuova chiave viene mostrata una volta sola e la vecchia smette subito di funzionare: aggiornala sul sito.
Nella stessa finestra si cambiano nome, stati e ritmo; non dimenticare «Salva».
Se il sito non riceve niente
- Risposta 401. La chiave è stata copiata solo in parte, è stata rigenerata oppure il collegamento è in pausa. Controlla l'intestazione
Authorization: Bearer …con la richiestaGET /me. - Al posto del JSON arriva la pagina del sito. Nell'indirizzo manca
/api. itemsvuoto. Guarda primapacing.reasonenextAvailableAt. Se trovireadyounlimited, nel progetto non ci sono materiali negli stati scelti: una bozza va prima accettata, vedi Lavorare con i contenuti.- Lo stesso materiale arriva di nuovo. Il sito non ha inviato
ack.
Cosa fare dopo
- Progetti e piattaforme — le altre piattaforme del progetto.
- Pubblicazioni e calendario — la pianificazione da cui il feed prende il ritmo.
- Soluzione dei problemi frequenti — se ti serve l'aiuto dell'assistenza.