API REST YOUCART

Non esiste un endpoint centrale: ogni negozio risponde sul proprio sottodominio, e il negozio viene riconosciuto dall'indirizzo della richiesta, non da un parametro.

https://tuonegozio.youcart.it/api/v1/…

È la ragione per cui una credenziale di un negozio non funziona sull'indirizzo di un altro: viene rifiutata con 401, anche se è valida a casa sua.

Per integrare un altro programma si usa una chiave API. Il token JWT serve alle applicazioni che agiscono per conto di una persona collegata, come la vetrina.

Chiave API — per i programmi

Si emette dal pannello del negozio, sezione Chiavi API. Va nell'intestazione X-Api-Key:

curl -H "X-Api-Key: yc_a1b2c3…" \
  https://tuonegozio.youcart.it/api/v1/youcart/prodotti

Token JWT — per conto di una persona

Si ottiene da POST /api/v1/auth/login e dura 30 minuti. Va in Authorization:

curl -H "Authorization: Bearer <token>" \
  https://tuonegozio.youcart.it/api/v1/auth/me

Sempre lo stesso, in caso di successo e di errore.

// riuscita
{ "success": true, "data": { … } }

// fallita — "errori" è sempre una lista
{ "success": false,
  "errori": [ { "codice": "VALIDATION", "messaggio": "…" } ] }

Codici che vale la pena distinguere

Il 402 è quello che sorprende di più: un endpoint può esistere, la credenziale essere giusta, e la risposta essere comunque un rifiuto perché quella funzionalità appartiene a un piano superiore. Nella tabella qui sotto gli endpoint interessati portano l'indicazione del piano minimo.

• Identificativi: esadecimali a 32 caratteri maiuscoli (A1B2…). Il confronto è sensibile: usali come li ricevi.
• Paginazione: ?pagina=1&per_pagina=24, massimo 100 per pagina. La risposta riporta pagina, per_pagina e totale.
• Importi: stringhe decimali, nella valuta del negozio — non è sempre l'euro. L'IVA è scomposta per aliquota.
• I prezzi non si inviano: prezzo, sconto e costo di spedizione vengono sempre riletti dal catalogo lato server. Un importo nel corpo della richiesta viene ignorato.
• Corpo: JSON, Content-Type: application/json.