REST API

REST API, kendi yazılımınızın uygulamanın yaptığını yapmasını sağlar: projeler ve ölçümleri, klasörler ve ürün kataloğu; Enterprise'ta kuruluşunuz, Enterprise sayfasının yönettiği şekliyle; Open Guest'te misafir bağlantınız, misafir projeleri ve teklif istekleri. JSON ile yanıt verir. Her alanı ve örneği içeren tam başvuru API dokümantasyonudur; bu sayfa ise genel bakıştır.

Dokümantasyonu uygulamadan açmak için codeGeliştirici > apiREST API yolunu izleyin ve menu_bookBelgeleri gör düğmesine basın.

Temel URL#

Her istek şuraya gider:

https://api.measuremaponline.com/api/v2

Kimlik doğrulama#

API anahtarınızı olduğu gibi, her isteğin Authorization başlığında gönderin. Anahtarı Geliştirici sayfasında oluşturun: bkz. API anahtarları.

curl https://api.measuremaponline.com/api/v2/projects/YOUR_PROJECT_ID \
  -H "Authorization: YOUR_API_KEY"

Her istek; anahtarın erişimine (örneğin Projeler Okuma), aboneliğinize ve bir web sayfasından gönderilen istekler için anahtarın web sitesi kısıtlamalarına göre denetlenir. Veri değiştirebilen anahtarları sunucunuzda tutun: bkz. anahtarınızı güvende tutun.

Canlı ve sandbox#

İkisi için de tek bir temel URL vardır. Karar anahtara aittir: bir sandbox anahtarı, canlı anahtarların hiç görmediği sandbox projelerini, klasörlerini ve ürünlerini okur ve yazar. Kuruluşunuzun kullanıcıları, koltukları ve ekipleri ikisinde de aynıdır, bu yüzden bunları değiştirmek canlı anahtar gerektirir. Sandbox anahtarıyla oluşturulan misafir projeleri hiçbir zaman faturalandırılmaz ve sandbox projeleri web sitenize yerleştirilemez. Token'lar ait oldukları ortamı bildirir.

API neleri kapsar#

Bilmeniz gereken birkaç şey:

• Bir anahtar kendi hesabının projelerine ve Enterprise'ta kuruluşun kullanıcılarının projelerine ulaşır.
• Bir projeyi silmek, uygulamadaki gibi onu Çöp kutusu içine koyar ve bunu yalnızca oluşturan kişi yapabilir; kalıcı olarak silmek için Çöp kutusu içinden forever=true ile silin. Bir klasörü silmek, projelerini Çöp kutusu içine koyar.
• Bir projenin ölçümlerinde bir şekil, ürünlerini sırayla productIds içinde listeler; productId bunların ilkidir.
• /projects/{pid}/mmp, uygulamanın dışa aktardığı .mmp dosyasının aynısını verir. Şeması github.com/blueblinkone/mmp-validator adresinde yayımlanmıştır. Yeni öğeler yalnızca isteğe bağlı olarak eklenir; bu yüzden eski bir dosya için yazılmış okuyucu çalışmaya devam eder.
• Open Guest'te API ile başlatılan bir misafir projesi (POST /open-guest/projects), misafir bağlantınızdan başlatılan gibi Open Guest kullanımınıza ve bütçenize sayılır.
• Open Guest'te person_pin_circleMisafir bağlantısı bölümünde, sunucunuz ve sayfanız için kod içeren Open Guest API kılavuzu vardır: sunucunuz canlı anahtarınızla POST /auth/token isteğinden bir token alır ve ziyaretçiyi, bilgileri doldurulmuş, kendine ait yeni bir projeye gönderir.
• İnsanlar kuruluşunuza yalnızca davetle katılır (POST /enterprise/invitations), Enterprise sayfasındaki gibi: hesabı olmayan birine hesap açılır ve parolasını kendisi seçer. API hiçbir zaman hesap oluşturmaz veya parola belirlemez.
• Bir kullanıcıyı kuruluştan çıkarmak (POST /enterprise/users/{uid}/remove) hesabını bırakır; birini silmek (DELETE /enterprise/users/{uid}) hesabı siler. Her iki durumda da yaptığı çalışma kuruluşta kalır, yöneticilerinizin paylaştığı, adını taşıyan yeni bir klasörde.
• Bir misafir teklifinizi istediğinde GET /open-guest/requests/{pid} kim olduğunu, ne yazdığını, ne ölçtüğünü ve Ürünler: Okuma ile birlikte teklifin kendisini yanıtlar.
• Open Guest'te token'lar ziyaretçileriniz için misafir projeleri başlatır. Bir ziyaretçiyi yerleşik bir haritada oturum açtıran POST /auth/iframe/token, Enterprise anahtarları içindir.
• Ürünler API ile hiçbir zaman silinmez, yalnızca arşivlenir ve bir ürünün maliyet fiyatı hiçbir zaman döndürülmez.
• Kadastro parselleri API'nin parçası değildir.

Yanıtlar ve hatalar#

Başarılı bir istek 200 durumuyla ve JSON ile yanıtlanır (.mmp dışa aktarımı XML ile yanıtlanır). Başarısız bir istek, bir hata durumu ve şuna benzer bir gövdeyle yanıtlanır:

