Configuration

C signatures use the C API. See C and C++ bindings for ownership and build instructions. The declarations below come from the generated headers. C++ exposes the same types in namespace fatoora through fatoora/Type.hpp headers.

There are three main "environments" which are required to determine which ZATCA API endpoint to use. Additionally, the type of environment changes the signing/validation process slightly.

• "Non-Production" Sometimes also called the "Sandbox". It's open to anyone to use without registration for initial testing. It's a dummy environment with mainly hardcoded values and responses. For instance, the OTP "123345" is always considered valid.

  Endpoint: ["https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal/"]

• "Simulation": The simulation environment requires registration at the developer portal. It's also used for testing only.

  Endpoint: ["https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/"]

• "Production": This is the real deal environment for in-production systems where real invoices are to be reported.

  Endpoint: ["https://gw-fatoora.zatca.gov.sa/e-invoicing/core/"]

C constructors accept uint8_t environment values: 0 for non-production, 1 for simulation, and 2 for production. Other values return an error.

Environment

from_str

Parse environment

Convert a string value to an environment enum.

RustPythonC (FFI)

EnvironmentType::from_str(env: &str) -> Result<EnvironmentType, EnvironmentParseError>

Environment(value: str) -> Environment

/* Pass uint8_t: 0 = non-production, 1 = simulation, 2 = production. */

as_str

Get canonical string

Return the canonical string value of the environment.

RustPythonC (FFI)

EnvironmentType::as_str(&self) -> &'static str

Environment.value: str

/* not exposed; use enum value directly */

endpoint_url

Resolve API base URL

Return the ZATCA API base URL for the selected environment.

RustPythonC (FFI)

EnvironmentType::endpoint_url(&self) -> &'static str

# not directly exposed

/* not exposed */

Config

new

Create config

Create an environment-aware config handle.

RustPythonC (FFI)

Config::new(env: EnvironmentType) -> Config

Config(env: Environment = Environment.NON_PRODUCTION)

#include "fatoora.h"

FatooraStatus fatoora_config_new(int32_t env,
    FatooraConfig **out,
    FatooraError **error);

env

Read config environment

Return the environment value stored in a config.

RustPythonC (FFI)

Config::env(&self) -> EnvironmentType

Config.env() -> Environment

#include "fatoora.h"

FatooraStatus fatoora_config_env(const FatooraConfig *self,
    uint8_t *out,
    FatooraError **error);

default

Default config

Create a default config using non-production environment.

RustPythonC (FFI)

Config::default() -> Config

Config() -> Config

#include "fatoora.h"

FatooraStatus fatoora_config_new(int32_t env,
    FatooraConfig **out,
    FatooraError **error);