UGO Documentation

Copia e incolla nel tuo codice

Script pronti per il backend. Sostituisci YOUR_API_KEY e l’email di destinazione, poi invia.

1

Prima di tutto

Crea una chiave in Chiavi API con lo scope necessario (es. email:send). Chiama le API solo dal server — mai dal browser. Base URL: https://api.unlimitedgo.it/v1

Invio email da un form di contatto

Al submit del form, il tuo backend chiama POST /v1/commands/email.send. Risposta attesa: 202 (email in coda). Non passare tenant_id.

PHP — incolla e adatta 
<?php
// send-form-email.php — chiama questo file al submit del form (server-side)
$apiKey = getenv('UGO_API_KEY') ?: 'YOUR_API_KEY';

$name    = trim($_POST['name'] ?? '');
$email   = trim($_POST['email'] ?? '');
$message = trim($_POST['message'] ?? '');

$payload = json_encode([
    'to'            => 'info@tuaazienda.it',   // dove vuoi ricevere le richieste
    'reply_to'      => $email,                // email del cliente (dal form)
    'sender_name'   => 'Form sito web',
    'subject'       => 'Nuova richiesta da ' . $name,
    'body'          => '<p><strong>Nome:</strong> ' . htmlspecialchars($name) . '</p>'
                     . '<p><strong>Email:</strong> ' . htmlspecialchars($email) . '</p>'
                     . '<p><strong>Messaggio:</strong><br>' . nl2br(htmlspecialchars($message)) . '</p>',
]);

$ch = curl_init('https://api.unlimitedgo.it/v1/commands/email.send');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// 202 = accettata (invio asincrono). Opzionale: leggi correlation_id e consulta GET /v1/runs/{id}
header('Content-Type: application/json');
http_response_code($httpCode ?: 500);
echo $response;

Crea una prenotazione da form

Stesso schema: backend → POST /v1/reservations con scope reservations:create.

PHP — incolla e adatta 
<?php
$apiKey = getenv('UGO_API_KEY') ?: 'YOUR_API_KEY';

$payload = json_encode([
    'customer_name' => trim($_POST['name'] ?? ''),
    'phone'         => trim($_POST['phone'] ?? ''),
    'email'         => trim($_POST['email'] ?? ''),
    'booking_date'  => trim($_POST['date'] ?? ''),   // YYYY-MM-DD
    'booking_time'  => trim($_POST['time'] ?? ''),   // HH:MM
    'people'        => (int) ($_POST['people'] ?? 2),
    'notes'         => trim($_POST['notes'] ?? ''),
]);

$ch = curl_init('https://api.unlimitedgo.it/v1/reservations');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

header('Content-Type: application/json');
http_response_code($httpCode ?: 500);
echo $response;
✓ Checklist minima
  • Chiave API in variabile d’ambiente (UGO_API_KEY)
  • Header Authorization: Bearer …
  • Su ogni POST: Idempotency-Key univoco
  • Content-Type: application/json
  • Niente tenant_id nel body

Prompt Cursor / Codex / Claude

Copia il prompt, aprilo nel tuo IDE AI e lascia che implementi l’integrazione delle API key UGO nel progetto.

  1. Crea una chiave in Chiavi API (scope es. email:send).
  2. Copia il prompt qui sotto.
  3. Incollalo in Cursor, Codex o Claude (chat Agent) sul tuo repository.
  4. Quando chiede la chiave, mettila in UGO_API_KEY (env), non nel codice.
Prompt — copia e incolla nell’IDE 
Implementa l'integrazione delle API UGO (Unlimited Go) in questo progetto.

## Obiettivo
Collega le API key UGO al codice esistente (form di contatto / prenotazioni / backend) in modo production-ready, senza esporre la chiave al browser.

## Credenziali e config
1. Usa la variabile d'ambiente `UGO_API_KEY` (non hardcodare la chiave nel repo).
2. Base URL: `https://api.unlimitedgo.it/v1`
3. Auth header: `Authorization: Bearer ${UGO_API_KEY}`
4. Alternativa ammessa: `X-API-Key: ${UGO_API_KEY}`
5. Su ogni richiesta POST aggiungi sempre:
   - `Content-Type: application/json`
   - `Idempotency-Key: <uuid univoco>` (nuovo per ogni submit)
6. NON inviare mai `tenant_id` nel body: l'isolamento è automatico dalla API key portal.

