API v1

API Reference

Complete reference for all ExportReady-Battery API endpoints. All endpoints use JSON for request and response bodies.

Base URL

https://api.exportready.com/api/v1

All endpoints are relative to this base URL. For local development, use http://localhost:8080/api/v1

Authentication

Protected endpoints require a Bearer token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Access tokens expire after 15 minutes. Use the refresh token to obtain a new access token.

Authentication

User registration, login, and password management endpoints.

POST/auth/register

Request Body

{
  "company_name": "Acme Batteries",
  "email": "admin@acme.com",
  "password": "SecurePass123!"
}

Response

{
  "message": "Registration successful",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000"
}

POST/auth/login

Authenticate and receive access & refresh tokens.

Request Body

{
  "email": "admin@acme.com",
  "password": "SecurePass123!"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiI...",
  "refresh_token": "eyJhbGciOiJIUzI1NiI...",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "admin@acme.com",
  "company_name": "Acme Batteries",
  "expires_in": 900
}

POST/auth/refresh

Exchange a refresh token for a new access token.

Request Body

{
  "refresh_token": "eyJhbGciOiJIUzI1NiI..."
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiI...",
  "expires_in": 900
}

POST/auth/forgot-password

Initiate password reset by sending a reset email.

Request Body

{
  "email": "admin@acme.com"
}

Response

{
  "message": "Password reset email sent"
}

POST/auth/reset-password

Complete password reset with token from email.

Request Body

{
  "token": "reset_token_from_email",
  "new_password": "NewSecurePass456!"
}

Response

{
  "message": "Password reset successful"
}

GET/auth/me🔐 Auth Required

Get the current authenticated user's profile.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "company_name": "Acme Batteries",
  "email": "admin@acme.com",
  "address": "Industrial Area, Delhi",
  "epr_registration_number": "B-29016/2024-25/CPCB",
  "bis_r_number": "R-41001234",
  "created_at": "2026-01-15T10:00:00Z"
}

PUT/auth/profile🔐 Auth Required

Update the current user's profile and compliance fields.

Request Body

{
  "company_name": "Acme Batteries Inc.",
  "address": "Updated Address, Mumbai",
  "support_email": "support@acme.com",
  "website": "https://acme.com",
  "epr_registration_number": "B-29016/2024-25/CPCB",
  "bis_r_number": "R-41001234",
  "iec_code": "0504012345"
}

Response

{
  "message": "Profile updated successfully"
}

Batches

Create, manage, and export battery batches.

POST/batches🔐 Auth Required

Create a new battery batch with specifications.

Request Body

{
  "batch_name": "Q1-2026-Production",
  "market_region": "INDIA",
  "specs": {
    "chemistry": "Li-ion NMC",
    "voltage": "48V",
    "capacity": "100Ah",
    "manufacturer": "Acme Batteries",
    "weight": "45kg",
    "country_of_origin": "India"
  },
  "pli_compliant": true,
  "domestic_value_add": 65.5,
  "cell_source": "DOMESTIC"
}

Response

{
  "id": "batch-uuid-here",
  "batch_name": "Q1-2026-Production",
  "created_at": "2026-01-15T10:00:00Z"
}

GET/batches🔐 Auth Required

List all batches for the authenticated tenant with pagination.

Response

