Expand description
§tax-invoice
tax-invoice is a Rust port of the official Java 电子发票/数电发票 SDK. It
gives you a strongly-typed, memory-safe, easy-to-test client for every
endpoint exposed by the fa-piao.com 数电发票
platform.
§Highlights
- Coverage for every public endpoint from the Java SDK (authorization, SMS/face login, blue & red invoices, OFD/PDF/XML download, account switching, credit-line queries, …).
- HMAC-SHA256 request signing that is byte-for-byte identical to the Java implementation.
- Decimal-precise tax utilities (Rust
Decimal↔ JavaBigDecimal). - Random serial number, validation, Chinese amount conversion and Base64 file saving helpers.
Display/Debugeverywhere, comprehensivethiserror-based error type, nounwraps in the public API.
§Quick start
use tax_invoice::prelude::*;
let client = InvoiceClient::new("app_key", "app_secret")?;
// 1. Acquire an authorization token (the client stores it internally).
let auth = client.get_authorization("91110000000000000X")?;
if auth.is_success() {
println!("got token: {}", auth.data().unwrap().token());
}
// 2. Issue a blue invoice.
let mut params = serde_json::Map::new();
params.insert("fplxdm".into(), serde_json::json!("82"));
params.insert("hjje".into(), serde_json::json!(9.9));
let resp = client.blue_ticket(params)?;
println!("blue ticket => code={}, msg={}", resp.code, resp.msg);See the examples/ directory in the crate for full programs.
Modules§
- prelude
- Convenience re-exports for the common case.
Structs§
- ApiResponse
- Generic API envelope used by every fa-piao.com endpoint.
- Authorization
Response - Strongly typed payload returned by the
/authorizationendpoint. - Http
Client - Internal transport wrapper.
- Invoice
Client - The main SDK client.
- Invoice
Config - SDK configuration holding the remote base URL and the application credentials.
- RawResponse
- Raw HTTP response returned by
HttpTransport. - Ureq
Transport - Default transport backed by a
ureq::Agent.
Enums§
- Invoice
Error - Error type returned by every fallible API in the SDK.
Constants§
- DEFAULT_
BASE_ URL - Default base URL of the fa-piao.com 数电发票 platform.
- DEFAULT_
SERIAL_ PREFIX - Default prefix used by
generate_invoice_serial_numberwhen none is supplied. - DEFAULT_
TIMEOUT - Default request timeout.
- SDK_
HEADER_ VALUE - Custom user-agent string sent by the SDK. It mirrors the Java SDK’s
Sdk: java1026header for parity so that the server can apply the same compatibility rules.
Traits§
- Http
Transport - Minimal abstraction over a HTTP agent so we can swap in a fake during
tests. The default implementation simply wraps a
ureq::Agent.
Functions§
- add
- Add two monetary amounts rounding to two decimal places (HALF_UP).
- amount_
to_ chinese - Convert a decimal amount (e.g.
123.45) to its Chinese uppercase form (“壹佰贰拾叁元肆角伍分”). This mirrorsOtherUtil.amountToChinesein Java. - amount_
to_ chinese_ str - Same as
amount_to_chinesebut accepts a string and returns “零元整” when the string cannot be parsed. - calculate_
amount_ without_ tax - Compute the net (tax-exclusive) amount from an inclusive amount and a rate.
- calculate_
signature - Compute the HMAC-SHA256 signature that protects every request to the fa-piao.com platform.
- calculate_
tax - Compute the tax amount for a given price.
- current_
timestamp - Return the current Unix epoch as a string of seconds.
- divide
- Divide two monetary amounts rounding to
scaledecimal places (HALF_UP). - generate_
invoice_ serial_ number - Generate a request serial number of the form
<prefix><yyyyMMddHHmmss><4-digit-random>, matching the JavaOtherUtil.generateInvoiceSerialNumberhelper. - generate_
invoice_ serial_ number_ with_ prefix - Same as
generate_invoice_serial_numberbut allows a custom prefix. - generate_
random_ string - Generate a random alphanumeric string of
lengthcharacters using a cryptographically secure random number generator. - multiply
- Multiply two monetary amounts rounding to two decimal places (HALF_UP).
- random_
string - Generate a random alphanumeric string of
lengthcharacters. This mirrors the public method in the JavaOtherUtilclass. - save_
base64_ file - Decode a Base64 string and write the bytes to
file_path. - subtract
- Subtract two monetary amounts rounding to two decimal places (HALF_UP).
- validate_
email - Validate an e-mail address.
- validate_
mobile - Validate a Chinese mobile phone number.
- validate_
tax_ number - Validate a Chinese taxpayer identification number.
Type Aliases§
- Result
- Convenience alias used throughout the crate.