## Cosa implementare
1. Aggiungi `.env` / config con `UGO_API_KEY=` (e documenta dove inserire la chiave creata su https://api.unlimitedgo.it/developers/keys).
2. Crea un piccolo client/helper server-side (PHP o Node, in base allo stack del repo) per chiamare UGO.
3. Collega il form di contatto esistente (o creane uno minimale) a:
   `POST https://api.unlimitedgo.it/v1/commands/email.send`
   Body esempio:
   {
     "to": "info@tuaazienda.it",
     "reply_to": "<email dal form>",
     "sender_name": "Form sito web",
     "subject": "Nuova richiesta da <nome>",
     "body": "<html con i campi del form>"
   }
   Scope richiesto sulla chiave: `email:send`
   Risposta attesa: HTTP 202 con `{ "status": "accepted", "correlation_id": "..." }`
4. (Opzionale se nel progetto c'è un form prenotazioni) Collega anche:
   `POST https://api.unlimitedgo.it/v1/reservations`
   con campi: customer_name, phone, email, booking_date, booking_time, people, notes
   Scope: `reservations:create`
5. Gestisci errori HTTP (401/403/4xx/5xx) e mostra un messaggio chiaro all'utente.
6. Non chiamare mai le API UGO dal frontend: solo dal backend / route API / server action.

## Vincoli
- Non inventare endpoint diversi da quelli sopra.
- Non committare la API key.
- Riusa lo stack e gli pattern già presenti nel repository.
- Alla fine dimmi: file creati/modificati, come settare `UGO_API_KEY`, e come testare con un submit reale.
!

Non incollare la API key nel prompt

Il prompt usa già il placeholder env. Dopo l’implementazione, inserisci la chiave solo in .env / secrets del server.

Autenticazione

Per autenticare le tue richieste, includi la chiave API negli header HTTP. Usa uno dei due metodi (non entrambi necessari).

Bearer token

Header 
Authorization: Bearer YOUR_API_KEY

X-API-Key

Header 
X-API-Key: YOUR_API_KEY
!

Proteggi la tua chiave

Non condividere mai la chiave API in codice lato client (browser). Usala solo in ambienti server-side sicuri.

ℹ

Isolamento tenant

Le chiavi create nel portale (key_kind=portal) operano solo sulla tua organizzazione. Non includere tenant_id nel body o nei query params.

Monitoraggio e contabilizzazione

Ogni chiamata API è tracciata e associata a un correlation_id. Puoi usarlo per verificare l’esito delle operazioni asincrone e per il supporto.

  • Audit log — Ogni richiesta viene registrata (metodo, path, status, correlation_id).
  • Comandi asincroni — Le chiamate a email.send, wa.send e workflow.trigger generano un job in coda; lo stato si consulta con GET /v1/runs/{correlation_id}.
  • Contabilizzazione — Gli invii sono conteggiati per organizzazione (tenant). In Admin del portale sono visibili i volumi (es. ultimi 30 giorni) per report e fatturazione.
ℹ

Correlation ID

Puoi inviare un X-Correlation-Id nelle richieste per collegare le chiamate ai tuoi log; se omesso, il gateway ne genera uno automaticamente. La risposta 202 dei comandi include sempre il correlation_id da usare con l’endpoint runs.

Status & Health

GET /v1/status

Health check del gateway.

Endpoint pubblico: nessuna API key richiesta.
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/status"
Example Response 
{
    "status": "ok",
    "correlation_id": "..."
}

Comandi Asincroni

POST /v1/commands/email.send

Invia un'email (risposta 202, esito via runs).

Scope richiesto: email:send

Parametri body

to string
subject string
body string
template_id? int
variables? object
sender_name? string
Idempotency-Key obbligatorio. Risposta 202. Non passare tenant_id: la chiave portal opera già nel tuo spazio isolato.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/commands/email.send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to":"user@example.com","subject":"Oggetto","body":"Testo","sender_name":"Il mio servizio"}'
Example Response 
{
    "status": "accepted",
    "correlation_id": "..."
}
POST /v1/commands/wa.send

Invia messaggio WhatsApp (202, esito via runs).

Scope richiesto: wa:send

Parametri body

to string
template_id string
components? array
Idempotency-Key obbligatorio.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/commands/wa.send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to":"+393331234567","template_id":"prenotazione_confermata","components":[{"type":"body","parameters":[{"type":"text","text":"Mario Rossi"},{"type":"text","text":"20:00"}]}]}'
Example Response 
{
    "status": "accepted",
    "correlation_id": "..."
}
POST /v1/commands/workflow.trigger

Attiva un workflow (202, esito via runs).

Scope richiesto: workflow:trigger

Parametri body

workflow_id int
payload? object
Idempotency-Key obbligatorio.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/commands/workflow.trigger" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"workflow_id":123,"payload":{"customer_id":456,"event":"booking_created","booking_id":789}}'
Example Response 
{
    "status": "accepted",
    "correlation_id": "..."
}

Runs asincrone

GET /v1/runs/{correlation_id}

Stato di una run asincrona.

Scope richiesto: autenticato
Usa il correlation_id restituito dalla risposta 202 dei comandi asincroni.
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/runs/CORR_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "status": "done",
    "result": "..."
}

Email templates

GET /v1/email/templates

Elenco template email.

Scope richiesto: email:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/email/templates" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "templates": [
        {
            "id": 1,
            "name": "..."
        }
    ]
}
GET /v1/email/templates/{id}

