Getting Started with Engagifii Revenue API

This guide will walk you through integrating with the Engagifii Revenue API in under 30 minutes. By the end, you'll be able to authenticate, create your first invoice, and process a payment.

Table of Contents

1. Prerequisites
2. Authentication Setup
3. First API Call
4. Common Integration Patterns
5. Testing Your Integration
6. Troubleshooting
7. Next Steps

Prerequisites

Before you begin, ensure you have:

Required

• API Credentials: Contact your account manager to obtain:
  • Tenant Code
  • Client ID
  • Client Secret
  • API Endpoint URL
• Development Environment: Any programming language that supports HTTP requests
• HTTPS Support: All API calls must use HTTPS

Recommended Tools

• Postman or similar API testing tool
• curl for command-line testing
• JSON formatter/viewer for response inspection

Authentication Setup

The Revenue API uses OAuth 2.0 for authentication. Follow these steps to obtain an access token:

Step 1: Obtain Access Token

curl -X POST https://engagifii-prod-revenue.azurewebsites.net/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=revenue.api"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "revenue.api"
}

Step 2: Store Access Token

Store the access_token securely in your application. Tokens expire after 1 hour (3600 seconds).

Step 3: Include Token in Requests

Add the token to all API requests in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

First API Call

Let's test your connection with a simple API call to retrieve invoice settings:

Using curl

curl -X GET "https://engagifii-prod-revenue.azurewebsites.net/api/1.0/settings/invoice" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "tenant-code: YOUR_TENANT_CODE" \
  -H "api-version: 1.0" \
  -H "Content-Type: application/json"

Using JavaScript (fetch)

const apiCall = async () => {
  const response = await fetch('https://engagifii-prod-revenue.azurewebsites.net/api/1.0/settings/invoice', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'tenant-code': 'YOUR_TENANT_CODE',
      'api-version': '1.0',
      'Content-Type': 'application/json'
    }
  });
  
  const data = await response.json();
  console.log('Invoice Settings:', data);
};

apiCall();

Using Python (requests)

import requests

url = "https://engagifii-prod-revenue.azurewebsites.net/api/1.0/settings/invoice"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "tenant-code": "YOUR_TENANT_CODE",
    "api-version": "1.0",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print("Invoice Settings:", response.json())

Using C# (.NET)

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
        client.DefaultRequestHeaders.Add("tenant-code", "YOUR_TENANT_CODE");
        client.DefaultRequestHeaders.Add("api-version", "1.0");
        
        var response = await client.GetAsync("https://engagifii-prod-revenue.azurewebsites.net/api/1.0/settings/invoice");
        var content = await response.Content.ReadAsStringAsync();
        Console.WriteLine($"Invoice Settings: {content}");
    }
}

Common Integration Patterns

Pattern 1: Creating an Invoice

curl -X POST "https://engagifii-prod-revenue.azurewebsites.net/api/1.0/invoice/manual" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "tenant-code: YOUR_TENANT_CODE" \
  -H "api-version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "customerType": "Person",
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "invoiceDate": "2024-01-15",
    "dueDate": "2024-02-15",
    "items": [
      {
        "itemName": "Professional Services",
        "description": "Consulting services for January 2024",
        "quantity": 10,
        "unitPrice": 150.00,
        "amount": 1500.00
      }
    ],
    "taxAmount": 150.00,
    "totalAmount": 1650.00,
    "notes": "Payment due within 30 days"
  }'

Pattern 2: Processing a Payment

curl -X POST "https://engagifii-prod-revenue.azurewebsites.net/api/1.0/payment" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "tenant-code: YOUR_TENANT_CODE" \
  -H "api-version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "invoice_123",
    "paymentMethod": "CreditCard",
    "amount": 1650.00,
    "paymentDate": "2024-01-20",
    "creditCard": {
      "cardNumber": "4111111111111111",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "cvv": "123",
      "cardholderName": "John Doe"
    }
  }'

Pattern 3: Listing Invoices with Pagination

async function getInvoices(page = 1, pageSize = 20) {
  const params = new URLSearchParams({
    page: page,
    pageSize: pageSize,
    sortBy: 'invoiceDate',
    sortOrder: 'desc'
  });
  
  const response = await fetch(`https://engagifii-prod-revenue.azurewebsites.net/api/1.0/invoice?${params}`, {
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'tenant-code': 'YOUR_TENANT_CODE',
      'api-version': '1.0'
    }
  });
  
  const data = await response.json();
  return {
    invoices: data.items,
    totalCount: data.totalCount,
    hasMore: data.hasMore
  };
}

Pattern 4: Handling Subscriptions

import requests

# Create a subscription
def create_subscription(customer_id, plan_id):
    url = "https://engagifii-prod-revenue.azurewebsites.net/api/1.0/subscription"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "tenant-code": tenant_code,
        "api-version": "1.0",
        "Content-Type": "application/json"
    }
    
    payload = {
        "customerId": customer_id,
        "subscriptionPlanId": plan_id,
        "startDate": "2024-02-01",
        "billingCycle": "Monthly",
        "autoRenew": True
    }
    
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

# Check subscription status
def get_subscription_status(subscription_id):
    url = f"https://engagifii-prod-revenue.azurewebsites.net/api/1.0/subscription/{subscription_id}"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "tenant-code": tenant_code,
        "api-version": "1.0"
    }
    
    response = requests.get(url, headers=headers)
    return response.json()

