diff --git a/docs/business.mdx b/docs/business.mdx new file mode 100644 index 0000000..b8b99f5 --- /dev/null +++ b/docs/business.mdx @@ -0,0 +1,99 @@ +# Business + +### Create New Business + + `/businesses` + +This endpoint allows you to create a new business entity under current business. +It returns created business details, including the `urlKey` for creating invoices in the future.
+Use the existing token with the new `urlKey` to create invoices for the new business entity. + + + + **Headers** + + | Name | Type | `Value` Description | + | ---------------- | ------ | ------------------- | + | Content-Type \* | string | `application-json` | + | Authorization \* | string | `Bearer ` | + + **Body** + + | Name | Type | `Value` Description | + | ----------------- | ------------- | ----------------------------------------------------------------------------------- | + | name \* | string | Name of the business | + | country \* | string | Country code (e.g., "IN" for India) | + | gstin | string | GST Identification Number | + | **billedTo** | object | Billing information | + | billedTo.name | string | Name for billing | + | billedTo.phone | string | Phone number | + | billedTo.email | string | Email address | + | billedTo.country | string | Country code | + | billedTo.gstState | string | GST state code | + | billedTo.pincode | string | Postal code | + | billedTo.city | string | City name | + | billedTo.street | string | Street address | + | billedTo.gstin | string | GST Identification Number | + | **auth** | object | Authentication information | + | auth.email \* | array[string] | List of users to add in the business | + + + + + :::success `200: OK` + Successful creation of a business entity. + + ```json # + { + "_id": "60cc8cc6aa3024abd4bef447", + "name": "Business Name", + "country": "IN", + "gstin": "29ABCDE1234F2Z5", + "urlKey": "business-url-key", + "country": "IN", + "currency": "IN", + "billedTo": { + "name": "Billing Name", + "phone": "+91 9876543210", + "email": "billing@example.com", + "country": "IN", + "gstState": "29", + "pincode": "560100", + "city": "Bangalore", + "street": "Street Address", + "gstin": "29ABCDE1234F2Z5" + }, + "users": [ + { + "name": "John Doe", + "email": "doejohn04@gmail.com", + "_id": "65ae751d8d476d33b879162d" + } + ], + "createdAt": "2024-08-18T12:08:38.000Z", + "updatedAt": "2024-08-18T12:08:38.000Z" + } + ``` + + ::: + + :::danger `401: Unauthorized` + Invalid authentication. + + ```json # + { + "name": "NotAuthenticated", + "message": "Invalid login", + "code": 401, + "className": "not-authenticated", + "data": { + "message": "Invalid login" + }, + "errors": {} + } + ``` + + ::: + + + diff --git a/docs/generate-einvoice.mdx b/docs/generate-einvoice.mdx new file mode 100644 index 0000000..0e66728 --- /dev/null +++ b/docs/generate-einvoice.mdx @@ -0,0 +1,94 @@ +# Generate IRN + +### Generation of E-Invoices (IRN) for Indian Business Invoices + +### Overview + +The Invoice Reference Number (IRN) is a unique identifier assigned to invoices, debit notes, and credit notes under the e-Invoicing system within the Goods and Services Tax (GST) framework. This system, facilitated by the Invoice Registration Portal (IRP), ensures streamlined, compliant, and secure invoicing for businesses. + + `/businesses/:urlKey/invoices/:invoice/irn` + +This endpoint allows you to generate IRN for an existing refrens invoice. + + + + **Path Params** + + `urlKey` - The unique identifier of the business.
+ `invoice` - The invoice ID for which the IRN is to be generated. + + **Query Params** + + | Name | Type | `Value` Description | + | -------------- | ------- | ----------------------------------------------- | + | includePaymentDetails | boolean | Set to `true` if you want to include the associated payments. | + + **Headers** + + | Name | Type | `Value` Description | + | ---------------- | ------ | ------------------- | + | Content-Type \* | string | `application-json` | + | Authorization \* | string | `Bearer ` | + + + + + :::success `200: OK` + The response will include the details of the e-invoice generated for the specified invoice. + + ```json + { + "AckNo": "182510010588566", + "AckDt": "2025-04-21 01:16:26", + "Irn": "b5abd0386b52bd2c30e014609ae6403c87576b01583f7cf1ef25370e7a14a92f", + "SignedInvoice": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjNCRTE3RTUxNDE5MjUyMjY0N0YwMUZEQkZGNTI3MUFENTI2OEQ3MzUiLCJ4NXQiOiJPLUYtVVVHU1VpWkg4Ql9iXzFKeHJWSm8xelUiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJOSUMgU2FuZGJveCIsImRhdGEiOiJ7XCJBY2tOb1wiOjE4MjUxMDAxMDU4ODU2NixcIkFja0R0XCI6XCIyMDI1LTA0LTIxIDAxOjE2OjI2XCIsXCJJcm5cIjpcImI1YWJkMDM4NmI1MmJkMmMzMGUwMTQ2MDlhZTY0MDNjODc1NzZiMDE1ODNmN2NmMWVmMjUzNzBlN2ExNGE5MmZcIixcIlZlcnNpb25cIjpcIjEuMVwiLFwiVHJhbkR0bHNcIjp7XCJUYXhTY2hcIjpcIkdTVFwiLFwiU3VwVHlwXCI6XCJCMkJcIixcIlJlZ1JldlwiOlwiTlwiLFwiSWdzdE9uSW50cmFcIjpcIk5cIn0sXCJEb2NEdGxzXCI6e1wiVHlwXCI6XCJJTlZcIixcIk5vXCI6XCJVRzAzMlwiLFwiRHRcIjpcIjE0LzA0LzIwMjVcIn0sXCJTZWxsZXJEdGxzXCI6e1wiR3N0aW5cIjpcIjE5QUFBUEkzMTgyTTAwN1wiLFwiTGdsTm1cIjpcIkhlbGxvRGl2ZS5jb21cIixcIkFkZHIxXCI6XCIjNzY1LCBIaWdoIFN0cmVldFwiLFwiTG9jXCI6XCJXZXN0IEJlbmdhbFwiLFwiUGluXCI6NzAwMDI1LFwiU3RjZFwiOlwiMTlcIixcIlBoXCI6XCI5ODE5NDY1MzY1XCIsXCJFbVwiOlwia2FydGlrXFx1MDAyQjEyQHJlZnJlbnMuY29tXCJ9LFwiQnV5ZXJEdGxzXCI6e1wiR3N0aW5cIjpcIjI5QUFJQ0EzOTE4SjFaRVwiLFwiTGdsTm1cIjpcIkNsaWVudCAyXCIsXCJQb3NcIjpcIjI5XCIsXCJBZGRyMVwiOlwiVGVzdFwiLFwiTG9jXCI6XCJLYXJuYXRha2FcIixcIlBpblwiOjU2MDEwMixcIlBoXCI6XCI5OTk5OTk5OTk5XCIsXCJFbVwiOlwiYmhhbnVzaGFsaW5pZGhpNDRAZ21haWwuY29tXCIsXCJTdGNkXCI6XCIyOVwifSxcIkl0ZW1MaXN0XCI6W3tcIkl0ZW1Ob1wiOjAsXCJTbE5vXCI6XCIxXCIsXCJJc1NlcnZjXCI6XCJOXCIsXCJQcmREZXNjXCI6XCJkc2Rhc2RcIixcIkhzbkNkXCI6XCI4NDE0XCIsXCJRdHlcIjoxOCxcIlVuaXRcIjpcIkRPWlwiLFwiVW5pdFByaWNlXCI6MTAsXCJUb3RBbXRcIjoxODAsXCJEaXNjb3VudFwiOjAsXCJQcmVUYXhWYWxcIjoxODAsXCJBc3NBbXRcIjoxODAsXCJHc3RSdFwiOjE4LFwiSWdzdEFtdFwiOjMyLjQsXCJDZ3N0QW10XCI6MCxcIlNnc3RBbXRcIjowLFwiQ2VzUnRcIjowLFwiQ2VzQW10XCI6MCxcIkNlc05vbkFkdmxBbXRcIjowLFwiU3RhdGVDZXNSdFwiOjAsXCJTdGF0ZUNlc0FtdFwiOjAsXCJTdGF0ZUNlc05vbkFkdmxBbXRcIjowLFwiT3RoQ2hyZ1wiOjAsXCJUb3RJdGVtVmFsXCI6MjEyLjR9LHtcIkl0ZW1Ob1wiOjAsXCJTbE5vXCI6XCIyXCIsXCJJc1NlcnZjXCI6XCJOXCIsXCJQcmREZXNjXCI6XCJkc2Rhc2RcIixcIkhzbkNkXCI6XCI4NDE0XCIsXCJRdHlcIjoxOCxcIlVuaXRcIjpcIk9USFwiLFwiVW5pdFByaWNlXCI6MTAsXCJUb3RBbXRcIjoxODAsXCJEaXNjb3VudFwiOjAsXCJQcmVUYXhWYWxcIjoxODAsXCJBc3NBbXRcIjoxODAsXCJHc3RSdFwiOjE4LFwiSWdzdEFtdFwiOjMyLjQsXCJDZ3N0QW10XCI6MCxcIlNnc3RBbXRcIjowLFwiQ2VzUnRcIjowLFwiQ2VzQW10XCI6MCxcIkNlc05vbkFkdmxBbXRcIjowLFwiU3RhdGVDZXNSdFwiOjAsXCJTdGF0ZUNlc0FtdFwiOjAsXCJTdGF0ZUNlc05vbkFkdmxBbXRcIjowLFwiT3RoQ2hyZ1wiOjAsXCJUb3RJdGVtVmFsXCI6MjEyLjR9XSxcIlZhbER0bHNcIjp7XCJBc3NWYWxcIjozNjAsXCJDZ3N0VmFsXCI6MCxcIlNnc3RWYWxcIjowLFwiSWdzdFZhbFwiOjY0LjgsXCJDZXNWYWxcIjowLFwiU3RDZXNWYWxcIjowLFwiRGlzY291bnRcIjowLFwiT3RoQ2hyZ1wiOjAsXCJSbmRPZmZBbXRcIjowLFwiVG90SW52VmFsXCI6NDI0Ljh9fSJ9.D5b0Fro8wxgWc24TWvdcuTymp61RB5-6WVCTT0eBHJZrxmqqO5WZ-5wY-6xWMDFhm1RKrTa-TTa4PFF7xMkPsshR7-1YUSaUb1Roc5T1O2Jr5kjzRPS6ZJLQzt3JHp_FdvA0Hu7wrB7N6o-Ugr5NorbJoE9ZAyBkE40R5WsAcK5d22eRW6cjOA8U7hc7hmpm--QKdAyvAjmyoBRqyIlda3rq4yO8xEuaCTO5bJXj2AIr3t_axepwsSp3R9jk6vbYI0sqzBsv4czUT_0kRysdjuXJ2oF3RXq9B-p4Z8YEYXaB8gHwNUQ-2BDI7FUjQ4VFCGHGv-De8I47YomsKETZrQ", + "SignedQRCode": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjNCRTE3RTUxNDE5MjUyMjY0N0YwMUZEQkZGNTI3MUFENTI2OEQ3MzUiLCJ4NXQiOiJPLUYtVVVHU1VpWkg4Ql9iXzFKeHJWSm8xelUiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJOSUMgU2FuZGJveCIsImRhdGEiOiJ7XCJTZWxsZXJHc3RpblwiOlwiMTlBQUFQSTMxODJNMDA3XCIsXCJCdXllckdzdGluXCI6XCIyOUFBSUNBMzkxOEoxWkVcIixcIkRvY05vXCI6XCJVRzAzMlwiLFwiRG9jVHlwXCI6XCJJTlZcIixcIkRvY0R0XCI6XCIxNC8wNC8yMDI1XCIsXCJUb3RJbnZWYWxcIjo0MjQuOCxcIkl0ZW1DbnRcIjoyLFwiTWFpbkhzbkNvZGVcIjpcIjg0MTRcIixcIklyblwiOlwiYjVhYmQwMzg2YjUyYmQyYzMwZTAxNDYwOWFlNjQwM2M4NzU3NmIwMTU4M2Y3Y2YxZWYyNTM3MGU3YTE0YTkyZlwiLFwiSXJuRHRcIjpcIjIwMjUtMDQtMjEgMDE6MTY6MjZcIn0ifQ.yQuP8IG5Qjc6juwfklMEQtMZkmKGgLPqIARnRWGye0Y-wV9BvBPXs6hfBFm_LcfLec0yrulnLuBbgTa67ngl0b-0CQkEPFy0EfqViVNQb7TtIPUSaIh4k0ewi9ff87R0PiaUqVbsPQdDPBVWb2o32rETzqcdddFeJ1idhBCYpwKqz__HNGE4i9CtMoPSXuip1GNRDyn7z-uT1-ayaeawjwGGSf8S9ADnGQxDFGvM6Jux20TqgPbiS91QwEfFXPP-_DXSp1UUp0bgDUXDUa8nWvGOCamn7OQdkk5geXtsomm0FFcH07T9lcGUzjeQ3QZ3YO14SxAnZq46sDpfBfiGZg", + "Status": "ACT", + "info": null, + "additionalInfo": null, + "alert": null, + "qr": "{\"SellerGstin\":\"19AAAPI3182M017\",\"BuyerGstin\":\"29AAICA3919L1ZE\",\"DocNo\":\"UG032\",\"DocTyp\":\"INV\",\"DocDt\":\"14/04/2025\",\"TotInvVal\":424.8,\"ItemCnt\":2,\"MainHsnCode\":\"8414\",\"Irn\":\"b5abd0386b52bd2c30e014609ae6403c87576b01583f7cf1ef25370e7a14a92f\",\"IrnDt\":\"2025-04-21 01:16:26\"}", + "invoiceNumber": "UG032", + "invoiceId": "67fcb537f811496b8721362b" + } + ``` + + ::: + + :::danger `401: Unauthorized` + Invalid authentication. + + ```json + { + "name": "NotAuthenticated", + "message": "Invalid login", + "code": 401, + "className": "not-authenticated", + "data": { + "message": "Invalid login" + }, + "errors": {} + } + ``` + ::: + + :::danger `400: Bad Request` + Error in generating IRN. + + ```json + { + "errorMessage": { + "details": [ + { + "ErrorCode": "2240", + "ErrorMessage": "For Sl. No 1, GST rate of tax is incorrect or not as notified" + } + ] + }, + "errorMessageDate": 1745178346990 + } + ``` + ::: + + + diff --git a/docs/invoices.mdx b/docs/invoices.mdx index 41dc789..82007c6 100644 --- a/docs/invoices.mdx +++ b/docs/invoices.mdx @@ -2,7 +2,7 @@ ### Create New Invoice - `/businesses/:urlKey/invoices` + `/businesses/:urlKey/invoices` This endpoint allows you to create an invoice @@ -173,6 +173,7 @@ This endpoint allows you to create an invoice ``` ::: + @@ -180,7 +181,7 @@ This endpoint allows you to create an invoice ### Find Invoices - `/businesses/:urlKey/invoices` + `/businesses/:urlKey/invoices` This endpoint allows you to find created invoices @@ -199,7 +200,7 @@ This endpoint allows you to find created invoices **Query Prams** - Optinal - Can be used for limiting results + Optional - Can be used for limiting results | Name | Type | `Value` Description | | -------------------- | ------ | --------------------------------------------------------- | @@ -209,6 +210,7 @@ This endpoint allows you to find created invoices | $sort[createdAt] | number | sort order on created date (1 ascending, -1 descending) | | $sort[invoiceNumber] | number | sort order on invoice number (1 ascending, -1 descending) | | $sort[invoiceDate] | number | sort order on invoice date (1 ascending, -1 descending) | + @@ -244,12 +246,12 @@ This endpoint allows you to find created invoices ``` ::: + ### Get Invoice - `/businesses/:urlKey/invoices/:invoiceId` This endpoint allows you to get a invoice via invoiceId (\_id) @@ -268,6 +270,7 @@ This endpoint allows you to get a invoice via invoiceId (\_id) | ---------------- | ------ | ------------------- | | Content-Type \* | string | `application-json` | | Authorization \* | string | `Bearer ` | + @@ -383,5 +386,104 @@ This endpoint allows you to get a invoice via invoiceId (\_id) ``` ::: + + + + +--- + +### Cancel Invoice + + `/businesses/:urlKey/invoices/:invoice?cancelPayment=true` + +This endpoint allows you to update an invoice for a specific business. + + + + **Path Params** + + `urlKey` - The unique identifier of the business.
+ `invoice` - The invoice ID for which the status is to be updated. + + **Query Params** + + | Name | Type | `Value` Description | + | -------------- | ------- | ----------------------------------------------- | + | cancelPayment | boolean | Set to `true` if you want to cancel the associated payments. | + + **Headers** + + | Name | Type | `Value` Description | + | ---------------- | ------ | ------------------- | + | Content-Type \* | string | `application-json` | + | Authorization \* | string | `Bearer ` | + + **Body** + + ```json + { + "status": "CANCELED" + } + ``` + + + + + :::success `200: OK` + Upon successful execution, the API responds with a status code of 200 and a JSON object containing the updated details of the invoice. + + ```json + { + "_id": "60cc8cc6aa3024abd4bef447", + "invoiceNumber": "APP-2020-0004", + "status": "CANCELED", + "currency": "INR", + "invoiceTitle": "Invoice", + "billType": "INVOICE", + "discount": { + "discountType": "PERCENTAGE" + }, + "items": [ + { + "name": "Item one name", + "rate": 100, + "quantity": 2, + "gstRate": 18, + "amount": 200, + "total": 236 + } + ], + "payments": [], + "finalTotal": { + "total": 0, + "amount": 0, + "subTotal": 0, + "igst": 0, + "cgst": 0, + "sgst": 0, + "discount": 0 + }, + "updatedAt": "2024-08-18T12:08:38.000Z" + } + ``` + ::: + + :::danger `401: Unauthorized` + Invalid authentication. + + ```json + { + "name": "NotAuthenticated", + "message": "Invalid login", + "code": 401, + "className": "not-authenticated", + "data": { + "message": "Invalid login" + }, + "errors": {} + } + ``` + ::: + diff --git a/docs/payment-updates.mdx b/docs/payment-updates.mdx new file mode 100644 index 0000000..a7fe46d --- /dev/null +++ b/docs/payment-updates.mdx @@ -0,0 +1,147 @@ +# Payment Updates in Invoices + +### Add Payment to Invoice + + `/businesses/:urlKey/invoices/:invoice/payments` + +This endpoint allows the you to add a payment to a specific invoice for a business. + + + + **Path Params** + + `urlKey` - will be provided by us
+ `invoice` - unique ID of the invoice. + + **Headers** + + | Name | Type | `Value` Description | + | ---------------- | ------ | ------------------- | + | Content-Type \* | string | `application-json` | + | Authorization \* | string | `Bearer ` | + + **Body** + + | Name | Type | `Value` Description | + | ----------------- | ------------- | ----------------------------------------------------------------------------------- | + | tds | number | The TDS (Tax Deducted at Source) amount for the payment. | + | transactionCharge | number | The transaction charge for the payment. | + | amount | number | The amount of the payment. | + | paymentDate | string | The date of the payment. | + | paymentMethod | string (enum) | The method used for the payment:
`ACCOUNT_TRANSFER` -> Account Transfer
`CASH` -> Cash
`CHEQUE` -> Cheque
`CREDIT_CARD` -> Credit Card
`DEBIT_CARD` -> Debit Card
`DD` -> Demand Draft
`UPI` -> UPI
. | + | notes | string | Any additional notes for the payment. | + | refId | string | Reference ID for the payment. | + + + + + :::success `201: Created` + Payment successfully added. + + ```json + { + "tds": 0, + "transactionCharge": 0, + "amount": 3000, + "paymentDate": "2024-08-18T12:08:38.000Z", + "paymentMethod": "CHEQUE", + "notes": "Payment for invoice #123", + "business": "60cc8cc6aa3024abd4bef997", + "payerBusiness": "60aa8hf6aa3024abd4bef447", + "isApproved": true, + "isRemoved": false, + "appId": "60cc8cc6aa3024abd4bej98k", + "_id": "60cc8cc6ps9024abd4bej98k" + } + ``` + ::: + + :::danger `401: Unauthorized` + Invalid authentication. + + ```json + { + "name": "NotAuthenticated", + "message": "Invalid login", + "code": 401, + "className": "not-authenticated", + "data": { + "message": "Invalid login" + }, + "errors": {} + } + ``` + ::: + + + + +--- + +### Get Payments on Invoice + + `/businesses/:urlKey/invoices/:invoice/payments` + +This endpoint retrieves the payments associated with a specific invoice for a business. + + + + **Path Params** + + `urlKey` - The unique identifier of the business.
+ `invoice` - The invoice ID for which the payments are being retrieved. + + **Headers** + + | Name | Type | `Value` Description | + | ---------------- | ------ | ------------------- | + | Content-Type \* | string | `application-json` | + | Authorization \* | string | `Bearer ` | + + + + + :::success `200: OK` + The response will include the details of the payments made towards the specified invoice. + + ```json + { + "payments": [ + { + "tds": 0, + "transactionCharge": 0, + "amount": 1000, + "paymentDate": "2023-10-01", + "paymentMethod": "CREDIT_CARD", + "notes": "Payment for invoice #123", + "business": "60cc8cc6aa3024abd4bef997", + "payerBusiness": "60aa8hf6aa3024abd4bef447", + "isApproved": true, + "isRemoved": false, + "appId": "60cc8cc6aa3024abd4bej98k", + "_id": "60cc8cc6ps9024abd4bej98k" + } + ] + } + ``` + ::: + + :::danger `401: Unauthorized` + Invalid authentication. + + ```json + { + "name": "NotAuthenticated", + "message": "Invalid login", + "code": 401, + "className": "not-authenticated", + "data": { + "message": "Invalid login" + }, + "errors": {} + } + ``` + ::: + + +