Dettaglio template email.

Scope richiesto: email:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/email/templates/1" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "id": 1,
    "name": "...",
    "subject": "..."
}

WhatsApp

GET /v1/wa/templates

Elenco template WhatsApp.

Scope richiesto: wa:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/wa/templates" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "templates": []
}
GET /v1/wa/status

Stato account WhatsApp.

Scope richiesto: wa:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/wa/status" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "accounts": []
}
GET /v1/wa/onboarding-url

URL di onboarding WhatsApp.

Scope richiesto: wa:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/wa/onboarding-url" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "onboarding_url": "..."
}
POST /v1/wa/sub-accounts

Crea (o recupera) il sub-account Twilio per l'organizzazione associata alla API key. Idempotente: se esiste già restituisce success con already_exists.

Scope richiesto: wa:admin

Parametri body

friendly_name? string (opzionale)
Scope wa:admin. In alternativa puoi usare il pulsante "Attiva WhatsApp" nelle Impostazioni → WhatsApp del portale.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/wa/sub-accounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
Example Response 
{
    "success": true,
    "account_sid": "AC...",
    "already_exists": false
}

Workflow

GET /v1/workflows

Elenco workflow.

Scope richiesto: workflow:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/workflows" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "workflows": [
        {
            "id": 1,
            "name": "..."
        }
    ]
}
GET /v1/workflows/{id}

Dettaglio workflow.

Scope richiesto: workflow:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/workflows/1" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "id": 1,
    "name": "...",
    "triggers": []
}

Categorie prenotazione

GET /v1/booking-categories

Elenco categorie prenotazione.

Scope richiesto: reservations:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/booking-categories" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "categories": [
        {
            "id": 1,
            "name": "..."
        }
    ]
}

Prenotazioni

GET /v1/reservations

Elenco prenotazioni con filtri e paginazione.

Scope richiesto: reservations:read
Paginazione: page, per_page (default 20).
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/reservations?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "reservations": [],
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total": 0,
        "total_pages": 0
    }
}
GET /v1/reservations/{id}

Dettaglio prenotazione.

Scope richiesto: reservations:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/reservations/1" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "id": 1,
    "type": "...",
    "customer_name": "...",
    "booking_date": "..."
}
POST /v1/reservations

Crea prenotazione.

Scope richiesto: reservations:create

Parametri body

customer_name string
phone? string
email? string
booking_date date
booking_time? string
people? int
notes? string
type? string
Idempotency-Key obbligatorio. Almeno uno tra customer_name, phone, email.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/reservations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"customer_name":"Mario Rossi","phone":"+393331234567","booking_date":"2026-08-15","booking_time":"20:00","people":2}'
Example Response 
{
    "id": 1,
    "message": "Reservation created."
}
PATCH /v1/reservations/{id}

Aggiorna prenotazione.

Scope richiesto: reservations:write

Parametri body

customer_name?
phone?
email?
booking_date?
booking_time?
people?
notes?
cURL Request 
curl -X PATCH "https://api.unlimitedgo.it/v1/reservations/1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"people":4,"notes":"Tavolo esterno"}'
Example Response 
{
    "id": 1,
    "message": "..."
}
POST /v1/reservations/{id}/confirm

Conferma prenotazione.

Scope richiesto: reservations:write
Idempotency-Key obbligatorio.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/reservations/1/confirm" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
Example Response 
{
    "id": 1,
    "message": "..."
}
POST /v1/reservations/{id}/cancel

Annulla prenotazione.

