Confirm Received Invoice

Confirm Invoice Receipt API

Confirm the receipt of an invoice for tracking and status management purposes within the invoice lifecycle.

Quick Reference

API Details

Method Endpoint Authentication Required
GET https://api-dev.nairainvoice.com/dev/external/businesses/:businessId/confirmInvoiceReceipt/:irn Yes

Request Structure

Path Parameters

Parameter Type Required Description Example
businessId string ✅ Unique identifier of the business 26ede24b-ac50-475f-aacc-5ea6339f0863
irn string ✅ Invoice Reference Number to confirm receipt INV237-1070ECE8-20250826

Path Parameters

This endpoint does not require a request body. All parameters are passed in the URL path.

Response Format

Success Response (200)

Copy to Clipboard

Response Fields

Field Type Description
responseCode string Status code indicating operation result
responseMessage string Descriptive message about the operation

Status Codes

Success Codes

Code Description
00 Receipt confirmed successfully

Error Codes

Code Description
404 Invoice not found
400 Invalid parameters
403 Access denied
422 Invoice not eligible for receipt confirmation

Validation Rules

Path Parameter Validation

  • businessId must be a valid UUID format
  • irn must exist and belong to the specified business
  • Invoice must be in a state that allows receipt confirmation

Business Logic Validation

  • Invoice must have been sent to be eligible for receipt confirmation
  • User must have permission to confirm receipt for the business
  • Invoice must not already be confirmed as received
  • Invoice must not be cancelled or deleted

Error Responses

Common Error Scenarios

Error Code Message Description Solution
404 Invoice not found Invoice IRN doesn’t exist for the business Verify invoice IRN and business ID
403 Access denied User doesn’t have permission Check user permissions for the business
422 Receipt already confirmed Invoice receipt was previously confirmed Check invoice status before confirmation
422 Invoice not sent Invoice must be sent before receipt can be confirmed Ensure invoice has been sent

Example Error Response

Copy to Clipboard

Invoice Receipt Workflow

Typical Flow

  1. Invoice Created – Invoice is created in the system
  2. Invoice Sent – Invoice is sent to recipient
  3. Receipt Confirmation – This endpoint confirms invoice was received
  4. Payment Processing – Payment can be processed after confirmation

Status Transitions

From Status To Status Action
Sent Received Confirm receipt
Received Paid Process payment

📊 Use Cases

Common Scenarios

1. Customer Acknowledgment

Copy to Clipboard

2. Automated Systems

Copy to Clipboard

3. Audit Trail

Copy to Clipboard

4. Payment Processing

Copy to Clipboard

Security Considerations

Access Control

  • Verify user has permission to confirm receipt for the business
  • Ensure invoice belongs to the specified business
  • Log all receipt confirmations for audit purposes

Data Integrity

  • Prevent duplicate receipt confirmations
  • Maintain audit trail of confirmation timestamps
  • Validate invoice state before allowing confirmation

Related Endpoints

Invoice Management

  • GET /invoices/ – Get invoice details
  • POST /invoices/update-payment/ – Update payment status
  • GET /invoices//qrcode – Get invoice QR code

Invoice Tracking

  • POST /invoices//send – Send invoice
  • GET /invoices//status – Get invoice status
  • GET /invoices//history – Get invoice history

This endpoint provides essential receipt confirmation functionality for invoice tracking and status management, ensuring accurate delivery verification and supporting automated invoice processing workflows.

Request

Path Params

Parameter Type Required Example
stage string required
businessId string required
irn string required INV236-1070ECE8-20250826

Header Params

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

Response

Response Status

  • 200 OK

  • 201 Created

  • 401 Unauthorized

  • 403 Forbidden

  • 404 Not Found