Get Symmetric Key (T104)

Retrieve the AES symmetric key and signature value used to encrypt/decrypt all subsequent API communications. This endpoint is called after successful sign-in (T103) and enables secure online mode operations.

---

Endpoint Overview

Property	Value
Interface Code	T104
Request Encrypted	❌ No
Response Encrypted	❌ No
Request Body	null
Response Format	JSON

---

Flow Description

1. Client calls this endpoint immediately after successful T103: Sign In.
2. Server generates a random 8-character symmetric key (passowrdDes) and signature value (sign).
3. Client stores these values in KeyClient for encrypting/decrypting future requests.
4. All subsequent API calls (T106+) use this symmetric key for payload encryption.

🔐 Security Note: The symmetric key is session-specific. Re-authenticate (T103) to obtain a fresh key if the session expires or keys are compromised.

---

PHP

try {
    // Call T104: Get Symmetric Key
    $response = $client->getSymmetricKey();
    
    $content = $response['data']['content'] ?? $response;
    
    if (isset($content['passowrdDes'], $content['sign'])) {
        echo "✅ Symmetric key retrieved\n";
        
        // Store credentials in KeyClient for subsequent encryption
        $keyClient->setAesKey($content['passowrdDes']);
        $keyClient->setSignature($content['sign']);
        
        echo "   Key: " . substr($content['passowrdDes'], 0, 4) . "****\n";
        echo "   Sign: " . substr($content['sign'], 0, 6) . "...\n";
    } else {
        echo "⚠️  Missing symmetric key or signature in response\n";
    }
} catch (\UraEfrisSdk\Exceptions\APIException $e) {
    echo "❌ API Error: " . $e->getMessage() . "\n";
    echo "   Return Code: " . $e->getReturnCode() . "\n";
}

JavaScript / TypeScript

try {
    // Call T104: Get Symmetric Key
    const response = await client.getSymmetricKey();
    
    const content = response?.data?.content ?? response;
    
    if (content?.passowrdDes && content?.sign) {
        console.log('✅ Symmetric key retrieved');
        
        // Store credentials in KeyClient for subsequent encryption
        keyClient.setAesKey(content.passowrdDes);
        keyClient.setSignature(content.sign);
        
        console.log(`   Key: ${content.passowrdDes.substring(0, 4)}****`);
        console.log(`   Sign: ${content.sign.substring(0, 6)}...`);
        
        return content;
    } else {
        console.warn('⚠️  Missing symmetric key or signature in response');
        return null;
    }
} catch (error: any) {
    console.error(`❌ API Error: ${error.message}`);
    if (error.returnCode) {
        console.error(`   Return Code: ${error.returnCode}`);
    }
    throw error;
}

Python

try:
    # Call T104: Get Symmetric Key
    response = client.get_symmetric_key()
    
    content = response.get("data", {}).get("content", response)
    
    if content.get("passowrdDes") and content.get("sign"):
        print("✅ Symmetric key retrieved")
        
        # Store credentials in KeyClient for subsequent encryption
        key_client.set_aes_key(content["passowrdDes"])
        key_client.set_signature(content["sign"])
        
        print(f"   Key: {content['passowrdDes'][:4]}****")
        print(f"   Sign: {content['sign'][:6]}...")
        
        return content
    else:
        print("⚠️  Missing symmetric key or signature in response")
        return None
except Exception as e:
    print(f"❌ API Error: {e}")
    if hasattr(e, "return_code"):
        print(f"   Return Code: {e.return_code}")
    raise

---

Response Structure

{
  "data": {
    "content": {
      "passowrdDes": "aB3xK9mP",
      "sign": "7F2e9A1c"
    }
  },
  "globalInfo": {
    "interfaceCode": "T104",
    "returnStateInfo": {
      "returnCode": "00",
      "returnMessage": "SUCCESS"
    }
  }
}

Response Fields

Field	Required	Type	Description
passowrdDes	✅ Yes	String (8 chars)	AES symmetric key for encrypting/decrypting all post-login data payloads
sign	✅ Yes	String	Signature value used to verify message integrity for encrypted requests

⚠️ Note: Field name is passowrdDes (with typo) as per EFRIS API specification. Do not correct to passwordDes.

---

Return Codes

Code	Message	Description
00	SUCCESS	Symmetric key and signature generated successfully
99	Unknown error	Generic server error
06	The outer message is empty	Malformed request envelope
07	GlobalInfo content cannot be empty	Missing required globalInfo
11	InterfaceCode cannot be empty	Missing interfaceCode in request
400	Device does not exist	deviceNo not registered for this TIN
402	Device key expired	Device credentials have expired; re-run T102
403	Device status is abnormal	Device blocked or suspended

💡 Tip: This endpoint must be called after T103 (Sign In) and before any encrypted endpoint (T106+). The SDK handles this automatically if you call endpoints in order.

---

Common Use Cases

1. Session Encryption Setup
   Establish AES encryption context after authentication to secure invoice uploads, stock queries, and other sensitive operations.

2. Key Rotation Handling
   Re-fetch symmetric key when receiving 402 (key expired) or after session timeout to maintain secure communication.

3. Offline-to-Online Transition
   When switching from offline mode (T109 with modeCode: 0) to online mode, retrieve fresh symmetric key for server-synced operations.

4. Multi-Session Management
   Maintain separate KeyClient instances with distinct symmetric keys for concurrent sessions (e.g., multi-tenant applications).

---

Integration Checklist

✅ Call sequence: T101 → T102 → T103 → T104 → [encrypted endpoints]
✅ Store passowrdDes and sign in secure memory (not logs or disk)
✅ Use SDK's KeyClient to handle encryption automatically—do not manually encrypt payloads
✅ Re-authenticate (T103) if symmetric key operations fail with 402 or 403