İlk API isteğiniz

Erişim anahtarı oluşturun; proje verisini okuyun, izinli bir noktayı yazın ve değişiklikleri izleyin.

Son güncelleme: 2026-11-10

Bu örneği hazırlayın

Bu akışta erişim anahtarınızı kontrol edecek, projeyi okuyacak ve izinli bir eğitim projesine örnek nokta yazacaksınız. Temel adres kurumunuzun uygulama adresidir. SOSOMAPS_URL ile ERISIM_ANAHTARI değerlerini kendi ortamınızın güvenli yapılandırmasından sağlayın. Belgelerde gerçek bir kurulum adresi veya çalışır sır bulunmaz.

Not: Aşağıdaki yanıtlarda gösterilen değerler örnektir; kendi kurulumunuzdaki kimlikler ve değerler farklı olur.

curl örnekleri kabukta, Python örnekleri requests bulunan ortamda, JavaScript örnekleri sunucu tarafında fetch ve ortam değişkenlerini destekleyen bir çalışma ortamında kullanılır. Anahtarı ziyaretçiye gönderilen tarayıcı koduna koymayın. Örnekteki istemci zaman aşımı bir istemci tercihidir; sunucunun süre taahhüdü değildir.

Anahtarı arayüzden oluşturun

1. Kurum kullanıcısıyla uygulamaya giriş yapın. Kullanıcı menüsünde Erişim anahtarları seçin.
2. Anahtar oluştur düğmesine basın; Anahtar adı girin.
3. Projeler alanında Yalnız seçilen projeler seçip eğitim projenizi işaretleyin.
4. İlk okuma adımları için Yazma erişimi kapalı kalabilir. Yazma adımını uygulayacaksanız gerekli yetkiye sahip hesabın okuma ve yazma kapsamlı anahtarını kullanın.
5. Gerekiyorsa Bitiş zamanı seçip Oluştur kullanın.
6. Bir kez gösterilen Anahtar sırrı değerini güvenli yapılandırmanıza alın ve Kaydettim, gizle seçin.

Anahtarınızın kapsamı hesabınızın yetkisini artırmaz. Kimlik doğrulama ve anahtar yaşam döngüsü sayfaları iptal ve yenileme adımlarını açıklar.

Kimliği kontrol edin

GET /api/v1/me, kullanılan kullanıcıyı ve anahtarın güvenli üst verisini döndürür. Başlıkta Bearer kimliği gerekir; oturum çerezi bu uç için yeterli değildir.

curl --fail-with-body "$SOSOMAPS_URL/api/v1/me" \
  -H "Authorization: Bearer $ERISIM_ANAHTARI"

import os
import requests

yanit = requests.get(
    os.environ["SOSOMAPS_URL"].rstrip("/") + "/api/v1/me",
    headers={"Authorization": "Bearer " + os.environ["ERISIM_ANAHTARI"]},
    timeout=30,
)
yanit.raise_for_status()
print(yanit.json())

const yanit = await fetch(
  `${process.env.SOSOMAPS_URL.replace(/\/$/, '')}/api/v1/me`,
  { headers: { Authorization: `Bearer ${process.env.ERISIM_ANAHTARI}` } }
);
if (!yanit.ok) throw new Error(`HTTP ${yanit.status}`);
console.log(await yanit.json());

{
  "user": {
    "id": 42,
    "username": "ornek-kullanici",
    "full_name": "Örnek Kullanıcı",
    "org_id": 7
  },
  "anahtar": {
    "id": 9,
    "ad": "Envanter okuma",
    "kapsam": [
      "oku"
    ],
    "proje_ids": [
      123
    ],
    "bitis_at": null
  }
}

anahtar.proje_ids, anahtarda seçili proje kapsamıdır; null kullanıcının güncel erişimiyle sınırlı genel kapsamı gösterir. kapsam içinde yaz bulunması, her projede düzenlemeye izin verildiği anlamına gelmez.

Projeyi bulun

GET /api/v1/projects yanıtından proje kimliğini seçin. Yanıt bir dizidir; items zarfı yoktur. Aşağıdaki örnekte seçilen kimlik 123 olarak gösterilmiştir. Sonraki isteklerde kendi yanıtınızdaki değeri kullanın.

curl --fail-with-body "$SOSOMAPS_URL/api/v1/projects" \
  -H "Authorization: Bearer $ERISIM_ANAHTARI"

