Quick Reference

Essential Revenue API operations for quick copy-paste reference. Replace placeholders with your actual values.

Setup

Base Configuration

BASE_URL="https://engagifii-prod-revenue.azurewebsites.net"
API_VERSION="1.0"
TENANT_CODE="YOUR_TENANT_CODE"
TOKEN="YOUR_ACCESS_TOKEN"

Get Access Token

curl -X POST "$BASE_URL/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.full"

Common Operations

Invoices

Create Invoice

curl -X POST "$BASE_URL/api/$API_VERSION/invoice/manual" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant-code: $TENANT_CODE" \
  -H "api-version: $API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "customerType": "Person",
    "customerId": "CUSTOMER_UUID",
    "invoiceDate": "2024-01-15",
    "dueDate": "2024-02-15",
    "items": [{
      "itemName": "Service",
      "quantity": 1,
      "unitPrice": 100.00
    }]
  }'

List Invoices

curl -X GET "$BASE_URL/api/$API_VERSION/invoice?status=Sent&page=1&pageSize=20" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant-code: $TENANT_CODE" \
  -H "api-version: $API_VERSION"

Get Invoice

curl -X GET "$BASE_URL/api/$API_VERSION/invoice/INVOICE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant-code: $TENANT_CODE" \
  -H "api-version: $API_VERSION"

Send Invoice

curl -X POST "$BASE_URL/api/$API_VERSION/invoice/send/INVOICE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant-code: $TENANT_CODE" \
  -H "api-version: $API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "emailTo": ["customer@example.com"],
    "attachPdf": true
  }'

Payments

Process Payment

curl -X POST "$BASE_URL/api/$API_VERSION/payment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant-code: $TENANT_CODE" \
  -H "api-version: $API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": "CreditCard",
    "amount": 100.00,
    "invoices": [{
      "invoiceId": "INVOICE_ID",
      "amount": 100.00
    }],
    "creditCard": {
      "cardNumber": "4111111111111111",
      "cardholderName": "John Doe",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "cvv": "123"
    }
  }'

List Payments

curl -X GET "$BASE_URL/api/$API_VERSION/payment?invoiceId=INVOICE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant-code: $TENANT_CODE" \
  -H "api-version: $API_VERSION"

Credit Notes

Create Credit Note

curl -X POST "$BASE_URL/api/$API_VERSION/creditNote" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant-code: $TENANT_CODE" \
  -H "api-version: $API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "CUSTOMER_UUID",
    "customerType": "Person",
    "creditNoteDate": "2024-01-20",
    "creditNoteType": "Refund",
    "items": [{
      "description": "Refund",
      "amount": 50.00
    }],
    "reason": "Service issue"
  }'

Apply Credit Note

curl -X POST "$BASE_URL/api/$API_VERSION/creditNote/CREDIT_NOTE_ID/apply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant-code: $TENANT_CODE" \
  -H "api-version: $API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "invoices": [{
      "invoiceId": "INVOICE_ID",
      "amountToApply": 50.00
    }]
  }'

Subscriptions

Create Subscription

curl -X POST "$BASE_URL/api/$API_VERSION/subscription" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant-code: $TENANT_CODE" \
  -H "api-version: $API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "CUSTOMER_UUID",
    "customerType": "Person",
    "planId": "PLAN_ID",
    "startDate": "2024-02-01",
    "billingCycle": "Monthly",
    "price": 99.99
  }'

Cancel Subscription

curl -X POST "$BASE_URL/api/$API_VERSION/subscription/SUBSCRIPTION_ID/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant-code: $TENANT_CODE" \
  -H "api-version: $API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellationType": "EndOfBillingPeriod",
    "reason": "Customer request"
  }'

JavaScript Quick Start

// Setup
const API = {
  baseURL: 'https://engagifii-prod-revenue.azurewebsites.net',
  version: '1.0',
  tenantCode: 'YOUR_TENANT_CODE',
  token: 'YOUR_ACCESS_TOKEN'
};

// Helper function
async function apiCall(method, endpoint, data = null) {
  const options = {
    method,
    headers: {
      'Authorization': `Bearer ${API.token}`,
      'tenant-code': API.tenantCode,
      'api-version': API.version,
      'Content-Type': 'application/json'
    }
  };
  
  if (data) options.body = JSON.stringify(data);
  
  const response = await fetch(
    `${API.baseURL}/api/${API.version}/${endpoint}`,
    options
  );
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || 'API Error');
  }
  
  return response.json();
}

// Examples
const invoice = await apiCall('GET', 'invoice/INV-123');
const payment = await apiCall('POST', 'payment', { /* data */ });

Python Quick Start

import requests

# Setup
API = {
    'base_url': 'https://engagifii-prod-revenue.azurewebsites.net',
    'version': '1.0',
    'tenant_code': 'YOUR_TENANT_CODE',
    'token': 'YOUR_ACCESS_TOKEN'
}

# Helper function
def api_call(method, endpoint, data=None):
    url = f"{API['base_url']}/api/{API['version']}/{endpoint}"
    headers = {
        'Authorization': f"Bearer {API['token']}",
        'tenant-code': API['tenant_code'],
        'api-version': API['version'],
        'Content-Type': 'application/json'
    }
    
    response = requests.request(method, url, json=data, headers=headers)
    response.raise_for_status()
    return response.json()

# Examples
invoice = api_call('GET', 'invoice/INV-123')
payment = api_call('POST', 'payment', {...})

Common Queries

Unpaid Invoices

GET /api/1.0/invoice?status=Sent,Overdue&sortBy=dueDate&sortOrder=asc

Today's Payments

GET /api/1.0/payment?fromDate=2024-01-20&toDate=2024-01-20

Customer Balance

GET /api/1.0/account/balance/statistics/Person/CUSTOMER_UUID

Active Subscriptions

GET /api/1.0/subscription?status=Active&page=1&pageSize=100

Status Codes Reference

Code	Meaning	Action
200	Success	Process response
201	Created	Resource created
400	Bad Request	Fix request format
401	Unauthorized	Check/refresh token
403	Forbidden	Check permissions
404	Not Found	Verify resource ID
422	Validation Error	Check field values
429	Rate Limited	Wait and retry
500	Server Error	Retry with backoff

Required Headers

Authorization: Bearer YOUR_ACCESS_TOKEN
tenant-code: YOUR_TENANT_CODE
api-version: 1.0
Content-Type: application/json

Test Credit Cards

Type	Number	Result
Success	4111111111111111	Approved
Declined	4000000000000002	Declined
Insufficient	4000000000000051	NSF

Date Formats

• Date only: YYYY-MM-DD (e.g., 2024-01-20)
• DateTime: YYYY-MM-DDTHH:mm:ssZ (e.g., 2024-01-20T10:30:00Z)

Pagination

?page=1&pageSize=20&sortBy=createdDate&sortOrder=desc

Filtering

?status=Active&customerId=UUID&fromDate=2024-01-01&toDate=2024-01-31

Common Error Fixes

Error	Fix
INVALID_TOKEN	Refresh access token
VALIDATION_ERROR	Check required fields
RATE_LIMIT_EXCEEDED	Wait for reset time
INSUFFICIENT_PERMISSIONS	Check user role
RESOURCE_NOT_FOUND	Verify ID exists

Support

• Docs: Full Documentation
• OpenAPI: Download Spec
• Postman: Import Collection
• Support: support@engagifii.com