Download the PHP package jonathan8312/plemsi-laravel without Composer

PLEMSI Laravel SDK

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

Not an official PLEMSI package. This is an independent, open-source integration built by reading PLEMSI's public Postman collection and verifying real behavior against their staging environment. It is not affiliated with, endorsed by, or supported by PLEMSI.

What this package does

jonathan8312/plemsi-laravel gives your Laravel application a clean, typed, testable way to talk to PLEMSI: issuing electronic invoices, credit and debit notes, support documents, and RADIAN events; managing customers, your company profile, and DIAN numbering resolutions; and looking up DIAN reference catalogs (municipalities, taxes, payment methods, and more).

It is deliberately just an SDK — it does not calculate totals or taxes, does not model your invoices/orders/customers in your database, and does not perform DIAN's own validation on your behalf. Your application owns its domain logic; this package owns talking to PLEMSI 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 PLEMSI 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/plemsi.php. Publishing it is optional — the package ships with sensible defaults for everything except your PLEMSI token and base URL, which you must set yourself.

Configuration

Set these in your application's .env:

PLEMSI_BASE_URL has no built-in default — not even PLEMSI's own staging URL — so a misconfigured deployment fails loudly at boot instead of silently talking to the wrong environment. See Environments and Configuration for the full detail.

Quick start

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

Available resources

Two resources not implemented yet: Nota Crédito a Documento Soporte and Docs. Equivalentes / POS. See Known Issues for status.

Methods, resource by resource

Catalogs — $plemsi->catalogs() — read-only DIAN reference lists:

documentIdentificationTypes(), municipalities(), municipalitiesComplete(), countries(), departments(), regimeTypes(), liabilityTypes(), operationTypes(), organizationTypes(), taxes(), unitMeasures(), paymentMethods(), paymentForms(), itemIdentificationTypes(), eventRejectionTypes(), documentTypes(), healthOperationTypes(), healthContractingPaymentMethods(), healthCoverageTypes(), healthPaymentCollectionTypes(). See docs/catalogs.md.

Customers — $plemsi->customers():

Company — $plemsi->company():

Invoices — $plemsi->invoices():

Credit Notes — $plemsi->creditNotes():

Debit Notes — $plemsi->debitNotes():

Resolutions — $plemsi->resolutions():

General — $plemsi->general():

Support Documents — $plemsi->supportDocuments():

RADIAN Events — $plemsi->radianEvents():

Every table above is a summary — request shapes, required/optional fields, and real behavior confirmed against staging 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

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

withToken() never mutates the instance it's called on — it always returns a new, independent one, which is safe under Octane and other long-running workers. See Authentication.

Why not a Facade?

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

1. Immutable multi-company scoping. withToken() returns a new instance rather than mutating the shared singleton (see Multi-company / SaaS usage above). A static facade makes it easy to call Plemsi::withToken(...) 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 Plemsi::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.

Error handling

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

POST/PUT requests (every document-issuing operation) are never retried automatically, under any configuration — an automatic retry of a non-idempotent call risks creating a duplicate electronic document. See Errors for the full model, including PLEMSI's inconsistent response envelope shapes across endpoints.

Testing your own application

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

See Testing for asserting on requests and for running this package's own opt-in staging verification suite.

Security

• No licensing checks, telemetry, tracking, or remote activation — this package only ever talks to the PLEMSI_BASE_URL you configure.
• Tokens are never logged, never included in exception messages or debug output, and never persisted by this package.
• withToken() 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

Some PLEMSI/DIAN behavior is documented in docs/known-issues.md as an environment or upstream limitation rather than an SDK defect — for example, RADIAN event issuance requiring a second, acquirer-side company account to fully verify, and DIAN offering no test environment at all for Documento Soporte. Worth a read before you file an issue against unexpected staging behavior.

Scope

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

• calculate or correct invoice totals, taxes, or any monetary value;
• replicate DIAN's own validation engine;
• model your application's customers, orders, or products;
• retry non-idempotent operations automatically.

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

Contributing

This package is built module by module, strictly against PLEMSI's documented Postman collection and behavior verified on their staging environment — 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.