PHPackages                             ameax/am-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. ameax/am-api

ActiveLibrary[API Development](/categories/api)

ameax/am-api
============

PHP client for the AM API

01.0k↓50%[1 issues](https://github.com/ameax/am-api/issues)PHPCI failing

Since Jul 14Pushed 10mo agoCompare

[ Source](https://github.com/ameax/am-api)[ Packagist](https://packagist.org/packages/ameax/am-api)[ RSS](/packages/ameax-am-api/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

AM API PHP Client
=================

[](#am-api-php-client)

A framework-agnostic PHP client for the AM API with a fluent interface and strong typing.

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

[](#requirements)

- PHP 8.3 or higher
- Composer

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

[](#installation)

```
composer require ameax/am-api
```

Configuration
-------------

[](#configuration)

The package supports two authentication methods: Basic Authentication and API Token.

### Basic Authentication

[](#basic-authentication)

```
use Ameax\AmApi\AmApi;
use Ameax\AmApi\Config\Config;

$config = Config::withBasicAuth(
    apiUrl: 'https://YOURDATABASE.ameax.de/api/rest/1.0/',
    username: 'your-username',
    password: 'your-password'
);

$api = new AmApi($config);
```

### API Token Authentication

[](#api-token-authentication)

```
use Ameax\AmApi\AmApi;
use Ameax\AmApi\Config\Config;

$config = Config::withApiToken(
    apiUrl: 'https://YOURDATABASE.ameax.de/api/rest/1.0/',
    apiToken: 'your-api-token'
);

$api = new AmApi($config);
```

### Configuration Options

[](#configuration-options)

Both authentication methods support additional options:

```
$config = Config::withApiToken(
    apiUrl: 'https://YOURDATABASE.ameax.de/api/rest/1.0/',
    apiToken: 'your-api-token',
    debug: true,  // Enable HTTP debugging
    httpOptions: [
        'timeout' => 60,  // Custom timeout
        'verify' => false  // Disable SSL verification (not recommended for production)
    ]
);
```

Usage Examples
--------------

[](#usage-examples)

### Creating a Customer

[](#creating-a-customer)

```
use Ameax\AmApi\Mappers\CustomerMapper;

// Using mapper to transform your field names to API format
$customerData = CustomerMapper::make()
    ->setData([
        'company_name' => 'Example Company GmbH',
        'route' => 'Hauptstraße',
        'house_number' => '123',
        'postal_code' => '10115',
        'locality' => 'Berlin',
        'country' => 'DE',
        'phone' => '+49 30 12345678',
        'email' => 'info@example.com',
        'fax' => '+49 30 12345679'
    ])
    ->getData();

try {
    $customerId = $api->customers()->add($customerData);
    echo "Customer created with ID: {$customerId}\n";
} catch (\Exception $e) {
    echo "Error creating customer: " . $e->getMessage();
}

// Or directly use API field names without mapping
$customerId = $api->customers()->add([
    'name1' => 'Example Company GmbH',
    'strasse' => 'Hauptstraße 123',
    'plz' => '10115',
    'ort' => 'Berlin',
    'isoland' => 'DE',
    'tel' => '+49 30 12345678',
    'email' => 'info@example.com'
]);
```

### Updating a Customer

[](#updating-a-customer)

```
use Ameax\AmApi\Mappers\CustomerMapper;

// Using mapper for updates
$updateData = CustomerMapper::make()
    ->setData([
        'company_name' => 'Updated Company Name GmbH',
        'phone' => '+49 30 98765432',
        'email' => 'newemail@example.com'
    ])
    ->getData();

try {
    $success = $api->customers()->update(12345, $updateData);

    if ($success) {
        echo "Customer updated successfully\n";
    }
} catch (\Exception $e) {
    echo "Error updating customer: " . $e->getMessage();
}
```

### More Examples

[](#more-examples)

```
// Get customer with related data - returns array
$customer = $api->customers()->get(12345, ['files', 'person', 'project']);

// Search customers
$results = $api->customers()->search([
    'name1_like' => 'Example',
    'add_dt_from' => '2024-01-01',
    'add_dt_till' => '2024-12-31'
]);

// Load customer (alternative search method)
$results = $api->customers()->load([
    'name1_like' => 'Example',
    'cat' => 1,
    'files' => 1,
    'images' => 1
]);

// Delete customer - returns bool
$deleted = $api->customers()->delete(12345);

// Account operations
$accountId = $api->accounts()->add(['email' => 'user@example.com', 'pw' => 'password']);
$account = $api->accounts()->get($accountId);
$api->accounts()->changePassword($accountId, 'newPassword');
$results = $api->accounts()->searchByEmail('user@example.com');

// Person operations with mapper
use Ameax\AmApi\Mappers\PersonMapper;

$personData = PersonMapper::make()
    ->setData([
        'customer_id' => 12345,
        'firstname' => 'John',
        'lastname' => 'Doe',
        'email' => 'john@example.com',
        'gender' => 'male',
        'phone' => '+49 30 12345678'
    ])
    ->getData();

$personId = $api->persons()->add($personData);

// Relation operations
$relationId = $api->relations()->add(12345, 67890, 'invoiceaddress');
$relations = $api->relations()->get(12345);

// Receipt PDF operations
// First, get the PDF data from the API (includes base64 content and metadata)
$pdfData = $api->receipts()->getPdfBase64($receiptId, 'Online');
// Returns: ['receipt_id' => 123, 'pdf_base64' => '...', 'filename' => 'Invoice_123.pdf', 'size' => 45678, 'generated_at' => '2024-01-01 12:00:00']

// Option 1: Decode to binary for direct output
$pdfContent = $api->receipts()->decodePdf($pdfData);
header('Content-Type: application/pdf');
header('Content-Disposition: inline; filename="' . $pdfData['filename'] . '"');
echo $pdfContent;

// Option 2: Save to file using the helper
$result = $api->receipts()->savePdfFromData($pdfData, '/path/to/invoices/invoice_123.pdf');
// Returns: ['filename' => 'Invoice_123.pdf', 'size' => 45678, 'path' => '/path/to/invoices/invoice_123.pdf']

// Object operations with file upload
$reflection = new ReflectionClass($api);
$clientProperty = $reflection->getProperty('client');
$clientProperty->setAccessible(true);
$client = $clientProperty->getValue($api);

// Create object with customer link
$response = $client->post('addObjectAndCustomerobject', [], [
    'object_id' => 1,
    'customer_id' => 12345,
    'project_id' => 1,
    'o_kennung' => 'REF-2024-001'
]);

if ($response['response']['ack'] === 'ok') {
    $objectDbId = $response['result']['id'];
    $indexId = $response['result']['index_id'];

    // Upload file to object (use database ID, not index_id!)
    $fileId = $api->files()->uploadToObject(1, $objectDbId, 'o_upload',
        '/path/to/file.pdf', 'application/pdf', 'document.pdf');
}
```

Field Mapping
-------------

[](#field-mapping)

The package provides optional mapper classes to transform between your application's field names and the AM API field names:

```
use Ameax\AmApi\Mappers\CustomerMapper;
use Ameax\AmApi\Mappers\PersonMapper;

// Map your data to API format
$apiData = CustomerMapper::make()
    ->setData([
        'company_name' => 'ACME Corp',
        'route' => 'Main Street',
        'house_number' => '42',
        'postal_code' => '10115',
        'locality' => 'Berlin'
    ])
    ->getData();

// Map API response back to your format
$apiResponse = $api->customers()->get(123);
$yourData = CustomerMapper::fromApiResponse($apiResponse);
```

### Customer Field Mappings

[](#customer-field-mappings)

Your FieldAPI FieldNotes`company_name``name1``route` + `house_number``strasse`Combined automatically`postal_code``plz``locality``ort``country``isoland``phone``tel`### Person Field Mappings

[](#person-field-mappings)

Your FieldAPI FieldNotes`firstname``vorname``lastname``nachname``phone``tel``mobile``mobil``department``abteilung``gender``anrede`Values: male→Herr, female→FrauFields like `email` and `fax` are passed through without mapping. You can also use the API field names directly without any mapping.

### Custom Fields

[](#custom-fields)

The API supports custom fields prefixed with module codes:

- `xcu_` - Customer custom fields
- `xpe_` - Person custom fields
- Other module-specific prefixes

Example:

```
$customerData = [
    'name1' => 'Company Name',
    'xcu_eine_weitere_adresse__street' => 'Custom Street',
    'xcu_eine_weitere_adresse__zipcode' => '12345',
    'xcu_eine_weitere_adresse__city' => 'Custom City'
];
```

Architecture
------------

[](#architecture)

This package follows a fluent resource-based architecture with strong typing:

- **Resource Classes**: Each API resource (customers, accounts, etc.) has its own class
- **Fluent Interface**: Clean method chaining: `$api->customers()->add(...)`
- **Strong Typing**: All methods have explicit return types (int, bool, array) - no mixed types
- **Optional Mappers**: Transform between your field names and API field names when needed
- **Trait-based Sharing**: Common functionality shared via traits instead of inheritance

Development
-----------

[](#development)

```
# Install dependencies
composer install

# Run linting
composer lint

# Run static analysis
composer test:types
```

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE.md).

###  Health Score

21

—

LowBetter than 18% of packages

Maintenance39

Infrequent updates — may be unmaintained

Popularity19

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity14

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.

### Community

Maintainers

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

---

Top Contributors

[![ms-aranes](https://avatars.githubusercontent.com/u/69188126?v=4)](https://github.com/ms-aranes "ms-aranes (12 commits)")

### Embed Badge

![Health badge](/badges/ameax-am-api/health.svg)

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

###  Alternatives

[stripe/stripe-php

Stripe PHP Library

4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[facebook/php-business-sdk

PHP SDK for Facebook Business

90821.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

74513.7M114](/packages/meilisearch-meilisearch-php)[google/gax

Google API Core for PHP

265103.1M454](/packages/google-gax)[google/common-protos

Google API Common Protos for PHP

173103.7M50](/packages/google-common-protos)

PHPackages © 2026

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