Claude per un assistente e-commerce in turco — calcolo al centesimo con Kunavo

Assistente per consigli sui prodotti basato su Claude per i vostri siti di e-commerce turchi: comprende query in linguaggio naturale del cliente come "se d'estate c'è il sole, vado in spiaggia, cosa posso comprare senza superare 1000 TL" e consiglia prodotti reali dal catalogo. Codice completo + calcolo dei costi mensili + IVA + strategia per le oscillazioni del cambio della TL.

Perché Claude Haiku 4.5?

Per attività del tipo "comprendi + formatta", come la raccomandazione di prodotti, Claude Haiku 4.5 offre circa l'85% della qualità di Sonnet 4.6 a un terzo del costo. Con i prezzi Kunavo:

• Haiku 4.5: input $0,40/1M, output $2,00/1M
• Sonnet 4.6: input $1,20/1M, output $6,00/1M

Catalogo di 200 prodotti + query del cliente = ~3K token di input, risposta JSON = ~200 token di output. Costo per chiamata: ~$0,0016 (circa ₺0,06).

Codice funzionante

import json
from openai import OpenAI

client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",
)

# Claude, json_schema tipindeki response_format'a uyar; json_object garanti edilmez.
ONERI = {
    "type": "object",
    "properties": {
        "oneriler": {"type": "array", "items": {
            "type": "object",
            "properties": {"urun_id": {"type": "string"}, "neden": {"type": "string"}},
            "required": ["urun_id", "neden"],
            "additionalProperties": False,
        }},
        "toplam_oneri": {"type": "integer"},
    },
    "required": ["oneriler", "toplam_oneri"],
    "additionalProperties": False,
}

def urun_oneri(kullanici_sorgusu: str, urun_katalogu: list[dict]) -> dict:
    """Müşterinin doğal dil sorgusuna göre 3-5 ürün önerir."""
    katalog_metni = "\n".join(
        f"- {u['id']}: {u['baslik']} | {u['kategori']} | {u['fiyat']} TL"
        for u in urun_katalogu[:200]
    )
    resp = client.chat.completions.create(
        model="claude-haiku-4-5",  # Hızlı + ucuz, ürün önerisi için yeterli
        messages=[
            {
                "role": "system",
                "content": [
                    {
                        "type": "text",
                        "text": (
                            "Sen bir Türk e-ticaret asistanısın. "
                            "Türkçe doğal konuş, samimi ama saygılı. "
                            "Cevap formatı JSON: "
                            '{"oneriler": [{"urun_id": "...", "neden": "..."}, ...], '
                            '"toplam_oneri": int}'
                        ),
                        "cache_control": {"type": "ephemeral"},
                    },
                ],
            },
            {
                "role": "user",
                "content": (
                    f"## Müşteri sorgusu\n{kullanici_sorgusu}\n\n"
                    f"## Mevcut katalog\n{katalog_metni}"
                ),
            },
        ],
        response_format={"type": "json_schema",
                         "json_schema": {"name": "oneri", "schema": ONERI}},
        max_tokens=400,
    )
    return json.loads(resp.choices[0].message.content)

Abbiamo contrassegnato il prompt di sistema con cache_control. Quando arrivano chiamate consecutive con lo stesso prompt, entra in funzione il prompt caching di Anthropic, risparmiando il 90% del costo di input.

Proiezione dei costi mensili

Confronto: gestire continuamente un assistente e-commerce con personale richiede almeno un team di supporto su 2-3 turni per oltre 1.000 consigli al giorno (~₺120.000/mese). Con l'AI, risparmio sui costi del 95%.

Strategia contro le oscillazioni del cambio della TL

Poiché Kunavo usa prezzi in USD, il costo aumenta quando la TL perde valore. Per attenuare questo effetto:

• Ricariche elevate: le ricariche da $1.000+ attivano un credito bonus aggiuntivo del 20% (ricarica $1.000, ricevi $1.200 di credito). Risparmio di circa il 17% in USD, con un margine indiretto contro le variazioni del cambio in TRY
• Prompt caching sempre attivo — libera un risparmio del 70%
• Tiering Haiku → Sonnet: risolvi le query semplici con Haiku e quelle complesse con Sonnet. Se ti serve un decisore automatico, consulta la cost optimization guide
• Limita l'output: con max_tokens=300 dimezzi il costo dell'output

Risoluzione dei problemi delle carte

La maggior parte delle banche turche mantiene disabilitate per impostazione predefinita le transazioni online internazionali. Se il checkout Stripe viene rifiutato:

• Chiedi alla tua banca di abilitare l'uso online internazionale della carta
• Sono supportate Visa, Mastercard, American Express e JCB
• Apple Pay può funzionare più facilmente; se configurato in Chrome / Android, è possibile selezionare anche Google Pay, ma la carta sottostante deve comunque essere abilitata alle operazioni internazionali

Conformità al KVKK

Se sono presenti dati personali del cliente (nome, telefono, indirizzo), anonimizzali prima di inviarli a un LLM. I dati di pagamento Stripe sono già coperti da PCI-DSS e restano fuori dal tuo ambiente. Kunavo non offre un accordo sul trattamento dei dati (DPA); le richieste vengono elaborate negli Stati Uniti e inoltrate ai fornitori dei modelli upstream. Se hai bisogno di un DPA, stipula direttamente un contratto con il fornitore del modello (Anthropic, OpenAI o le condizioni aziendali di Google).

Checklist per la produzione

• Esamina manualmente i primi 100 consigli e automatizza quando la qualità raggiunge ≥%80
• Imposta un limite di spesa giornaliero tramite /app/keys (per evitare picchi accidentali)
• Per i payload di errore, aggiungi un comportamento di fallback che mostri all'utente "mi dispiace, al momento non posso formulare consigli"
• Monitora il costo mensile da /app/usage e configura un avviso in caso di aumenti imprevisti

Per iniziare, registrati gratuitamente, ricarica da $10 e paga in base all'utilizzo. La documentazione completa è disponibile su /docs/quickstart.