Download the PHP package taxora/sdk-php without Composer

Taxora PHP SDK

Official PHP SDK for the Taxora VAT Validation API Validate EU VAT numbers, generate compliance certificates, and integrate VAT checks seamlessly into your systems — all with clean, modern PHP.

🚀 Overview

The Taxora SDK provides an elegant, PSR-compliant interface to the Taxora API, supporting:

• ✅ Secure API-Key and Bearer Token authentication
• ✅ Single & multiple VAT validation with AI-based company matching
• ✅ VAT state history and search endpoints
• ✅ Certificate generation (PDF) and bulk/list exports (ZIP or PDF)
• ✅ Full test coverage & PSR-18 compatible HTTP client
• ✅ PHP 8.3, 8.4, and (soon) 8.5 ready

🔒 The SDK itself is free to use, but a Taxora API subscription is required. You can obtain your x-api-key from your Taxora account developer settings.

🧮 Installation

Install via Composer:

The package supports all PSR-18 clients (e.g. Guzzle, Symfony, Buzz) and PSR-17/PSR-7 factories.

Example dependencies for Guzzle:

⚙️ Quick Start

🔎 Smart Enrichment (reverse VAT lookup)

Resolve a company name + address + country → VAT number + confidence. A confident match returns synchronously; harder cases (and all bulk batches) are processed asynchronously and delivered via the enrichment.completed webhook — poll with get($jobId) in the meantime. Requires the Smart Enrichment add-on to be active on your account.

Note: no_vat_exists means the company was identified but legitimately has no VAT/UID number (common for purely-domestic German firms). It is a definitive answer — not a failure — and is not billed.

🇫🇷 E-Reporting / Compliance (DGFiP Flux 10)

Full French e-reporting flow: enroll a company with the provider, record (and optionally submit) transactions, follow the resulting DGFiP tax reports, and pull turnover statistics. All endpoints require an active E-Reporting subscription / feature grant — except requestEReportingAccess(), which is exactly how you ask for one. Provider failures (B2Brouter/DGFiP) surface as HttpException with status code 502.

1. Enroll (SIRENE lookup → enrollment)

2. Record & submit transactions

3. CSV bulk import

4. Tax reports (DGFiP ledger outcomes)

5. Revenue statistics & VAT rates

Read-only turnover aggregation over your e-reporting transactions — totals, a time series and breakdowns by transaction type, counterparty country and state. All headline figures are expressed in the most frequent currency in the range (primaryCurrency); when more than one currency is present, isMultiCurrency is true and byCurrency lists each one. Monetary values are returned as 4-decimal strings to preserve precision.

6. No access yet?

🇳🇴 E-Invoicing Norway (EHF / Peppol)

Compliance services are booked per country: each enrollment covers one country and one service — France offers e-reporting (and e-invoicing) via DGFiP Flux 10 (regime: dgfip_flux10), Norway offers e-invoicing via EHF 3.0 = Peppol BIS Billing 3.0 (regime: peppol_bis3). $enrollment->service tells you which service an enrollment books (ComplianceService::E_REPORTING / E_INVOICING). Billing is per country as well: Norway is charged a one-off setup fee when the country is activated plus a price per document sent.

The company needs the e-invoicing service unlocked — otherwise enrolling fails with an HttpException (status 403, body code service_not_active); use requestEReportingAccess(service: 'e_invoicing', countries: ['NO']) to ask for it. Norwegian organisation numbers are validated locally (9 digits, modulus-11 check digit) before any request; Taxora\Sdk\Support\NorwegianOrgNumber exposes the same helpers (normalize(), isValid(), toVatNumber() → NO923609016MVA).

1. Registry lookup → enrollment

2. Can the buyer receive e-invoices? (Peppol lookup)

3. Send an invoice

4. Send a credit note

company()->get() returns the raw company payload. New company limit fields are exposed as api_rate_limit and vat_rate_limit. The legacy rate_limit field may still appear temporarily for backward compatibility, but it should be treated as deprecated.

