API v1 - CAFECA-IO/iSunFA GitHub Wiki

*## API code API code example : A011001

The initial letter 'A' indicates that the API is located in a folder whose name begins with 'A'. Following this, the first two digits '01' specify the API's position in a sequence of folders, suggesting that it is the first folder starting with 'A'. The third digit '1' denotes the API's position within a subsequence of folders inside the initial folder starting with 'A', indicating it is in the first subfolder. Lastly, the final three digits '001' represent the API's sequence number within the subfolder, meaning it is the first API listed there.

API list

BaseUrl: `/api/v1`

除 A010001, C070001, S040001, S050001, S060001 API不驗證登入, 其餘API皆會驗證登入

A010001 - GET /audit_report - iSunFA-Landing-page-Animation10 [不需驗證登入]
A020001 - GET /company/:companyId/account - ISFMK00040, ISFMK00031
A020002 - GET /company/:companyId/account/:accountId
A020003 - POST /company/:companyId/account - ISFMK00040左邊
A020004 - PUT /company/:companyId/account/:accountId - ISFMK00031下面
A021005 - DELETE /company/:companyId/account/:accountId - ISFMK00040左邊
A040001 - POST /company/:companyId/asset - ISFMK00052
A040002 - GET /company/:companyId/asset - ISFMK00052
A041001 - GET /company/:companyId/asset/:assetId - ISFMK00052
A041002 - PUT /company/:companyId/asset/:assetId - ISFMK00052
A050001 - GET /company/:companyId/ask_ai/:resultId/status?aiApi= - ISFMK00052
A050002 - GET /company/:companyId/ask_ai/:resultId?aiApi= - ISFMK00052
A060001 - GET /company/:companyId/admin - ISFMK00005
A060002 - GET /company/:companyId/admin/:adminId - ISFMK00005, ISFMK00063
A060003 - PUT /company/:companyId/admin/:adminId - ISFMK00063
A060004 - DELETE /company/:companyId/admin/:adminId - ISFMK00063
A060005 - PUT /company/:companyId/transfer_owner - ISFMK0069
C010001 - GET /company/:companyId/client - ISFMK00032
C010002 - POST /company/:companyId/client - ISFMK00032
C011001 - GET /company/:companyId/client/:clientId - ISFMK00032
C011002 - PUT /company/:companyId/client/:clientId - ISFMK00032
C011003 - DELETE /company/:companyId/client/:clientId - ISFMK00032
C030001 - GET /company/:companyId/contract - ISFMK00003
C030002 - POST /company/:companyId/contract - ISFMK00011
C031001 - GET /company/:companyId/contract/:contractId-ISFMK0008
C031002 - PUT /company/:companyId/contract/:contractId - ISFMK00011
C040001 - GET /company - ISFMK00004
C040002 - POST /company - ISFMK00004
C041001 - GET /company/:companyId - ISFMK00069
C041002 - PUT /company/:companyId - ISFMK00069
C041003 - DELETE /company/:companyId - ISFMK00069
C042001 - PUT /company/:companyId/select - ISFMK00004
C070001 - GET /challenge - ISFMK00001 [不需驗證登入]
D010001 - GET /company/:companyId/department - ISFMK00041
E010001 - GET /company/:companyId/employee - ISFMK00041
E010002 - POST /company/:companyId/employee - ISFMK00041
E011001 - GET /company/:companyId/employee/:employeeId - ISFMK00041, ISFMK00064
E011002 - DELETE /company/:companyId/employee/:employeeId - ISFMK00041, ISFMK00064
E011003 - PUT /company/:companyId/employee/:employeeId - ISFMK00064
F010001 - POST /company/:companyId/file - ISFMK00004, ISFMK00058, ISFMK00061右邊
F011001 - GET /company/:companyId/file/:fileId - ISFMK00058
F011002 - DELETE /company/:companyId/file/:fileId - ISFMK00058
I010001 - POST /company/:companyId/invoice - ISFMK00034
I011001 - GET /company/:companyId/invoice/:invoiceId - 這支沒用到備用(ISFMK00050)
I011002 - PUT /company/:companyId/invoice/:invoiceId
I011003 - GET /company/:companyId/image/[imageId] - ISFMK00015, ISFMK00024
I020001 - GET /company/:companyId/income_expense_trend - ISFMK00006 右上角
I030001 - POST /company/:companyId/invitation - ISFMK00005
J010001 - GET /company/:companyId/journal - ISFMK00038
J011001 - GET /company/:companyId/journal/:journalId - ISFMK00015 ISFMK00024
J011002 - DELETE /company/:companyId/journal/:journalId - ISFMK00025
K010001 - POST /company/:companyId/kyc
L020001 - GET /company/:companyId/labor_cost_chart - ISFMK00006 左中
O011001 - POST /company/:companyId/ocr
O011003 - GET /company/:companyId/ocr
O011004 - DELETE /company/:companyId/ocr/:resultId
O020001 - GET /company/:companyId/order
O020002 - POST /company/:companyId/order
P020001 - GET /company/:companyId/project - ISFMK00017
P020002 - POST /company/:companyId/project
P021001 - GET /company/:companyId/project/:projectId - ISFMK00033, ISFMK00006
P021002 - PUT /company/:companyId/project/:projectId - ISFMK00061
P024001 - GET /company/:companyId/project/:projectId/milestone - ISFMK00033
P024002 - PUT /company/:companyId/project/:projectId/milestone - ISFMK00033, ISFMK00061
P025001 - GET /company/:companyId/project/:projectId/progress - ISFMK00033
P026001 - GET /company/:companyId/project/:projectId/sale - ISFMK00033
P027001 - GET /company/:companyId/project/:projectId/value - ISFMK00033
P028001 - GET /company/:companyId/project/:projectId/work_rate - ISFMK00033
P040001 - GET /company/:companyId/profit_comparison - ISFMK00006 右下角
P050001 - GET /company/:companyId/project_progress - ISFMK00006 右上角
P070001 - GET /company/:companyId/profit_insight - ISFMK00006 左上角橘框
P080001 - GET /company/:companyId/payment?orderId=
P080002 - POST /company/:companyId/payment
R010001 - POST /company/:companyId/report
R010002 - GET /company/:companyId/report - ISFMK00066
R011001 - GET /company/:companyId/report/:reportId - ISFMK00066
R040001 - GET /company/:companyId/role - ISFMK00031, ISFMK00040
R040002 - POST /company/:companyId/role - ISFMK00040
R041001 - GET /company/:companyId/role/:roleId - ISFMK00031, ISFMK00040
R041002 - PUT /company/:companyId/role/:roleId - ISFMK00040
R041003 - DELETE /company/:companyId/role/:roleId - ISFMK00040
S020001 - GET /company/:companyId/salary - ISFMK00067
S020002 - POST /company/:companyId/salary - ISFMK00067
S020003 - PUT /company/:companyId/salary - ISFMK00067
S020004 - GET /company/:companyId/salary/:salaryId - ISFMK00039, ISFMK00023
S020005 - PUT /company/:companyId/salary/:salaryId - ISFMK00039, ISFMK00023
S021001 - POST /company/:companyId/salary/voucher - ISFMK00075右邊
S022001 - GET /company/:companyId/salary/folder - ISFMK00078
S022002 - GET /company/:companyId/salary/folder/:folderId - ISFMK00076
S022003 - PUT /company/:companyId/salary/folder/:folderId - ISFMK00076
S040001 - POST /sign-up - ISFMK00001 [不需驗證登入]
S050001 - POST /sign-out [不需驗證登入]
S060001 - GET /session - ISFMK00001 [不需驗證登入]
U010001 - GET /user
U011001 - GET /user/:userId - ISFMK00001, ISFMK00062
U011002 - PUT /user/:userId - ISFMK00004, ISFMK00062
U012001 - POST /user/:userId/agreement
U030001 - PUT /user/:userId/invitation
V010001 - POST /company/:companyId/voucher - ISFMK00050
V011002 - PUT /company/:companyId/voucher/:voucherId - ISFMK00050右邊

Format

BaseUrl = /api/v1

API Example

description: some description

Request

Request url

GET /example

Parameters

name	type	description	required	default

Request Example

GET /example

Response

Response Parameters

name	type	description
powerby	string	ISunFa api 1.0.0
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	string	response data

Response Example

成功的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": true,
    "code":  "00000000",
    "message": "example",
    "payload": "example",
}

失敗的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": false,
    "code":  "09000000",
    "message": "fail request",
    "payload": null
}

listClient

description: list all clients

Request

Request url

GET /company/:companyId/client

Request Example

GET /company/1/client

Response

Response Parameters

name	type	description
powerby	string	ISunFa api 1.0.0
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Client[]	response data

Client

name	type	description
id	number	client's id
companyId	number	id of the company associated with this client
name	string	client's name
taxId	string	client's tax id
favorite	boolean	favorite client
createdAt	number	create time
updatedAt	number	update time

Response Example

成功的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": true,
    "code":  "200",
    "message": "list all client ",
    "payload": [
       {
          "id": 1,
          "companyId": 1000,
          "name": "cafeca",
          "taxId": "1234",
          "favorite": false,
          "createdAt": 1630000000,
          "updatedAt": 1630000000,
       },
       {
          "id": 2,
          "companyId": 1000,
          "name": "isunfa",
          "taxId": "3333",
          "favorite": true,
          "createdAt": 1630000000,
          "updatedAt": 1630000000,
       }
     ],
}

失敗的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": false,
    "code":  "500",
    "message": "internal server error",
    "payload": null
}

getClientById

description: get client by code

Request

Request url

GET /company/:companyId/client/:clientId

Request Example

GET /company/1/client/1

Response

Response Parameters

name	type	description
powerby	string	ISunFa api 1.0.0
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Client	response data

Client

name	type	description
id	number	client's id
companyId	number	id of the company associated with this client
name	string	client's name
taxId	string	client's tax id
favorite	boolean	favorite client
createdAt	number	create time
updatedAt	number	update time

Response Example

成功的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": true,
    "code":  "200",
    "message": "get clients by id",
    "payload": {
          "id": 1,
          "companyId": 1000,
          "name": "cafeca",
          "taxId": "1234",
          "favorite": false,
          "createdAt": 1630000000,
          "updatedAt": 1630000000,
       },
}

失敗的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": false,
    "code":  "422",
    "message": "invalid input parammeter",
    "payload": null
}

createClient

description: create client

Request

Request url

POST /company/:companyId/client

body

name	type	description	required	default
name	string	client's name	true	-
taxId	string	client's tax id	true	-
favorite	boolean	favorite client	false	false

Request Example

POST /company/1/client

const body = {
          "name": "cafeca",
          "taxId": "1234",
          "favorite": false,
       }

Response

Response Parameters

name	type	description
powerby	string	ISunFa api 1.0.0
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Client	response data

Client

name	type	description
id	number	client's id
companyId	number	id of the company associated with this client
name	string	client's name
taxId	string	client's tax id
favorite	boolean	favorite client
createdAt	number	create time
updatedAt	number	update time

Response Example

成功的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": true,
    "code":  "200",
    "message": "create client successfully",
    "payload": {
          "id": 1,
          "companyId": 1000,
          "name": "cafeca",
          "taxId": "1234",
          "favorite": false,
          "createdAt": 1630000000,
          "updatedAt": 1630000000,
       },
}

失敗的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": false,
    "code":  "422",
    "message": "invalid input parameter",
    "payload": null
}

updateClientById

description: update client by id

Request

Request url

PUT /company/:companyId/client/:clientId

body

name	type	description	required	default
name	string	client's name	true	-
taxId	string	client's tax id	true	-
favorite	boolean	favorite client	false	false

Request Example

PUT /company/1/client/1234

const body = {
        name: 'cafeca',
        taxId: '5678',
        favorite: false,
}

Response

Response Parameters

name	type	description
powerby	string	ISunFa api 1.0.0
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Client	response data

Client

name	type	description
id	number	client's id
companyId	number	id of the company associated with this client
name	string	client's name
taxId	string	client's tax id
favorite	boolean	favorite client
createdAt	number	create time
updatedAt	number	update time

Response Example

成功的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": true,
    "code":  "200",
    "message": "update client successfully",
    "payload": {
          "id": 1,
          "companyId": 1000,
          "name": "cafeca",
          "taxId": "5678",
          "favorite": false,
          "createdAt": 1630000000,
          "updatedAt": 1630000000,
       },
}

失敗的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": false,
    "code":  "422",
    "message": "invalid input parameter",
    "payload": null
}

deleteClientById

description: delete client by id

Request

Request url

DELETE /company/:companyId/client/:clientId

Request Example

DELETE /company/1/client/2

Response

Response Parameters

name	type	description
powerby	string	ISunFa api 1.0.0
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Client	response data

Client

name	type	description
id	number	client's id
companyId	number	id of the company associated with this client
name	string	client's name
taxId	string	client's tax id
favorite	boolean	favorite client
createdAt	number	create time
updatedAt	number	update time

Response Example

成功的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": true,
    "code":  "200",
    "message": "delete client successfully",
    "payload": {
          "id": 2,
          "companyId": 1000,
          "name": "isunfa",
          "taxId": "3333",
          "favorite": false,
          "createdAt": 1630000000,
          "updatedAt": 1630000000,
       },
}

失敗的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": false,
    "code":  "422",
    "message": "invalid input parameter",
    "payload": null
}

listContract

Description: Retrieve a list of contracts associated with a specific project, with pagination support.

Request

Request URL

GET /company/:companyId/contract

Query Parameters

name	type	description	required	default
page	number	Page number of the contract	false	1
limit	number	Number of contracts to return per page	false	10
status	string	return contracts that on certain stage("designing" \| "developing" \| "betaTesting" \| "selling" \| "sold" \| "archived")	false	undefined
sort	string	if not provided or provided "desc", will be sort by descent, provide other words will be sort by absent	false	desc

Request Example

GET /company/1/contracts?page=2&limit=5&status=designing&sort=asc

Response

Response Parameters

name	type	description
powerby	string	Version of the API powering the request
success	boolean	Indicates if the API call was successful
code	string	HTTP response code
message	string	Description of the response
payload	Contract[]	Object containing the list of contracts and meta of page info

Contract

name	type	description
id	number	Unique identifier of the contract
projectId	number	Unique identifier of the project associated with the contract
projectName	string	Name of the associated project
companyId	number	Unique identifier of the company associated with the contract
companyName	string	Name of the associated company
status	string	Status of the contract (valid \| invalid \| pending \| terminated)
progress	number	Progress percentage of the contract 0~100
name	string	Name of the contract
signatory	string	Name of the signatory
signatoryDate	number	Date of the signatory
payment	IPayment	Payment information of the contract
hasContractDate	boolean	Whether the contract has a contract date
contractStartDate	number	Start date of the contract
contractEndDate	number	End date of the contract
hasDeadlineDate	boolean	Whether the contract has a deadline date
deadlineDate	number	Deadline date of the contract
hasWarrantyDate	boolean	Whether the contract has a warranty date
warrantyStartDate	number	Start date of the warranty period
warrantyEndDate	number	End date of the warranty period
serviceType	string	Type of service (buyout \| usage \| subscription\| technicalSupport)
estimatedCost	number	Estimated cost of the contract
createdAt	number	Date of creation of the contract
updatedAt	number	Date of the last update of the contract

IPayment

name	type	description
isRevenue	boolean	Whether the payment is revenue
price	number	Total price of the payment
hasTax	boolean	Whether the payment has tax
taxPercentage	number	Tax percentage of the payment
hasFee	boolean	Whether the payment has fee
fee	number	Fee of the payment
method	string	Payment method
period	string	Payment period (atOnce \| installment)
installmentPeriod	number	Number of installments
alreadyPaid	number	Amount already paid
status	string	Payment status (pending \| paid \| overdue)
progress	number	Progress percentage of the payment

PageMeta

name	type	description
currentPage	number	The current page number
totalPages	number	The total number of pages available
totalItems	number	The total number of items available

Response Example

Success Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": true,
  "code": "200",
  "message": "Contracts retrieved successfully",
  "payload": {
    "contracts": [
      {
        "id": 1,
        "projectId": 1,
        "projectName": "Project 1",
        "companyId": 1,
        "companyName": "Company 1",
        "status": "valid",
        "progress": 50,
        "name": "Contract 1",
        "signatory": "Signatory 1",
        "signatoryDate": 1630000000,
        "payment": {
          "isRevenue": true,
          "price": 1000000,
          "hasTax": true,
          "taxPercentage": 5,
          "hasFee": true,
          "fee": 50000,
          "method": "creditCard",
          "period": "installment",
          "installmentPeriod": 3,
          "alreadyPaid": 300000,
          "status": "paid",
          "progress": 30
        },
        "hasContractDate": true,
        "contractStartDate": 1630000000,
        "contractEndDate": 1630000000,
        "hasDeadlineDate": true,
        "deadlineDate": 1630000000,
        "hasWarrantyDate": true,
        "warrantyStartDate": 1630000000,
        "warrantyEndDate": 1630000000,
        "serviceType": "subscription",
        "estimatedCost": 785000,
        "createdAt": 1630000000,
        "updatedAt": 1630000000
      },
      // ... additional contracts
    ]
    "pageMeta": {
   "currentPage": 2,
      "totalPages": 20,
      "totalItems": 85
    }
  },
}

Failure Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": false,
  "code": "404",
  "message": "Project not found or you do not have permission to view the contracts",
}

getAContract

Description

Retrieve detailed information extracted from a contract document after OCR processing has completed. This data is useful for contract creation and verification.

Request

Request URL

GET /company/:companyId/contract/:contractId

Parameters

name	type	description	required
contractId	string	The id of the contract	true

Request Example

GET /company/1/contract/123456

Response

Response Parameters

name	type	description
powerby	string	The version of the API
success	boolean	Whether the data retrieval was successful
code	string	The response code
message	string	A message detailing the result of the request
payload	Contract	The structured data extracted from the document

Contract

name	type	description
id	number	Unique identifier of the contract
projectId	number	Unique identifier of the project associated with the contract
projectName	string	Name of the associated project
companyId	number	Unique identifier of the company associated with the contract
companyName	string	Name of the associated company
status	string	Status of the contract (valid \| invalid \| pending \| terminated)
progress	number	Progress percentage of the contract 0~100
name	string	Name of the contract
signatory	string	Name of the signatory
signatoryDate	number	Date of the signatory
payment	IPayment	Payment information of the contract
hasContractDate	boolean	Whether the contract has a contract date
contractStartDate	number	Start date of the contract
contractEndDate	number	End date of the contract
hasDeadlineDate	boolean	Whether the contract has a deadline date
deadlineDate	number	Deadline date of the contract
hasWarrantyDate	boolean	Whether the contract has a warranty date
warrantyStartDate	number	Start date of the warranty period
warrantyEndDate	number	End date of the warranty period
serviceType	string	Type of service (buyout \| usage \| subscription\| technicalSupport)
estimatedCost	number	Estimated cost of the contract
createdAt	number	Date of creation of the contract
updatedAt	number	Date of the last update of the contract

IPayment

name	type	description
isRevenue	boolean	Whether the payment is revenue
price	number	Total price of the payment
hasTax	boolean	Whether the payment has tax
taxPercentage	number	Tax percentage of the payment
hasFee	boolean	Whether the payment has fee
fee	number	Fee of the payment
method	string	Payment method
period	string	Payment period (atOnce \| installment)
installmentPeriod	number	Number of installments
alreadyPaid	number	Amount already paid
status	string	Payment status (pending \| paid \| overdue)
progress	number	Progress percentage of the payment

Response Example

Success Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": true,
  "code": "200",
  "message": "Contract data retrieved successfully.",
  "payload": {
    {
        "id": 1,
        "projectId": 1,
        "projectName": "Project 1",
        "companyId": 1,
        "companyName": "Company 1",
        "status": "valid",
        "progress": 50,
        "name": "Contract 1",
        "signatory": "Signatory 1",
        "signatoryDate": 1630000000,
        "payment": {
          "isRevenue": true,
          "price": 1000000,
          "hasTax": true,
          "taxPercentage": 5,
          "hasFee": true,
          "fee": 50000,
          "method": "creditCard",
          "period": "installment",
          "installmentPeriod": 3,
          "alreadyPaid": 300000,
          "status": "paid",
          "progress": 30
        },
        "hasContractDate": true,
        "contractStartDate": 1630000000,
        "contractEndDate": 1630000000,
        "hasDeadlineDate": true,
        "deadlineDate": 1630000000,
        "hasWarrantyDate": true,
        "warrantyStartDate": 1630000000,
        "warrantyEndDate": 1630000000,
        "serviceType": "subscription",
        "estimatedCost": 785000,
        "createdAt": 1630000000,
        "updatedAt": 1630000000
      }
  }
}

Failure Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": false,
  "code": "404",
  "message": "Contract OCR result data not found for the provided resultId.",
}

createAContract

Description

This API endpoint is for creating a new contract in the system using data that may be provided manually or derived from an OCR-processed document.

Request

Request URL

POST /company/:companyId/contract

Headers

Name	Type	Description	Required
Content-Type	string	application/json	true

Body

IPayment

name	type	description
isRevenue	boolean	Whether the payment is revenue
price	number	Total price of the payment
hasTax	boolean	Whether the payment has tax
taxPercentage	number	Tax percentage of the payment
hasFee	boolean	Whether the payment has fee
fee	number	Fee of the payment
method	string	Payment method
period	string	Payment period (atOnce \| installment)
installmentPeriod	number	Number of installments
alreadyPaid	number	Amount already paid
status	string	Payment status (pending \| paid \| overdue)
progress	number	Progress percentage of the payment

Request Example

POST /company/1/contract

Body Example

{
  "projectId": 1,
  "projectName": "Project 1",
  "companyId": 1,
  "companyName": "Company 1",
  "status": "valid",
  "progress": 50,
  "name": "Contract 1",
  "signatory": "Signatory 1",
  "signatoryDate": 1630000000,
  "payment": {
    "isRevenue": true,
    "price": 1000000,
    "hasTax": true,
    "taxPercentage": 5,
    "hasFee": true,
    "fee": 50000,
    "method": "creditCard",
    "period": "installment",
    "installmentPeriod": 3,
    "alreadyPaid": 300000,
    "status": "paid",
    "progress": 30
  },
  "hasContractDate": true,
  "contractStartDate": 1630000000,
  "contractEndDate": 1630000000,
  "hasDeadlineDate": true,
  "deadlineDate": 1630000000,
  "hasWarrantyDate": true,
  "warrantyStartDate": 1630000000,
  "warrantyEndDate": 1630000000,
  "serviceType": "subscription",
  "estimatedCost": 785000,
  "createdAt": 1630000000,
  "updatedAt": 1630000000
}

Response

Response Parameters

name	type	description
powerby	string	The version of the API
success	boolean	Whether the data retrieval was successful
code	string	The response code
message	string	A message detailing the result of the request
payload	Contract	The structured data extracted from the document

Contract

name	type	description
id	number	Unique identifier of the contract
projectId	number	Unique identifier of the project associated with the contract
projectName	string	Name of the associated project
companyId	number	Unique identifier of the company associated with the contract
companyName	string	Name of the associated company
status	string	Status of the contract (valid \| invalid \| pending \| terminated)
progress	number	Progress percentage of the contract 0~100
name	string	Name of the contract
signatory	string	Name of the signatory
signatoryDate	number	Date of the signatory
payment	IPayment	Payment information of the contract
hasContractDate	boolean	Whether the contract has a contract date
contractStartDate	number	Start date of the contract
contractEndDate	number	End date of the contract
hasDeadlineDate	boolean	Whether the contract has a deadline date
deadlineDate	number	Deadline date of the contract
hasWarrantyDate	boolean	Whether the contract has a warranty date
warrantyStartDate	number	Start date of the warranty period
warrantyEndDate	number	End date of the warranty period
serviceType	string	Type of service (buyout \| usage \| subscription\| technicalSupport)
estimatedCost	number	Estimated cost of the contract
createdAt	number	Date of creation of the contract
updatedAt	number	Date of the last update of the contract

IPayment

name	type	description
isRevenue	boolean	Whether the payment is revenue
price	number	Total price of the payment
hasTax	boolean	Whether the payment has tax
taxPercentage	number	Tax percentage of the payment
hasFee	boolean	Whether the payment has fee
fee	number	Fee of the payment
method	string	Payment method
period	string	Payment period (atOnce \| installment)
installmentPeriod	number	Number of installments
alreadyPaid	number	Amount already paid
status	string	Payment status (pending \| paid \| overdue)
progress	number	Progress percentage of the payment

Response Example

Success Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": true,
  "code": "201",
  "message": "Contract data retrieved successfully.",
  "payload": {
    {
        "id": 1,
        "projectId": 1,
        "projectName": "Project 1",
        "companyId": 1,
        "companyName": "Company 1",
        "status": "valid",
        "progress": 50,
        "name": "Contract 1",
        "signatory": "Signatory 1",
        "signatoryDate": 1630000000,
        "payment": {
          "isRevenue": true,
          "price": 1000000,
          "hasTax": true,
          "taxPercentage": 5,
          "hasFee": true,
          "fee": 50000,
          "method": "creditCard",
          "period": "installment",
          "installmentPeriod": 3,
          "alreadyPaid": 300000,
          "status": "paid",
          "progress": 30
        },
        "hasContractDate": true,
        "contractStartDate": 1630000000,
        "contractEndDate": 1630000000,
        "hasDeadlineDate": true,
        "deadlineDate": 1630000000,
        "hasWarrantyDate": true,
        "warrantyStartDate": 1630000000,
        "warrantyEndDate": 1630000000,
        "serviceType": "subscription",
        "estimatedCost": 785000,
        "createdAt": 1630000000,
        "updatedAt": 1630000000
      }
  }
}

Failure Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": false,
  "code": "404",
  "message": "Contract OCR result data not found for the provided resultId.",
}

updateAContract

Description

Update existing contract details in the system using the unique identifier for a contract.

Request

Request URL

