API v2 con OAuth

La nuova versione dell'API Oblic usa gli oggetti visibili in Oblic, percorsi, segmenti e messaggi, nello spazio collegato da una persona. Usa token di accesso OAuth 2.1 anziché chiavi API e agisce con il ruolo della persona. /external/v1 continua a funzionare con le chiavi API.


Ottenere un token

L'API v2 non accetta mai una chiave API: inviandola si riceve 401 API_KEY_NOT_ACCEPTED. Una persona collega invece l'applicazione a uno dei propri spazi, dove l'applicazione agisce per suo conto.

Il deployment Oblic deve avere il server di autorizzazione OAuth attivo, l'API v2 tra le risorse consentite, chiavi di firma e pagina di consenso configurate e il client registrato. Conferma la disponibilità con l'assistenza Oblic prima dell'integrazione; gli URL di esempio non dimostrano che un deployment sia configurato.

  1. Registra l'applicazione. Comunica all'assistenza Oblic nome, URI di reindirizzamento e ambiti richiesti per ricevere un identificatore client. I client sono pubblici: non esiste un segreto client e ogni autorizzazione usa PKCE. Solo un server o un'app nativa può usare l'API: nessuna origine del browser è consentita né sull'endpoint dei token né sull'API.
  2. Invita la persona ad accedere. Apri l'endpoint di autorizzazione con il resource dell'API v2 e scope=read send per inviare messaggi, oppure scope=read per la sola lettura. La persona accede a Oblic, sceglie lo spazio e approva gli ambiti.
  3. Scambia il codice sull'endpoint dei token con lo stesso resource.
  4. Chiama l'API con Authorization: Bearer <access token>.
Server di autorizzazionehttps://api.oblic.app (metadati in /.well-known/oauth-authorization-server)
Endpoint di autorizzazionehttps://api.oblic.app/oauth2/authorize
Endpoint dei tokenhttps://api.oblic.app/oauth2/token
Risorsahttps://api.oblic.app/external/v2
PKCESolo S256
Token di accessovalido per un'ora per impostazione predefinita
Token di aggiornamentosostituito a ogni uso; per impostazione predefinita scade dopo 30 giorni senza utilizzo e 90 giorni dal collegamento iniziale

Scambiare il codice

curl -X POST https://api.oblic.app/oauth2/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d code=THE_CODE \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d resource=https://api.oblic.app/external/v2

Un token emesso per un'altra risorsa, come il server MCP di Oblic, non funziona qui. Una richiesta senza token utilizzabile riceve 401 con l'intestazione WWW-Authenticate che indica i metadati della risorsa, https://api.oblic.app/.well-known/oauth-protected-resource/external/v2.

Ambiti e ruoli

  • Nome
    read
    Tipo
    scope
    Descrizione

    Richiedilo sempre: un token senza questo ambito viene rifiutato. Permette di leggere percorsi e segmenti dello spazio e messaggi inviati tramite API.

  • Nome
    send
    Tipo
    scope
    Descrizione

    Permette di accodare invii e-mail, SMS e WhatsApp per l'organizzazione; non implica che il fornitore li abbia consegnati. La persona vede questo ambito su una riga distinta prima di approvarlo.

Un ambito non supera mai il ruolo della persona, verificato a ogni richiesta. Rimuovere il ruolo o l'appartenenza all'organizzazione interrompe immediatamente l'accesso del token.

  • Percorsi e segmenti appartengono allo spazio scelto dalla persona; qualsiasi ruolo in quello spazio può leggerli.
  • I messaggi inviati tramite API appartengono allo spazio predefinito dell'organizzazione, come con una chiave API. L'invio richiede send e il ruolo Owner, Admin o Editor in tale spazio; qualsiasi ruolo nello spazio permette la lettura.

Il token non è soggetto all'elenco IP consentiti dell'organizzazione per le chiavi API: viene usato dai server dell'applicazione, nei limiti del ruolo della persona e degli ambiti approvati.


Endpoint dell'API

Ogni risposta contiene {"status": "success", "data": …, "errors": null}, oppure "status": "error" con gli errori.

MetodoPercorsoFunzione
GET/external/v2/journeysCampagne, automazioni, bot WhatsApp e percorsi creati in Journeys dello spazio, modificati più di recente per primi
GET/external/v2/journeys/{id}Un percorso
GET/external/v2/segmentsLe liste dello spazio, poi i segmenti dinamici
GET/external/v2/segments/{id}Un segmento
POST/external/v2/messages/emailInvia un'e-mail da un mittente verificato
POST/external/v2/messages/smsInvia un SMS conforme a uno dei modelli DLT
POST/external/v2/messages/whatsappInvia un modello WhatsApp approvato o una risposta entro 24 ore
GET/external/v2/messagesMessaggi inviati tramite API, più recenti per primi, con i parametri della lista v1
GET/external/v2/messages/{messageId}Un messaggio inviato tramite API e il relativo esito