vat()->validate() returns a VatResource object that includes the canonical VAT number, status, requested company name echo, optional scoring data, and optional API error metadata. state remains backward-compatible and still carries the canonical business result, while has_api_error, error_message, and next_api_recheck_at expose technical provider failures without breaking existing integrations. The score reflects the overall confidence (higher is better), while breakdown provides an array of ScoreBreakdown objects describing every validation step, its score contribution, and any metadata (e.g. matched addresses or mismatched fields).

Need to plug in your own PSR-18 client or PSR-17 factories (e.g. to add logging or retries)? Call the constructor directly or pass them as optional overrides to the factory:

🧩 Architecture

The SDK follows clean separation of concerns:

Each endpoint handles:

• Request signing with x-api-key
• Bearer token refresh if expired or unauthorized
• PSR-7 response parsing into DTOs

📦 DTOs

Example:

🔄 Authentication Flow

1. Login

   Need to authenticate with a technical client_id instead of an email?

   Advanced: you can still pass loginIdentifier: LoginIdentifier::CLIENT_ID into login() if you prefer an explicit enum instead of the helper.

   → Stores and returns a Token DTO (valid for ~3600 seconds).

2. Auto-refresh The client automatically refreshes the token on 401 responses.

3. Manual refresh (optional)

4. Token storage By default, tokens are stored in memory. You can provide a PSR-16 cache adapter for persistence:

🤪 Testing

Run the test suite locally:

CI runs on PHP 8.3, 8.4, and (soon) 8.5, verifying:

• PHPUnit 12
• Psalm static analysis
• Code style checks

🗟️ Environments

Need sandbox sample data? Known VAT UIDs with deterministic responses live in tests/Fixtures/SandboxVatFixtures.php.

Switch easily via the constructor:

🚨 Error Handling

Exception messages are always short and safe to log. A response body is never used as the message: gateways in front of the API answer 502/503/504 with a full HTML error page, and that page would otherwise land in every log line and error mail of your application. The SDK uses the message / error field of a JSON error body when there is one, and falls back to the status line (Taxora API request failed (HTTP 504 Gateway Timeout).) otherwise. The untouched body stays available via HttpException::getResponseBody().

Automatic retries

The SDK retries what never produced an answer from the API itself: 3 attempts, with 500 ms and 1000 ms of backoff in between. That covers

• gateway failures (502, 503, 504) — the infrastructure in front of the API, where a second attempt a moment later usually succeeds;
• connection-level failures — reset connections, client-side timeouts, DNS hiccups. Once the attempts are used up, the transport exception of your own HTTP client is rethrown unchanged, so nothing about its type or message changes for you;
• 429 Too Many Requests, but only with a Retry-After — then the SDK waits exactly as long as the API asked instead of using its own backoff. Without that header a retry would only hammer a rate limit that is already tripped, so the error is surfaced immediately. A Retry-After longer than maxRetryAfterMs (10 s by default) also fails immediately rather than blocking your worker — the raw header stays readable via HttpException::getRetryAfter().

Everything else fails on the first attempt, including any 5xx the API produced itself (a 500 is a bug, not a hiccup — repeating it just costs time).

Retries apply to read-only calls only — VAT validation, lookups, state, history, search, certificate downloads, company and e-reporting reads, login and token refresh. Calls that change state or cost quota (certificatesBulkExport(), smartEnrichment()->lookup(), e-reporting enrollment/transaction writes) are never retried automatically, because a gateway timeout does not tell us whether the API already processed the request.

Once the attempts are used up you get one clean error:

Tune or disable it via RetryPolicy:

⚠️ Deprecations

So fresh there aren't even any deprecated features yet. Check back in a few months when we're on v47 and have made some regrettable decisions. 🎉

🪪 License

Licensed under the MIT License © 2025 theconcept technologies. The SDK is open-source, but API usage requires a valid Taxora subscription.

🤝 Contributing

Contributions and pull requests are welcome!

• Follow PSR-12 coding style (composer fix).
• Run composer test before submitting a PR.
• Ensure new endpoints include DTOs + tests.

💬 Support

Need help or enterprise support? 📧 [email protected] 🌐 https://taxora.io