Skip to main content

Integrazioni API

Grip AI può chiamare le tue API durante le conversazioni per recuperare o inviare dati in tempo reale.

Quando Usare

Usa le API quando l’assistente deve:
  • Verificare lo stato di un ordine
  • Cercare un cliente nel CRM
  • Creare un ticket di supporto
  • Controllare disponibilità prodotto
  • Aggiornare dati in tempo reale

Setup Base

1. Configura Endpoint in Dashboard

Vai in Strumenti → Integrazioni API → Nuova Integrazione
Nome: Verifica Ordini
URL Base: https://api.tuodominio.com
Metodo: GET
Endpoint: /orders/{order_id}/status

2. Autenticazione

Scegli il metodo appropriato:
Header: X-API-Key
Valore: sk_live_abc123xyz789

3. Definisci Parametri

Specifica quali dati l’AI deve raccogliere prima di chiamare l’API:
{
  "parameters": {
    "order_id": {
      "type": "string",
      "required": true,
      "description": "Numero ordine formato ORD-XXXXX"
    }
  }
}

4. Istruzioni nel Prompt

Aggiungi al system prompt:
## Verifica Ordini

Quando cliente chiede "dov'è il mio ordine":

1. Chiedi numero ordine: "Può fornirmi il numero d'ordine?"
2. Valida formato: deve iniziare con ORD-
3. Usa API: get_order_status
4. Comunica risultato:
   - Se "shipped": "Il suo ordine è stato spedito ed è in consegna [data]"
   - Se "processing": "Il suo ordine è in elaborazione, spedizione entro 24h"
   - Se "delivered": "Il suo ordine è stato consegnato il [data]"
5. Se API fallisce: "Non riesco ad accedere al sistema. Può riprovare tra poco?"

Esempi Pratici

GET Request - Recupera Dati

GET https://api.tuodominio.com/customers?phone=+393331234567
Authorization: Bearer token123
Response:
{
  "customer_id": "CUST-123",
  "name": "Mario Rossi",
  "tier": "VIP",
  "open_tickets": 2
}
L’AI usa questi dati nella conversazione: “Buongiorno Sig. Rossi, vedo che ha 2 ticket aperti…”

POST Request - Crea Dati

POST https://api.tuodominio.com/tickets
Content-Type: application/json
Authorization: Bearer token123

{
  "customer_id": "CUST-123",
  "subject": "Problema con ordine",
  "description": "Prodotto danneggiato",
  "priority": "high"
}
Response:
{
  "ticket_id": "TICKET-456",
  "status": "created"
}
L’AI conferma: “Ho creato il ticket #456. Riceverà aggiornamenti via email.”

Gestione Errori

L’AI deve gestire risposte di errore:
Status CodeComportamento AI
200-299Successo - comunica risultato
404”Non trovo questo ordine. Può verificare il numero?“
401/403”Problema tecnico. La faccio richiamare.”
500”Sistema momentaneamente non disponibile. Riprovi tra poco.”
Timeout”Il sistema sta impiegando troppo tempo. Preferisce attendere?”

Configurazione Avanzata

Parametri Dinamici

{
  "path": "/customers/{customer_id}/orders/{order_id}",
  "parameters": {
    "customer_id": {
      "type": "string",
      "required": true
    },
    "order_id": {
      "type": "string",
      "required": true
    },
    "include_items": {
      "type": "boolean",
      "default": true
    }
  }
}

Retry Policy

{
  "timeout": 5000,
  "retry": {
    "max_attempts": 3,
    "backoff": "exponential"
  }
}

Response Mapping

Specifica come interpretare la risposta:
{
  "response_mapping": {
    "status": "order_status",
    "tracking_code": "tracking_number",
    "eta": "estimated_delivery"
  }
}

Best Practices

Imposta timeout realistici (2-5 secondi). API troppo lente peggiorano l’esperienza.
Fai validare i parametri all’AI prima di chiamare (es. formato numero ordine).
Dai sempre alternative se API fallisce (callback, email, numero diretto).
  • Usa HTTPS sempre
  • API key con minimi permessi necessari
  • Rate limiting sul tuo server

Troubleshooting

Check:
  • URL corretto?
  • Firewall blocca IP Grip?
  • Autenticazione corretta?
  • Test con curl/Postman
  • Verifica API key corretta (no spazi)
  • Header name esatto (case-sensitive)
  • Token non scaduto
  • Controlla response nei log Grip
  • Verifica response mapping
  • Valida formato JSON

Prossimi Passi