Başlarken

Kendi yazılımınızdan (filo takip, ERP, ön muhasebe ya da kendi siteniz) doğrudan ilan açabilir, açtığınız ilanların durumunu okuyabilirsiniz. Site üzerinden açılan ilanlarla aynı kurallara tabidir — moderasyon açıksa API'den gelen ilan da incelemeye düşer.

Panelden anahtar üretmek gerekmez. İki şey yeterli: gizli sözcük (isteğin bize ait olduğunu kanıtlar) ve vergi numarası (ilanın hangi firmaya açılacağını belirler).

Kurulum

Sunucu yöneticisi .env dosyasına iki değer yazar ve konteynerleri yeniden başlatır:

# Rastgele, en az 32 karakter. Uretmek icin:  openssl rand -base64 48
INTEGRATION_SECRET=uzun-ve-rastgele-bir-gizli-sozcuk-buraya

# Istege bagli: yalnizca bu vergi numaralari adina ilan acilabilir.
# Bos birakilirsa numarasi kayitli her onayli firma kullanilabilir.
INTEGRATION_ALLOWED_TAX_NUMBERS=

# Istege bagli: yalnizca bu IP adreslerinden gelen istekler kabul edilir.
INTEGRATION_ALLOWED_IPS=

Aynı gizli sözcük, istek gönderen programın yapılandırmasına da yazılır. Tanımlı değilse entegrasyon uçları kapalıdır ve 503 döner — yapılandırılmamış bir ucun korumasız açık kalmaması için.

Ayrıca firmanın vergi numarası panelde kayıtlı olmalı: Firma bilgileri sayfasındaki “Vergi numarası” alanı. Numara girilmemişse eşleştirme yapılamaz ve istek 422 COMPANY_NOT_FOUND alır.

Kimlik doğrulama

Her isteğe X-Integration-Secret başlığını ekleyin; değer INTEGRATION_SECRET ile birebir aynı olmalı.

curl -X GET "https://servis.alcom.dev/api/v1/entegrasyon/firma?taxNumber=1234567890" \
  -H "X-Integration-Secret: $SERVISILAN_SECRET"

Sözcük Authorization başlığında taşınmaz: o başlığı sitenin oturum katmanı kullanıyor ve iki ayrı kimlik mekanizmasının aynı başlığı paylaşması okuyanı yanıltır.

Firma eşleştirme

Her istek bir taxNumber taşır. Sunucu bu numaraya ait kayıtlı bir firma arar:

• Firma bulunduysa ilan o firmanın adına açılır.
• Bulunamadıysa ilan açılmaz — 422 COMPANY_NOT_FOUND. Firmanın panelde vergi numarasını kaydetmiş olması gerekir.
• Firma onaylı değilse (başvuru bekliyor ya da askıda) 403 COMPANY_INACTIVE.

Karşılaştırma yalnızca rakamlar üzerinden yapılır: "123 456 7890", "1234567890" ile aynı sayılır. Bir vergi numarası sitede yalnızca bir firmaya kayıtlı olabilir.

İlan kimin adına yazılır?

İlanın sitede bir sahibi olmak zorundadır. ownerEmail göndermezseniz ilan firmanın yetkilisine yazılır — çoğu kurulum için doğrusu budur. Belirli bir kişiye yazılmasını istiyorsanız o üyenin e-posta adresini gönderin; adres o firmanın aktif bir üyesine ait değilse istek 422 OWNER_NOT_FOUND ile reddedilir, ilan yanlış hesaba açılmaz. Kullanılabilir adresleri GET /v1/entegrasyon/firma ucu listeler.

Uçlar

curl -X POST "https://servis.alcom.dev/api/v1/entegrasyon/ilanlar" \
  -H "X-Integration-Secret: $SERVISILAN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "taxNumber": "1234567890",
    "externalId": "ILAN-2026-00412",
    "adType": "VEHICLE_WANTED",
    "title": "Ankara-Konya güzergahinda 27 kisilik servis araci araniyor",
    "description": "Hafta ici sabah ve aksam personel servisi icin arac ariyoruz.",
    "vehicleTypeId": 3,
    "cityId": 6,
    "routeFromCityId": 6,
    "routeToCityId": 42,
    "priceAmount": 85000,
    "shiftStartTime": "07:00",
    "shiftEndTime": "18:30",
    "contactName": "Operasyon",
    "contactPhone": "05001112233"
  }'