{"errorCode": "insufficient_scope", "errorMessage": "This API key does not have the scope required for this endpoint"}

API'yi Geliştirici sayfasından deneyin#

codeGeliştirici > terminalAPI'yi deneyin, anahtarınızla gerçek istekler gönderir ve geri dönenleri olduğu gibi gösterir.

1. Canlı ya da Sandbox seçin.
2. Bir Uç nokta seçin; örneğin "Projelerinizi listele", "Ölçümleri getir" ya da "Hesabı getir". Liste, planınızın içerdiği uç noktaları sunar.
3. Parametrelerini doldurun. Bir proje ya da ürün, anahtarın okuyabildikleri arasından adıyla seçilir; bir kişi gerektiğinde kendi hesabınız sizin için doldurulur.
4. play_arrowİsteği gönder düğmesine basın. Durum ve yanıt aşağıda görünür.

Yalnızca okuyan istekler sunulur; bu yüzden denemekle hiçbir şey değişmez ve bu istekler kullanımınıza sayılmaz. Anahtarınız bir uç noktanın gerektirdiği erişime sahip değilse sayfa, 403 yanıtı vereceği konusunda sizi uyarır.

Webhook'lar#

Webhook, bildirim e-postalarının size söylediği gibi, bir şey olduğunda sunucunuza haber verir. Webhook'lar Enterprise ve Open Guest planlarının parçasıdır.

Webhook kurun#

codeGeliştirici > webhookWebhook'lar bölümünde:

1. Uç nokta URL'si alanına yazın: internette bir https:// adresi. Özel ağlardaki adresler reddedilir ve bu her teslimattan önce yeniden denetlenir.
2. İstediğiniz Olaylar olaylarını işaretleyin (bkz. olaylar). Yeni bir uç nokta, planınızın gönderdiği olaylarla başlar ve en az biri işaretli olmalıdır.
3. saveKaydet düğmesine basın. İlk seferde sayfa İmzalama gizli anahtarı değerinizi tam olarak gösterir. O zaman kopyalayın: sonrasında yalnızca son karakterleri gösterilir.
4. sendTest olayı gönder düğmesine basın ve bir olay seçin.

Bir test, o olayın örneğini, uydurma değerlerle ve data içinde "test": true olacak şekilde, olay işaretli olmasa ya da uç nokta kapalı olsa bile kayıtlı uç noktanıza gönderir. Tüm teslimatları durdurmak için delete_outlineKaldır düğmesine basın: uç nokta ve gizli anahtarı silinir.

Ayarların altında Webhook başvurusu, alıcı tarafı yazmak için gereken her şeyi içerir: başlıklar ve gövde, imzayı Node.js, Python ve PHP'de denetleyen kod ve her olay için örnek veriler.

Sunucunuzun aldığı#

Her olay, uç noktanıza JSON gövdeli tek bir POST olarak gelir:

{"id": "evt_3f9a1c2b7d4e5f60718293a4", "type": "project.created", "created": 1790000000000, "data": { ... }}

id her olay için benzersizdir, created olayın 1 Ocak 1970'ten (UTC) beri milisaniye cinsinden ne zaman gerçekleştiğidir ve data içeriği olaya göre değişir. İstek ayrıca şu başlıkları taşır:

• Yavaş bir işe girişmeden önce, 8 saniye içinde 2xx durumuyla yanıt verin. Başka herhangi bir durum, yönlendirme ya da zaman aşımı başarısızlık sayılır.
• Her olay bir kez gönderilir ve asla yeniden denenmez. Bölüm Son teslimat ve Art arda başarısızlıklar değerlerini gösterir.
• Üst üste 10 başarısızlıktan sonra uç nokta kapatılır ve sahip bir e-posta alır. Sunucunuzu düzeltin ve yeniden açmak için saveKaydet düğmesine basın.
• Arada bir olay iki kez ya da sırasız gelir. Tekrarları yok saymak için id, olayları sıraya koymak için created kullanın.

İmzayı denetleyin#

Adresinizi bilen herkes ona gönderi yapabilir; bu yüzden güvenmeden önce her teslimatı denetleyin:

1. X-MMO-Signature başlığını virgülden t ve v1 olarak ayırın.
2. İmzalama gizli anahtarınızı anahtar olarak kullanarak, t, bir nokta ve ham istek gövdesinden oluşan metnin HMAC-SHA256 değerini onaltılık olarak hesaplayın.
3. Sonucu v1 ile sabit zamanlı bir karşılaştırmayla karşılaştırın.
4. t, geçerli zamandan 5 dakikadan fazla uzaksa teslimatı reddedin. t milisaniye cinsindendir.

Gövdeyi tam olarak geldiği gibi kullanın: JSON'u ayrıştırıp yeniden yazmak onu değiştirir ve imza artık eşleşmez.

autorenewGizli anahtarı yenile, gizli anahtarı hemen değiştirir ve yenisini bir kez, tam olarak gösterir. Değiştirir değiştirmez sunucunuzu güncelleyin.

Olaylar#