PUT /company/:companyId/contract/:contractId

URL Parameters

Name	Type	Description	Required
contractId	string	The unique contract ID	true

Headers

Name	Type	Description	Required
Content-Type	string	application/json	true

Body

IPayment

name	type	description
isRevenue	boolean	Whether the payment is revenue
price	number	Total price of the payment
hasTax	boolean	Whether the payment has tax
taxPercentage	number	Tax percentage of the payment
hasFee	boolean	Whether the payment has fee
fee	number	Fee of the payment
method	string	Payment method
period	string	Payment period (atOnce \| installment)
installmentPeriod	number	Number of installments
alreadyPaid	number	Amount already paid
status	string	Payment status (pending \| paid \| overdue)
progress	number	Progress percentage of the payment

Request Example

PUT /company/1/contract/:contractId

Body Example

{
  "projectId": 1,
  "projectName": "Project 1",
  "companyId": 1,
  "companyName": "Company 1",
  "status": "valid",
  "progress": 50,
  "name": "Contract 1",
  "signatory": "Signatory 1",
  "signatoryDate": 1630000000,
  "payment": {
    "isRevenue": true,
    "price": 1000000,
    "hasTax": true,
    "taxPercentage": 5,
    "hasFee": true,
    "fee": 50000,
    "method": "creditCard",
    "period": "installment",
    "installmentPeriod": 3,
    "alreadyPaid": 300000,
    "status": "paid",
    "progress": 30
  },
  "hasContractDate": true,
  "contractStartDate": 1630000000,
  "contractEndDate": 1630000000,
  "hasDeadlineDate": true,
  "deadlineDate": 1630000000,
  "hasWarrantyDate": true,
  "warrantyStartDate": 1630000000,
  "warrantyEndDate": 1630000000,
  "serviceType": "subscription",
  "estimatedCost": 785000,
  "createdAt": 1630000000,
  "updatedAt": 1630000000
}

Response

Response Parameters

name	type	description
powerby	string	The version of the API
success	boolean	Whether the data retrieval was successful
code	string	The response code
message	string	A message detailing the result of the request
payload	Contract	The structured data extracted from the document

Contract

name	type	description
id	number	Unique identifier of the contract
projectId	number	Unique identifier of the project associated with the contract
projectName	string	Name of the associated project
companyId	number	Unique identifier of the company associated with the contract
companyName	string	Name of the associated company
status	string	Status of the contract (valid \| invalid \| pending \| terminated)
progress	number	Progress percentage of the contract 0~100
name	string	Name of the contract
signatory	string	Name of the signatory
signatoryDate	number	Date of the signatory
payment	IPayment	Payment information of the contract
hasContractDate	boolean	Whether the contract has a contract date
contractStartDate	number	Start date of the contract
contractEndDate	number	End date of the contract
hasDeadlineDate	boolean	Whether the contract has a deadline date
deadlineDate	number	Deadline date of the contract
hasWarrantyDate	boolean	Whether the contract has a warranty date
warrantyStartDate	number	Start date of the warranty period
warrantyEndDate	number	End date of the warranty period
serviceType	string	Type of service (buyout \| usage \| subscription\| technicalSupport)
estimatedCost	number	Estimated cost of the contract
createdAt	number	Date of creation of the contract
updatedAt	number	Date of the last update of the contract

IPayment

name	type	description
isRevenue	boolean	Whether the payment is revenue
price	number	Total price of the payment
hasTax	boolean	Whether the payment has tax
taxPercentage	number	Tax percentage of the payment
hasFee	boolean	Whether the payment has fee
fee	number	Fee of the payment
method	string	Payment method
period	string	Payment period (atOnce \| installment)
installmentPeriod	number	Number of installments
alreadyPaid	number	Amount already paid
status	string	Payment status (pending \| paid \| overdue)
progress	number	Progress percentage of the payment

Response Example

Success Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": true,
  "code": "200",
  "message": "Contract data retrieved successfully.",
  "payload": {
    {
        "id": 1,
        "projectId": 1,
        "projectName": "Project 1",
        "companyId": 1,
        "companyName": "Company 1",
        "status": "valid",
        "progress": 50,
        "name": "Contract 1",
        "signatory": "Signatory 1",
        "signatoryDate": 1630000000,
        "payment": {
          "isRevenue": true,
          "price": 1000000,
          "hasTax": true,
          "taxPercentage": 5,
          "hasFee": true,
          "fee": 50000,
          "method": "creditCard",
          "period": "installment",
          "installmentPeriod": 3,
          "alreadyPaid": 300000,
          "status": "paid",
          "progress": 30
        },
        "hasContractDate": true,
        "contractStartDate": 1630000000,
        "contractEndDate": 1630000000,
        "hasDeadlineDate": true,
        "deadlineDate": 1630000000,
        "hasWarrantyDate": true,
        "warrantyStartDate": 1630000000,
        "warrantyEndDate": 1630000000,
        "serviceType": "subscription",
        "estimatedCost": 785000,
        "createdAt": 1630000000,
        "updatedAt": 1630000000
      }
  }
}

Failure Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": false,
  "code": "404",
  "message": "Contract OCR result data not found for the provided resultId.",
}

listCompanies

description: list all companies
request url

GET /company

Request Example

GET /company

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	{company: Company, role: Role}[]	response data

Company

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start date of the company
createdAt	number	create timestamp of the company
updatedAt	number	update timestamp of the company

Role

name	type	description
id	number	id of the role
name	string	name of the role
permissions	string[]	permission list

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code":  "200",
    "message": "List successfully",
    "payload": [
     {
     "company": {
        "id": 10000002,
        "name": "kk",
        "code": "123",
        "regional": "Taiwan",
        "kycStatus": false,
        "imageId": "https://storage.googleapis.com/mermer-offical-km/ISunFa/e8a48a55-2d97-4dc3-89fb-0fd3947cc971.svg",
        "startDate": 1723538434,
        "createdAt": 1723538434,
        "updatedAt": 1723538434,
        "deletedAt": null
      },
      "role": {
        "id": 1003,
        "name": "Owner",
        "permissions": [
          
        ],
        "createdAt": 1,
        "updatedAt": 1,
        "deletedAt": null
      }
    }
  ]
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "405",
    "message": "Method not allowed",
    "payload": {}
}

getCompanyById

description: get company by id

Request

Request url

GET /company/:companyId

Request Example

GET /company/1

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	CompanyAndRole	response data

CompanyAndRole

name	type	description
company	CompanyDetail	company detail
role	Role	role

CompanyDetail

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start date of the company
createAt	number	create timestamp of the company
updateAt	number	update timestamp of the company
ownerId	number	owner of the company's id
kycStatusDetail	string	kyc status detail of company

Role

name	type	description
id	string	role's id
name	string	role's name
permissions	string[]	permission of the role

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code":  "200",
    "message": "Get successfully",
   "payload": {
    "company": {
      "id": 10000002,
      "name": "kk",
      "code": "123",
      "regional": "Taiwan",
      "kycStatus": false,
      "imageId": "https://storage.googleapis.com/mermer-offical-km/ISunFa/e8a48a55-2d97-4dc3-89fb-0fd3947cc971.svg",
      "startDate": 1723538434,
      "createdAt": 1723538434,
      "updatedAt": 1723538434,
      "deletedAt": null,
      "ownerId": 10000003,
      "kycStatusDetail": "NOT_STARTED"
    },
    "role": {
      "id": 1003,
      "name": "Owner",
      "permissions": [
        
      ],
      "createdAt": 1,
      "updatedAt": 1,
      "deletedAt": null
    }
  }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "404",
    "message": "Resource not found",
    "payload": null
}

createCompany

description: create company

Request

Request url

POST /company

Request Example

POST /company

const body = {
  "name": "iSunFA",
  "code": "168",
  "regional": "Taiwan",
}

Body

name	type	description
name	string	company's name
code	string	company's code
regional	string	company's regional

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	{company: Company, role: Role}	response data

Company

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start date of the company
createdAt	number	create timestamp of the company
updatedAt	number	update timestamp of the company

Role

name	type	description
id	number	id of the role
name	string	name of the role
permissions	string[]	permission list

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code":  "200",
    "message": "Create successfully",
    "payload": [
     {
     "company": {
        "id": 10000002,
        "name": "kk",
        "code": "123",
        "regional": "Taiwan",
        "kycStatus": false,
        "imageId": "https://storage.googleapis.com/mermer-offical-km/ISunFa/e8a48a55-2d97-4dc3-89fb-0fd3947cc971.svg",
        "startDate": 1723538434,
        "createdAt": 1723538434,
        "updatedAt": 1723538434,
        "deletedAt": null
      },
      "role": {
        "id": 1003,
        "name": "Owner",
        "permissions": [
          
        ],
        "createdAt": 1,
        "updatedAt": 1,
        "deletedAt": null
      }
    }
  ]
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "422",
    "message": "Invalid input parameter",
    "payload": {}
}

updateCompany

description: update company

Request

Request url

PUT /company/:companyId

Request Example

PUT /company/1

Body

name	type	description
name	string	company's name
code	string	company's code
regional	string	company's regional

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Company	response data

Company

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start date of the company
createdAt	number	create timestamp of the company
updatedAt	number	update timestamp of the company

{
  "name": "iSunFA",
  "code": "168",
  "regional": "Taiwan",
}

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code":  "200",
    "message": "Update successfully",
    "payload": {
        "id":"1",
        "name": "iSunFA",
        "code":"168",
        "regional":"Taiwan",
        "kycStatus": false,
        "imageId": "123",
        "startDate": 1630000000,
        "createdAt": 1630000000,
        "updatedAt": 1630000000
    },
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "422",
    "message": "Invalid input parameter",
    "payload": {}
}

deleteCompany

description: delete company

Request

Request url

DELETE /company/:companyId

Request Example

DELETE /company/1

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Company	response data

Company

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start date of the company
createdAt	number	create timestamp of the company
updatedAt	number	update timestamp of the company

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code":  "200",
    "message": "Update successfully",
    "payload": {
        "id":"1",
        "name": "iSunFA",
        "code":"168",
        "regional":"Taiwan",
        "kycStatus": false,
        "imageId": "123",
        "startDate": 1630000000,
        "createdAt": 1630000000,
        "updatedAt": 1630000000
    },
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "422",
    "message": "Invalid input parameter",
    "payload": {}
}

listRoles

description: list all roles

Request

Request url

GET /company/:companyId/role

Request Example

GET /company/1/role

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Role[]	response data

Role

name	type	description
id	number	role's id
name	string	role's name
permissions	string[]	permission of the role

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code":  "200",
    "message": "List successfully",
    "payload": [
        {
          "id":1,
          "name": "Bob",
          "permissions":["auditing_viewer", "accounting_editor", "internalControl_editor"],
        },
        {
          "id":2,
          "name": "Alice",
          "permissions":["read"],
        }
    ],
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "405",
    "message": "Method not allowed",
    "payload": {}
}

getRoleById

description: get role by id

Request

Request url

GET /company/:companyId/role/:roleId

Request Example

GET /company/1/role/1

Parameters

name	type	description	require	default
roleId	string	role id	true	-

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Role	response data

Role

name	type	description
id	number	role's id
name	string	role's name
permissions	string[]	permission of the role

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code":  "200",
    "message": "Get successfully",
    "payload": [
        {
          "id":1,
          "name": "Bob",
          "permissions":["auditing_viewer", "accounting_editor", "internalControl_editor"],
        }
    ],
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "422",
    "message": "Invalid input parameter",
    "payload": {}
}

createRole

description: create role

Request

Request url

POST /company/:companyId/role

Request Example

POST /company/1/role

const body = {
  "name": "Bobie",
}

Body

name	type	description
name	string	role's name

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Role	response data

Role

name	type	description
id	number	role's id
name	string	role's name
permissions	string[]	permission of the role

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code":  "201",
    "message": "Created successfully",
    "payload": [
        {
          "id":1,
          "name": "Bobie",
          "permissions":['auditing_editor', 'accounting_editor', 'internalControl_editor'],
        }
    ],
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "405",
    "message": "Method not allowed",
    "payload": {}
}

updateRoleById

description: update role by id

Request

Request url

PUT /company/:companyId/role/:roleId

Request Example

PUT /company/1/role/1

const body = {
  "name": "Bobie",
  "permissions":["auditing_viewer"],
}

Parameters

name	type	description	require	default
roleId	string	role id	true	-

Body

name	type	description
name	string	role's name
permissions	string[]	permission of the role

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Role	response data

Role

name	type	description
id	number	role's id
name	string	role's name
permissions	string[]	permission of the role

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code":  "200",
    "message": "Update successfully",
    "payload": [
        {
          "id": 1,
          "name": "Bobie",
          "permissions":["auditing_viewer"],
        }
    ],
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "405",
    "message": "Method not allowed",
    "payload": {}
}

deleteRoleById

description: delete role

Request

Request url

DELETE /company/:companyId/role/:roleId

Request Example

DELETE /company/1/role/1

Parameters

name	type	description	require	default
roleId	string	role id	true	-

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Role	response data

Role

name	type	description
id	number	role's id
name	string	role's name
permissions	string[]	permission of the role

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code":  "200",
    "message": "Delete successfully",
    "payload": [
        {
          "id": 1,
          "name": "Bobie",
          "permissions":["auditing_viewer"],
        }
    ],
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "405",
    "message": "Method not allowed",
    "payload": {}
}

getProcessedJournalData

Description

Retrieve the data processed from the document/image upload, which can be used to create a new income or expense line item.

Request

URL

GET /company/:companyId/journal/:journalId

Parameters

name	type	description	required	default
journalId	string	The unique identifier for the processed journal data	true	-

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Journal	The data processed from the document

Journal

name	type	description
id	number	Unique identifier for the journal.
event	JOURNAL_EVENT	event type.
tokenContract	string	The contract address for the token.
tokenId	string	Identifier for the specific token.
aichResultId	string	Identifier for the aich result.
projectId	number	Identifier for the project.
contractId	number	Identifier for the contract.
imageUrl	string	image url.
invoice	Invoice	invoice info.
voucher	VoucherDataForSavingToDB	voucher info.

JOURNAL_EVENT

JOURNAL_EVENT {
  UPLOADED = 'JOURNAL.UPLOADED',
  UPCOMING = 'JOURNAL.UPCOMING',
}

Invoice

name	type	description
journalId	number / null	this value is not required, just use null
date	number	The timestamp representing the date and time. (second)
eventType	EventType	The type of event ('income', 'payment', 'transfer').
paymentReason	string	The reason for the payment.
description	string	A description of the transaction.
vendorOrSupplier	string	The name of the vendor or supplier involved.
projectId	number \|null	The identifier for the project. (can be null )
project	string \|null	The name of the project. (can be null )
contractId	number \|null	The unique identifier for the contract. (can be null )
contract	string \|null	The name or title of the contract. (can be null )
payment	Payment	A object containing payment details.

Payment

name	type	description
isRevenue	boolean	Indicates if the transaction will generate income. True: money is coming in; false: going out.
price	number	The total amount of money involved in the transaction.
hasTax	boolean	Specifies whether the amount includes tax.
taxPercentage	number	The tax rate, for example, 0 or 5, etc.
hasFee	boolean	Indicates whether there is a handling fee included.
fee	number	The amount of the handling fee.
method	string	The method by which money is received or paid out.
period	PaymentPeriodType (enum)	The timing of payment, either at once (atOnce) or in installments (installment).
installmentPeriod	number	The number of installments for payment.
alreadyPaid	number	The amount of money that has already been paid or collected.
status	PaymentStatusType(enum)	The status of the payment. "paid" or "unpaid" or "partial
progress	number	The actual work completion percentage for a contract, not referring to payment progress.

VoucherDataForSavingToDB

name	type	description
journalId	number	journal id
lineItem	LineItem[]	Line items of voucher, each line item represent each line in url voucher

LineItem

name	type	description
lineItemIndex	string	The unique index of the line item entry. But this has no actual meaning, just random response from aich, real id will be number and store in db
account	string	The account associated with the line item.
description	string	A detailed description of the line item.
debit	boolean	Indicates if the item is a debit (true) or credit (false).
amount	number	The monetary amount of the line item.
accountId	number	The account id of the line item.

Response Example

Success Response

{
    "powerby": "iSunFA v0.8.0",
    "success": true,
    "code": "200ISF0000",
    "message": "Success",
    "payload": {
        "id": 10000224,
        "tokenContract": "",
        "tokenId": "",
        "aichResultId": "b75850fb4d0601ad5f1d",
        "projectId": 0,
        "contractId": 0,
        "imageUrl": "/api/v1/company/0/invoice/b8f3fcc73af5234058614fe04.png/image",
        "event": "JOURNAL.UPLOADED",
        "invoice": {
            "journalId": 10000224,
            "date": 1723132800,
            "eventType": "income",
            "paymentReason": "123",
            "description": "123",
            "vendorOrSupplier": "123",
            "projectId": null,
            "project": null,
            "contractId": null,
            "contract": null,
            "payment": {
                "isRevenue": true,
                "price": 1000,
                "hasTax": true,
                "taxPercentage": 52,
                "hasFee": false,
                "fee": 0,
                "method": "",
                "period": "atOnce",
                "installmentPeriod": 0,
                "alreadyPaid": 1610599188,
                "status": "paid",
                "progress": 100
            }
        },
        "voucher": {
            "journalId": 10000224,
            "lineItems": [
                {
                    "lineItemIndex": "10000310",
                    "amount": 1000,
                    "debit": true,
                    "account": "指定透過損益按公允價值衡量之金融資產評價調整－流動",
                    "description": "222",
                    "accountId": 10000546
                },
                {
                    "lineItemIndex": "10000311",
                    "amount": 1000,
                    "debit": false,
                    "account": "零用金／週轉金",
                    "description": "222",
                    "accountId": 10000541
                }
            ]
        }
    }
}

Failure Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "404",
  "message": "Resource not found"
  "payload": null
}

getInvoice

Description

Retrieve an image of a specific invoice.

Request

URL

GET /company/:companyId/invoice/:id

Parameters

name	type	description	required
id	string	Unique identifier for the invoice	true

Request Example

GET /company/1/invoice/1

Response

Headers

The response will have the Content-Type header set to an image MIME type (like image/jpeg or image/png) to indicate that an image is being returned.

Response Body

The body of the response will be the binary data of the image.

Response Example

The response will be the image file itself, not a JSON object.

createOCRAnalyzingProcess

description:
- Post an image or multiples images in formData (all image need to use the key "image" and append to formData), will return a list of OCR resultId and status of OCR analyzed.
- If you want to get all status of the uploaded image of certain company, you need to get from GET /OCR API.
logic flow:
- 1. Post image to AICH for OCR analyzing
- 1. Retrieve the resultId and status of OCR analyzed from AICH
- 1. Create a row in OCR table in database to store the resultId, status of OCR analyzed and image related information
- 1. Return a list of resultId and status of OCR analyzed
- 1. Warning: this api won't create journal

Request

Request url

POST /company/:companyId/ocr

Body

name	type	description	require	default
formData	FormData	Need to use `new FormData` to post invoice images (see example down below)	true	-

formData內包含

name	type	description	require	default
image	File[]	An array of Image To be analyze by ocr (請所有的image在formData的key都是"image", 或著直接上傳一個array)	true	-

Request Example

  const formData = new FormData()
  formData.append('image', [圖片1, 圖片2])

  // the URL of the uploaded image in the response
  const response = await fetch('/invoice', {
    method: 'POST',
    body: formData
  })

Response

Response Parameters

name	type	description
powerby	string	ISunFa api 1.0.0
success	boolean	true \| false
code	string	response code
message	string	description of response data
payload	IAccountResultStatus[]	Every image upload will return a set of id and result status

AccountResultStatus

name	type	description
reultId	string	result Id
status	ProgressStatus Enum	status of current OCR ResultId

ProgressStatus

export enum ProgressStatus {
  SUCCESS = 'success',
  IN_PROGRESS = 'inProgress',
  NOT_FOUND = 'notFound',
  ALREADY_UPLOAD = 'alreadyUpload',
  INVALID_INPUT = 'invalidInput',
  LLM_ERROR = 'llmError',
  SYSTEM_ERROR = 'systemError',
  PAUSED = 'paused',
  HAS_BEEN_USED = 'hasBeenUsed',
}

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.4+4",
    "success": true,
    "code": "201ISF0000",
    "message": "Created successfully",
    "payload": [
        {
            "resultId": "b6e8a6c6e70eb1c92bbd",
            "status": "inProgress"
        },
        {
            "resultId": "81d677209caaabbbccc",
            "status": "inProgress"
        }
    ]
}

如果上傳的invoice還存在AICH 則是alreadyUploaded

{
    "powerby": "iSunFA v0.1.4+4",
    "success": true,
    "code": "201ISF0000",
    "message": "Created successfully",
    "payload": [
        {
            "resultId": "b6e8a6c6e70eb1c92bbd",
            "status": "alreadyUpload"
        },
        {
            "resultId": "81d677209caaabbbccc",
            "status": "alreadyUpload"
        }
    ]
}

失敗的回傳 (如果ISunFa連不上AICH的話)

{
  "powerby": "iSunFA v1.0.0",
  "success": false,
  "code":  "422ISF0000",
  "message": "Invalid input formdata image",
  "payload": {}
}

如果出現像是下面的 Bad gateway 的話則是AICH的問題

{
  "powerby": "iSunFA v1.0.0",
  "success": false,
  "code":  "502ISF0001",
  "message": "Bad gateway connect AICH failed",
  "payload": {}
}

getUnprocessedOCR

description

This API is mean to replace /unprocess_journal, it has same shape of response, but the Interface changed to Ocr[]
This API can return all OCR process that are not yet bond to certain invoice, which means it will return the OCR that contain aichResultId, but have null value on journalId in database

Request

Request url

GET `/company/:companyId/ocr`

Query

name	type	description	required	default
companyId	string	specific company number, will be used on query to db	yes	-

Request Example

GET `/company/1/ocr`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Ocr[]	response data or []

Ocr

name	type	description
id	number	the unique identifier for the journal
aichResultId	string	for asking result
imageName	string	the name of image (contain File extension)
imageUrl	string	the url for frontend to show image
imageSize	string	the size of image, ex: "10 KB" or "10 MB", round to 2 below decimal point
progress	number	0~100 Integer, is count by (time already consumed)/(default average Ocr process time), will be set to 100 if status is success
status	ProgressStatus	the status of OCR analyzing
createdAt	number	timestamp in second

export interface IOCR {
  id: number;
  aichResultId: string;
  imageName: string;
  imageUrl: string;
  imageSize: number;
  progress: number; // 0 ~ 100 Int
  status: ProgressStatus;
  createdAt: number;
}

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.4+78",
    "success": true,
    "code": "200ISF0002",
    "message": "Get successfully",
    "payload": [
        {
            "id": 3,
            "aichResultId": "b6e8a6c6e70eb1c92bbd",
            "imageUrl": "/api/v1/company/0/invoice/621d30213185179d76ffa7e00.jpg/image",
            "imageName": "621d30213185179d76ffa7e00.jpg",
            "imageSize": "487.03 KB",
            "status": "systemError",
            "progress": 0,
            "createdAt": 1718594724
        }
    ]
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "500ISF0002",
  "message": "Database create failed",
  "payload": []
}

deleteOCRbyResultId

description: delete OCR by resultId

Request

Request url

DELETE /company/:companyId/ocr/:resultId

Request Example

DELETE /company/1/ocr/b6e8a6c6e7

Response

Response Parameters

name	type	description
powerby	string	ISunFa api 1.0.0
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	OCR	response data

OCR

name	type	description
id	number	the unique identifier for the journal
aichResultId	string	for asking result
imageName	string	the name of image (contain File extension)
imageUrl	string	the url for frontend to show image
imageSize	string	the size of image, ex: "10 KB" or "10 MB", round to 2 below decimal point
progress	number	0~100 Integer, is count by (time already consumed)/(default average Ocr process time), will be set to 100 if status is success
status	ProgressStatus	the status of OCR analyzing
createdAt	number	timestamp in second

Response Example

成功的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": true,
    "code":  "200",
    "message": "delete successfully",
    "payload": {
        "id": 3,
        "aichResultId": "b6e8a6c6e70eb1c92bbd",
        "imageUrl": "/api/v1/company/0/invoice/621d30213185179d76ffa7e00.jpg/image",
        "imageName": "621d30213185179d76ffa7e00.jpg",
        "imageSize": "487.03 KB",
        "status": "systemError",
        "progress": 0,
        "createdAt": 1718594724
    }
}

失敗的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": false,
    "code":  "422",
    "message": "invalid input parameter",
    "payload": null
}

createNewProject

Description: Create a new project with the specified details including the project name, stage, and team members.

Request

Request URL

POST /company/:companyId/project

Body

name	type	description
name	string	name of the project
stage	string	current stage of the project
memberIdList	number[]	list of ids of project members

Request Example

POST /company/1/project

const body = {
  name: "Project 3",
  stage: "Designing",
  memberIdList: [1000, 1001]
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	Indicates if the API call was successful
code	string	HTTP response code
message	string	Description of the response
payload	Project \| null	project object or null

Project

name	type	description
id	number	unique identifier for the project
companyId	number	unique identifier for the company
imageId	string	unique identifier for the image
name	string	name of the project
income	number	total income of the project
expense	number	total expenses of the project
profit	number	total profit of the project
contractAmount	number	total contract amount of the project
stage	string	current stage of the project
completedPercent	number	completed percent of the project
members	Member[]	list of usernames of project members
createdAt	number	timestamp for the project creation
updatedAt	number	timestamp for the project last update

Member

name	type	description
name	string	name of the member
imageId	string	id for the member's image

Response Example

Success Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code": "200",
  "message": "create project successfully",
  "payload": {
    id: 3,
    companyId: 1,
    imageId: "3",
    name: "Project 3",
    income: 1000,
    expense: 500,
    profit: 500,
    contractAmount: 2000,
    stage: "Designing",
    completedPercent: 0,
    members: [
      {
        name: "Eva",
        imageId: "3"
      }
    ],
    createdAt: 1630000000,
    updatedAt: 1630000000
  };
}

