Struct InvoiceBuilder 

pub struct InvoiceBuilder<State = Draft> { /* private fields */ }

Typestate builder for NF-e / NFC-e XML documents.

In the Draft state all setters are available. Calling build() validates the data and transitions to Built, which exposes xml() and access_key(). Calling sign_with() on Built transitions to Signed, which exposes signed_xml().

Implementations

impl InvoiceBuilder<Draft>

pub fn new( issuer: IssuerData, environment: SefazEnvironment, model: InvoiceModel, ) -> Self

Create a new builder in the Draft state.

The three arguments are required; everything else has sensible defaults or is optional.

pub fn series(self, s: u32) -> Self

Set the invoice series (default: 1).

pub fn invoice_number(self, n: u32) -> Self

Set the invoice number (default: 1).

pub fn emission_type(self, et: EmissionType) -> Self

Set the emission type (default: EmissionType::Normal).

pub fn schema_version(self, sv: SchemaVersion) -> Self

Set the schema version (default: SchemaVersion::PL009).

When PL009, PL_010-exclusive tags (IBS/CBS, IS, gCompraGov, gPagAntecipado, agropecuario) are silently omitted even if data is provided.

When PL010, all reform-related tags are emitted normally.

pub fn issued_at(self, dt: DateTime<FixedOffset>) -> Self

Set the emission date/time (default: now in UTC-3).

pub fn operation_nature(self, n: impl Into<String>) -> Self

Set the operation nature (default: "VENDA").

pub fn add_item(self, item: InvoiceItemData) -> Self

Add one item to the invoice.

pub fn items(self, items: Vec<InvoiceItemData>) -> Self

Set all items at once (replaces any previously added items).

pub fn recipient(self, r: RecipientData) -> Self

Set the recipient (optional for NFC-e under R$200).

pub fn payments(self, p: Vec<PaymentData>) -> Self

Set the payment list.

pub fn change_amount(self, c: Cents) -> Self

Set the change amount (vTroco).

pub fn payment_card_details(self, d: Vec<PaymentCardDetail>) -> Self

Set card payment details.

pub fn contingency(self, c: ContingencyData) -> Self

Set contingency data.

pub fn exit_at(self, dt: DateTime<FixedOffset>) -> Self

Set the exit/departure date/time (dhSaiEnt, model 55 only).

pub fn operation_type(self, v: u8) -> Self

Override the operation type (tpNF, default: 1).

pub fn purpose_code(self, v: u8) -> Self

Override the invoice purpose code (finNFe, default: 1).

pub fn intermediary_indicator(self, v: impl Into<String>) -> Self

Set the intermediary indicator (indIntermed).

pub fn emission_process(self, v: impl Into<String>) -> Self

Set the emission process (procEmi).

pub fn consumer_type(self, v: impl Into<String>) -> Self

Set the consumer type (indFinal).

pub fn buyer_presence(self, v: impl Into<String>) -> Self

Set the buyer presence indicator (indPres).

pub fn print_format(self, v: impl Into<String>) -> Self

Set the DANFE print format (tpImp).

pub fn destination_indicator(self, v: impl Into<String>) -> Self

Set the destination indicator (idDest): “1” internal, “2” interstate, “3” export.

pub fn ver_proc(self, v: impl Into<String>) -> Self

Set the application version (verProc).

pub fn references(self, refs: Vec<ReferenceDoc>) -> Self

Set referenced documents (NFref).

pub fn transport(self, t: TransportData) -> Self

Set transport data.

pub fn billing(self, b: BillingData) -> Self

Set billing data (cobr).

pub fn withdrawal(self, w: LocationData) -> Self

Set the withdrawal/pickup location (retirada).

pub fn delivery(self, d: LocationData) -> Self

Set the delivery location (entrega).

pub fn authorized_xml(self, a: Vec<AuthorizedXml>) -> Self

Set authorized XML downloaders (autXML).

pub fn additional_info(self, a: AdditionalInfo) -> Self

Set additional info (infAdic).

pub fn intermediary(self, i: IntermediaryData) -> Self

Set intermediary data (infIntermed).

pub fn ret_trib(self, r: RetTribData) -> Self

Set retained taxes (retTrib).

pub fn tech_responsible(self, t: TechResponsibleData) -> Self

Set tech responsible (infRespTec).

pub fn purchase(self, p: PurchaseData) -> Self

Set purchase data (compra).

pub fn export(self, e: ExportData) -> Self

Set export data (exporta).

pub fn issqn_tot(self, t: IssqnTotData) -> Self

Set ISSQN total data (ISSQNtot).

pub fn cana(self, c: CanaData) -> Self

Set sugarcane supply data (cana).

pub fn agropecuario(self, a: AgropecuarioData) -> Self

Set agropecuário data (guia de trânsito or defensivos).

pub fn compra_gov(self, c: CompraGovData) -> Self

Set compra governamental data (gCompraGov, PL_010+).

pub fn pag_antecipado(self, p: PagAntecipadoData) -> Self

Set pagamento antecipado data (gPagAntecipado, PL_010+).

pub fn is_tot(self, t: IsTotData) -> Self

Set IS (Imposto Seletivo) total data.

pub fn ibs_cbs_tot(self, t: IbsCbsTotData) -> Self

Set IBS/CBS total data.

pub fn only_ascii(self, enabled: bool) -> Self

Enable or disable ASCII-only mode.

When enabled, accented characters (common in Brazilian Portuguese) are replaced by their closest ASCII equivalents in the generated XML. For example, “São Paulo” becomes “Sao Paulo”.

This mirrors the PHP Make::setOnlyAscii() method.

pub fn calculation_method(self, m: CalculationMethod) -> Self

Set the calculation method for automatic totals (vNF and vItem).

• V1 — from accumulated struct values.
• V2 — from built XML tags (default).

Matches the PHP setCalculationMethod() API.

pub fn v_nf_tot_override(self, v: Cents) -> Self

Override the vNFTot value (PL_010 only).

When set, this value is used instead of the auto-calculated vNF + vIBS + vCBS + vIS. Matches the PHP tagTotal(vNFTot) API.

Only emitted when schema is PL010 and IBSCBSTot is present.

pub fn build(self) -> Result<InvoiceBuilder<Built>, FiscalError>

Validate and build the XML, transitioning to Built.

Errors

Returns FiscalError if:

• The issuer state code is unknown
• Tax data is invalid

impl InvoiceBuilder<Built>

pub fn xml(&self) -> &str

The unsigned XML string.

pub fn access_key(&self) -> &str

The 44-digit access key.

pub fn sign_with<F>( self, signer: F, ) -> Result<InvoiceBuilder<Signed>, FiscalError>

where F: FnOnce(&str) -> Result<String, FiscalError>,

Sign the XML using the provided signing function.

The signing function receives the unsigned XML and must return the signed XML or an error. This keeps fiscal-core independent of the crypto implementation.

Examples

// Assuming `builder` is an InvoiceBuilder<Built>:
let signed = builder.sign_with(|xml| {
    // In real code, call fiscal_crypto::certificate::sign_xml() here.
    Ok(format!("{xml}<Signature/>"))
})?;
assert!(signed.signed_xml().contains("<Signature/>"));

Errors

Returns FiscalError if the signing function returns an error.

impl InvoiceBuilder<Signed>

pub fn signed_xml(&self) -> &str

The signed XML string (includes <Signature> element).

pub fn access_key(&self) -> &str

The 44-digit access key.

pub fn unsigned_xml(&self) -> &str

The unsigned XML (before signing).