          
          REST · HTTPS · JSON
        

Astana API
Reference

Integrasikan sistem POS, inventori, resit dan pembayaran Astana ke dalam aplikasi anda. Dokumentasi lengkap untuk endpoint, authorization dan webhooks.

v1.0

Versi semasa

300/300s

Had kadar

24+

Kumpulan endpoint

Menggunakan REST API

Astana API mengikut corak REST am menggunakan sambungan HTTPS. Untuk mula menguji dengan Postman, ikut langkah berikut.

1Install dan download Postman.
2Import Astana API Postman Collection ke dalam Postman.
3Tetapkan baseUrl dan Token dalam Postman environment.

🔑

Dapatkan access token dari Astana Backoffice → Access token di bawah Integrations. Simpan token dengan selamat dan jangan kongsi secara terbuka.

postman.environment

baseUrl  = https://api.astanabiz.com/v1.0
Token    = Bearer YOUR_ACCESS_TOKEN

Versioning

Versi mesti dinyatakan dalam base URL. Dokumentasi ini untuk versi 1.0.

          https://api.astanabiz.com/v1.0
        

Authorization

Astana API menyediakan dua kaedah authorization.

3.1

Personal Access Tokens

Sesuai untuk skrip berkala yang berinteraksi dengan data dalam akaun sendiri.

3.2

OAuth 2.0

Aliran authorization penuh dengan App ID, App secret dan refresh token.

Header setiap panggilan API

Authorization header

Token : Bearer YOUR_ACCESS_TOKEN

OAuth 2.0 — minta access token

Guna Authorization Code untuk minta token. Payload menghantar parameter berikut.

ParameterKeterangan

200 · response.json

{
  "access_token": "d6a4a1ce…37d8ca4e",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "OptNZG",
  "refresh_token": "b54f8bc7…5d94050b"
}

↻ Refresh token: POST ke /oauth/token dengan client_id, client_secret, refresh_token dan grant_type=refresh_token.

Pagination

Sesetengah endpoint memaparkan hasil secara pagination. Response mengandungi field cursor. Hantar semula nilai cursor sebagai query parameter untuk set seterusnya. Bila field cursor tiada, itu set terakhir.

limit default

10

limit maksimum

250

API Rate Limits

Had semasa ialah 300 requests setiap 300 saat untuk setiap akaun.

429 Request melebihi had akan menerima HTTP 429 Too Many Requests.

Format Tarikh & Masa

Semua tarikh dan masa menggunakan format 24 jam (Y-m-d H:i:s). Tukar ke waktu tempatan anda semasa diproses.

Handling Errors

API memulangkan Error List untuk request yang gagal.

error.json

{
  "errors": {
    "code": "UNAUTHORIZED",
    "details": "Access token is not valid."
  }
}

Kod RalatKeterangan

401 UNAUTHORIZED Ralat pengesahan. Data authorization tiada, salah format atau tidak sah.

Webhooks Overview

Notifikasi masa nyata untuk event sistem Astana disampaikan melalui webhooks — Astana menghantar HTTP POST ke URL yang dikonfigurasi setiap kali event dicetuskan.

Event yang disokong

Konfigurasi & kebolehpercayaan

▸Konfigur guna endpoint /webhook atau web interface.
▸Satu langganan = satu jenis event. Pasangan event + URL mesti unik.
▸Endpoint mesti pulangkan HTTP 2xx. Redirect dianggap ralat.
▸Cuba semula sehingga 200 kali dalam 48 jam; jika gagal, status → Disabled.

inventory_levels.update payload

{
  "merchant_id": "WFpYWmQwMkJ…",
  "type": "inventory_levels.update",
  "created_at": "2025-06-30 12:54:31",
  "inventory_levels": [{
    "product_id": "QWhxek54UkQ…",
    "shop_id": "bHF2M2pMakk…",
    "product_code": "10003",
    "in_stock": 10
  }]
}

Rujukan

Astana APIReference