Per Sviluppatori

Documentazione API

Integra HaoChi nelle tue applicazioni. Autenticazione, gestione profilo e molto altro.

Panoramica

URL base

https://haochi.it/api

Header richiesti

Tutte le richieste devono includere i seguenti header:

Content-Type: application/json
Accept: application/json

Formato risposta

Tutte le risposte sono in formato JSON con la seguente struttura:

Risposta di esempio 200

{
  "success": true,
  "message": "...",
  "data": { ... }
}

Risposta di esempio 201

{
  "success": true,
  "message": "...",
  "data": { ... }
}

Autenticazione

Gli endpoint utente richiedono un token Bearer nell'header Authorization:

Authorization: Bearer <token>

API Key

Gli endpoint prodotti richiedono una API key statica nell'header X-Api-Key:

X-Api-Key: <api_key>

Rate Limiting

Gli endpoint di autenticazione sono limitati a 5 richieste al minuto per IP. Gli endpoint prodotti sono limitati a 30 richieste al minuto per IP.

Risposte di errore

Risposte di errore 401

{
  "success": false,
  "message": "Invalid credentials."
}

Risposte di errore 422

{
  "message": "The email field is required.",
  "errors": {
    "email": [
      "The email field is required."
    ]
  }
}
POST /api/auth/register

Registrazione

Crea un nuovo account utente con email e password.

Parametri

name
string Obbligatorio

Nome dell'utente

surname
string Obbligatorio

Cognome dell'utente

email
string Obbligatorio

Indirizzo email

password
string Obbligatorio

Password (minimo 8 caratteri)

password_confirmation
string Obbligatorio

Conferma password

Risposta di esempio 201

{
  "success": true,
  "message": "Registration successful.",
  "data": {
    "user": {
      "id": 1,
      "name": "Marco",
      "surname": "Rossi",
      "full_name": "Marco Rossi",
      "email": "marco@example.com",
      "email_verified": false,
      "avatar": null,
      "google_linked": false,
      "google_locale": null,
      "created_at": "2025-01-15T10:30:00+00:00",
      "updated_at": "2025-01-15T10:30:00+00:00"
    },
    "token": "1|abc123..."
  }
}
POST /api/auth/login

Login

Autentica un utente esistente con email e password.

Nota: Se l'utente si è registrato tramite Google e non ha una password, la risposta sarà un 401 con il messaggio: "Invalid credentials. If you signed up with Google, please use Google Sign-In."

Parametri

email
string Obbligatorio

Indirizzo email

password
string Obbligatorio

Password (minimo 8 caratteri)

Risposta di esempio 200

{
  "success": true,
  "message": "Login successful.",
  "data": {
    "user": {
      "id": 1,
      "name": "Marco",
      "surname": "Rossi",
      "full_name": "Marco Rossi",
      "email": "marco@example.com",
      "email_verified": false,
      "avatar": null,
      "google_linked": false,
      "google_locale": null,
      "created_at": "2025-01-15T10:30:00+00:00",
      "updated_at": "2025-01-15T10:30:00+00:00"
    },
    "token": "2|def456..."
  }
}
POST /api/auth/google

Google Sign-In

Autentica o registra un utente tramite Google ID token. Se l'account non esiste, viene creato automaticamente.

Parametri

id_token
string Obbligatorio

Token ID ottenuto da Google Sign-In

Risposta di esempio 200

{
  "success": true,
  "message": "Login via Google successful.",
  "data": {
    "user": {
      "id": 2,
      "name": "Laura",
      "surname": "Bianchi",
      "full_name": "Laura Bianchi",
      "email": "laura@gmail.com",
      "email_verified": true,
      "avatar": "https://lh3.googleusercontent.com/...",
      "google_linked": true,
      "google_locale": "it",
      "created_at": "2025-01-15T10:30:00+00:00",
      "updated_at": "2025-01-15T10:30:00+00:00"
    },
    "token": "3|ghi789...",
    "is_new": false
  }
}
GET /api/user Richiede autenticazione

Profilo utente

Recupera il profilo dell'utente autenticato.

Risposta di esempio 200

{
  "success": true,
  "message": "User profile retrieved.",
  "data": {
    "id": 1,
    "name": "Marco",
    "surname": "Rossi",
    "full_name": "Marco Rossi",
    "email": "marco@example.com",
    "email_verified": false,
    "avatar": null,
    "google_linked": false,
    "google_locale": null,
    "created_at": "2025-01-15T10:30:00+00:00",
    "updated_at": "2025-01-15T10:30:00+00:00"
  }
}
PUT /api/user Richiede autenticazione

Aggiorna profilo

Aggiorna i dati del profilo dell'utente autenticato. Inviare solo i campi da modificare.

Parametri

name
string Opzionale

Nome dell'utente

surname
string Opzionale

Cognome dell'utente

email
string Opzionale

Indirizzo email

Risposta di esempio 200