Failure Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "400",
  "message": "create failed",
  "payload": null 
}

createAsset

Description

Create a new asset that will automatically depreciate over time and generate the appropriate accounting vouchers.

Request

URL

POST /company/:companyId/asset

Headers

name	type	description	required
Content-Type	string	Must be set to application/json	true

Body

name	type	description	required	default
voucherId	number	The voucher id that the asset is associated with	true	-
projectId	number	The project id that the asset is associated with	true	-
contractId	number	The contract id that the asset is associated with	true	-
name	string	The name of the asset	true	-
label	string	The lable of the asset	true	-
type	string	The type of the asset	true	-
description	string	A description of the asset	true	-
supplier	string	The supplier of the asset	true	-
startDate	string	The start date the asset was purchased, (YYYY-MM-DD)	true	-
endDate	string	The end date the asset was purchased, (YYYY-MM-DD)	true	-
price	string	The purchase price of the asset	true	-
residualValue	string	The residual value of the asset	true	-
depreciationMethod	string	The method of depreciation	true	-
estimatedUsefulLife	number	The estimated useful life in months	true	-

Request Example

{
    "voucherId": 123456,
    "projectId": 123456,
    "contractId": 123456,
    "name": "mac",
    "tag": "computer",
    "type": "liquid",
    "description": "asset discription",
    "startDate": "2024-01-01",
    "endDate": "2024-11-01",
    "price": 20,
    "residualValue": 15,
    "depreciationMethod": "stright",
    "estimatedUsefulLife": 36
  }

Response

Response Parameters

name	type	description
powerby	string	The version of the API
success	boolean	Whether the asset creation was successful
code	string	The response code
message	string	A message about the asset creation
payload	Asset	The details of the created asset

Asset

name	type	description
id	number	asset id
voucherId	number	The voucher id that the asset is associated with
projectId	number	The project id that the asset is associated with
contractId	number	The contract id that the asset is associated with
name	string	The name of the asset
label	string	The label of the asset
type	string	The type of the asset
description	string	A description of the asset
supplier	string	The supplier of the asset
startDate	number	The start date the asset was purchased, (YYYY-MM-DD)
endDate	number	The end date the asset was purchased, (YYYY-MM-DD)
price	number	The purchase price of the asset
residualValue	number	The residual value of the asset
depreciationMethod	string	The method of depreciation
estimatedUsefulLife	number	The estimated useful life in months
createdAt	number	The timestamp representing the date and time the asset was created
updatedAt	number	The timestamp representing the date and time the asset was last updated

Response Example

Success Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": true,
  "code": "201",
  "message": "Asset created successfully.",
  "payload": {
    "id": 123456,
    "voucherId": 123456,
    "projectId": 123456,
    "contractId": 123456,
    "name": "mac",
    "label": "computer",
    "type": "liquid",
    "description": "asset description",
    "supplier": "apple",
    "startDate": "2024-01-01",
    "endDate": "2024-11-01",
    "price": 20,
    "residualValue": 15,
    "depreciationMethod": "stright",
    "estimatedUsefulLife": 36,
    "createdAt": 1713052800,
    "updatedAt": 1713052800
  }
}

Failure Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": false,
  "code": "400",
  "message": "Failed to create asset. Invalid data provided.",
}

listAsset

Description: Retrieve a list of assets associated with a specific project, with pagination support.

Request

URL

GET /company/:companyId/asset

Headers

name	type	description	required
Content-Type	string	Must be set to application/json	true

Response

Response Parameters

name	type	description
powerby	string	The version of the API
success	boolean	Whether the asset creation was successful
code	string	The response code
message	string	A message about the asset creation
payload	Asset	The details of the created asset

Asset

name	type	description
id	number	asset id
voucherId	number	The voucher id that the asset is associated with
projectId	number	The project id that the asset is associated with
contractId	number	The contract id that the asset is associated with
name	string	The name of the asset
label	string	The label of the asset
type	string	The type of the asset
description	string	A description of the asset
supplier	string	The supplier of the asset
startDate	number	The start date the asset was purchased, (YYYY-MM-DD)
endDate	number	The end date the asset was purchased, (YYYY-MM-DD)
price	number	The purchase price of the asset
residualValue	number	The residual value of the asset
depreciationMethod	string	The method of depreciation
estimatedUsefulLife	number	The estimated useful life in months
createdAt	number	The timestamp representing the date and time the asset was created
updatedAt	number	The timestamp representing the date and time the asset was last updated

Response Example

Success Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": true,
  "code": "200",
  "message": " Asset created successfully.",
  "payload": {
    "id": 123456,
    "voucherId": 123456,
    "projectId": 123456,
    "contractId": 123456,
    "name": "mac",
    "label": "computer",
    "type": "liquid",
    "description": "asset description",
    "startDate": "2024-01-01",
    "endDate": "2024-11-01",
    "price": 20,
    "residualValue": 15,
    "depreciationMethod": "stright",
    "estimatedUsefulLife": 36,
    "createdAt": 1713052800,
    "updatedAt": 1713052800
  }
}

Failure Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": false,
  "code": "400",
  "message": "Failed to create asset. Invalid data provided.",
}

getAsset

Description

Retrieve the details of a specific asset for review or editing.

Request

URL

GET /company/:companyId/asset/:assetId

URL Parameters

name	type	description	required
id	string	Unique identifier for the asset	true

Response

Response Parameters

name	type	description
powerby	string	The version of the API
success	boolean	Whether the retrieval was successful
code	string	The response code
message	string	A message about the retrieval
payload	Asset	The details of the requested asset

Asset (as defined in POST)

Response Example

Success Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": true,
  "code": "200",
  "message": " Asset details retrieved successfully.",
  "payload": {
    "id": 123456,
    "voucherId": 123456,
    "projectId": 123456,
    "contractId": 123456,
    "name": "mac",
    "label": "computer",
    "type": "liquid",
    "description": "asset description",
    "supplier": "apple",
    "startDate": "2024-01-01",
    "endDate": "2024-11-01",
    "price": 20,
    "residualValue": 15,
    "depreciationMethod": "stright",
    "estimatedUsefulLife": 36,
    "createdAt": 1713052800,
    "updatedAt": 1713052800
  }
}

Failure Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": false,
  "code": "404",
  "message": " Asset not found.",
}

updateAsset

Description

Update the details of an existing asset.

Request

URL

PUT /company/:companyId/asset/:id

URL Parameters

name	type	description	required
id	string	Unique identifier for the asset	true

Body Parameters

Body

name	type	description	required	default
voucherId	number	The voucher id that the asset is associated with	true	-
projectId	number	The project id that the asset is associated with	true	-
contractId	number	The contract id that the asset is associated with	true	-
name	string	The name of the asset	true	-
label	string	The label of the asset	true	-
type	string	The type of the asset	true	-
description	string	A description of the asset	true	-
supplier	string	The supplier of the asset	true	-
startDate	string	The start date the asset was purchased, (YYYY-MM-DD)	true	-
endDate	string	The end date the asset was purchased, (YYYY-MM-DD)	true	-
price	string	The purchase price of the asset	true	-
residualValue	string	The residual value of the asset	true	-
depreciationMethod	string	The method of depreciation	true	-
estimatedUsefulLife	number	The estimated useful life in months	true	-

Request Example

{
    "voucherId": 123456,
    "projectId": 123456,
    "contractId": 123456,
    "name": "mac",
    "tag": "computer",
    "type": "liquid",
    "description": "asset discription",
    "startDate": "2024-01-01",
    "endDate": "2024-11-01",
    "price": 20,
    "residualValue": 15,
    "depreciationMethod": "stright",
    "estimatedUsefulLife": 36
}

Response

Response Parameters

Same as the POST response parameters.

Response Example

Success Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": true,
  "code": "200",
  "message": " Asset updated successfully.",
  "payload": {
    "id": 123456,
    "voucherId": 123456,
    "projectId": 123456,
    "contractId": 123456,
    "name": "mac",
    "label": "computer",
    "type": "liquid",
    "description": "asset description",
    "supplier": "apple",
    "startDate": "2024-01-01",
    "endDate": "2024-11-01",
    "price": 20,
    "residualValue": 15,
    "depreciationMethod": "stright",
    "estimatedUsefulLife": 36,
    "createdAt": 1713052800,
    "updatedAt": 1713052800
  }
}

Failure Response

{
  "powerby": "ISunFa API v1.0.0",
  "success": false,
  "code": "400",
  "message": "Failed to update asset. Invalid data provided.",
}

getAskAiResultStatusById

description: get the result status of the 'ask ai' by id

Request

Request url

GET /company/:companyId/ask_ai/:resultId/status?aiApi=vouchers

Params

name	type	description	required	default
companyId	string	specific id of the company	yes	-
resultId	string	specific id of result of the ask ai	yes	-

Query

name	type	description	required	default
aiApi	string	the api that will call AICH, use `vouchers` for voucher	yes	vouchers

Request Example

GET /company/1/ask_ai/1/status?aiApi=vouchers

Response

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	ProgressStatus enum	check below

ProgressStatus

name	type	description
ProgressStatus(enum)	string	'success', 'inProgress', 'notFound', 'alreadyUpload', 'invalidInput', 'llmError', 'systemError', 'paused', 'hasBeenUsed'

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.4+10",
    "success": true,
    "code": "200ISF0002",
    "message": "Get successfully",
    "payload": "success"
}

失敗的回傳如果 aiApi 填入的值 aich沒有相對應的api就會出現下面的樣子

{
    "powerby": "iSunFA v0.1.4+10",
    "success": false,
    "code": "404ISF0002",
    "message": "AICH API not found",
    "payload": null
}

getAskAiResultById

description: get the result of the 'ask ai' by id if the status is 'success', others will return null

Request

Request url

GET /company/:companyId/ask_ai/:resultId?aiApi=vouchers

Params

name	type	description	required	default
companyId	string	specific id of the company	yes	-
resultId	string	specific id of result of the ask ai	yes	-

Query

name	type	description	required	default
aiApi	string	the api that will call AICH, use `vouchers` for voucher	yes	vouchers

Request Example

GET /company/1/ask_ai/1?aiApi=vouchers

Response

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	any	Depend on which `aiApi` you provide, return IVoucherDataForSavingToDB if "vouchers"

IVoucherDataForSavingToDB

name	type	description
journalId	null	this value will not be return in this api, since `IVoucherDataForSavingToDB` is both using in POST and GET voucher, journalId will only be used when POSTing voucher
lineItems	ILineItem[]	Line items of voucher, each line item represent each line in url voucher

ILineItem

name	type	description
lineItemIndex	string	The unique index of the line item entry. But this has no actual meaning, just random response from aich, real id will be number and store in db
account	string	The account associated with the line item.
description	string	A detailed description of the line item.
debit	boolean	Indicates if the item is a debit (true) or credit (false).
amount	number	The monetary amount of the line item.
accountId	number	The account id of the line item.

Response Example

成功的回傳 If providing aiApi=voucher:

{
    "powerby": "iSunFA v0.1.4+10",
    "success": true,
    "code": "200ISF0002",
    "message": "Get successfully",
    "payload": {
        "lineItems": [
            {
                "lineItemIndex": "20240426001",
                "account": "電信費",
                "description": "光世代電路月租費： 593, HiNet企業專案服務費: 1607",
                "debit": true,
                "amount": 2210,
                "accountId": 1234
            },
            {
                "lineItemIndex": "20240325002",
                "account": "進項稅額",
                "description": "WSTP會計師工作輔助幡: 88,725, 文中網路版主機授權費用: 8,400, 文中工作站授權費用: 6,300",
                "debit": true,
                "amount": 110,
                "accountId": 4321,
            },
            {
                "lineItemIndex": "20240426003",
                "account": "銀行存款",
                "description": "合庫銀行",
                "debit": false,
                "amount": 2310,
                "accountId": 4424,
            }
        ]
    }
}

失敗的回傳如果 aiApi 填入的值 aich沒有相對應的api就會出現下面的樣子

{
    "powerby": "iSunFA v0.1.4+10",
    "success": false,
    "code": "404ISF0002",
    "message": "AICH API not found",
    "payload": null
}

companyKYC

description: KYC for entity

Request

Request url

POST /company/:companyId/kyc

body

name	type	description	required	default
companyKYCForm	CompanyKYCForm	company kyc info	true	-

CompanyKYCForm

name	type	description	required	default
legalName	string	entity's name	true	-
country	CountryOptions	country	true	-
city	string	city	true	-
address	string	entity's address	true	-
zipCode	string	zip code	true	-
representativeName	string	representative's name	true	-
structure	LegalStructureOptions	structure	true	-
registrationNumber	string	registration number	true	-
registrationDate	string	registration date	true	-
industry	IndustryOptions	registration industry	true	-
contactPerson	string	contact person name	true	-
contactPhone	string	contact phone	true	-
contactEmail	string	contact email	true	-
website	string	website	false	-
registrationCertificateId	string	registration certificate	true	-
taxCertificateId	string	tax certificate	true	-
representativeIdType	RepresentativeIDType	representative id type	true	-
representativeIdCardId	string	representative id card	true	-

CountryOptions

export enum CountryOptions {
  DEFAULT = '',
  TAIWAN = 'Taiwan',
  UNITED_STATES = 'United States',
  CHINA = 'China',
  HONG_KONG = 'Hong Kong',
}

LegalStructureOptions

export enum LegalStructureOptions {
  DEFAULT = '', 
  SOLE_PROPRIETORSHIP = 'Sole Proprietorship',
  PARTNERSHIP = 'Partnership',
  CORPORATION = 'Corporation',
  LIMITED_LIABILITY_COMPANY = 'Limited Liability Company',
}

IndustryOptions

export enum IndustryOptions {
  DEFAULT = '',
  ACCOMMODATION_AND_FOOD_SERVICES = 'Accommodation and food services',
  ADMINISTRATIVE_AND_SUPPORT_SERVICES = 'Administrative and support services',
  ARTS_AND_RECREATION_SERVICES = 'Arts and Recreation services',
  BASIC_METAL_PRODUCTION = 'Basic metal production',
  BUSINESS_FRANCHISES = 'Business franchises',
  CHEMICAL_SUBSTANCE = 'Chemical substance',
  COMMERCE = 'Commerce',
  COMPUTER_AND_ELECTRONIC_PRODUCT = 'Computer and Electronic Product',
  CONSTRUCTION = 'Construction',
  EDUCATION = 'Education',
  FINANCE_AND_INSURANCE = 'Finance and insurance',
  FINANCIAL_SERVICES = 'Financial services',
  FOOD_INDUSTRY = 'Food industry',
  HEALTHCARE_AND_SOCIAL_ASSISTANCE = 'Healthcare and social assistance',
  INFORMATION = 'Information',
  MINING = 'Mining',
  OTHER_SERVICE_ACTIVITIES = 'Other service activities',
  PERSONAL_SERVICES = 'Personal services',
  REAL_ESTATE_ACTIVITIES = 'Real estate activities',
  RETAIL = 'Retail',
  THEMATIC_REPORTS = 'Thematic reports',
  TRANSPORT_INDUSTRY = 'Transport industry',
}

RepresentativeIDType

export enum RepresentativeIDType {
  PASSPORT = 'PASSPORT',
  ID_CARD = 'ID_CARD',
  DRIVER_LICENSE = 'DRIVER_LICENSE',
}

Request Example

POST /company/1/kyc

const companyKYCForm = {
  "legalName": "台灣科技有限公司",
  "country": "Taiwan",
  "city": "台北市",
  "address": "信義路五段7號",
  "zipCode": "110",
  "representativeName": "王小明",
  "structure": "Limited Liability Company",
  "registrationNumber": "12345678",
  "registrationDate": "2020-01-15",
  "industry": "Technology",
  "contactPerson": "李小華",
  "contactPhone": "+886912345678",
  "contactEmail": "[email protected]",
  "website": "https://www.taiwantech.com",
  "registrationCertificateId": "RC123456789",
  "taxCertificateId": "TC987654321",
  "representativeIdType": "ID_CARD",
  "representativeIdCardId": "A123456789"
}

Response

Response Parameters

name	type	description
powerby	string	ISunFa api 1.0.0
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	CompanyKYC	response data

CompanyKYC

name	type	description
id	number	companyKYC's id
companyId	number	company's id
legalName	string	entity's name
country	string	country
city	string	city
address	string	entity's address
zipCode	string	zip code
representativeName	string	representative's name
structure	string	structure
registrationNumber	string	registration number
registrationDate	string	registration date
industry	string	registration industry
contactPerson	string	contact person name
contactPhone	string	contact phone
contactEmail	string	contact email
website	string	website
representativeIdType	string	representative id type
registrationCertificateId	string	registration certificate id
taxCertificateId	string	tax certificate id
representativeIdCardId	string	representative id card id
status	string	review status
reviewer	string	reviewer name
note	string	if any note
reviewAt	number	review time
createdAt	number	create time
updatedAt	number	update time
deletedAt	number	deleted time

Response Example

成功的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": true,
    "code":  "200",
    "message": "KYC for entity",
    "payload": {
          "id":1,
          "companyId": 1,
          "legalName": "mermer",
          "country": "Taiwan",
          "city": "Taipei",
          "address": "106-Taipei-xinyi road",
          "zipCode": "106",
          "representativeName": "bob",
          "structure": "Limited Liability Company",
          "registrationNumber": "123456",
          "registrationDate": "2021-01-01",
          "industry": "Information",
          "contactPerson": "bob",
          "contactPhone": "0912345678",
          "contactEmail": "[email protected]",
          "website": "www.mermer.cc",
          "representativeIdType": "ID_CARD",
          "registrationCertificateId": "1",
          "taxCertificateId": "2",
          "representativeIdCardId": "3",
          "status": "完成",
          "reviewer": "Emma",
          "note": "無",
          "reviewAt": 123456,
          "createdAt": 123456,
          "updatedAt": 123456,
          "deletedAt": null
    }
}

失敗的回傳

{
    "powerby": "ISunFa api 1.0.0",
    "success": false,
    "code":  "422",
    "message": "invalid input parameter",
    "payload": {}
}

getAuditReports

description: This API provides the functionality to query financial reports information of various companies.

Request

Request url

GET /audit_report

Query

name	type	description	required	default
region	string	only return results for a specific region	no	-
page	string	specify the page number of results to return	no	1
limit	string	the maximum number of results to return per page	no	10
begin	string	only return results after this date(timestamp)	no	-
end	string	only return results before this date(timestamp)	no	-
search	string	only return results that include a specific keyword	no	-

Request Example

example 1

GET `/audit_report`

example 2

GET `/audit_report?&begin=1713755682&search=DA 1175`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	AuditReports[] \| null	array of response data

AuditReports

name	type	description
id	number	unique id of the report
code	string	company code
regional	string	region of the company
company	string	company name
companyId	number	unique id of the company
informationYear	string	financial report year
detailedInformation	string	detailed financial report name
creditRating	string	credit rating
dateOfUpload	string	date of upload
link	string	URL link

Response Example

example 2
- 成功的回傳

  {
  "powerby": "iSunFA v0.1.5+19",
  "success": true,
  "code": "200ISF0002",
  "message": "Get successfully",
  "payload": [
    {
      "id": 1,
      "companyId": 8867,
      "code": "20206111752",
      "regional": "Taiwan",
      "company": "CNN",
      "informationYear": "2024 Q1",
      "detailedInformation": "Cash Flow Balance Sheet-20240423-1-20240420-1",
      "creditRating": "AA",
      "dateOfUpload": "1713815673",
      "link": "https: //BFample.com/download/report.pdf"
    },
    {
      "id": 3,
      "companyId": 8867,
      "code": "20206111752",
      "regional": "Taiwan",
      "company": "CNN",
      "informationYear": "2024 Q3",
      "detailedInformation": "Balance Sheet-20240427-1",
      "creditRating": "AAA",
      "dateOfUpload": "1714220640",
      "link": "https: //BFample.com/download/report.pdf"
    },
    {
      "id": 4,
      "companyId": 8867,
      "code": "20206111752",
      "regional": "Taiwan",
      "company": "CNN",
      "informationYear": "2024 Q4",
      "detailedInformation": "Comprehensive Income Statement-20240422-1",
      "creditRating": "C",
      "dateOfUpload": "1713755682",
      "link": "https: //BFample.com/download/report.pdf"
    },
    {
      "id": 5,
      "companyId": 8867,
      "code": "20206111752",
      "regional": "Taiwan",
      "company": "CNN",
      "informationYear": "DAILY",
      "detailedInformation": "Balance Sheet-20240429-1",
      "creditRating": "BB",
      "dateOfUpload": "1714331987",
      "link": "https: //BFample.com/download/report.pdf"
    },
    {
      "id": 6,
      "companyId": 6146,
      "code": "國立政治大學",
      "regional": "Taiwan",
      "company": "國立政治大學",
      "informationYear": "DAILY",
      "detailedInformation": "Balance Sheet-20240429-1",
      "creditRating": "BB",
      "dateOfUpload": "1714331987",
      "link": "https: //BFample.com/download/report.pdf"
    }
   ]
  }

- 失敗的回傳

```json
{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": null
}
```

createAVoucher

Description:
- Save voucher data into database, POST body need to be IVoucherDataForSavingToDB Type, It will create voucher and related line items in database, and return the created result.
- logic flow:
  - 1. Check and Format Body to IVoucherDataForSavingToDB
  - 1. Create a new voucher
  - 1. Create a new line item for the voucher, and connect to the voucher
  - 1. Return voucher (type will be Prisma.voucher)

Request

Request url

POST /company/:companyId/voucher

Body

name	type	description	require
voucher	IVoucherDataForSavingToDB	read down below, this combine two data, journalId and lineItems	true

IVoucherDataForSavingToDB

name	type	description	require
journalId	number	the index of journal that will be connect to new voucher	true
lineItems	ILineItem[]	the line items of the voucher (ILineItems need to have accountId)	true

Request Example

POST /company/1/voucher

Body: JSON type

{
    "voucher": {
        "journalId": 15,
        "lineItems": [
            {
                "lineItemIndex": "'20240426001'",
                "account": "'電信費'",
                "description": "'光世代電路月租費： 593, HiNet企業專案服務費: 1607'",
                "debit": true,
                "amount": 2210,
                "accountId": 1
            },
            {
                "lineItemIndex": "'20240325002'",
                "account": "'進項稅額'",
                "description": "'WSTP會計師工作輔助幡: 88,725, 文中網路版主機授權費用: 8,400, 文中工作站授權費用: 6,300'",
                "debit": true,
                "amount": 110,
                "accountId": 2
            },
            {
                "lineItemIndex": "'20240426003'",
                "account": "'銀行存款'",
                "description": "'合庫銀行'",
                "debit": false,
                "amount": 2310,
                "accountId": 3
            }
        ]
    }
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Custom type \| null	the shape of data has no interface, but it follows Prisma.voucher

payload custom type

name	type	description
id	number	the id of the voucher that was created
journalId	number	the journal that the voucher connect to
no	string	the voucher serial number, it will increase base on company, format is `YYYYMMDD001`
createdAt	number	the timestamp of the voucher created (timestamp in second)
updatedAt	number	the timestamp of the voucher updated (timestamp in second)
deletedAt	number	the timestamp of the voucher deleted (timestamp in second)
lineItems	Prisma.LineItem[] \| null	the lineItems that was created

Prisma.LineItem

name	type	description
id	number	the id of the lineItem
amount	number	the amount of the lineItem
description	string	the description of the lineItem
debit	boolean	is debit or credit
accountId	number	the account that the lineItem connect to
voucherId	number	the voucher that the lineItem connect to
createdAt	number	the timestamp of the lineItem created (timestamp in second)
updatedAt	number	the timestamp of the lineItem updated (timestamp in second)
deletedAt	number	the timestamp of the lineItem deleted (timestamp in second)

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.4+78",
    "success": true,
    "code": "201ISF0000",
    "message": "Created successfully",
    "payload": {
        "id": 1,
        "journalId": 1,
        "no": "2024617001",
        "createdAt": 1718612861,
        "updatedAt": 1718612861,
        "deletedAt": null,
        "lineItems": [
            {
                "id": 2,
                "amount": 110,
                "description": "'WSTP會計師工作輔助幡: 88,725, 文中網路版主機授權費用: 8,400, 文中工作站授權費用: 6,300'",
                "debit": true,
                "accountId": 61,
                "voucherId": 1,
                "createdAt": 1718612861,
                "updatedAt": 1718612861,
                "deletedAt": null
            },
            {
                "id": 1,
                "amount": 2210,
                "description": "'光世代電路月租費： 593, HiNet企業專案服務費: 1607'",
                "debit": true,
                "accountId": 61,
                "voucherId": 1,
                "createdAt": 1718612861,
                "updatedAt": 1718612861,
                "deletedAt": null
            },
            {
                "id": 3,
                "amount": 2310,
                "description": "'合庫銀行'",
                "debit": false,
                "accountId": 61,
                "voucherId": 1,
                "createdAt": 1718612861,
                "updatedAt": 1718612861,
                "deletedAt": null
            }
        ]
    }
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code":  "502",
  "message": "Bad gateway data from AICH is invalid type",
  "payload": {}
}

createReport

description: Create a report based on the given date and financial statement name. Base on financial statement name, startDate and endDate, this API will find if the report has been generated or not, if the report has been generated it will return the ID of that report, if not it will create a new report and return the id of that report. This API will generate the report base on lastPeriodStartDate and lastPeriodEndDate (which base on startDate minus one year and endDate minus one year), and will return the ID of the last period report if it has been generated.

Request

Request URL

POST /company/:companyId/report

Query