import os
import requests

yanit = requests.get(
    os.environ["SOSOMAPS_URL"].rstrip("/") + "/api/v1/projects",
    headers={"Authorization": "Bearer " + os.environ["ERISIM_ANAHTARI"]},
    timeout=30,
)
yanit.raise_for_status()
print(yanit.json())

const yanit = await fetch(
  `${process.env.SOSOMAPS_URL.replace(/\/$/, '')}/api/v1/projects`,
  { headers: { Authorization: `Bearer ${process.env.ERISIM_ANAHTARI}` } }
);
if (!yanit.ok) throw new Error(`HTTP ${yanit.status}`);
console.log(await yanit.json());

[
  {
    "id": 123,
    "org_id": 7,
    "name": "Örnek fiber projesi",
    "description": "Eğitim kaydı",
    "archived": false,
    "modules": [
      "saha",
      "fiber"
    ],
    "updated_at": "2026-11-10T09:00:00+00:00",
    "erisim": "kurum"
  }
]

Proje ayrıntısı için GET /api/v1/projects/{pid} kullanın. Ayrıntı yanıtındaki counts etkin türlere göre adet ve uzunluk bilgisi içerir. Proje listesinde bulunmayan bir kimliği tahmin ederek çağırmayın; kurum ve üyelik kapsamı her istekte uygulanır.

Nesneleri sayfalayın

İlk istekte bbox değerini minBoylam,minEnlem,maxBoylam,maxEnlem sırasıyla verebilirsiniz. Örnek sınır bir çalışma alanına aittir. limit sayfada istediğiniz kayıt sayısıdır.

curl --fail-with-body "$SOSOMAPS_URL/api/v1/projects/123/features?bbox=31.9,38.9,32.1,39.1&limit=100" \
  -H "Authorization: Bearer $ERISIM_ANAHTARI"

import os
import requests

yanit = requests.get(
    os.environ["SOSOMAPS_URL"].rstrip("/") + "/api/v1/projects/123/features?bbox=31.9,38.9,32.1,39.1&limit=100",
    headers={"Authorization": "Bearer " + os.environ["ERISIM_ANAHTARI"]},
    timeout=30,
)
yanit.raise_for_status()
print(yanit.json())

const yanit = await fetch(
  `${process.env.SOSOMAPS_URL.replace(/\/$/, '')}/api/v1/projects/123/features?bbox=31.9,38.9,32.1,39.1&limit=100`,
  { headers: { Authorization: `Bearer ${process.env.ERISIM_ANAHTARI}` } }
);
if (!yanit.ok) throw new Error(`HTTP ${yanit.status}`);
console.log(await yanit.json());

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "DOL-123",
      "geometry": {
        "type": "Point",
        "coordinates": [
          32.0,
          39.0
        ]
      },
      "properties": {
        "name": "Örnek dolap",
        "status": "planned",
        "id": "DOL-123",
        "type": "cabinet",
        "v": 1
      }
    }
  ],
  "next": null,
  "cursor": 25
}

next doluysa onu sonraki istekte after olarak gönderin; null son sayfadır. Filtreleri sayfalar arasında değiştirmeyin. Nesneleri kimlikleriyle işleyin. İlk okumanın cursor değerini ayrıca saklayın; bu değer nesne sayfalamasındaki next ile aynı şey değildir.

Aşağıdaki Python döngüsü bütün sayfaları okur. next metin kimliği olabilir; sayıya çevirmeyin. Döngü tamamlandığında ilk_cursor değişiklik izlemeye başlangıç değeridir.

import os
import requests

url = os.environ["SOSOMAPS_URL"].rstrip("/") + "/api/v1/projects/123/features"
baslik = {"Authorization": "Bearer " + os.environ["ERISIM_ANAHTARI"]}
params = {"bbox": "31.9,38.9,32.1,39.1", "limit": 100}
ilk_cursor = None
while True:
    yanit = requests.get(url, headers=baslik, params=params, timeout=30)
    yanit.raise_for_status()
    sayfa = yanit.json()
    if ilk_cursor is None:
        ilk_cursor = sayfa["cursor"]
    for nesne in sayfa["features"]:
        print(nesne["id"], nesne["properties"]["v"])
    if sayfa["next"] is None:
        break
    params["after"] = sayfa["next"]

İzinli projeye ilk noktayı yazın

