ZATCA API Client¶

Using the fatoora-core API client for compliance, reporting, and clearance APIs.

Example¶

RustPythonC/C++

#[tokio::main]
pub async fn main() {
    use fatoora_core::api::{CsidCredentials, Compliance, ZatcaClient};
    use fatoora_core::config::{Config, EnvironmentType};
    use fatoora_core::invoice::xml::parse::parse_signed_invoice_xml;

    // Doc example: build a client and prepare compliance request data.
    let signed_xml_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests/fixtures/invoices/sample-simplified-invoice.xml");
    let config = Config::new(EnvironmentType::NonProduction);
    let client = ZatcaClient::new(config).expect("create client");

    let xml = std::fs::read_to_string(&signed_xml_path).expect("read xml");
    let signed = parse_signed_invoice_xml(&xml).expect("parse signed invoice");
    let hash = signed.hash_base64().expect("compute hash");

    let ccsid = CsidCredentials::<Compliance>::new(
        EnvironmentType::NonProduction,
        Some("1234567890".to_string()),
        "binary_security_token",
        "secret",
    );

    assert!(!hash.is_empty());
    let _ = (client, signed, ccsid);
    // let response = client.check_invoice_compliance(&signed, &ccsid).await?;
    // println!("{:?}", response.validation_results().status());
}

from fatoora.api import CsidCompliance, ZatcaClient
from fatoora.config import Config, Environment
from fatoora.invoice import parse_signed_invoice_xml

# signed_xml_path = "path/to/signed_invoice.xml"
config = Config(Environment.NON_PRODUCTION)
signed = parse_signed_invoice_xml(signed_xml_path.read_text(encoding="utf-8"))

client = ZatcaClient(config)
ccsid = CsidCompliance.new(
    Environment.NON_PRODUCTION,
    "binary_security_token",
    "secret",
    "1234567890",
)
hash_b64 = signed.hash_base64()
assert hash_b64

#include "fatoora/api.h"
#include "fatoora/invoice.h"

#include <assert.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#ifndef FATOORA_DOC_SIGNED_XML
#define FATOORA_DOC_SIGNED_XML "path/to/signed_invoice.xml"
#endif

static char *read_file(const char *path);

int main(void) {
    const char *signed_xml_path = FATOORA_DOC_SIGNED_XML;
    char *xml_cstr = read_file(signed_xml_path);
    if (!xml_cstr) {
        /* handle error */
        return 1;
    }

    struct FfiConfig *config = fatoora_config_new(FfiEnvironment_NonProduction);
    struct FfiResult_FfiZatcaClient client = fatoora_zatca_client_new(config);
    if (!client.ok) {
        /* handle error */
        return 1;
    }

    /* signed_xml_path = "path/to/signed_invoice.xml" */
    struct FfiResult_FfiSignedInvoice signed_invoice = fatoora_parse_signed_invoice_xml(xml_cstr);
    if (!signed_invoice.ok) {
        /* handle error */
        return 1;
    }

    struct FfiResult_FfiString hash = fatoora_signed_invoice_hash_base64(&signed_invoice.value);
    assert(hash.value.ptr && strlen(hash.value.ptr) > 0);
    fatoora_string_free(hash.value);

    struct FfiResult_FfiCsidCompliance ccsid =
        fatoora_csid_compliance_new(FfiEnvironment_NonProduction, 1234567890,
                                    "binary_security_token", "secret");
    if (!ccsid.ok) {
        /* handle error */
        return 1;
    }

    /* response handle provides getters for results */
    /* struct FfiResult_FfiValidationResponse resp =
       fatoora_zatca_check_compliance(&client.value, &signed_invoice.value, &ccsid.value); */
    free(xml_cstr);
    fatoora_signed_invoice_free(&signed_invoice.value);
    fatoora_csid_compliance_free(&ccsid.value);
    fatoora_zatca_client_free(&client.value);
    fatoora_config_free(config);
    return 0;
}

Notes¶

Config and credentials must target the same environment (non-production, simulation, or production).
Reporting and clearance APIs require production credentials; compliance checks use compliance credentials.
All endpoints return structured validation responses; in FFI/bindings these are opaque handles with getter functions (no JSON payloads).