API Documentation

1. Overview

The Invoicemonk API provides programmatic access to our compliance infrastructure, enabling ERP integrators, accounting software vendors, and enterprise IT teams to build integrations with audit-ready, immutable records management.

Access Requirement: API access is available exclusively to Business tier subscribers.

2. Authentication

2.1 Bearer Token Authentication

All API requests must include a valid bearer token in the Authorization header:

Authorization: Bearer <access_token>

2.2 Token Acquisition

Access tokens are obtained through Supabase Auth using JWT-based authentication. Tokens can be acquired via:

• Email/password authentication
• OAuth providers (if configured)
• Refresh token flow for session renewal

2.3 Security Requirements

• HTTPS required for all API requests
• Tokens should never be logged or transmitted insecurely
• Token rotation recommended every 90 days for service accounts
• Store tokens securely (never in source code)

3. Core Endpoints

3.1 Invoice Issuance

POST /functions/v1/issue-invoice

Issues a draft invoice, making it immutable and assigning a verification ID.

Request Body

{
  "invoice_id": "uuid"
}

Preconditions

• Invoice must be in draft status
• Business profile must be complete
• User email must be verified
• Monthly invoice limit not exceeded

Response

{
  "success": true,
  "invoice": {
    "id": "uuid",
    "invoice_number": "INV-001",
    "verification_id": "uuid",
    "issued_at": "2026-01-30T12:00:00Z",
    "invoice_hash": "sha256-hex-string"
  }
}

Compliance Behavior

• SHA-256 hash generated and stored
• Point-in-time snapshots captured (issuer, recipient, tax schema)
• Audit event logged: INVOICE_ISSUED
• Invoice becomes immutable

3.2 Invoice Verification

GET /functions/v1/verify-invoice?verification_id={uuid}

Public Access: This endpoint does not require authentication.

Tier Restriction: Verification only succeeds if the invoice issuer has Professional or Business tier.

Response

{
  "verified": true,
  "invoice": {
    "invoice_number": "INV-001",
    "issue_date": "2026-01-30",
    "issued_at": "2026-01-30T12:00:00Z",
    "issuer_name": "Business Name",
    "payment_status": "Issued - Awaiting Payment",
    "total_amount": 50000.00,
    "currency": "USD",
    "integrity_valid": true
  }
}

Integrity Check: integrity_valid confirms the invoice hash exists and has not been tampered with.

3.3 Payment Recording

POST /functions/v1/record-payment

Request Body

{
  "invoice_id": "uuid",
  "amount": 25000.00,
  "payment_method": "bank_transfer",
  "payment_reference": "TRF-123456",
  "payment_date": "2026-01-30",
  "notes": "First installment"
}

Validation

• Invoice must be in issued, sent, or viewed status
• Amount must be positive
• Payment recorded with retention_locked_until based on jurisdiction

Response

{
  "success": true,
  "payment": {
    "id": "uuid",
    "invoice_id": "uuid",
    "amount": 25000.00,
    "payment_date": "2026-01-30"
  },
  "invoice_status": "issued"
}

Auto-Status Update: If total payments equal invoice amount, status changes to paid.

3.4 Invoice Voiding

POST /functions/v1/void-invoice

Request Body

{
  "invoice_id": "uuid",
  "reason": "Customer requested cancellation due to order error"
}

Validation

• Reason must be at least 10 characters (audit requirement)
• Invoice must be in issued, sent, or viewed status
• Cannot void already paid, voided, or credited invoices

Response

{
  "success": true,
  "credit_note": {
    "id": "uuid",
    "credit_note_number": "CN-INV-001",
    "amount": 50000.00,
    "reason": "Customer requested cancellation",
    "issued_at": "2026-01-30T12:00:00Z"
  }
}

Compliance Behavior

• Original invoice is NOT deleted (immutable)
• Credit note created with SHA-256 hash
• Invoice status changed to voided
• Audit event logged: INVOICE_VOIDED

3.5 PDF Generation

POST /functions/v1/generate-pdf

Request Body

{
  "invoice_id": "uuid"
}

Tier Behavior

• Starter: Watermark applied
• Professional/Business: Clean PDF with optional branding

