Skip to main content

Crate tax_invoice

Crate tax_invoice 

Source
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 ↔ Java BigDecimal).
  • Random serial number, validation, Chinese amount conversion and Base64 file saving helpers.
  • Display/Debug everywhere, comprehensive thiserror-based error type, no unwraps 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.
AuthorizationResponse
Strongly typed payload returned by the /authorization endpoint.
HttpClient
Internal transport wrapper.
InvoiceClient
The main SDK client.
InvoiceConfig
SDK configuration holding the remote base URL and the application credentials.
RawResponse
Raw HTTP response returned by HttpTransport.
UreqTransport
Default transport backed by a ureq::Agent.

Enums§

InvoiceError
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_number when 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: java1026 header for parity so that the server can apply the same compatibility rules.

Traits§

HttpTransport
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 mirrors OtherUtil.amountToChinese in Java.
amount_to_chinese_str
Same as amount_to_chinese but 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 scale decimal places (HALF_UP).
generate_invoice_serial_number
Generate a request serial number of the form <prefix><yyyyMMddHHmmss><4-digit-random>, matching the Java OtherUtil.generateInvoiceSerialNumber helper.
generate_invoice_serial_number_with_prefix
Same as generate_invoice_serial_number but allows a custom prefix.
generate_random_string
Generate a random alphanumeric string of length characters 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 length characters. This mirrors the public method in the Java OtherUtil class.
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.