Benvenuto nelle API di UGO

Le API di Unlimited Go consentono di integrare il motore di prenotazioni, la gestione clienti e le automazioni marketing direttamente nelle tue applicazioni.

{""}

Endpoint base

https://api.unlimitedgo.it/v1

✓

Architettura REST

Tutti i dati vengono inviati e ricevuti in formato JSON standard.

⚠️ Header comuni

Header	Valore	Descrizione
`Content-Type`	application/json	Obbligatorio per richieste con body.
`Idempotency-Key`	UUID / String	Previene esecuzioni multiple della stessa operazione.
`X-Correlation-Id`	String (opzionale)	Per tracciare la richiesta; se omesso il gateway ne genera uno.

Autenticazione

Per autenticare le tue richieste, includi la chiave API negli header HTTP.

// Esempio header

Authorization: Bearer YOUR_SECRET_KEY
X-API-Key: YOUR_SECRET_KEY

Proteggi la tua chiave

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

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.

Nessuno scope richiesto.

cURL Request

curl -X GET "https://api.unlimitedgo.it/v1/status" -H "Authorization: Bearer YOUR_API_KEY"

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. Nome mittente (sender_name) e altri dati si passano nel body, non dalle impostazioni del portale.

cURL Request

curl -X POST ".../v1/commands/email.send" -H "Authorization: Bearer KEY" -H "Content-Type: application/json" -H "Idempotency-Key: uuid" -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 ".../v1/commands/wa.send" -H "Authorization: Bearer KEY" -H "Content-Type: application/json" -H "Idempotency-Key: uuid" -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 ".../v1/commands/workflow.trigger" -H "Authorization: Bearer KEY" -H "Content-Type: application/json" -H "Idempotency-Key: uuid" -d '{"workflow_id":123,"payload":{"customer_id":456,"event":"booking_created","booking_id":789}}'

Example Response

{
    "status": "accepted",
    "correlation_id": "..."
}

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" \
  -H "Authorization: Bearer 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/{id}" \
  -H "Authorization: Bearer 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 KEY"

Example Response

{
    "id": 1,
    "message": "Reservation created."
}

PATCH /v1/reservations/{id}

Aggiorna prenotazione.

Scope richiesto: reservations:write

Parametri body

0 customer_name?

1 phone?

2 email?

3 booking_date?

4 booking_time?

5 people?

6 notes?

cURL Request

curl -X PATCH "https://api.unlimitedgo.it/v1/reservations/{id}" \
  -H "Authorization: Bearer KEY"

Example Response

{
    "id": 1,
    "message": "..."
}

POST /v1/reservations/{id}/confirm

Conferma prenotazione.

Scope richiesto: reservations:write

cURL Request

curl -X POST "https://api.unlimitedgo.it/v1/reservations/{id}/confirm" \
  -H "Authorization: Bearer KEY"

Example Response

{
    "id": 1,
    "message": "..."
}

POST /v1/reservations/{id}/cancel

Annulla prenotazione.

Scope richiesto: reservations:write

cURL Request

curl -X POST "https://api.unlimitedgo.it/v1/reservations/{id}/cancel" \
  -H "Authorization: Bearer KEY"

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/{id}/notes" \
  -H "Authorization: Bearer KEY"

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/{id}" \
  -H "Authorization: Bearer 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" \
  -H "Authorization: Bearer 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/{id}" \
  -H "Authorization: Bearer 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 KEY"

Example Response

{
    "id": 1,
    "first_name": "..."
}

PATCH /v1/contacts/{id}

Aggiorna contatto.

Scope richiesto: contacts:write

Parametri body

0 first_name?

1 last_name?

2 email?

3 phone?

4 consent_gdpr?

5 tag_ids?

6 emoji_ids?

cURL Request

curl -X PATCH "https://api.unlimitedgo.it/v1/contacts/{id}" \
  -H "Authorization: Bearer KEY"

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/{id}" \
  -H "Authorization: Bearer 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/{id}/tags" \
  -H "Authorization: Bearer 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/{id}/tags" \
  -H "Authorization: Bearer KEY"

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/{id}/emojis" \
  -H "Authorization: Bearer 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/{id}/emojis" \
  -H "Authorization: Bearer KEY"

Example Response

{
    "emojis": []
}

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 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 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 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 KEY"

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/{id}" \
  -H "Authorization: Bearer KEY"

Example Response

{}