# MikroJB-API Login Entegrasyon ve Kullanım Dokümanı

Bu doküman, **MikroAPI (Genel)** servisleri üzerinden `APILogin` / `MikroApiUp` kimlik doğrulama isteklerinde **HTTP 200 OK** yanıtı alabilmeniz için gerekli teknik analizleri, istek yapısını, zorunlu parametreleri ve kontrol noktalarını içermektedir. Örnek POSTMAN Collection'a Anasayfa üzerinde bulunan ekstra kaynaklar bölümünden erişilebilir.

## 1. İstek Mimarisi ve Analizi

MikroAPI login mimarisi, hem **HTTP Header (Bearer Token)** seviyesinde hem de **JSON Request Body** seviyesinde çift katmanlı bir doğrulama yapısı kullanır.

### Endpoint Detayları

* **HTTP Metodu:** `POST`
* **URL Yapısı:** `{{ApiLinkV16Gateway}}/ApiMethods/{{LoginAlias}}/APILogin`
  * `ApiLinkV16Gateway`: MikroAPI servisinin çalıştığı gateway adresi (örn. `https://jumpbulutapigw.mikro.com.tr/ApiJB/ApiMethods`).
  * `LoginAlias`: Firma/API için tanımlanmış servis takma adı (MIKRO-1234).


## 2. HTTP Header Gereksinimleri

Başarılı bir oturum açma isteği için aşağıdaki HTTP başlıklarının gönderilmesi şarttır:

| Header | Değer / Format | Açıklama |
|  --- | --- | --- |
| `Content-Type` | `application/json` | Gönderilen verinin JSON formatında olduğunu belirtir. |
| `Authorization` | `Bearer {{KeyToken}}` | MikroAPI Gateway seviyesinde yetkilendirme sağlayan Bearer Token. |
| `User-Agent` | `MkRo4486JB76043` | Request'in MikroAPI istemcisi üzerinden gönderildiğini belirtir. Tüm requestlerde bu değer kullanılmalıdır. |


> **Önemli:** `KeyToken` değeri geçersiz, süresi dolmuş veya hatalı olduğunda API gateway seviyesinde `401 Unauthorized` veya `403 Forbidden` hatası alınır.


## 3. İstek Gövdesi (Request Body)

İstek gövdesi `application/json` formatında olmalı ve Mikro v16 veritabanı/oturum parametrelerini içermelidir.

### JSON Şablonu

```json
{
  "Alias": "{{LoginAlias}}",
  "FirmaKodu": "{{LoginFirmaKodu}}",
  "CalismaYili": "{{LoginCalismaYili}}",
  "ApiKey": "{{LoginApiKey}}",
  "KullaniciKodu": "{{LoginKullaniciKoduSRV}}",
  "Sifre": "{{LoginSifreSRV}}",
  "FirmaNo": "{{LoginFirmaNo}}",
  "SubeNo": "{{LoginSubeNo}}"
}
```

### Parametre Açıklamaları ve Veri Tipleri

| Parametre | Tipi | Örnek Değer | Zorunlu mu? | Açıklama |
|  --- | --- | --- | --- | --- |
| `Alias` | `String` | `"DEMO_ALIAS"` | **Evet** | URL path ile eşleşmesi gereken firma alias adı. |
| `FirmaKodu` | `String` | `"MIKRO_DEMO"` | **Evet** | Mikro v16 veritabanı firma kodu. |
| `CalismaYili` | `String/Int` | `"2026"` | **Evet** | İşlem yapılacak aktif çalışma yılı. |
| `ApiKey` | `String` | `"abc123xyz..."` | **Evet** | MikroAPI entegrasyonu için tanımlanmış API anahtarı. |
| `KullaniciKodu` | `String` | `"SRV"` veya `"1"` | **Evet** | Mikro v16 yetkili kullanıcı kodu. |
| `Sifre` | `String` | `"MD5_HASH--GUNUNTARIHI_VE_PAROLA"` | **Evet** | Kullanıcı şifresi (Mikro yapılandırmasına göre MD5 hash). |
| `FirmaNo` | `Integer` | `0` | **Evet** | Çalışılacak firma sıra numarası (Varsayılan: `0`). |
| `SubeNo` | `Integer` | `0` | **Evet** | Çalışılacak şube sıra numarası (Varsayılan: `0`). |


