ARN Generation API Documentation

Overview

This API generates ARN (Application Reference Number) for invoice processing. The API is designed for training purposes and includes a 20% failure rate to simulate real-world error handling scenarios.

Authentication

This API requires authentication using an API key passed in the request headers.

Required Headers

Endpoint

POST https://buildwithhussain.com/api/v2/method/get_arn_number

Request Parameters

Example Request

curl -X POST "https://buildwithhussain.com/api/v2/method/get_arn_number" \
  -H "Authorization: token {api_key}:{api_secret}" \
  -H "Content-Type: application/json" \
  -d '{"user_name": "john_doe", "invoice_number": "INV-2024-001"}'

Success Response

HTTP Status: 200 OK

{
  "message": {
    "arn_number": "ARN2024-07-28JOH001"
  }
}

ARN Format Breakdown

The ARN follows this format: ARN{DATE}{USER}{INVOICE}

• ARN: Static prefix
• {DATE}: Current date in YYYY-MM-DD format
• {USER}: First 3 characters of username (uppercase), padded with 'X' if needed
• {INVOICE}: Last 6 characters of invoice number (special characters removed)

Examples:

• Username: "john_doe", Invoice: "INV-2024-001" → ARN2024-07-28JOH001
• Username: "ai", Invoice: "BILL/2024/123456789" → ARN2024-07-28AIX456789

Error Responses

⚠️ Important: This API has a 20% failure rate by design for training purposes.

Possible Error Types

Error Response Format

Follows Frappe's error format

{
    "errors": [
        {
            "type": "ValidationError",
            "message": "This is a portal error",
            "title": "Random Error 1",
            "indicator": "red"
        }
    ]
}

Error Handling Best Practices

Since this API has a 20% failure rate, implement proper error handling:

1. Retry Logic

async function generateARN(userData, apiKey, apiSecret, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://buildwithhussain.com/api/v2/method/get_arn_number', {
        method: 'POST',
        headers: { 
          'Authorization': `token ${apiKey}:${apiSecret}`,
          'Content-Type': 'application/json' 
        },
        body: JSON.stringify(userData)
      });
      
      if (response.ok) {
        return await response.json();
      }
      
      // Don't retry authentication errors
      if (response.status === 401) {
        throw new Error('Authentication failed - check API key');
      }
      
      throw new Error(`HTTP ${response.status}`);
    } catch (error) {
      console.log(`Attempt ${attempt} failed:`, error.message);
      
      if (attempt === maxRetries || error.message.includes('Authentication')) {
        throw error;
      }
      
      // Wait before retrying (exponential backoff)
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }
}

Important Notes

1. API Token: Combination of API Key & Secret, as illustrated above
2. Failure Rate: Approximately 1 in 5 requests will fail randomly (excluding auth errors)
3. Error Logging: All API errors must be logged to database with full context
4. Retry Strategy: Implement exponential backoff, don't retry authentication errors
5. ARN Format: Uses server's current date (YYYY-MM-DD), uppercase username, cleaned invoice number

Deliverables

• Integration of this API into your project
• Error handling and database logging of all errors for investigation

Rate Limiting

No rate limiting is implemented for this training API.

Brownie points for implementing retry logic