name	type	description	require	default
projectId	numeric \| undefined	which project this financial report will link to, it will be set as null if: 1. not provided, 2.provide null or undefined 3. provide other non numeric words	false	undefined
type	ReportSheetType	which financial statement you want to create, see description below, it will be BalanceSheet if not provided	false	BalanceSheet
reportLanguage	string	this query is not implemented, it will only add language tag to report name	false	"tw"
from	timestamp in second (millisecond will be transform into second if provided)	start date of the financial report period, it will be set to 0 if choosing BalanceSheet as reportType, this number minus 1 year will be the start date of last period	false	first second of this year
to	timestamp in second (millisecond will be transform into second if provided)	end date of the financial report period, this number minus 1 year will be the start date of last period	false	last second of today
reportType	string	since report_financial and report_analysis might be combined, use "financial" (or not provided) to actually generate financial report, it will be "financial" if not provided	false	"financial"

ReportSheetType

name	type	description
BALANCE_SHEET	string	it represent "balance_sheet"
INCOME_STATEMENT	string	it represent "comprehensive_income_statement"
CASH_FLOW_STATEMENT	string	it represent "cash_flow_statement"
REPORT_401	string	it represent "report_401"

Response

name	type	description
id	number	the id of the report generated or found

Success Response

{
  "powerby": "iSunFA v0.1.8+36",
  "success": true,
  "code": "201ISF0000",
  "message": "Created successfully",
  "payload": 10000001
}

Error Response

{
  "powerby": "iSunFA v0.1.8+36",
  "success": false,
  "code": "400ISF0001",
  "message": "Invalid request",
  "payload": -1
}

getReportById

description: get Report by id, it will return Balance sheet, Income statement or Cash flow or 401 report

Request

Request url

GET /company/:companyId/report/:reportId

Params

name	type	description	required	default
reportId	number	specific id of the report	yes	-

Request Example

GET /company/1/report/1

Response

Response Parameter

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description
payload	FinancialReport or Report(only for 401 report)	the data

FinancialReport

name	type	description
company	`{id: number, code: string, name: string}`	company related info
preDate	`{from: number, to: number }`	last period time spam, it will be same date of curDate last year
curDate	`{from: number, to: number }`	it will be from and to of current date
reportType	ReportSheetType `{ BALANCE_SHEET = 'balance_sheet', INCOME_STATEMENT = 'comprehensive_income_statement', CASH_FLOW_STATEMENT = 'cash_flow_statement', REPORT_401 = 'report_401',}`	Financial Report type
general	FinancialReportItem[]	simplified version of financial report rows
details	FinancialReportItem[]	detail version of financial report rows
otherInfo	BalanceSheetOtherInfo \| IncomeStatementOtherInfo \| CashFlowStatementOtherInfo	base on your financial report type, it will return different info

FinancialReportItem

name	type	description
code	string	code of accounting
name	string	name of accounting
curPeriodAmount	number	this period amount of money
curPeriodAmountString	string	this period amount of money but in string, it will be brackets if negative
curPeriodPercentage	string	percentage of amount vs total amount of that account category
prePeriodAmount	number	last period amount of money
prePeriodAmount	string	last period amount of money but in string, it will be brackets if negative
prePeriodPercentage	string	percentage of amount vs total amount of that account category
indent	number	what level of this account in account tree

BalanceSheetOtherInfo

name	type	description
assetLiabilityRatio	`{[date: string]: {data: number[], labels: string[]}}`	data 和 labels 的順序是 [資產, 負債, 權益]，key 則是日期 YYYY-MM-DD
assetMixRatio	`{[date: string]: {data: number[], labels: string[]}}`	data 和 labels 的順序是 [資產, 負債, 權益]，key 則是日期 YYYY-MM-DD
dso	`{ curDso: number; preDso: number;}`	應收週轉天數：curDso 是本期，preDso 是上期
inventoryTurnoverDays	`{ curInventoryTurnoverDays: number; preInventoryTurnoverDays: number; };`	存貨週轉天數： curInventoryTurnoverDays 是本期， preInventoryTurnoverDays 是上期

IncomeStatementOtherInfo

name	type	description
revenueAndExpenseRatio	Check Below	投入費用和成本, 與收入的倍數關係
revenueToRD	Check Below	收入提撥制研發費用比例

RevenueAndExpenseRatio

name	type	description
revenue	IAccountReadyForFrontend	revenue data of current year income statement
totalCost	IAccountReadyForFrontend	total Cost(not expense) of current year income statement
salesExpense	IAccountReadyForFrontend	sale expense data of current year income statement
administrativeExpense	IAccountReadyForFrontend	admin expense data of current year income statement
ratio	`{curRatio: number; preRatio: number;};`	ratio of revenue/(cost + expense)

RevenueToRD

name	type	description
revenue	IAccountReadyForFrontend	revenue data of current year income statement
researchAndDevelopmentExpense	IAccountReadyForFrontend	Research and Development expense of current year income statement
ratio	`{curRatio: number; preRatio: number;};`	ratio of revenue/(cost + expense)

CashFlowStatementOtherInfo

name	type	description
operatingStabilized	Check Below	營業活動穩定度：A 與 B 呈現穩定比例關係，公司的營業活動穩定
lineChartDataForRatio	`{data: number[];labels: string[];}`	A 和 b 比例的線圖, labels 依照時間排列
strategyInvest	`[year: string]: {data: number[];labels: string[];};`	依照年份列出 [不動產、廠房、設備的收支項目, 策略性投資項目, 其他] data 是資料內容，labels 是資料名稱
thirdTitle	string	三：營業活動穩定度的標題內容
forthTitle	String	四：投資活動 - 「不動產, 廠房及設備」及「策略性投資」的標題內容
fourPointOneTitle	String	四之一：202X 年度上圖組成支系項及 ISunFa 認為
ourThoughts	String[] (length is 3)	四之一的段落內容: outThoughts[0] 是第一段(不動產, 廠房, 設備的收支項目)，outThoughts[1] 是第二段（策略性投資項目），outThoughts[2] 是第三段(其他)
freeCash	Check Below	五、年度產生的自由現金圖表資料

OperatingStabilized

name	type	description
beforeTaxIncome	[year: string]: number	5 period (current year ~ current year - 4) of income before tax
amortizationDepreciation	[year: string]: number	5 period (current year ~ current year - 4) of amortization and depreciation
tax	[year: string]: number	5 period (current year ~ current year - 4) of tax expense
operatingIncomeCashFlow	[year: string]: number	5 period (current year ~ current year - 4) of operating income cash flow
ratio	[year: string]: number	5 period (current year ~ current year - 4) of (beforeTaxIncome + amortizationDepreciation + tax) / operatingIncomeCashFlow

FreeCash

  freeCash: {
    [year: string]: {
      operatingCashFlow: number;
      ppe: number;
      intangibleAsset: number;
      freeCash: number;
    };
  };

name	type	description
[year]	string	以年份當作 key, 有今年度和去年度資料
operatingCashFlow	number	營業活動產生的現金流量
ppe	number	不動產、廠房及設備的收支項目
intangibleAsset	number	無形資產的收支項目
freeCash	number	自由現金流量

Response example

{
  "powerby": "iSunFA v0.1.8+101",
  "success": true,
  "code": "200ISF0000",
  "message": "Success",
  "payload": {
    "company": {
      "id": 10000131,
      "code": "123456",
      "name": "aaa"
    },
    "reportType": "incomeStatement",
    "preDate": {
      "from": 1688140800,
      "to": 1690732799
    },
    "curDate": {
      "from": 1719763200,
      "to": 1722355199
    },
    "details": [
      {
        "code": "",
        "name": "營業收入",
        "curPeriodAmount": 0,
        "curPeriodPercentage": 0,
        "curPeriodAmountString": "0",
        "prePeriodAmount": 0,
        "prePeriodPercentage": 0,
        "prePeriodAmountString": "0",
        "indent": 0
      },...
    ],
    "general": [
      {
        "code": "4000",
        "name": "營業收入合計",
        "curPeriodAmount": 0,
        "curPeriodPercentage": 0,
        "curPeriodAmountString": "0",
        "prePeriodAmount": 0,
        "prePeriodPercentage": 0,
        "prePeriodAmountString": "0",
        "indent": 0
      },...
    ],
  "otherInfo": {
      "revenueAndExpenseRatio": {
        "revenue": {
          "code": "4000",
          "name": "營業收入合計",
          "curPeriodAmount": 0,
          "curPeriodPercentage": 0,
          "curPeriodAmountString": "0",
          "prePeriodAmount": 0,
          "prePeriodPercentage": 0,
          "prePeriodAmountString": "0",
          "indent": 0
        },
        "totalCost": {
          "code": "5000",
          "name": "營業成本合計",
          "curPeriodAmount": 0,
          "curPeriodPercentage": 0,
          "curPeriodAmountString": "0",
          "prePeriodAmount": 0,
          "prePeriodPercentage": 0,
          "prePeriodAmountString": "0",
          "indent": 0
        },
        "salesExpense": {
          "code": "6100",
          "name": "推銷費用",
          "curPeriodAmount": 0,
          "curPeriodPercentage": 0,
          "curPeriodAmountString": "0",
          "prePeriodAmount": 0,
          "prePeriodPercentage": 0,
          "prePeriodAmountString": "0",
          "indent": 0
        },
        "administrativeExpense": {
          "code": "6200",
          "name": "管理費用",
          "curPeriodAmount": 0,
          "curPeriodPercentage": 0,
          "curPeriodAmountString": "0",
          "prePeriodAmount": 0,
          "prePeriodPercentage": 0,
          "prePeriodAmountString": "0",
          "indent": 0
        },
        "ratio": {
          "curRatio": 0,
          "preRatio": 0
        }
      },
      "revenueToRD": {
        "revenue": {
          "code": "4000",
          "name": "營業收入合計",
          "curPeriodAmount": 0,
          "curPeriodPercentage": 0,
          "curPeriodAmountString": "0",
          "prePeriodAmount": 0,
          "prePeriodPercentage": 0,
          "prePeriodAmountString": "0",
          "indent": 0
        },
        "researchAndDevelopmentExpense": {
          "code": "6300",
          "name": "研究發展費用",
          "curPeriodAmount": 0,
          "curPeriodPercentage": 0,
          "curPeriodAmountString": "0",
          "prePeriodAmount": 0,
          "prePeriodPercentage": 0,
          "prePeriodAmountString": "0",
          "indent": 0
        },
        "ratio": {
          "curRatio": 0,
          "preRatio": 0
        }
      }
    }
  }
}

getAllAccounts

description: This API provides the functionality to get all accounting accounts with pagination.

Request

Request url

GET `/company/:companyId/account`

Query

When undefined is provided (or not provided that query), that query will be ignored, which means all accounts will be provided

name	type	description	required	default
companyId	number	specific id of the company	yes	-
includeDefaultAccount	boolean	whether including default account	no	undefined
liquidity	boolean	whether containing liquidity	no	undefined
type	string	which AccountType	no	undefined
reportType	string	which ReportSheetType	no	undefined
equityType	string	which EquityType	no	undefined
forUser	boolean	whether used by user	no	undefined
page	number	page number	no	1
limit	number	items per page	no	10
sortBy	string	sort by 'code' or 'createdAt'	no	'code'
sortOrder	string	sort order 'asc' or 'desc'	no	'asc'
searchKey	string	search keywords	no	undefined

AccountType
- asset, liability, equity, revenue, cost, income, expense, gainOrLoss, otherComprehensiveIncome, cashFlow, changeInEquity, other
ReportSheetType
- balanceSheet, incomeStatement, cashFlowStatement, changeInEquityStatement
EquityType
- stock, capitalSurplus, retainedEarnings, otherEquity

Request Example

GET `/company/1/account?limit=2`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	IPaginatedAccount \| null	response data

IPaginatedAccount

name	type	description
data	IAccount[]	the data of the current page
page	number	the current page number
totalPages	number	the total number of pages
totalCount	number	the total number of items
pageSize	number	the number of items per page
hasNextPage	boolean	whether there is a next page
hasPreviousPage	boolean	whether there is a previous page
sort	{ sortBy: string; sortOrder: string; }[]	the sorting criteria

IAccount

name	type	description
id	number	the unique id of the updated account
companyId	number	the id of the company
system	string	the name of the system which the account belongs to
type	string	AccountType
debit	boolean	whether it is a debit
liquidity	boolean	whether its liquidity is current
code	string	the code number of the accounting account
name	string	the name / note of the accounting account
createdAt	number	the creation timestamp
updatedAt	number	the update timestamp
deletedAt	number or null	the deletion timestamp

AccountType

'asset'
'liability'
'equity'
'revenue'
'cost'
'income'
'expense'
'gainOrLoss'
'otherComprehensiveIncome'
'cashFlow'
'changeInEquity'
'other' |

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.8+103",
  "success": true,
  "code": "200ISF0000",
  "message": "Success",
  "payload": {
    "data": [
      {
        "id": 10000540,
        "companyId": 99999991,
        "system": "IFRS",
        "type": "asset",
        "liquidity": true,
        "debit": true,
        "code": "1101",
        "name": "庫存現金",
        "createdAt": 0,
        "updatedAt": 0,
        "deletedAt": null
      },
      {
        "id": 10000541,
        "companyId": 99999991,
        "system": "IFRS",
        "type": "asset",
        "liquidity": true,
        "debit": true,
        "code": "1102",
        "name": "零用金／週轉金",
        "createdAt": 0,
        "updatedAt": 0,
        "deletedAt": null
      }
    ],
    "page": 1,
    "totalPages": 467,
    "totalCount": 934,
    "pageSize": 2,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "sort": [
      {
        "sortBy": "code",
        "sortOrder": "asc"
      }
    ]
  }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": null
}

getAccountById

description:
- Get one account (會計科目) of certain companyId or that is regulated by government (which companyId is 1002), and return the account data in the response, can not get the account that is customized by other company

Request

Request url

GET /company/:companyId/account/:accountId

Query

name	type	description	required	default
companyId	number	specific id of the company	yes	-
accountId	number	specific id of the account	yes	-

Request Example

GET /company/1/account/1

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	IAccount	check below

IAccount

name	type	description
id	number	the id of the account
companyId	number	the company that the account belong to
system	string	the system that the account belong to
type	AccountType	the type of account, "asset", "liability" , "equity", "income", "expense", "otherComprehensiveIncome"
liquidity	boolean	the liquidity of account (current or not current)
debit	boolean	the debit of account (debit or credit)
code	string	the code of account, can use this code to mapping in18 multi-language json file
name	string	the name of account, this value is custom by user, it should be empty string if this account is regulated by government
createdAt	number	the timestamp of the account created (timestamp in second)
updatedAt	number	the timestamp of the account updated (timestamp in second)
deletedAt	number	the timestamp of the account deleted (timestamp in second)

Response example

成功的回傳

{
    "powerby": "iSunFA v0.1.5+1",
    "success": true,
    "code": "200ISF0000",
    "message": "Success",
    "payload": {
        "id": 1,
        "companyId": 1,
        "system": "IFRS",
        "type": "Expense",
        "liquidity": true,
        "debit": true,
        "code": "0100005",
        "name": "營業成本",
        "createdAt": 1718681566,
        "updatedAt": 1718681566,
        "deletedAt": null,
    }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "422ISF0000",
    "message": "Invalid input parameters",
    "payload": {}
}

createNewSubAccountingAccount

description: This API provides the functionality to create a new sub accounting account.

Request

Request url

POST `/company/:companyId/account`

Body

name	type	description	required	default
accountId	number	the unique number of the parent accounting account	yes	-
name	string	the name / note of the accounting account	yes	-

Request Example

POST `/company/1/account`

const body = {
  "accountId": 251,
  "name": "華奇銀行"
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the put
payload	Account	response data

Account

name	type	description
id	number	the unique id of the updated account
companyId	number	the id of the company
system	string	the name of the system which the account belongs to
type	string	AccountType
debit	boolean	whether it is a debit
liquidity	boolean	whether its liquidity is current
code	string	the code number of the accounting account
name	string	the name / note of the accounting account
createdAt	number	the creation timestamp
updatedAt	number	the update timestamp
deletedAt	number	the deletion timestamp

AccountType

'asset'
'liability'
'equity'
'revenue'
'cost'
'income'
'expense'
'gainOrLoss'
'otherComprehensiveIncome'
'cashFlow'
'changeInEquity'
'other'

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.6+11",
    "success": true,
    "code": "201ISF0000",
    "message": "Created successfully",
    "payload": {
        "id": 1478,
        "companyId": 1,
        "system": "IFRS",
        "type": "asset",
        "debit": true,
        "liquidity": true,
        "code": "1100-1",
        "name": "華奇銀行",
        "forUser": true,
        "parentCode": "1100",
        "rootCode": "1100",
        "createdAt": 1719997790,
        "updatedAt": 1719997790,
        "level": 3,
        "deletedAt": null
    }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "create failed",
    "payload": {}
}

updateOwnAccountInfoById

description: This API provides the functionality to update the information(name) of owned account.

Request

Request url

PUT `/company/:companyId/account/:accountId`

Param

name	type	description	required	default
accountId	string	the unique id of the account to be updated	yes	-

Body

name	type	description	required	default
name	string	the name / note of the accounting account	yes	-

Request Example

PUT `/company/99999991/account/1474`

const body = {
  "name": "華奇銀行2"
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the put
payload	Account	response data

Account

name	type	description
id	number	the unique id of the updated account
companyId	number	the id of the company
system	string	the name of the system which the account belongs to
type	string	AccountType
debit	boolean	whether it is a debit
liquidity	boolean	whether its liquidity is current
code	string	the code number of the accounting account
name	string	the name / note of the accounting account
createdAt	number	the creation timestamp
updatedAt	number	the update timestamp
deletedAt	number	the deletion timestamp

AccountType

'asset'
'liability'
'equity'
'revenue'
'cost'
'income'
'expense'
'gainOrLoss'
'otherComprehensiveIncome'
'cashFlow'
'changeInEquity'
'other'

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.6+9",
    "success": true,
    "code": "200ISF0003",
    "message": "Update successfully",
    "payload": {
        "id": 1474,
        "companyId": 99999991,
        "system": "IFRS",
        "type": "asset",
        "liquidity": true,
        "debit": true,
        "code": "1100-1",
        "name": "華奇銀行2",
        "createdAt": 0,
        "updatedAt": 0,
        "deletedAt": 0
    }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "update failed",
    "payload": {}
}

deleteOwnAccountById

description: This API provides the functionality to delete an owned account by update deleted time.

Request

Request url

DELETE `/company/:companyId/account/:accountId`

Param

name	type	description	required	default
accountId	string	the unique id of the account to be deleted	yes	-

Request Example

DELETE `/company/99999991/account/1474`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the put
payload	Account	response data

Account

name	type	description
id	number	the unique id of the updated account
companyId	number	the id of the company
system	string	the name of the system which the account belongs to
type	string	AccountType
debit	boolean	whether it is a debit
liquidity	boolean	whether its liquidity is current
code	string	the code number of the accounting account
name	string	the name / note of the accounting account
createdAt	number	the creation timestamp
updatedAt	number	the update timestamp
deletedAt	number	the deletion timestamp

AccountType

'asset'
'liability'
'equity'
'revenue'
'cost'
'income'
'expense'
'gainOrLoss'
'otherComprehensiveIncome'
'cashFlow'
'changeInEquity'
'other'

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.6+9",
    "success": true,
    "code": "200ISF0004",
    "message": "Delete successfully",
    "payload": {
        "id": 1474,
        "companyId": 99999991,
        "system": "IFRS",
        "type": "asset",
        "liquidity": true,
        "debit": true,
        "code": "1100-1",
        "name": "華奇銀行2",
        "createdAt": 0,
        "updatedAt": 0,
        "deletedAt": 1719913324
    }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "delete failed",
    "payload": {}
}

getAllEmployees

description: This API provides the functionality to get all employees information.

Request

Request url

GET `/company/:companyId/employee`

Query

name	type	description	required	default
companyId	string	specific id of the company	yes	-
targetPage	string	the page number to be retrieved	false	1
pageSize	string	the number of items per page	false	10
searchQuery	string	the query string used to search for specific items	false	""

Request Example

GET `/company/10000000/employee?targetPage=2&pageSize=2`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	IEasyEmployeeWithPagination \| null	response data

IEasyEmployeeWithPagination

name	type	description
data	IEasyEmployee[]	an array of employee data
page	number	the current page number
totalPages	number	the total number of pages
totalCount	number	the total number of records
pageSize	number	the number of records per page
hasNextPage	boolean	indicates if there is a next page
hasPreviousPage	boolean	indicates if there is a previous page

IEasyEmployee

name	type	description
id	number	the unique identifier for the employee
name	string	the name of the employee
salary	number	the salary of the employee
department	string	the department the employee belongs to
payFrequency	string	the frequency of salary payment

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.8+52",
  "success": true,
  "code": "200ISF0001",
  "message": "List successfully",
  "payload": {
    "data": [
      {
        "id": 10000002,
        "name": "cook",
        "department": "Engineering",
        "payFrequency": "monthly",
        "salary": 4000
      },
      {
        "id": 10000004,
        "name": "bee",
        "department": "Marketing",
        "payFrequency": "Monthly",
        "salary": 45000
      }
    ],
    "page": 2,
    "totalPages": 2,
    "totalCount": 4,
    "pageSize": 2,
    "hasNextPage": false,
    "hasPreviousPage": true
  }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": null
}

getAnEmployee

description: This API provides the functionality to query specific employee information.

Request

Request url

GET `/company/:companyId/employee/:employeeId`

Query

name	type	description	required	default
companyId	string	specific id of the company	yes	-
employeeId	string	specific employee number	yes	-

Request Example

GET `/company/1/employee/3`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	IEmployeeData \| {}	response data

IEmployeeData

name	type	description
id	number	the unique identifier of the employee
name	string	the name of the employee
salary	number	the salary of the employee
department	string	the department the employee belongs to
start_date	number	the start date of the employee's employment (timestamp)
bonus	number	the bonus for the employee
salary_payment_mode	string	the mode of salary payment
pay_frequency	string	the frequency of salary payment
projects	{ id: number, name: string }[]	the projects the employee is involved in
insurance_payments	number	the employee insurance paid by the employer
additionalOfTotal	number	the additional amount of salary, bonus, and insurance_payments

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.8+52",
  "success": true,
  "code": "200ISF0002",
  "message": "Get successfully",
  "payload": {
    "id": 10000000,
    "name": "aook",
    "salary": 200000,
    "department": "Engineering",
    "start_date": 1630435200,
    "bonus": 1000,
    "salary_payment_mode": "Cash",
    "pay_frequency": "Monthly",
    "projects": [
      {
        "id": 9999991,
        "name": "iSunFA"
      }
    ],
    "insurance_payments": 1000,
    "additionalOfTotal": 202000
  }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": {}
}

getAllDepartments

description: This API provides the functionality to get all departments information.

Request

Request url

GET `/company/:companyId/department`

Request Example

GET `/company/1/department`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	string[] \| null	array of departments

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code":  "200",
    "message": "request successful",
    "payload": ["Marketing", "Accounting", "Human Resource", "UI/UX", "PM", "Develop"]
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": null
}

createAnEmployee

description: This API provides the functionality to create a new employee information.

Request

Request url

POST `/company/:companyId/employee`

Query

name	type	description	required	default
companyId	string	specific id of the company	yes	-

Body

name	type	description
name	string	the employee's name
salary	number	the employee's base salary
department	string	the department the employee belongs to
bonus	number	the employee's bonus
salaryPayMode	string	method of salary payment
payFrequency	string	frequency of salary payment

Request Example

POST `/company/1/employee`

Body

{   
    "name": "bee",
    "department": "Marketing",
    "salaryPayMode": "Cash",
    "payFrequency": "Monthly",
    "salary": 45000,
    "bonus": 0
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the post
payload	IEmployee \| null	response data

IEmployee

name	type	description
id	number	the unique identifier for the employee
name	string	the name of the employee
imageId	string \| undefined	the id of the employee's image, if any
departmentId	number	the id of the department the employee belongs to
companyId	number	the id of the company the employee works for
salary	number	the salary of the employee
insurancePayment	number	the employee insurance paid by the employer
bonus	number	the bonus for the employee
salaryPayMode	string	the mode of salary payment
payFrequency	string	the frequency of salary payment
startDate	number	the start date of the employee's employment (timestamp)
endDate	number \| undefined	the end date of the employee's employment, if any (timestamp)
createdAt	number	the timestamp when the employee record was created
updatedAt	number	the timestamp when the employee record was last updated

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.8+52",
    "success": true,
    "code": "201ISF0000",
    "message": "Created successfully",
    "payload": {
        "id": 10000005,
        "name": "bee",
        "departmentId": 10000000,
        "companyId": 10000000,
        "salary": 45000,
        "insurancePayment": 8823,
        "bonus": 0,
        "salaryPayMode": "Cash",
        "payFrequency": "Monthly",
        "startDate": 1721704554,
        "createdAt": 1721704554,
        "updatedAt": 1721704554
    }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "create employee failed",
    "payload": null
}

DeleteAnEmployee

description: This API provides the functionality to mark an resigned employee by updating end date.

Request

Request url

DELETE `/company/:companyId/employee/:employeeId`

Query

name	type	description	required	default
companyId	string	specific id of the company	yes	-
employeeId	string	specific employee number	yes	-

Request Example

DELETE `/company/1/employee/3`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the delete
payload	{}	-

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.8+52",
    "success": true,
    "code": "200ISF0004",
    "message": "Delete successfully",
    "payload": {}
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "delete employee failed",
    "payload": {}
}

UpdateAnEmployee

description: This API provides the functionality to update specific employee information.

Request

Request url

PUT `/company/:companyId/employee/:employeeId`

Query

name	type	description	required	default
companyId	string	specific id of the company	yes	-
employeeId	string	specific employee number	yes	-

Body

name	type	description
insurancePayment	number	the employee insurance paid by the employer
salary	number	the employee's base salary
projectIdsNames	{ id: number, name: string }[]	the projects the employee is involved in
bonus	number	the employee's bonus
salaryPayMode	string	method of salary payment
payFrequency	string	frequency of salary payment

