README

A framework-agnostic PHP package for sending data to Ameax via their JSON API. This package provides an easy way to create and send organization, private person, receipt, and sales opportunity data to the Ameax API, with built-in validation according to the JSON schema v1.0.

Installation

You can install the package via composer:

composer require ameax/ameax-json-import-api

Basic Usage

Working with Organizations

use Ameax\AmeaxJsonImportApi\AmeaxJsonImportApi;

// Initialize the client
$client = new AmeaxJsonImportApi(
    'your-api-key',
    'https://your-database.ameax.de'
);

// Create an organization with fluent setters
$organization = $client->createOrganization();

// Add organization details using fluent setters
$organization
    ->setName('ACME Corporation')
    // Set required identifiers
    ->createIdentifiers('CUST12345')
    // Create address (required)
    ->createAddress('12345', 'Berlin', 'DE')
    ->setStreet('Main Street')
    // Set communication details
    ->setEmail('info@acme-corp.com')
    ->setPhone('+49 30 123456789');

// Add a contact
$organization->addContact(
    'John',
    'Doe',
    ['email' => 'john.doe@example.com']
);

// Send to Ameax API
try {
    $response = $organization->sendToAmeax();
    echo "Success!";
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Working with Private Persons

use Ameax\AmeaxJsonImportApi\AmeaxJsonImportApi;

// Initialize the client
$client = new AmeaxJsonImportApi(
    'your-api-key',
    'https://your-database.ameax.de'
);

// Create a private person with fluent setters
$privatePerson = $client->createPrivatePerson();

// Add private person details using fluent setters
$privatePerson
    ->setFirstName('John')
    ->setLastName('Doe')
    // Create address (required)
    ->createAddress('12345', 'Berlin', 'DE')
    ->setStreet('Main Street')
    // Set communication details
    ->setEmail('john.doe@example.com')
    ->setPhone('+49 30 123456789');

// Send to Ameax API
try {
    $response = $privatePerson->sendToAmeax();
    echo "Success!";
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Working with Receipts (Invoices, Orders, etc.)

use Ameax\AmeaxJsonImportApi\AmeaxJsonImportApi;
use Ameax\AmeaxJsonImportApi\Models\Receipt;
use Ameax\AmeaxJsonImportApi\Models\LineItem;
use Ameax\AmeaxJsonImportApi\Models\DocumentPdf;

// Initialize the client
$client = new AmeaxJsonImportApi(
    'your-api-key',
    'https://your-database.ameax.de'
);

// Create a receipt (invoice)
$receipt = $client->createReceipt();

$receipt
    ->setType(Receipt::TYPE_INVOICE)
    ->setReceiptNumber('INV-2025-001')
    ->setCustomerNumber('CUST12345')
    ->setDate('2025-06-01')
    ->setStatus(Receipt::STATUS_PENDING)
    ->setTaxMode(Receipt::TAX_MODE_NET)
    ->setTaxType(Receipt::TAX_TYPE_REGULAR);

// Add line items
$lineItem = new LineItem();
$lineItem
    ->setDescription('Product A')
    ->setQuantity(2)
    ->setPrice(100.00)
    ->setTaxRate(19)
    ->setTaxType(LineItem::TAX_TYPE_REGULAR)
    ->setUom('pcs'); // Unit of measurement (optional)

$receipt->addLineItem($lineItem);

// Add PDF document attachment (optional)
// Option 1: From base64 encoded content
$receipt->setDocumentPdfFromBase64($base64PdfContent);

// Option 2: From URL
$receipt->setDocumentPdfFromUrl('https://example.com/invoice.pdf');

// Option 3: Using DocumentPdf object
$pdf = DocumentPdf::fromBase64($base64PdfContent);
$receipt->setDocumentPdf($pdf);

// Send to Ameax API
try {
    $response = $receipt->sendToAmeax();
    echo "Receipt created successfully!";
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Working with Sales Opportunities

use Ameax\AmeaxJsonImportApi\AmeaxJsonImportApi;
use Ameax\AmeaxJsonImportApi\Models\Sale;
use Ameax\AmeaxJsonImportApi\Models\Rating;

// Initialize the client
$client = new AmeaxJsonImportApi(
    'your-api-key',
    'https://your-database.ameax.de'
);

// Create a sales opportunity
$sale = $client->createSale();

$sale
    ->setExternalId('OPP-2025-001')
    ->setCustomerNumber('CUST12345')
    ->setSubject('New Software Implementation')
    ->setSaleStatus(Sale::STATUS_ACTIVE)
    ->setSellingStatus(Sale::SELLING_STATUS_QUALIFICATION)
    ->setUserExternalId('USER123')
    ->setDate('2025-06-01')
    ->setAmount(50000.00)
    ->setProbability(75)
    ->setCloseDate('2025-07-01');

// Add rating (optional)
$rating = $sale->createRating();
$rating
    ->setRelationship(6, Rating::SOURCE_KNOWN)
    ->setProposition(5, Rating::SOURCE_ASSUMED)
    ->setTrust(7, Rating::SOURCE_KNOWN)
    ->setCompetition(4, Rating::SOURCE_GUESSED)
    ->setNeedForAction(6, Rating::SOURCE_KNOWN)
    ->setBuyingProcess(5, Rating::SOURCE_ASSUMED)
    ->setPrice(5, Rating::SOURCE_KNOWN);

// Send to Ameax API
try {
    $response = $sale->sendToAmeax();
    echo "Sales opportunity created successfully!";
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}

Data Structure

This package follows the Ameax JSON schema structure:

Organization

The organization structure includes multiple nested objects:

[
    'meta' => [
        'document_type' => 'ameax_organization_account',
        'schema_version' => '1.0'
    ],
    'name' => 'ACME Corporation',
    'additional_name' => 'ACME Corp.',
    'identifiers' => [
        'customer_number' => 'CUST12345',
        'external_id' => 'EXT98765',
        'ameax_internal_id' => 123456  // Set by API, read-only
    ],
    'address' => [
        'route' => 'Main Street',
        'house_number' => '123',
        'postal_code' => '12345',
        'locality' => 'Berlin',
        'country' => 'DE'
    ],
    'social_media' => [
        'web' => 'https://www.acme-corp.com'
    ],
    'communications' => [
        'phone_number' => '+49 30 123456789',
        'mobile_phone' => '+49 151 123456789',
        'email' => 'info@acme-corp.com',
        'fax' => '+49 30 987654321'
    ],
    'business_information' => [
        'vat_id' => 'DE123456789',
        'iban' => 'DE89370400440532013000'
    ],
    'agent' => [
        'external_id' => 'AGENT123'
    ],
    'custom_data' => [
        'industry' => 'Technology',
        'employees' => 500
    ],
    'contacts' => [/* Array of contact objects */]
]

Private Person

The private person structure is similar to the organization but without contacts:

[
    'meta' => [
        'document_type' => 'ameax_private_person_account',
        'schema_version' => '1.0'
    ],
    'salutation' => 'Mr.',
    'honorifics' => 'Dr.',
    'firstname' => 'John',
    'lastname' => 'Doe',
    'date_of_birth' => '1980-01-01',
    'identifiers' => [
        'customer_number' => 'CUST12345',
        'external_id' => 'EXT-PP-001',
        'ameax_internal_id' => 654321  // Set by API, read-only
    ],
    'address' => [
        'route' => 'Main Street',
        'house_number' => '123',
        'postal_code' => '12345',
        'locality' => 'Berlin',
        'country' => 'DE'
    ],
    'communications' => [
        'phone_number' => '+49 30 123456789',
        'mobile_phone' => '+49 151 123456789',
        'email' => 'john.doe@example.com',
        'fax' => '+49 30 987654321'
    ],
    'agent' => [
        'external_id' => 'AGENT123'
    ],
    'custom_data' => [
        'preferred_language' => 'en',
        'newsletter_subscription' => true
    ]
]

Contact

Contacts have a similar nested structure:

[
    'salutation' => 'Mr.',
    'honorifics' => 'Dr.',
    'firstname' => 'John',
    'lastname' => 'Doe',
    'date_of_birth' => '1980-01-01',
    'identifiers' => [
        'external_id' => 'EMP123'
    ],
    'employment' => [
        'job_title' => 'CEO',
        'department' => 'Management'
    ],
    'communications' => [
        'phone_number' => '+49 30 123456789',
        'mobile_phone' => '+49 151 123456789',
        'email' => 'john.doe@example.com',
        'fax' => '+49 30 987654321'
    ],
    'custom_data' => [
        'language' => 'en',
        'timezone' => 'Europe/Berlin'
    ]
]

Receipt

Receipts represent invoices, orders, offers, credit notes, and cancellation documents:

[
    'meta' => [
        'document_type' => 'ameax_receipt',
        'schema_version' => '1.0'
    ],
    'type' => 'invoice',
    'identifiers' => [
        'receipt_number' => 'INV-2025-001',
        'external_id' => 'EXT-INV-001',
        'ameax_internal_id' => 12345
    ],
    'business_id' => 1,
    'user_external_id' => 'USER123',
    'sale_external_id' => 'OPP-2025-001',
    'date' => '2025-06-01',
    'customer_number' => 'CUST12345',
    'status' => 'pending',
    'tax_mode' => 'net',
    'tax_type' => 'regular',
    'subject' => 'Invoice for Services',
    'line_items' => [
        [
            'article_number' => 'ART001',
            'description' => 'Consulting Services',
            'quantity' => 10,
            'price' => 150.00,
            'tax_rate' => 19,
            'tax_type' => 'regular',
            'uom' => 'hours'  // Unit of measurement (optional)
        ]
    ],
    'document_pdf' => [
        'type' => 'base64',
        'content' => 'JVBERi0xLjQK...' // base64 encoded PDF content
        // OR use URL mode:
        // 'type' => 'url',
        // 'url' => 'https://example.com/invoice.pdf'
    ],
    'custom_data' => [
        'payment_terms' => '30 days net'
    ]
]

Sale

Sales represent opportunities in the sales pipeline:

[
    'meta' => [
        'document_type' => 'ameax_sale',
        'schema_version' => '1.0'
    ],
    'identifiers' => [
        'external_id' => 'OPP-2025-001',
        'ameax_internal_id' => 54321
    ],
    'customer' => [
        'customer_number' => 'CUST12345'
    ],
    'subject' => 'New Software Implementation',
    'description' => 'Implementation of ERP system',
    'sale_status' => 'active',
    'selling_status' => 'qualification',
    'user_external_id' => 'USER123',
    'date' => '2025-06-01',
    'amount' => 50000.00,
    'probability' => 75,
    'close_date' => '2025-07-01',
    'rating' => [
        'relationship' => ['rating' => 6, 'source' => 'known'],
        'proposition' => ['rating' => 5, 'source' => 'assumed'],
        'trust' => ['rating' => 7, 'source' => 'known'],
        'competition' => ['rating' => 4, 'source' => 'guessed'],
        'need_for_action' => ['rating' => 6, 'source' => 'known'],
        'buying_process' => ['rating' => 5, 'source' => 'assumed'],
        'price' => ['rating' => 5, 'source' => 'known']
    ],
    'custom_data' => [
        'lead_source' => 'website',
        'campaign' => 'Q2-2025'
    ]
]

Complete Examples

Organization Example

Here's a comprehensive example using all available features for organizations:

use Ameax\AmeaxJsonImportApi\AmeaxJsonImportApi;
use Ameax\AmeaxJsonImportApi\Exceptions\ValidationException;

// Create the API client
$client = new AmeaxJsonImportApi('your-api-key', 'https://your-database.ameax.de');

try {
    // Create a new organization
    $organization = $client->createOrganization();
    
    // Set basic information
    $organization->setName('ACME Corporation')
                 ->setAdditionalName('ACME Corp.');
    
    // Set identifiers (required)
    $organization->createIdentifiers('CUST12345', 'EXT98765');
    
    // Create address (required)
    $organization->createAddress('12345', 'Berlin', 'DE')
                 ->setRoute('Example Street')
                 ->setHouseNumber('42');
    
    // Set social media
    $organization->setWebsite('https://www.example.com');
    
    // Set communications
    $organization->createCommunications(
        'info@example.com',          // email
        '+49 30 123456789',          // phone
        '+49 151 123456789',         // mobile
        '+49 30 987654321'           // fax
    );
    
    // Set business information
    $organization->createBusinessInformation(
        'DE123456789',               // VAT ID
        'DE89370400440532013000'     // IBAN
    );
    
    // Set agent
    $organization->createAgent('AGENT123');
    
    // Set custom data
    $organization->setCustomData([
        'industry' => 'Technology',
        'employees' => 500
    ]);
    
    // Create and add a contact with full details
    $contact = $client->createContact();
    $contact->setSalutation('Mr.')
            ->setHonorifics('Dr.')
            ->setFirstName('John')
            ->setLastName('Doe')
            ->setDateOfBirth('1980-01-01');
    
    // Set contact identifiers
    $contact->createIdentifiers('EMP123');
    
    // Set contact employment
    $contact->createEmployment('CEO', 'Management');
    
    // Set contact communications
    $contact->createCommunications(
        'john.doe@example.com',      // email
        '+49 30 123456789',          // phone
        '+49 151 123456789',         // mobile
        '+49 30 987654321'           // fax
    );
    
    // Add the contact to the organization
    $organization->addContactObject($contact);
    
    // Send to Ameax API
    $response = $organization->sendToAmeax();
    
} catch (ValidationException $e) {
    // Handle validation errors
    print_r($e->getErrors());
} catch (\Exception $e) {
    // Handle other errors
    echo $e->getMessage();
}

Private Person Example

Here's a complete example for creating and sending private person data:

use Ameax\AmeaxJsonImportApi\AmeaxJsonImportApi;
use Ameax\AmeaxJsonImportApi\Exceptions\ValidationException;
use Ameax\AmeaxJsonImportApi\Models\Meta;

// Create the API client
$client = new AmeaxJsonImportApi('your-api-key', 'https://your-database.ameax.de');

try {
    // Create a new private person
    $privatePerson = $client->createPrivatePerson();
    
    // Set basic personal information
    $privatePerson->setSalutation('Mr.')
                  ->setHonorifics('Dr.')
                  ->setFirstName('John')
                  ->setLastName('Doe')
                  ->setDateOfBirth('1980-01-01');
    
    // Set identifiers
    $privatePerson->createIdentifiers('CUST12345');
    
    // Create address (required)
    $privatePerson->createAddress('12345', 'Berlin', 'DE')
                  ->setStreet('Example Street')
                  ->setHouseNumber('42');
    
    // Set communications
    $privatePerson->createCommunications(
        'john.doe@example.com',          // email
        '+49 30 123456789',              // phone
        '+49 151 123456789',             // mobile
        '+49 30 987654321'               // fax
    );
    
    // Set agent
    $privatePerson->createAgent('AGENT123');
    
    // Set custom data
    $privatePerson->setCustomData([
        'preferred_language' => 'en',
        'newsletter_subscription' => true
    ]);
    
    // Send to Ameax API
    $response = $privatePerson->sendToAmeax();
    
} catch (ValidationException $e) {
    // Handle validation errors
    print_r($e->getErrors());
} catch (\Exception $e) {
    // Handle other errors
    echo $e->getMessage();
}

Creating from Existing Data

You can create objects from existing data when you already have all the data structured as an array.

Organization from Array

// Complete organization data structure
$data = [
    'meta' => [
        'document_type' => 'ameax_organization_account',
        'schema_version' => '1.0'
    ],
    'name' => 'XYZ Ltd',
    'additional_name' => 'XYZ Limited',
    'identifiers' => [
        'customer_number' => 'CUST54321',
        'external_id' => 'EXT12345'
    ],
    'address' => [
        'route' => 'Main Street',
        'house_number' => '42',
        'postal_code' => '54321',
        'locality' => 'Munich',
        'country' => 'DE',
    ],
    'communications' => [
        'email' => 'info@xyz-ltd.com',
        'phone_number' => '+49 89 123456789'
    ],
    'social_media' => [
        'web' => 'https://www.xyz-ltd.com'
    ],
    'business_information' => [
        'vat_id' => 'DE123456789'
    ],
    'contacts' => [
        [
            'firstname' => 'Jane',
            'lastname' => 'Smith',
            'communications' => [
                'email' => 'jane.smith@xyz-ltd.com'
            ],
            'employment' => [
                'job_title' => 'CEO'
            ]
        ]
    ],
    'custom_data' => [
        'industry' => 'Manufacturing'
    ]
];

// Create the organization from the array
$organization = $client->organizationFromArray($data);

// Optionally modify some fields
$organization->setEmail('new-email@xyz-ltd.com');

// Send to Ameax API
$response = $organization->sendToAmeax();

Private Person from Array

// Complete private person data structure
$data = [
    'meta' => [
        'document_type' => 'ameax_private_person_account',
        'schema_version' => '1.0'
    ],
    'salutation' => 'Ms.',
    'firstname' => 'Jane',
    'lastname' => 'Doe',
    'date_of_birth' => '1985-05-15',
    'identifiers' => [
        'customer_number' => 'CUST67890'
    ],
    'address' => [
        'route' => 'Example Road',
        'house_number' => '42',
        'postal_code' => '54321',
        'locality' => 'Munich',
        'country' => 'DE',
    ],
    'communications' => [
        'email' => 'jane.doe@example.com',
        'phone_number' => '+49 89 123456789'
    ],
    'custom_data' => [
        'preferred_language' => 'en',
        'newsletter_subscription' => true
    ]
];

// Create the private person from the array
$privatePerson = $client->privatePersonFromArray($data);

// Optionally modify some fields
$privatePerson->setEmail('new-email@example.com');

// Send to Ameax API
$response = $privatePerson->sendToAmeax();

You can also create objects with partial data and disable immediate validation:

// Only provide required fields
$minimalData = [
    'firstname' => 'Jane',
    'lastname' => 'Doe',
    'address' => [
        'postal_code' => '54321',
        'locality' => 'Munich',
        'country' => 'DE',
    ],
];

// Pass false to disable immediate validation
$privatePerson = $client->privatePersonFromArray($minimalData, false);

// Fill in more data before validation
$privatePerson->setEmail('jane.doe@example.com')
             ->setCustomerNumber('CUST67890');

// Manually validate when ready
$privatePerson->validate();

// Send to Ameax API
$response = $privatePerson->sendToAmeax();

JSON Schema Validation

This package validates your data against the Ameax JSON schema before sending it to the API. The validation uses the official Ameax JSON schemas to ensure your data is valid. The package performs validation at multiple levels:

1. Field-level validation: Each setter method validates individual fields (e.g., email format, phone number format).
2. Model-level validation: The validate() method checks required fields and relationships.
3. Schema-level validation: Before sending data to the API, it validates against the official Ameax JSON schema.

Custom Schemas

You can use your own schemas by specifying the schemas path using the fluent setter:

$client = new AmeaxJsonImportApi(
    'your-api-key', 
    'https://your-database.ameax.de'
);

$client->setSchemasPath('/path/to/your/schemas');

Schema Validation

The package provides built-in JSON Schema validation using the SchemaValidator class:

use Ameax\AmeaxJsonImportApi\Validation\SchemaValidator;

// Validate data against a schema file
$data = $organization->toArray();
$schemaPath = '/path/to/schemas/ameax_organization_account.json';
SchemaValidator::validate($data, $schemaPath);

// Or validate against a schema string
$schemaJson = file_get_contents($schemaPath);
SchemaValidator::validateWithString($data, $schemaJson);

Documentation

For more detailed documentation, see the docs directory:

• Installation
• Organization API
• API Reference

Testing

composer test

Versioning

This package follows Semantic Versioning. The version numbers follow the MAJOR.MINOR.PATCH format:

• MAJOR version increases when incompatible API changes are made
• MINOR version increases when functionality is added in a backward-compatible manner
• PATCH version increases when backward-compatible bug fixes are implemented

Use the appropriate version constraint in your composer.json:

"require": {
    "ameax/ameax-json-import-api": "^1.0"
}

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Michael Schmidt
• All Contributors

License

The MIT License (MIT). Please see License File for more information.