Reporting API v2 - overview

Introduction

This article provides a comprehensive guide to the Reporting API v2, an enhanced collection of API endpoints designed for advanced self-service reporting and billing integrations. The API v2 offers improved performance, additional endpoints, and expanded data access capabilities compared to v1. It enables access to key platform data across currency exchange rates, invoice consolidations, and enhanced invoice management with partner-specific reporting capabilities, offering enhanced filtering options and better metadata support.

Understanding the Reporting API v2

The Reporting API v2 is an enhanced version of the REST API endpoints that provide comprehensive data access for self-service reporting and billing integrations. This API serves as an advanced interface for extracting platform data programmatically, enabling organizations to build sophisticated reporting solutions, integrate with external systems, and automate complex billing processes.

The API v2 is designed to handle large-scale data requests more efficiently than v1 while maintaining enhanced security through proper authentication and authorization mechanisms. All endpoints follow RESTful principles and return data in JSON format for easy integration with modern applications.

For information about the previous version, see the Reporting API v1 - overview documentation.

API Coverage Areas

The Reporting API v2 covers several key areas of the platform with enhanced capabilities:

Currency Exchange Rates: Comprehensive currency rate management with requester-specific rates, partner currency rates summary, and historical exchange rate data with enhanced filtering capabilities. Includes support for multi-currency reporting and financial calculations.For details refer to Reporting API v2 - currency exchange rates

Invoice Consolidations: Detailed invoice consolidation reporting with filtering by consolidation ID, invoice type, and consumer information for better financial oversight and consolidated billing management. For details refer to: Reporting API v1/v2 – consolidated invoices

Enhanced Invoice Management: Extended invoice header and row data with additional fields, improved performance, and partner-specific reporting capabilities. Includes support for preview functionality and detailed line item analysis with expanded metadata.

Partner-Specific Reporting: Dedicated endpoints for accessing partner invoice headers and rows, enabling enhanced multi-tier reporting capabilities and distributor validation activities.

Access Requirements

To access the Reporting API v2, you must first request proper credentials through the official process:

1. Navigate to the API access request documentation: How to request API Access
2. Submit your access request following the provided instructions
3. Wait for approval and credential provisioning from AppXite
4. Configure your application with the provided authentication parameters

Authentication Parameters

The Reporting API v2 supports flexible authentication methods. After your access request is approved, you will receive the following authentication parameters:

requesterId: This is the unique identifier of your organization that sets the context for data access. The requesterId determines which data records you can access based on your organizational permissions and hierarchy.

sasKey: This is the secure access key provided by AppXite specifically for API authentication. Keep this key confidential and rotate it regularly according to your security policies.

Authentication Methods: The sasKey can be provided via:

• Query parameter: sasKey={{sasKey}}
• Header: saskey: {{sasKey}}

environment: This parameter specifies the API environment for your requests (e.g., "api" for production)

Historical Data Retrieval

The Reporting API v2 supports both current and historical invoice data through an optimized dual-table architecture for improved performance.

Performance Optimization

Invoice data is automatically split between operational tables (data after 2024-12-01) and historical tables (data before 2024-12-01). For optimal performance, use the createdDataFrom and createdDataTill parameters in your API requests.

Benefits of using date parameters:

• Significantly faster response times by targeting specific data sources
• Reduced server load through intelligent query routing
• Automatic selection of operational or historical tables based on date range

API Endpoints

Currency Rates

The v2 API provides enhanced currency rate endpoints with comprehensive filtering and partner support:

• GET /api/v2/reporting/requesters/{{requesterId}}/currency-rates

Get Requester Currency Rates

Access currency exchange rates for multi-currency reporting and financial calculations with enhanced filtering capabilities.

Parameters: exchangeDateFrom (required), exchangeDateTill (required), fromCurrency (optional), toCurrency (optional), sasKey (required)

• GET /api/v2/reporting/requesters/{{requesterId}}/currency-rates/partners/list

Get Requester Partners Currency Rates Summary

Retrieve a summary list of partners who have configured currency rates by themselves.

Parameters: sasKey (required)

• GET /api/v2/reporting/requesters/{{requesterId}}/partners/{{partnerId}}/currency-rates

