Geliştiriciler için Mosaqo API

Uygulamada kullandığınız çalışma alanının üzerinde bir REST API. Aşağıdaki her şey tek bir API anahtarı ve herhangi bir HTTP istemcisiyle çalışır.

Neler yapabilirsiniz

Kendi kayıtlarınızdan QR kodu oluşturmak — teker teker ya da bir CSV’den on bin tane.
Basılı bir kodun nereye gittiğini değiştirmek, tek bir çağrıyla ve hiçbir şeyi yeniden basmadan.
Bitmiş kartı PNG, SVG veya PDF olarak indirip bir CRM kaydına eklemek.
Taramaları ve toplu analitiği, çalışma alanınızın gizlilik kurallarıyla süzülmüş olarak okumak.
Kodlar oluşturulduğunda, yayınlandığında, değiştiğinde veya arşivlendiğinde imzalı webhook almak.

Hızlı başlangıç

Çalışma alanınızdaki Bulk & API bölümünden bir anahtar oluşturun, qr:write ve qr:read kapsamlarını işaretleyin ve gizli anahtarı kopyalayın — yalnızca bir kez gösterilir.

Anahtarı doğrulayın ve hangi çalışma alanını açtığını öğrenin:

curl https://api.mosaqo.app/v1/public-api/me \
  -H "Authorization: Bearer $MOSAQO_KEY"

Dinamik bir QR kodu oluşturun:

curl -X POST https://api.mosaqo.app/v1/public-api/qr \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Autumn campaign",
    "mode": "dynamic",
    "contentType": "url",
    "content": { "targetUrl": "https://example.com/autumn" }
  }'

Yayınlayın — yönlendirmeyi çalıştıran şey budur — ardından basabileceğiniz görseli alın:

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/publish \
  -H "Authorization: Bearer $MOSAQO_KEY"

curl https://api.mosaqo.app/v1/public-api/qr/$QR_ID/image?format=png&size=2048 \
  -H "Authorization: Bearer $MOSAQO_KEY" -o campaign.png

Aylar sonra kampanya değiştiğinde, aynı basılı kodu yeniden basmadan yönlendirin:

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/destination \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/winter" }'

Kimlik doğrulama

Gizli anahtarınızı iki yoldan biriyle gönderin. İkisi de v1 boyunca geçerlidir.

Authorization: Bearer mosaqo_xxx
X-Mosaqo-API-Key: mosaqo_xxx

Bir anahtar tam olarak bir çalışma alanına aittir, bu yüzden yollarda çalışma alanı kimliği gerekmez: /v1/public-api/qr yeterlidir. Eski biçim /v1/public-api/workspaces/{workspaceId}/qr hâlâ çalışır.

Kapsam	Neye izin verir
`qr:read`	QR kodlarını, klasörleri ve şablonları listelemek ve okumak
`qr:write`	Oluşturmak, değiştirmek, yönlendirmek, yayınlamak, arşivlemek ve silmek
`exports:read`	Oluşturulmuş kartları indirmek
`analytics:read`	Toplu analitik ve tek tek taramalar
`bulk:write`	Toplu işleri oluşturmak ve okumak
`webhooks:write`	Webhook aboneliklerini yönetmek

Anahtarlar iptal edilebilir, son kullanma tarihi alabilir ve bir IP izin listesiyle sınırlanabilir. Anahtarı reddeden şey bu listeyse, bunu açıkça söyleriz; geçersizmiş gibi göstermeyiz.

Sayfalama

Listeler anahtar tabanlı sayfalama kullanır. pagination.nextCursor değerini olduğu gibi geri gönderin: senkronizasyonun ortasında bir şey düzenlendi diye satırlar asla tekrarlanmaz veya kaybolmaz — gece çalışan bir senkronizasyonda bu önemlidir.

curl "https://api.mosaqo.app/v1/public-api/qr?limit=50&cursor=$CURSOR" \
  -H "Authorization: Bearer $MOSAQO_KEY"

Her şeyi baştan taramak yerine değişiklikleri sormak için updatedSince=2026-08-05T00:00:00Z ekleyin.

Hatalar

Her hata, dallanabileceğiniz kararlı bir code, okunabilir bir message ve destekte belirtmeye değer bir requestId taşır.

{
  "error": "This API key does not have the qr:write scope.",
  "message": "This API key does not have the qr:write scope.",
  "code": "insufficient_scope",
  "details": { "required": "qr:write", "granted": ["qr:read"] },
  "requestId": "req-42"
}

Durum	Kodlar	Ne yapmalı
401	`invalid_api_key`	Anahtar yok, iptal edilmiş veya süresi dolmuş. Kullanıcıdan yeniden bağlanmasını isteyin.
403	`insufficient_scope`, `ip_not_allowed`, `workspace_mismatch`, `quota_exceeded`	Anahtar geçerli ama bu yetkiye sahip değil. Yeniden bağlanmak işe yaramaz.
404	`not_found`	Bu çalışma alanında böyle bir kayıt yok.
409	`idempotency_conflict`, `idempotency_in_progress`	Anahtar farklı verilerle yeniden kullanıldı ya da ilk deneme hâlâ sürüyor.
422	`validation_failed`, `invalid_cursor`, `approval_required`, `contrast_check_failed`	Girdiyi düzeltin. Değiştirmeden asla yeniden denemeyin.
429	`rate_limited`	`Retry-After` başlığındaki saniye kadar bekleyin.

İstek limitleri

Her yanıt, yalnızca reddedilenler değil, güncel bütçenizi taşır:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 1785942718

Limit kötüye kullanıma karşı bir korumadır, bir plan değil: kota, faturalandırma veya üst pakete geçiş anlamına gelmez.

İdempotentlik

Idempotency-Key isteğe bağlıdır. Bir tane gönderin — herhangi bir benzersiz dize — ve aynı isteği 24 saat içinde yinelemek, iki kez işlem yapmak yerine ilk yanıtı tekrar oynatır. Aynı anahtar farklı veriyle 409 döner. Anahtarsız istek yalnızca çalışır, yineleme koruması olmadan.

Sırada

Webhook’lar — olay kataloğu ve bir teslimatın nasıl doğrulanacağı.
Tarifler — Make, Zapier, n8n ve CRM kalıpları.
API referansı — her endpoint, canlı konsolla.