Interfaccia API

L’API Oblic consente ai server di inviare email, SMS e WhatsApp per conto dell’organizzazione e verificarne gli esiti, registrare le azioni dei contatti nei propri sistemi e gestire modelli, identità mittente, liste di contatti, webhook e sottoaccount utilizzati. I server la chiamano con una chiave API.

URL di base

Tutti i percorsi iniziano con https://api.oblic.app/external/v1, tranne quelli precedenti delle liste di contatti, che iniziano con https://api.oblic.app/external/contact-list/v1.

Chiamare l’API

La chiave usata per la chiamata

curl https://api.oblic.app/external/v1/key \
  -H 'Authorization: Bearer YOUR_API_KEY'
  • Inviare una chiave API come Authorization: Bearer <key>. Le chiavi si creano in Impostazioni → Integrazione API, ciascuna con gli ambiti necessari. Conservarle sui server: una chiave in un browser o in un’app mobile è leggibile da chiunque. Vedere Autenticazione.
  • Le risposte con corpo usano un involucro JSON: {"status": "success", "data": …, "errors": null}, oppure "status": "error" con gli errori, ciascuno con codice (cd) e messaggio. Vedere Errori.
  • Una piattaforma opera per i propri clienti tramite sottoaccount: una chiave e il cliente indicato in X-Oblic-On-Behalf-Of a ogni richiesta.
  • Riprovare finché lo stato della chiave è conservato, con lo stesso Idempotency-Key e corpo. Le chiavi email e WhatsApp restano in Redis per 24 ore; perdita o scadenza della cache può consentire un altro invio. La chiave SMS resta nella riga del messaggio memorizzato senza scadenza temporale. Non è una garanzia permanente di esecuzione esattamente una volta. Vedere Messaggi.

Timestamp

I timestamp di risposta che identificano un istante includono uno scostamento ISO 8601. Ad esempio, 2026-10-30T20:00:00Z e 2026-10-31T01:30:00+05:30 identificano lo stesso istante. Interpretare lo scostamento prima di mostrare l’ora nel fuso del lettore. new Date(value) in JavaScript e OffsetDateTime.parse(value) in Java lo fanno; aggiungere Z a un valore senza scostamento o interpretare un istante come LocalDateTime no.

Un valore composto solo da una data rimane una data. Una pianificazione esplicitamente locale ha un contratto distinto: l’ora è associata a un campo di fuso orario, non interpretata da sola come un istante.

Endpoint

«Permessi» indica l’ambito che la chiave deve possedere per la rotta; se ne sono elencati più di uno, ne basta uno. Alcune rotte richiedono anche una chiave con ruolo Proprietario o Amministratore. Ambito e ruolo concedono il permesso, ma configurazione del servizio e idoneità della risorsa possono ancora causare un rifiuto.

Messaggi API

MetodoPercorsoFunzionePermessi
GET/external/v1/messagesMessaggi inviati tramite API, dal più recentemessages:read
POST/external/v1/messages/emailInviare un’email da un mittente verificato, con HTML proprio o un modelloemail:send
POST/external/v1/messages/smsInviare un SMS corrispondente a un modello DLT dell’accountsms:send
POST/external/v1/messages/whatsappInviare un modello WhatsApp approvato o una risposta entro 24 orewhatsapp:send
GET/external/v1/messages/{messageId}Un messaggio inviato tramite API e il suo esitomessages:read

Rapporti

MetodoPercorsoFunzionePermessi
GET/external/v1/reports/summaryEsiti dei messaggi inviati in un periodo, per canale e statomessages:read

Modelli email

MetodoPercorsoFunzionePermessi
GET/external/v1/templatesModelli email dell’account, dal più recenteemail:send oppure templates:manage
POST/external/v1/templatesCreare un modello email da HTMLtemplates:manage, chiave Proprietario o Amministratore
GET/external/v1/templates/{id}Un modello email con HTML e variabili ammesseemail:send oppure templates:manage
PUT/external/v1/templates/{id}Sostituire un modello email creato da HTMLtemplates:manage, chiave Proprietario o Amministratore
DELETE/external/v1/templates/{id}Eliminare un modello emailtemplates:manage, chiave Proprietario o Amministratore

Intestazioni e modelli SMS

Solo gli account di registro configurati possono modificare il registro SMS, anche con ambito e ruolo richiesti. Queste rotte memorizzano intestazioni e modelli già registrati presso DLT; non li registrano presso DLT. Gli elenchi includono modelli approvati anche inattivi; l’invio richiede ulteriori controlli di idoneità.

