Developer API Integration

Welcome to the BillKaro API documentation. This guide provides the necessary information for any application or service to integrate with BillKaro for seamless client management, invoice generation, and PDF rendering.

Hybrid API Architecture

  • Supabase REST API (PostgREST)Used for core CRUD operations on data models (clients, invoices, profiles). Extremely fast and secure with RLS.
  • Next.js Custom API RoutesUsed for specialized server-side operations (e.g., generating highly-styled PDFs, secure selective deletions).

Authentication

All API requests require authentication via Supabase Auth. App integrations must authenticate a user and include the JWT token in the Authorization header.

Header Format
Authorization: Bearer <YOUR_SUPABASE_JWT_TOKEN>
apikey: sb_publishable_urR7gDDm6thuyFKKz2OJJA_37FXfZvG

Get an Access Token

While the UI uses Google OAuth, programmatic access requires standard Email/Password authentication. First, POST to /api/auth/register with email and password to create an account. Then, POST your credentials to /api/auth/login to receive a Session containing an access_token.

Endpoint:/api/auth/login
Headers:
Content-Type: application/json
Request Body (JSON)
{
  "email": "developer@company.com",
  "password": "secure-password-here"
}

Note for Future Integrations:In the future, server-to-server API keys may be supported for dedicated application integrations without the need for user-level JWTs.

1. Clients API (Supabase REST)

Manage customer and client records. Clients must be created before associating them with invoices.

Manage Profile Settings

Before creating clients and invoices, configure your invoice details and sequence format securely entirely through the backend API.

Endpoint:/api/profile
Headers:
Authorization: Bearer <token>Content-Type: application/json

GET Request: Returns your current profile settings.

PUT Request: Update the settings using a JSON body (e.g., {"business_name": "Acme Corp", "state": "Maharashtra"}).

POST

Create a Client

Creates a new client record to which invoices can be associated.

Endpoint:https://qsubqcddcwwfjfioownb.supabase.co/rest/v1/clients
Headers:
AuthorizationapikeyContent-Type: application/jsonPrefer: return=representation
Request Body (JSON)
{
  "user_id": "uuid-of-authenticated-user",
  "client_name": "Acme Corp",
  "client_gstin": "27AADCB2230M1Z2",
  "client_state": "Maharashtra",
  "client_address": "123 Business Rd, Mumbai",
  "client_email": "billing@acmecorp.com"
}

Response (201 Created): Returns the created client object including the generated id (UUID).

GET

Get Clients

Retrieve a list of clients for the authenticated user.

Endpoint:https://qsubqcddcwwfjfioownb.supabase.co/rest/v1/clients?user_id=eq.<user_id>
Headers:
Authorizationapikey

2. Invoices API

Create, update, and manage invoices throughout their lifecycle.

POST

Create an Invoice (Draft)

Creates a new invoice record in the database. Initially, invoices should always be created with a draft status.

Endpoint:/api/invoices
Headers:
Authorization: Bearer <token>Content-Type: application/json
Request Body (JSON)
{
  "client_id": "uuid-of-client",
  "invoice_date": "2023-10-25",
  "place_of_supply": "Maharashtra",
  "line_items": [
    {
      "description": "App Software License",
      "service_category": "Software",
      "hsn_sac_code": "998331",
      "quantity": 1,
      "rate": 5000,
      "tax_rate": 18,
      "amount": 5000
    }
  ]
}

Response (201 Created): Returns the created invoice object with the generated id (UUID).

PATCH

Update an Invoice

Update an existing invoice. Note: This is only allowed if the invoice status is not 'generated'.

Endpoint:/api/invoices/:id (Next.js Route)
Headers:
Authorization: Bearer <token>
Body:Any updatable fields (e.g., line_items, total, status)
Response:
  • 200 OK: Returns the updated invoice object.
  • 409 Conflict: Returned if attempting to modify an invoice that is already generated.
DELETE

Delete an Invoice

Securely delete a draft invoice.

Endpoint:/api/invoices/:id (Next.js Route)
Headers:
Authorization: Bearer <token>
Response:
  • 200 OK: { "ok": true }
  • 409 Conflict: Generated invoices cannot be deleted to preserve audit logs.

3. PDF Generation & Retrieval

Once an invoice is drafted, you can call the generation API to lock the invoice and render a formal PDF document.

POST

Generate PDF

Generates a PDF for the specified invoice, securely uploads it to Supabase storage, and updates the invoice status to generated.

Endpoint:/api/invoices/:id/generate-pdf
Headers:
Authorization: Bearer <token>
Response (200 OK)
{
  "success": true,
  "pdf_url": "https://<supabase-id>.supabase.co/storage/v1/object/public/invoices/user-id/invoice_INV-2023-001.pdf",
  "status": "generated",
  "message": "PDF generated successfully"
}
GET

Download PDF

Endpoint specifically handling the forced download headers for a given invoice (if applicable).

Endpoint:/api/invoices/download/:id
Headers:
Authorization: Bearer <token>
Response:

Returns the binary PDF stream directly to the client.

Best Practices for API Integrations

1

Client Resolution

Before creating an invoice, check if the client_gstin or client_name already exists in the clients table to avoid duplication. Use the existing client_id if found.

2

Tax Calculations

The integrating app should calculate cgst_amount, sgst_amount, igst_amount, and total before sending the payload to BillKaro. Ensure mathematically precise values are sent.

3

Idempotency

Invoice creation relies on UNIQUE(user_id, invoice_number). Attempting to create two invoices with the same invoice_number for the same user will fail safely.

4

State Machine

Invoices start as draft. Once /generate-pdf is called successfully, they move to generated and become read-only. Further edits or deletions are blocked by the Next.js API routes to maintain audit compliance.