B2G MBES API Documentation

This API allows for the integration of Enterprise Resource Planning (ERP) and accounting systems with the PIIS B2G MBES platform to generate, manage, and submit e-Invoices to the Federal Inland Revenue Service (FIRS) MBS system in compliance with Nigerian tax regulations.

The API facilitates real-time and batch processing of invoice data, IRN (Invoice Registration Number) issuance, and provides status updates.

All API requests must be authenticated using a multi-layered security approach.

Get Authentication Token

This is a server-to-server authentication flow. The API Key is provided during initial system provisioning.

// Request Headers
Content-Type: application/json
X-API-Key: your_provisioned_api_key

// Request Body
{
  "clientId": "your_client_id"
}

// Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Generate e-Invoice & IRN

This endpoint submits invoice data to the B2G MBES platform, which validates it, generates a compliant e-Invoice, submits it to the FIRS MBS, and returns the FIRS-generated IRN.

// Request Headers
Authorization: Bearer <your_access_token>
X-API-Key: your_provisioned_api_key
Content-Type: application/json

// Request Body
{
  "invoiceHeader": {
    "invoiceNumber": "INV-2025-001",
    "issueDate": "2025-11-18",
    "dueDate": "2025-12-18",
    "currency": "NGN",
    "taxAmount": 15000.00,
    "totalAmount": 115000.00
  },
  "seller": {
    "taxIdentificationNumber": "12345678-0001",
    "name": "Named Client Ltd.",
    "address": "123 Business Ave, Lagos"
  },
  "buyer": {
    "taxIdentificationNumber": "87654321-0001",
    "name": "Buyer Company Ltd.",
    "address": "456 Customer St, Abuja"
  },
  "lineItems": [
    {
      "description": "Software Development Services",
      "quantity": 1,
      "unitPrice": 100000.00,
      "taxAmount": 15000.00
    }
  ]
}

// Response (201 Created)
{
  "id": "einv_piis_abc123def456",
  "clientInvoiceId": "INV-2025-001",
  "firsIrn": "FIRSNG.IRN.20251118.ABC123XYZ",
  "status": "SUCCESS",
  "submittedAt": "2025-11-18T14:30:00Z",
  "qrCodeUrl": "https://api.piis-ng.com/qr/FIRSNG.IRN.20251118.ABC123XYZ"
}

Check System Status

Check the operational status of the B2G MBES API and its connection to the FIRS MBS.

// Response
{
  "status": "OPERATIONAL",
  "version": "1.0.0",
  "firsConnectivity": true,
  "lastChecked": "2025-11-18T16:45:10Z"
}

Sync Status (Webhook)

To ensure data consistency, the B2G MBES platform can send webhook notifications to a pre-configured endpoint in your ERP system for critical status updates.

// Webhook Payload Example
{
  "eventType": "EINVOICE_STATUS_UPDATED",
  "resourceId": "einv_piis_abc123def456",
  "timestamp": "2025-11-18T14:31:05Z",
  "data": {
    "newStatus": "SUCCESS",
    "firsIrn": "FIRSNG.IRN.20251118.ABC123XYZ"
  }
}

Standard HTTP status codes are used. In case of an error, the response body will contain details.

// Error Response Example (400 Bad Request)
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided invoice data failed validation.",
    "details": [
      "Buyer TIN is not in a valid format."
    ]
  }
}

Support Response Times