MetodoPercorsoFunzionePermessi
GET/external/v1/sms/accountLimiti SMS dell’account e invii effettuati nel mesesms:send oppure templates:manage
GET/external/v1/sms/sendersIntestazioni DLT dell’accountsms:send oppure templates:manage
GET/external/v1/sms/templatesModelli DLT dell’accountsms:send oppure templates:manage
POST/external/v1/sms/templatesMemorizzare in Oblic un modello già registrato presso DLTtemplates:manage, chiave Proprietario o Amministratore
PUT/external/v1/sms/senders/{senderId}Memorizzare un’intestazione DLT o cambiarne l’impostazione predefinitatemplates:manage, chiave Proprietario o Amministratore
DELETE/external/v1/sms/senders/{senderId}Eliminare un’intestazione DLTtemplates:manage, chiave Proprietario o Amministratore
PUT/external/v1/sms/templates/{id}Modificare un modello DLTtemplates:manage, chiave Proprietario o Amministratore
DELETE/external/v1/sms/templates/{id}Eliminare un modello DLTtemplates:manage, chiave Proprietario o Amministratore
PUT/external/v1/sms/templates/{id}/sharingConsentire l’invio di un modello a nessun sottoaccount, a tutti o a quelli indicatitemplates:manage, chiave Proprietario o Amministratore

Numero e modelli WhatsApp

MetodoPercorsoFunzionePermessi
GET/external/v1/whatsapp/connectionNumero WhatsApp collegato all’accountwhatsapp:send oppure templates:manage
POST/external/v1/whatsapp/connectionCollegare o sostituire il numero WhatsApp Business dell’accounttemplates:manage, chiave Proprietario o Amministratore
DELETE/external/v1/whatsapp/connectionScollegare il numero WhatsApp dell’accounttemplates:manage, chiave Proprietario o Amministratore
GET/external/v1/whatsapp/templatesModelli WhatsApp dell’account con l’esito della revisione Metawhatsapp:send oppure templates:manage
POST/external/v1/whatsapp/templatesSottoporre un modello WhatsApp alla revisione di Metatemplates:manage, chiave Proprietario o Amministratore
GET/external/v1/whatsapp/recipients/{number}Cosa l’account può inviare ora a un numerowhatsapp:send oppure templates:manage

Identità mittente

MetodoPercorsoFunzionePermessi
GET/external/v1/identitiesDomini e indirizzi mittente e relativo stato di verificaemail:send oppure identities:manage
POST/external/v1/identitiesAggiungere un dominio o indirizzo mittente da verificareidentities:manage
DELETE/external/v1/identities/{identityId}Eliminare un’identità mittenteidentities:manage

Liste di contatti

MetodoPercorsoFunzionePermessi
POST/external/contact-list/v1/addCreare una lista di contatticontacts:manage
POST/external/contact-list/v1/{contactListId}/addAggiungere contatti a una listacontacts:manage
GET/external/contact-list/v1/{nextIndex}/{limit}Liste di contatti dell’account, una pagina alla voltacontacts:manage

Eventi

MetodoPercorsoFunzionePermessi
POST/external/v1/eventsRegistrare fino a 100 eventi dei contatti, come ordini e carrelli abbandonatievents:write

Webhook API

MetodoPercorsoFunzionePermessi
GET/external/v1/webhooksEndpoint webhook dell’organizzazionewebhooks:manage, chiave Proprietario o Amministratore
POST/external/v1/webhooksRegistrare un endpoint webhook o trovare quello della stessa URLwebhooks:manage, chiave Proprietario o Amministratore
GET/external/v1/webhooks/deliveriesConsegne fallite, dalla più recentewebhooks:manage, chiave Proprietario o Amministratore
GET/external/v1/webhooks/{webhookId}Un endpoint webhookwebhooks:manage, chiave Proprietario o Amministratore
PUT/external/v1/webhooks/{webhookId}Cambiare URL o tipi di evento di un endpointwebhooks:manage, chiave Proprietario o Amministratore
DELETE/external/v1/webhooks/{webhookId}Interrompere le consegne a un endpointwebhooks:manage, chiave Proprietario o Amministratore
POST/external/v1/webhooks/deliveries/{deliveryId}/replayAccodare nuovamente una consegna fallitawebhooks:manage, chiave Proprietario o Amministratore

Sottoaccount API

MetodoPercorsoFunzionePermessi
GET/external/v1/accountsSottoaccount dell’organizzazioneaccounts:manage, chiave Proprietario o Amministratore
POST/external/v1/accountsCreare un sottoaccount o trovarlo tramite externalId, con una propria chiave APIaccounts:manage, chiave Proprietario o Amministratore
DELETE/external/v1/accounts/{accountId}Disattivare un sottoaccount e revocarne le chiaviaccounts:manage, chiave Proprietario o Amministratore

La chiave API

MetodoPercorsoFunzionePermessi
GET/external/v1/healthVerificare che una chiave raggiunga l’APIQualsiasi chiave con ruolo Proprietario o Amministratore
GET/external/v1/infoL’organizzazione per cui opera la chiaveQualsiasi chiave
GET/external/v1/keyLa chiave chiamante: nome, ruolo, ambiti e capacità attualiQualsiasi chiave
Questa pagina è stata utile?