Request Example

PUT `/company/1/employee/3`

Body

{   
    "insurancePayment": 1000,
    "salaryPayMode": "Cash",
    "payFrequency": "Monthly",
    "salary": 200000,
    "bonus": 1000,
    "projectIdsNames": [
        {
            "id": 9999991,
            "name": "iSunFA"
        },
              {
            "id": 9999992,
            "name": "BAIFA"
        }
    ]
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the update status
payload	IEmployeeData \| {}	response data

IEmployeeData

name	type	description
id	number	the unique identifier of the employee
name	string	the name of the employee
salary	number	the salary of the employee
department	string	the department the employee belongs to
start_date	number	the start date of the employee's employment (timestamp)
bonus	number	the bonus for the employee
salary_payment_mode	string	the mode of salary payment
pay_frequency	string	the frequency of salary payment
projects	{ id: number, name: string }[]	the projects the employee is involved in
insurance_payments	number	the employee insurance paid by the employer
additionalOfTotal	number	the additional amount of salary, bonus, and insurance_payments

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.8+52",
    "success": true,
    "code": "200ISF0003",
    "message": "Update successfully",
    "payload": {
        "id": 10000000,
        "name": "aook",
        "salary": 200000,
        "department": "Engineering",
        "start_date": 1630435200,
        "bonus": 1000,
        "salary_payment_mode": "Cash",
        "pay_frequency": "Monthly",
        "projects": [
            {
                "id": 9999991,
                "name": "iSunFA"
            },
            {
                "id": 9999992,
                "name": "BAIFA"
            }
        ],
        "insurance_payments": 1000,
        "additionalOfTotal": 202000
    }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "update employee information failed",
    "payload": {}
}

getAllUsers

description: This API provides the functionality to get all users.

Request

Request url

GET `/user`

Request Example

GET `/user`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	User[] \| {}	array of response data or {}

User

name	type	description
id	number	unique number of user
name	string	user name
fullName	string	user full name
email	string	user email
phone	string	user phone
imageId	string	user image id
agreementList	string[]	list of agreement hash
createdAt	number	creation timestamp
updatedAt	number	update timestamp

Response Example

成功的回傳

    {
        "powerby": "iSunFA v0.1.2+50",
        "success": true,
        "code":  "200",
        "message": "List Users successfully",
        "payload": [
          {
            "id": 1,
            "name": "John",
            "fullName": "John Doe",
            "email": "[email protected]",
            "phone": "12345678",
            "imageId": "552c2dbf-997c-4b13-957e-ea03c45d2ec1.svg",
            "agreementList": ["agreement1", "agreement2"],
            "createdAt": 1723538422,
            "updatedAt": 1723538422
          },
          {
            "id": 2,
            "name": "Jane",
            "fullName": "Jane Higher",
            "email": "[email protected]",
            "phone": "12765878",
            "imageId": "552c2dbf-997c-4b13-957e-ea03c45d2ec1.svg",
            "agreementList": ["agreement1", "agreement2"],
            "createdAt": 1723538422,
            "updatedAt": 1723538422
          }
        ]
    }

Unsuccessful Response

 {
    "powerby": "iSunFA v0.8.0+5",
    "success": false,
    "code": "401ISF0000",
    "message": "Get failed",
    "payload": {}

signUp

description: This API is used to register an user through WebAuthn.

Request

Request URL

POST `/sign-up`

Body Parameters

name	type	description	required	default
registration	RegistrationEncoded	object containing the registration details	yes	-

RegistrationEncoded

name	type	description
username	string	The name of the user registering the credential.
credential	CredentialKey	The key associated with the user's credential.
authenticatorData	string	The data provided by the authenticator during the registration process.
clientData	string	The data provided by the client during the registration process.
attestationData	string	Optional data that provides evidence of the authenticator's capabilities.

CredentialKey

name	type	description
id	string	The unique identifier for the credential.
publicKey	string	The public key used for verification.
algorithm	string	The cryptographic algorithm used, with possible values 'RS256' or 'ES256'.

Request Example

POST `/sign-up`

const body = {
  username: "Arnaud",
  credential: {
    id: "3924HhJdJMy_svnUowT8eoXrOOO6NLP8SK85q2RPxdU",
    publicKey: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgyYqQmUAmDn9J7dR5xl-HlyAA0R2XV5sgQRnSGXbLt_xCrEdD1IVvvkyTmRD16y9p3C2O4PTZ0OF_ZYD2JgTVA==",
    algorithm: "ES256"
  },
  authenticatorData: "SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2NFAAAAAAiYcFjK3EuBtuEw3lDcvpYAIN_duB4SXSTMv7L51KME_HqF6zjjujSz_EivOatkT8XVpQECAyYgASFYIIMmKkJlAJg5_Se3UecZfh5cgANEdl1ebIEEZ0hl2y7fIlgg8QqxHQ9SFb75Mk5kQ9esvadwtjuD02dDhf2WA9iYE1Q=",
  clientData: "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiYTdjNjFlZjktZGMyMy00ODA2LWI0ODYtMjQyODkzOGE1NDdlIiwib3JpZ2luIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwIiwiY3Jvc3NPcmlnaW4iOmZhbHNlfQ=="
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	User or null	response data or null

User

name	type	description
id	number	unique number of user
name	string	user name
fullName	string	user full name
email	string	user email
phone	string	user phone
imageId	string	user image id
agreementList	string[]	list of agreement hash
createdAt	number	creation timestamp
updatedAt	number	update timestamp

Response Example

成功的回傳

    {
      "powerby": "iSunFA v0.1.2+50",
      "success": true,
      "code":  "200",
      "message": "Create sucessfully",
      "payload": 
        {
          "id": 1,
          "name": "John",
          "fullName": "John Doe",
          "email": "[email protected]",
          "phone": "12345678",
          "imageId": "552c2dbf-997c-4b13-957e-ea03c45d2ec1.svg",
          "agreementList": ["agreement1", "agreement2"],
          "createdAt": 1723538422,
          "updatedAt": 1723538422
        },
    }

Unsuccessful Response

 {
    "powerby": "iSunFA v0.8.0+5",
    "success": false,
    "code": "401ISF0000",
    "message": "create failed",
    "payload": null

signOut

description: This API is used to sign out an user by clearing the FIDO2 cookie.

Request

Request URL

POST `/sign-out`

Request Example

POST `/sign-out`

Response

Response Parameters

name	type	description
success	boolean	indicates whether the operation was successful
message	string	provides a message related to the success or failure of the operation.

Response Example

Successful Response

{
  "success": true,
  "message": "Successfully signed out"
}

Unsuccessful Response

{
  "success": false,
  "message": "Failed to sign out"
}

getSession

description: This API provides the functionality to get the session information.

Request

Request URL

GET `/session`

Request Example

GET `/session`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	{user: User, company: Company}	response data or {}

Company

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start date of the company
createdAt	number	create timestamp of the company
updatedAt	number	update timestamp of the company

User

name	type	description
id	number	unique number of user
name	string	user name
fullName	string	user full name
email	string	user email
phone	string	user phone
imageId	string	user image id
agreementList	string[]	list of agreement hash
createdAt	number	creation timestamp
updatedAt	number	update timestamp

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.8.0+5",
    "success": true,
    "code": "200ISF0002",
    "message": "Get successfully",
    "payload": {
        "user": {
            "id": 10000003,
            "name": "kk",
            "fullName": null,
            "email": null,
            "phone": null,
            "imageId": "552c2dbf-997c-4b13-957e-ea03c45d2ec1.svg",
            "agreementList": ["agreement1", "agreement2"],
            "createdAt": 1723538422,
            "updatedAt": 1723538422
        },
        "company": {
            "id": 10000002,
            "name": "kk",
            "code": "123",
            "regional": "Taiwan",
            "kycStatus": false,
            "imageId": "https://storage.googleapis.com/mermer-offical-km/ISunFa/e8a48a55-2d97-4dc3-89fb-0fd3947cc971.svg",
            "startDate": 1723538434,
            "createdAt": 1723538434,
            "updatedAt": 1723538434,
            "deletedAt": null
        }
    }
}

失敗的回傳

    {
      "powerby": "iSunFA v0.1.2+50",
      "success": false,
      "code": "404",
      "message": "Resource not found",
      "payload": {} 
    }

selectCompany

description: This API provides the functionality to select a company.

Request

Request URL

PUT `/company/:companyId/select`

Query

name	type	description	required	default
companyId	string	specific company number	yes	-

Request Example

PUT `/company/1/select`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	company	response data or {}

Company

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start date of the company
createdAt	number	create timestamp of the company
updatedAt	number	update timestamp of the company

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code":  "200",
  "message": "Select Company sucessfully",
  "payload": {
    "id":"1",
    "name": "iSunFA",
    "code":"168",
    "regional":"Taiwan",
    "kycStatus": false,
    "imageId": "123",
    "startDate": 1630000000,
    "createdAt": 1630000000,
    "updatedAt": 1630000000
}
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
"success": false,
"code": "404",
"message": "Resource not found",
"payload": {} 
}

getAnUser

description: This API provides the functionality to get an user.

Request

Request url

GET `/user/:userId`

Query

name	type	description	required	default
userId	string	specific user number	yes	-

Request Example

GET `/user/1`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	User or null	response data or null

User

name	type	description
id	number	unique number of user
name	string	user name
fullName	string	user full name
email	string	user email
phone	string	user phone
imageId	string	user image id
agreementList	string[]	list of agreement hash
createdAt	number	creation timestamp
updatedAt	number	update timestamp

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code":  "200",
  "message": "Get User sucessfully",
  "payload": 
    {
      "id": 1,
      "name": "John",
      "fullName": "John Doe",
      "email": "[email protected]",
      "phone": "12345678",
      "imageId": "552c2dbf-997c-4b13-957e-ea03c45d2ec1.svg",
      "agreementList": ["agreement1", "agreement2"],
      "createdAt": 1723538422,
      "updatedAt": 1723538422
    },
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
"success": false,
"code": "404",
"message": "Resource not found",
"payload": {} 
}

updateAnUser

description: This API provides the functionality to update an user.

Request

Request url

PUT `/user/:userId`

Query

name	type	description	required	default
userId	string	specific user number	yes	-

Body

name	type	description
name	string	name of the user
fullName	string	full name of the user
email	string	email of the user
phone	string	phone of the user
imageId	string	imageId of the user

Request Example

PUT `/user/1`

const body = {
      name: 'Jane',
      email: '[email protected]',
      fullName: 'Jane Doe',
      phone: '1234567890',
      imageId: 'imageId',
    }

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	User	response data

User

name	type	description
id	number	unique number of user
name	string	user name
fullName	string	user full name
email	string	user email
phone	string	user phone
imageId	string	user image id
agreementList	string[]	list of agreement hash
createdAt	number	creation timestamp
updatedAt	number	update timestamp

Response Example

成功的回傳

    {
      "powerby": "iSunFA v0.1.2+50",
      "success": true,
      "code":  "200",
      "message": "Update User sucessfully",
      "payload": 
        {
          "id": 1,
          "name": "John",
          "fullName": "John Doe",
          "email": "[email protected]",
          "phone": "12345678",
          "imageId": "552c2dbf-997c-4b13-957e-ea03c45d2ec1.svg",
          "agreementList": ["agreement1", "agreement2"],
          "createdAt": 1723538422,
          "updatedAt": 1723538422
        },
    }

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
"success": false,
"code": "404",
"message": "Resource not found",
"payload": {} 
}

listProject

description: This API provides the functionality to list all projects.

Request

Request URL

GET `/company/:companyId/project`

Request Example

GET `/company/1/project`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	Indicates if the API call was successful
code	string	HTTP response code
message	string	Description of the response
payload	Project[] \| null	project array or null

Project

name	type	description
id	number	unique identifier for the project
companyId	number	unique identifier for the company
imageId	string	unique identifier for the image
name	string	name of the project
income	number	total income of the project
expense	number	total expenses of the project
profit	number	total profit of the project
contractAmount	number	total contract amount of the project
stage	string	current stage of the project
completedPercent	number	completed percent of the project
members	Member[]	list of usernames of project members
createdAt	number	timestamp for the project creation
updatedAt	number	timestamp for the project last update

Member

name	type	description
name	string	name of the member
imageId	string	id for the member's image

Response Example

Success Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code": "200",
  "message": "List projects successfully",
  "payload": [
    {
      id: 1,
      companyId: 1,
      imageId: "1",
      name: "Project 1",
      income: 1000,
      expense: 500,
      profit: 500,
      contractAmount: 2000,
      stage: "Selling",
      completedPercent: 90,
      members: [
        {
          name: "John",
          imageId: "1"
        }
      ],
      createdAt: 1630000000,
      updatedAt: 1630000000
    },
    {
      id: 2,
      companyId: 1,
      imageId: "2",
      name: "Project 2",
      income: 2000,
      expense: 1000,
      profit: 1000,
      contractAmount: 3000,
      stage: "Designing",
      completedPercent: 40,
      members: [
        {
          name: "Jane",
          imageId: "2"
        }
      ],
      createdAt: 1630000000,
      updatedAt: 1630000000
    }
  ]
}

Failure Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "404",
  "message": "Resource not found",
  "payload": null 
}

getAProject

Description: Retrieve a project with the specified details including the project name, stage, and team members...

Request

Request URL

GET /company/:companyId/project/:projectId

Query

name	type	description	required
companyId	string	Unique identifier for the company	true
projectId	string	Unique identifier for the project	true

Request Example

GET /company/1/project/3

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	Indicates if the API call was successful
code	string	HTTP response code
message	string	Description of the response
payload	Project \| null	project object or null

Project

name	type	description
id	number	unique identifier for the project
companyId	number	unique identifier for the company
imageId	string	unique identifier for the image
name	string	name of the project
income	number	total income of the project
expense	number	total expenses of the project
profit	number	total profit of the project
contractAmount	number	total contract amount of the project
stage	string	current stage of the project
completedPercent	number	completed percent of the project
members	Member[]	list of usernames of project members
createdAt	number	timestamp for the project creation
updatedAt	number	timestamp for the project last update

Member

name	type	description
name	string	name of the member
imageId	string	id for the member's image

Response Example

Success Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code": "200",
  "message": "get a project successfully",
  "payload": {
    id: 3,
    companyId: 1,
    imageId: "3",
    name: "Project 3",
    income: 1000,
    expense: 500,
    profit: 500,
    contractAmount: 2000,
    stage: "Selling",
    completedPercent: 90,
    members: [
      {
        name: "Eva",
        imageId: "3"
      }
    ],
    createdAt: 1630000000,
    updatedAt: 1630000000
  };
}

Failure Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "404",
  "message": "Resource not found",
  "payload": null 
}

updateAProject

Description: Update a project with the specified details including the project name, stage, and team members.

Request

Request URL

PUT /company/:companyId/project/:projectId

Query

name	type	description	required
companyId	string	Unique identifier for the company	true
projectId	string	Unique identifier for the project	true

Body

name	type	description
name	string	name of the project
stage	string	current stage of the project
memberIdList	number[]	list of ids of project members
imageId	string	image id of the project

Request Example

PUT /company/1/project/3

const body = {
  name: "Project 3A",
  stage: "Selling",
  memberIdList: [3,4],
  imageId: "2"
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	Indicates if the API call was successful
code	string	HTTP response code
message	string	Description of the response
payload	Project \| null	project object or null

Project

name	type	description
id	number	unique identifier for the project
companyId	number	unique identifier for the company
imageId	string	unique identifier for the image
name	string	name of the project
income	number	total income of the project
expense	number	total expenses of the project
profit	number	total profit of the project
contractAmount	number	total contract amount of the project
stage	string	current stage of the project
completedPercent	number	completed percent of the project
members	Member[]	list of usernames of project members
createdAt	number	timestamp for the project creation
updatedAt	number	timestamp for the project last update

Member

name	type	description
name	string	name of the member
imageId	string	id for the member's image

Response Example

Success Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code": "200",
  "message": "update project",
  "payload": {
    id: 3,
    companyId: 1,
    imageId: "3",
    name: "Project 3A",
    income: 1000,
    expense: 500,
    profit: 500,
    contractAmount: 2000,
    stage: "Selling",
    members: [
      {
        name: "Eva",
        imageId: "3"
      }
    ],
    createdAt: 1630000000,
    updatedAt: 1630000000
  };
}

Failure Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "404",
  "message": "Resource not found",
  "payload": null 
}

getMilestone

description: This API provides the functionality to get the milestone information.

Request

Request URL

GET `/company/:companyId/project/:projectId/milestone`

Query

name	type	description	required
companyId	string	Unique identifier for the company	yes
projectId	string	Unique identifier for the project	yes

Request Example

GET `/company/1/project/1/milestone`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	Indicates if the API call was successful
code	string	HTTP response code
message	string	Description of the response
payload	Milestone[] \| []	milestone array or []

Milestone

name	type	description
id	number	unique identifier for the milestone
projectId	number	unique identifier for the project
startDate	number	start date of the milestone(timestamp)
endDate	number	end date of the milestone(timestamp)
status	string	status of the milestone
createdAt	number	timestamp for the milestone creation
updatedAt	number	timestamp for the milestone last update

Response Example

Success Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code": "200",
  "message": "Get milestone successfully",
  "payload": [
    {
      id: 1,
      projectId: 1,
      startDate: 1630000000,
      endDate: 1630000000,
      status: "In Progress",
      createdAt: 1630000000,
      updatedAt: 1630000000
    },
    {
      id: 2,
      projectId: 2,
      startDate: 1630000000,
      endDate: 1630000000,
      status: "Completed",
      createdAt: 1630000000,
      updatedAt: 1630000000
    }
  ]
}

Failure Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "404",
  "message": "Resource not found",
  "payload": {} 
}

updateMilestone

description: This API provides the functionality to update the milestone information.

Request

Request URL

PUT `/company/:companyId/project/:projectId/milestone`

Query

name	type	description	required
companyId	string	Unique identifier for the company	yes
projectId	string	Unique identifier for the project	yes

Body

name	type	description
startDate	string	start date of the milestone(timestamp)
stage	string	stage of the milestone

Request Example

PUT `/company/1/project/1/milestone`

const body = {
  startDate: "1630000000",
  stage: "In Progress"
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	Indicates if the API call was successful
code	string	HTTP response code
message	string	Description of the response
payload	Milestone[] \| []	milestone array or []

Milestone

name	type	description
id	number	unique identifier for the milestone
projectId	number	unique identifier for the project
startDate	number	start date of the milestone(timestamp)
endDate	number	end date of the milestone(timestamp)
status	string	status of the milestone
createdAt	number	timestamp for the milestone creation
updatedAt	number	timestamp for the milestone last update

Response Example

Success Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code": "200",
  "message": "Update milestone successfully",
  "payload": {
    id: 1,
    projectId: 1,
    startDate: 1630000000,
    endDate: 1630000000,
    status: "In Progress",
    createdAt: 1630000000,
    updatedAt: 1630000000
  }
}

Failure Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "404",
  "message": "Resource not found",
  "payload": {} 
}

getProgress

description: This API provides the functionality to get the progress information.

Request

Request URL

GET `/company/:companyId/project/:projectId/progress`

Request Example

GET `/company/1/project/1/progress`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	Indicates if the API call was successful
code	string	HTTP response code
message	string	Description of the response
payload	number	progress object or 0

Response Example

Success Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code": "200",
  "message": "Get progress successfully",
  "payload": 50
}

Failure Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "404",
  "message": "Resource not found",
  "payload": 0
}

getSale

description: This API provides the functionality to get the sale information.

Request

Request URL

GET `/company/:companyId/project/:projectId/sale`

Request Example

GET `/company/1/project/1/sale`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	Indicates if the API call was successful
code	string	HTTP response code
message	string	Description of the response
payload	sale \| {}	sale object or {}

Sale

name	type	description
id	string	unique identifier for the sale
projectId	number	unique identifier for the project
date	number	date of the sale
totalSales	number	total sales of the project
comparison	number	comparison of the project
createdAt	number	timestamp for the sale creation
updatedAt	number	timestamp for the sale last update

Response Example

Success Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code": "200",
  "message": "Get sale successfully",
  "payload": {
    id: "1",
    projectId: 1,
    date: 1630000000,
    totalSales: 1000,
    comparison: 500,
    createdAt: 1630000000,
    updatedAt: 1630000000
  }
}

Failure Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "404",
  "message": "Resource not found",
  "payload": {} 
}

getValue

description: This API provides the functionality to get the value information.

Request

Request URL

GET `/company/:companyId/project/:projectId/value`

Request Example

GET `/company/1/project/1/value`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	Indicates if the API call was successful
code	string	HTTP response code
message	string	Description of the response
payload	Value \| {}	value object or {}

Value

name	type	description
id	string	unique identifier for the value
projectId	number	unique identifier for the project
totalRevenue	number	total revenue of the project
totalRevenueGrowthIn30d	number	total revenue growth in 30 days
totalExpense	number	total expenses of the project
netProfit	number	net profit of the project
netProfitGrowthIn30d	number	net profit growth in 30 days
netProfitGrowthInYear	number	net profit growth in a year
createdAt	number	timestamp for the value creation
updatedAt	number	timestamp for the value last update

Response Example

Success Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code": "200",
  "message": "Get value successfully",
  "payload": {
    id: "1",
    projectId: 1,
    totalRevenue: 1000,
    totalRevenueGrowthIn30d: 500,
    totalExpense: 500,
    netProfit: 500,
    netProfitGrowthIn30d: 250,
    netProfitGrowthInYear: 1000,
    createdAt: 1630000000,
    updatedAt: 1630000000
  }
}

Failure Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "404",
  "message": "Resource not found",
  "payload": {} 
}

getWorkRate

description: This API provides the functionality to get the work rate information.

Request

Request URL

GET `/company/:companyId/project/:projectId/workrate`

Request Example

GET `/company/1/project/1/workrate`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	Indicates if the API call was successful
code	string	HTTP response code
message	string	Description of the response
payload	WorkRate \| {}	work rate object or {}

WorkRate

name	type	description
id	string	unique identifier for the work rate
employeeProjectId	string	unique identifier for the employee project
member	Member	member object
involvementRate	number	involvement rate of the project
expectedHours	number	expected hours of the project
actualHours	number	actual hours of the project
createdAt	number	timestamp for the work rate creation
updatedAt	number	timestamp for the work rate last update

Member

name	type	description
name	string	name of the member
imageId	string	id for the member's image

Response Example

Success Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code": "200",
  "message": "Get work rate successfully",
  "payload": {
    id: "1",
    employeeProjectId: "1",
    member: {
      name: "John",
      imageId: "1"
    },
    involvementRate: 50,
    expectedHours: 100,
    actualHours: 50,
    createdAt: 1630000000,
    updatedAt: 1630000000
  }
}

Failure Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "404",
  "message": "Resource not found",
  "payload": {} 
}

listJournal

Description

Retrieve all journal data.

Request

URL

GET /company/:companyId/journal

Query

name	type	description	required
page	number	The page number	no
pageSize	number	The number of items per page	no
eventType	string	The type of event	no
sortBy	string	The field to sort by	no
sortOrder	string	The order to sort by	no
startDate	number	The start date	no
endDate	number	The end date	no
searchQuery	string	The search query	no

Request Example

GET /company/1/journal?page=1&pageSize=10&eventType=expense&sortBy=createdAt&sortOrder=desc&startDate=1630000000&endDate=1630000000&searchQuery=journal

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	{[key: string]: IPaginatedData<IJournalListItem[]>}	both uploaded and upcoming journal data

JOURNAL_EVENT

JOURNAL_EVENT {
  UPLOADED = 'JOURNAL.UPLOADED',
  UPCOMING = 'JOURNAL.UPCOMING',
}

IPaginatedData

name	type	description
data	IJournalListItem[]	The journal data
page	number	The page number
totalPages	number	The total number of pages
totalCount	number	The total number of items
pageSize	number	The number of items per page
hasNextPage	boolean	Indicates if there is a next page
hasPreviousPage	boolean	Indicates if there is a previous page
sort	{sortBy: string, sortOrder: string}[]	The order and field to sort by

IJournalListItem

name	type	description
id	number	The unique identifier of the journal
date	number	The date of the journal
event	JOURNAL_EVENT	journal status
type	string	The type of the journal
particulars	string	The particulars of the journal
fromTo	string	The from/to of the journal
account	IAccount[]	The account of the journal
projectName	string	The project name of the journal
projectImageId	string	The project image id of the journal
voucherId	number	The voucher id of the journal
voucherNo	string	The voucher number of the journal

IAccount

name	type	description
id	number	The unique identifier of the account
debit	boolean	The debit of the journal
account	string	The account of the journal
amount	number	The amount of the journal

Response Example

Success Response

{
    "powerby": "iSunFA v0.1.8+51",
    "success": true,
    "code": "200ISF0001",
    "message": "List successfully",
    "payload": {
        "JOURNAL.UPLOADED": {
            "data": [],
            "page": 1,
            "totalPages": 0,
            "totalCount": 0,
            "pageSize": 10,
            "hasNextPage": false,
            "hasPreviousPage": false,
            "sort": [
                {
                    "sortBy": "createdAt",
                    "sortOrder": "desc"
                },
                {
                    "sortBy": "JOURNAL.UPLOADED",
                    "sortOrder": ""
                }
            ]
        },
        "JOURNAL.UPCOMING": {
            "data": [
                {
                    "id": 10000003,
                    "date": 1721635633,
                    "event": "JOURNAL.UPCOMING",
                    "type": "payment",
                    "particulars": "小熱拿鐵 x1, 合計 1項, $35",
                    "fromTo": "全家便利商店股份有限公司",
                    "account": [
                        {
                            "id": 10000018,
                            "debit": false,
                            "account": "在途現金",
                            "amount": 35
                        },
                        {
                            "id": 10000019,
                            "debit": true,
                            "account": "庫存現金",
                            "amount": 35
                        }
                    ],
                    "voucherId": 10000001,
                    "voucherNo": "20240722001"
                }
            ],
            "page": 1,
            "totalPages": 1,
            "totalCount": 1,
            "pageSize": 10,
            "hasNextPage": false,
            "hasPreviousPage": false,
            "sort": [
                {
                    "sortBy": "createdAt",
                    "sortOrder": "desc"
                },
                {
                    "sortBy": "JOURNAL.UPCOMING",
                    "sortOrder": ""
                }
            ]
        }
    }
}

