PHPackages                             macropage/idealo-business-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. macropage/idealo-business-api

ActiveLibrary[API Development](/categories/api)

macropage/idealo-business-api
=============================

idealo Business Click API SDK based on Saloon PHP

v0.1.0(2mo ago)00MITPHPPHP ^8.2

Since Apr 27Pushed 2mo agoCompare

[ Source](https://github.com/michabbb/idealo-business-api-php-sdk)[ Packagist](https://packagist.org/packages/macropage/idealo-business-api)[ RSS](/packages/macropage-idealo-business-api/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

idealo Business Click API SDK
=============================

[](#idealo-business-click-api-sdk)

PHP SDK for the [idealo Business Click Report API](https://business.idealo.com/assets/docs/click-report.html), built on [Saloon PHP](https://docs.saloon.dev/).

Implements the **V2 Detailed Click Report** flow only. The deprecated V1 Detailed Click Report (planned shutdown 2026-03-15) is intentionally not included.

Requirements
------------

[](#requirements)

- PHP `^8.2`
- `saloonphp/saloon` `^4.0`
- A pair of idealo Business API credentials (`client_id` + `client_secret`)

Installation
------------

[](#installation)

```
composer require macropage/idealo-business-api
```

Quick Start
-----------

[](#quick-start)

The SDK reads no env vars itself. Wire your own config:

```
use IdealoBusiness\IdealoBusinessConnector;
use IdealoBusiness\Data\ClickReportStatus;

$idealo = new IdealoBusinessConnector(
    clientId:     getenv('IDEALO_CLIENT_ID'),
    clientSecret: getenv('IDEALO_CLIENT_SECRET'),
);

// First request triggers auto-auth via boot(). You can also call it explicitly:
$idealo->authenticateWithClientCredentials();

// idealo returns the shop_id directly in the token response for single-shop credentials:
$shopId = $idealo->getAuthenticatedShopId();
```

Auth
----

[](#auth)

- Endpoint: `POST /api/v1/oauth/token`
- Auth: HTTP Basic (`client_id:client_secret`)
- No request body
- Response fields used by the SDK: `access_token`, `expires_in`, `scope`, `shop_id`

The connector caches the token internally. `boot()` re-authenticates automatically when the token has expired (with a 60-second safety buffer).

Detailed Click Report V2 Flow
-----------------------------

[](#detailed-click-report-v2-flow)

The full flow is **start → poll → download**.

### 1. Start a report

[](#1-start-a-report)

```
$response = $idealo->clickReports()->start(
    shopId: $shopId,
    from:   '2026-04-20', // YYYY-MM-DD, optional
    to:     '2026-04-22', // YYYY-MM-DD, optional
);

$data = $response->json();
// $data = ['status' => 'PROCESSING', 'startTime' => '...', 'id' => '',
//          'shopId' => 12345, 'from' => '2026-04-20', 'to' => '2026-04-22']

$reportId = $data['id'];
```

`HTTP 201 Created` on success. `endTime` is **not present** while status is `PROCESSING`.

### 2. Poll status

[](#2-poll-status)

```
$response = $idealo->clickReports()->get($shopId, $reportId);
$data     = $response->json();

$status = ClickReportStatus::from($data['status']);
// ClickReportStatus::Processing | Failed | Successful
```

Poll responsibly. The SDK ships no built-in polling helper on purpose, so you stay in control of intervals and retries.

### 3. Download (when SUCCESSFUL)

[](#3-download-when-successful)

The download response is a **ZIP archive** containing one CSV file. The SDK does not decompress or parse it.

```
$response = $idealo->clickReports()->download($shopId, $reportId);

// Always treat this as binary. Do NOT call ->json().
file_put_contents("report_{$reportId}.zip", $response->body());
```

Server filename pattern: `click-cost-report_{shopId}_{YYYY-MM-DD-HH-MM-SS}.csv.zip`.

Inspect with PHP's `ZipArchive`:

```
$zip = new ZipArchive();
$zip->open("report_{$reportId}.zip");
$csv = $zip->getFromIndex(0);
```

CSV Columns (Detailed V2)
-------------------------

[](#csv-columns-detailed-v2)

In order:

```
Date, Product, idealo Product ID, Category, Customer-IP, Click Type, Site/Partner, Link, Sku, EANs, Cpc

```

- `Customer-IP` is hashed.
- `EANs` may contain one or more GTIN values.
- `Cpc` is the cost per click (decimal).
- `Click Type` distinguishes regular `offer` clicks from low-price-inventory clicks. See the official docs for the full list.

Limits and Date Rules
---------------------

[](#limits-and-date-rules)

- **5 requests per 24 hours** to `start()` per shop.
- **At least 15 minutes** between two `start()` calls.
- The report covers data **up to 15 months in the past, but never including today**.
- Previous-day data is typically available from **~05:00 UTC**.
- Exceeding the limits returns **HTTP 429**.

Error Handling
--------------

[](#error-handling)

The connector uses `AlwaysThrowOnErrors`. Non-2xx responses throw `Saloon\Exceptions\Request\RequestException`. Common ones:

StatusMeaning`409 Conflict`A report is already in progress for this shop.`429 Too Many Requests`Rate limit reached (5/24h or 15-min minimum).Connector API
-------------

[](#connector-api)

```
$idealo = new IdealoBusinessConnector($clientId, $clientSecret);
// Optional 3rd arg: $baseUrl (defaults to https://businessapi.idealo.com)

$idealo->authenticateWithClientCredentials(): self
$idealo->getAuthenticatedShopId(): ?int   // from token response
$idealo->getTokenScope(): ?string
$idealo->getTokenType(): ?string

$idealo->clickReports()->start(int $shopId, ?string $from = null, ?string $to = null): Response
$idealo->clickReports()->get(int $shopId, string $reportId): Response
$idealo->clickReports()->download(int $shopId, string $reportId): Response
```

Deprecated and Out of Scope
---------------------------

[](#deprecated-and-out-of-scope)

- **Detailed Click Report V1** (`/api/v1/shops/{shopId}/click-reports`) — discontinued 2026-03-15, not implemented.
- **Daily Click Report** — exists at `/api/v1/shops/{shopId}/daily-click-reports/download` and is not yet covered by this SDK.
- The SDK does **not** decompress ZIPs, parse CSV, validate dates, or poll automatically. Those are application concerns.

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance83

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

88d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ea63e34d79d9383a876c7c107f9175746dea8a8b48974a797e39430e135f16a8?d=identicon)[macropage](/maintainers/macropage)

---

Top Contributors

[![michabbb](https://avatars.githubusercontent.com/u/3524595?v=4)](https://github.com/michabbb "michabbb (2 commits)")

---

Tags

idealophpsdk

###  Code Quality

Static AnalysisPHPStan, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/macropage-idealo-business-api/health.svg)

```
[![Health](https://phpackages.com/badges/macropage-idealo-business-api/health.svg)](https://phpackages.com/packages/macropage-idealo-business-api)
```

###  Alternatives

[saloonphp/laravel-plugin

The official Laravel plugin for Saloon

807.1M211](/packages/saloonphp-laravel-plugin)[myoutdeskllc/salesforce-php

salesforce library for php8+

1579.5k](/packages/myoutdeskllc-salesforce-php)[codebar-ag/laravel-docuware

DocuWare integration with Laravel

1123.7k](/packages/codebar-ag-laravel-docuware)[codebar-ag/laravel-zammad

Zammad integration with Laravel

107.1k](/packages/codebar-ag-laravel-zammad)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)