{
  "success": true,
  "message": "Profile updated.",
  "data": {
    "id": 1,
    "name": "Marco",
    "surname": "Verdi",
    "full_name": "Marco Verdi",
    "email": "marco@example.com",
    "email_verified": false,
    "avatar": null,
    "google_linked": false,
    "google_locale": null,
    "created_at": "2025-01-15T10:30:00+00:00",
    "updated_at": "2025-01-15T11:00:00+00:00"
  }
}
POST /api/auth/logout Richiede autenticazione

Logout

Revoca il token di accesso corrente dell'utente autenticato.

Risposta di esempio 200

{
  "success": true,
  "message": "Logged out successfully.",
  "data": null
}

Risorsa utente

Tutti gli endpoint che restituiscono dati utente utilizzano la seguente struttura:

id integer

Identificativo univoco

name string

Nome

surname string

Cognome

full_name string

Nome completo

email string

Indirizzo email

email_verified boolean

Se l'email è verificata

avatar string

URL dell'avatar (da Google)

google_linked boolean

Se l'account Google è collegato

google_locale string

Lingua dell'account Google

created_at string

Data di creazione (ISO 8601)

updated_at string

Data di ultimo aggiornamento (ISO 8601)

Risorsa prodotto

L'endpoint di ricerca prodotto restituisce la seguente struttura:

id integer

Identificativo univoco

barcode string

Codice a barre EAN

product_name string

Nome del prodotto

product_name_it string

Nome del prodotto in italiano

brand string

Marca

image_url string

URL dell'immagine del prodotto

nutriscore_grade string

Grado Nutri-Score (a-e)

ecoscore_grade string

Grado Eco-Score (a-e)

nova_group integer

Gruppo NOVA (1-4)

Valori nutrizionali (per 100g)

nutriments.energy_kcal decimal

Energia (kcal)

nutriments.fat decimal

Grassi (g)

nutriments.saturated_fat decimal

Grassi saturi (g)

nutriments.carbohydrates decimal

Carboidrati (g)

nutriments.sugars decimal

Zuccheri (g)

nutriments.fiber decimal

Fibre (g)

nutriments.proteins decimal

Proteine (g)

nutriments.salt decimal

Sale (g)

nutriments.sodium decimal

Sodio (g)

Filtri dietetici

filters.is_vegetarian boolean

Adatto ai vegetariani

filters.is_vegan boolean

Adatto ai vegani

filters.is_palm_oil_free boolean

Senza olio di palma

filters.is_gluten_free boolean

Senza glutine

filters.is_lactose_free boolean

Senza lattosio

filters.is_low_carbon boolean

Basso impatto ambientale

filters.is_diabetic_friendly boolean

Adatto ai diabetici

filters.is_ketogenic boolean

Adatto alla dieta chetogenica

GET /api/products/{barcode} Richiede API Key

Ricerca prodotto

Cerca un prodotto alimentare tramite codice a barre (EAN). Il prodotto viene recuperato da OpenFoodFacts e memorizzato nella cache locale per 7 giorni.

Nota: La risposta include un campo "source" che indica la provenienza dei dati: "cache" se serviti dal database locale, "openfoodfacts" se appena recuperati dall'API OpenFoodFacts.

Parametri

barcode
string Obbligatorio

Codice a barre EAN del prodotto (13 cifre)

Risposta di esempio 200

{
  "success": true,
  "message": "Product retrieved.",
  "source": "cache",
  "data": {
    "id": 1,
    "barcode": "3017620422003",
    "product_name": "Nutella",
    "product_name_it": "Nutella",
    "brand": "Ferrero",
    "image_url": "https://images.openfoodfacts.net/...",
    "nutriscore_grade": "e",
    "ecoscore_grade": null,
    "nova_group": 4,
    "nutriments": {
      "energy_kcal": "539.000",
      "fat": "30.900",
      "saturated_fat": "10.600",
      "carbohydrates": "57.500",
      "sugars": "56.300",
      "fiber": "0.000",
      "proteins": "6.300",
      "salt": "0.107",
      "sodium": "0.043"
    },
    "filters": {
      "is_vegetarian": true,
      "is_vegan": false,
      "is_palm_oil_free": false,
      "is_gluten_free": true,
      "is_lactose_free": false,
      "is_low_carbon": false,
      "is_diabetic_friendly": false,
      "is_ketogenic": false
    },
    "last_fetched_at": "2026-02-17T10:55:47+00:00",
    "created_at": "2026-02-17T10:55:47+00:00",
    "updated_at": "2026-02-17T10:55:47+00:00"
  }
}

Risposte di errore 404

{
  "success": false,
  "message": "Product not found."
}

Codici di stato HTTP

L'API utilizza i seguenti codici di stato HTTP:

Status Descrizione
200 Richiesta completata con successo
201 Risorsa creata con successo
401 Non autenticato o credenziali non valide
403 Accesso negato
404 Risorsa non trovata
422 Errore di validazione dei dati inviati
429 Troppe richieste (rate limit superato)
500 Errore interno del server
In sviluppo

Aiutaci a costruire HaoChi

Stiamo lavorando duramente per creare l'app che ti meriti. Supporta il progetto e riceverai 1 anno di accesso alle funzioni Pro al lancio!

Offrici un caffè