{"id":17275178,"url":"https://github.com/mjaschen/collmex","last_synced_at":"2025-04-05T09:08:43.278Z","repository":{"id":10645070,"uuid":"12872921","full_name":"mjaschen/collmex","owner":"mjaschen","description":"Collmex PHP SDK","archived":false,"fork":false,"pushed_at":"2025-01-07T15:56:46.000Z","size":754,"stargazers_count":18,"open_issues_count":7,"forks_count":23,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-29T08:08:43.536Z","etag":null,"topics":["collmex"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mjaschen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"mjaschen","custom":"https://www.paypal.com/paypalme/mjaschen"}},"created_at":"2013-09-16T16:58:11.000Z","updated_at":"2025-01-07T15:56:27.000Z","dependencies_parsed_at":"2025-02-23T21:12:03.507Z","dependency_job_id":"f47be90c-3548-44ab-8c6d-3a1d39310e71","html_url":"https://github.com/mjaschen/collmex","commit_stats":{"total_commits":591,"total_committers":22,"mean_commits":"26.863636363636363","dds":0.4145516074450084,"last_synced_commit":"56cf574f0aa5e662ce961e53eadc36b2b69a51ff"},"previous_names":[],"tags_count":119,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjaschen%2Fcollmex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjaschen%2Fcollmex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjaschen%2Fcollmex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjaschen%2Fcollmex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mjaschen","download_url":"https://codeload.github.com/mjaschen/collmex/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247312081,"owners_count":20918344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["collmex"],"created_at":"2024-10-15T08:55:37.056Z","updated_at":"2025-04-05T09:08:43.235Z","avatar_url":"https://github.com/mjaschen.png","language":"PHP","funding_links":["https://github.com/sponsors/mjaschen","https://www.paypal.com/paypalme/mjaschen"],"categories":[],"sub_categories":[],"readme":"# Collmex API PHP SDK\n\n[![Latest Stable Version](https://poser.pugx.org/mjaschen/collmex/v)](https://packagist.org/packages/mjaschen/collmex)\n[![Total Downloads](https://poser.pugx.org/mjaschen/collmex/downloads)](https://packagist.org/packages/mjaschen/collmex)\n[![CI Status](https://github.com/mjaschen/collmex/workflows/Collmex%20PHP%20SDK%20Tests/badge.svg)](https://github.com/mjaschen/collmex/actions)\n[![License](https://poser.pugx.org/mjaschen/collmex/license)](https://packagist.org/packages/mjaschen/collmex)\n\nThis library provides a wrapper for the Collmex API. It's not complete yet, some record types (and maybe some features)\nare missing.\n\nPlease create a pull request if you have implemented a new type/feature or create issues for bugs/feature requests.\n\nThere is (or least should be…) a *Type* class for every Collmex record type\n(\"Satzart\"). Currently, only the base types (`MESSAGE`, `LOGIN`,\n`NEW_OBJECT_ID`) and a few normal record types are implemented:\n\n- `ABO_GET`\n- `ACC_BAL`\n- `ACCBAL_GET`\n- `ACCDOC`\n- `ACCDOC_GET`\n- ... [full list »](#list-of-supported-types)\n\n## Compatibility\n\nThe Collmex PHP SDK requires PHP \u003e= 8.1. It's possible to install an older\nversion of the Collmex PHP SDK, if you're still using a no longer supported\nPHP version:\n\n- for PHP 7.3, 7.4 and 8.0 compatibility: use the 2.x tags (`composer require mjaschen/collmex:^2.0`); this version will receive security updates until version 4.0 is released.\n- for PHP 7.2 compatibility: use the 1.x tags (`composer require mjaschen/collmex:^1.0`); this version won't receive any updates.\n- for PHP 7.0 compatibility: use the 0.12.x tags (`composer require mjaschen/collmex:^0.12`); this version won't receive any updates.\n- for PHP 5.6 compatibility: use the 0.11.x tags (`composer require mjaschen/collmex:^0.11`); this version won't receive any updates.\n\nNew features will only go into the main branch and won't be backported.\n\n| PHP Version | Collmex PHP SDK Version | Support Status       |\n| ----------- | ----------------------- | -------------------- |\n| 8.4         | 3.x                     | ✅ active (untested) |\n| 8.3         | 3.x                     | ✅ active            |\n| 8.2         | 3.x                     | ✅ active            |\n| 8.1         | 3.x                     | ✅ active            |\n| 8.0         | 2.x                     | ⚠️ security only   |\n| 7.4         | 2.x                     | ⚠️ security only   |\n| 7.3         | 2.x                     | ⚠️ security only   |\n| 7.2         | 1.x                     | ❌ end of life       |\n| 7.1         | 1.x                     | ❌ end of life       |\n| 7.0         | 1.x                     | ❌ end of life       |\n| 5.6         | 0.11.x                  | ❌ end of life       |\n\n## Installation\n\nUsing Composer, just add it to your `composer.json` by running:\n\n```shell\ncomposer require mjaschen/collmex\n```\n\nIf you want to use the included Laravel service provider\n`CollmexServiceProvider`, add it to the `config/app.php` providers array:\n\n```php\nreturn [\n\n    // ...\n\n    'providers' =\u003e [\n        // ...\n        \\MarcusJaschen\\Collmex\\CollmexServiceProvider::class,\n    ],\n\n    // ...\n];\n```\n\n## Upgrading\n\n### Version 2.x to 3.x\n\n1. Read the [change log](https://github.com/mjaschen/collmex/blob/main/CHANGELOG.md).\n   You will see the list of everything changed between versions 2 and 3.\n2. Ensure your codebase is compatible with all requirements in `composer.json`.\n3. Update your `composer.json` to require version 3.x of the Collmex PHP SDK:\n\n  ```json\n  {\n    \"require\": {\n      \"mjaschen/collmex\": \"^3.0\"\n    }\n  }\n  ```\n\n### Version 1.x to 2.x\n\n1. Read the [change log](https://github.com/mjaschen/collmex/blob/main/CHANGELOG.md).\n   You will see the list of everything changed between versions 1 and 2.\n2. Ensure your codebase is compatible with all requirements in `composer.json`.\n3. Rename attributes which are used in your codebase. Some attributes\n   in the type classes have been renamed. If you use these attributes, you have\n   to adjust your code as well. A simple search-and-replace is sufficient for\n   this. Below you will find the complete list of renamed attributes:\n\n| Class                      | Old Name                      | New Name                     |\n| -------------------------- | ----------------------------- | ---------------------------- |\n| `Stock`                    | `charge_number`               | `batch_number`               |\n| `Stock`                    | `charge_description`          | `batch_description`          |\n| `StockChange`              | `destination_charge`          | `destination_batch`          |\n| `StockChange`              | `destination_charge_labeling` | `destination_batch_labeling` |\n| `StockChange`              | `source_charge`               | `source_batch`               |\n| `AccountDocumentGet`       | `only_changed`                | `changed_only`               |\n| `CustomerGet`              | `only_changed`                | `changed_only`               |\n| `MemberGet`                | `only_changed`                | `changed_only`               |\n| `SalesOrderGet`            | `only_changed`                | `changed_only`               |\n| `StockGet`                 | `only_changed`                | `changed_only`               |\n| `VoucherGet`               | `only_changed`                | `changed_only`               |\n| `Customer`                 | `forename`                    | `firstname`                  |\n| `CustomerOrder`            | `forename`                    | `firstname`                  |\n| `Invoice`                  | `forename`                    | `firstname`                  |\n| `Member`                   | `forename`                    | `firstname`                  |\n| `Customer`                 | `firm`                        | `company`                    |\n| `DifferentShippingAddress` | `firm`                        | `company`                    |\n| `Member`                   | `firm`                        | `company`                    |\n| `CustomerOrder`            | `customer_firm`               | `customer_company`           |\n| `Invoice`                  | `customer_firm`               | `customer_company`           |\n| `CustomerOrder`            | `delivery_firm`               | `delivery_company`           |\n| `Invoice`                  | `delivery_firm`               | `delivery_company`           |\n\n## Usage/Examples\n\n### Fetch from Collmex API\n\n#### Load a Collmex *Customer* record:\n\n```php\nuse MarcusJaschen\\Collmex\\Client\\Curl as CurlClient;\nuse MarcusJaschen\\Collmex\\Request;\nuse MarcusJaschen\\Collmex\\Type\\CustomerGet;\n\n// initialize HTTP client\n$collmexClient = new CurlClient('USER', 'PASSWORD', 'CUSTOMER_ID');\n\n// create request object\n$collmexRequest = new Request($collmexClient);\n\n// create a record type; we're querying the API for customer with ID=12345\n$getCustomerType = new CustomerGet(array('customer_id' =\u003e '12345'));\n\n// send HTTP request and get response object\n$collmexResponse = $collmexRequest-\u003esend($getCustomerType-\u003egetCsv());\n\nif ($collmexResponse-\u003eisError()) {\n    echo 'Collmex error: ' . $collmexResponse-\u003egetErrorMessage() . '; Code=' . $collmexResponse-\u003egetErrorCode() . PHP_EOL;\n\n    return;\n}\n\n$records = $collmexResponse-\u003egetRecords();\n\nforeach ($records as $record) {\n    // contains one Customer object and the Message object(s)\n    var_dump($record-\u003egetData());\n}\n\n// show unparsed response contents:\nvar_dump($collmexResponse-\u003egetResponseRaw());\n```\n\n#### Fetch a PDF Invoice from Collmex\n\n```php\nuse MarcusJaschen\\Collmex\\Client\\Curl as CurlClient;\nuse MarcusJaschen\\Collmex\\Request;\nuse MarcusJaschen\\Collmex\\Type\\InvoiceGet;\n\n$collmexRequest = new Request(new CurlClient('USER', 'PASSWORD', 'CUSTOMER_ID'));\n$getInvoice = new InvoiceGet(['invoice_id' =\u003e '1', 'format' =\u003e InvoiceGet::FORMAT_ZIP]);\n\ntry {\n    $collmexResponse = $collmexRequest-\u003esend($getInvoice-\u003egetCsv());\n} catch (\\Exception) {\n    // Error Handling ...\n}\n\n/** @var \\Symfony\\Component\\Finder\\Finder $files */\n$files = $collmexResponse-\u003egetFilesByType(type: 'pdf');\n\n/** @var SplFileInfo $file */\nforeach ($files as $file) {\n    $pdfContent = file_get_contents($file-\u003egetPathname());\n    // save, mail, display, etc.\n    break;\n}\n```\n\n\n### Send Data to Collmex\n\nCreate a new Collmex *Customer* record and get the Collmex customer ID from the response data:\n\n```php\nuse MarcusJaschen\\Collmex\\Client\\Curl as CurlClient;\nuse MarcusJaschen\\Collmex\\Request;\nuse MarcusJaschen\\Collmex\\Type\\Customer;\n\n// initialize HTTP client\n$collmexClient = new CurlClient('USER', 'PASSWORD', 'CUSTOMER_ID');\n\n// create request object\n$collmexRequest = new Request($collmexClient);\n\n// create a record type; we create a customer with some basic fields\n$customer = new Customer(\n    [\n        'client_id' =\u003e '1',\n        'salutation' =\u003e 'Herr',\n        'firstname' =\u003e 'Charly',\n        'lastname' =\u003e 'Cash',\n        'street' =\u003e 'Hauptstraße 12',\n        'zipcode' =\u003e '12222',\n        'city' =\u003e 'Berlin',\n        'inactive' =\u003e Customer::STATUS_ACTIVE,\n        'country' =\u003e 'DE',\n        'phone' =\u003e '+49300000000',\n        'email' =\u003e 'cash@example.org',\n        'output_medium' =\u003e Customer::OUTPUT_MEDIUM_EMAIL,\n    ]\n);\n\n// send HTTP request and get response object\n$collmexResponse = $collmexRequest-\u003esend($customer-\u003egetCsv());\n\nif ($collmexResponse-\u003eisError()) {\n    echo 'Collmex error: ' . $collmexResponse-\u003egetErrorMessage() . '; Code=' . $collmexResponse-\u003egetErrorCode() . PHP_EOL;\n\n    return;\n}\n\n  $newObject = $collmexResponse-\u003egetFirstRecord();\n  echo 'New Collmex customer ID=' . $newObject-\u003enew_id . PHP_EOL;\n\n  $records = $collmexResponse-\u003egetRecords();\n\n  foreach ($records as $record) {\n      // contains one NewObject object and the Message object(s)\n      var_dump($record-\u003egetData());\n  }\n```\n\n### Send Multiple Records at Once\n\nThe Collmex API accepts requests containing multiple records.\n\nFor example, a customer order with three line-items is sent as three CSV records/lines within a single request.\n\nThe `MultiRequest` class provides a simple way to send multiple records to Collmex at once. Any valid `Type` (or an\narray of valid `Type` instances) can be added to a queue and eventually sent to the Collmex API.\n\n```php\nuse MarcusJaschen\\Collmex\\Client\\Curl as CurlClient;\nuse MarcusJaschen\\Collmex\\MultiRequest;\nuse MarcusJaschen\\Collmex\\Type\\CustomerOrder;\n\n// initialize HTTP client\n$collmexClient = new CurlClient('USER', 'PASSWORD', 'CUSTOMER_ID');\n\n// create request object\n$collmexMultiRequest = new MultiRequest($collmexClient);\n\n// create a record type; we create a CustomerOrder with some basic fields\n$customerOrderData = [\n    'client_id' =\u003e '1',\n    'customer_salutation' =\u003e 'Herr',\n    'customer_firstname' =\u003e 'Charly',\n    'customer_lastname' =\u003e 'Cash',\n    'customer_street' =\u003e 'Hauptstraße 12',\n    'customer_zipcode' =\u003e '12222',\n    'customer_city' =\u003e 'Berlin',\n    'customer_country' =\u003e 'DE',\n    'customer_phone' =\u003e '+49300000000',\n    'customer_email' =\u003e 'cash@example.org',\n    'order_date' =\u003e '01.01.1970',\n    'status' =\u003e CustomerOrder::STATUS_CONFIRMED,\n];\n\n// set several item positions\n$customerOrderItem = new CustomerOrder(\n    array_merge(\n        $customerOrderData,\n        [\n            'product_description' =\u003e 'erster Artikel',\n            'quantity' =\u003e '1',\n            'price' =\u003e '10,50',\n            'tax_rate' =\u003e CustomerOrder::TAX_RATE_FULL,\n        ]\n    )\n);\n$collmexMultiRequest-\u003eadd($customerOrderItem);\n\n$customerOrderItem = new CustomerOrder(\n    array_merge(\n        $customerOrderData,\n        [\n            'product_description' =\u003e 'zweiter Artikel',\n            'quantity' =\u003e '10',\n            'price' =\u003e '37,99',\n            'tax_rate' =\u003e CustomerOrder::TAX_RATE_REDUCED,\n        ]\n    )\n);\n$collmexMultiRequest-\u003eadd($customerOrderItem);\n\n$customerOrderItem = new CustomerOrder(\n    array_merge(\n        $customerOrderData,\n        [\n            'product_description' =\u003e 'Artikel Nummer drei',\n            'quantity' =\u003e '3',\n            'price' =\u003e '1250,00',\n            'tax_rate' =\u003e CustomerOrder::TAX_RATE_FULL,\n        ]\n    )\n);\n$collmexMultiRequest-\u003eadd($customerOrderItem);\n\n// send HTTP request and get response object\n$collmexResponse = $collmexMultiRequest-\u003esend();\n\nif ($collmexResponse-\u003eisError()) {\n    echo 'Collmex error: ' . $collmexResponse-\u003egetErrorMessage() . '; Code=' . $collmexResponse-\u003egetErrorCode() . PHP_EOL;\n\n    return;\n}\n\n$newObject = $collmexResponse-\u003egetFirstRecord();\necho 'New Collmex order ID=' . $newObject-\u003enew_id . PHP_EOL;\n\n$records = $collmexResponse-\u003egetRecords();\n\nforeach ($records as $record) {\n    // contains one NewObject object and the Message object(s)\n    var_dump($record-\u003egetData());\n}\n```\n\n## Notes\n\nCollmex expects all strings encoded in code page 1252 (Windows) while the\nCollmex PHP SDK expects all inputs as UTF-8 and outputs everything as UTF-8.\nThe conversion of string encodings is done transparently by using the\nSymfony String Component and PHP's `mb_convert_encoding()` function before\nsending a request to the Collmex API and after receiving the response from\nthe API.\n\n### Numeric / money values\n\nThis SDK does not convert numeric values to the string format required by\nthe Collmex API by default.\n\nFor more information on format requirements, see the [offical API documentation](https://www.collmex.de/c.cmx?1005,1,help,daten_importieren_datentypen_felder).\n\nThe library provides helpers for simple conversion from several types to\nthe Collmex money format:\n\n| type                                                 | example value                      | call                       | result (string) |\n| ---------------------------------------------------- | ---------------------------------- | -------------------------- | --------------- |\n| *float*                                              | `19.99`                            | `Money::fromFloat(19.99)`  | `19,99`         |\n| *integer* (cents)                                    | `1999`                             | `Money::fromCents(1999)`   | `19,99`         |\n| [Money for PHP](https://www.moneyphp.org/en/stable/) | `$money = \\Money\\Money::EUR(1999)` | `Money::fromMoney($money)` | `19,99`         |\n\nFully qualified class name for the helper: `\\MarcusJaschen\\Collmex\\CollmexField\\Money`.\n\nSee the unit tests for [more examples](tests/Unit/CollmexField/MoneyTest.php).\n\n### Date Values\n\nCollmex unterstands two different formats for dates:\n\n- ISO style: `YYYYMMDD`\n- German style: `DD.MM.YYYY`\n\nThe library provides a helper to convert `DateTime` (which covers *Carbon* instances as well) from and to the Collmex date format:\n\n```php\nuse MarcusJaschen\\Collmex\\CollmexField\\Date;\n\necho Date::toDateTime('20220921')-\u003eformat('Y-m-d')\necho Date::toDateTime('12.08.2022')-\u003eformat('Y-m-d')\n```\n\nThis will output\n\n```\n2022-09-21\n2022-08-12\n```\n\nTo convert a `DateTime` instance to Collmex format (ISO style):\n\n```php\nuse MarcusJaschen\\Collmex\\CollmexField\\Date;\n\necho Date::fromDateTime(new \\DateTime('2022-09-21T00:00:00', new \\DateTimeZone('Europe/Berlin')))\n```\n\nThis will output\n\n```\n20220921\n```\n\n## List of Supported Types\n\n- `ABO_GET`\n- `ACC_BAL`\n- `ACCBAL_GET`\n- `ACCDOC`\n- `ACCDOC_GET`\n- `ADDRESS_GROUPS_GET`\n- `API_NOTIFICATION`\n- `CMXADR`\n- `ADRGRP`\n- `BANK_STATEMENT_GET_FROM_BANK`\n- `BATCH_GET`\n- `BILL_OF_MATERIAL_GET`\n- `CMXABO`\n- `CMXADR`\n- `CMXBOM`\n- `CMXBTC`\n- `CMXDLV`\n- `CMXEPF`\n- `CMXINV`\n- `CMXKND`\n- `CMXLIF`\n- `CMXLRN`\n- `CMXMGD`\n- `CMXORD-2`\n- `CMXPOD`\n- `CMXPRD`\n- `CMXPRI`\n- `CMXPRI_CHANGE`\n- `CMXQTN`\n- `CMXSBI`\n- `CMXSTK`\n- `CMXUMS`\n- `CMXVAG`\n- `CUSTOMER_GET`\n- `DELIVERY_GET`\n- `EMPLOYEE`\n- `EMPLOYEE_GET`\n- `INVOICE_GET`\n- `INVOICE_PAYMENT`\n- `INVOICE_PAYMENT_GET`\n- `INVOICE_OUTPUT`\n- `INVOICE_OUTPUT_SET`\n- `MEMBER_GET`\n- `OPEN_ITEM`\n- `OPEN_ITEMS_GET`\n- `PAYMENT_CONFIRMATION`\n- `PRICE_GROUP`\n- `PRICE_GROUPS_GET`\n- `PRDGRP`\n- `PRODUCT_GET`\n- `PRODUCT_GROUPS_GET`\n- `PRODUCT_PRICE_GET`\n- `PRODUCTION_ORDER`\n- `PRODUCTION_ORDER_GET`\n- `PROJECT_STAFF`\n- `PROJECT_STAFF_GET`\n- `PURCHASE_ORDER_GET`\n- `SALES_ORDER_GET`\n- `SHIPMENT_CONFIRM`\n- `SHIPMENT_NOTIFICATION_SEND`\n- `SHIPMENT_ORDERS_GET`\n- `STOCK_AVAILABLE`\n- `STOCK_AVAILABLE_GET`\n- `STOCK_CHANGE`\n- `STOCK_CHANGE_GET`\n- `STOCK_GET`\n- `TRACKING_NUMBER`\n- `VENDOR_GET`\n- `VOUCHER`\n- `VOUCHER_GET`\n\n## Development\n\n### Run code checks\n\nTo run checks and tests, it's the easiest to use the provided Composer scripts:\n\n- lint PHP files for syntax errors: `composer ci:lint`\n- run static analysis with [Psalm] and report errors: `composer ci:psalm`\n- run unit tests with PHPUnit: `composer ci:tests`\n- check the code style with\n  [PHP_CodeSniffer]:\n  `composer ci:sniff`\n\nTo run all checks and tests at once, just use `composer ci`.\n\nOf course, it's possible to use the test runners directly, e.g. for PHPUnit:\n\n```shell\n./vendor/bin/phpunit\n```\n\nPsalm:\n\n```shell\n./vendor/bin/psalm\n```\n\n### Autoformat the code\n\nYou can use a Composer script to autoformat the code:\n\n```shell\ncomposer fix:php-cs\n```\n\n## Collmex API Documentation\n\n\u003chttps://www.collmex.de/cgi-bin/cgi.exe?1005,1,help,api\u003e\n\n[forceutf8]: https://github.com/neitanod/forceutf8\n\n[PHP_CodeSniffer]: https://github.com/squizlabs/PHP_CodeSniffer\n\n[Psalm]: https://github.com/vimeo/psalm\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjaschen%2Fcollmex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmjaschen%2Fcollmex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjaschen%2Fcollmex/lists"}