---
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)

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`**.

> **Access rule.** `APITEST` is available **only while the account has no approved sender ID** (a new account or one waiting on approval). The moment your sender ID is approved, `APITEST` is automatically disabled; from that point on, calling `send-sms` with `sender: "APITEST"` returns `450: sender not allowed`. Use your approved sender ID instead; the approved list can be fetched via [`get-sender`](./get-sender.md).

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)