Skip to main content

tax_invoice/
lib.rs

1//! # tax-invoice
2//!
3//! `tax-invoice` is a Rust port of the official Java 电子发票/数电发票 SDK. It
4//! gives you a strongly-typed, memory-safe, easy-to-test client for every
5//! endpoint exposed by the [fa-piao.com](https://fa-piao.com) 数电发票
6//! platform.
7//!
8//! ## Highlights
9//!
10//! * Coverage for every public endpoint from the Java SDK (authorization,
11//!   SMS/face login, blue & red invoices, OFD/PDF/XML download, account
12//!   switching, credit-line queries, …).
13//! * HMAC-SHA256 request signing that is byte-for-byte identical to the
14//!   Java implementation.
15//! * Decimal-precise tax utilities (Rust `Decimal` ↔ Java `BigDecimal`).
16//! * Random serial number, validation, Chinese amount conversion and
17//!   Base64 file saving helpers.
18//! * `Display`/`Debug` everywhere, comprehensive `thiserror`-based error
19//!   type, no `unwrap`s in the public API.
20//!
21//! ## Quick start
22//!
23//! ```no_run
24//! use tax_invoice::prelude::*;
25//!
26//! # fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
27//! let client = InvoiceClient::new("app_key", "app_secret")?;
28//!
29//! // 1. Acquire an authorization token (the client stores it internally).
30//! let auth = client.get_authorization("91110000000000000X")?;
31//! if auth.is_success() {
32//!     println!("got token: {}", auth.data().unwrap().token());
33//! }
34//!
35//! // 2. Issue a blue invoice.
36//! let mut params = serde_json::Map::new();
37//! params.insert("fplxdm".into(), serde_json::json!("82"));
38//! params.insert("hjje".into(), serde_json::json!(9.9));
39//! let resp = client.blue_ticket(params)?;
40//! println!("blue ticket => code={}, msg={}", resp.code, resp.msg);
41//! # Ok(()) }
42//! ```
43//!
44//! See the `examples/` directory in the crate for full programs.
45
46#![cfg_attr(docsrs, feature(doc_cfg))]
47#![deny(unsafe_code)]
48#![warn(missing_debug_implementations)]
49
50mod client;
51mod config;
52mod error;
53mod http_client;
54mod model;
55mod signature;
56mod util;
57
58pub use crate::client::{InvoiceClient};
59pub use crate::config::{InvoiceConfig, DEFAULT_BASE_URL};
60pub use crate::error::{InvoiceError, Result};
61pub use crate::http_client::{
62    HttpClient, HttpTransport, RawResponse, UreqTransport, DEFAULT_TIMEOUT, SDK_HEADER_VALUE,
63};
64pub use crate::model::{ApiResponse, AuthorizationResponse};
65pub use crate::signature::{calculate_signature, current_timestamp, generate_random_string};
66pub use crate::util::{
67    add, amount_to_chinese, amount_to_chinese_str, calculate_amount_without_tax, calculate_tax,
68    divide, generate_invoice_serial_number, generate_invoice_serial_number_with_prefix,
69    multiply, random_string, save_base64_file, subtract, validate_email, validate_mobile,
70    validate_tax_number, DEFAULT_SERIAL_PREFIX,
71};
72
73/// Convenience re-exports for the common case.
74pub mod prelude {
75    pub use crate::client::{InvoiceClient};
76    pub use crate::config::{InvoiceConfig, DEFAULT_BASE_URL};
77    pub use crate::error::{InvoiceError, Result};
78    pub use crate::http_client::RawResponse;
79    pub use crate::model::{ApiResponse, AuthorizationResponse};
80    pub use crate::util::{
81        add, amount_to_chinese, amount_to_chinese_str, calculate_amount_without_tax,
82        calculate_tax, divide, generate_invoice_serial_number,
83        generate_invoice_serial_number_with_prefix, multiply, random_string, save_base64_file,
84        subtract, validate_email, validate_mobile, validate_tax_number,
85    };
86}