API Documentation - OINvoices | Developer Resources

Getting Started

The OINvoices API is a RESTful API that allows you to create, manage, and track invoices programmatically. All API requests should be made over HTTPS to https://api.oinvoices.com/v1/.

Base URL

https://api.oinvoices.com/v1/

Response Format

All responses are returned in JSON format with appropriate HTTP status codes.

Authentication

The OINvoices API uses API keys for authentication. You can find your API key in your account dashboard under Settings > API Keys.

API Key Authentication

Include your API key in the Authorization header of each request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.oinvoices.com/v1/invoices

Invoices

Create, retrieve, update, and manage invoices through the API.

POST /invoices

Create a new invoice

Request Body:

{
  "client_id": "client_123",
  "due_date": "2024-02-15",
  "currency": "USD",
  "line_items": [
    {
      "description": "Web Development",
      "quantity": 1,
      "rate": 1500.00
    }
  ],
  "notes": "Thank you for your business!"
}

Response:

{
  "id": "inv_abc123",
  "number": "INV-001",
  "status": "draft",
  "total": 1500.00,
  "created_at": "2024-01-15T10:30:00Z",
  "due_date": "2024-02-15",
  "client": {
    "id": "client_123",
    "name": "Acme Corporation"
  }
}

GET /invoices/{id}

Retrieve a specific invoice by ID

GET /invoices

List all invoices with optional filtering

Query Parameters:

status - Filter by status (draft, sent, paid, overdue)
client_id - Filter by client ID
limit - Number of results to return (default: 50)
offset - Pagination offset

Clients

Manage your client database through the API.

POST /clients

Create a new client

Request Body:

{
  "name": "Acme Corporation",
  "email": "billing@acme.com",
  "address": {
    "street": "123 Business St",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  }
}

Webhooks

Receive real-time notifications when events occur in your OINvoices account.

Supported Events

invoice.created - Invoice was created
invoice.sent - Invoice was sent to client
invoice.paid - Invoice was marked as paid
payment.received - Payment was received

Webhook Payload Example

{
  "event": "invoice.paid",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "invoice": {
      "id": "inv_abc123",
      "number": "INV-001",
      "status": "paid",
      "total": 1500.00
    }
  }
}

Error Codes

The OINvoices API uses standard HTTP response codes to indicate success or failure.

Code	Status	Description
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Something went wrong on our end

Rate Limits

API requests are rate limited to ensure fair usage and system stability.

Plan	Requests per minute	Requests per hour
Starter	60	1,000
Professional	120	5,000
Enterprise	300	15,000

SDKs and Libraries

Official SDKs and community libraries to help you integrate faster.

Node.js

Official JavaScript SDK

npm install oinvoices

Python

Official Python SDK

pip install oinvoices

PHP

Official PHP SDK

composer require oinvoices/php