EzCare CRM API

Partner Integration Documentation

API Credentials

Enter your credentials to test the APIs

Current: development

Each nonce can only be used once (idempotency). UUID or claimNo+timestamp recommended.

Please fill all credentials to test API
○ API Key · ○ API Secret · ○ Encrypt Key

Base URL

https://api2.suksesmultiservis.id

Security

Inbound (Partner → EzCare CRM)

  • • API Key + Timestamp + Nonce
  • • SHA256 Signature
  • • AES/GCM/NoPadding Encryption

Outbound (EzCare CRM → Partner)

  • • X-Req-AppId / X-Req-Timestamp / X-Req-Nonce
  • • HmacSHA256 Signature

Response Codes

0000 success
5000 fail - system error
0101 fail - rule check fail
0102 fail - payment info changed
0201 fail - logic rule check fail
0202 success - acceptance rejected
0301 fail - status/data error
0302 fail - acceptance is null
0303 fail - claim is null
0304 fail - payment is null
0305 fail - acceptance is accepted
0306 fail - acceptance is rejected
0307 fail - claim is closed
0308 fail - claim is rejected
0309 fail - payment is not null

API Endpoints

Data Retrieval

Claim Submission

Claim Approval

Payment

Signature & Security Reference

Inbound Signature (Partner → EzCare CRM)

Used when Partner sends requests TO EzCare CRM API

SHA256(apiKey + timestamp + nonce + apiName + SHA256(jsonRequestBody) + apiSecret)

Step 1: bodyHash = SHA256(jsonRequestBody) — hash the encrypted Base64 body

Step 2: Concatenate: apiKey + timestamp + nonce + apiName + bodyHash + apiSecret

Step 3: signature = SHA256(concatenated string)

Parameter Table:

#
Parameter
Source
1
apiKey
Common Request Body
2
timestamp
Common Request Body
3
nonce
Common Request Body
4
apiName
Common Request Body
5
bodyHash
SHA-256 result from Step 1
6
apiSecret
Provided by EzCare CRM

Encryption / Decryption (AES/GCM/NoPadding)

Both request body and response body are encrypted

Encrypt (Request):

  1. Ensure key = 32 bytes (SHA-256 if needed)
  2. Generate random 12-byte IV
  3. Encrypt with AES-256-GCM
  4. Combine: IV(12) + ciphertext + authTag(16)
  5. Base64 encode → jsonRequestBody

Decrypt (Response):

  1. Base64 decode jsonResponseBody
  2. Extract IV (first 12 bytes)
  3. Extract ciphertext (remaining bytes)
  4. Decrypt with AES-256-GCM + key + IV

⚠️ Response body HARUS di-decrypt sebelum digunakan!

Outbound Signature (EzCare CRM → Partner Webhook)

Used to verify webhook notifications received from EzCare CRM

HmacSHA256(apiSecret, "POST\n" + path + "\n" + timestamp + "\n" + nonce + "\n" + body + "\n")

Step 1: Get timestamp & nonce from X-Req-Timestamp / X-Req-Nonce headers

Step 2: Build: toBeHashed = "POST\n" + path + "\n" + timestamp + "\n" + nonce + "\n" + jsonBody + "\n"

Step 3: signature = HmacSHA256(apiSecret, toBeHashed)

Step 4: Compare with X-Req-Signature header

Webhook Notifications

HTTP Request From EzCare CRM To Partner — Real-time claim state notifications

How It Works

When a claim state changes, EzCare CRM automatically sends an HTTP POST to your webhook URL. You must verify the X-Req-Signature header using the HmacSHA256 formula.

Supported State Changes

10 — CLAIM_CREATED
20 — SENT_TO_PARTNER
30 — LOSS_ASSESSED
40 — APPROVED
41 — REJECTED
50 — REPAIRING
60 — REPAIR_COMPLETED
70 — CUSTOMER_RECEIVED
80 — PAYMENT_PROCESSING
90 — PAID
99 — CLOSED

⚠️ State 15 (CLAIM_SENT_TO_INTERNAL) and state 95 (PAID_CHECKED) are internal states — they do NOT trigger webhooks.

Request Headers

HeaderValueDescription
Content-Typeapplication/jsonContent type
Acceptapplication/jsonExpected response type
Accept-Charsetutf-8Character encoding
X-Req-AppIdpartner's allowed_api_namesPartner identifier
X-Req-TimestampUnix timestamp (seconds)Request timestamp
X-Req-NonceRandom int 10000000-99999999Anti-replay nonce
X-Req-SignatureHmacSHA256 hex stringSignature

Webhook Payload

{
  "claim_no": "CLM_1765793845",
  "old_state": 20,
  "current_state": 40,
  "state_name": "APPROVED",
  "timestamp": "2024-12-16T11:35:00Z",
  "state_history": {
    "from_state": 20,
    "to_state": 40,
    "api_name": "approve",
    "changed_by": "PARTNER_NAME",
    "info": "Claim Approval:\nAction=APPROVED\nApprovedAt=2024-12-16 11:35:00",
    "created_at": "2024-12-16T11:35:00Z"
  }
}

Signature Verification

Formula: HmacSHA256(apiSecret, "POST " + path + " " + timestamp + " " + nonce + " " + body + " ")

⚠️ Each parameter is separated by a newline (\n) and the string ends with a newline.

🐍 Python — Verify Signature
import hmac, hashlib

# From webhook headers
timestamp = request.headers["X-Req-Timestamp"]
nonce = request.headers["X-Req-Nonce"]
signature = request.headers["X-Req-Signature"]

# Build toBeHashed
path = "/webhook/ezcarecrm"  # your endpoint path
body = request.body  # raw JSON string
to_be_hashed = f"POST\n{path}\n{timestamp}\n{nonce}\n{body}\n"

# Calculate expected signature
expected = hmac.new(
    api_secret.encode(),
    to_be_hashed.encode(),
    hashlib.sha256
).hexdigest()

# Verify
assert signature == expected, "Invalid signature!"
☕ Java — Verify Signature
String toBeHashed = String.format("%s\n%s\n%d\n%s\n%s\n",
    "POST", path, timestamp, nonce, jsonRequestBody);

Mac mac = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKey = new SecretKeySpec(
    apiSecret.getBytes(), "HmacSHA256");
mac.init(secretKey);
byte[] hash = mac.doFinal(toBeHashed.getBytes());
String signature = Hex.encodeHexString(hash);
Your Webhook Response

Return HTTP 200, 201, or 202 withContent-Type: application/json. Timeout: 10 seconds.