Integration Checklist

Complete checklist for successful integration

Pre-Integration

✅ Obtain Credentials

1. Contact Dükkango to request API access
2. Receive app_secret_key
3. Receive rest_secret_key for your restaurant(s)
4. Store credentials securely (environment variables)

Test:

curl -X POST https://www.xn--dkkango-n2a.com/api/integrations/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"app_secret_key": "your-key", "rest_secret_key": "your-key"}'

✅ Setup Development Environment

• HTTPS-enabled server
• Node.js/Python/PHP environment
• Database for local order storage
• Logging system
• Error tracking (optional but recommended)

✅ Review Documentation

• Read Quick Start
• Understand Authentication
• Study Order Lifecycle
• Review all API endpoints

Authentication Implementation

1. Implement Login

   async function login(appSecret, restSecret) {
     const response = await fetch(
       'https://www.xn--dkkango-n2a.com/api/integrations/auth/login',
       {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
           app_secret_key: appSecret,
           rest_secret_key: restSecret
         })
       }
     );
     
     const data = await response.json();
     return data.data;
   }
   

   • Login endpoint implemented
   • Credentials stored securely
   • Access token received successfully
2. Implement Token Storage

   class TokenManager {
     storeToken(accessToken, expirationDate) {
       localStorage.setItem('access_token', accessToken);
       localStorage.setItem('token_expiry', expirationDate);
     }
     
     getToken() {
       return localStorage.getItem('access_token');
     }
   }
   

   • Token storage implemented
   • Expiration date tracked
3. Implement Token Refresh

   async function ensureValidToken() {
     const expiry = new Date(localStorage.getItem('token_expiry'));
     const now = new Date();
     
     // Refresh if expired or expiring soon (1 hour buffer)
     if (now > expiry - 3600000) {
       const { access_token, expiration_date } = await login();
       storeToken(access_token, expiration_date);
     }
   }
   

   • Token refresh logic implemented
   • Proactive refresh (before expiration)
   • Handles 401 errors

Restaurant Management

✅ Implement Restaurant Endpoints

• GET /restaurants/get - Fetch restaurant list
• GET /restaurants/status/get/{rest_id} - Check status
• PUT /restaurants/status/open/{rest_id} - Open restaurant
• PUT /restaurants/status/close/{rest_id} - Close restaurant

Test each endpoint:

# Get restaurants
curl -X GET https://www.xn--dkkango-n2a.com/api/integrations/restaurants/get \
  -H 'Access-Token: your-token'

# Check status
curl -X GET https://www.xn--dkkango-n2a.com/api/integrations/restaurants/status/get/{rest_id} \
  -H 'Access-Token: your-token'

# Open restaurant
curl -X PUT https://www.xn--dkkango-n2a.com/api/integrations/restaurants/status/open/{rest_id} \
  -H 'Access-Token: your-token'

# Close restaurant
curl -X PUT https://www.xn--dkkango-n2a.com/api/integrations/restaurants/status/close/{rest_id} \
  -H 'Access-Token: your-token'

✅ UI Integration

• Display restaurant status in POS
• Open/close buttons functional
• Status syncs with API
• Visual indicators (green=open, red=closed)

Menu Management

✅ Implement Food Endpoints

• GET /foods/get-foods - Fetch menu (with rate limit handling)
• PUT /foods/status-active/{food_id} - Activate item
• PUT /foods/status-passive/{food_id} - Deactivate item

Test:

# Get menu
curl -X GET https://www.xn--dkkango-n2a.com/api/integrations/foods/get-foods \
  -H 'Access-Token: your-token'

# Activate item
curl -X PUT https://www.xn--dkkango-n2a.com/api/integrations/foods/status-active/1 \
  -H 'Access-Token: your-token'

# Deactivate item
curl -X PUT https://www.xn--dkkango-n2a.com/api/integrations/foods/status-passive/1 \
  -H 'Access-Token: your-token'

✅ Menu Caching

• Menu data cached locally
• Cache duration: 30+ minutes
• Manual refresh option for staff
• Respects 30-second rate limit

✅ Modifier Handling

• Parse add_substract modifier groups
• Display modifiers in POS
• Calculate prices including modifiers
• Match modifiers in incoming orders

Order Management

✅ Order Polling

• GET /orders/get-current implemented
• Polling interval: 30+ seconds
• Rate limit (429) handled
• Polls continuously while POS is running

setInterval(async () => {
  try {
    const orders = await getOrders();
    for (const order of orders) {
      await processOrder(order);
    }
  } catch (error) {
    handleError(error);
  }
}, 30000); // 30 seconds

✅ Order Acknowledgment

• PUT /orders/success/{payment_key} implemented
• Called immediately after importing order
• Uses payment_key (UUID), not id (integer)
• Prevents duplicate orders

✅ Order Acceptance

• PUT /orders/accept/{payment_key} implemented
• Includes preparing_time parameter
• Staff can set preparation time
• Updates order status to CONFIRMED

✅ Order Dispatch

