استخراج رمز QR للربط

Deciphering the Protocol: The Raw QR Payload Guide

The /v2/auth/qr endpoint is the specialized "Engine Access" tool for developers who require surgical control over the authentication process. Unlike the image-based endpoint, which is optimized for quick rendering, this route provides the raw, Base64-encoded protocol string. This is essential for building custom QR generators, CLI-based tools, or native mobile implementations where binary data is preferred over a static image.

🏗️ Technical Breakdown: The JSON Envelope

The response from this endpoint is a JSON object containing two primary components:

1. mimetype: Typically application/json, indicating that the payload is a structured data object.
2. data: A Base64-encoded string. Once decoded, this string yields a JSON object containing the Protocol Signature required by the WhatsApp WebSocket.

The Decoded Payload Structure

When you decode the data field, you will find:

• value: The actual alphanumeric string that needs to be encoded into a QR pattern.
• expiry: A Unix timestamp representing the exact millisecond when this specific QR code will be invalidated by the WhatsApp servers.

🛡️ Strategic Best Practices

1. Implementing a CLI-Based ASCII Renderer

If you are building a headless tool (like a VPS manager or a terminal-based bot), fetching the raw QR string allows you to render the code directly in the terminal using ASCII characters.

• Developer Action: Use a library like qrcode-terminal in Node.js or qrcode in Python. Pass the value from the decoded response to the library to display the scanable pattern directly to your server administrators.

2. Synchronization and Rate Limiting

Fetching the raw QR is a relatively resource-intensive task for the underlying engine as it involves a real-time probe of the browser state.

• The Polling Window: We recommend a polling interval of 5-7 seconds. Polling faster than this will not yield a "fresher" code (as WhatsApp only rotates codes every 20-30 seconds) and may lead to 429 Rate Limit responses from our infrastructure.

3. Handling the Recovery Window (422 Status)

If the engine is busy resetting its internal WhatsApp bridge, you will receive a 422 Session Status Not Expected error.

• The Fix: This is not a failure; it’s a "Please Wait" signal. Your application should implement an exponential backoff. Wait 10 seconds, then 20 seconds, before attempting to fetch the QR again. This gives the engine time to finalize its background handshake.

💡 Industry-Standard Use Cases

A. Deep-Link Mobile Integration

If you are building a native iOS or Android app, you can fetch the raw QR string and use the mobile OS's native QR generation libraries (like CoreImage on iOS). This results in a much sharper, high-contrast QR code that is easier for the user's secondary device to scan compared to a compressed PNG image.

B. Security-Hardened Dashboards

For high-security environments where you do not want to load external images from our servers, you can fetch the raw string on your backend, verify its integrity, and then generate the QR pattern locally using your own internal corporate styling.

⚠️ Common Pitfalls

• Binary vs. String: The data field is Base64 encoded. If you try to pass the raw Base64 string directly into a QR generator without decoding it first, the scan will fail because the data will be interpreted as a literal Base64 string rather than the underlying WhatsApp protocol ID.
• Expiry Ignorance: Always check the expiry field. If your frontend displays a QR code that has already passed its expiry timestamp, the user will scan it only to see an "Expired" error on their phone, leading to significant UX frustration.

Summary of Responsibilities:

• Retrieve the raw cryptographic string required for a WhatsApp handshake.
• Provide a Base64-wrapped JSON envelope for protocol compatibility.
• Enable custom rendering in non-browser environments (CLI, Mobile).
• Facilitate advanced monitoring of QR rotation cycles and expiration.