1. Pulling Up Invoice List from Weixin Official Account

2. Pulling Up Invoice List from Weixin Mini Program

3. Pulling Up Invoice List from Weixin Work

4. Pulling Up Invoice List from External App

5. Querying Reimbursement Invoice Information

6. Querying Reimbursement Invoice Information in Batch

7. Updating Invoice Status by Reimburser

8. Updating Invoice Statuses in Batch by Reimburser

9. Error Codes

10. List of Invoice Reimbursement Status


# 1. Pulling Up Invoice List from Weixin Official Account

API description

This API is used to pull up an invoice card list in a Weixin Official Account. After a user selects an invoice to submit for reimbursement, the developer obtains identification information for the selected invoice.

Calls to this API must follow the JS-SDK call method. Before development, read the [Weixin JS-SDK API Documentation](http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141115&token=&lang=zh_CN" target="_blank) to get familiar with the development terminology and basic API calls.

Request method

Call the chooseInvoice API.

Request parameters

Parameter Type Required Description
timestamp string(32) Yes Timestamp, expressed as a 10-digit Unix timestamp.
nonceStr string(32) Yes The random string

Response

After the user taps OK or Cancel, a result containing the following fields is returned.

Parameter Type Required Description
err_msg string Yes ok: Invoice selected successfully; fail: Invoice selection failed; cancel: Invoice selection canceled.
choose_invoice_info object No The list of invoices selected by the user

The choose_invoice_info object contains the following fields:

Parameter Type Required Description
card_id string Yes The card_id of the selected invoice card
encrypt_code string Yes The encryption code of the selected invoice card. The reimburser can obtain the information of the reimbursement invoice based on card_id and encrypt_code.
app_id string Yes The appid of the invoice issuer

Sample code

wx.config({
    beta: true,
    debug: false,
    appId: "wx00000000000000",
    timestamp: 1489030247,
    nonceStr: "(9J4YRV[#@",
    signature: "f027317f8910000000000000000000",
    jsApiList: ['chooseInvoice']
});
wx.ready(function () {
    wx.invoke('chooseInvoice', {
        'timestamp': 1489030247, 
        'nonceStr': "p(6N&7WOAF", 
        }, function(res) {
            alert(JSON.stringify(res));
        }
    });
});

# 2. Pulling Up Invoice List from Weixin Mini Program

API description

This API is used to pull up an invoice list in a Weixin Mini Program.

See the invoice section in the Mini Program API documentation for details.

# 3. Pulling Up Invoice List from Weixin Work

API description

Weixin Work 2.1 comes with a JS-API to select electronic invoices. After a company updates its Weixin Work version to 2.1 or later, it can quickly implement electronic invoice selection in Weixin Work.

See the electronic invoice section in the Weixin Work API documentation for details.

# 4. Pulling Up Invoice List from External App

API description

For companies with self-deployed mobile office apps and reimbursement service providers who provide independent reimbursement apps to companies, Weixin provides an API that allows external apps to pull up the invoice list. Just like the API to pull up the invoice list in Weixin, external app developers can obtain invoice identification data after a user selects an invoice and taps OK.

Calls to this API must follow the JS-SDK calling method. Before development, make sure the following conditions are met:

(1) You have a verified Weixin Open Platform account.

(2) You have created an app on the Weixin Open Platform and it has passed the verification. Developers of unregistered apps can register their apps on the app registration page.

(3) You have read the basic SDK usage methods in the Weixin Open Platform Resource Center and the SDKs are correctly used in your app.

Request method

iOS apps

Refer to the OpenSDK1.7.7 file in the code package. During use, call the WXChooseInvoice class. Refer to the JS-SDK call method for information about the required signature. Sample code

