{ "openapi": "3.1.0", "info": { "title": "FiniiAPI", "version": "1.0.0", "description": "FiniiOne inventory, invoicing, collections and accounting connectors." }, "servers": [ { "url": "https://finiione.lovable.app/api/public/v1" } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } } }, "security": [ { "bearer": [] } ], "paths": { "/inventory": { "get": { "summary": "List stock", "description": "Paginated stock with specs. status = available | reserved | sold. Also filters brand/grade/search.\n\nScope: inventory:read. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } }, "post": { "summary": "Stock entry", "description": "Add one device, or send { items: [...] } for up to 100 at once. IMEI must be unique in active stock.\n\nScope: inventory:write. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "requestBody": { "content": { "application/json": { "example": { "device": "iPhone 13 128GB", "product_type": "Mobile", "imei": "356789012345678", "grade": "A", "purchase_price": 32000, "repair_cost": 1500, "suggested_sale_price": 38999, "vendor_name": "ABC Traders", "invoice_number": "PB-101", "attributes": { "RAM": "4GB", "Storage": "128GB", "Colour": "Blue", "Battery": "89%" } } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/inventory/changes": { "get": { "summary": "Changes since", "description": "Devices added, reserved or sold after the given time — poll every minute to keep your store in sync.\n\nScope: inventory:read. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/inventory/{id}": { "get": { "summary": "Get one device", "description": "One device by item id, IMEI or barcode, including any active reservation.\n\nScope: inventory:read. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/inventory/{id}/reserve": { "post": { "summary": "Reserve device", "description": "Atomic hold (1–60 minutes, default 15). Returns 409 if already reserved or sold.\n\nScope: reserve:manage. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "example": { "customer_ref": "cart_8812", "hold_minutes": 15 } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } }, "delete": { "summary": "Release hold", "description": "Puts the device back on sale immediately (cart abandoned).\n\nScope: reserve:manage. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/inventory/{id}/reserve/confirm": { "post": { "summary": "Confirm hold", "description": "Extends the hold to 24 hours once the customer is paying.\n\nScope: reserve:manage. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "example": { "customer_ref": "cart_8812" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/invoices": { "post": { "summary": "Raise invoice", "description": "Creates a tax invoice in your official series. Margin scheme (Rule 32(5)) by default; tax_mode 'regular' charges GST on full price.\n\nScope: invoice:create. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "requestBody": { "content": { "application/json": { "example": { "item_ids": [ "" ], "sale_prices": [ 38999 ], "customer": { "name": "Rahul Sharma", "phone": "9876543210", "state": "Delhi", "gstin": "", "address": "" }, "tax_mode": "margin", "invoice_date": "2026-10-03" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } }, "get": { "summary": "List invoices", "description": "Invoice number, date, buyer, total, balance due and payment status.\n\nScope: inventory:read. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/invoices/{id}": { "get": { "summary": "Get invoice", "description": "Invoice details with line items, IMEI, tax totals, balance and credit notes.\n\nScope: inventory:read. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/invoices/{id}/cancel": { "post": { "summary": "Cancel invoice", "description": "Cancels an unpaid invoice with no credit notes; its devices go straight back to stock. Otherwise use a credit note.\n\nScope: invoice:create. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "example": { "reason": "Raised in error" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/credit-notes": { "post": { "summary": "Credit note (return)", "description": "GST credit note for returned devices against the original invoice; restock=true puts them back in stock. GET lists credit notes.\n\nScope: invoice:create. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "requestBody": { "content": { "application/json": { "example": { "invoice_id": "", "item_ids": [ "" ], "reason": "Customer return", "restock": true } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/invoices/{id}/payments": { "post": { "summary": "Collection mapping", "description": "Records money received against an invoice and updates Paid / Partially Paid.\n\nScope: payment:create. Category: recommerce_core_api.", "tags": [ "recommerce_core_api" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "example": { "amount": 38999, "mode": "UPI", "reference": "pay_Nx81Q", "paid_on": "2026-10-03", "notes": "Razorpay" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/integrations/zoho/invoices": { "get": { "summary": "Zoho Books invoices", "description": "Invoices in Zoho Books invoice format (customer, line items, HSN, tax) ready to post to Zoho's API.\n\nScope: integrations:read. Category: zoho_connect.", "tags": [ "zoho_connect" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/integrations/tally/export": { "get": { "summary": "Tally XML vouchers", "description": "TallyPrime XML (Sales + Receipt vouchers). Import in Tally: Import → Vouchers.\n\nScope: integrations:read. Category: tally_connect.", "tags": [ "tally_connect" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/integrations/ai/tools": { "get": { "summary": "AI tool schema", "description": "Function-calling definitions for ChatGPT Actions and Claude tools.\n\nScope: integrations:read. Category: ai_agent_mcp.", "tags": [ "ai_agent_mcp" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/integrations/ai/query": { "post": { "summary": "Business summary", "description": "Read-only figures for AI agents: topic = summary | stock | sales | receivables.\n\nScope: integrations:read. Category: ai_agent_mcp.", "tags": [ "ai_agent_mcp" ], "requestBody": { "content": { "application/json": { "example": { "topic": "summary" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/verify/checks": { "get": { "summary": "List KYC checks", "description": "Every FiniiVerify check with its required fields and credit cost: gst, gst_by_pan, pan, cin, udyam, din, bank, contact, address, iec.\n\nScope: kyc:verify. Category: finii_verify.", "tags": [ "finii_verify" ], "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } }, "/verify/{check}": { "post": { "summary": "Run KYC check", "description": "Verifies a business or person: GST, PAN, CIN, Udyam, DIN, bank account, phone/email, address or IEC. Body carries the check's fields (see GET /v1/verify/checks). Sandbox keys return a demo result.\n\nScope: kyc:verify. Category: finii_verify.", "tags": [ "finii_verify" ], "requestBody": { "content": { "application/json": { "example": { "gstin": "22AAAAA0000A1Z5", "fy": "2024-25" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Invalid key" }, "402": { "description": "Subscription required" }, "403": { "description": "Missing scope" }, "409": { "description": "Conflict" }, "422": { "description": "Validation error" }, "429": { "description": "Rate limited" } } } } } }