---
title: "Testing and Development with the iletiMerkezi API"
description: "iletiMerkezi has no separate sandbox API — safe testing patterns with the production key: side-effect-free endpoints, sending TEST-prefixed messages to your own number, verification flow."
slug: /en/docs/api/test-mode
locale: en
audience: developer
last_updated: 2026-04-29
auth: api-key-and-hash
related: [authentication, get-balance, send-sms]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/test-mode
  en: https://www.iletimerkezi.com/en/docs/api/test-mode
---

# Testing and Development with the iletiMerkezi API

iletiMerkezi does **not** offer a separate sandbox / test API. The same key works for both production and development; "test mode" is a discipline, not an endpoint flag. This page collects practical rules for trying the API without sending real SMS or burning credits unintentionally.

## Side-effect-free endpoints — start here

These endpoints consume no credits, send no SMS, and don't change state even on error. Perfect for verification, automation, and CI:

- [`get-balance`](./get-balance.md) — Verify auth + read balance
- [`get-sender`](./get-sender.md) — Approved sender ID list
- [`get-blacklist`](./get-blacklist.md) — Blacklist query
- [`get-report`](./get-report.md) — Past order report (sends no new SMS)
- [`get-inbox`](./inbox.md) — Inbound messages list

The first integration step is usually `get-balance`:

```bash
curl -X POST 'https://api.iletimerkezi.com/v1/get-balance/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "API_KEY",
        "hash": "API_HASH"
      }
    }
  }'
```

If you get a `200 İşlem başarılı` response, your credentials, the panel toggle, and the request shape are all correct. You're ready to call other endpoints.

## Real-SMS test patterns

When you want to exercise `send-sms`, every successful call **delivers a real SMS and consumes credits**. Test safely:

### 1. Send to your own mobile number

Test messages should only go to numbers you (or your dev team) control. Wrong recipients = spam and brand risk.

### 2. Prefix the body with "TEST"

The recipient (yourself) should be able to tell test messages from production messages. Standard pattern:

```
TEST send-sms integration verify, 2026-04-29 14:35
```

### 3. Cap message length

iletiMerkezi's real character limits are slightly lower than the standard SMS values because of the B186 operator code: English **155**, Turkish **150**, Unicode **65** characters (first part). Keep test bodies **under 140 characters** and avoid Turkish characters when possible — no surprise multi-part splits, no surprise credit multiplier. Full table: [overview](./overview.md).

### 4. Log balance before and after

```javascript
const before = await client.account().balance();
await client.sms().send(myNumber, 'TEST message');
const after = await client.account().balance();
console.log('Credits consumed:', before.getCredits() - after.getCredits());
```

The `send-sms` `200` debits credits the moment the order is queued (it does not wait for delivery confirmation).

### 5. Use `iys: "0"` (transactional)

Test messages aren't commercial. `iys: "0"` exempts them from the IYS commercial-consent check. Details in [send-sms](./send-sms.md).

## CI / automation approach

In a CI environment, **avoid calling `send-sms`**. Instead:

- Auth + connectivity check: `get-balance` (no credits used)
- Body schema check: mock your HTTP client and assert the JSON your code produces matches the expected shape in unit tests
- Separate test account for dev: rather than your production account, open a dedicated iletiMerkezi account for the team and put its key in your CI secret store. The test budget is then isolated from production.

## Idempotency and duplicate guard

If you re-send the same `sender + recipient + text` combination within a short window, the API returns `451 — Tekrar eden sipariş` ("Duplicate order"; verified in live testing on 2026-04-29). Append a unique nonce (timestamp, UUID) to the body in your test loop:

```
TEST send-sms 2026-04-29T14:35:42Z
```

## Use `APITEST` sender to test before sender ID approval

Turkish telecom regulation requires an approved sender ID (header) before any SMS can be sent, and approval takes 1–2 business days. To let you start integrating without waiting, iletiMerkezi accepts a special sender value: **`APITEST`**.

When you call `send-sms` with `order.sender` set to `"APITEST"`:

- **The HTTP flow works end-to-end:** the request is accepted, returns `200` + an `orderId`.
- **`get-report`, webhooks, `get-balance` all behave normally:** the order is recorded, credit is consumed (even though no real SMS is delivered to a recipient with your text).
- **But the message body is replaced.** The recipient always receives the following fixed Turkish text; the `text` you submitted is ignored:

  > Bu bir deneme mesajıdır. SMS gonderim hizmetimizi test ettiginiz icin tesekkur ederiz. Detayli bilgiye www.iletimerkezi.com adresinden ulasabilirsiniz.

(Translation: "This is a test message. Thanks for trying our SMS service. For more information visit www.iletimerkezi.com.")

**When to use `APITEST`:**

- Test the end-to-end HTTP integration while your real sender ID is still in review
- Verify your SDK or HTTP client builds the correct request/response shapes
- Wire up and test your webhook handler against real `accepted` / `delivered` callbacks
- Confirm `get-report` and `get-balance` work against a real `orderId`

**When not to use it:**

- Verifying message body rendering (the body is replaced — re-test once your sender is approved)
- Any production traffic (switch to your approved sender once available)
- Character-limit or multi-part testing (the fixed body is always the same length)

## Test credentials

iletiMerkezi does not publish a shared test key. Each team opens its own account in the panel; **new accounts receive 100 free SMS credits** for testing and evaluation, which is enough to walk through the first integration without extra cost. Store the key in a secret manager (Vault, AWS Secrets, GitHub Actions secrets, etc.).

**Never** commit your API key to a repository, public file, blog post, or screenshot — the key grants full account access; a single API call can drain the entire balance.

## Common pitfalls

- **There is no sandbox.** "Test mode" isn't a flag; it's a discipline you enforce.
- **Don't run CI against your production account.** A single bad script can burn the entire balance; a separate test account is the standard pattern.
- **Don't call `send-sms` from CI.** Mock + unit-test is faster, safer, and cheaper.
- **Wrong recipient = real damage.** A typo, a bad regex, or a stale local record can send an unwanted message to a real user during testing. Use a hard-coded recipient whitelist in test paths.

## Related

- [Authentication](./authentication.md)
- [Get balance](./get-balance.md)
- [Send SMS (send-sms)](./send-sms.md)
- [Error code table](./error-codes.md)