Testing Your Integration

Test Environment Setup

1. Use Test Data: Always use test customer IDs and test payment methods in non-production environments
2. Test Credit Cards:
   • Success: 4111111111111111
   • Decline: 4000000000000002
   • Insufficient Funds: 4000000000000051

Integration Test Checklist

• [ ] Authentication flow works correctly
• [ ] Token refresh before expiration
• [ ] Create test invoice successfully
• [ ] Retrieve invoice details
• [ ] Process test payment
• [ ] Handle pagination for list endpoints
• [ ] Error handling for invalid requests
• [ ] Webhook receipt confirmation (if applicable)

Sample Test Script

// Complete integration test
async function runIntegrationTest() {
  console.log('Starting Revenue API Integration Test...\n');
  
  // Step 1: Authenticate
  console.log('1. Testing authentication...');
  const token = await getAccessToken();
  console.log('✓ Authentication successful\n');
  
  // Step 2: Create Invoice
  console.log('2. Creating test invoice...');
  const invoice = await createTestInvoice(token);
  console.log(`✓ Invoice created: ${invoice.invoiceNumber}\n`);
  
  // Step 3: Retrieve Invoice
  console.log('3. Retrieving invoice details...');
  const invoiceDetails = await getInvoice(token, invoice.id);
  console.log('✓ Invoice retrieved successfully\n');
  
  // Step 4: Process Payment
  console.log('4. Processing test payment...');
  const payment = await processPayment(token, invoice.id, invoice.totalAmount);
  console.log(`✓ Payment processed: ${payment.transactionId}\n`);
  
  // Step 5: Verify Invoice Status
  console.log('5. Verifying invoice status...');
  const updatedInvoice = await getInvoice(token, invoice.id);
  if (updatedInvoice.status === 'Paid') {
    console.log('✓ Invoice marked as paid\n');
  }
  
  console.log('Integration test completed successfully!');
}

runIntegrationTest().catch(console.error);

Troubleshooting

Common Issues and Solutions

1. Authentication Errors

Error: 401 Unauthorized

{
  "error": "invalid_token",
  "error_description": "The access token is invalid or has expired"
}

Solution:

• Verify your credentials are correct
• Check if token has expired (tokens last 1 hour)
• Ensure you're including "Bearer " prefix in Authorization header

2. Missing Required Headers

Error: 400 Bad Request

{
  "error": "missing_header",
  "message": "Required header 'tenant-code' is missing"
}

Solution: Include all required headers:

headers: {
  'Authorization': 'Bearer TOKEN',
  'tenant-code': 'YOUR_TENANT_CODE',
  'api-version': '1.0',
  'Content-Type': 'application/json'
}

3. Rate Limiting

Error: 429 Too Many Requests

{
  "error": "rate_limit_exceeded",
  "retry_after": 60
}

Solution:

• Implement exponential backoff
• Check X-RateLimit-Remaining header
• Cache responses when possible

4. Validation Errors

Error: 422 Unprocessable Entity

{
  "errors": {
    "amount": ["Amount must be greater than 0"],
    "dueDate": ["Due date cannot be in the past"]
  }
}

Solution:

• Review field validation rules in Data Models
• Ensure date formats are ISO 8601 (YYYY-MM-DD)
• Validate decimal precision (2 decimal places for currency)

5. Network Issues

Error: Connection timeout Solution:

• Implement retry logic with exponential backoff
• Set appropriate timeout values (recommended: 30 seconds)
• Use connection pooling for multiple requests

Debug Mode

Enable detailed logging for troubleshooting:

// Debug wrapper for API calls
async function apiCallWithDebug(url, options) {
  console.log('Request:', {
    url,
    method: options.method,
    headers: options.headers,
    body: options.body
  });
  
  try {
    const response = await fetch(url, options);
    const data = await response.json();
    
    console.log('Response:', {
      status: response.status,
      headers: Object.fromEntries(response.headers.entries()),
      body: data
    });
    
    return data;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

Next Steps

Now that you've successfully integrated with the Revenue API:

1. Explore Advanced Features

• Subscription Management - Set up recurring billing
• Credit Notes - Handle refunds and adjustments
• Webhooks - Receive real-time notifications
• Batch Operations - Process multiple items efficiently

2. Implement Best Practices

• Error Handling: Implement comprehensive error handling
• Logging: Log all API interactions for debugging
• Monitoring: Set up monitoring for API health
• Security: Store credentials securely, rotate keys regularly

3. Optimize Performance

• Caching: Cache frequently accessed data
• Batch Requests: Use batch endpoints when available
• Pagination: Implement efficient pagination for large datasets
• Webhooks: Use webhooks instead of polling

4. Review Documentation

• API Reference - Complete endpoint documentation
• Data Models - Detailed schema information
• Error Handling - Comprehensive error guide
• Authentication - Security best practices

5. Get Support

• Technical Support: support@engagifii.com
• API Status: Check system status page
• Community: Join our developer community

Sample Projects

Explore our sample integration projects:

• Node.js Integration
• Python Integration
• C# Integration
• Java Integration

---

Congratulations! You've successfully integrated with the Engagifii Revenue API. For questions or support, contact our technical team.