Laravel Contaazul Laravel Package

Getting Started

laravel-contaazul is a Laravel wrapper around the ContaAzul API (Brazilian ERP/financial platform). The v1.2.2 patch is a small fix to a returned response type, so nothing in your integration flow should change — but if you were type-hinting against a specific response object and saw a mismatch, this is the release that resolves it.

Minimal path to first call:

1. Install the package via Composer and run its migrations/publish step if the package exposes a config publish tag:

   composer require eliseusantos/laravel-contaazul
   php artisan vendor:publish --tag=contaazul-config
   

2. Add credentials to .env (client ID, client secret, redirect URI). Look at config/contaazul.php first — it is the source of truth for URLs, scopes, and token storage.
3. Complete the OAuth handshake once. Most integrations in this package follow a "authorize → store refresh token → let the package refresh" pattern; check the package's routes/controllers or documented artisan command for the callback.
4. Make your first real call — typically ContaAzul::customers()->list() or an equivalent facade/resource call. Inspect the exact namespace in the package's src/ before assuming facade aliases.

First realistic use case: syncing customers or financial entries from a Laravel app into ContaAzul on a schedule via a queued job. Start there before tackling webhooks.

Implementation Patterns

Facade/resource wrapper pattern. The package exposes the ContaAzul API as resource groups (customers, products, sales, finance). Prefer wrapping these in your own service class rather than calling the facade across your codebase — this makes swapping or mocking trivial when the package bumps versions like v1.2.2.

Token lifecycle. Treat OAuth tokens as infrastructure, not business logic. Have a single service responsible for hydration/refresh, and register it as a singleton. Store the refresh token in the database (or a dedicated settings table) rather than .env — you will need to update it whenever ContaAzul rotates it.

Queued sync jobs. The ContaAzul API is rate-limited and network-fragile. Put every write behind a job with $tries = 3, backoff() returning [60, 300, 900], and an idempotency key on your side (a local UUID mapped to the remote entity). This isolates your request cycle from API latency.

DTO mapping at the boundary. Do not pass Eloquent models into the package. Build an explicit mapper (CustomerData::from($model)) so a change in the package's expected payload is caught in one file, not thirty.

Response handling after v1.2.2. Because this patch fixes the returned response type, prefer consuming responses through the package's documented array/object accessors rather than re-typing the raw Illuminate\Http\Client\Response. If you had a workaround (->json(), custom casts), review it — the fix may let you remove it.

Integration tip: pair the package with Laravel's HTTP client events (Http::afterResponse) for logging in non-production; you get full audit trails of what was sent to ContaAzul without touching package internals.

Gotchas and Tips

• Patch releases can still change types. v1.2.2 is only "Fix response type", but that means callers relying on the old wrong type will break. Grep your codebase for anything decoding the response manually before upgrading.
• Token expiry is silent until it isn't. ContaAzul tokens expire quickly; a missing refresh path will surface as sporadic 401s in production. Add a health check that performs a cheap authenticated read once per hour.
• Timezone and currency. ContaAzul is Brazil-centric — send dates in America/Sao_Paulo context and amounts as strings or cents per the API's expectation. Silent rounding bugs are common when using floats.
• Sandbox vs production URLs. Verify config('contaazul.base_url') is environment-driven; a hardcoded production URL in a staging deploy is a classic footgun with this kind of wrapper.
• Debugging request failures. The package typically wraps Laravel's HTTP client. Enable Http::preventStrayRequests() in tests and register a fake for the ContaAzul base URL — otherwise your test suite will hit the real API intermittently.
• Extension points worth knowing. Config publish tag, any binding in the service provider (swap the client for a mock in TestCase), and model/table names used for token storage if the package persists them. Those three are usually enough to bend the package to your needs without forking.
• Version pinning. Given that patch releases here can touch response shapes, pin to ~1.2.0 in composer.json and treat minor bumps as reviewable changes rather than automatic.

If you maintain a fork or local override, the only file touched by v1.2.2 is the response-type fix — a small surface, but diff it before re-applying your patches.