Yazma adımı kayıt oluşturur. Eğitim projenizi, anahtarın oku ve yaz kapsamını, hesabın proje ve bölge izinlerini kontrol edin. Aşağıdaki gövdeyi istek.json olarak kaydedin. Her yeni iş için ayrı request_id seçin; aynı işin yanıtı kaybolursa aynı kimlik ve aynı ops ile tekrar deneyin.

{
  "request_id": "ornek-duzenleme-20261110-01",
  "note": "Örnek nokta kaydı",
  "ops": [
    {
      "op": "create",
      "entity": "feature",
      "id": "gecici-dolap",
      "type": "cabinet",
      "geometry": {
        "type": "Point",
        "coordinates": [
          32.0,
          39.0
        ]
      },
      "props": {
        "name": "Örnek dolap",
        "status": "planned"
      }
    }
  ]
}

curl --fail-with-body "$SOSOMAPS_URL/api/v1/projects/123/edit" \
  -H "Authorization: Bearer $ERISIM_ANAHTARI" \
  -H 'Content-Type: application/json' \
  --data-binary @istek.json

import json
import os
import requests

with open("istek.json", encoding="utf-8") as dosya:
    istek = json.load(dosya)
yanit = requests.post(
    os.environ["SOSOMAPS_URL"].rstrip("/") + "/api/v1/projects/123/edit",
    headers={"Authorization": "Bearer " + os.environ["ERISIM_ANAHTARI"]},
    json=istek, timeout=30,
)
yanit.raise_for_status()
print(yanit.json())

import { readFile } from 'node:fs/promises';
const istek = JSON.parse(await readFile('istek.json', 'utf8'));
const yanit = await fetch(
  `${process.env.SOSOMAPS_URL.replace(/\/$/, '')}/api/v1/projects/123/edit`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ERISIM_ANAHTARI}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(istek)
  }
);
if (!yanit.ok) throw new Error(`HTTP ${yanit.status}`);
console.log(await yanit.json());

Temsili başarı yanıtı:

{
  "ok": true,
  "batch": "ornek-islem",
  "ids": [
    "DOL-123"
  ],
  "tmp": {
    "gecici-dolap": "DOL-123"
  },
  "features": [
    {
      "type": "Feature",
      "id": "DOL-123",
      "geometry": {
        "type": "Point",
        "coordinates": [
          32.0,
          39.0
        ]
      },
      "properties": {
        "name": "Örnek dolap",
        "status": "planned",
        "id": "DOL-123",
        "type": "cabinet",
        "v": 1,
        "_deleted": false
      }
    }
  ]
}

tmp, istekteki geçici kimliği kalıcı kayda eşler. Sonraki güncellemede features içindeki properties.v değerini version olarak gönderin; oluşturma işleminde mevcut bir kayıt sürümü yoktur. Sürümü tahmin ederek artırmayın. Aynı isteğin kabul edilmiş tekrarı replayed: true içerebilir.

Değişiklikleri izleyin

İlk okumanın cursor değerini GET /api/v1/projects/123/changes?after=25&limit=100 isteğinde kullanın. Gösterilen 25 örnek değerdir. Yeni değişiklik yoksa yanıt şöyledir:

{"items": [], "next": null}

Değişiklik varsa items satırlarını artan id sırasıyla uygulayın ve başarıyla işlediğiniz son kimliği kalıcı saklayın. next dolu olduğu sürece sayfalamaya devam edin. Bazı satırlarda before ve after yerine gizli: true bulunabilir; bu, o kaydın ayrıntısını görme kapsamınız olmadığını gösterir. Kapsam değiştiğinde görünümü yeniden kurun.

401 için anahtarı, 403 için kapsam ve yetkiyi, 409 için güncel kayıt sürümünü kontrol edin. 429 yanıtında Retry-After değerini bekleyin. Yazma yanıtının kaybolması işlemin yapılmadığını kanıtlamaz. Ayrıntılar sözleşme kuralları, hata kodları ve v1 API referansında bulunur.

İstemcinize taşıyın

Yayımlanmış resmi SDK yoktur. v1 OpenAPI dosyasını kendi istemci üretim aracınıza, Postman koleksiyonunu istek çalışma alanınıza aktarabilirsiniz. Genel bakıştaki istemci üretimi örneği, temel adres ve Bearer başlığının yapılandırılmasıyla birlikte başlangıç sağlar.