Scope richiesto: reservations:write
Idempotency-Key obbligatorio.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/reservations/1/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
Example Response 
{
    "id": 1,
    "message": "..."
}
PATCH /v1/reservations/{id}/notes

Aggiorna note amministrative.

Scope richiesto: reservations:write

Parametri body

admin_notes string
cURL Request 
curl -X PATCH "https://api.unlimitedgo.it/v1/reservations/1/notes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"admin_notes":"Cliente abituale"}'
Example Response 
{
    "id": 1
}
DELETE /v1/reservations/{id}

Elimina prenotazione.

Scope richiesto: reservations:write
204 No Content.
cURL Request 
curl -X DELETE "https://api.unlimitedgo.it/v1/reservations/1" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{}

Clienti & Rubrica

GET /v1/contacts

Elenco contatti con ricerca e paginazione.

Scope richiesto: contacts:read
q = ricerca su nome, email, telefono.
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/contacts?page=1&q=mario" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "contacts": [],
    "pagination": []
}
GET /v1/contacts/{id}

Dettaglio contatto con tag e emoji.

Scope richiesto: contacts:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/contacts/1" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "id": 1,
    "first_name": "...",
    "tags": [],
    "emojis": []
}
POST /v1/contacts

Crea contatto.

Scope richiesto: contacts:create

Parametri body

first_name string
last_name? string
email? string
phone? string
consent_gdpr? int
tag_ids? array
emoji_ids? array
Idempotency-Key obbligatorio.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"first_name":"Mario","last_name":"Rossi","email":"mario@example.com","phone":"+393331234567","consent_gdpr":1}'
Example Response 
{
    "id": 1,
    "first_name": "..."
}
PATCH /v1/contacts/{id}

Aggiorna contatto.

Scope richiesto: contacts:write

Parametri body

first_name?
last_name?
email?
phone?
consent_gdpr?
tag_ids?
emoji_ids?
cURL Request 
curl -X PATCH "https://api.unlimitedgo.it/v1/contacts/1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+393339999999"}'
Example Response 
{
    "id": 1,
    "first_name": "..."
}
DELETE /v1/contacts/{id}

Elimina contatto.

Scope richiesto: contacts:write
204 No Content.
cURL Request 
curl -X DELETE "https://api.unlimitedgo.it/v1/contacts/1" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{}
GET /v1/contacts/{id}/tags

Tag del contatto.

Scope richiesto: contacts:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/contacts/1/tags" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "tags": [
        {
            "id": 1,
            "name": "..."
        }
    ]
}
PUT /v1/contacts/{id}/tags

Sincronizza tag del contatto.

Scope richiesto: contacts:write

Parametri body

tag_ids array
cURL Request 
curl -X PUT "https://api.unlimitedgo.it/v1/contacts/1/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag_ids":[1,2,3]}'
Example Response 
{
    "tags": []
}
GET /v1/contacts/{id}/emojis

Emoji del contatto.

Scope richiesto: contacts:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/contacts/1/emojis" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "emojis": [
        {
            "id": 1,
            "name": "..."
        }
    ]
}
PUT /v1/contacts/{id}/emojis

Sincronizza emoji del contatto.

Scope richiesto: contacts:write

Parametri body

emoji_ids array
cURL Request 
curl -X PUT "https://api.unlimitedgo.it/v1/contacts/1/emojis" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emoji_ids":[1,2]}'
Example Response 
{
    "emojis": []
}

Tag

GET /v1/tags

Elenco tag.

Scope richiesto: tags:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/tags" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "tags": [
        {
            "id": 1,
            "name": "..."
        }
    ]
}
GET /v1/tags/{id}

Dettaglio tag.

Scope richiesto: tags:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/tags/1" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "id": 1,
    "name": "..."
}
POST /v1/tags

Crea tag.

Scope richiesto: tags:create

Parametri body

name string
Idempotency-Key obbligatorio.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"VIP"}'
Example Response 
{
    "id": 1,
    "name": "..."
}
PATCH /v1/tags/{id}

Aggiorna tag.

Scope richiesto: tags:write

Parametri body

name string
cURL Request 
curl -X PATCH "https://api.unlimitedgo.it/v1/tags/1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cliente abituale"}'
Example Response 
{
    "id": 1,
    "name": "..."
}
DELETE /v1/tags/{id}

Elimina tag.

Scope richiesto: tags:write
204 No Content.
cURL Request 
curl -X DELETE "https://api.unlimitedgo.it/v1/tags/1" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{}

Mailing list