• PUT /orders/ontheway/{payment_key} implemented
• Only for restaurant couriers
• Checks courier_type before calling
• Updates order status to IN_DELIVERY

✅ Order Completion

• PUT /orders/complete/{payment_key} implemented
• Confirms delivery and payment
• Works for all payment types
• Updates order status to COMPLETE_WITH_PAYMENT

✅ Order Cancellation

• GET /orders/cancel-reasons implemented
• PUT /orders/cancel/{payment_key} implemented
• Staff can select cancellation reason
• Includes reason_id (1-8)
• Updates order status to CANCELED

✅ Order Variables

• GET /orders/variables implemented
• Payment methods cached
• Shipping methods cached
• Used for display mapping

Data Handling

✅ Order Storage

• Orders saved to local database
• All order fields stored correctly
• Customer information stored
• Order items with modifiers stored
• Order history maintained

✅ Data Validation

• Validate order structure
• Check required fields
• Validate UUIDs
• Verify payment methods
• Confirm shipping methods

✅ Modifier Processing

• Parse nested modifier structure
• Extract modifier group names
• Extract ingredient names and prices
• Calculate total with modifiers
• Display modifiers to kitchen staff

Error Handling

✅ Implement Error Handling

• Try-catch around all API calls
• Parse error responses
• Handle 401 (authentication)
• Handle 403 (forbidden)
• Handle 404 (not found)
• Handle 422 (validation)
• Handle 429 (rate limit)
• Handle 500 (server error)
• Network error handling

✅ Retry Logic

• Retry on 429 (after 30s wait)
• Retry on 500 (with exponential backoff)
• Maximum retry attempts (3)
• Don’t retry on 400/403/404

✅ Error Logging

• Log all errors with context
• Include timestamps
• Include request details
• Store locally for debugging
• Send to monitoring service (optional)

User Interface

✅ Order Display

• New orders highlighted
• Order details clearly displayed
• Customer information visible
• Delivery address shown
• Order items with modifiers listed
• Total amount displayed
• Order status visible

✅ Actions

• Accept order button
• Set preparation time input
• Mark on the way button
• Complete order button
• Cancel order button (with reason selection)
• View order details

✅ Notifications

• Sound alert for new orders
• Visual notification
• Desktop notification (optional)
• Success/error messages

Testing

✅ Endpoint Testing

• Test login with valid credentials
• Test login with invalid credentials
• Test token expiration
• Test all restaurant endpoints
• Test all food endpoints
• Test all order endpoints
• Test rate limiting
• Test error responses

✅ Order Lifecycle Testing

• Test RECEIVED → CONFIRMED
• Test CONFIRMED → IN_DELIVERY
• Test IN_DELIVERY → COMPLETE
• Test order cancellation
• Test order repetition (before acknowledgment)
• Test order acknowledgment

✅ Edge Cases

• Orders with no modifiers
• Orders with multiple modifier groups
• Scheduled orders
• Cash vs card payments
• Different courier types
• Large orders (many items)
• Network timeouts
• Server errors

Security

✅ Credential Security

• Credentials in environment variables
• Credentials not in source code
• Credentials not logged
• Credentials encrypted at rest

✅ Token Security

• Tokens stored securely
• Tokens not logged
• Tokens transmitted over HTTPS only
• Token refresh implemented

✅ HTTPS

• All requests use HTTPS
• SSL certificates validated
• No HTTP fallback

Production Deployment

✅ Pre-Deployment

• All tests passing
• Error handling tested
• Logging configured
• Monitoring set up
• Backup procedures in place

✅ Configuration

• Production API base URL configured
• Production credentials set
• Polling intervals optimized
• Cache durations configured
• Timeout values set

✅ Monitoring

• API call success rate monitored
• Error rates tracked
• Response times monitored
• Rate limit hits tracked
• Alerts configured for issues

✅ Documentation

• Internal documentation written
• Staff training completed
• Troubleshooting guide created
• Emergency procedures documented

Post-Deployment

✅ Verification

• Test order flow end-to-end
• Verify orders appear correctly
• Confirm status updates work
• Test restaurant open/close
• Test menu item activation/deactivation
• Monitor for errors

✅ Ongoing Maintenance

• Monitor integration health daily
• Review error logs regularly
• Update credentials periodically
• Keep documentation updated
• Train new staff as needed

Quick Reference

Critical IDs

• Use payment_key (UUID) for order operations
• Use food_id (integer) for menu operations
• Use rest_id (UUID) for restaurant operations

Critical Intervals

• Poll orders: 30+ seconds
• Cache menu: 30+ minutes
• Token refresh: Before 24 hours

Critical Remember

• Always acknowledge orders immediately
• Always use HTTPS
• Always handle rate limits
• Never log credentials
• Never use integer id for order operations

Need Help?

API Reference

Complete endpoint documentation

Order Lifecycle

Understand order flow

Best Practices

Production-ready patterns

Contact Support

Get help from our team

---

Congratulations! Once you’ve completed this checklist, your integration is ready for production. 🎉