{
  "batches": [
    {
      "id": "batch-uuid-1",
      "batch_name": "Q1-2026-Production",
      "total_passports": 500,
      "market_region": "INDIA",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "total": 10,
  "page": 1,
  "per_page": 20
}

GET/batches/{id}🔐 Auth Required

Get detailed information about a specific batch.

Response

{
  "id": "batch-uuid-here",
  "batch_name": "Q1-2026-Production",
  "market_region": "INDIA",
  "specs": { ... },
  "pli_compliant": true,
  "domestic_value_add": 65.5,
  "total_passports": 500,
  "created_at": "2026-01-15T10:00:00Z"
}

POST/batches/{id}/upload🔐 Auth Required

Upload a CSV file with serial numbers to generate passports.

Request Body

Content-Type: multipart/form-data

file: [CSV file with serial_number,manufacture_date columns]

Response

{
  "message": "Successfully created 500 passports",
  "created": 500,
  "errors": []
}

GET/batches/{id}/download🔐 Auth Required

Download all QR codes for the batch as a ZIP file.

Response

Content-Type: application/zip
Content-Disposition: attachment; filename="batch-qrcodes.zip"

[Binary ZIP file containing PNG QR codes]

GET/batches/{id}/export🔐 Auth Required

Export all passports in the batch to a CSV file.

Response

Content-Type: text/csv

uuid,serial_number,manufacture_date,status,qr_url
uuid-1,BAT-001,2026-01-15,ACTIVE,https://example.com/p/uuid-1

GET/batches/{id}/passports🔐 Auth Required

List all passports in a batch with pagination.

Response

{
  "passports": [
    {
      "uuid": "passport-uuid",
      "serial_number": "BAT-001",
      "manufacture_date": "2026-01-15",
      "status": "ACTIVE"
    }
  ],
  "total": 500,
  "page": 1
}

Passports

Public passport data and scan tracking.

GET/p/{uuid}

Get public passport data. No authentication required.

Response

{
  "uuid": "passport-uuid",
  "serial_number": "BAT-2026-001",
  "manufacture_date": "2026-01-15",
  "status": "ACTIVE",
  "batch": {
    "batch_name": "Q1-2026-Production",
    "market_region": "INDIA",
    "specs": { ... },
    "pli_compliant": true,
    "domestic_value_add": 65.5
  },
  "tenant": {
    "company_name": "Acme Batteries",
    "address": "Industrial Area, Delhi",
    "epr_registration_number": "B-29016/2024-25/CPCB"
  }
}

POST/scan

Record a scan event for a passport. Called automatically when QR is scanned.

Request Body

{
  "passport_id": "passport-uuid"
}

Response

{
  "message": "Scan recorded"
}

GET/scan/feed🔐 Auth Required

Get real-time scan feed for the authenticated tenant.

Response

{
  "scans": [
    {
      "id": "scan-uuid",
      "passport_id": "passport-uuid",
      "serial_number": "BAT-001",
      "city": "Mumbai",
      "country": "India",
      "device_type": "Mobile",
      "scanned_at": "2026-01-15T14:30:00Z"
    }
  ]
}

Billing

Quota management and Razorpay payment integration.

GET/billing/packages

Get available quota packages for purchase.

Response

{
  "packages": [
    {
      "id": "starter",
      "name": "Starter",
      "quota": 100,
      "price": 999,
      "currency": "INR"
    },
    {
      "id": "professional",
      "name": "Professional",
      "quota": 500,
      "price": 3999,
      "currency": "INR"
    }
  ]
}

GET/billing/quota🔐 Auth Required

Get current quota balance for the authenticated tenant.

Response

{
  "quota_balance": 450,
  "quota_used": 50,
  "quota_limit": 500
}

POST/billing/razorpay/order🔐 Auth Required

Create a Razorpay order for quota purchase.

Request Body

{
  "package_id": "professional"
}

Response

{
  "order_id": "order_xyz123",
  "amount": 399900,
  "currency": "INR",
  "key_id": "rzp_test_xxx"
}

POST/billing/razorpay/verify🔐 Auth Required

Verify Razorpay payment and add quota.

Request Body

{
  "razorpay_order_id": "order_xyz123",
  "razorpay_payment_id": "pay_abc456",
  "razorpay_signature": "signature_here"
}

Response

{
  "message": "Payment verified, quota added",
  "new_balance": 950
}

Dashboard

Statistics and analytics endpoints.

GET/dashboard/stats🔐 Auth Required

Get dashboard statistics for the authenticated tenant.

Response

{
  "total_passports": 2500,
  "total_batches": 15,
  "quota_used": 2500,
  "quota_limit": 5000,
  "passports_this_week": 340,
  "pending_export_batches": 2,
  "carbon_compliance_pct": 85.5
}

GET/dashboard/recent-batches🔐 Auth Required

Get the most recent batches for quick access.

Response

{
  "batches": [
    {
      "id": "batch-uuid",
      "batch_name": "Q1-2026-Production",
      "total_passports": 500,
      "status": "ACTIVE",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

Passport Lifecycle

Track and manage passport status transitions with tamper-proof audit trail.

POST/passports/{uuid}/transition🔐 Auth Required

Apply a lifecycle action with automatic event logging.

Request Body

{
  "action": "SHIP",
  "evidence": {
    "shipment_reference": "IND123456789",
    "shipment_date": "2026-01-15"
  }
}

Response

{
  "success": true,
  "previous_status": "ACTIVE",
  "new_status": "SHIPPED",
  "action": "SHIP",
  "event_id": "event-uuid"
}

GET/passports/{uuid}/transitions🔐 Auth Required

Get allowed lifecycle actions for a passport.

Response

{
  "current_status": "SHIPPED",
  "allowed_actions": ["INSTALL", "RECALL"]
}

GET/passports/{uuid}/events🔐 Auth Required

Get audit trail with tamper-proof hash chain.

Response

{
  "events": [
    {
      "id": "event-uuid",
      "event_type": "STATUS_CHANGED",
      "action": "SHIP",
      "actor": "admin@acme.com",
      "actor_role": "LOGISTICS",
      "status_from": "ACTIVE",
      "status_to": "SHIPPED",
      "metadata": { "evidence": { "shipment_reference": "IND123456789" } },
      "hash": "sha256:abc123...",
      "previous_hash": "sha256:def456...",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

POST/passports/bulk/transition🔐 Auth Required

Bulk transition multiple passports.

Request Body

{
  "passport_ids": ["uuid-1", "uuid-2", "uuid-3"],
  "action": "SHIP",
  "evidence": {
    "shipment_reference": "BATCH-2026-001",
    "shipment_date": "2026-01-15"
  }
}

Response

{
  "total": 3,
  "succeeded": 3,
  "failed": 0,
  "failed_ids": [],
  "errors": []
}

Team Management

Invite team members and manage roles within your organization.

GET/team🔐 Auth Required

List all team members for the tenant.

Response

{
  "members": [
    {
      "id": "user-uuid",
      "email": "operator@acme.com",
      "role": "operator",
      "status": "active",
      "invited_at": "2026-01-10T10:00:00Z"
    }
  ]
}

POST/team/invite🔐 Auth Required

Invite a new team member via email.

Request Body

{
  "email": "newuser@acme.com",
  "role": "operator"
}

Response

{
  "message": "Invitation sent",
  "invite_id": "invite-uuid"
}

PUT/team/{id}/role🔐 Auth Required

Update a team member's role.

Request Body

{
  "role": "admin"
}

Response

{
  "message": "Role updated"
}

DELETE/team/{id}🔐 Auth Required

Remove a team member.

Response

{
  "message": "Team member removed"
}

Webhooks

Server-side webhook handlers for secure payment processing.

🔒 Secure Payment Processing

Webhooks use HMAC-SHA256 signature verification. Quota is ONLY added via webhook confirmation, not client-side verification.

POST/webhooks/razorpay

Razorpay payment webhook. Verifies signature and adds quota on payment.captured.

Request Body

Headers:
X-Razorpay-Signature: <HMAC-SHA256 signature>

Body:
{
  "event": "payment.captured",
  "payload": {
    "payment": {
      "entity": {
        "id": "pay_abc123",
        "order_id": "order_xyz789",
        "amount": 399900
      }
    }
  }
}

Response

{
  "status": "ok"
}

// Or on signature failure:
HTTP 401 Unauthorized

Error Responses

All error responses follow a consistent format:

{
  "error": "Error message describing what went wrong",
  "code": "ERROR_CODE"
}

400Bad Request - Invalid input data

401Unauthorized - Missing or invalid token

403Forbidden - Insufficient permissions

404Not Found - Resource does not exist

500Internal Server Error