GET /v1/mailing-lists

Elenco liste email.

Scope richiesto: mailing_lists:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/mailing-lists" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "lists": [
        {
            "id": 1,
            "name": "...",
            "members_count": 0
        }
    ]
}
GET /v1/mailing-lists/{id}

Dettaglio lista.

Scope richiesto: mailing_lists:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/mailing-lists/1" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "id": 1,
    "name": "...",
    "address": "...",
    "members_count": 0
}
POST /v1/mailing-lists

Crea lista email.

Scope richiesto: mailing_lists:create

Parametri body

name string
Idempotency-Key obbligatorio.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/mailing-lists" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Newsletter"}'
Example Response 
{
    "id": 1,
    "name": "...",
    "address": "..."
}
PATCH /v1/mailing-lists/{id}

Aggiorna lista.

Scope richiesto: mailing_lists:write

Parametri body

name string
cURL Request 
curl -X PATCH "https://api.unlimitedgo.it/v1/mailing-lists/1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Promo estate"}'
Example Response 
{
    "id": 1,
    "name": "..."
}
DELETE /v1/mailing-lists/{id}

Elimina lista.

Scope richiesto: mailing_lists:write
204 No Content.
cURL Request 
curl -X DELETE "https://api.unlimitedgo.it/v1/mailing-lists/1" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{}
GET /v1/mailing-lists/{id}/members

Membri della lista.

Scope richiesto: mailing_lists:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/mailing-lists/1/members" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "members": [
        {
            "client_id": 1,
            "email": "..."
        }
    ]
}
POST /v1/mailing-lists/{id}/members

Aggiungi membro (contatto) alla lista.

Scope richiesto: mailing_lists:write

Parametri body

client_id int
Idempotency-Key obbligatorio.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/mailing-lists/1/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"client_id":42}'
Example Response 
{
    "message": "Member added"
}
DELETE /v1/mailing-lists/{id}/members/{client_id}

Rimuovi membro dalla lista.

Scope richiesto: mailing_lists:write
204 No Content.
cURL Request 
curl -X DELETE "https://api.unlimitedgo.it/v1/mailing-lists/1/members/42" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{}

Autosync

POST /v1/autosync/bookings

Invia una o più prenotazioni (push da sistema esterno).

Scope richiesto: autosync:push
Idempotency-Key obbligatorio. Almeno uno tra customer_name, phone, email.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/autosync/bookings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"customer_name":"Mario Rossi","booking_date":"2026-08-15","booking_time":"20:00","people":2}'
Example Response 
{
    "created_ids": [
        1,
        2
    ],
    "count": 2,
    "errors": []
}
GET /v1/autosync/config

Elenco configurazioni autosync del tenant.

Scope richiesto: autosync:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/autosync/config" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "configs": [
        {
            "id": 1,
            "site_url": "...",
            "pixel_token_masked": "****",
            "bookings_synced": 0
        }
    ]
}

Social & AI

GET /v1/social/connections

Stato connessione Meta (Facebook/Instagram).

Scope richiesto: social:read
Richiede modulo AI Team v1 abilitato.
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/social/connections" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "connection": {
        "page_id": "...",
        "ig_username": "..."
    },
    "health": []
}
GET /v1/social/onboarding-url

URL OAuth per collegare account Meta.

Scope richiesto: social:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/social/onboarding-url" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "oauth_url": "https:\/\/..."
}
GET /v1/social/actions

Elenco azioni social (pubblicazioni, scheduling).

Scope richiesto: social:read
cURL Request 
curl -X GET "https://api.unlimitedgo.it/v1/social/actions" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{
    "actions": [],
    "dead_letter": []
}
POST /v1/social/actions

Crea azione (pubblicazione FB/IG o schedulata).

Scope richiesto: social:publish

Parametri body

action_type publish_fb|publish_ig|publish_ig_story|publish_ig_reel|publish_ig_carousel
payload object
scheduled_for? datetime
Idempotency-Key obbligatorio.
cURL Request 
curl -X POST "https://api.unlimitedgo.it/v1/social/actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"action_type":"publish_fb","payload":{"message":"Ciao dal tuo locale!"}}'
Example Response 
{
    "success": true,
    "action_id": 1
}
DELETE /v1/social/actions/{id}

Elimina azione (e contenuto su Meta se già pubblicato).

Scope richiesto: social:publish
204 No Content.
cURL Request 
curl -X DELETE "https://api.unlimitedgo.it/v1/social/actions/1" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response 
{}