L'API pubblica Escher V2 (/v1/*) richiede un token Bearer su ogni richiesta. Crea e gestisci i token nella pagina API tokens — apri il menu dell'account in basso a sinistra della barra laterale e scegli API tokens (/settings/api-tokens).
Prima devi abilitare l'accesso API
I token API sono limitati. La pagina ti permette di creare token solo se l'accesso API è attivato sul tuo account.
Se non è attivato, la pagina mostra:
API access isn't enabled on your account. Contact your account manager at support@theprintspace.co.uk to request it.
Invia un'email a support@theprintspace.co.uk per abilitarlo, poi torna a questa pagina.
Chi ha bisogno di token API
- Artisti che creano integrazioni personalizzate (ad esempio un sito portfolio che attiva drop su richiesta).
- Agenzie che gestiscono più account artist mediante automazione.
- Sviluppatori che creano tool interni che comunicano con l'API.
Se utilizzi solo l'interfaccia web per creare drop manualmente, non hai bisogno di un token.
Come creare
- Apri la pagina API tokens (menu account → API tokens).
- Inserisci un Token name (il placeholder del campo recita "Token name (e.g. 'Backend CI')") per poterlo identificare in seguito.
- Facoltativamente inserisci un Webhook URL — vedi sotto. Il placeholder del campo recita "Webhook URL (optional, https://…)"; lascialo vuoto oppure fornisci un URL completo
https://. - Fai clic su Generate token.
- Il token completo viene mostrato una sola volta, con la nota "Copy this token now — it will never be shown again." Copialo immediatamente.
- Conservalo in modo sicuro — in un secrets manager, nelle variabili d'ambiente della tua CI/CD, o in un file
.enval di fuori del controllo versione.
I nuovi token compaiono nell'elenco con queste colonne: Name, Prefix, Webhook, Created, Last used. Solo il prefisso viene memorizzato — il token completo non può essere recuperato dopo la creazione.
URL webhook facoltativo
Ogni token può avere un URL webhook https:// facoltativo. Configuralo quando generi il token, oppure modificalo in seguito: fai clic sulla matita accanto alla cella Webhook del token, inserisci un URL completo https:// (o cancellalo), e salva.
Cosa puoi fare con il token
L'intera superficie /v1 è documentata nell'endpoint OpenAPI (/openapi.json nel servizio API). Operazioni comuni:
- Creare drop —
POST /v1/drops. - Aggiungere prodotti ai drop —
POST /v1/drops/{drop_id}/products. - Configurare varianti —
PUT /v1/drops/{drop_id}/products/{product_id}/variants. - Attivare la pubblicazione —
POST /v1/drops/{drop_id}/publish. - Controllare lo stato di pubblicazione —
GET /v1/drops/{drop_id}/publish-attempts/latest. - Generare raccomandazioni —
POST /v1/recommendations. - Estrarre stili pagina da un URL —
POST /v1/styles/extract(restituisce cinque variazioni tra cui scegliere). - Salvare un preset di stile pagina —
POST /v1/styles.
Autenticazione
Passa il token come header Bearer su ogni richiesta:
Authorization: Bearer <your-token>
Un token mancante, revocato o non valido restituisce HTTP 401. Se l'accesso API è stato disabilitato sull'account, ottieni HTTP 403.
Limiti di frequenza
- Endpoint di lettura: 120 richieste al minuto per utente.
- Endpoint di scrittura: 30 richieste al minuto per utente.
Le richieste oltre il limite ricevono HTTP 429 con un header Retry-After. I limiti sono per utente, non per token, quindi più token dello stesso utente condividono lo stesso bucket.
Ciclo di vita del token
- Revocare — fai clic sul pulsante Revoke nella riga del token e conferma la finestra di dialogo ("Revoke … This cannot be undone and the token will stop working immediately."). Le richieste future con quel token restituiranno 401.
- Ruotare — genera un nuovo token, cambia l'integrazione per utilizzarlo, quindi revoca il vecchio. Nessun tempo di inattività se procedi nell'ordine giusto.
- Scadenza — i token non scadono automaticamente per impostazione predefinita. Ruota ogni 6–12 mesi come pratica di igiene della sicurezza.
Non condividere
I token sono credenziali complete — chiunque ne abbia uno può agire come te sulla piattaforma, inclusa la pubblicazione di drop e la modifica di prodotti. Trattali con la stessa cautela che useresti per una password.