Failure Response

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code": "404",
  "message": "Resource not found",
  "payload": {} 
}

createInvoice

description:
- Upload Invoice Data in ISFMK00052，body need to match IInvoice when POSTing.
- If ocrId is provided, meaning that the invoice data is coming from AICH, and ocr data already exist in database, by providing ocrId, the ocr data will be connected to Journal.
- logic flow:
  - 1. Format Body to IInvoice
  - 1. Format ocrId, it can be rather null or number (need to provided in body)
  - 1. upload IInvoice to AICH
  - 1. If journalId is null, create a new journal than create a new invoice, connect journalId to invoice, otherwise update the invoice that has certain journalId
  - 1. Return the resultId and status of the invoice (IAccountResultStatus)

Request

Request url

POST /company/:companyId/invoice

Body

Body should include invoice: IInvoice interface
ocrId is optional, if provided, it need to be a string of number

name	type	description
ocrId (optional)	number \| null	The index of ocr in Database, need to be numeric string, it can be retrieve from `IUnprocessedOCR`, which can be fetch by `GET /OCR`, if "null", it will be consider as user skip OCR process and upload new journal by user input
invoice	IInvoice	The invoice data that need to be upload to AICH, and create a new journal in database.

ex:

{
    "invoice": IInvoice
}

{
    "ocrId": 123456
    "invoice": IInvoice,
}

IInvoice

name	type	description
journalId	null	this value is not required, just use null
date	number	The timestamp representing the date and time. (second)
eventType	EventType	The type of event ('income', 'payment', 'transfer').
paymentReason	string	The reason for the payment.
description	string	A description of the transaction.
vendorOrSupplier	string	The name of the vendor or supplier involved.
projectId	string \|null	The identifier for the project. (can be null )
project	string \|null	The name of the project. (can be null )
contractId	string \|null	The unique identifier for the contract. (can be null )
contract	string \|null	The name or title of the contract. (can be null )
payment	Payment	A object containing payment details.

Payment

name	type	description
isRevenue	boolean	Indicates if the transaction will generate income. True: money is coming in; false: going out.
price	number	The total amount of money involved in the transaction.
hasTax	boolean	Specifies whether the amount includes tax.
taxPercentage	number	The tax rate, for example, 0 or 5, etc.
hasFee	boolean	Indicates whether there is a handling fee included.
fee	number	The amount of the handling fee.
method	string	The method by which money is received or paid out.
period	PaymentPeriodType (enum)	The timing of payment, either at once (atOnce) or in installments (installment).
installmentPeriod	number	The number of installments for payment.
alreadyPaid	number	The amount of money that has already been paid or collected.
status	PaymentStatusType(enum)	The status of the payment. "paid" or "unpaid" or "partial
progress	number	The actual work completion percentage for a contract, not referring to payment progress.

export interface IInvoice {
  journalId: number | null;
  date: number; // timestamp
  eventType: EventType;
  paymentReason: string;
  description: string;
  vendorOrSupplier: string;
  projectId: number | null;
  project: string | null;
  contractId: number | null;
  contract: string | null;
  payment: IPayment;
}

Body example

{
    "ocrId": 2,
    "invoice": {
        "journalId": null,
        "date": 1715356800,
        "eventType": "income",
        "paymentReason": "Buy a cup of coffee",
        "description": "CCC",
        "vendorOrSupplier": "Carrefour",
        "project": "None",
        "projectId": null,
        "contract": "None",
        "contractId": null,
        "payment": {
            "isRevenue": true,
            "price": 2320,
            "hasTax": true,
            "taxPercentage": 0,
            "hasFee": false,
            "fee": 0,
            "period": "atOnce",
            "method": "Cash",
            "installmentPeriod": 0,
            "alreadyPaid": 0,
            "status": "unpaid",
            "progress": 57

        }
    }
}

{
    "invoice": {
        "journalId": null,
        "date": 1715356800,
        "eventType": "income",
        "paymentReason": "Buy a cup of coffee",
        "description": "CCC",
        "vendorOrSupplier": "Carrefour",
        "project": "None",
        "projectId": null,
        "contract": "None",
        "contractId": null,
        "payment": {
            "isRevenue": true,
            "price": 2320,
            "hasTax": true,
            "taxPercentage": 0,
            "hasFee": false,
            "fee": 0,
            "period": "atOnce",
            "method": "Cash",
            "installmentPeriod": 0,
            "alreadyPaid": 0,
            "status": "unpaid",
            "progress": 57

        }
    }
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	payload(check below)	-

payload

name	type	description
journalId	number	the unique index for the journal in the database, it's the journal that has been updated or created
resultStatus	IAccountResultStatus	the result status of AICH of the invoice

IAccountResultStatus

name	type	description
resultId	string	the id of the result
status	ProgressStatus	the progress status of the result

ProgressStatus

name	type	description
ProgressStatus(enum)	string	'inProgress','alreadyUpload', 'invalidInput'

成功的回傳：

{
    "powerby": "iSunFA v0.1.4+78",
    "success": true,
    "code": "201ISF0000",
    "message": "Created successfully",
    "payload": {
        "journalId": 2,
        "resultStatus": {
            "resultId": "717316182a",
            "status": "alreadyUpload"
        }
    }
}

失敗的回傳： Due to the fact that aichResultId has @unique constrain, if same aichResultId was return from AICH, it will cause "Database create failed", and no data be created

{
    "powerby": "iSunFA v0.1.4+10",
    "success": false,
    "code": "500ISF0002",
    "message": "Database create failed",
    "payload": {}
}

getAnInvoice

Description

Get an invoice data.

Request

Request url

GET /company/:companyId/invoice/:invoiceId

Param

name	type	description	require	default
invoiceId	string	invoice id	true	-

Request Example

GET /company/1/invoice/1

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Invoice	invoice data

Invoice

name	type	description
journalId	number	the unique id of the journal
date	number	timestamp, date of invoice occur
eventType	EventType	'income', 'payment', 'transfer'
paymentReason	string	which account（會計科目） should this invoice belongs to
venderOrSupplier	string	the company that pay money
description	string	text to describe why invoice is existed
project	string	the name of related project
projectId	number	the id of related project
contract	string	the name of related contract
contractId	number	the id of related contract
payment	Payment	the payment information

Payment

name	type	description
isRevenue	boolean	Indicates if the transaction will generate income. True: money is coming in; false: going out.
price	number	The total amount of money involved in the transaction.
hasTax	boolean	Specifies whether the amount includes tax.
taxPercentage	number	The tax rate, for example, 0 or 5, etc.
hasFee	boolean	Indicates whether there is a handling fee included.
fee	number	The amount of the handling fee.
method	string	The method by which money is received or paid out.
period	PaymentPeriodType(enum)	The timing of payment, either at once ('atOnce') or in installments ('installment').
installmentPeriod	number	The number of installments for payment.
alreadyPaid	number	The amount of money that has already been paid or collected.
status	PaymentStatusType(enum)	The status of the payment. 'paid' or 'unpaid' or 'partial'
progress	number	The actual work completion percentage for a contract, not referring to payment progress.

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.5+28",
  "success": true,
  "code": "200ISF0002",
  "message": "Get successfully",
  "payload": {
    "journalId": 2,
    "date": 1717430400,
    "eventType": "income",
    "paymentReason": "文書費用",
    "description": "買受人統編:52414797\n營業人統編:51380003\n格式:25\n誠品股份有限公司中山書街分公司\n地址:台北市大同區南京西路16號\n店號:BA01捷運中山店\n序號:04140107\n機號:BA010007\n系統日:2024-04-14 17:19:04",
    "vendorOrSupplier": "誠品股份有限公司中山書街分公司",
    "projectId": null,
    "contractId": null,
    "payment": {
      "isRevenue": true,
      "price": 1223,
      "hasTax": false,
      "taxPercentage": 0,
      "hasFee": false,
      "fee": 0,
      "method": "Cash",
      "period": "atOnce",
      "installmentPeriod": 0,
      "alreadyPaid": 0,
      "status": "unpaid",
      "progress": 0
    }
  }
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code":  "502",
  "message": "Bad Request",
  "payload": {}
}

updateAnInvoice

description:
- Update an invoice in ISFMK00052，body need to match IInvoice when POSTing and name it invoice insite the body. JournalId must be not null. This api will use JournalId to find the invoice to update, not InvoiceId provided in the parameter.
- updated invoice will be resend to AICH, and new aichResultId will be generated and return.

Request

Request URL

PUT /company/:companyId/invoice/:invoiceId

Body

name	type	description
invoice	IInvoice	The invoice data that need to be upload to AICH, and create a new journal in database.

ex:

{
    "invoice": IInvoice
}

IInvoice

name	type	description
journalId	number	The unique identifier for the journal that invoice belongs to, it "Must" be provided
date	number	The timestamp representing the date and time. (second)
eventType	EventType	The type of event ('income', 'payment', 'transfer').
paymentReason	string	The reason for the payment.
description	string	A description of the transaction.
vendorOrSupplier	string	The name of the vendor or supplier involved.
projectId	string \|null	The identifier for the project. (can be null )
project	string \|null	The name of the project. (can be null )
contractId	string \|null	The unique identifier for the contract. (can be null )
contract	string \|null	The name or title of the contract. (can be null )
payment	Payment	A object containing payment details.

Payment

name	type	description
isRevenue	boolean	Indicates if the transaction will generate income. True: money is coming in; false: going out.
price	number	The total amount of money involved in the transaction.
hasTax	boolean	Specifies whether the amount includes tax.
taxPercentage	number	The tax rate, for example, 0 or 5, etc.
hasFee	boolean	Indicates whether there is a handling fee included.
fee	number	The amount of the handling fee.
method	string	The method by which money is received or paid out.
period	PaymentPeriodType (enum)	The timing of payment, either at once (atOnce) or in installments (installment).
installmentPeriod	number	The number of installments for payment.
alreadyPaid	number	The amount of money that has already been paid or collected.
status	PaymentStatusType(enum)	The status of the payment. "paid" or "unpaid" or "partial
progress	number	The actual work completion percentage for a contract, not referring to payment progress.

body example

{
  "invoice": {
    "journalId": 10000000,
    "date": 1715356800,
    "eventType": "income",
    "paymentReason": "Buy a cup of coffee",
    "description": "CCC",
    "vendorOrSupplier": "Carrefour",
    "project": "None",
    "projectId": null,
    "contract": "None",
    "contractId": null,
    "payment": {
      "price": 2320,
      "hasTax": true,
      "taxPercentage": 0,
      "hasFee": false,
      "fee": 0,
      "method": "Cash",
      "installmentPeriod": 0,
      "alreadyPaid": 0,
      "isRevenue": true,
      "progress": 57,
      "period": "atOnce",
      "status": "unpaid"
    }
  }
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	payload(check below)	-

payload

name	type	description
journalId	number	the unique index for the journal in the database, it's the journal that has been updated or created
resultStatus	IAccountResultStatus	the result status of AICH of the invoice

IAccountResultStatus

name	type	description
resultId	string	the id of the result
status	ProgressStatus	the progress status of the result

ProgressStatus

name	type	description
ProgressStatus(enum)	string	'inProgress','alreadyUpload', 'invalidInput'

成功的回傳：

{
  "powerby": "iSunFA v0.1.4+78",
  "success": true,
  "code": "201ISF0000",
  "message": "Update successfully",
  "payload": {
    "journalId": 10000000,
    "resultStatus": {
      "resultId": "717316182a",
      "status": "alreadyUpload"
    }
  }
}

失敗的回傳：

{
    "powerby": "iSunFA v0.1.4+10",
    "success": false,
    "code": "500ISF0002",
    "message": "Database create failed",
    "payload": {}
}

getAnImage

Description

Get an image and decrypt.

Request

Request url

GET /company/:companyId/image/[imageId]

Param

name	type	description	require	default
imageId	string	imageId can be id of "File" or it can be the name of File store in file table(if you know the name), use id will be faster	true	-

Request Example

GET /company/1/image/1

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Buffer \| null	the buffer of the image

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code": "200",
    "message": "Success",
    "payload": Buffer
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code":  "404",
  "message": "Resource not found",
  "payload": null
}

getProfitComparison

description: This API provides the functionality to query income, expenses of each project within the designed period.

Request

Request url

GET `/company/:companyId/profit_comparison`

Query

name	type	description	required	default
startDate	string	the start date of the period, timestamp	yes	-
endDate	string	the end date of the period, timestamp	yes	-
currentPage	string	which page of projects you want to get	no	1
itemsPerPage	string	how many projects you want to get in one page	no	10

Request Example

example

GET `/company/1/profit_comparison?startDate=1717171200&endDate=1718294399`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	ProjectROIComparisonChartDataWithPagination \| {}	response data

ProjectROIComparisonChartDataWithPaginationAndDate

name	type	description
startDate	number	timestamp, the start date of the period
endDate	number	timestamp, the end date of the period
currentPage	number	current page
totalPages	number	total pages
categories	string[]	all names of the projects
series	number[][]	income, expenses of each project in two array
empty	boolean	check if categories is empty

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code":  "200",
  "message": "Get successfully",
  "payload": {
    "startDate": 1711929600,
    "endDate": 1714521600,
    "currentPage": 1,
    "totalPages": 1,
    "categories": [
      "iSunFA", "BAIFA", "iSunOne", "TideBit", "ProjectE", "ProjectF", "ProjectG", "ProjectH", "ProjectI", "ProjectJ"
     ],
    "series": [
      [
       170000, 2000000, 250000, 170000, 2000000, 250000, 170000, 2000000, 250000, 170000
      ],
      [
       150000, 1500000, 80000, 150000, 1500000, 80000, 150000, 1500000, 80000, 150000
      ],
    ],
    "empty": false
  },
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "422",
    "message": "Invalid input parameter",
    "payload": {}
}

getProjectProgress

description: This API provides the functionality to query numbers of how many projects within each progress status.

Request

Request url

GET `/company/:companyId/project_progress`

Query

name	type	description	required	default
date	string	the date you want to query	yes	-

Request Example

example

GET `/company/1/project_progress?date=2024-03-01`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	ProjectProgressChartData \| {}	response data

ProjectProgressChartData

name	type	description
date	number	timestamp, the date you query
categories	string[]	progress status array
series	object[]	contain name and array data of how many projects corresponding to each progress
empty	boolean	check if series number is empty

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code":  "200",
    "message": "Get successfully",
    "payload": {
      "date": 1711929600,
      "categories": [ "Designing", "Beta Testing", "Develop", "Sold", "Selling", "Archived" ],
      "series": [
        {
          "name": "Projects",
          "data": [ 2, 3, 2, 3, 2, 1 ]
        }
      ]
    "empty": false
    }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "422",
    "message": "Invalid input parameter",
    "payload": {}
}

getProfitInsight

description: This API provides the functionality to query overview of total profit growth rate, ROI of top project, numbers of projects which are going to be online.

Request

Request url

GET `/company/:companyId/profit_insight`

Request Example

example

GET `/company/1/profit_insight`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	ProfitInsight \| {}	response data

ProfitInsight

name	type	description
profitChange	number	total profit growth rate of all projects compared to previous day
topProjectRoi	number	highest ROI among all the projects
preLaunchProject	number	numbers of projects which are going to be online(progress: beta testing)
emptyProfitChange	boolean	check if today and yesterday profit is empty
emptyTopProjectRoi	boolean	check if project is empty
emptyPreLaunchProject	boolean	check if pre launch project is empty

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": true,
  "code":  "200",
  "message": "Get successfully",
  "payload": {
    "profitChange": -0.1000,
    "topProjectRoi": 0.3000,
    "preLaunchProject": 5,
    "emptyProfitChange": false,
    "emptyTopProjectRoi": false, 
    "emptyPreLaunchProject": false
  },
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "405",
    "message": "Method not allowed",
    "payload": {}
}

listReport

description: get all report of company, it will return all report of company by status, including financial report and analysis report

Request

Request URL

GET /company/:companyId/report

Query

const { targetPage, pageSize, sortBy, sortOrder, startDateInSecond, endDateInSecond, searchQuery, status } = req.query;

name	type	description	require	default
targetPage	numeric	which page of date you want to check	false	1
pageSize	numeric	how many items a page need to return	false	10
sortBy	'createdAt' \| 'name' \| 'type' \| 'reportType' \| 'status'	which category to be sort by	false	"createdAt"
sortOrder	'desc' \| 'asc	is "sortBy" need to be ascent or descent	false	"desc"
startDateInSecond	numeric (timestamp in second)	items "from" after this date will be selected (Balance sheet won't check this)	false	0
endDateInSecond	numeric (timestamp in second)	items "to" before this date will be selected	false	Number.MAX_SAFE_INTEGER
searchQuery	string	keyword use to search name, type, report type	false	undefined
status	'pending' \| 'generated' \| 'all'	which status of report you want to get	false	'all'

GET /company/:companyId/report?status=pending&targetPage=1&pageSize=10&sortBy=createdAt&sortOrder=desc&startDateInSecond=0&endDateInSecond=1717948800&searchQuery=balance sheet

Response

Response Parameters

name	type	description
powerby	string	ISunFa api 1.0.0
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	IPaginatedReport	response data

IPaginatedReport

name	type	description
data	IReport[]	list of report
totalPage	number	total page of item
page	number	current page

IReport

name	type	description
id	number	the unique index for the report in the database
companyId	number	the unique index for the company in the database
tokenContract	string	the token contract of the report
tokenId	string	the token id of the report
name	string	the name of the report
from	number	the start date of the report
to	number	the end date of the report
type	ReportType(enum)	the type of the report('financial' / 'analysis')
reportType	ReportSheetType(enum)	the report type of the report('balance_sheet' / 'comprehensive_income_statement' / 'cash_flow_statement' / 'report_401')
status	string	the status of the report
remainingSeconds	number	the remaining seconds of the report
paused	boolean	check if the report is paused
projectId	number \| null	the unique index for the project in the database
project	{ id: string, name: string, code: string } \| null	the project of the report
reportLink	string	the link of the report
downloadLink	string	the download link of the report
blockChainExplorerLink	string	the blockchain explorer link of the report
evidenceId	string	the evidence id of the report
content	IAccountReadyForFrontend[]	the content of the report
otherInfo	unknown	other information of the report
createdAt	number	the create date of the report
updatedAt	number	the update date of the report

IAccountReadyForFrontend

name	type	description
code	string	The unique identifier for the account.
name	string	The name of the account.
curPeriodAmount	number	The amount for the current period.
curPeriodAmountString	string	The amount for the current period as a string.
curPeriodPercentage	number	The percentage for the current period.
prePeriodAmount	number	The amount for the previous period.
prePeriodAmountString	string	The amount for the previous period as a string.
prePeriodPercentage	number	The percentage for the previous period.
indent	number	The indentation level for display purposes.

Response Example

Success Response

{
  "powerby": "iSunFA v0.1.8+51",
  "success": true,
  "code": "201ISF0000",
  "message": "Get successfully",
  "payload": {
    "data": [
  {
    "id": 1,
    "companyId": 123,
    "tokenContract": "0x123abc",
    "tokenId": "456def",
    "name": "Mock Report",
    "from": 1630444800,
    "to": 1633046400,
    "type": "financial",
    "reportType": "balance_sheet",
    "status": "completed",
    "remainingSeconds": 0,
    "paused": false,
    "projectId": null,
    "project": null,
    "reportLink": "https://example.com/report",
    "downloadLink": "https://example.com/download",
    "blockChainExplorerLink": "https://example.com/explorer",
    "evidenceId": "abc123",
    "content": [
      {
        "code": "4000",
        "name": "營業收入合計",
        "curPeriodAmount": 0,
        "curPeriodPercentage": 0,
        "curPeriodAmountString": "0",
        "prePeriodAmount": 0,
        "prePeriodPercentage": 0,
        "prePeriodAmountString": "0",
        "indent": 0
      }......
    ],
    "otherInfo": null,
    "createdAt": 1633046400,
    "updatedAt": 1633046400
  },
  {
    "id": 2,
    "companyId": 123,
    "tokenContract": "0x123abc",
    "tokenId": "456def",
    "name": "Mock Report",
    "from": 1630444800,
    "to": 1633046400,
    "type": "financial",
    "reportType": "balance_sheet",
    "status": "completed",
    "remainingSeconds": 0,
    "paused": false,
    "projectId": null,
    "project": null,
    "reportLink": "https://example.com/report",
    "downloadLink": "https://example.com/download",
    "blockChainExplorerLink": "https://example.com/explorer",
    "evidenceId": "abc123",
    "content": [
      {
        "code": "4000",
        "name": "營業收入合計",
        "curPeriodAmount": 0,
        "curPeriodPercentage": 0,
        "curPeriodAmountString": "0",
        "prePeriodAmount": 0,
        "prePeriodPercentage": 0,
        "prePeriodAmountString": "0",
        "indent": 0
      }......
    ],
    "otherInfo": null,
    "createdAt": 1633046400,
    "updatedAt": 1633046400
  }
],
    "page": 1,
    "totalPages": 0,
    "totalCount": 0,
    "pageSize": 10,
    "hasNextPage": false,
    "hasPreviousPage": false,
    "sort": [
        {
            "sortBy": "createdAt",
            "sortOrder": "desc"
        }
    ]
  }
}

Error response

{
  "powerby": "iSunFA v0.1.8+51",
  "success": false,
  "code": "500ISF0002",
  "message": "Database list failed",
  "payload": {}
}

getLaborCostChart

description: This API provides the functionality to get data about labor cost chart.

Request

Request url

GET `/company/:companyId/labor_cost_chart`

Query

name	type	description	required	default
date	string	the date you want to query	yes	-

Request Example

GET `/company/1/labor_cost_chart?date=2024-06-19`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of the request
payload	LaborCostChartData \| {}	object of labor cost chart data or {}

LaborCostChartData

Name	Type	Description
date	number	The date you request, typically represented as a timestamp.
categories	string[]	An array of categories for all active projects.
series	number[]	An array of numerical values, each representing the labor costs for each project.
empty	boolean	check if any cost happened

Response Example

成功的回傳

{
 "powerby": "iSunFA v0.1.5+7",
 "success": true,
 "code": "200ISF0002",
 "message": "Get successfully",
 "payload": {
     "date": 1718755200,
     "categories": [
         "iSunFA",
         "BAIFA"
     ],
     "series": [
         90300,
         63700
     ],
     "empty": false
 }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "405",
    "message": "Method not allowed",
    "payload": {}
}

getIncomeExpenseTrendChart

description: This API provides the functionality to query value of total income, expenses and profit within 12 months or years.

Request

Request url

GET `/company/:companyId/income_expense_trend`

Query

name	type	description	required	default
period	string	the period displayed, month or year	no	month

Request Example

GET `/company/1/income_expense_trend?period=month`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of the request
payload	IncomeExpenseTrendChartData \| {}	object of income expense trend chart data or {}

IncomeExpenseTrendChartData

name	type	description
categories	string[]	An array of months or years used in the chart.
series	{ name: string; data: number[]; }[]	An array of objects, with value related to designated period separately in income, expense, and profit
annotations	{ name: string; data: { absolute: number; }[]; }[]	An array of objects for annotations, each with a name(income, expense, and profit) and a data array containing objects that provide absolute values for designated period.
empty	boolean	check if series or categories is empty

Response Example

成功的回傳

 {
  "powerby": "iSunFA v0.1.4+37",
  "success": true,
  "code": "200ISF0002",
  "message": "Get successfully",
  "payload": {
    "categories": [
      "Jan",
      "Feb",
      "Mar",
      "Apr",
      "May",
      "Jun",
      "Jul",
      "Aug",
      "Sep",
      "Oct",
      "Nov",
      "Dec"
    ],
    "series": [
      {
        "name": "Income",
        "data": [
          0,
          200,
          300,
          40760,
          500,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ]
      },
      {
        "name": "Expense",
        "data": [
          0,
          100,
          200,
          20660,
          400,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ]
      },
      {
        "name": "Profit Status",
        "data": [
          0,
          100,
          100,
          20100,
          100,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ]
      }
    ],
    "annotations": [
      {
        "name": "Income",
        "data": [
          {
            "absolute": 0
          },
          {
            "absolute": 200
          },
          {
            "absolute": 300
          },
          {
            "absolute": 40760
          },
          {
            "absolute": 500
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          }
        ]
      },
      {
        "name": "Expense",
        "data": [
          {
            "absolute": 0
          },
          {
            "absolute": 100
          },
          {
            "absolute": 200
          },
          {
            "absolute": 20660
          },
          {
            "absolute": 400
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          }
        ]
      },
      {
        "name": "Profit Status",
        "data": [
          {
            "absolute": 0
          },
          {
            "absolute": 100
          },
          {
            "absolute": 100
          },
          {
            "absolute": 20100
          },
          {
            "absolute": 100
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          },
          {
            "absolute": 0
          }
        ]
      }
    ]
    "empty": false
 }

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "405",
    "message": "Method not allowed",
    "payload": {}
}

createInvitation

description: This API provides the functionality to create an invitation.

Request

Request url

POST `/company/:companyId/invitation`

Request Body

name	type	description	require	default
emails	string[]	email list	true	-
roleId	number	role id	true	-

Request Example

POST /company/1/invitation
const body = {
    "emails": ["[email protected]"],
    "roleId": 1
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Invitation[]	invitation content

Invitation

name	type	description
id	number	id of invitation
roleId	number	id of role
companyId	number	id of company
createdUserId	number	create user id
code	string	code of invitation
email	string	email address
phone	string	phone number
hasUsed	boolean	whether the invitaion has been used or not
expireAt	number	expire timestamp of the invitation
createdAt	number	creation timestamp
updatedAt	number	updated timestamp

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code": "200",
    "message": "Success",
    "payload": {
      "id": 1000,
      "companyId": 1000,
      "roleId": 1000,
      "createdUserId": 1000,
      "code": "testCode123",
      "email": "[email protected]",
      "phone": "1234567890",
      "has_used": false,
      "expired_at": 1935724800,
      "created_at": 1635724800,
      "updated_at": 1723605258,
    }
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code":  "422",
  "message": "Invalid input parameter",
  "payload": {}
}

updateInvitation

description: This API provides the functionality to update an invitation for inviting an user.

Request

Request url

PUT `/user/:userId/invitation`

Request Body

name	type	description	require	default
invitationCode	string	code of invitation	true	-

Request Example

PUT /user/1/invitation
const body = {
    "invitationCode": "123456"
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Admin or null	admin info or null

Admin

name	type	description
id	number	The unique identifier for the admin.
user	User	The user associated with the admin.
company	Company	The company to which the admin belongs.
role	Role	The role assigned to the admin.
email	string	The email address of the admin.
status	boolean	The current status of the admin.
startDate	number	The start date of the admin's role, represented as a timestamp.
endDate	number	The end date of the admin's role, represented as a timestamp.
createdAt	number	The timestamp when the admin record was created.
updatedAt	number	The timestamp when the admin record was last updated.

User

name	type	description
id	number	unique number of user
name	string	user name
fullName	string	user full name
email	string	user email
phone	string	user phone
imageId	string	user image id
agreementList	string[]	list of agreement hash
createdAt	number	creation timestamp
updatedAt	number	update timestamp

Company

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start timestamp of the company
createdAt	number	create timestamp of the company
updatedAt	number	update timestamp of the company

Role

name	type	description
id	number	role's id
name	string	role's name
permissions	string[]	permission of the role

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code": "200",
    "message": "Success",
    "payload": 
     {
            "id": 1,
            "email": "test_PUT_INVITATION@test",
            "status": true,
            "startDate": 1717571361,
            "endDate": null,
            "createdAt": 1717571361,
            "updatedAt": 1717571361,
            "user": {
                "id": 11,
                "name": "",
                "fullName": null,
                "email": "test_PUT_INVITATION@test",
                "phone": null,
                "imageId": "552c2dbf-997c-4b13-957e-ea03c45d2ec1.svg",
                "agreementList": ["agreement1", "agreement2"],
                "createdAt": 1723538422,
                "updatedAt": 1723538422
            },
            "company": {
                "id": 24,
                "name": "Test Company",
                "code": "TST_invitation3",
                "regional": "TW",
                "kycStatus": false,
                "imageId": "imageId",
                "startDate": 1717565772,
                "createdAt": 1717565772,
                "updatedAt": 1717565772
            },
            "role": {
                "id": 19,
                "name": "Test_invitaion",
                "permissions": [],
            }
        },
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code":  "422",
  "message": "Invalid input parameter",
  "payload": {}
}

listAdmin

description: This API provides the functionality to get all admins of a company.

Request

Request url

GET `/company/:companyId/admin`

Request Example

GET `/company/1/admin`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Admin[]	admin info

Admin

Name	Type	Description
id	number	id of admin
user	user	user of admin
company	company	company of admin
role	role	role of admin
email	string	email of admin
status	string	status of admin
startDate	number	start date of the admin
endDate	number	end date of the admin
createAt	number	create timestamp of the admin
updateAt	number	update timestamp of the admin

User

name	type	description
id	number	unique number of user
name	string	user name
fullName	string	user full name
email	string	user email
phone	string	user phone
imageId	string	user image id
agreementList	string[]	list of agreement hash
createdAt	number	creation timestamp
updatedAt	number	update timestamp

Company

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start date of the company
createdAt	number	create timestamp of the company
updatedAt	number	update timestamp of the company

Role

name	type	description
id	string	role's id
name	string	role's name
permissions	string[]	permission of the role

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.4+46",
  "success": true,
  "code": "200ISF0002",
  "message": "Get successfully",
  "payload": 
      [
        {
            "id": 140,
            "userId": 11,
            "companyId": 24,
            "roleId": 19,
            "email": "test_PUT_INVITATION@test",
            "status": true,
            "startDate": 1717571361,
            "endDate": null,
            "createdAt": 1717571361,
            "updatedAt": 1717571361,
            "user": {
                "id": 11,
                "name": "",
                "fullName": null,
                "email": "test_PUT_INVITATION@test",
                "phone": null,
                "imageId": "552c2dbf-997c-4b13-957e-ea03c45d2ec1.svg",
                "agreementList": ["agreement1", "agreement2"],
                "createdAt": 1723538422,
                "updatedAt": 1723538422
            },
            "company": {
                "id": 24,
                "name": "Test Company",
                "code": "TST_invitation3",
                "regional": "TW",
                "kycStatus": false,
                "imageId": "imageId",
                "startDate": 1717565772,
                "createdAt": 1717565772,
                "updatedAt": 1717565772
            },
            "role": {
                "id": 19,
                "name": "Test_invitaion",
                "permissions": [],
            }
        },
        {
            "id": 198,
            "userId": 11,
            "companyId": 24,
            "roleId": 19,
            "email": "test_PUT_INVITATION@test",
            "status": true,
            "startDate": 1717575197,
            "endDate": null,
            "createdAt": 1717575197,
            "updatedAt": 1717575197,
            "user": {
                "id": 11,
                "name": "",
                "fullName": null,
                "email": "test_PUT_INVITATION@test",
                "phone": null,
                "credentialId": "test_PUT_INVITATION",
                "publicKey": "",
                "algorithm": "",
                "imageId": null,
                "createdAt": 1717565772,
                "updatedAt": 1717565772
            },
            "company": {
                "id": 24,
                "name": "Test Company",
                "code": "TST_invitation3",
                "regional": "TW",
                "kycStatus": false,
                "imageId": "imageId",
                "startDate": 1717565772,
                "createdAt": 1717565772,
                "updatedAt": 1717565772
            },
            "role": {
                "id": 19,
                "name": "Test_invitaion",
                "permissions": [],
            }
        },
      ]
}