İlan alanları

İlan gövdesi aşağıdaki alanları kabul eder. Tanınmayan alanlar yok sayılır. companyId gönderilmez — firmayı vergi numarası belirler.

Tekrarlanan istekler

Ağ koptuğunda yanıtı alamayabilirsiniz — ama ilan açılmış olabilir. externalId göndererek bu durumu güvenle çözersiniz: aynı numarayla ikinci istek yeni ilan açmaz, mevcut ilanı created: false ile geri verir. Numara yalnızca sizin firmanız içinde tekildir.

Yanıt içeriği

Her ilan yanıtı üç bloktan oluşur: ad (ilanın tüm alanları, id'lerin yanında adlarıyla), owner (ilanı taşıyan üye) ve company (firmanın tüm bilgileri). Böylece dönen kaydı kendi ekranınızda göstermek için ayrıca sözlük çekmeniz gerekmez.

{
  "created": true,
  "ad": {
    "id": "6f1c…", "referenceCode": "SI-4A2B9C11", "slug": "ankara-konya-…",
    "url": "https://servis.alcom.dev/ilan/ankara-konya-…",
    "externalId": "ILAN-2026-00412",
    "status": "PENDING_REVIEW", "statusLabel": "İncelemede",
    "adType": "VEHICLE_WANTED", "adTypeLabel": "İşime araç arıyorum",
    "visibility": "PUBLIC",
    "title": "…", "description": "…",
    "vehicleType": { "id": 3, "name": "Otobüs" },
    "city": { "id": 6, "name": "Ankara" }, "district": null,
    "routeFrom": { "city": { "id": 6, "name": "Ankara" }, "district": null, "text": null },
    "routeTo":   { "city": { "id": 42, "name": "Konya" }, "district": null, "text": null },
    "priceAmount": 85000, "shiftStartTime": "07:00", "shiftEndTime": "18:30",
    "contactName": "Operasyon", "contactPhone": "05001112233",
    "publishedAt": null, "expiresAt": null,
    "createdAt": "2026-09-08T08:12:44.512Z", "updatedAt": "2026-09-08T08:12:44.512Z"
  },
  "owner": {
    "id": "9ab3…", "email": "[email protected]",
    "fullName": "Örnek Firma Operasyon", "phone": "05001112233", "companyRole": "ADMIN"
  },
  "company": {
    "id": "1c4d…", "name": "Örnek Taşımacılık A.Ş.", "slug": "ornek-tasimacilik",
    "url": "https://servis.alcom.dev/firma/ornek-tasimacilik",
    "legalName": "Örnek Taşımacılık Anonim Şirketi",
    "taxNumber": "1234567890", "taxOffice": "Çankaya",
    "contactEmail": "[email protected]", "contactPhone": "03121112233",
    "phones": ["03121112233", "05001112233"],
    "city": { "id": 6, "name": "Ankara" }, "district": { "id": 88, "name": "Çankaya" },
    "employeeCount": 45, "fleetSize": 30,
    "status": "APPROVED", "isVerified": true, "defaultAdVisibility": "PUBLIC"
  }
}

Moderasyon açıkken yeni ilan PENDING_REVIEW durumunda başlar ve onaylandığında PUBLISHED olur. Durumu GET /v1/entegrasyon/ilanlar/ext:… ile sorgulayabilirsiniz.

Hatalar

Hata yanıtları message ve — ayırt etmeniz gereken durumlarda — sabit bir code taşır. Alan bazlı doğrulama hataları errors nesnesinde alan adıyla döner.

{
  "statusCode": 422,
  "code": "VALIDATION",
  "message": "Gönderilen alanlar geçersiz",
  "errors": {
    "title": ["Başlık en az 10 karakter"],
    "adType": ["Bu ilan tipi seçilen hesap için geçerli değil: firma adına araç/şoför aranır, bireysel olarak iş aranır"]
  }
}

Sınırlar

• Dakikada 300 istek. Aşıldığında 429 döner.
• İstek gövdesi en fazla 1 MB.
• İlan görselleri şu an API ile yüklenemez; ilan açıldıktan sonra panelden eklenir.
• Bu sürümde ilan oluşturma ve okuma desteklenir; güncelleme ve silme panelden yapılır.

Entegrasyon sırasında takıldığınız bir yer olursa [email protected] adresine yazın; isteğinizin gövdesini ve dönen hata metnini eklerseniz daha hızlı yanıt veririz.