PHPackages                             themarketer/api-client - 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. themarketer/api-client

ActiveLibrary[API Development](/categories/api)

themarketer/api-client
======================

The Marketer PHP api client

0.1.0(1mo ago)02MITPHPPHP ^8.1CI passing

Since Apr 28Pushed 3w agoCompare

[ Source](https://github.com/the-marketer/api-client)[ Packagist](https://packagist.org/packages/themarketer/api-client)[ RSS](/packages/themarketer-api-client/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (5)Versions (3)Used By (0)

The Marketer API Client (PHP)
=============================

[](#the-marketer-api-client-php)

Client PHP pentru API-ul **The Marketer**. Trimite cereri HTTP prin **Guzzle** (clasa internă `ApiGateway`) și validează payload-urile cu **Symfony Validator** (DTO-uri `AbstractPayload` / `Data` din `TheMarketer\ApiClient\Common`).

Documentatie pentru clienti
---------------------------

[](#documentatie-pentru-clienti)

Pentru o varianta structurata, usor de parcurs:

- [API Client Docs](https://the-marketer.github.io/api-client/docs/intro)

### Docusaurus site (GitHub Pages)

[](#docusaurus-site-github-pages)

Documentatia este pregatita si ca site Docusaurus in folderul `website/`.

Rulare locala:

```
cd website
npm install
npm run start
```

Deploy pe GitHub Pages este configurat prin workflow-ul:

- `.github/workflows/deploy-docs.yml`

Cerințe (requirements)
----------------------

[](#cerințe-requirements)

CerințăVersiune / notă**PHP**`^8.1`**Composer**pentru instalarea dependențelor**ext-mbstring**obligatoriu**Dependențe principale**`guzzlehttp/guzzle` ^7, `symfony/validator` ^7, `symfony/expression-language` ^8**Dezvoltare / teste**`phpunit` ^10, `orchestra/testbench` ^8 (pentru suite-ul de teste)Instalare în proiect:

```
composer install
```

Pachet public (exemplu):

```
composer require themarketer/api-client
```

---

Arhitectură pe scurt
--------------------

[](#arhitectură-pe-scurt)

- **`TheMarketer\ApiClient\Client`** — punct unic de intrare: primește un **array** de configurare (`customerId`, `restKey`, opțional `trackingKey`, `restUrl`, `trackingUrl`, `maxRetryAttempts`), construiește **`Config`** + **`ApiContext`** și expune modulele API (`subscribers()`, `orders()`, `checkCredentials()`, etc.).
- **`ApiContext`** — oferă gateway **REST** (`ApiGateway`) și **tracking** (`TrackingGateway`); ambele folosesc Guzzle (retry configurabil).
- **`ApiGateway`** — pentru REST: query `k` (rest key) și `u` (customer id); JSON la POST unde cere DTO-ul; mapează erorile HTTP la excepții.
- **`TrackingGateway`** — pentru host-ul de tracking: necesită `trackingKey` în config; alt set de parametri de autentificare în query.
- **Clasele din `src/Api/`** — încapsulează endpoint-urile; validarea inputului se face în **`src/DTO/`**.

Baza URL pentru REST este `Config::baseRestUrl()` = `{restUrl}/api/{apiVersion}/` (implicit `apiVersion` = `v1`). URL-urile implicite sunt în `Client` / `Config` (`src/Common/Config.php`).

---

Utilizare de bază
-----------------

[](#utilizare-de-bază)

```
use TheMarketer\ApiClient\Client;

$client = new Client([
    'customerId' => 'ID_CONT_THE_MARKETER', // query `u` pe REST
    'restKey' => 'CHEIA_REST',               // query `k` pe REST
    'trackingKey' => 'CHEIE_TRACKING',     // opțional: pentru evenimente tracking
    'maxRetryAttempts' => 1,                // opțional
]);

// Exemple de acces la API-uri grupate
$client->subscribers()->addSubscriber([/* … */]);
$client->orders()->saveOrder([/* … */]);
$client->transactionals()->sendEmail([/* … */]);
```

---

Credențiale și utilitare (direct pe `Client`)
---------------------------------------------

[](#credențiale-și-utilitare-direct-pe-client)

Aceste metode nu trec prin `subscribers()` / `orders()`; sunt delegate la **`CredentialsClient`** intern.

### `checkCredentials(string $trackingKey): bool`

[](#checkcredentialsstring-trackingkey-bool)

Verifică credențialele (tracking key în **body JSON** pe REST, vezi `CredentialsClient`). Pe **`Client`**, returnează **`true`** dacă răspunsul decodat este array gol `[]`, altfel **`false`**. Pentru JSON-ul brut ca `array`, folosește `CredentialsClient::checkCredentials()` cu același context.

```
$ok = $client->checkCredentials('CHEIE_TRACKING');
```

### `checkApiCredentials(): bool`

[](#checkapicredentials-bool)

Pe **`Client`**, returnează **`bool`** (același criteriu: corp JSON → array gol = succes). Pentru răspuns decodat complet, vezi `CredentialsClient::checkApiCredentials()`.

```
$ok = $client->checkApiCredentials();
```

### `getCosts()`, `getRealtimeVisitors()`, `getSmsCredit(): array`

[](#getcosts-getrealtimevisitors-getsmscredit-array)

Răspuns JSON decodat.

### `getReferralLink(?string $email = null): string`

[](#getreferrallinkstring-email--null-string)

Returnează **conținutul brut** al răspunsului (nu JSON).

### `getDeliveryLogs(array $payload): array`

[](#getdeliverylogsarray-payload-array)

`email` obligatoriu; opțional: `per_page`, `page`, `start`, `end`.

### `getEnteredAutomation(array $payload): array`

[](#getenteredautomationarray-payload-array)

`date` obligatoriu (`Y-m-d`); opțional `page`, `perPage`.

### `config(): Config`

[](#config-config)

Acces la `customerId`, `restKey`, `baseRestUrl()`, `trackingKey()`, etc.

---

Module API (exemple)
--------------------

[](#module-api-exemple)

Accesor pe `Client`Rol`subscribers()`Abonați: status, add/remove, bulk, tag-uri, etc.`orders()`Comenzi, feed URL, retail, statistici`transactionals()`Email și SMS tranzacționale`products()`CRUD / sync produse, categorii, branduri`campaigns()`Listă, creare campanie, raport email, ultima campanie`loyalty()`Puncte loialitate`coupons()`Cupoane disponibile, salvare`reviews()`Recenzii produse, merchant, setări Merchant Pro`mobilePush()`Push mobil (token-uri iOS/Android)`events()`Evenimente personalizate`reports()`Rapoarte email/SMS/push/forms/audienceDetalii despre parametri: fișierele din `src/Api/*Api.php` și `src/DTO/**`. Testele din `tests/*ApiTest.php` arată exemple de payload-uri valide.

### Campanii — note importante

[](#campanii--note-importante)

- **`list()`** folosește **POST** către `/campaigns/list`, cu body din `ListCampaign`.
- **`create()`** cere structură imbricată validată de `CreateCampaign`; la **sender** folosește cheile **`name`**, **`sender`** (email), **`reply_to`** (nu `sender_name` / `sender_email`).

### Recenzii

[](#recenzii)

- **`getProductReviews()`** returnează **string** (conținut răspuns, nu `array` decodat automat).

### Rapoarte

[](#rapoarte)

- Query-urile includ de obicei `start`, `end`, `type` (vezi enum-urile din `src/Enum/` și DTO-urile din `src/DTO/Reports/`).

---

Erori și excepții
-----------------

[](#erori-și-excepții)

**Înainte de request (validare locală)**

- **`TheMarketer\ApiClient\Exception\ValidationException`** — lipsă `customerId` / `restKey` în config sau mesaje din validarea Symfony pe DTO.
- Lipsă argumente obligatorii la construirea DTO poate duce la **`ArgumentCountError`** sau **`TypeError`** înainte de rețea.

**După request** (`ApiGateway` mapează status HTTP)

StatusExcepție**401**`UnauthorizedException`**404**`CustomerNotFoundException`**405**`MethodNotAllowedException`Alte erori`ApiException` (folosește codul și mesajul din răspuns; mesajul e extras din JSON `message` când există)La răspuns de succes cu JSON invalid, metodele care decodă pot arunca **`JsonException`**. Pentru erori de rețea: **`GuzzleHttp\Exception\GuzzleException`**.

---

Teste
-----

[](#teste)

```
composer test
```

Suite-ul folosește `ApiGateway` cu **Guzzle MockHandler** (fără apeluri reale la API). Pentru **`Client`** în teste cu mock HTTP, `context` este `readonly`; în practică se testează `CredentialsClient` și clasele `*Api` cu același stack — vezi `tests/CredentialsClientTest.php` și `tests/TestCase.php`.

---

Script smoke (`smoke.php`)
--------------------------

[](#script-smoke-smokephp)

Verificare rapidă cu **credențiale reale** (nu comita chei în repo):

```
php smoke.php
```

Exemplul din repo apelează `checkCredentials($trackingKey)` — înlocuiește valorile cu cele din contul tău The Marketer.

---

Licență
-------

[](#licență)

MIT (vezi `composer.json`).

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance93

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

 Bus Factor1

Top contributor holds 54.3% 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

42d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/56d28ba81bf83f27f15d64332c55c5f25004aead889cf62658f982820e4cc44c?d=identicon)[themarketer](/maintainers/themarketer)

---

Top Contributors

[![radudalbea-mkt](https://avatars.githubusercontent.com/u/246182343?v=4)](https://github.com/radudalbea-mkt "radudalbea-mkt (19 commits)")[![negura-alexandru](https://avatars.githubusercontent.com/u/263327552?v=4)](https://github.com/negura-alexandru "negura-alexandru (14 commits)")[![cristiantoma-mkt](https://avatars.githubusercontent.com/u/275912144?v=4)](https://github.com/cristiantoma-mkt "cristiantoma-mkt (2 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/themarketer-api-client/health.svg)

```
[![Health](https://phpackages.com/badges/themarketer-api-client/health.svg)](https://phpackages.com/packages/themarketer-api-client)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k5.8M710](/packages/sylius-sylius)[rcsofttech/audit-trail-bundle

Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking.

1155.2k](/packages/rcsofttech-audit-trail-bundle)[pimcore/pimcore

Content & Product Management Framework (CMS/PIM/E-Commerce)

3.8k3.8M444](/packages/pimcore-pimcore)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3751.2M45](/packages/tencentcloud-tencentcloud-sdk-php)[open-dxp/opendxp

Content & Product Management Framework (CMS/PIM)

9017.2k55](/packages/open-dxp-opendxp)

PHPackages © 2026

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