## 4. HTTP 200 OK Almak İçin Adım Adım Kontrol Listesi

1. **Gateway URL & Alias Kontrolü:**
  * `{{ApiLinkV16Gateway}}` adresinin erişilebilir ve aktif olduğundan emin olun.
  * Path içerisindeki `{{LoginAlias}}` ile body içerisindeki `"Alias"` alanının birebir aynı string değerini taşıdığını doğrulayın.


image copy.png
1. **Bearer Token Doğrulaması:**
  * Header alanına `Authorization: Bearer <KeyToken>` parametresinin eksiksiz eklendiğinden emin olun.


image.png
1. **TOKEN Endpointi.**
  * Body alanında bulunan Username ve Password alanına Mikro IDM kullanıcı bilgileri ile giriş yapılarak Send Edilir ve Token üretilir.


image copy 2.png
1. **User-Agent Header Key eklentisi**
  * Gelen istekler için Headers'da User-Agent Eklenmelidir.
  * Key : **User-Agent**
  * Value : **MkRo4486JB76043**


image copy 3.png
1. **Mikro Veritabanı ve Kullanıcı Yetkileri:**
  * `FirmaKodu` ve `CalismaYili` Mikro ERP sisteminde tanımlı ve erişilebilir durumda olmalıdır.
  * `KullaniciKodu` servise erişim yetkisine sahip aktif bir SRV veya sistem kullanıcısı olmalıdır.
  * `Sifre` alanı MikroAPI'nin beklediği formatta (MD5 hash- Gününtarihi Boşluk Şifre - örn. `0496d62c59cccbb4894dadf4fdebc5e8` gibi MD5 değeri) doğru iletilmelidir.
2. **Karakter ve Format Kontrolü:**
  * Body verisinin geçerli bir JSON objesi olduğundan, kaçış karakterlerinin (`\r\n`) veya tırnak hatalarının JSON yapısını bozmadığından emin olun.


## 5. Örnek Kod Kullanımları

### cURL

```bash
curl --location --request POST 'https://jumpbulutapigw.mikro.com.tr/ApiJB/ApiMethods/DEMO_ALIAS/APILogin' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_KEY_TOKEN_HERE' \
--header 'User-Agent: MkRo4486JB76043' \
--data-raw '{
  "Alias": "DEMO_ALIAS",
  "FirmaKodu": "DEMO_FIRMA",
  "CalismaYili": "2026",
  "ApiKey": "YOUR_API_KEY",
  "KullaniciKodu": "1",
  "Sifre": "0496d62c59cccbb4894dadf4fdebc5e8",
  "FirmaNo": "0",
  "SubeNo": "0"
}'
```

### Python (`requests`)

```python
import requests
import json

url = "https://jumpbulutapigw.mikro.com.tr/ApiJB/ApiMethods/DEMO_ALIAS/APILogin"

payload = json.dumps({
    "Alias": "DEMO_ALIAS",
    "FirmaKodu": "DEMO_FIRMA",
    "CalismaYili": "2026",
    "ApiKey": "YOUR_API_KEY",
    "KullaniciKodu": "1",
    "Sifre": "0496d62c59cccbb4894dadf4fdebc5e8",
    "FirmaNo": 0,
    "SubeNo": 0
})

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_KEY_TOKEN_HERE'
    'User-Agent: MkRo4486JB76043'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.status_code)
print(response.text)
```

## 6. Olası Hata Durumları ve Çözümleri

| HTTP Kodu / Durum | Olası Neden | Çözüm |
|  --- | --- | --- |
| **401 Unauthorized** | Bearer Token (`KeyToken`) eksik veya geçersiz. | Header alanındaki Bearer Token bilgisini yenileyin. |
| **404 Not Found** | URL üzerindeki `LoginAlias` veya Endpoint adı hatalı. | URL yolunu ve Alias parametresini kontrol edin. |
| **400 Bad Request** | Request Body JSON formatı bozuk veya eksik alan var. | Gönderilen JSON verisini doğrulayın. |
| **500 Internal Error** | Firma Kodu, Çalışma Yılı, Kullanıcı Kodu/Şifre veya DB bağlantısı hatalı. | Mikro ERP veritabanı servislerinin çalışırlığını ve kullanıcı kimlik bilgilerini doğrulayın. |