Download the PHP package jonathan8312/siigo-laravel without Composer

Siigo Laravel SDK

A community-maintained Laravel SDK for the public Siigo API — Colombian electronic invoicing (facturación electrónica) and related business documents.

Not an official Siigo package. This is an independent, open-source integration built by reading Siigo's public developer documentation, cross-referenced against Siigo's official JavaScript SDK (SiigoSAS/siigo_sdk_javascript) and its public API Blueprint spec to fill documentation gaps, and verified against real behavior on Siigo's sandbox wherever possible — see docs/known-issues.md for every discrepancy found this way. It is not affiliated with, endorsed by, or supported by Siigo.

What this package does

jonathan8312/siigo-laravel gives your Laravel application a clean, typed, testable way to talk to Siigo: issuing sales invoices and credit notes, registering payment receipts to suppliers, managing customers and products, and looking up Siigo's reference catalogs (taxes, sellers, cost centers, document types, payment types, and more).

It is deliberately just an SDK — it does not calculate totals or taxes, does not model your invoices/customers/products in your own database, and does not make fiscal decisions on your behalf. Your application owns its domain logic; this package owns talking to Siigo correctly and safely.

It is also free, open source, and has no phone-home behavior — no license checks, no telemetry, no tracking, no remote activation. It only ever talks to the Siigo base URL you configure.

Requirements

This is the exact matrix verified on every change by CI (PHP 8.2/8.4 against Laravel 12, PHP 8.3/8.5 against Laravel 13). No other combination is tested or supported.

Installation

The package registers itself automatically via Laravel package discovery — no manual service provider registration needed.

Optionally publish the config file:

This creates config/siigo.php. Publishing it is optional — the package ships with sensible defaults for everything except your Siigo credentials, which you must set yourself. See docs/installation.md for the full walkthrough.

Configuration

Set these in your application's .env:

See Configuration for every available option.

Quick start

Every resource is reached through $siigo->{resource}(), never through a hand-built Siigo URL — see each resource's own doc page below for its full request shape, since Siigo's payloads are too specific to summarize generically here.

Available resources

Remaining business resources — Purchases, Vouchers, Quotations, Journals, Reports, ... — are implemented phase by phase. See Known limitations and docs/research/siigo-api-co for what has already been investigated against the real Siigo API ahead of each future module.

Methods, resource by resource

Catalogs — $siigo->catalogs() — read-only reference data, cached per company (see Caching below):

Customers — $siigo->customers():

Products — $siigo->products():

Invoices — $siigo->invoices():

Credit Notes — $siigo->creditNotes():

No PUT, DELETE, or annul endpoint exists for this resource — confirmed against Siigo's own official SDK and documentation, see docs/credit-notes.md.

Payment Receipts — $siigo->paymentReceipts() — recibos de pago/egreso to suppliers:

Every table above is a summary — request shapes, required/optional fields, and real behavior confirmed against sandbox are documented in full on each resource's own doc page linked above. This README intentionally does not duplicate that detail.

Multi-company / SaaS usage

Siigo issues one JWT per company. For applications serving more than one company, resolve a scoped instance per request instead of relying on the configured default:

withCredentials() never mutates the container singleton — it returns a new, detached Siigo instance with its own token and catalog cache entries, safe under Octane and other long-running workers. See docs/authentication.md.

Why not a Facade?

This package doesn't ship a static Illuminate\Support\Facades\Siigo facade — you resolve Siigo::class from the container (or its 'siigo' alias) directly, as shown throughout this README. Two reasons:

1. Immutable multi-company scoping. withCredentials() returns a new instance rather than mutating the shared singleton (see Multi-company / SaaS usage above). A static facade makes it easy to call Siigo::withCredentials(...) and assume it changed the app-wide instance, when really the return value is what you needed to keep.
2. Testability without facade mocking. Everything goes through Illuminate\Http\Client, so Http::fake() already covers testing (see Testing your own application) — there's no need for Siigo::shouldReceive(...)-style facade mocks, which would encourage mocking the SDK's own methods instead of the actual HTTP boundary.

Full rationale in docs/authentication.md.

Caching

Reference catalogs (taxes, sellers, cost centers, document/payment types, ...) are per-company data, not a fixed list — and invoicing needs to resolve these ids on nearly every request. When resolved through the container, $siigo->catalogs() is cached via Laravel's Cache, scoped per company, for SIIGO_CATALOG_CACHE_TTL_SECONDS (default one hour) — so your application does not burn through Siigo's rate limit (as low as 10 req/min on trial accounts) re-fetching effectively-static data. This SDK does not persist that data anywhere beyond the cache, and does not ship migrations or Eloquent models to match it against your own local master data — see docs/catalogs.md for the reasoning and a suggested pattern.

Error handling

Every failure is surfaced as one of a small set of typed exceptions, all extending Jonathan8312\Siigo\Exceptions\SiigoException:

POST/PUT/DELETE requests are never retried automatically, under any configuration — an automatic retry of a non-idempotent call risks creating a duplicate document. See docs/errors.md for the full model.

Testing your own application

This SDK talks to Siigo through Laravel's own HTTP client, so Http::fake() works exactly as it does for any other Laravel HTTP call:

See docs/testing.md for asserting on requests and for running this package's own opt-in sandbox verification suite (composer test:staging).

Security

• No licensing checks, telemetry, tracking, or remote activation — this package only ever talks to the SIIGO_BASE_URL you configure.
• Credentials and the resulting JWT are never exposed as plain string properties, never appear in exception messages or logs, and never persisted anywhere beyond Laravel's Cache, keyed by a non-reversible fingerprint rather than the raw username/access key.
• withCredentials() returns new, immutable instances rather than mutating shared state — safe under Octane and other long-running workers.
• Explicit connection/request timeouts by default; non-idempotent requests are never retried automatically.

See docs/authentication.md for the full detail. Please report suspected security issues privately to [email protected] rather than opening a public issue.

Known limitations

Siigo's own documentation has confirmed gaps and inconsistencies — documented as such rather than guessed around — in docs/known-issues.md: PascalCase error response keys inconsistent with the rest of the API, a page_size query parameter not always honored, a Partner-Id format requirement confirmed only empirically, and more. Worth a read before filing an issue against unexpected sandbox behavior.

Remaining business resources not yet implemented: Purchases, Vouchers, Quotations, Journals, Payment Receipts' Detailed variant not verified against sandbox, and Reports. See docs/research/siigo-api-co for the investigation already done ahead of each.

Scope

This package is intentionally just an SDK. It does not:

• calculate or correct invoice totals, taxes, or any monetary value;
• model your application's customers, orders, or products in a database;
• persist Siigo's reference data anywhere beyond an optional cache (see Caching);
• retry non-idempotent operations automatically.

Your application remains responsible for its own domain logic; this package is responsible for communicating correctly and safely with Siigo.

Contributing

This package is built module by module, strictly against Siigo's documented behavior and verified against their sandbox wherever possible — never invented endpoints, fields, or business rules. If you'd like to contribute, please open an issue first to discuss scope.

Author

Maintained by Jonathan Torres — trebolcolombia.com.

License

MIT — see LICENSE.