# SimpleSMS REST API – Integrációs dokumentáció AI fejlesztői ágensek számára

> Forrás: a SimpleSMS Postman Collection (`simpleSMS.postman_collection.json`).
>
> **Fontos:** ez a dokumentáció kizárólag a megadott Postman collectionből biztosan megállapítható információkra épül. A collection nem tartalmaz minta response-okat, ezért a válaszok pontos JSON-struktúráját, státuszkódjait és hibakódjait nem szabad feltételezni.

## 1. Áttekintés

A SimpleSMS REST API alap URL-je:

```text
https://api.simplesms.hu/rest/SMSapi
```

A collectionben szereplő végpontok:

| Funkció | Metódus | Endpoint |
|---|---|---|
| Bejelentkezés / token lekérése | POST | `/connect` |
| SMS küldése | POST | `/sendSMS` |
| SMS előzmények lekérése | POST | `/getHistory` |
| SMS státusz lekérése | POST* | lásd az eltérést lent |
| Egyenleg / kreditszám lekérése | GET | `/getCreditNumber` |
| Havi statisztika | GET | `/getMonthlyStat` |

A Postman collection gyökérszintű autentikációja Bearer token. A `connect` végpont külön `noauth` beállítású, tehát a hitelesítés megszerzésére szolgál.

## 2. Autentikáció

### POST `/connect`

Teljes URL:

```text
https://api.simplesms.hu/rest/SMSapi/connect
```

Autentikáció:

```text
nincs
```

Request body típusa:

```text
multipart/form-data
```

Paraméterek:

| Paraméter | Kötelezőség | Leírás |
|---|---|---|
| `username` | a collection alapján szükséges | SimpleSMS portálon megadott felhasználónév |
| `password` | a collection alapján szükséges | SimpleSMS portálon megadott jelszó |
| `domain` | a collection alapján szükséges | SimpleSMS portálon megadott domain |

Példa:

```bash
curl -X POST \
  'https://api.simplesms.hu/rest/SMSapi/connect' \
  -F 'username=FELHASZNALONEV' \
  -F 'password=JELSZO' \
  -F 'domain=HOST'
```

### Token használata

A collection globális autentikációja:

```http
Authorization: Bearer <TOKEN>
```

A `connect` kivételével a collection elemei öröklik ezt a Bearer autentikációt.

**AI implementációs szabály:** a `connect` válaszából ki kell nyerni az API által visszaadott tokent, majd azt kell használni a további kérésekhez. A Postman collection nem tartalmaz válaszmintát, ezért a token pontos JSON mezőnevét nem szabad kitalálni. Az implementációban ezt konfigurálhatóvá kell tenni vagy valós API-válasz alapján kell meghatározni.

## 3. SMS küldése

### POST `/sendSMS`

Teljes URL:

```text
https://api.simplesms.hu/rest/SMSapi/sendSMS
```

Autentikáció:

```http
Authorization: Bearer <TOKEN>
```

Request body:

```text
multipart/form-data
```

Aktív paraméterek a collectionben:

| Paraméter | Példa | Leírás |
|---|---|---|
| `message` | `Teszt8` | SMS üzenet tartalma |
| `phone_number` | `36303539369` | teljes telefonszám |

A collectionben megtalálható, de **disabled** mezők:

| Paraméter | Példa | Leírás |
|---|---|---|
| `country_code` | `36` | országhívó kód |
| `area_code` | `30` | szolgáltatói körzetszám |
| `number` | `3539369` | telefonszám további része |

A jelenlegi collection tehát a `phone_number` használatát mutatja aktív megoldásként.

Példa:

```bash
curl -X POST \
  'https://api.simplesms.hu/rest/SMSapi/sendSMS' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'phone_number=36303539369' \
  -F 'message=Teszt uzenet'
```

A `phone_number` mintája alapján a telefonszám országkóddal, `+` jel nélkül szerepel. Ezt a collection példája mutatja; általános validációs szabály nincs dokumentálva.

A collection megjegyzése szerint SMS küldéskor a response tartalmaz egy `sms_id` értéket, amelyet későbbi lekérdezésekhez lehet használni. A response pontos struktúrája nincs dokumentálva.

## 4. SMS előzmények lekérése

### POST `/getHistory`

Teljes URL:

```text
https://api.simplesms.hu/rest/SMSapi/getHistory
```

Autentikáció:

```http
Authorization: Bearer <TOKEN>
```

Body:

```text
multipart/form-data
```

Paraméter:

| Paraméter | Leírás |
|---|---|
| `sms_id` | SMS küldéskor kapott SMS azonosító |

Példa:

```bash
curl -X POST \
  'https://api.simplesms.hu/rest/SMSapi/getHistory' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'sms_id=SMS_ID'
```

## 5. SMS státusz – FONTOS COLLECTION ELTÉRÉS

A collection tartalmaz egy `getStatus` nevű requestet, amelynek body-ja:

```text
sms_id
```

Viszont a request URL-je nem `getStatus`, hanem:

```text
https://api.simplesms.hu/rest/SMSapi/getMonthlyStat
```

Ez nagy valószínűséggel collection-konfigurációs eltérés vagy elnevezési hiba, de a rendelkezésre álló fájl alapján **nem állapítható meg biztosan**, hogy a helyes státusz endpoint:

```text
/getStatus
```

vagy más URL.

