Test e live sono isolati. Integra prima in sandbox, esercita errori e webhook e promuovi configurazione e segreti deliberatamente.
Sandbox e produzione
Configura base URL e key esplicitamente per ambiente. Le credenziali test non vedono risorse live e viceversa.
Contratto API v1
OpenAPI pubblico e schemi documentati formano il contratto. CI blocca modifiche incompatibili che richiedono deprecazione o nuova major.
Aggiunte compatibili
Possono comparire nuovi campi opzionali, endpoint e capabilities. I client devono ignorare campi sconosciuti ed evitare switch esaustivi fragili su enum estendibili. La stessa regola vale per le opzioni di conversione specifiche della coppia: ConverterHQ può aggiungere nuove opzioni facoltative, ma un’opzione v1 esistente non verrà rimossa, resa obbligatoria, modificata nel tipo o nella semantica predefinita, privata di valori enum o ristretta nel relativo intervallo accettato.
Deprecazioni
Ogni deprecazione viene annunciata nel changelog con alternativa e finestra di migrazione. Non dipendere da comportamento non documentato o endpoint interni.