Fetch Received Invoices

Fetch Received Invoices

Retrieve a paginated list of invoices for a specified business with flexible filtering and sorting options.

Quick Reference

Method Endpoint Content-Type
POST https://api-dev.nairainvoice.com/dev/external/businesses/:businessId/fetchInvoices application/json

Request Structure

Path Parameters

Parameter Type Required Description Example
businessId string ✅ Unique identifier of the business 26ede24b-ac50-475f-aacc-5ea6339f086

Query Parameters

Parameter Type Required Description Example
invoicePaymentStatus string optional This filters the invoices using the payment status PENDING, PAID, REJECTED

Request Body

The request body must be a JSON object containing pagination parameters:

Field Type Required Description Default Validation
page number ✅ Page number for pagination Must be ≥ 1
size number ✅ Number of results per page Must be between 1–100
invoicePaymentStatus string optional This filters the invoices using the payment status PENDING, PAID, REJECTED
dateTo string optional This filters the invoices within a specific date range Valid date format (YYYY-MM-DD)
dateFrom string optional This filters the invoices within a specific date range Valid date format (YYYY-MM-DD)

📤 Response Format

Success Response (200)

Copy to Clipboard

📋 Response Data Structure

Invoice Object

Field Type Description
irn string Invoice Reference Number
invoiceNumber string User-defined invoice number
issueDate string Date invoice was issued (YYYY-MM-DD)
dueDate string Payment due date (YYYY-MM-DD)
paymentStatus string Payment status: PENDING, PAID, REJECTED
documentCurrencyCode string Currency code (e.g., NGN, USD)
payableAmount number Total amount payable
taxInclusiveAmount number Amount including tax
customerPartyName string Customer name
supplierPartyName string Supplier name
note string Additional notes about the invoice

Pagination Object

Field Type Description
currentPage number Current page number
pageSize number Number of items per page
totalPages number Total number of pages
totalElements number Total number of invoices
hasNext boolean Whether there are more pages
hasPrevious boolean Whether there are previous pages

Summary Object

Field Type Description
totalInvoices number Total number of invoices
totalAmount number Sum of all invoice amounts
paidInvoices number Count of paid invoices
pendingInvoices number Count of pending invoices
rejectedInvoices number Count of rejected invoices

✅ Validation Rules

Request Body Validation

  • page must be a positive integer (≥ 1)
  • size must be between 1 and 100
  • Both fields are required

Path Parameter Validation

  • businessId must be a valid UUID format
  • Business must exist and be accessible to the user

Business Logic Validation

  • User must have permission to access the business’s invoices
  • Only finalized/sent invoices are included in results
  • Deleted invoices are excluded from results

⚠️ Error Responses

Common Error Scenarios

Error Code Message Description Solution
400 Invalid page parameter Page number is less than 1 Use page ≥ 1
400 Invalid size parameter Page size is outside allowed range Use size between 1–100
404 Business not found Business ID doesn’t exist Verify business ID
403 Access denied User doesn’t have permission Check user permissions
422 Missing required fields Page or size not provided Include both page and size

Example Error Response

Copy to Clipboard

💡 Pagination Best Practices

Efficient Data Loading

  • Start small: Use page size 10-25 for initial loads
  • Progressive loading: Increase page size for subsequent requests
  • Maximum limit: Don’t exceed 100 items per page

Navigation Implementation

  • Use pagination object: Leverage hasNext and hasPrevious for navigation
  • Total pages: Display total pages using totalPages
  • Current position: Show current page context

Performance Optimization

  • Cache results: Store frequently accessed pages client-side
  • Debounce requests: Avoid rapid-fire pagination requests
  • Loading states: Show loading indicators during fetch operations

📊 Use Cases

Common Implementation Scenarios

1. Invoice Dashboard

Copy to Clipboard

2. Financial Reports

Copy to Clipboard

3. Customer Portal

Copy to Clipboard

4. Bulk Operations

Copy to Clipboard

🔍 Filtering & Sorting Considerations

While this endpoint provides basic pagination, consider these future enhancements:

Potential Filter Parameters

  • Payment status filtering
  • Date range filtering
  • Customer/supplier filtering
  • Amount range filtering

Potential Sort Options

  • Sort by issue date
  • Sort by due date
  • Sort by amount
  • Sort by payment status

Note: Current endpoint provides basic pagination. Contact API team for advanced filtering requirements.

🔗 Related Endpoints

Invoice Operations

  • GET /invoices/ – Get specific invoice details
  • POST /invoices – Create new invoice
  • POST /invoices/bulk – Bulk invoice creation
  • POST /invoices/update-payment/ – Update payment status

Business Management

  • GET /businesses/ – Get business details
  • GET /businesses//statistics – Get business statistics
  • GET /businesses//reports – Generate business reports

📈 Response Time & Performance

Expected Performance

  • Typical response time: 200-800ms depending on page size
  • Large datasets: May take longer for businesses with many invoices
  • Concurrent requests: Multiple pagination requests are supported

Optimization Tips

  • Use appropriate page sizes for your use case
  • Implement client-side caching for frequently accessed pages
  • Consider using the summary data to avoid unnecessary full-page loads

This endpoint provides efficient access to invoice data with comprehensive pagination support, enabling businesses to manage large volumes of invoices effectively while maintaining optimal performance.

Request

Path Params

Parameter Type Required Example
stage string required
businessId string required

Header Params

Header Type Required Description Example
X-Business-Key string required (Required) X-Business-Key BK-26EDE24BAC50475FAACC5EA6339F0863-DEV-B2Z6QCEHI3X9
Content-Type string required – application/json
Accept string required – */*

Body Params

Field Type Required
page integer required
size integer required
invoicePaymentStatus string optional
dateFrom string optional
dateTo string optional

Response

Response Status

  • 200 OK

  • 201 Created

  • 401 Unauthorized

  • 403 Forbidden

  • 404 Not Found