Ambienti
Differenze tra sandbox, staging e produzione: credenziali, dati di test, promozione, IP statici e finestre di manutenzione.
Blu Pantheon espone tre ambienti indipendenti. Ognuno ha base URL, credenziali e dati separati: una chiave API di sandbox non funziona in produzione e viceversa.
Confronto
| Produzione | Staging | Sandbox | |
|---|---|---|---|
| Base URL | https://api.blupantheon.com | https://api.staging.blupantheon.com | https://api.sandbox.blupantheon.com |
| Prefisso chiavi | bp_live_ | bp_stg_ | bp_test_ |
| Scopo | Traffico reale dei clienti | Verifica pre-rilascio, collaudo di release | Sviluppo e test di integrazione |
| Dati | Reali, persistenti | Copia anonimizzata, rigenerata mensilmente | Sintetici, azzerabili su richiesta |
| Disponibilità | SLA 99,9 per cento | Nessuno SLA | Nessuno SLA |
| Limiti di chiamata | Secondo piano sottoscritto | Pari al piano Business | Ridotti al 20 per cento |
| Modelli AI | Produzione, versione stabile | Produzione, versione stabile | Modelli ridotti, risposte deterministiche opzionali |
| Email e SMS | Recapitati realmente | Intercettati, non recapitati | Intercettati, non recapitati |
| Pagamenti | Reali | Simulati | Simulati |
| Conservazione dati | Secondo policy del tenant | 30 giorni | 14 giorni |
Webhook livemode | true | false | false |
Non incrociare gli ambienti
Non usare mai dati reali di clienti in sandbox o staging: gli ambienti non di produzione hanno politiche di conservazione e controlli di accesso differenti, e l'inserimento di dati personali reali costituisce una violazione delle policy interne e degli obblighi verso i tuoi interessati.
Ottenere le credenziali di sandbox
Prima di iniziare
- Un account Blu Pantheon con ruolo Amministratore
- Un tenant attivo su qualsiasi piano, prova inclusa
Attiva la sandbox
La sandbox è disponibile per tutti i piani e va attivata una volta per tenant.
L'attivazione crea un tenant gemello con lo stesso slug, popolato con il set di dati di test descritto più avanti. Richiede alcuni minuti.
Crea una chiave di test
Nella sandbox le chiavi si creano dalla stessa sezione della Console, con l'ambiente impostato su sandbox.
Chiave sandbox
bp_test_••••••••••••••••Visibile una sola volta. Non ha effetti su dati reali.
Configura il tuo ambiente locale
Punta il client alla sandbox tramite variabili di ambiente, senza modificare il codice.
BP_BASE_URL=https://api.sandbox.blupantheon.com
BP_API_KEY=bp_test_xxxxxxxxxxxxxxxx
BP_TENANT_SLUG=acmeVerifica la connessione
curl -sS https://api.sandbox.blupantheon.com/identity/v1/me \
-H "Authorization: Bearer bp_test_xxxxxxxxxxxxxxxx"La risposta deve contenere "livemode": false. Se contiene true stai chiamando l'ambiente sbagliato.
L'accesso a staging è riservato ai piani Enterprise e va richiesto al referente tecnico: non è autoprovisionabile dalla Console.
Dati di test
La sandbox viene inizializzata con un set di dati coerente che puoi usare negli script di integrazione.
| Risorsa | Identificativo | Note |
|---|---|---|
| Tenant | tnt_sandbox_0001 | Slug identico a quello di produzione |
| Progetto | bp_proj_7f3a9c21 | Progetto dimostrativo pubblicato, canale web attivo |
| Knowledge base | ds_3c8f1a60 | 12 documenti già indicizzati |
| Cliente | cli_5e1a7b30 | mario.rossi@acme.it, anagrafica completa |
| Utente operatore | usr_4a7b1e90 | Ruolo operator, con coda vendite |
| Servizio prenotabile | svc_1d9a4f70 | Slot da 30 minuti, orario 9-18 dal lunedì al venerdì |
Comportamenti deterministici
Alcuni valori speciali attivano risposte prevedibili, utili per i test automatici.
| Valore | Dove usarlo | Effetto |
|---|---|---|
test-fail@blupantheon.com | Campo email di un cliente | Restituisce VALIDATION_ERROR |
test-timeout@blupantheon.com | Campo email di un cliente | Simula un timeout del servizio a monte |
FORZA_HANDOVER | Testo di un messaggio in sessione | Attiva immediatamente handover.requested |
FORZA_QUOTA | Header X-BP-Test-Scenario | Restituisce QUOTA_EXCEEDED |
FORZA_429 | Header X-BP-Test-Scenario | Restituisce RATE_LIMITED con Retry-After: 5 |
curl -sS https://api.sandbox.blupantheon.com/console/v1/sessions \
-H "Authorization: Bearer bp_test_xxxxxxxxxxxxxxxx" \
-H "X-BP-Test-Scenario: FORZA_429"Carte di pagamento di test
Utilizzabili solo in sandbox e staging, sui flussi di attivazione dell'abbonamento.
| Numero | Circuito | Esito |
|---|---|---|
4242 4242 4242 4242 | Visa | Pagamento approvato |
5555 5555 5555 4444 | Mastercard | Pagamento approvato |
4000 0000 0000 0002 | Visa | Rifiutata, PAYMENT_METHOD_DECLINED |
4000 0000 0000 9995 | Visa | Fondi insufficienti |
4000 0025 0000 3155 | Visa | Richiede autenticazione forte (3D Secure) |
Per tutte: data di scadenza qualsiasi nel futuro, CVC di tre cifre qualsiasi, CAP qualsiasi.
Le carte di test non funzionano in produzione
Un tentativo di usare una carta di test su api.blupantheon.com viene rifiutato con
PAYMENT_METHOD_DECLINED e registrato negli eventi di sicurezza del tenant.
Differenze dalla produzione
Conosci queste differenze prima di considerare un test superato.
Sandbox e staging girano su infrastruttura ridotta e condivisa. I tempi di risposta possono essere sensibilmente superiori a quelli di produzione: non usarli per test di carico o per misurare le latenze attese. I test di carico su produzione vanno concordati preventivamente.
Email e SMS generati in sandbox e staging non raggiungono i destinatari reali. Puoi consultarne il contenuto dalla Console nella sezione delle comunicazioni in uscita, con evidenza di destinatario, oggetto e corpo del messaggio.
La sandbox usa modelli più leggeri per contenere i costi. Le risposte sono coerenti nella struttura ma possono differire nei contenuti rispetto alla produzione: verifica in staging la qualità delle risposte prima del rilascio.
I dati di sandbox vengono conservati 14 giorni e possono essere azzerati su richiesta o durante gli aggiornamenti maggiori della piattaforma. Non usare la sandbox come archivio.
Sandbox e staging non sono coperti da SLA e possono essere resi indisponibili senza preavviso per attività tecniche. Progetta le pipeline in modo che un'indisponibilità non blocchi il rilascio.
Promozione verso la produzione
Checklist da completare prima di attivare un'integrazione su dati reali.
Credenziali e configurazione
- Chiave
bp_live_creata con i soli scope necessari e caricata nel secret manager. - Nessuna credenziale presente nel repository, nei file di configurazione versionati o nelle variabili di build pubbliche.
- Base URL parametrizzato: nessun host cablato nel codice.
- Rotazione delle chiavi pianificata e documentata.
Robustezza
- Gestione di tutti gli status documentati, non solo di
200. - Ritentativi con backoff esponenziale e jitter su
429,502,503,504. Idempotency-Keysu tutte le scritture, generata prima del primo tentativo.- Timeout esplicito su ogni chiamata, non affidato al valore predefinito della libreria.
- Paginazione che termina su
hasMoree non sulla dimensione della pagina.
Webhook
- Endpoint pubblico raggiungibile con certificato TLS valido.
- Verifica della firma HMAC con confronto a tempo costante e controllo della finestra temporale.
- Consumatore idempotente basato sull'
iddell'evento. - Risposta
2xxentro 5 secondi, con elaborazione asincrona. - Vedi Riferimento webhook.
Osservabilità
traceIdregistrato in ogni log relativo a una chiamata API.- Metriche su tasso di errore, latenza e
X-RateLimit-Remaining. - Allarme sul superamento dell'80 per cento della quota e sui fallimenti di consegna dei webhook.
- Nessuna credenziale o dato personale nei log.
Verifica finale
- Test end-to-end eseguito in sandbox con esito positivo.
- Piano di rollback definito e provato.
- Referenti tecnici e canale di escalation documentati.
- Prima esecuzione in produzione su un volume ridotto, con verifica manuale dei risultati.
Indirizzi IP
Allowlist in ingresso
Puoi limitare l'uso delle API agli indirizzi della tua infrastruttura, a livello di tenant o di singola chiave API.
Sono accettati indirizzi singoli e reti CIDR, IPv4 e IPv6. Una chiamata da un indirizzo non autorizzato
riceve 403 con codice IP_NOT_ALLOWED.
{
"security": {
"ipAllowlist": ["203.0.113.0/24", "198.51.100.42/32", "2001:db8::/32"]
}
}Verifica prima di attivare
Un'allowlist errata blocca immediatamente tutte le integrazioni. Attivala prima su una singola chiave di test, verifica il traffico e solo dopo estendila a livello di tenant. Mantieni sempre un accesso alternativo dalla Console per poterla correggere.
IP statici in uscita
Le chiamate in uscita di Blu Pantheon — consegne webhook e chiamate agli strumenti esterni configurati nei progetti — provengono da un insieme fisso di indirizzi. Inseriscili nella allowlist del tuo firewall.
| Ambiente | Indirizzi in uscita |
|---|---|
| Produzione | 203.0.113.10, 203.0.113.11, 203.0.113.12 |
| Staging | 203.0.113.40, 203.0.113.41 |
| Sandbox | 203.0.113.70 |
L'elenco aggiornato in formato machine readable è disponibile senza autenticazione:
Elenco IP
https://api.blupantheon.com/.well-known/egress-ips.jsonAggiornato a ogni variazione, con preavviso di 30 giorni.
Preavviso sulle variazioni
Le modifiche agli IP in uscita vengono comunicate con almeno 30 giorni di anticipo agli amministratori del tenant. Se la tua sicurezza perimetrale dipende da questi indirizzi, sottoscrivi le comunicazioni tecniche e verifica periodicamente l'elenco pubblicato.
Manutenzione e stato del servizio
| Ambiente | Finestra ordinaria | Preavviso |
|---|---|---|
| Produzione | Domenica 02:00-05:00 CET, al massimo una volta al mese | 7 giorni |
| Staging | Martedì e giovedì 20:00-23:00 CET | 24 ore |
| Sandbox | In qualsiasi momento | Nessuno |
Durante una manutenzione con interruzione le API rispondono 503 con codice MAINTENANCE_MODE e
l'header Retry-After. La maggior parte degli interventi avviene senza interruzione del servizio.
Per lo stato dei componenti, gli incidenti in corso e lo storico, scrivi a support@blupantheon.com.
Puoi verificare programmaticamente la disponibilità di ciascun servizio:
/healthPubblicoRestituisce lo stato del servizio. Non consuma quota e non richiede autenticazione.
{
"status": "operational",
"environment": "production",
"region": "eu-west",
"services": {
"identity": "operational",
"console": "operational",
"billing": "operational",
"booking": "degraded"
},
"timestamp": "2026-09-04T13:44:02.118Z"
}Non usare /health come health check applicativo
L'endpoint riflette lo stato della piattaforma, non la raggiungibilità della tua integrazione. Interrogalo al massimo una volta al minuto: un polling più frequente non fornisce informazioni aggiuntive e viene comunque limitato per IP.