Response: Base64-encoded PDF or binary stream

3.6 Data Export

POST /functions/v1/export-records

Access: Professional and Business tiers only

Request Body

{
  "export_type": "invoices",
  "business_id": "uuid",
  "date_from": "2026-01-01",
  "date_to": "2026-01-31",
  "format": "csv"
}

Export Types: invoices, audit_logs, payments, clients

Response

{
  "success": true,
  "export_id": "uuid",
  "manifest_id": "uuid",
  "data": "csv-content-string",
  "filename": "invoices_export_2026-01-30.csv",
  "record_count": 45,
  "generated_at": "2026-01-30T12:00:00Z",
  "integrity_hash": "sha256-of-export-content"
}

Chain of Custody

• Export manifest created with actor, timestamp, scope
• Integrity hash generated for export content
• Audit event logged: DATA_EXPORTED

4. Audit & Compliance Behavior

4.1 Automatically Logged Events

Authentication

• USER_LOGIN
• USER_LOGOUT
• USER_SIGNUP
• EMAIL_VERIFIED
• PASSWORD_RESET

Invoice Lifecycle

• INVOICE_CREATED
• INVOICE_UPDATED
• INVOICE_ISSUED
• INVOICE_SENT
• INVOICE_VIEWED
• INVOICE_VOIDED
• INVOICE_CREDITED

Financial

• PAYMENT_RECORDED

Access Control

• TEAM_MEMBER_ADDED
• TEAM_MEMBER_REMOVED
• ROLE_CHANGED
• DATA_EXPORTED

4.2 Audit Log Structure

{
  "event_type": "INVOICE_ISSUED",
  "entity_type": "invoice",
  "entity_id": "uuid",
  "actor_id": "uuid",
  "actor_role": "owner",
  "timestamp_utc": "2026-01-30T12:00:00Z",
  "previous_state": { ... },
  "new_state": { ... },
  "metadata": { ... },
  "event_hash": "sha256-of-event"
}

4.3 Retention Policies

5. Rate Limiting and Usage Controls

5.1 Default Limits

• 100 requests per minute per user
• 1,000 requests per hour per user
• Bulk export operations limited to 10,000 records per request

5.2 Tier-Based Scaling

• Business tier: Higher rate limits available upon request
• Enterprise agreements: Custom rate limits negotiated separately

5.3 Abuse Prevention

• Repeated authentication failures may trigger temporary lockout
• Excessive failed requests logged for security review

6. Error Handling

6.1 Standard Error Response

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

6.2 HTTP Status Codes

6.3 Compliance-Safe Errors

• Error messages do not expose internal system details
• Validation errors provide guidance without revealing data structure

7. Versioning and Change Management

Current Version: v1  |  Format: /functions/v1/endpoint-name

7.1 Backward Compatibility

• Breaking changes will be introduced in new versions only
• Deprecated versions will be supported for minimum 12 months
• Deprecation notices published 6 months in advance

7.2 Change Notification

• API changes documented in release notes
• Enterprise customers notified via registered email
• Status page updated for any breaking changes

8. Security Considerations

8.1 Encryption

• All API traffic encrypted via HTTPS/TLS 1.2+
• Data encrypted at rest using infrastructure-level encryption

8.2 Access Logging

• All API requests logged with timestamp, user, and action
• Logs retained per jurisdiction retention policy

8.3 IP Restrictions

• IP whitelisting available for Enterprise tier
• Contact support to configure IP restrictions

8.4 Key Management

• API tokens should be stored securely (never in source code)
• Service accounts recommended for production integrations
• Token rotation every 90 days recommended

9. Access and Support

9.1 Requesting API Access

1. Upgrade to Business tier
2. Complete business profile with legal name and tax ID
3. Verify email address
4. Contact support for API key provisioning (if separate from auth tokens)

9.2 Review Process

• Business verification may be required for high-volume access
• Enterprise customers receive dedicated onboarding

9.3 Support Channels

• Standard: In-app messaging, email support
• Business tier: Priority email support
• Enterprise: Dedicated account manager, SLA-backed response times

9.4 Escalation

For urgent compliance or security matters, contact security@invoicemonk.com.