Get Requester Partner Currency Rates

Access specific partner currency rates for distributor reporting and validation activities.

Parameters: exchangeDateFrom (required), exchangeDateTill (required), fromCurrency (optional), toCurrency (optional), sasKey (required)

Invoice Consolidations

• GET /api/v2/reporting/requesters/{{requesterId}}/invoice-consolidations

Get Requester Invoice Consolidations

Access comprehensive invoice consolidation data for enhanced financial reporting and billing oversight.

Parameters: invoiceConsolidationId (optional), invoiceId (optional), invoiceYear (optional), invoiceMonth (optional), invoiceType (optional), consumerId (optional), lastUpdatedDate (optional), saskey (optional)

Invoice Headers

• GET /api/v2/reporting/requesters/{{requesterId}}}/invoices/headers

Get Requester Invoice Headers

Access enhanced invoice header data with additional fields and improved performance for comprehensive billing information.

Parameters: invoiceYear (optional), invoiceMonth (optional), lastUpdatedDate (optional), invoiceType (optional), contractTypeId (optional), invoiceId (optional), invoiceConsolidationId (optional), consumerId (optional), includeOtherSources (optional), isPreview (optional), saskey (optional)

• GET /api/v2/reporting/requesters/{{requesterId}}/partners/{{partnerId}}/invoices/headers

Get Requester Partner Invoice Headers

Access partner-specific invoice headers for enhanced multi-tier reporting capabilities.

Parameters: Same as Get Requester Invoice Headers

Invoice Rows

• GET /api/v2/reporting/requesters/{{requesterId}}/invoices/rows

Get Requester Invoice Rows

Retrieve detailed invoice line items with expanded metadata and enhanced filtering options for comprehensive invoice analysis.

Parameters: invoiceYear (optional), invoiceMonth (optional), lastUpdatedDate (optional), invoiceType (optional), contractTypeId (optional), invoiceId (optional), consumerId (optional), invoiceConsolidationId (optional), includeOtherSources (optional), expand (optional), isPreview (optional), saskey (optional)

• GET /api/v2/reporting/requesters/{{requesterId}}/partners/{{partnerId}}/invoices/rows

Get Requester Partner Invoice Rows

Access partner-specific invoice rows with inventory information and tracking details for advanced reporting needs.

Parameters: Same as Get Requester Invoice Rows

Invoice taxes

• GET /api/v2/reporting/requesters/{{requesterId}}/invoice-taxes

Get requester invoice taxes

Retrieve detailed tax records associated with requester invoices for compliance reporting and financial analysis.

Parameters: invoiceConsolidationId (optional), invoiceId (optional), invoiceYear (required if invoiceMonth specified), invoiceMonth (required if invoiceYear specified), consumerId (optional), taxLastCreatedDateFrom (required if invoiceYear and invoiceMonth not specified), saskey (optional)

Environment Variables

• {{environment}} - Environment (e.g., "api")
• {{requesterId}} - Requester ID (GUID)
• {{partnerId}} - Partner ID (GUID)
• {{sasKey}} - SAS Key for authentication

Response Format

All endpoints return JSON format with appropriate HTTP status codes.

Notes

• All date parameters should be in yyyy-MM-dd format
• GUIDs are expected in standard GUID format
• Boolean parameters accept true/false values

Limitations

• Some advanced endpoints require specific organizational permissions beyond basic API access
• Cross-organization data access is restricted based on your organizational hierarchy and permissions
• Historical data may have different availability windows depending on the endpoint
• Rate limiting may apply to prevent system overload

Summary

The Reporting API v2 provides enhanced access to platform data through advanced REST endpoints covering currency exchange rates, invoice consolidations, enhanced invoice management, and partner-specific reporting capabilities. The v2 API offers improved performance, additional endpoints, and expanded data access capabilities compared to v1. Access requires proper authentication credentials including requesterId and sasKey, with flexible authentication methods supporting both query parameters and headers. The API enables advanced self-service reporting and billing integrations while maintaining enhanced security through proper authentication and authorization mechanisms.

For optimal performance in production environments, we recommend using date range parameters when querying invoice data to take advantage of the optimized dual-table architecture.