失敗的回傳

  {
        "powerby": "iSunFA v0.1.2+50",
        "success": false,
        "code":  "405",
        "message": "Method not allowed",
        "payload": {}
  }

getAdminById

description: This API provides the functionality to get an admin by id.

Request

Request url

GET `/company/:companyId/admin/:adminId`

Request Example

GET `/company/1/admin/1`

Param

name	type	description	required	default
adminId	string	id of admin	yes	-

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Admin	admin info

Admin

Name	Type	Description
id	number	id of admin
user	user	user of admin
company	company	company of admin
role	role	role of admin
email	string	email of admin
status	string	status of admin
startDate	number	start date of the admin
endDate	number	end date of the admin
createAt	number	create timestamp of the admin
updateAt	number	update timestamp of the admin

User

name	type	description
id	number	unique number of user
name	string	user name
fullName	string	user full name
email	string	user email
phone	string	user phone
imageId	string	user image id
agreementList	string[]	list of agreement hash
createdAt	number	creation timestamp
updatedAt	number	update timestamp

Company

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start date of the company
createdAt	number	create timestamp of the company
updatedAt	number	update timestamp of the company

Role

name	type	description
id	string	role's id
name	string	role's name
permissions	string[]	permission of the role

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.4+46",
  "success": true,
  "code": "200ISF0002",
  "message": "Get successfully",
  "payload": 
     {
            "id": 1,
            "userId": 11,
            "companyId": 24,
            "roleId": 19,
            "email": "test_PUT_INVITATION@test",
            "status": true,
            "startDate": 1717571361,
            "endDate": null,
            "createdAt": 1717571361,
            "updatedAt": 1717571361,
            "user": {
                "id": 11,
                "name": "",
                "fullName": null,
                "email": "test_PUT_INVITATION@test",
                "phone": null,
                "imageId": "552c2dbf-997c-4b13-957e-ea03c45d2ec1.svg",
                "agreementList": ["agreement1", "agreement2"],
                "createdAt": 1723538422,
                "updatedAt": 1723538422
            },
            "company": {
                "id": 24,
                "name": "Test Company",
                "code": "TST_invitation3",
                "regional": "TW",
                "kycStatus": false,
                "imageId": "imageId",
                "startDate": 1717565772,
                "createdAt": 1717565772,
                "updatedAt": 1717565772
            },
            "role": {
                "id": 19,
                "name": "Test_invitaion",
                "permissions": [],
            }
        },
}

失敗的回傳

    {
        "powerby": "iSunFA v0.1.2+50",
        "success": false,
        "code":  "405",
        "message": "Method not allowed",
        "payload": {}
    }

updateAdminById

description: This API provides the functionality to update an admin by id.

Request

Request url

PUT `/company/:companyId/admin/:adminId`

Request Body

name	type	description	require	default
status	boolean	admin status	yes	-
roleName	string	role	yes	-

Request Example

PUT /company/1/admin/1
const body = {
    "status": false,
    "roleName": "admin"
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Admin	admin info

Admin

Name	Type	Description
id	number	id of admin
user	user	user of admin
company	company	company of admin
role	role	role of admin
email	string	email of admin
status	string	status of admin
startDate	number	start date of the admin
endDate	number	end date of the admin
createAt	number	create timestamp of the admin
updateAt	number	update timestamp of the admin

User

name	type	description
id	number	unique number of user
name	string	user name
fullName	string	user full name
email	string	user email
phone	string	user phone
imageId	string	user image id
agreementList	string[]	list of agreement hash
createdAt	number	creation timestamp
updatedAt	number	update timestamp

Company

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start date of the company
createdAt	number	create timestamp of the company
updatedAt	number	update timestamp of the company

Role

name	type	description
id	string	role's id
name	string	role's name
permissions	string[]	permission of the role

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code": "200",
    "message": "Success",
    "payload": {
        "id": 1,
        "userId": 11,
        "companyId": 24,
        "roleId": 19,
        "email": "test_PUT_INVITATION@test",
        "status": false,
        "startDate": 1717571361,
        "endDate": null,
        "createdAt": 1717571361,
        "updatedAt": 1717571361,
        "user": {
            "id": 11,
            "name": "",
            "fullName": null,
            "email": "test_PUT_INVITATION@test",
            "phone": null,
            "imageId": "552c2dbf-997c-4b13-957e-ea03c45d2ec1.svg",
            "agreementList": ["agreement1", "agreement2"],
            "createdAt": 1723538422,
            "updatedAt": 1723538422
        },
        "company": {
            "id": 24,
            "name": "Test Company",
            "code": "TST_invitation3",
            "regional": "TW",
            "kycStatus": false,
            "imageId": "imageId",
            "startDate": 1717565772,
            "createdAt": 1717565772,
            "updatedAt": 1717565772
        },
        "role": {
            "id": 19,
            "name": "admin",
            "permissions": [],
        }
    }
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code":  "422",
  "message": "Invalid input parameter",
  "payload": {}
}

transferOwner

description: This API provides the functionality to transfer the ownership of a company to another admin.

Request

Request url

PUT `/company/:companyId/transfer_owner`

Request Body

name	type	description	require	default
newOwnerId	string	newOwnerId	true	-

Request Example

PUT /company/1/transfer_owner
const body = {
    "newOwnerId": "1"
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Admin[]	updated admin info

Admin

Name	Type	Description
id	number	id of admin
user	user	user of admin
company	company	company of admin
role	role	role of admin
email	string	email of admin
status	string	status of admin
startDate	number	start date of the admin
endDate	number	end date of the admin
createAt	number	create timestamp of the admin
updateAt	number	update timestamp of the admin

User

name	type	description
id	number	unique number of user
name	string	user name
fullName	string	user full name
email	string	user email
phone	string	user phone
imageId	string	user image id
agreementList	string[]	list of agreement hash
createdAt	number	creation timestamp
updatedAt	number	update timestamp

Company

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start date of the company
createdAt	number	create timestamp of the company
updatedAt	number	update timestamp of the company

Role

name	type	description
id	string	role's id
name	string	role's name
permissions	string[]	permission of the role

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code": "200",
    "message": "Success",
    "payload": {
        "id": 1,
        "userId": 11,
        "companyId": 24,
        "roleId": 19,
        "email": "test_PUT_INVITATION@test",
        "status": false,
        "startDate": 1717571361,
        "endDate": null,
        "createdAt": 1717571361,
        "updatedAt": 1717571361,
        "user": {
            "id": 11,
            "name": "",
            "fullName": null,
            "email": "test_PUT_INVITATION@test",
            "phone": null,
            "imageId": "552c2dbf-997c-4b13-957e-ea03c45d2ec1.svg",
            "agreementList": ["agreement1", "agreement2"],
            "createdAt": 1723538422,
            "updatedAt": 1723538422
        },
        "company": {
            "id": 24,
            "name": "Test Company",
            "code": "TST_invitation3",
            "regional": "TW",
            "kycStatus": false,
            "imageId": "imageId",
            "startDate": 1717565772,
            "createdAt": 1717565772,
            "updatedAt": 1717565772
        },
        "role": {
            "id": 19,
            "name": "admin",
            "permissions": [],
        }
    }
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code":  "422",
  "message": "Invalid input parameter",
  "payload": {}
}

deleteAdminById

description: This API provides the functionality to delete an admin by id by updating deletedAt timestamp.

Request

Request url

DELETE `/company/:companyId/admin/:adminId`

Request Example

DELETE `/company/1/admin/1`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Admin	admin info

Admin

Name	Type	Description
id	number	id of admin
user	user	user of admin
company	company	company of admin
role	role	role of admin
email	string	email of admin
status	string	status of admin
startDate	number	start date of the admin
endDate	number	end date of the admin
createAt	number	create timestamp of the admin
updateAt	number	update timestamp of the admin

User

name	type	description
id	number	unique number of user
name	string	user name
fullName	string	user full name
email	string	user email
phone	string	user phone
imageId	string	user image id
agreementList	string[]	list of agreement hash
createdAt	number	creation timestamp
updatedAt	number	update timestamp

Company

name	type	description
id	number	id of company
name	string	name of company
code	string	code of company
regional	string	regional of company
kycStatus	boolean	kyc status of company
imageId	string	image id of company
startDate	number	start date of the company
createdAt	number	create timestamp of the company
updatedAt	number	update timestamp of the company

Role

name	type	description
id	string	role's id
name	string	role's name
permissions	string[]	permission of the role

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code": "200",
    "message": "Success",
    "payload": {
        "id": 1,
        "userId": 11,
        "companyId": 24,
        "roleId": 19,
        "email": "test_PUT_INVITATION@test",
        "status": false,
        "startDate": 1717571361,
        "endDate": null,
        "createdAt": 1717571361,
        "updatedAt": 1717571361,
        "user": {
            "id": 11,
            "name": "",
            "fullName": null,
            "email": "test_PUT_INVITATION@test",
            "phone": null,
            "imageId": "552c2dbf-997c-4b13-957e-ea03c45d2ec1.svg",
            "agreementList": ["agreement1", "agreement2"],
            "createdAt": 1723538422,
            "updatedAt": 1723538422
        },
        "company": {
            "id": 24,
            "name": "Test Company",
            "code": "TST_invitation3",
            "regional": "TW",
            "kycStatus": false,
            "imageId": "imageId",
            "startDate": 1717565772,
            "createdAt": 1717565772,
            "updatedAt": 1717565772
        },
        "role": {
            "id": 19,
            "name": "admin",
            "permissions": [],
        }
    }
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code":  "422",
  "message": "Invalid input parameter",
  "payload": {}
}

getChallenge

description: This API provides the functionality to get a challenge which format is base64URL.

Request

Request url

GET `/challenge`

Request Example

GET `/challenge`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	string	challenge

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": true,
    "code": "200",
    "message": "Success",
    "payload": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MzQwNzQwNzAsImV4cCI6MTYzNDA3NDA3MX0",
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code":  "422",
  "message": "Invalid input parameter",
  "payload": ""
}

getAllSalaryRecords

description: This API provides the functionality to get all salary records.

Request

Request url

GET `/company/:companyId/salary`

Query

name	type	description	required	default
companyId	number	specific id of the company	yes	-

Request Example

GET `/company/1/salary`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	ISalaryRecord[] \| ISalaryRecord \| {}	response data

ISalaryRecord

name	type	description
id	number	unique number of the salary record
employeeId	number	unique number of the employee
employeeName	string	employee name
employeeDepartment	string	employee department
salary	number	employee salary
insurancePayment	number	insurance paid by the company(健保+勞保+勞退)
bonus	number	employee bonus
description	string	description of the salary record
startDate	number	start duration of the salary record
endDate	number	end duration of the salary record
workingHour	number	working hours in the duration of the salary record
confirmed	boolean	if the salary record is confirmed
createdAt	number	creation timestamp of the salary record
updatedAt	number	update timestamp of the salary record

Response Example

成功的回傳

  {
    "powerby": "iSunFA v0.1.8+52",
    "success": true,
    "code": "200ISF0001",
    "message": "List successfully",
    "payload": [
        {
            "id": 10000000,
            "employeeId": 10000000,
            "employeeName": "aook",
            "employeeDepartment": "Engineering",
            "salary": 6000,
            "insurancePayment": 250,
            "bonus": 0,
            "description": "June Salary",
            "startDate": 1717527265,
            "endDate": 1720119265,
            "workingHour": 184,
            "confirmed": false,
            "createdAt": 1721115051,
            "updatedAt": 1721115051
        },
        {
            "id": 10000001,
            "employeeId": 10000001,
            "employeeName": "book",
            "employeeDepartment": "Engineering",
            "salary": 5000,
            "insurancePayment": 200,
            "bonus": 0,
            "description": "June Salary",
            "startDate": 1717527265,
            "endDate": 1720119265,
            "workingHour": 184,
            "confirmed": false,
            "createdAt": 1721115051,
            "updatedAt": 1721115051
        },
        {
            "id": 10000002,
            "employeeId": 10000002,
            "employeeName": "cook",
            "employeeDepartment": "Engineering",
            "salary": 4000,
            "insurancePayment": 150,
            "bonus": 0,
            "description": "June Salary",
            "startDate": 1717527265,
            "endDate": 1720119265,
            "workingHour": 184,
            "confirmed": false,
            "createdAt": 1721115051,
            "updatedAt": 1721115051
        }
    ]
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": {}
}

createSalaryRecords

description: This API provides the functionality to post many salary records.

Request

Request url

POST `/company/:companyId/salary`

Query

name	type	description	required	default
companyId	number	specific id of the company	yes	-

Body

name	type	description
type	string	type of the salary record("Salary" / "Bonus")
frequency	string	frequency of the payment("Month" / "Year" / "Day")
startDate	number	start timestamp of the salary record period
endDate	number	end timestamp of the salary record period
employeeIdList	number[]	list of employee IDs
description	string	description of salary records

Request Example

POST `/company/1/salary`

Body

{
    "type": "Salary",
    "frequency": "Month",
    "startDate": 1717527265,
    "endDate": 1720119265,
    "employeeIdList": [10000000, 10000001, 10000002],
    "description": "June Salary"
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	ISalaryRecord[] \| ISalaryRecord \| {}	response data

ISalaryRecord

name	type	description
id	number	unique number of the salary record
employeeId	number	unique number of the employee
employeeName	string	employee name
employeeDepartment	string	employee department
salary	number	employee salary
insurancePayment	number	insurance paid by the company(健保+勞保+勞退)
bonus	number	employee bonus
description	string	description of the salary record
startDate	number	start duration of the salary record
endDate	number	end duration of the salary record
workingHour	number	working hours in the duration of the salary record
confirmed	boolean	if the salary record is confirmed
createdAt	number	creation timestamp of the salary record
updatedAt	number	update timestamp of the salary record

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.8+52",
    "success": true,
    "code": "201ISF0000",
    "message": "Created successfully",
    "payload": [
        {
            "id": 10000003,
            "employeeId": 10000000,
            "employeeName": "aook",
            "employeeDepartment": "Engineering",
            "salary": 200000,
            "insurancePayment": 1000,
            "bonus": 0,
            "description": "June Salary",
            "startDate": 1717527265,
            "endDate": 1720119265,
            "workingHour": 184,
            "confirmed": false,
            "createdAt": 1721635489,
            "updatedAt": 1721635489
        },
        {
            "id": 10000004,
            "employeeId": 10000001,
            "employeeName": "book",
            "employeeDepartment": "Engineering",
            "salary": 5000,
            "insurancePayment": 200,
            "bonus": 0,
            "description": "June Salary",
            "startDate": 1717527265,
            "endDate": 1720119265,
            "workingHour": 184,
            "confirmed": false,
            "createdAt": 1721635489,
            "updatedAt": 1721635489
        },
        {
            "id": 10000005,
            "employeeId": 10000002,
            "employeeName": "cook",
            "employeeDepartment": "Engineering",
            "salary": 4000,
            "insurancePayment": 150,
            "bonus": 0,
            "description": "June Salary",
            "startDate": 1717527265,
            "endDate": 1720119265,
            "workingHour": 184,
            "confirmed": false,
            "createdAt": 1721635489,
            "updatedAt": 1721635489
        }
    ]
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": {}
}

updateSalaryRecords

description: This API provides the functionality to update unconfirmed salary records.

Request

Request url

PUT `/company/:companyId/salary`

Query

name	type	description	required	default
companyId	number	specific id of the company	yes	-

Request Example

PUT `/company/1/salary`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	ISalaryRecord[] \| ISalaryRecord \| {}	response data

ISalaryRecord

name	type	description
id	number	unique number of the salary record
employeeId	number	unique number of the employee
employeeName	string	employee name
employeeDepartment	string	employee department
salary	number	employee salary
insurancePayment	number	insurance paid by the company(健保+勞保+勞退)
bonus	number	employee bonus
description	string	description of the salary record
startDate	number	start duration of the salary record
endDate	number	end duration of the salary record
workingHour	number	working hours in the duration of the salary record
confirmed	boolean	if the salary record is confirmed
createdAt	number	creation timestamp of the salary record
updatedAt	number	update timestamp of the salary record

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.8+52",
    "success": true,
    "code": "200ISF0003",
    "message": "Update successfully",
    "payload": [
        {
            "id": 10000000,
            "employeeId": 10000000,
            "employeeName": "aook",
            "employeeDepartment": "Engineering",
            "salary": 6000,
            "insurancePayment": 250,
            "bonus": 0,
            "description": "June Salary",
            "startDate": 1717527265,
            "endDate": 1720119265,
            "workingHour": 184,
            "confirmed": true,
            "createdAt": 1721115051,
            "updatedAt": 1721635854
        },
        {
            "id": 10000001,
            "employeeId": 10000001,
            "employeeName": "book",
            "employeeDepartment": "Engineering",
            "salary": 5000,
            "insurancePayment": 200,
            "bonus": 0,
            "description": "June Salary",
            "startDate": 1717527265,
            "endDate": 1720119265,
            "workingHour": 184,
            "confirmed": true,
            "createdAt": 1721115051,
            "updatedAt": 1721635854
        },
        {
            "id": 10000002,
            "employeeId": 10000002,
            "employeeName": "cook",
            "employeeDepartment": "Engineering",
            "salary": 4000,
            "insurancePayment": 150,
            "bonus": 0,
            "description": "June Salary",
            "startDate": 1717527265,
            "endDate": 1720119265,
            "workingHour": 184,
            "confirmed": true,
            "createdAt": 1721115051,
            "updatedAt": 1721635854
        },
        {
            "id": 10000003,
            "employeeId": 10000000,
            "employeeName": "aook",
            "employeeDepartment": "Engineering",
            "salary": 200000,
            "insurancePayment": 1000,
            "bonus": 0,
            "description": "June Salary",
            "startDate": 1717527265,
            "endDate": 1720119265,
            "workingHour": 184,
            "confirmed": true,
            "createdAt": 1721635489,
            "updatedAt": 1721635854
        },
        {
            "id": 10000004,
            "employeeId": 10000001,
            "employeeName": "book",
            "employeeDepartment": "Engineering",
            "salary": 5000,
            "insurancePayment": 200,
            "bonus": 0,
            "description": "June Salary",
            "startDate": 1717527265,
            "endDate": 1720119265,
            "workingHour": 184,
            "confirmed": true,
            "createdAt": 1721635489,
            "updatedAt": 1721635854
        },
        {
            "id": 10000005,
            "employeeId": 10000002,
            "employeeName": "cook",
            "employeeDepartment": "Engineering",
            "salary": 4000,
            "insurancePayment": 150,
            "bonus": 0,
            "description": "June Salary",
            "startDate": 1717527265,
            "endDate": 1720119265,
            "workingHour": 184,
            "confirmed": true,
            "createdAt": 1721635489,
            "updatedAt": 1721635854
        }
    ]
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": {}
}

getASalaryRecord

description: This API provides the functionality to get a salary record.

Request

Request url

GET `/company/:companyId/salary/:salaryId`

Query

name	type	description	required	default
companyId	number	specific id of the company	yes	-
salaryId	number	specific id of the salary record	yes	-

Request Example

GET `/company/1/salary/1`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	ISalaryRecordWithProjects \| {}	response data

ISalaryRecordWithProjects

name	type	description
id	number	unique number of the salary record
employeeId	number	unique number of the employee
employeeName	string	employee name
employeeDepartment	string	employee department
salary	number	employee salary
insurancePayment	number	insurance paid by the company(健保+勞保+勞退)
bonus	number	employee bonus
description	string	description of the salary record
startDate	number	start duration of the salary record
endDate	number	end duration of the salary record
workingHour	number	working hours in the duration of the salary record
confirmed	boolean	if the salary record is confirmed
createdAt	number	creation timestamp of the salary record
updatedAt	number	update timestamp of the salary record
projects	{ id: number; name: string }[]	involved projects of the salary record

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.8+52",
  "success": true,
  "code": "200ISF0002",
  "message": "Get successfully",
  "payload": {
    "id": 10000003,
    "employeeId": 10000000,
    "employeeName": "aook",
    "employeeDepartment": "Engineering",
    "salary": 200000,
    "insurancePayment": 1000,
    "bonus": 0,
    "description": "June Salary",
    "startDate": 1717527265,
    "endDate": 1720119265,
    "workingHour": 184,
    "confirmed": true,
    "createdAt": 1721635489,
    "updatedAt": 1721635854,
    "projects": [
      {
        "id": 9999991,
        "name": "iSunFA"
      }
    ]
  }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": {}
}

