Getting Started

Minimal Setup for Laravel Integration

Clone the Repository
```
git clone --recurse-submodules https://github.com/controleonline/accounting.git
```
Ensure submodules are initialized (git submodule update --init --recursive).
API Documentation
- The package relies on the Controle Online API.
- Review the API docs for endpoints (e.g., /api/v1/accounts, /api/v1/invoices).

First Use Case: Fetching Accounts

use ControleOnline\Accounting\Client;

$client = new Client(config('accounting.api_url'), config('accounting.api_key'));
$accounts = $client->getAccounts(); // Returns a collection of account objects

Laravel Configuration Add to config/services.php:

'accounting' => [
    'api_url' => env('ACCOUNTING_API_URL', 'https://api.controleonline.com'),
    'api_key' => env('ACCOUNTING_API_KEY'),
],

Implementation Patterns

1. Service Layer Abstraction

Pattern: Wrap API calls in Laravel services to decouple logic from controllers.

namespace App\Services;

use ControleOnline\Accounting\Client;

class AccountingService {
    protected $client;

    public function __construct(Client $client) {
        $this->client = $client;
    }

    public function getAccountBalance($accountId) {
        return $this->client->getAccount($accountId)->balance;
    }
}

2. Event-Driven Workflows

Pattern: Trigger Laravel events for accounting actions (e.g., InvoiceCreated, PaymentProcessed).

// In a controller or service
event(new \App\Events\InvoiceCreated($invoiceData));

// Listen in EventServiceProvider
protected $listen = [
    \App\Events\InvoiceCreated::class => [
        \App\Listeners\SyncToAccounting::class,
    ],
];

3. Model Observers for Sync

Pattern: Sync Laravel models with the API using observers.

namespace App\Observers;

use App\Models\Invoice;
use ControleOnline\Accounting\Client;

class InvoiceObserver {
    public function saved(Invoice $invoice) {
        $client = app(Client::class);
        $client->createInvoice($invoice->toArray());
    }
}

Invoice::observe(InvoiceObserver::class);

4. API Rate Limiting

Pattern: Use Laravel’s throttle middleware for API calls.

Route::middleware(['throttle:60,1'])->group(function () {
    Route::get('/accounting/sync', [AccountingController::class, 'sync']);
});

5. Webhook Handling

Pattern: Process webhooks from Controle Online (e.g., payment confirmations).

Route::post('/accounting/webhook', function (Request $request) {
    $payload = $request->json()->all();
    // Validate and process (e.g., update Laravel models)
});

Gotchas and Tips

1. API Key Management

Gotcha: Hardcoding API keys in .env is insecure. Use Laravel’s Vault or environment-based secrets.
Tip: Rotate keys periodically and revoke old ones in the Controle Online dashboard.

2. Rate Limits and Retries

Gotcha: The API enforces rate limits (e.g., 60 requests/minute). Unhandled limits cause 429 errors.

Tip: Implement exponential backoff in your Client wrapper:

use Illuminate\Support\Facades\Http;

$response = Http::retry(3, 100)->get($url);

3. Data Mismatches

Gotcha: Field names differ between Laravel models and the API (e.g., due_date vs. vencimento).

Tip: Use a Mapper class to transform data:

class AccountingMapper {
    public static function mapInvoice($apiData) {
        return [
            'due_date' => $apiData['vencimento'],
            'status' => self::mapStatus($apiData['status']),
        ];
    }
}

4. Submodule Dependencies

Gotcha: Submodules may introduce breaking changes if not updated.

Tip: Pin submodule commits in your composer.json or .gitmodules:

"extra": {
    "laravel": {
        "submodule": {
            "controleonline/api-platform-community": "a1b2c3d"
        }
    }
}

5. Webhook Verification

Gotcha: Webhooks require signature verification to avoid spoofing.

Tip: Use Laravel’s webhook package or manually verify signatures:

$expectedSignature = hash_hmac('sha256', $payload, config('accounting.webhook_secret'));
if (!hash_equals($request->header('X-Signature'), $expectedSignature)) {
    abort(403);
}

6. Local Development Quirks

Gotcha: The API may not have a local sandbox. Use a staging environment.

Tip: Mock API responses in tests:

Http::fake([
    'api.controleonline.com/*' => Http::response([...], 200),
]);

7. Extension Points

Tip: Extend the Client class to add custom endpoints:

namespace App\Services;

use ControleOnline\Accounting\Client as BaseClient;

class CustomClient extends BaseClient {
    public function getCustomReport($params) {
        return $this->get('/reports/custom', $params);
    }
}

8. Logging and Debugging

Tip: Enable Laravel’s HTTP client logging:

Http::withOptions(['debug' => true])->get($url);

Gotcha: The API may return opaque error messages. Use try-catch with JsonException:

try {
    $response = $client->getAccounts();
} catch (\GuzzleHttp\Exception\RequestException $e) {
    Log::error('Accounting API error: ' . $e->getResponse()->getBody());
}

Accounting Laravel Package