Technical Implementation Guide
This technical implementation guide provides comprehensive details for integrating your mobile application with gashapon machines. Explore the different technical areas below.
Core Requirements
Discover the essential components needed for your mobile application and backend API to support gashapon machine integration.
View Details →Machine Communication
Learn about the protocol for communicating with gashapon machines, including command sequences and responses.
View Details →Security Considerations
Explore security best practices for QR code generation, API communication, and transaction processing.
View Details →Error Handling
Understand common error scenarios and strategies for handling them effectively to ensure a smooth user experience.
View Details →Mobile App Requirements
To enable your mobile app to interact with gashapon machines, you'll need to implement several key components.
QR Code Generation
The QR code must contain the following essential components:
Required Information
- App ID: Unique identifier for your application
- User ID: Unique identifier for the user
- Transaction ID: Unique for each play attempt
- Point Amount: Number of points to deduct
- Timestamp: UTC timestamp of QR generation
- Signature (optional): Digital signature for security
Example QR Code Content
Important Considerations
- Set QR code expiration time (recommended: 5 minutes)
- Implement one-time-use validation for security
- Use HMAC or similar methods for signature generation
App Modifications Needed
UI Components
-
1
QR Code Generation Screen
Create a dedicated screen to generate and display QR codes for machine scanning.
-
2
Point Balance Display
Show current point balance and update in real-time after transactions.
-
3
Transaction History
Display a log of gashapon plays with dates, points used, and outcomes.
App Logic
-
1
QR Code Generator
Implement secure QR code generation with all required data elements.
-
2
Status Polling
Implement API polling to check transaction status after QR code is scanned.
-
3
Error Handling
Create robust error handling for network issues, insufficient points, and other scenarios.
Backend API Requirements
Your backend needs to implement several new API endpoints to facilitate communication between your app and the gashapon machines.
New API Endpoints Required
QR Code Validation API
This endpoint verifies the QR code scanned by the gashapon machine and processes point deduction.
Endpoint Specifications
- URL: /api/v1/gashapon/validate
- Method: POST
- Authentication: API Key
- Content-Type: application/json
Responsibilities
- Verify QR code authenticity and expiration
- Check if user has sufficient points
- Deduct points from user account
- Return success or failure to machine
- Store transaction details
Transaction Status API
Allows the mobile app to check transaction status and update point balance information.
Endpoint Specifications
- URL: /api/v1/gashapon/transaction/{transaction_id}
- Method: GET
- Authentication: User Auth Token
- Response Format: JSON
Responsibilities
- Provide transaction status (pending, complete, failed)
- Return updated point balance
- Include error details if applicable
- Support polling from mobile app
Webhook/Callback (Optional)
Receive real-time notifications from machine about transaction completion.
Endpoint Specifications
- URL: /api/v1/gashapon/webhook
- Method: POST
- Authentication: Webhook Secret
- Content-Type: application/json
Responsibilities
- Receive transaction completion notifications
- Update transaction status in database
- Push notification to mobile app (optional)
- Handle refunds for failed dispensing