Viewing Invoices

API Documentation for Viewing Invoices with Filters and Paging

This document provides detailed instructions for developers to view invoices for a specific merchant using the provided API, with added functionality for filtering and paging.

Endpoint

• URL: /api/merchants/{merchantId}/invoices
• Method: GET
• Content-Type: application/json

Description

This API endpoint allows you to retrieve all invoices for a specific merchant, with options to filter results and paginate the response.

Request URL

Replace {merchantId} with the actual merchant ID.

https://api.paylink.sa/api/merchants/{merchantId}/invoices

HTTP Method

• GET

Request Headers

• Content-Type: application/json
• X-API-KEY: your_api_key

Query Parameters

• status (optional, string): Filter invoices by status. Example: ?status=paid
• startDate (optional, string): Filter invoices created after this date (inclusive), in YYYY-MM-DD format. Example: ?startDate=2024-01-01
• endDate (optional, string): Filter invoices created before this date (inclusive), in YYYY-MM-DD format. Example: ?endDate=2024-12-31
• customerPhone (optional, string): Filter invoices by customer phone or part of it.
• customerName (optional, string): Filter invoices by customer name or part of it.
• page (optional, integer): The page number for pagination. Example: ?page=1
• pageSize (optional, integer): The number of invoices per page. Example: ?pageSize=10

Example curl Command

curl -X GET 'https://api.paylink.sa/api/merchants/{merchantId}/invoices?status=paid&startDate=2024-01-01&endDate=2024-12-31&customerName=Hassan&customerPhone=56789&page=1&pageSize=10' \
-H "Content-Type: application/json" \
-H "X-API-KEY: your_api_key"

Replace {merchantId} with the actual merchant ID and your_api_key with your actual API key in the headers.

Success Response

If the request is successful, you will receive a 200 OK status code with the following response body:

{
  "invoices": [
    {
      "invoiceId": "unique_invoice_id_1",
      "merchantId": "merchant123",
      "invoiceNumber": "INV-1001",
      "date": "2024-07-10",
      "dueDate": "2024-07-31",
      "items": [
        {
          "description": "Web Development Services",
          "quantity": 1,
          "price": 5000
        },
        {
          "description": "Hosting Services",
          "quantity": 1,
          "price": 200
        }
      ],
      "totalAmount": 5200,
      "currency": "SAR",
      "customerInfo": {
        "customerName": "Customer XYZ",
        "customerPhone": "966123456789"
      },
      "invoicePaymentUrl": "http://yourpaymentgateway.com/invoice/unique_invoice_id",
      "status": "paid"
    }
    // Additional invoices
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 5,
    "totalItems": 50
  }
}

Error Response

If there is an error in the request, you will receive a 400 Bad Request status code with an error message:

{
  "message": "Invalid request data"
}

By following these steps and using the provided documentation, you should be able to successfully view invoices for a specific merchant with filtering and paging options using the API.