> For the complete documentation index, see [llms.txt](https://vendex.gitbook.io/vendex-invoice/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vendex.gitbook.io/vendex-invoice/developers/openapi.md).

# Open API

Open REST APIs and pre‑built connectors for SAP, Oracle, QuickBooks, Xero, and other ERP/accounting systems, allowing seamless embedding of Vendex modules into existing enterprise workflows. 

### **API Overview**

#### **Base URLs:**

```
Sandbox: https://sandbox-api.getvendex.com/v1
Production: https://api.getvendex.com/v1
```

#### **Authentication:**

All API requests require authentication using API keys:

```http
Authorization: Bearer {YOUR_API_KEY}
```

**Obtaining API Keys:**

1. Navigate to **Settings** > **Security** > **API Keys**
2. Click **"+ Generate New Key"**
3. Provide key name
4. Set permissions level
5. Copy key (shown once only)
6. Store securely

**Request Format:**

* Content-Type: `application/json`
* Accept: `application/json`
* All dates in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`

**Response Format:**

```json
{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2024-12-08T15:30:00Z",
    "request_id": "req_abc123"
  }
}
```

**Error Format:**

```json
{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": {
      "field": "customer_email",
      "issue": "Invalid email format"
    }
  },
  "meta": {
    "timestamp": "2024-12-08T15:30:00Z",
    "request_id": "req_abc123"
  }
}
```

**Rate Limiting:**

| Plan       | Requests/Hour | Requests/Day |
| ---------- | ------------- | ------------ |
| Standard   | 1,000         | 10,000       |
| Premium    | 10,000        | 100,000      |
| Enterprise | Unlimited     | Unlimited    |

**Rate Limit Headers:**

```http
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9543
X-RateLimit-Reset: 1638360000
```

**API Resources**

**Core Resources:**

* **Invoices**: Create, retrieve, update, send invoices
* **Orders**: Manage order lifecycle
* **Customers**: Customer management
* **Products**: Product/service catalog
* **Payments**: Payment tracking and reconciliation
* **FIRS**: E-invoicing compliance operations

### **Invoices API**

#### **Create Invoice**

```http
POST /invoices
```

**Request Body:**

```json
{
  "customer_id": "cust_0987654321",
  "due_date": "2024-12-31",
  "invoice_title": "Monthly Services - December 2024",
  "invoice_description": "Consulting services rendered",
  "invoice_number": "INV-2024-001",
  "po_number": "PO-12345",
  "line_items": [
    {
      "item_id": "item_111222333",
      "description": "Consulting Services",
      "quantity": 40,
      "unit_price": 25000,
      "hsn_code": "9601",
      "product_category": "Professional Services"
    }
  ],
  "tax_rate": 7.5,
  "discount_amount": 10000,
  "notes": "Payment due within 30 days",
  "payment_collection": {
    "automated": true,
    "bank_account_id": "bank_acc_456"
  }
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "id": "inv_1234567890",
    "invoice_number": "INV-2024-001",
    "irn": "INV2024001-B4FA9D41-20241208",
    "status": "draft",
    "customer": {
      "id": "cust_0987654321",
      "name": "Oando Plc",
      "email": "procurement@oandoplc.com"
    },
    "issue_date": "2024-12-08",
    "due_date": "2024-12-31",
    "amounts": {
      "subtotal": 1000000,
      "tax": 75000,
      "discount": 10000,
      "total": 1065000,
      "currency": "NGN"
    },
    "firs_compliant": true,
    "created_at": "2024-12-08T15:30:00Z",
    "updated_at": "2024-12-08T15:30:00Z"
  }
}
```

#### **Retrieve Invoice**

```http
GET /invoices/{invoice_id}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "id": "inv_1234567890",
    "invoice_number": "INV-2024-001",
    "irn": "INV2024001-B4FA9D41-20241208",
    "status": "sent",
    "customer": {
      "id": "cust_0987654321",
      "name": "Oando Plc",
      "email": "procurement@oandoplc.com",
      "tin": "58207582-2537"
    },
    "line_items": [
      {
        "id": "line_item_123",
        "description": "Consulting Services",
        "quantity": 40,
        "unit_price": 25000,
        "amount": 1000000,
        "hsn_code": "9601"
      }
    ],
    "amounts": {
      "subtotal": 1000000,
      "tax": 75000,
      "discount": 10000,
      "total": 1065000,
      "amount_paid": 0,
      "balance_due": 1065000,
      "currency": "NGN"
    },
    "dates": {
      "issue_date": "2024-12-08",
      "due_date": "2024-12-31",
      "sent_at": "2024-12-08T16:00:00Z"
    },
    "firs": {
      "enabled": true,
      "irn": "INV2024001-B4FA9D41-20241208",
      "signed": true,
      "transmitted": true,
      "transmission_status": "acknowledged",
      "qr_code_url": "https://cdn.vendex.africa/qr/inv_1234567890.png"
    },
    "pdf_url": "https://cdn.vendex.africa/invoices/inv_1234567890.pdf",
    "created_at": "2024-12-08T15:30:00Z",
    "updated_at": "2024-12-08T16:00:00Z"
  }
}
```

#### **List Invoices**

```http
GET /invoices?status=pending&limit=20&offset=0
```

**Query Parameters:**

| Parameter     | Type    | Description                                             |
| ------------- | ------- | ------------------------------------------------------- |
| `status`      | string  | Filter by status: `draft`, `pending`, `paid`, `overdue` |
| `customer_id` | string  | Filter by customer ID                                   |
| `from_date`   | date    | Filter invoices issued after this date                  |
| `to_date`     | date    | Filter invoices issued before this date                 |
| `limit`       | integer | Number of results (max 100)                             |
| `offset`      | integer | Pagination offset                                       |

**Response:**

```json
{
  "success": true,
  "data": [
    {
      "id": "inv_1234567890",
      "invoice_number": "INV-2024-001",
      "customer_name": "Oando Plc",
      "total": 1065000,
      "status": "pending",
      "due_date": "2024-12-31"
    },
    ...
  ],
  "meta": {
    "total": 243,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
```

#### **Send Invoice**

```http
POST /invoices/{invoice_id}/send
```

**Request Body:**

```json
{
  "send_email": true,
  "email_subject": "Invoice from Vendex Platforms Ltd",
  "email_message": "Please find attached your invoice."
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "invoice_id": "inv_1234567890",
    "status": "sent",
    "sent_at": "2024-12-08T16:00:00Z",
    "email_delivered": true,
    "firs_transmitted": true
  }
}
```

#### **Record Payment**

```http
POST /invoices/{invoice_id}/payments
```

**Request Body:**

```json
{
  "amount": 1065000,
  "payment_date": "2024-12-15",
  "payment_method": "bank_transfer",
  "reference": "TXN-ABC123",
  "notes": "Payment received via bank transfer"
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "payment_id": "pay_789456123",
    "invoice_id": "inv_1234567890",
    "amount": 1065000,
    "payment_date": "2024-12-15",
    "status": "completed",
    "invoice_status": "paid"
  }
}
```

### **Customers API**

#### **Create Customer**

```http
POST /customers
```

**Request Body:**

```json
{
  "name": "Oando Plc",
  "email": "procurement@oandoplc.com",
  "phone": "+2348012345678",
  "tin": "58207582-2537",
  "business_description": "Oil and Gas Company",
  "address": {
    "street": "2 Ajose Adeogun Street",
    "city": "Lagos",
    "state": "Lagos",
    "postal_code": "101001",
    "country": "NG"
  },
  "access_point_id": "ap_vendor123"
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "id": "cust_0987654321",
    "name": "Oando Plc",
    "email": "procurement@oandoplc.com",
    "tin": "58207582-2537",
    "total_invoices": 0,
    "total_paid": 0,
    "outstanding_balance": 0,
    "risk_score": "low",
    "created_at": "2024-12-08T15:30:00Z"
  }
}
```

#### **Retrieve Customer**

```http
GET /customers/{customer_id}
```

**List Customers**

```http
GET /customers?limit=50&offset=0
```

### **Orders API**

#### **Create Order**

```http
POST /orders
```

**Request Body:**

```json
{
  "customer_id": "cust_0987654321",
  "title": "20T Gas Supply",
  "description": "Supply of 20 tonnes of natural gas",
  "status": "proposal_draft",
  "buyer_on_vendex": false,
  "documents": [
    {
      "type": "proposal",
      "name": "Technical Proposal",
      "url": "https://cdn.vendex.africa/docs/proposal_123.pdf"
    }
  ]
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "id": "ord_555666777",
    "order_number": "ORD-2024-001",
    "customer": {
      "id": "cust_0987654321",
      "name": "Oando Plc"
    },
    "status": "proposal_draft",
    "created_at": "2024-12-08T15:30:00Z"
  }
}
```

#### **Update Order Status**

```http
PATCH /orders/{order_id}
```

**Request Body:**

```json
{
  "status": "proposal_sent",
  "notes": "Proposal submitted to customer for review"
}
```

### **Products API**

#### **Create Product**

```http
POST /products
```

**Request Body:**

```json
{
  "name": "Consulting Services",
  "description": "Professional consulting services",
  "type": "service",
  "hsn_code": "9601",
  "product_category": "Professional Services",
  "unit_price": 25000,
  "tax_category": "standard"
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "id": "prod_111222333",
    "name": "Consulting Services",
    "hsn_code": "9601",
    "unit_price": 25000,
    "created_at": "2024-12-08T15:30:00Z"
  }
}
```

#### **List Products**

```http
GET /products
```

### **FIRS API**

#### **Validate IRN**

```http
POST /firs/validate-irn
```

**Request Body:**

```json
{
  "irn": "INV2024001-B4FA9D41-20241208"
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "irn": "INV2024001-B4FA9D41-20241208",
    "valid": true,
    "service_id": "B4FA9D41",
    "invoice_date": "2024-12-08"
  }
}
```

#### **Check Transmission Status**

```http
GET /firs/transmission/{irn}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "irn": "INV2024001-B4FA9D41-20241208",
    "status": "acknowledged",
    "transmitted_at": "2024-12-08T16:05:00Z",
    "acknowledged_at": "2024-12-08T16:05:23Z",
    "message": "Invoice successfully registered with FIRS"
  }
}
```

#### **Report Fiscalization**

```http
POST /firs/fiscalize
```

**Request Body:**

```json
{
  "irn": "INV2024001-B4FA9D41-20241208",
  "payment_date": "2024-12-15",
  "amount_paid": 1065000
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "irn": "INV2024001-B4FA9D41-20241208",
    "fiscalized": true,
    "fiscalized_at": "2024-12-15T10:30:00Z",
    "confirmation_number": "FISC-2024-12345"
  }
}
```

### **Error Codes**

| Code                    | HTTP Status | Description                                              |
| ----------------------- | ----------- | -------------------------------------------------------- |
| `invalid_request`       | 400         | Request is malformed or missing required fields          |
| `authentication_failed` | 401         | Invalid or missing API key                               |
| `permission_denied`     | 403         | API key lacks required permissions                       |
| `resource_not_found`    | 404         | Requested resource doesn't exist                         |
| `duplicate_resource`    | 409         | Resource already exists (e.g., duplicate invoice number) |
| `validation_error`      | 422         | Request data failed validation                           |
| `rate_limit_exceeded`   | 429         | Too many requests, retry after rate limit resets         |
| `server_error`          | 500         | Internal server error                                    |
| `service_unavailable`   | 503         | Temporary service outage                                 |

### **Testing and Sandbox**

#### **Sandbox Features**

* Separate from production data
* Test FIRS integration safely
* No actual invoice transmission
* Reset data anytime
* Same API endpoints and authentication

#### **Sandbox API Keys**

Generate sandbox keys separately:

1. Enable **"Test Mode"** toggle in Settings
2. Generate API key
3. Key works only with sandbox URL
4. Prefix: `sk_test_...`

#### **Production API Keys**

* Generate with test mode disabled
* Prefix: `sk_live_...`
* Only works with production URL

#### **Transitioning to Production**

1. Complete integration in sandbox
2. Obtain production FIRS credentials
3. Generate production API keys
4. Update API base URL to production
5. Run smoke tests
6. Monitor initial transactions closely