Skip to main content

​
Development Setup

Prerequisites:
  • A code editor (VS Code recommended)
  • Postman for API testing
  • Agd Ejar API credentials

​
1. Environment Setup

First, set up your development environment variables: 
# API Configuration
AGDEJAR_URL=https://app.agdejar.sa
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret

# Optional Configuration
DEBUG=true
ENVIRONMENT=development

​
2. Authentication Helper

Create a helper function to manage authentication: 
async function getAccessToken() {
  const response = await fetch(`${config.baseUrl}/oauth/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'multipart/form-data'
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: config.auth.clientId,
      client_secret: config.auth.clientSecret,
      scope: 'read'
    })
  });
  
  return response.json();
}

​
Testing Tools

​
Postman Setup

  1. Import our Postman Collection
  2. Create an environment with these variables:
    • base_url: https://app.agdejar.sa
    • client_id: Your client ID
    • client_secret: Your client secret
    • access_token: Will be automatically set after authentication

​
Error Handling

Implement proper error handling in your development environment: 
try {
  const response = await makeApiCall();
  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error);
    // Handle specific error cases
    switch (error.code) {
      case 'TOKEN_EXPIRED':
        await refreshToken();
        break;
      // Add other error cases
    }
  }
} catch (err) {
  console.error('Network Error:', err);
}

​
Best Practices

  1. Rate Limiting
    • Implement exponential backoff
    • Cache responses where appropriate
    • Monitor API usage
  2. Security
    • Never commit credentials to version control
    • Use environment variables
    • Implement proper token management
  3. Debugging
    • Enable debug logs in development
    • Use proper error handling
    • Monitor API responses

​
Troubleshooting

  • Verify your credentials are correct
  • Check token expiration
  • Ensure proper Content-Type headers
  • Implement request throttling
  • Add proper error handling
  • Contact support for limit adjustments

​
Need Help?

If you encounter any issues during development: