# Tradevan E-Invoice APIs ## Overview * Preparation * Encode Request * Decode Response * APIs ## Preparation After contacting with Tradevan, you'll get * acnt: your account name * acntp: your account password * key1: 1st AES encryption key * key2: 2nd AES encryption key ## Encode Request * Method: POST/GET * URL: "#{endpoint}/#{path}" * Parameters: "#{v}" * v: `Base64_strict.encode(AES.encrypt(key2, { acnt: "#{acnt}", acntp: "#{acntp}", api_key1: "#{encryption_of_api_value1}", api_key2: "#{encryption_of_api_value2}", ... }))` * `AES.encrypt(key, content)`: * mode: CBC-128 * key: use `key2` for outter encryption, use `key1` for inner value encryption * iv: same as key * padding: no, but you should manually pad with `"\u0000"`(character space in bytes format) to fit correct CBC block size * encryption_of_api_value1: `Base64_strict.encode(AES.encrypt(key1, api_value1))` ## Decode Response * Format: JSON, i.e. `{ "Success": "Y", "Message": "#{encryption_of_message}" }` * Success: "Y" for OK, "N" for Failure, "E" for Error * Message: * Plain Text when `"Success": "E"` * Encryption Text when `"Success": "Y"` or `"Success": "N"` * Decryption: `AES.decrypt(key2, Base64_strict.decode(response["Message"]))` * `AES.decrypt(key, content)`: * mode: CBC-128 * key: use `key2` for decrypt `response["Message"]` content * iv: key * padding: no ## APIs ### POST /DEFAULTAPI/post/issue You could use this API to do 1. issue an new invoice 2. issue an existed invoice 3. issue an allowance 4. issue an existed allowance #### Parameters * issueData * type: json ### POST /DEFAULTAPI/post/cancel You could use this API to do 1. cancel an existed invoice 2. cancel an allowance #### Parameters * voidData * type: json ### GET /DEFAULTAPI/get/searchInvoiceByMemberId #### Parameters * invoiceStartDate * description: begining of invoice issued date interval * type: string * require: false * format: yyyyMMdd * invoiceEndDate * description: end of invoice issued date interval * type: string * require: false * format: yyyyMMdd * companyUn * description: company universal business number(ubn) of Taiwan * type: string * require: true * memberId * description: customer's member id of your service * type: string * require: true if `sellTargetCode` and `carrierId` are empty * carrierId * description: customer's carrier id of invoices * type: string * require: true if `memberId` and `sellTargetCode` are empty * sellTargetCode * description: ? * type: string * require: true if `memberId` and `carrierId` are empty ### GET /DEFAULTAPI/get/searchInvoiceDetail #### Parameters * invoiceNumber * description: invoice number * type: string * require: true ### GET /DEFAULTAPI/get/sendCardInfotoCust #### Parameters * companyUn * description: company universal business number(ubn) of Taiwan * type: string * require: true * sellTargetCode * description: ? * type: string * require: true * invoiceStartYM * description: begining of invoice issued year and month interval * type: string * require: false * format: yyyyMM * invoiceEndYM * description: end of invoice issued year and month interval * type: string * require: false * format: yyyyMM * receiverEmail * description: receiver's email * type: string * require: true if `receiverMobile` is empty * receiverMobile * description: receiver's mobile * type: string * require: true if `receiverEmail` is empty ### GET /DEFAULTAPI/get/getInvoiceMarkInfo #### Parameters * companyUn * description: your company universal business number(ubn) of Taiwan * type: string * require: true * orgId * description: your orgId * type: string * require: true * uniFiedNumber * description: your company or branch ubn used to issue invoices * type: string * require: true * bookType * description: your book type * type: string * require: true * period * description: query year with or without months * type: string * require: true * format: yyyymm ### GET /DEFAULTAPI/get/getDonateUnitList #### Parameters * companyUn * description: company universal business number(ubn) of Taiwan * type: string * require: true ### GET /DEFAULTAPI/get/getInvoiceContent #### Parameters * invoiceNumber * description: invoice number * type: string * require: true if `sellTargetCode` is empty * sellTargetCode * description: ? * type: string * require: true if `invoiceNumber` is empty * invoiceStartDate * description: begining of invoice issued date interval * type: string * require: false * format: yyyyMMdd * invoiceEndDate * description: end of invoice issued date interval * type: string * require: false * format: yyyyMMdd