—(void)getlnvoiceWithTicket: (NSString*)ticket whenComptetion: (void(^)(NSString* result, NSString*errorDesc) )comptetion{
BOOL isWXApplnstalled = [WXApi isWXApplnstalled]; 
if (!isWXApplnstalled) { // The result is directly returned if Weixin is not installed.
completion(nil.,@"Wechat Not installed");
return;
}
_completion = completion;
WXChooselnvoiceReq *cardReq = [[WXChooselnvoiceReq alloc]initl; 
cardReq. applD = WechatlnvoiceAppld;
cardReq.timeStamp = [[NSDate date]timelntervalSince1970]; 
NSString* timeStamp = [NSString stringWithFormat:@"%d",cardReq.timeStamp]; 
cardReq. nonceStr = @"sfim_invoice";

NSString *cardSign = [self genCardSignWithNonceStr: cardReq.nonceStr andTimeStr:
timeStamp andApiTicket:ticket];
cardReq.cardSign = cardSign;
[WXApi sendReq:cardReq];//Send

Android apps

Refer to the JAR file in the code package. During use, call the ChooseCardFromWXCardPackage class and set the CardType to "INVOICE". Refer to the JS-SDK call method for information about the required signature.

Response

After the user taps OK or Cancel, a result containing the following fields is returned.

Parameter Type Required Description
err_msg string Yes ok: Invoice selected successfully; fail: Invoice selection failed; cancel: Invoice selection canceled.
choose_invoice_info object No The list of invoices selected by the user

The choose_invoice_info object contains the following fields:

Parameter Type Required Description
card_id string Yes The card_id of the selected invoice card
encrypt_code string Yes The encryption code of the selected invoice card. The reimburser can obtain the information of the reimbursement invoice based on card_id and encrypt_code.
app_id string Yes The appid of the invoice issuer

# 5. Querying Reimbursement Invoice Information

API description

This API is used to query the structured information of an electronic invoice and obtain the invoice's PDF file.

Request method

Request URL: https://api.weixin.qq.com/card/invoice/reimburse/getinvoiceinfo?access_token={access_token}

Request method: POST

Request parameters

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
card_id string Yes The card_id of the invoice card
encrypt_code string Yes The encrypted code of the invoice card. encrypt_code and card_id are used together to construct the unique identifier of an invoice card.

Response

The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message

If the error code is 0, the following information is returned:

Parameter Type Required Description
card_id String Yes The invoice ID
begin_time Int Yes Start time of the invoice validity period
end_time Int Yes End time of the invoice validity period
openid String Yes User ID
type String Yes Invoice type, such as Guangdong VAT invoice.
payee String Yes Invoice payee
detail String Yes Invoice details
user_info Object Yes The primary information on an invoice

user_info contains the following information:

Parameter Type Required Description
fee Int Yes Tax-inclusive amount of the invoice (in cents)
title String Yes The invoice title
billing_time Int Yes The invoicing time, expressed as a 10-digit timestamp (utc+8).
billing_no String Yes The invoice number
billing_code String Yes The invoice code
info List No The product information structure, explained below.
fee_without_tax Int Yes Tax-exclusive amount (in cents)
tax Int Yes The tax amount (in cents)
pdf_url String Yes The PDF_URL corresponding to the invoice
trip_pdf_url String No URLs of other proofs of purchase, such as itineraries and water bills.
reimburse_status String Yes The invoice reimbursement status. See Notes 7.4.
check_code String Yes The verification code (required)
buyer_number String No The buyer's taxpayer ID (optional)
buyer_address_and_phone String No The buyer's address and phone number (optional)
buyer_bank_account String No The buyer's bank and bank account (optional)
seller_number String No The seller's taxpayer ID (optional)
seller_address_and_phone String No The seller's address and phone number (optional)
seller_bank_account String No The seller's bank and bank account (optional)
remarks String No Remarks
cashier String No The payee, in the lower left corner of the invoice (optional)
maker String No The invoice issuer, in the lower right corner of the invoice (optional)

info provides the information of invoice items. The data is expressed as an Object list, and each Object in the list includes the following information:

Parameter Type Required Description
name String Yes Item (product) name
num Int No Item quantity
unit String No Item unit
price Int Yes Unit price (in cents)

Sample code

Request:
{
    "card_id": "pjZ8Yt5crPbAouhFqFf6JFgZv4Lc",
    "encrypt_code": "fbdt/fWy1VitQwhbKtSjNeR3BJyfpeJXfZjjGsdCXiM="
}
Response:
{
    "errcode": 0,
    "errmsg": "ok",
    "card_id": "pjZ8Yt5crPbAouhFqFf6JFgZv4Lc",
    "begin_time": 1476068114,
    "end_time": 1476168114,
    "user_card_status": "EXPIRE",
    "openid": "obLatjnG4vRXJvSO8p914rSK8-Vo",
    "type": "Guangdong VAT invoice",
    "payee": "Test - Payee",
    "detail": "Test - detail",
    "user_info": {
        "fee": 1100,
        "title": "XX company",
        "billing_time": 1468322401,
        "billing_no": "hello",
        "billing_code": "world",
            "info": [
                {
                    "name": "Green Giant",
                    "num": 10,
                    "unit": "Tons",
                    "price": 4
                }
        ],
        "accept": true,
        "fee_without_tax": 2345,
        "tax": 123,
        "pdf_url": "pdf_url",
        " reimburse_status": "INVOICE_REIMBURSE_INIT",
    }
}

# 6. Querying Reimbursement Invoice Information in Batch

API description

This API is used to query the structured information of electronic invoices in batch and obtain their PDF files.

Request method

Request URL: https://api.weixin.qq.com/card/invoice/reimburse/getinvoicebatch?access_token={access_token}

Request method: POST

Request parameters

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
item_list List Yes Invoice list

Each object in the item_list contains the following fields:

Parameter Type Required Description
card_id string Yes The card_id of the invoice card
encrypt_code string Yes The encrypted code of the invoice card. encrypt_code and card_id are used together to construct the unique identifier of an invoice card.

Response

The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message
item_list List Yes Invoice information

If the error code is 0, each object in the item_list contains the following information:

Parameter Type Required Description
card_id String Yes The invoice ID
begin_time Int Yes Start time of the invoice validity period
end_time Int Yes End time of the invoice validity period
openid String Yes User ID
type String Yes Invoice type, such as Guangdong VAT invoice.
payee String Yes Invoice payee
detail String Yes Invoice details
user_info Object Yes The primary information on an invoice

user_info contains the following information:

Parameter Type Required Description
fee Int Yes Tax-inclusive amount of the invoice (in cents)
title String Yes The invoice title
billing_time Int Yes The invoicing time, expressed as a 10-digit timestamp (utc+8).
billing_no String Yes The invoice number
billing_code String Yes The invoice code
info List No The product information structure, explained below.
fee_without_tax Int Yes Tax-exclusive amount (in cents)
tax Int Yes The tax amount (in cents)
pdf_url String Yes The PDF_URL corresponding to the invoice
trip_pdf_url String No URLs of other proofs of purchase, such as itineraries and water bills.
reimburse_status String Yes The invoice reimbursement status. See Notes 7.4.
check_code String Yes The verification code (required)
buyer_number String No The buyer's taxpayer ID (optional)
buyer_address_and_phone String No The buyer's address and phone number (optional)
buyer_bank_account String No The buyer's bank and bank account (optional)
seller_number String No The seller's taxpayer ID (optional)
seller_address_and_phone String No The seller's address and phone number (optional)
seller_bank_account String No The seller's bank and bank account (optional)
remarks String No Remarks
cashier String No The payee, in the lower left corner of the invoice (optional)
maker String No The invoice issuer, in the lower right corner of the invoice (optional)

info provides the information of invoice items. The data is expressed as an Object list, and each Object in the list includes the following information:

Parameter Type Required Description
name String Yes Item (product) name
num Int No Item quantity
unit String No Item unit
price Int Yes Unit price (in cents)

Sample code

Request:
{
    "item_list": [
        {
            "card_id": "pjZ8Yt7KKEXWMpETmwG2ZZxX2m6E",
            "encrypt_code": "O/mPnGTpBu22a1szmK2 "
        },
        {
            "card_id": "pjZ8YtxSguaLUaaDqzeAf385soJM",
            "encrypt_code": "O/mPnGTpBu22a1szmK2ogz "
        }
    ]
}
Response:
{
    "errcode": 0,
    "errmsg": "ok",
    "item_list": [
        {
            "user_info": {
                "fee": 123,
                "title": "Guan Ge's invoice",
                "billing_time": 1504085973,
                "billing_no": "1504085973",
                "billing_code": "aabbccdd",
                "info": [
                    {
                        "name": "Toothpaste",
                        "num": 3,
                        "unit": "Tube"
                        "price": 10000
                    }
                ],
                "fee_without_tax": 2345, 
                "tax": 123, 
                "detail": "Item", 
                "pdf_url": "http://pdfurl", 
                "reimburse_status": "INVOICE_REIMBURSE_INIT", 
                "order_id": "1504085935", 
                "check_code": "check_code", 
                "buyer_number": "buyer_number"
            }, 
            "card_id": "pjZ8Yt7KKEXWMpETmwG2ZZxX2m6E", 
            "openid": "oZI8Fj8L63WugQsljlzzfCcw3AkQ", 
            "type": "Guangdong VAT invoice", 
            "payee": "Test - Payee", 
            "detail": "detail"
        }, 
        {
            "user_info": {
                "fee": 123, 
                "title": "Guan Ge's invoice", 
                "billing_time": 1504083578, 
                "billing_no": "1504083578", 
                "billing_code": "aabbccdd", 
                "info": [
                    {
                        "name": "Toothpaste", 
                        "num": 3, 
                        "unit": "Tube" 
                        "price": 10000
                    }
                ], 
                "fee_without_tax": 2345, 
                "tax": 123, 
                "detail": "Item", 
                "pdf_url": " http://pdfurl", 
                "reimburse_status": "INVOICE_REIMBURSE_INIT", 
                "order_id": "1504083522", 
                "check_code": "check_code", 
                "buyer_number": "buyer_number"
            }, 
            "card_id": "pjZ8YtxSguaLUaaDqzeAf385soJM", 
            "openid": "oZI8Fj8L63WugQsljlzzfCcw3AkQ", 
            "type": "Guangdong VAT invoice", 
            "payee": "Test - Payee", 
            "detail": "detail"
        }
    ]
}

# 7. Updating Invoice Status by Reimburser

API description

Reimbursing companies and reimbursement service providers can use this API to lock, unlock, or reimburse an invoice, as described below:

Lock: The electronic invoice should be locked after it enters the reimbursement process of the company. After an electronic invoice is locked, it still appears in the user's Cards & Offers, but cannot be submitted for reimbursement again.

Unlock: When the reimbursement process cannot be completed for an electronic invoice, it should be unlocked. After an electronic invoice is unlocked, it can be submitted for reimbursement again.

Reimburse: After an electronic invoice is reimbursed, this API should be used to perform the reimbursement operation. After this operation is performed, the electronic invoice is removed from the user's Cards & Offers. The user can view the electronic invoice's write-off information in the Cards & Offers messages. Note that the reimbursement operation is irreversible so call this API with caution.

Request method

Request URL: https://api.weixin.qq.com/card/invoice/reimburse/updateinvoicestatus?access_token={access_token}

Request method: POST

Request parameters

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
card_id string Yes The card_id of the invoice card
encrypt_code string Yes The encrypted code of the invoice card. encrypt_code and card_id are used together to construct the unique identifier of an invoice card.
reimburse_status string Yes The invoice reimbursement status

Response

The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message

Sample code

Request:
{
    "card_id": "pjZ8Yt5crPbAouhFqFf6JFgZv4Lc",
    "encrypt_code": "fbdt/fWy1VitQwhbKtSjNeR3BJyfpeJXfZjjGsdCXiM=",
    "reimburse_status": "INVOICE_REIMBURSE_INIT"
}
Response:
{
    "errcode": 0,
    "errmsg": "ok"
}

# 8. Updating Invoice Statuses in Batch by Reimburser

API description

An invoicing platform can call this API to lock, unlock, or reimburse multiple invoices. Note that once an invoice is changed to the reimbursed status, it cannot be changed back. Therefore, call this API with caution.

Notes:

  1. The reimburser must ensure that, after invoices are reimbursed, locked, or unlocked, the new statuses are promptly synced with Weixin to ensure user invoices can be used normally.

  2. The API for batch update of invoice statuses is a transactional operation. If any invoice fails to be updated, the statuses of the other invoices in the list will not be changed. All invoices will revert to their statuses before the API was called.

Request method

Request URL: https://api.weixin.qq.com/card/invoice/reimburse/updatestatusbatch?access_token={access_token}

Request method: POST

Request parameters

The request parameters use JSON format and contain the following fields:

Parameter Type Required Description
openid String Yes User's openid
reimburse_status String Yes The invoice reimbursement status. For more information, see Notes 7.2.
invoice_list List Yes Invoice list

Each object in the invoice_list contains the following fields:

Parameter Type Required Description
card_id String Yes The card_id of the invoice card
encrypt_code String Yes The encrypted code of the invoice card. encrypt_code and card_id are used together to construct the unique identifier of an invoice card.

Response

The returned result is in JSON format and contains the following fields:

Parameter Type Required Description
errcode Int Yes Error code
errmsg String Yes Error message

Sample code

Request:
{
    "openid": "{openid}",
    "reimburse_status": "{reimburse_status}",
    "invoice_list":
    [
        {"card_id":"cardid_1","encrypt_code":"encrypt_code_1"},
        {"card_id":"cardid_2","encrypt_code":"encrypt_code_2"}
    ]
}
Response:
{
    "errcode": 0,
    "errmsg": "ok"
}

# 9 Error Codes

Error Code Error Message Description
0 OK Successful
72015 unauthorized create invoice No permission for this operation. Check whether you have activated the permission.
72017 invalid invoice title Inconsistent invoice title
72023 invoice has been lock The invoice has been locked by another Official Account. Generally, this means the invoice has entered a subsequent reimbursement process and the Official Account/OA Company Account/App of the reimbursing company has locked the invoice.
72024 invoice status error Incorrect invoice status
72025 invoice token error Invalid wx_invoice_token
72028 invoice never set pay mch info WeChat Pay merchant information is not set.
72029 invoice never set auth field Authorization fields not set
72030 invalid mchid Invalid mchid
72031 invalid params Parameter error. The request may contain an invalid parameter name or a parameter value that fails the verification of backend.
72035 biz reject insert Invoicing has been rejected for the invoice. If an order_id has been used as a parameter when calling the "Reject Invoicing" API, an error occurs when the order_id is used again to add the e-invoice to Cards & Offers.
72036 invoice is busy The invoice is being modified. Try again later.
72038 invoice order never auth No authorization granted for the order. There may be a mismatch among the invoicing platform appid, merchant appid, and order_id.
72039 invoice must be lock first The order has not been locked.
72040 invoice pdf error Invalid PDF. Provide an authentic and valid PDF.
72042 billing_code and billing_no repeated Duplicate invoice ID and code
72043 billing_code or billing_no size error Incorrect invoice ID and code
72044 scan text out of time The invoice title QR code timed out.
40078 invalid card status No authorization granted for the card_id. If this error is reported in a sandbox environment, the reason is that the Weixin account calling the API is not added to the test list. If this error is reported in an official environment, the possible reasons include: the Official Account calling the API has not activated the Cards & Offers permission; or the gap between the creation time of card_id and the time of adding the e-invoice to Cards & Offers is too small.

# 10. List of Invoice Reimbursement Status

Status Description
INVOICE_REIMBURSE_INIT Initial invoice status. Not locked.
INVOICE_REIMBURSE_LOCK Invoice locked
INVOICE_REIMBURSE_CLOSURE Invoice written off
INVOICE_REIMBURSE_CANCEL Invoice offset