**AI fejlesztői utasítás:** ezt az endpointot ne implementáld feltételezés alapján produkciós kódban. A helyes URL-t ellenőrizni kell a SimpleSMS API-n vagy a szolgáltatónál. A collection alapján csak az biztos, hogy a `getStatus` nevű request `sms_id` form-data paramétert küld.

## 6. Egyenleg / kreditszám

### GET `/getCreditNumber`

Teljes URL:

```text
https://api.simplesms.hu/rest/SMSapi/getCreditNumber
```

Autentikáció:

```http
Authorization: Bearer <TOKEN>
```

Body nincs.

Példa:

```bash
curl \
  'https://api.simplesms.hu/rest/SMSapi/getCreditNumber' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

A válasz pontos struktúrája nincs dokumentálva.

## 7. Havi statisztika

### GET `/getMonthlyStat`

Teljes URL:

```text
https://api.simplesms.hu/rest/SMSapi/getMonthlyStat
```

Autentikáció:

```http
Authorization: Bearer <TOKEN>
```

Body nincs.

Példa:

```bash
curl \
  'https://api.simplesms.hu/rest/SMSapi/getMonthlyStat' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

A collection nem dokumentál query paramétereket vagy dátumtartományt.

## 8. Javasolt integrációs folyamat

```text
1. POST /connect
      |
      v
2. Token kinyerése
      |
      v
3. Authorization: Bearer TOKEN
      |
      +--> POST /sendSMS
      |       |
      |       +--> sms_id eltárolása
      |
      +--> POST /getHistory
      |
      +--> GET /getCreditNumber
      |
      +--> GET /getMonthlyStat
```

A státuszlekérdezést csak a helyes endpoint ellenőrzése után kell hozzáadni.

## 9. AI coding agent instrukció

Ha ebből a dokumentációból SimpleSMS klienst készítesz:

1. Hozz létre külön `SimpleSMSClient` / szolgáltatás osztályt.
2. A base URL legyen konfigurálható, alapértelmezése:
   `https://api.simplesms.hu/rest/SMSapi`
3. A `username`, `password` és `domain` ne legyen hardcode-olva.
4. A hitelesítő adatokat environment variable-ből vagy secret store-ból olvasd.
5. A jelszót és Bearer tokent soha ne logold.
6. A `/connect` kérést Bearer token nélkül küldd.
7. A többi dokumentált endpointnál Bearer tokent használj.
8. A POST body-kat a collectionnek megfelelően `multipart/form-data` formában küldd.
9. A telefonszámot stringként kezeld, ne integerként.
10. Az SMS azonosítót (`sms_id`) stringként kezeld, amíg az API tényleges típusa nem ismert.
11. Ne feltételezd a response JSON mezőneveit, mert a collection nem tartalmaz response példákat.
12. Ne találj ki hibakódokat vagy státuszértékeket.
13. HTTP/network hibákat kezeld külön az API által visszaadott üzleti hibáktól.
14. Állíts be ésszerű connection és request timeoutot.
15. Automatikus retry-t SMS-küldésnél csak idempotencia-védelem mellett használj, különben ugyanaz az SMS többször is kiküldhető.
16. A `getStatus` endpoint URL-jét implementáció előtt ellenőrizd.
17. A kódot úgy strukturáld, hogy az API válaszformátuma később könnyen pontosítható legyen.

### Ajánlott publikus interfész

```text
connect(username, password, domain)
sendSMS(phoneNumber, message)
getHistory(smsId)
getCreditNumber()
getMonthlyStat()
```

`getStatus(smsId)` csak az endpoint ellenőrzése után kerüljön a stabil interfészbe.

## 10. Biztonság

Soha ne kerüljön repositoryba:

```text
SimpleSMS username
SimpleSMS password
SimpleSMS domain/host, ha érzékeny ügyféladat
Bearer token
```

Példa `.env`:

```dotenv
SIMPLESMS_BASE_URL=https://api.simplesms.hu/rest/SMSapi
SIMPLESMS_USERNAME=
SIMPLESMS_PASSWORD=
SIMPLESMS_DOMAIN=
```

A `.env` fájlt ne commitold.

## 11. Ami NINCS dokumentálva a Postman collectionben

Az integráció során nem szabad feltételezni:

- response JSON struktúrák;
- token mezőneve és élettartama;
- HTTP státuszkódok jelentése;
- API-specifikus hibakódok;
- rate limit;
- timeout követelmények;
- maximális SMS hossz;
- GSM-7 / Unicode kezelés;
- SMS szegmensek számlázási szabályai;
- telefonszám-validáció teljes szabályrendszere;
- bulk/tömeges küldés támogatása;
- callback/webhook támogatás;
- `getStatus` tényleges URL-je;
- token megújításának módja.

Ezeket valós API-válaszokkal vagy további hivatalos dokumentációval kell pontosítani.

## 12. Rövid referencia

```text
BASE URL
https://api.simplesms.hu/rest/SMSapi

AUTH
POST /connect
form-data:
  username
  password
  domain

SEND SMS
POST /sendSMS
Bearer token
form-data:
  phone_number
  message

HISTORY
POST /getHistory
Bearer token
form-data:
  sms_id

CREDIT
GET /getCreditNumber
Bearer token

MONTHLY STAT
GET /getMonthlyStat
Bearer token

STATUS
A collectionben ellentmondásos; ellenőrzés szükséges.
```