ARMS IT Nigeria FIRS Compliant E-Invoicing Logo

API Documentation

Integrate ARMS IT e-invoicing solution with your systems using our RESTful API

Table of Contents

Authentication

All API requests require authentication using an API key. Include your API key in the request header.

Header Name:

X-API-KEY

Example Request

curl -X GET https://api.example.com/v1/invoices \
  -H "X-API-KEY: your-api-key-here"

⚠️ Security Note: Keep your API key secure and never expose it in client-side code or public repositories. If your API key is compromised, contact support immediately to regenerate it.

Base URL

All API endpoints are relative to the base URL:

https://api.armsit.ng/v1

Note: Replace api.armsit.ng with your actual API endpoint URL.

Invoices

GET/invoices

Retrieve a list of invoices. Supports pagination and filtering.

Query Parameters

ParameterTypeDescription
pageintegerPage number (default: 1)
pageSizeintegerItems per page (default: 20, max: 100)
statusstringFilter by status (Draft, ReadyForClearance, Cleared)
customerIdstring (UUID)Filter by customer ID

Example Request

GET /v1/invoices?page=1&pageSize=20&status=Draft
Headers:
  X-API-KEY: your-api-key-here

Example Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "invoiceNumber": "INV-2025-001",
      "issueDate": "2025-01-15T00:00:00Z",
      "status": "Draft",
      "customer": {
        "id": "660e8400-e29b-41d4-a716-446655440000",
        "name": "Acme Corporation"
      },
      "taxExclusiveAmount": 100000.00,
      "taxInclusiveAmount": 107500.00,
      "payableAmount": 107500.00,
      "currency": "NGN"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 45,
  "totalPages": 3
}
POST/invoices

Create a new invoice. The invoice will be created in Draft status.

Request Body

{
  "invoiceNumber": "INV-2025-001",
  "issueDate": "2025-01-15",
  "invoiceTypeCode": "380",
  "customerId": "660e8400-e29b-41d4-a716-446655440000",
  "note": "Optional invoice note",
  "items": [
    {
      "productId": "770e8400-e29b-41d4-a716-446655440000",
      "description": "Product description",
      "quantity": 10,
      "unitCode": "C62",
      "unitPrice": 10000.00,
      "taxCategoryCode": "S"
    }
  ]
}

Field Descriptions

FieldTypeRequiredDescription
invoiceNumberstringYesUnique invoice number
issueDatedate (YYYY-MM-DD)YesInvoice issue date
invoiceTypeCodestringYes380 (Standard) or 381 (Credit Note)
customerIdstring (UUID)YesCustomer ID
notestringNoOptional invoice note
itemsarrayYesArray of invoice items (minimum 1)

Customers

GET/customers

Retrieve a list of customers. Supports pagination and search.

Query Parameters

ParameterTypeDescription
pageintegerPage number (default: 1)
pageSizeintegerItems per page (default: 20, max: 100)
searchstringSearch by name, email, or TIN
POST/customers

Create a new customer.

Request Body

{
  "name": "Acme Corporation",
  "tin": "12345678-0001",
  "email": "contact@acme.com",
  "phone": "+2348012345678",
  "street": "123 Business Street",
  "city": "Lagos",
  "state": "Lagos",
  "country": "NG",
  "postalCode": "100001"
}
PUT/customers/{id}

Update an existing customer. Include only the fields you want to update.

DELETE/customers/{id}

Delete a customer. Customers with existing invoices will be soft-deleted.

Products

GET/products

Retrieve a list of products. Supports pagination and search.

POST/products

Create a new product.

Request Body

{
  "name": "Product Name",
  "description": "Product description",
  "hsCode": "1234.56.78",
  "sku": "PROD-001",
  "unitPrice": 10000.00,
  "unitCode": "C62",
  "taxCategoryCode": "S"
}
PUT/products/{id}

Update an existing product. Include only the fields you want to update.

DELETE/products/{id}

Delete (deactivate) a product. Products are soft-deleted and can be reactivated.

Error Handling

The API uses standard HTTP status codes to indicate success or failure. Error responses follow a consistent format.

HTTP Status Codes

CodeDescription
200OK - Request successful
201Created - Resource created successfully
204No Content - Request successful, no response body
400Bad Request - Invalid request data
401Unauthorized - Missing or invalid API key
404Not Found - Resource not found
422Unprocessable Entity - Validation errors
500Internal Server Error - Server error

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more validation errors occurred",
    "details": {
      "invoiceNumber": ["Invoice number is required"],
      "customerId": ["Customer ID must be a valid UUID"]
    },
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Need Help?

For API support, integration assistance, or to request your API key, please contact our support team.

Contact SupportEmail Us