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:

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:

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

Error Format:

{
  "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:

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

POST /invoices

Request Body:

{
  "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:

{
  "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": "[e-mail]"
    },
    "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

GET /invoices/{invoice_id}

Response:

{
  "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": "[e-mail]",
      "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

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:

{
  "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

POST /invoices/{invoice_id}/send

Request Body:

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

Response:

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

Record Payment

POST /invoices/{invoice_id}/payments

Request Body:

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

Response:

{
  "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

POST /customers

Request Body:

{
  "name": "Oando Plc",
  "email": "[e-mail]",
  "phone": "[phone]",
  "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:

{
  "success": true,
  "data": {
    "id": "cust_0987654321",
    "name": "Oando Plc",
    "email": "[e-mail]",
    "tin": "58207582-2537",
    "total_invoices": 0,
    "total_paid": 0,
    "outstanding_balance": 0,
    "risk_score": "low",
    "created_at": "2024-12-08T15:30:00Z"
  }
}

Retrieve Customer

GET /customers/{customer_id}

List Customers

GET /customers?limit=50&offset=0

Orders API

Create Order

POST /orders

Request Body:

{
  "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:

{
  "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

PATCH /orders/{order_id}

Request Body:

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

Products API

Create Product

POST /products

Request Body:

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

Response:

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

List Products

GET /products

FIRS API

Validate IRN

POST /firs/validate-irn

Request Body:

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

Response:

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

Check Transmission Status

GET /firs/transmission/{irn}

Response:

{
  "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

POST /firs/fiscalize

Request Body:

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

Response:

{
  "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