Ana içeriğe geç

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:

The first integration step is usually get-balance:

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.

4. Log balance before and after

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.

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.

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

Last updated: 2026-04-29 · Türkçe