v4 modernization: preserve API error shape and expand critical tests

[javorosas]

Summary

• preserve full API error payload on non-2xx responses via FacturapiException
• expose error metadata with getErrorData(), getResponseData(), getStatusCode(), and getRawBody()
• keep API error message as primary exception message when available
• add coverage for invoice/receipt creation request building and multipart upload failures
• add edge-case coverage for non-JSON/invalid JSON/empty/random-text error bodies
• document error handling in English and Spanish READMEs

Validation

• ./vendor/bin/phpunit --configuration phpunit.xml
• result: OK (16 tests, 70 assertions)

[Copilot]

Pull request overview

Modernizes the Facturapi PHP SDK to v4 by switching to a PSR-18/Guzzle-based HTTP layer, preserving full API error payloads via a new FacturapiException, expanding test coverage, and refreshing documentation and examples.

Changes:

• Replaced cURL transport with a PSR-18 HTTP client flow in BaseClient, adding richer error metadata on failures.
• Introduced FacturapiException (with compatibility alias for Facturapi_Exception) and expanded error-handling tests for JSON/non-JSON bodies.
• Added/expanded resource method modernizations (camelCase + deprecated snake_case aliases) and updated READMEs, example, PHPUnit config, and Composer constraints.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/bootstrap.php	Adds PHPUnit bootstrap and Support autoloading.
tests/Support/FakeHttpClient.php	PSR-18 fake client used by new tests.
tests/Resources/WebhooksTest.php	Covers local webhook signature verification and API fallback.
tests/Resources/OrganizationsMultipartTest.php	Covers multipart request building and file-open failures.
tests/Resources/InvoicesTest.php	Verifies download PDF path + headers.
tests/Resources/InvoiceReceiptCreationTest.php	Verifies create/cancel request building (JSON + query params).
tests/Http/ErrorHandlingTest.php	Verifies API error shape preservation and metadata accessors.
tests/Http/ErrorHandlingNonJsonEdgeCasesTest.php	Adds coverage for invalid/empty/plain-text error bodies.
src/Http/BaseClient.php	New PSR-18 request execution, error extraction, config normalization, multipart building.
src/Facturapi.php	Updates SDK constructor/config and resource wiring.
src/Exceptions/Facturapi_Exception.php	Keeps deprecated compatibility alias to FacturapiException.
src/Exceptions/FacturapiException.php	New exception carrying error payload/status/raw body.
src/Resources/Webhooks.php	Modernizes methods and adds local signature verification logic.
src/Resources/Tools.php	Modernizes request building and exception handling.
src/Resources/Retentions.php	Adds camelCase methods + deprecated snake_case wrappers.
src/Resources/Receipts.php	Adds camelCase methods + deprecated snake_case wrappers.
src/Resources/Products.php	Modernizes resource methods and exception handling.
src/Resources/Organizations.php	Modernizes methods, improves query building, adds deprecation wrapper for typo’d method.
src/Resources/Invoices.php	Adds camelCase methods + deprecated snake_case wrappers.
src/Resources/Customers.php	Modernizes methods and exception handling.
src/Resources/ComercioExteriorCatalogs.php	Adds Comercio Exterior catalogs resource support.
src/Resources/Catalogs.php	Modernizes query building and exception handling.
src/Resources/CartaPorteCatalogs.php	Modernizes query building and exception handling.
phpunit.xml	Adds PHPUnit configuration and bootstrap.
example.php	Switches example to Composer autoload and env-based API key.
composer.json	Bumps PHP to >=8.2, adds Guzzle + PSR HTTP client, moves to PSR-4 autoload.
VERSION	Bumps to 4.0.0 and documents breaking changes/migration notes.
README.md	Updates English docs for v4 config, usage, and error handling.
README.es.md	Adds Spanish docs mirroring the updated guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 31 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.