Download the PHP package simplefatoora/laravel without Composer

Simple Fatoora for Laravel

The official Laravel package for the Simple Fatoora API. It provides a Laravel-native client for account onboarding, business profiles, clients, products, invoices and related documents, quotations, reports, downloads, and ZATCA Phase 2 workflows.

The package uses the public https://api.simplefatoora.com/v1/ API. It does not expose administration or membership-payment operations, collect telemetry, or log request data.

Requirements

These are the combinations exercised by the automated test matrix.

Installation

Install the package with Composer:

Laravel discovers the service provider and facade automatically. Publish the configuration file if you need to change timeouts or retry settings:

Configuration

Add your keys to the Laravel application's .env file:

The available settings are:

Keep API keys in environment variables or another server-side secret store. Never expose them in browser code, client-side JavaScript, public logs, or source control.

First request

Type-hint SimpleFatooraClient in a controller, job, command, or service. Laravel resolves it from the container:

Every JSON method returns an ApiResponse with successful, response, message, and raw properties. response contains the API's response value.

The optional facade is also registered:

Dependency injection is recommended for application services and tests.

Live and sandbox keys

The configured environment selects which key is sent as X-API-Key. Customer sandbox is an isolated invoicing and ZATCA test area; membership and billing remain shared with the live account.

The original client is not changed by forLive() or forSandbox(), so one injected client can safely create both scoped clients. Use only test data in sandbox.

Account onboarding and API keys

Public registration uses an email-verification flow. Generate and retain a unique journey ID in your application, collect the registration details, and then complete these calls in order:

Use the registration_intent value returned by the flow; do not log it. Existing account owners can retrieve their API keys with credentials and validate a key:

Do not log credentials or key-retrieval responses.

Business profile

Logo uploads are streamed from a readable local file.

Clients

Products

Products are remembered from successfully created documents. The public API supports searching and listing them:

Invoices and related documents

Use the typed request objects for common fields, or pass an array when the public API adds a supported field that is not represented by a data object.

DocumentType provides the supported document kinds:

Credit and debit notes use the same create() method and must reference an original document from the same API-key environment:

Use DocumentType::DebitNote for a debit note. The API validates the parent ownership, environment, document relationship, legal rules, and ZATCA requirements.

List and filter documents with InvoiceListOptions:

PDF, XML, and archive downloads

Downloads are streamed into a temporary file in the destination directory and moved into place only after a successful response and format check. Existing files are not overwritten unless overwrite: true is explicit.

Each result is a DownloadedFile containing path, contentType, filename, and size. XML is available only for eligible Phase 2 tax documents. Archive limits and eligibility rules are described in the API reference.

Quotations and conversion

Conversion issues a normal document and marks the quotation converted. Repeating conversion with the same quotation ID returns the original document rather than creating a duplicate. The package still does not retry the conversion request automatically.

Reports

ZATCA Phase 2

Read the current state before beginning or continuing onboarding:

The following methods cover the public onboarding, recovery, refresh, and renewal contract:

Only an authorized business representative should start or renew ZATCA onboarding. OTPs for this flow come from ZATCA and are not the account-registration email OTP.

Error handling

All package exceptions extend SimpleFatooraException:

Specific exception classes cover invalid configuration, unauthorized and forbidden responses, validation failures, rate limits, timeouts, other network failures, server errors, malformed JSON, and failed downloads. API keys, credentials, OTPs, and token-like response fields are redacted from exception messages and details.

Timeouts and retries

Timeouts are configurable and finite. Automatic retries apply only to GET requests after connection failures, rate limits, or server errors. Retry delays are capped by SIMPLE_FATOORA_MAX_RETRY_DELAY_MS.

POST, PUT, PATCH, and DELETE requests are never retried automatically. This includes account creation, profile changes, client writes, document creation, quotation writes and conversion, archive generation, reports, and ZATCA operations. Your application may make a deliberate retry only after determining whether the first write succeeded.

Testing

The package uses Laravel HTTP fakes and Orchestra Testbench, so the normal suite does not call a live service:

Maintainers can also run the opt-in tools/staging-smoke.php check against a dedicated, non-production Simple Fatoora test account. It reads protected configuration from standard input, does not print response data, cleans up mutable records, and never runs as part of ordinary pull-request CI.

The bundled OpenAPI snapshot is compared with every exposed endpoint. A separate contract command can compare a newly downloaded official document without making ordinary pull-request tests depend on API availability:

Versioning and upgrades

The package follows Semantic Versioning. Releases before 1.0 may introduce interface changes in a new minor version. Patch versions preserve the documented public interface unless a security or legal correction requires otherwise. Review CHANGELOG.md before upgrading.

Security and support

Do not post API keys, credentials, invoice contents, or customer data in a public issue. Follow SECURITY.md for private vulnerability reporting.

• Simple Fatoora integration and API documentation
• OpenAPI document
• Simple Fatoora contact page
• GitHub issues