Entegrasyon tarifleri

Dört kalıp gördüğümüz hemen her entegrasyonu kapsar. Her biri birkaç çağrıdan ibarettir ve birbirleriyle birleşir.

Basılı bir kodu yönlendirme

Çoğu ekibin API’ye yönelmesinin başlıca nedeni. Ambalajdaki, etiketteki ya da afişteki bir kod, arkasındaki kampanya değişirken çalışmaya devam eder.

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" }'

Yayınlanmış bir kodda anında etkili olur — yeniden yayınlama adımı yoktur — ve yanıt, kodun live mi yoksa hâlâ taslak mı olduğunu söyler.

Bir CRM kaydına QR ekleme

Kodu kaydın kendi URL’siyle oluşturun, yayınlayın ve ardından görseli doğrudan bir dosya alanına çekin. Görsel endpoint’i baytları satır içi döndürür, bu yüzden çoğu CRM bunları ara bir yükleme olmadan ek olarak kabul eder.

const headers = { Authorization: `Bearer ${process.env.MOSAQO_KEY}` };

const created = await fetch('https://api.mosaqo.app/v1/public-api/qr', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: `Deal ${deal.id}`,
    mode: 'dynamic',
    contentType: 'url',
    content: { targetUrl: `https://crm.example.com/deals/${deal.id}` },
  }),
}).then((r) => r.json());

const qrId = created.data.id;
await fetch(`https://api.mosaqo.app/v1/public-api/qr/${qrId}/publish`, { method: 'POST', headers });

const png = await fetch(
  `https://api.mosaqo.app/v1/public-api/qr/${qrId}/image?format=png&size=1024`,
  { headers },
).then((r) => r.arrayBuffer());

Kaydınızda qrId değerini saklayın. Sonraki her şeyin tutamağı odur — yönlendirme, arşivleme, analitik.

Toplu kod üretme

Ürün başına, masa başına, ekipman başına bir kod. Bir CSV gönderin, işi sorgulayın, sonra sonuçları kendi satırlarınızla eşleştirin — her satır ürettiği qrId değerini taşır.

curl -X POST https://api.mosaqo.app/v1/public-api/bulk \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "url",
    "mode": "dynamic",
    "csv": "name,destination\nTable 1,https://example.com/menu?t=1\nTable 2,https://example.com/menu?t=2"
  }'

curl "https://api.mosaqo.app/v1/public-api/bulk/$JOB_ID?limit=500" \
  -H "Authorization: Bearer $MOSAQO_KEY"

Hiçbir şey yazmadan her satırı doğrulamak için önce "dryRun": true gönderin.

Görseli URL ile gömme

Airtable, Notion ve Sheets görseli kendilerinin çektiği bir bağlantıdan gösterir, dolayısıyla Authorization başlığınızı asla göndermezler ve yukarıdaki endpoint’i kullanamazlar. Bunun yerine imzalı bir bağlantı isteyin:

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/image-url \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "png", "size": 1024 }'

Yalnızca yayınlanmış kodlar uygundur — yayınlanmış bir kod zaten basılmış ve dünyadadır, oysa bir taslak duyurulmamış bir kampanya olabilir. Dönen url değerini doğrudan bir ek veya görsel alanına koyun. Kodu arşivlemek veya silmek bağlantıyı anında kapatır: amaçladığınızdan daha uzağa yayılmış bir bağlantı böyle geri alınır.

Taramalara tepki verme

Taramalar asla dışarı gönderilmez: tarama başına webhook yoktur ve tarama düzeyindeki analitiği üçüncü taraf endpoint’lerine göndermeyiz. Toplama yeterliyse scan.aggregate_ready olayına abone olun ya da tek tek taramaları bir zamanlamayla kendiniz çekin:

curl "https://api.mosaqo.app/v1/public-api/scans?since=$LAST_SEEN&limit=500" \
  -H "Authorization: Bearer $MOSAQO_KEY"

Dönen pagination.nextCursor değerini saklayın ve bir sonraki seferde geri gönderin. Sıralama kararlıdır, bu yüzden bir yoklayıcı asla aynı taramayı tekrar okumaz veya atlamaz. Hangi alanların görüneceği çalışma alanınızın analitik gizlilik ayarlarına bağlıdır — yanıt, ne bekleyeceğinizi bilmeniz için allowedDimensions listeler.

Yoklama sizin için gerçekten uygun değilse ve taramalara gerçekleştikleri anda ihtiyacınız varsa, bu varsayılan olarak değil, talep üzerine mümkündür.

Kod gerektirmeyen platformlar

Make, Zapier, n8n ve Pipedream bugün bile genel bir HTTP modülüyle Mosaqo ile konuşabilir ve ihtiyaç duydukları parçalar yerinde: bağlantı testi olarak GET /me, yineleyiciler için imleçli sayfalama ve bir tetikleyicinin kendi başına oluşturup kaldırdığı webhook abonelikleri.

Aynı OpenAPI belgesi Postman ve Insomnia’ya aktarılır ve openapi-typescript ya da herhangi bir OpenAPI üreticisiyle tipli bir istemci üretir.

Uyulmaya değer iki kural

• Herkese açık URL’yi değil, `qrId` değerini saklayın. URL kararlıdır ama sonraki her çağrının ihtiyaç duyduğu şey kimliktir.
• Silmek yerine arşivleyin. Silmek kalıcıdır ve basılı her kopyayı bozar; arşivlemek bir kodu yayından kaldırır ve geri alınabilir.

Endpoint ayrıntılarının tamamı API referansında.