ConverterHQDevelopers
API v1

Ortamlar ve versioning

Sandbox’tan üretime güvenle geçin ve v1 uyumluluk sözleşmesini anlayın.

Test ve live izoledir. Önce sandbox’ta entegre olun, failure path ve webhooks’u test edin, sonra config ve secrets’i bilinçli promote edin.

Sandbox ve üretim

Base URL ve key’i environment başına açıkça yapılandırın. Test credential live resource göremez ve tersi.

API v1 sözleşmesi

Public OpenAPI ve dokümante schema sözleşmedir. CI incompatible değişiklikleri engeller; deprecation veya yeni major gerekir.

Uyumlu eklemeler

Yeni optional fields, endpoints ve capabilities eklenebilir. Client bilinmeyen field’ları yok saymalı ve genişleyebilir enum’larda kırılgan exhaustive switch yapmamalıdır. Aynı kural çift özelindeki dönüştürme seçenekleri için de geçerlidir: ConverterHQ yeni isteğe bağlı seçenekler ekleyebilir; ancak mevcut bir v1 seçeneği kaldırılmaz, zorunlu hâle getirilmez, türü veya varsayılan anlamı değiştirilmez, enum değerleri azaltılmaz ya da kabul edilen aralığı daraltılmaz.

Deprecation

Deprecation changelog’da alternatif ve migration window ile duyurulur. Dokümante edilmemiş behavior veya internal endpoint’e güvenmeyin.