ConverterHQDevelopers
API v1

Ambienti e versioning

Passa in sicurezza da sandbox a produzione e comprendi il contratto v1.

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.