# Follow a company

`POST https://ulawk.com/api/v1/sirket-ekle/`

Follows a company by registry office and registry number. The request does not wait: the record is created at once and notices and the profile are prepared in the background; poll `durum_adresi`. If the same company (same office + same registry root, `325075-0` = `325075`) is already on your list, no second record is created, `zaten_var` is returned and no allowance is used. With a sandbox key nothing is created; a new number is routed to the `DENEME-YAVAS` flow.

## Authentication

Two headers on every request: `X-API-Key` and `X-API-Secret`.

## Request body

- `mudurluk` (string, zorunlu) — Registry office (e.g. İSTANBUL).
- `sicil_no` (string, zorunlu) — Registry number; starts with a digit.
- `unvan` (string) — Optional company name.

```json
{
  "mudurluk": "İSTANBUL",
  "sicil_no": "555555"
}
```

## Response

### 201 — Followed (`eklendi`).

- `durum` (string, zorunlu) — eklendi (201) or zaten_var (200, no allowance used). Değerler: eklendi, zaten_var.
- `sirket_id` (integer | string, zorunlu) — Company id: numeric with a live key (e.g. 1234); a DENEME-… string with a sandbox key.
- `kayit_id` (integer, null, zorunlu)
- `unvan` (string, null)
- `mudurluk` (string, zorunlu)
- `sicil_no` (string, zorunlu)
- `aciklama` (string)
- `profil` (string (uri), zorunlu)
- `durum_adresi` (string (uri), zorunlu) — Status polling URL.

```json
{
  "durum": "eklendi",
  "sirket_id": "DENEME-YAVAS",
  "kayit_id": null,
  "mudurluk": "İSTANBUL",
  "sicil_no": "555555",
  "aciklama": "Deneme ortamı: kayıt açılmadı, paket hakkı harcanmadı. Hazırlanma akışını DENEME-YAVAS ile izleyin.",
  "profil": "https://ulawk.com/api/v1/sirketler/DENEME-YAVAS/",
  "durum_adresi": "https://ulawk.com/api/v1/sirketler/DENEME-YAVAS/durum/"
}
```

### 200 — Already on your list (`zaten_var`).

- `durum` (string, zorunlu) — eklendi (201) or zaten_var (200, no allowance used). Değerler: eklendi, zaten_var.
- `sirket_id` (integer | string, zorunlu) — Company id: numeric with a live key (e.g. 1234); a DENEME-… string with a sandbox key.
- `kayit_id` (integer, null, zorunlu)
- `unvan` (string, null)
- `mudurluk` (string, zorunlu)
- `sicil_no` (string, zorunlu)
- `aciklama` (string)
- `profil` (string (uri), zorunlu)
- `durum_adresi` (string (uri), zorunlu) — Status polling URL.

```json
{
  "durum": "zaten_var",
  "sirket_id": "DENEME-100001",
  "kayit_id": null,
  "unvan": "ÖRNEK DENEME SANAYİ VE TİCARET ANONİM ŞİRKETİ",
  "mudurluk": "İSTANBUL",
  "sicil_no": "DENEME-100001",
  "profil": "https://ulawk.com/api/v1/sirketler/DENEME-100001/",
  "durum_adresi": "https://ulawk.com/api/v1/sirketler/DENEME-100001/durum/"
}
```

### 400 — `eksik_alan` or `gecersiz_sicil`.


```json
{
  "hata": "eksik_alan",
  "detay": "'mudurluk' ve 'sicil_no' zorunludur.",
  "hata_ayrinti": {
    "kod": "eksik_alan",
    "mesaj": "'mudurluk' ve 'sicil_no' zorunludur.",
    "taraf": "istemci",
    "kaynak": null,
    "tekrar_denenebilir": false,
    "tekrar_sn": null
  }
}
```

### 402 — Plan allowance used up (`kota_doldu`).


```json
{
  "hata": "kota_doldu",
  "detay": "Paket şirket hakkınız doldu.",
  "hata_ayrinti": {
    "kod": "kota_doldu",
    "mesaj": "Paket şirket hakkınız doldu.",
    "taraf": "istemci",
    "kaynak": null,
    "tekrar_denenebilir": false,
    "tekrar_sn": null
  }
}
```

### 405 — POST expected (`yontem`).


```json
{
  "hata": "yontem",
  "detay": "POST bekleniyor.",
  "hata_ayrinti": {
    "kod": "yontem",
    "mesaj": "POST bekleniyor.",
    "taraf": "istemci",
    "kaynak": null,
    "tekrar_denenebilir": false,
    "tekrar_sn": null
  }
}
```

### 401 — Missing or invalid key (`yetkisiz`).


```json
{
  "hata": "yetkisiz",
  "detay": "Geçerli X-API-Key başlığı gerekli (panel › API).",
  "hata_ayrinti": {
    "kod": "yetkisiz",
    "mesaj": "Geçerli X-API-Key başlığı gerekli (panel › API).",
    "taraf": "istemci",
    "kaynak": null,
    "tekrar_denenebilir": false,
    "tekrar_sn": null
  }
}
```

### 429 — Hourly rate limit exceeded (`hiz_siniri`); the Retry-After header gives the seconds until reset.

Retry-After: `2494`

```json
{
  "hata": "hiz_siniri",
  "detay": "Saatlik istek sınırı aşıldı (600). Bir sonraki saatte tekrar deneyin.",
  "hata_ayrinti": {
    "kod": "hiz_siniri",
    "mesaj": "Saatlik istek sınırı aşıldı (600). Bir sonraki saatte tekrar deneyin.",
    "taraf": "istemci",
    "kaynak": null,
    "tekrar_denenebilir": true,
    "tekrar_sn": 2494
  }
}
```

### 500 — Unexpected error (`ic_hata`, taraf ulawk); retry shortly.

Retry-After: `60`

```json
{
  "hata": "ic_hata",
  "detay": "Beklenmeyen bir hata oluştu; kısa süre sonra yeniden deneyin.",
  "hata_ayrinti": {
    "kod": "ic_hata",
    "mesaj": "Beklenmeyen bir hata oluştu; kısa süre sonra yeniden deneyin.",
    "taraf": "ulawk",
    "kaynak": null,
    "tekrar_denenebilir": true,
    "tekrar_sn": 60
  }
}
```

## Request

```bash
curl -X POST "https://ulawk.com/api/v1/sirket-ekle/" \
  -H "X-API-Key: ulk_DENEME_ANAHTARINIZ" \
  -H "X-API-Secret: ulsk_DENEME_GIZLI_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{"mudurluk": "İSTANBUL", "sicil_no": "555555"}'
```