Elencare i percorsi

  • Nome
    offset
    Tipo
    integer
    Descrizione

    Inizio della pagina; 0 per impostazione predefinita.

  • Nome
    limit
    Tipo
    integer
    Descrizione

    Numero di percorsi, da 1 a 100; 50 per impostazione predefinita.

  • Nome
    mode
    Tipo
    string
    Descrizione

    campaign, automation, bot o journey per un percorso creato in Journeys.

  • Nome
    status
    Tipo
    string
    Descrizione

    Stati consentiti: draft, scheduled, live, paused o done.

  • Nome
    search
    Tipo
    string
    Descrizione

    Parte del nome di un percorso.

Il nextOffset della pagina indica l'inizio della successiva ed è null nell'ultima.

Elencare i percorsi

curl 'https://api.oblic.app/external/v2/journeys?status=live&limit=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Risposta

{
  "status": "success",
  "data": {
    "journeys": [
      {
        "id": "CMP000R7ZM4Q2VXH00",
        "mode": "campaign",
        "name": "Weekly offer",
        "status": "live",
        "createdAt": "2026-10-01T09:30:00Z",
        "updatedAt": "2026-10-12T14:05:00Z"
      }
    ],
    "nextOffset": null
  },
  "errors": null
}

Inviare un messaggio

I corpi sono quelli di /external/v1/messages. L'invio viene accodato e riceve 202 con l'identificatore del messaggio. Ripeti con la stessa intestazione Idempotency-Key, da 1 a 255 caratteri, come negli invii v1: lo stesso invio restituisce il primo identificatore senza inviare ancora; la stessa chiave con un messaggio diverso dà 409 IDEMPOTENCY_CONFLICT. La chiave appartiene all'applicazione: un'altra applicazione o una chiave API con lo stesso valore invia un messaggio distinto.

Inviare un'e-mail

curl -X POST https://api.oblic.app/external/v2/messages/email \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-4471-shipped' \
  -d '{
    "to": ["customer@example.com"],
    "subject": "Your order has shipped",
    "html": "<p>Your order 4471 is on its way.</p>"
  }'

Risposta

{
  "status": "success",
  "data": { "id": "msg_4f9c2a7e1b8d4e0f9a6c3b2d1e0f9a8b", "status": "queued" },
  "errors": null
}

Leggi l'esito con GET /external/v2/messages/{messageId}.


Errori dell'API

Stato HTTPCodice di erroreSignificato
401MISSING_ACCESS_TOKENNessun token di accesso inviato
401INVALID_ACCESS_TOKENToken scaduto, emesso per altra risorsa, senza read o persona uscita dall'organizzazione: aggiornalo o collegati di nuovo
401API_KEY_NOT_ACCEPTEDChiave API inviata: usala con /external/v1
403INSUFFICIENT_SCOPEAmbito necessario assente, indicato in WWW-Authenticate: collegati di nuovo e approvalo
403FORBIDDENIl ruolo della persona non permette questa operazione
403EMAIL_SUSPENDEDE-mail dell'account sospese per rimbalzi o segnalazioni di spam, come in /external/v1
400BAD_REQUEST, INVALID_IDEMPOTENCY_KEYParametro, intestazione o corpo assente o illeggibile
400nome del campo, per esempio TOUn campo del corpo non è valido
402INSUFFICIENT_BALANCEUn invio SMS o WhatsApp di marketing richiede fondi nel portafoglio pagante; un portafoglio vuoto non blocca codici di accesso, messaggi transazionali o risposte
404JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUNDNon presente nello spazio o non inviato tramite API
404NOT_FOUNDLa rotta non esiste
405METHOD_NOT_ALLOWEDLa rotta non accetta il metodo: Allow elenca quelli consentiti
415UNSUPPORTED_MEDIA_TYPECorpo non inviato come application/json
422UNVERIFIED_SENDERMittente dell'e-mail non verificato
429RATE_LIMITED, QUOTA_EXCEEDEDLimiti orari o quota mensile e-mail superati, come in /external/v1; Retry-After indica quando riprovare

Anche un SMS o WhatsApp può essere rifiutato con un motivo specifico, come in /external/v1: modello non approvato, numero disiscritto dal marketing, numero non collegato o limite raggiunto, con Retry-After quando conviene riprovare più tardi.

Questa pagina è stata utile?