updateASalaryRecord

description: This API provides the functionality to update a salary record.

Request

Request url

PUT `/company/:companyId/salary/:salaryId`

Query

name	type	description	required	default
companyId	number	specific id of the company	yes	-
salaryId	number	specific id of the salary record	yes	-

Body

name	type	description
department	string	department of the employee
name	string	name of the employee
salary	number	salary of the employee
bonus	number	bonus of the employee
insurancePayment	number	insurance paid by the company(健保+勞保+勞退)
description	string	description of the salary record
projects	{ id: number; name: string; hours: number }[]	involved projects info of the salary record
startDate	number	start duration of the salary record
endDate	number	end duration of the salary record
workingHours	number	working hours in the duration of the salary record

Request Example

PUT `/company/1/salary/1`

Body

{
    "name": "book",
    "department": "Engineering",
    "salary": 5000,
    "insurancePayment": 200,
    "bonus": 0,
    "description": "June Salary",
    "startDate": 1717527265,
    "endDate": 1720119265,
    "workingHours": 184,
    "projects": [
      {
        "id": 9999991,
        "name": "iSunFA",
        "hours": 80
      },
      {
        "id": 9999992,
        "name": "BAIFA",
        "hours": 70
      }
    ]
  }

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	ISalaryRecordWithProjectsAndHours \| {}	response data

ISalaryRecordWithProjectsAndHours

name	type	description
id	number	unique number of the salary record
employeeId	number	unique number of the employee
employeeName	string	employee name
employeeDepartment	string	employee department
salary	number	employee salary
insurancePayment	number	insurance paid by the company(健保+勞保+勞退)
bonus	number	employee bonus
description	string	description of the salary record
startDate	number	start duration of the salary record
endDate	number	end duration of the salary record
workingHour	number	working hours in the duration of the salary record
confirmed	boolean	if the salary record is confirmed
createdAt	number	creation timestamp of the salary record
updatedAt	number	update timestamp of the salary record
projects	{ id: number; name: string; hours: number }[]	involved projects of the salary record

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.8+52",
    "success": true,
    "code": "200ISF0003",
    "message": "Update successfully",
    "payload": {
        "id": 10000004,
        "employeeId": 10000001,
        "employeeName": "book",
        "employeeDepartment": "Engineering",
        "salary": 5000,
        "insurancePayment": 200,
        "bonus": 0,
        "description": "June Salary",
        "startDate": 1717527265,
        "endDate": 1720119265,
        "workingHour": 184,
        "confirmed": true,
        "createdAt": 1721635489,
        "updatedAt": 1721637905,
        "projects": [
            {
                "id": 9999991,
                "name": "iSunFA",
                "hours": 80
            },
            {
                "id": 9999992,
                "name": "BAIFA",
                "hours": 70
            }
        ]
    }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": {}
}

createASalaryVoucher

description: This API provides the functionality to post a voucher for salary records.

Request

Request url

POST `/company/:companyId/salary/voucher`

Query

name	type	description	required	default
companyId	number	specific id of the company	yes	-

Body

name	type	description
salaryRecordsIdsList	number[]	array of IDs of salary records
voucherType	string	voucher type("Salary" / "Bonus")

Request Example

POST `/company/1/salary/voucher`

Body

{
    "salaryRecordsIdsList": [10000000,10000001,10000002],
    "voucherType": "Salary"    
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	voucherFolder \| {}	response data

voucherFolder

name	type	description
id	number	unique number of the folder
name	string	folder name
createdAt	number	creation timestamp of the folder
updatedAt	number	update timestamp of the folder
companyId	number	unique number of the company

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.8+52",
    "success": true,
    "code": "201ISF0000",
    "message": "Created successfully",
    "payload": {
        "id": 10000001,
        "name": "Salary Voucher: 20240722001",
        "createdAt": 1721638861,
        "updatedAt": 1721638861,
        "companyId": 10000000
    }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": {}
}

getAllSalaryVoucherFolders

description: This API provides the functionality to get all salary voucher folders.

Request

Request url

GET `/company/:companyId/salary/folder`

Query

name	type	description	required	default
companyId	number	specific id of the company	yes	-

Request Example

GET `/company/1/salary/folder`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	IFolder[] \| IFolder \| {}	response data

IFolder

name	type	description
id	number	unique number of the folder
name	string	folder name
createdAt	number	creation timestamp of the folder

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.8+52",
  "success": true,
  "code": "200ISF0001",
  "message": "List successfully",
  "payload": [
    {
      "id": 10000000,
      "name": "薪資傳票六月",
      "createdAt": 1721115205
    },
    {
      "id": 10000001,
      "name": "Salary Voucher: 20240722001",
      "createdAt": 1721638861
    }
  ]
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": {}
}

getASalaryVoucherFolder

description: This API provides the functionality to get a salary voucher folder with voucher and salary records.

Request

Request url

GET `/company/:companyId/salary/folder/:folderId`

Query

name	type	description	required	default
companyId	number	specific id of the company	yes	-
folderId	number	specific id of the folder	yes	-

Request Example

GET `/company/10000000/salary/folder/10000000`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	IFolderContent \| {}	response data

IFolderContent

name	type	description
id	number	unique number of the folder
name	string	folder name
createdAt	number	creation timestamp of the folder
voucher	IJournalListItem	the voucher info
salaryRecordList	ISalaryRecord[]	array of salary records for the voucher

IJournalListItem

name	type	description
id	number	unique id of the voucher
date	number	creation timestamp of the voucher
type	string	type of the voucher("Payment")
particulars	string	details of the voucher("Salary Bookkeeping")
fromTo	string	source or destination of the voucher("Employees")
account	{ id: number; debit: boolean; account: string; amount: number }[]	list of account details(id: accounting account code, debit: if it's a debit accounting account, account: accounting account name)
voucherId	number	unique id of the voucher
voucherNo	string	number of the voucher

ISalaryRecord

name	type	description
id	number	unique number of the salary record
employeeId	number	unique number of the employee
employeeName	string	employee name
employeeDepartment	string	employee department
salary	number	employee salary
insurancePayment	number	insurance paid by the company(健保+勞保+勞退)
bonus	number	employee bonus
description	string	description of the salary record
startDate	number	start duration of the salary record
endDate	number	end duration of the salary record
workingHour	number	working hours in the duration of the salary record
confirmed	boolean	if the salary record is confirmed
createdAt	number	creation timestamp of the salary record
updatedAt	number	update timestamp of the salary record

Response Example

成功的回傳

{
  "powerby": "iSunFA v0.1.8+52",
  "success": true,
  "code": "200ISF0002",
  "message": "Get successfully",
  "payload": {
    "id": 10000000,
    "name": "薪資傳票七月",
    "createdAt": 1721115205,
    "voucher": {
      "id": 10000000,
      "date": 1721115205,
      "type": "Payment",
      "particulars": "Salary Bookkeeping",
      "fromTo": "Employees",
      "account": [
        {
          "id": 2201,
          "debit": false,
          "account": "應付薪資",
          "amount": 15600
        },
        {
          "id": 6110,
          "debit": true,
          "account": "薪資支出",
          "amount": 15600
        }
      ],
      "voucherId": 10000000,
      "voucherNo": "20240716001"
    },
    "salaryRecordList": [
      {
        "id": 10000001,
        "employeeId": 10000001,
        "employeeName": "book",
        "employeeDepartment": "Engineering",
        "salary": 5000,
        "insurancePayment": 200,
        "bonus": 0,
        "description": "June Salary",
        "startDate": 1717527265,
        "endDate": 1720119265,
        "workingHour": 184,
        "confirmed": true,
        "createdAt": 1721115051,
        "updatedAt": 1721635854
      },
      {
        "id": 10000000,
        "employeeId": 10000000,
        "employeeName": "aook",
        "employeeDepartment": "Engineering",
        "salary": 6000,
        "insurancePayment": 250,
        "bonus": 0,
        "description": "June Salary",
        "startDate": 1717527265,
        "endDate": 1720119265,
        "workingHour": 184,
        "confirmed": true,
        "createdAt": 1721115051,
        "updatedAt": 1721635854
      },
      {
        "id": 10000002,
        "employeeId": 10000002,
        "employeeName": "cook",
        "employeeDepartment": "Engineering",
        "salary": 4000,
        "insurancePayment": 150,
        "bonus": 0,
        "description": "June Salary",
        "startDate": 1717527265,
        "endDate": 1720119265,
        "workingHour": 184,
        "confirmed": true,
        "createdAt": 1721115051,
        "updatedAt": 1721635854
      }
    ]
  }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": {}
}

updateASalaryVoucherFolder

description: This API provides the functionality to update a name of a salary voucher folder.

Request

Request url

PUT `/company/:companyId/salary/folder/:folderId`

Query

name	type	description	required	default
companyId	number	specific id of the company	yes	-
folderId	number	specific id of the folder	yes	-

Body

name	type	description
name	string	name of the folder

Request Example

PUT `/company/10000000/salary/folder/10000000`

Body

{
    "name": "薪資傳票七月"
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	IFolder \| {}	response data

IFolder

name	type	description
id	number	unique number of the folder
name	string	folder name
createdAt	number	creation timestamp of the folder

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.8+52",
    "success": true,
    "code": "200ISF0003",
    "message": "Update successfully",
    "payload": {
        "id": 10000000,
        "name": "薪資傳票七月",
        "createdAt": 1721115205
    }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": {}
}

deleteAJournalById

description: This API provides the functionality to delete a journal by id through updating delete time for related payment, invoice, lineItem, voucher, journal data.

Request

Request url

DELETE `/company/:companyId/journal/:journalId`

Query

name	type	description	required	default
companyId	number	specific id of the company	yes	-
journalId	number	specific id of the journal	yes	-

Request Example

DELETE `/company/1/journal/10000035`

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	Journal \| null	response data

Journal

name	type	description
id	number	the id of the journal
event	JOURNAL_EVENT	the journal event
tokenContract	string	the token contract address
tokenId	string	the token identifier
aichResultId	string	the AI check result identifier
projectId	number	the project identifier
contractId	number	the contract identifier
imageUrl	string	the image URL
invoice	Invoice	the invoice data
voucher	VoucherDataForSavingToDB	the voucher data for saving to DB

JOURNAL_EVENT

JOURNAL_EVENT {
  UPLOADED = 'JOURNAL.UPLOADED',
  UPCOMING = 'JOURNAL.UPCOMING',
}

Invoice

name	type	description
journalId	number	the id of the journal
date	number	The timestamp representing the date and time. (second)
eventType	EventType	The type of event ('income', 'payment', 'transfer').
paymentReason	string	The reason for the payment.
description	string	A description of the transaction.
vendorOrSupplier	string	The name of the vendor or supplier involved.
projectId	number \|null	The identifier for the project. (can be null )
project	string \|null	The name of the project. (can be null )
contractId	number \|null	The unique identifier for the contract. (can be null )
contract	string \|null	The name or title of the contract. (can be null )
payment	Payment	A object containing payment details.

VoucherDataForSavingToDB

name	type	description
journalId	number	the id of the journal
lineItems	LineItem[]	Line items of voucher, each line item represent each line in url voucher

LineItem

name	type	description
lineItemIndex	string	The unique index of the line item entry. But this has no actual meaning, just random response from aich, real id will be number and store in db
account	string	The account associated with the line item.
description	string	A detailed description of the line item.
debit	boolean	Indicates if the item is a debit (true) or credit (false).
amount	number	The monetary amount of the line item.
accountId	number	account number.

Payment

name	type	description
isRevenue	boolean	Indicates if the transaction will generate income. True: money is coming in; false: going out.
price	number	The total amount of money involved in the transaction.
hasTax	boolean	Specifies whether the amount includes tax.
taxPercentage	number	The tax rate, for example, 0 or 5, etc.
hasFee	boolean	Indicates whether there is a handling fee included.
fee	number	The amount of the handling fee.
method	string	The method by which money is received or paid out.
period	PaymentPeriodType (enum)	The timing of payment, either at once (atOnce) or in installments (installment).
installmentPeriod	number	The number of installments for payment.
alreadyPaid	number	The amount of money that has already been paid or collected.
status	PaymentStatusType(enum)	The status of the payment. "paid" or "unpaid" or "partial
progress	number	The actual work completion percentage for a contract, not referring to payment progress.

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.8+103",
    "success": true,
    "code": "200ISF0004",
    "message": "Delete successfully",
    "payload": {
        "id": 10000224,
        "tokenContract": "",
        "tokenId": "",
        "aichResultId": "b75850fb4d0601ad5f1d",
        "projectId": 0,
        "contractId": 0,
        "imageUrl": "/api/v1/company/0/invoice/b8f3fcc73af5234058614fe04.png/image",
        "event": "JOURNAL.UPLOADED",
        "invoice": {
            "journalId": 10000224,
            "date": 1723132800,
            "eventType": "income",
            "paymentReason": "123",
            "description": "123",
            "vendorOrSupplier": "123",
            "projectId": null,
            "project": null,
            "contractId": null,
            "contract": null,
            "payment": {
                "isRevenue": true,
                "price": 1000,
                "hasTax": true,
                "taxPercentage": 52,
                "hasFee": false,
                "fee": 0,
                "method": "",
                "period": "atOnce",
                "installmentPeriod": 0,
                "alreadyPaid": 1610599188,
                "status": "paid",
                "progress": 100
            }
        },
        "voucher": {
            "journalId": 10000224,
            "lineItems": [
                {
                    "lineItemIndex": "10000310",
                    "amount": 1000,
                    "debit": true,
                    "account": "指定透過損益按公允價值衡量之金融資產評價調整－流動",
                    "description": "222",
                    "accountId": 10000546
                },
                {
                    "lineItemIndex": "10000311",
                    "amount": 1000,
                    "debit": false,
                    "account": "零用金／週轉金",
                    "description": "222",
                    "accountId": 10000541
                }
            ]
        }
    }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": null
}

updateAVoucherById

Description: This API provides the functionality to update a voucher info.

Request

Request url

PUT /company/:companyId/voucher/:voucherId

Query

name	type	description	required	default
companyId	number	specific id of the company	yes	-
voucherId	number	specific id of the voucher	yes	-

Body

name	type	description	require
voucher	IVoucherDataForSavingToDB	read down below, this combine two data, journalId and lineItems	true

IVoucherDataForSavingToDB

name	type	description	require
journalId	number	the index of journal that will be connect to new voucher	true
lineItems	ILineItem[]	the line items of the voucher (ILineItems need to have accountId)	true

Request Example

PUT /company/1/voucher/1

Body: JSON type

{
    "voucher": {
        "journalId": 15,
        "lineItems": [
            {
                "lineItemIndex": "'20240426001'",
                "account": "'電信費'",
                "description": "'光世代電路月租費： 593, HiNet企業專案服務費: 1607'",
                "debit": true,
                "amount": 2210,
                "accountId": 1
            },
            {
                "lineItemIndex": "'20240325002'",
                "account": "'進項稅額'",
                "description": "'WSTP會計師工作輔助幡: 88,725, 文中網路版主機授權費用: 8,400, 文中工作站授權費用: 6,300'",
                "debit": true,
                "amount": 110,
                "accountId": 2
            },
            {
                "lineItemIndex": "'20240426003'",
                "account": "'銀行存款'",
                "description": "'合庫銀行'",
                "debit": false,
                "amount": 2310,
                "accountId": 3
            }
        ]
    }
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Custom type \| null	the shape of data has no interface, but it follow Prisma.voucher

payload custom type

name	type	description
id	number	the id of the voucher that was created
journalId	number	the journal that the voucher connect to
no	string	the voucher serial number, it will increase base on company, format is `YYYYMMDD001`
createdAt	number	the timestamp of the voucher created (timestamp in second)
updatedAt	number	the timestamp of the voucher updated (timestamp in second)
deletedAt	number	the timestamp of the voucher deleted (timestamp in second)
lineItems	Prisma.LineItem[] \| null	the lineItems that was created

Prisma.LineItem

name	type	description
id	number	the id of the lineItem
amount	number	the amount of the lineItem
description	string	the description of the lineItem
debit	boolean	is debit or credit
accountId	number	the account that the lineItem connect to
voucherId	number	the voucher that the lineItem connect to
createdAt	number	the timestamp of the lineItem created (timestamp in second)
updatedAt	number	the timestamp of the lineItem updated (timestamp in second)
deletedAt	number	the timestamp of the lineItem deleted (timestamp in second)

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.4+78",
    "success": true,
    "code": "201ISF0000",
    "message": "Created successfully",
    "payload": {
        "id": 1,
        "journalId": 1,
        "no": "2024617001",
        "createdAt": 1718612861,
        "updatedAt": 1718612861,
        "deletedAt": null,
        "lineItems": [
            {
                "id": 2,
                "amount": 110,
                "description": "'WSTP會計師工作輔助幡: 88,725, 文中網路版主機授權費用: 8,400, 文中工作站授權費用: 6,300'",
                "debit": true,
                "accountId": 61,
                "voucherId": 1,
                "createdAt": 1718612861,
                "updatedAt": 1718612861,
                "deletedAt": null
            },
            {
                "id": 1,
                "amount": 2210,
                "description": "'光世代電路月租費： 593, HiNet企業專案服務費: 1607'",
                "debit": true,
                "accountId": 61,
                "voucherId": 1,
                "createdAt": 1718612861,
                "updatedAt": 1718612861,
                "deletedAt": null
            },
            {
                "id": 3,
                "amount": 2310,
                "description": "'合庫銀行'",
                "debit": false,
                "accountId": 61,
                "voucherId": 1,
                "createdAt": 1718612861,
                "updatedAt": 1718612861,
                "deletedAt": null
            }
        ]
    }
}

失敗的回傳

{
  "powerby": "iSunFA v0.1.2+50",
  "success": false,
  "code":  "502",
  "message": "Bad gateway data from AICH is invalid type",
  "payload": {}
}

createFile

description: post file for kyc, company, user, project, invoice, it can provide encrypted file with symmetric key and iv, if encrypted file is provided, it will be save in encrypt and be decrypted when get from image

Request

Request url

POST /company/:companyId/file

Request Example

POST / company / 1 / file;

Query

name	type	description	require	default
type	UploadType	type of usage	true	-
targetId	number	target id, this will base on type, and change which table in database this file will connect to (only `company`, `user`, `project` will be connect, `kyc` and `invoice` will just create `File`) ex: if type is `UploadType.company` and targetId is `1000000`, new file created will be connect to company by id: `10000000`	true	-

UploadType

name	type	description	require	default
KYC	string	kyc file	true	-
COMPANY	string	company image	true	-
USER	string	user image	true	-
PROJECT	string	project image	true	-
INVOICE	string	invoice for ocr	true	-

Body

name	type	description	require	default
formData	FormData	Need to use `new FormData` to post images (see example down below)	true	-

FormData

name	type	description	require	default
file	formidable.File[]	An array of Image	true	-
field	formidable.Fields, it will be look like `{[string]: [ array of string data]}`, check below for what to put inside field	need to use `formData.append('fieldName', actual data)`to add data, like: `formData.append('isEncrypted', true)`	false (default value will be used if not append any data)	check below

Field

name	type	description	require	default
isEncrypted	boolean	if the file is encrypted	false	false
encryptedSymmetricKey	string	encrypted symmetric key	false	''
iv	string	initialization vector, it should be an Uint8Array than be join by ',' `Array.from(item.iv).join(',')`	false	''

Request Example

  POST /company/1/file?type=company&?targetId=1

createUserAgreement

description: This API provides the functionality to create an agreement for user.

Request

Request url

POST `/user/:userId/agreement`

Body

name	type	description
agreementHash	string	hash of the agreement

Request Example

POST `/user/1/agreement`

Body

{
    "agreementHash": "0x1234567890"
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description of response data
payload	IUser \| {}	response data

User

name	type	description
id	number	unique number of user
name	string	user name
fullName	string	user full name
email	string	user email
phone	string	user phone
imageId	string	user image id
agreementList	string[]	list of agreement hash
createdAt	number	creation timestamp
updatedAt	number	update timestamp

Response Example

成功的回傳

{
    "powerby": "iSunFA v0.1.8+52",
    "success": true,
    "code": "201ISF0000",
    "message": "Created successfully",
    "payload": {
        "id": 10000001,
        "name": "book",
        "fullName": "book",
        "email": "[email protected]",
        "phone": "0912345678",
        "imageId": "0x1234567890",
        "agreementList": ["0x1234567890"],
        "createdAt": 1721635489,
        "updatedAt": 1721635489
    }
}

失敗的回傳

{
    "powerby": "iSunFA v0.1.2+50",
    "success": false,
    "code":  "400",
    "message": "bad request",
    "payload": {}
}

getPaymentByOrderId

description:
- get payment by order id

Request

Request url

GET /company/:companyId/payment?orderId=

Param

name	type	description	required	default
companyId	string	specific id of the company	yes	-

Query

name	type	description	required	default
orderId	string	specific id of the order	yes	-

Request Example

GET /company/1/payment?orderId=ORDER00001

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	string	redirectUrl

Response example

成功的回傳

{
    "powerby": "iSunFA v0.1.4+55",
    "success": true,
    "code": "200ISF0002",
    "message": "Get successfully",
    "payload":  "https://${merchantId}.testing.oen.tw/checkout/subscription/create/${id}"
}

失敗的回傳

{
        "powerby": "iSunFA v0.1.2+50",
        "success": false,
        "code":  "400",
        "message": "bad request",
        "payload": ""
}

createPayment

description:
- create payment

Request

Request url

POST /company/:companyId/payment

Param

name	type	description	required	default
companyId	string	specific id of the company	yes	-

Body

name	type	description	required	default
token	string	specific id of the token	yes	-
customId	string	json stringify, with orderIdNum, subPlan, subPeriod	yes	-

Request Example

POST /company/1/payment
{
    "token": "2etM3aQSCMWv7OGYQ6gDWtcOJaR",
    "customId": "{"orderId":1,"subPlan":"Trail","subPeriod":30}"
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	string	payment record status

Response example

成功的回傳

{
    "powerby": "iSunFA v0.1.4+55",
    "success": true,
    "code": "200ISF0002",
    "message": "Create successfully",
    "payload":  "success"
}

失敗的回傳

{
        "powerby": "iSunFA v0.1.2+50",
        "success": false,
        "code":  "400",
        "message": "bad request",
        "payload": ""
}

getOrderList

description:
- get order list

Request

Request url

GET /company/:companyId/order

Param

name	type	description	required	default
companyId	string	specific id of the company	yes	-

Request Example

GET /company/1/order

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Order[]	order list

Order

name	type	description
id	number	Unique identifier for the order
companyId	number	Identifier for the associated company
planId	number	Identifier for the associated plan
status	string	Current status of the order
createdAt	number	Timestamp when the order was created
updatedAt	number	Timestamp when the order was last updated

Response example

成功的回傳

{
    "powerby": "iSunFA v0.1.4+55",
    "success": true,
    "code": "200ISF0002",
    "message": "list successfully",
    "payload":  [
        {
            "id": 1,
            "companyId": 1,
            "planId": 1,
            "status": "success",
            "createdAt": 1630000000,
            "updatedAt": 1630000000
        }
    ]
}

失敗的回傳

{
        "powerby": "iSunFA v0.1.2+50",
        "success": false,
        "code":  "400",
        "message": "bad request",
        "payload": {}
}

createAnOrder

description:
- create an order

Request

Request url

POST /company/:companyId/order

Param

name	type	description	required	default
companyId	string	specific id of the company	yes	-

Body

name	type	description	required	default
planId	number	specific id of the plan	yes	-
status	string	status of the order	yes	-

Request Example

POST /company/1/order

{
    "planId": 1,
    "status": "active"
}

Response

Response Parameters

name	type	description
powerby	string	iSunFA v0.1.2+50
success	boolean	true or false
code	string	response code
message	string	description the status of the request
payload	Order	an order

Response example

成功的回傳

{
    "powerby": "iSunFA v0.1.4+55",
    "success": true,
    "code": "200ISF0002",
    "message": "Create successfully",
    "payload": {
      "id": 12345,
      "companyId": 678,
      "planId": 91011,
      "status": "active",
      "createdAt": 1627890123,
      "updatedAt": 1627891123
    }

}

失敗的回傳

{
        "powerby": "iSunFA v0.1.2+50",
        "success": false,
        "code":  "400",
        "message": "bad request",
        "payload": {}
}

API v1 - CAFECA-IO/iSunFA GitHub Wiki

API list

BaseUrl: /api/v1

除 A010001, C070001, S040001, S050001, S060001 API不驗證登入, 其餘API皆會驗證登入

Format

BaseUrl = /api/v1

API Example

Request

Request url

Parameters

Request Example

Response

Response Parameters

Response Example

listClient

Request

Request url

Request Example

Response

Response Parameters

Client

Response Example

getClientById

Request

Request url

Request Example

Response

Response Parameters

Client

Response Example

createClient

Request

Request url

body

Request Example

Response

Response Parameters

Client

Response Example

updateClientById

Request

Request url

body

Request Example

Response

Response Parameters

Client

Response Example

deleteClientById

Request

Request url

Request Example

Response

Response Parameters

Client

Response Example

listContract

Request

Request URL

Query Parameters

Request Example

Response

Response Parameters

Response Example

getAContract

Description

Request

Request URL

Parameters

Request Example

Response

Response Parameters

Response Example

createAContract

Description

Request

Request URL

Headers

Body

Request Example

BaseUrl: `/api/v1`