{"id":17323900,"url":"https://github.com/sanmai/shipandco-sdk","last_synced_at":"2025-10-26T22:32:06.554Z","repository":{"id":44161414,"uuid":"301259020","full_name":"sanmai/shipandco-sdk","owner":"sanmai","description":"Ship\u0026co API PHP SDK: Integrate with FedEx, DHL, Japan's Yamato and Sagawa shipping providers using this PHP library","archived":false,"fork":false,"pushed_at":"2025-01-12T05:44:17.000Z","size":138,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T05:24:14.341Z","etag":null,"topics":["carrier","fedex","php","php-library","registered-carriers","sagawa","sdk","ship","shipments","yamato","yupack"],"latest_commit_sha":null,"homepage":"https://developer.shipandco.com/en/","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/sanmai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":["sanmai"]}},"created_at":"2020-10-05T00:52:17.000Z","updated_at":"2025-01-12T05:44:20.000Z","dependencies_parsed_at":"2024-02-23T00:32:27.173Z","dependency_job_id":"a159c362-e591-4c9b-91cf-dff50ba5492f","html_url":"https://github.com/sanmai/shipandco-sdk","commit_stats":{"total_commits":35,"total_committers":2,"mean_commits":17.5,"dds":0.05714285714285716,"last_synced_commit":"ca33cd509ce72529a25c02e4d431c88f61718c2c"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanmai%2Fshipandco-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanmai%2Fshipandco-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanmai%2Fshipandco-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanmai%2Fshipandco-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sanmai","download_url":"https://codeload.github.com/sanmai/shipandco-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248553815,"owners_count":21123524,"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":["carrier","fedex","php","php-library","registered-carriers","sagawa","sdk","ship","shipments","yamato","yupack"],"created_at":"2024-10-15T14:09:27.074Z","updated_at":"2025-10-26T22:32:06.549Z","avatar_url":"https://github.com/sanmai.png","language":"PHP","funding_links":["https://github.com/sponsors/sanmai"],"categories":[],"sub_categories":[],"readme":"# Ship\u0026amp;co API integration SDK\n\n[![Latest Stable Version](https://poser.pugx.org/sanmai/shipandco-sdk/v/stable)](https://packagist.org/packages/sanmai/shipandco-sdk)\n[![Coverage Status](https://coveralls.io/repos/github/sanmai/shipandco-sdk/badge.svg?branch=main)](https://coveralls.io/github/sanmai/shipandco-sdk?branch=main)\n\nFeatures:\n\n- [ ] Shipments\n  - [x] [Create Shipment](#create-shipment)\n  - [ ] List Shipments\n  - [ ] Get Shipment\n  - [ ] Delete Shipment\n- [x] Rate\n  - [x] [List Rates](#list-rates)\n- [ ] Carrier\n  - [ ] Register Carrier\n  - [x] [List Carriers](#list-carriers)\n  - [ ] Update Carrier\n  - [ ] Delete Carrier\n- [ ] Tracking\n- [ ] Address\n  - [ ] Register Address\n  - [x] [List Addresses](#list-addresses)\n- [ ] Warehouse\n  - [ ] Register Warehouse\n  - [x] [List Warehouses](#list-warehouses)\n- [ ] Sub User\n  - [ ] Register Sub User\n  - [ ] List Sub User\n  - [ ] Get Sub User\n  - [ ] Refresh Sub User\n  - [ ] Delete Sub User\n\nThis library is far from offering a complete set of API methods, but it should do the most important bits.\n\n**Something is amiss?** [Let us know](https://github.com/sanmai/shipandco-sdk/issues/new/choose), or, even better, send a PR!\n\n[Ship\u0026amp;co API documentation](https://developer.shipandco.com/en/) for your reference. Please note this is _not_ in any way an official SDK of Ship\u0026co, therefore most likely they won't be able to answer any questions about this SDK.\n\n## Installation\n\n```bash\ncomposer require sanmai/shipandco-sdk\n```\n\nThis SDK requires at least PHP 8.2.\n\n## Overview\n\nMajor parts are:\n\n- Client. Client is the object you send all requests through.\n- Requests. There are several request objects for most requests the API offers. They follow a fluent interface paradigm, where if the original request has a certain property, a request here will have it too. More on this below.\n- Responses. After sending a request you'll have a response object, which could be an actual response, or an error response. All responses follow the same fluent paradigm.\n\n## Usage\n\nFirst, you need to acquire an access token [as outlined in the documentation](https://developer.shipandco.com/en/#t-auth).\n\nNext, instantiate a client using a convenient builder:\n\n```php\n$builder = new \\ShipAndCoSDK\\ClientBuilder();\n$builder-\u003esetToken($token);\n\n$client = $builder-\u003ebuild();\n``` \n\nThe builder has several more convenience methods to set timeouts and enable caching. Check with the source code.\n\n### Error handling\n\nError handling is built upon error responses. Exceptions are almost never thrown. If there's an exception, this has to be a truly exceptional situation, even a bug.\n\n```php\n$request = new \\ShipAndCoSDK\\Requests\\RatesRequest();\n\n// This requests requires several properties to be set, therefore we'll have an error here.\n$response = $client-\u003esendRatesRequest($request);\n\nif (\\count($response) \u003e 0) {\n    // Will not be printed because count() is zero here.\n    echo 'Rates received: ', \\count($response), \"\\n\";\n}\n\nif ($response-\u003ehasErrors()) {\n    // Check for exact errors\n    foreach ($response-\u003egetMessages() as $message) {\n        if ($message-\u003egetErrorCode() !== '') {\n            // That's the error:\n            echo \"{$message-\u003egetErrorCode()}: {$message-\u003egetMessage()}\\n\";\n        }\n    }\n\n    /** @var \\ShipAndCoSDK\\Responses\\Bad\\ErrorResponse $response */\n    \n    // To get more specific error details use response-specific fields. E.g.:\n    foreach ($response-\u003edetails as $detail) {\n        echo \"Error code: {$detail-\u003ecode}\\n\\tMessage: {$detail-\u003emessage}\\n\\tField: {$detail-\u003efield}\\n\";\n    }\n}\n```\n\n### Requests\n\nFor every implemented request [there's a runnable example](examples). E.g. running this:\n\n```bash\nexport SHIPANDCO_ACCESS_TOKEN=... (your token)\nphp examples/030_CarriersRequest.php\n```\n\n...Will output your registered carriers.\n\nExamples come with a debugging output enabled so that you can experiment freely.\n\nObviously, to run examples you'll need to have the library checked out:\n\n```bash\ngit clone https://github.com/sanmai/shipandco-sdk.git\ncd shipandco-sdk\ncomposer install\n```\n\n#### List Carriers\n\n```php\n$request = new \\ShipAndCoSDK\\Requests\\CarriersRequest();\n\n$response = $client-\u003esendCarriersRequest($request);\n\n\\var_dump(\\count($response)); // Should print the number of configured carriers\n\nforeach ($response as $value) {\n    echo \"{$value-\u003eid}\\t{$value-\u003etype}\\t{$value-\u003estate}\\t{$value-\u003ecreated_at-\u003eformat('Y-m-d')}\\n\";\n    \n    foreach ($value-\u003ecredentials as $key =\u003e $value) {\n        echo \"\\t$key =\\t$value\\n\";\n    }\n}\n```\n\n#### List Addresses\n\n```php\n$request = new \\ShipAndCoSDK\\Requests\\AddressesRequest();\n\n$response = $client-\u003esendAddressesRequest($request);\n\n\\var_dump(\\count($response)); // Should print the number of addresses returned\n\nforeach ($response as $value) {\n    echo \"{$value-\u003eid}\\t{$value-\u003ecreated_at-\u003eformat('Y-m-d')}\\n\";\n    \n    foreach ($value-\u003eaddress as $key =\u003e $value) {\n        echo \"\\t$key =\\t$value\\n\";\n    }\n}\n```\n\n#### List Warehouses\n\n```php\n$request = new \\ShipAndCoSDK\\Requests\\WarehousesRequest();\n\n$response = $client-\u003esendWarehousesRequest($request);\n\n\\var_dump(\\count($response)); // Should print the number of warehouses returned\n\nforeach ($response as $value) {\n    echo \"{$value-\u003eid}\\t{$value-\u003ecreated_at-\u003eformat('Y-m-d')}\\t{$value-\u003ecompany}\\n\";\n    \n    foreach ($value-\u003eaddress as $key =\u003e $value) {\n        echo \"\\t$key =\\t$value\\n\";\n    }\n}\n```\n\n#### List Rates\n\n```php\n$request = new \\ShipAndCoSDK\\Requests\\RatesRequest();\n\n$request-\u003efrom_address-\u003ecountry = 'JP';\n$request-\u003efrom_address-\u003efull_name = 'Yamada Taro';\n$request-\u003efrom_address-\u003ecompany = 'World Company';\n$request-\u003efrom_address-\u003eemail = 'ytaro@example.com';\n$request-\u003efrom_address-\u003ephone = '08012341234';\n$request-\u003efrom_address-\u003ecountry = 'JP';\n$request-\u003efrom_address-\u003eaddress1 = 'OSAKAFU';\n$request-\u003efrom_address-\u003eaddress2 = 'OTECHO';\n$request-\u003efrom_address-\u003eprovince = 'OSAKA';\n$request-\u003efrom_address-\u003ezip = '5670883';\n$request-\u003efrom_address-\u003ecity = 'IBARAKI SHI';\n\n$request-\u003eto_address-\u003efull_name = 'John Doe';\n$request-\u003eto_address-\u003ecompany = 'ACME';\n$request-\u003eto_address-\u003eemail = 'john@example.net';\n$request-\u003eto_address-\u003ephone = '0901231234';\n$request-\u003eto_address-\u003ecountry = 'PT';\n$request-\u003eto_address-\u003eaddress1 = 'Rua Maria Matos, 32';\n$request-\u003eto_address-\u003eaddress2 = '';\n$request-\u003eto_address-\u003eprovince = 'SETUBAL';\n$request-\u003eto_address-\u003ezip = '2820-344';\n$request-\u003eto_address-\u003ecity = 'CHARNECA DA CAPARICA';\n\n$product = $request-\u003eaddProduct();\n$product-\u003equantity = 1;\n$product-\u003ename = 'Example';\n$product-\u003eprice = 1000;\n\n$parcel = $request-\u003eaddParcel();\n$parcel-\u003eweight = 200;\n$parcel-\u003ewidth = 10;\n$parcel-\u003eheight = 10;\n$parcel-\u003edepth = 10;\n\n$request-\u003ecustoms-\u003eduty_paid = false;\n$request-\u003ecustoms-\u003econtent_type = 'MERCHANDISE';\n\n$request-\u003esetup-\u003edate = new DateTime('+1 week');\n\n$response = $client-\u003esendRatesRequest($request);\n\n\\var_dump(\\count($response));\n\nforeach ($response as $rate) {\n    echo \"{$rate-\u003ecarrier}\\t{$rate-\u003eservice}\\t{$rate-\u003eprice} {$rate-\u003ecurrency}\\n\";\n\n    foreach ($rate-\u003esurcharges as $surcharge) {\n        echo \"\\t{$surcharge-\u003etype}\\t{$surcharge-\u003eprice}\\n\";\n    }\n}\n```\n\n#### Create Shipment\n\nAs far as shipments go, it's important to understand that requests for domestic shipments over Japan (Sagawa, Yamato, YuPack) are a bit different from an International shipments:\n\n- For domestic shipments addresses (to and from) should be in Japanese. The opposite is true for International shipments.\n- No city field is needed for domestic shipments (city goes to `address_1`).\n- No need for most details about product: on the contrary, for International shipments, details about products are used for customs clearance purpose.\n- For domestic shipments, if it's not a cash on delivery shipment, product name only should work (just to show on the label whats inside the box).\n\nThis SDK poses no restrictions on the number of fields specified in a request (other than that they should exist), thus it is a user responsibility (yours) to set correct fields for each type of request.\n\n```php\n$request = new \\ShipAndCoSDK\\Requests\\CreateShipmentRequest();\n\n$request-\u003eto_address-\u003ecountry = 'JP';\n$request-\u003eto_address-\u003efull_name = 'TEST TARO';\n$request-\u003eto_address-\u003ephone = '1111111111';\n$request-\u003eto_address-\u003ecountry = 'JP';\n$request-\u003eto_address-\u003eaddress1 = '京都市中京区八百屋町117';\n$request-\u003eto_address-\u003ezip = '604-8072';\n$request-\u003eto_address-\u003ecity = '京都府';\n\n$request-\u003efrom_address-\u003efull_name = 'テスト';\n$request-\u003efrom_address-\u003ephone = '08012341234';\n$request-\u003efrom_address-\u003ecountry = 'JP';\n$request-\u003efrom_address-\u003eaddress1 = 'OSAKAFU';\n$request-\u003efrom_address-\u003eprovince = 'OSAKA';\n$request-\u003efrom_address-\u003ezip = '1234567';\n$request-\u003efrom_address-\u003ecity = 'IBARAKI SHI';\n\n$product = $request-\u003eaddProduct();\n$product-\u003ename = 'Blue Basketball';\n$product-\u003equantity = 2;\n$product-\u003eprice = 4850;\n$product-\u003eorigin_country = 'JP';\n\n$product = $request-\u003eaddProduct();\n$product-\u003ename = 'Orange Basketball';\n$product-\u003equantity = 1;\n$product-\u003eprice = 7850;\n$product-\u003eorigin_country = 'JP';\n\n$parcel = $request-\u003eaddParcel();\n$parcel-\u003eamount = 1; // That's the default.\n$parcel-\u003eweight = 2000;\n$parcel-\u003ewidth = 10;\n$parcel-\u003eheight = 10;\n$parcel-\u003edepth = 10;\n// $parcel-\u003epackage = 'fedex_envelope';\n\n$request-\u003ecustoms-\u003eduty_paid = false;\n$request-\u003ecustoms-\u003econtent_type = 'MERCHANDISE';\n\n$request-\u003esetup-\u003ecarrier = 'sagawa';\n$request-\u003esetup-\u003eservice = 'sagawa_regular';\n$request-\u003esetup-\u003ecurrency = 'JPY';\n$request-\u003esetup-\u003eshipment_date = new DateTime('+1 day');\n$request-\u003esetup-\u003edate = new DateTime('+2 day');\n$request-\u003esetup-\u003etime = '16-18';\n$request-\u003esetup-\u003einsurance = 0;\n$request-\u003esetup-\u003eref_number = '';\n$request-\u003esetup-\u003edelivery_note = '';\n$request-\u003esetup-\u003esignature = false;\n$request-\u003esetup-\u003ecare-\u003efragile = false;\n$request-\u003esetup-\u003ecare-\u003eside_up = false;\n$request-\u003esetup-\u003ecare-\u003evaluable_goods = false;\n$request-\u003esetup-\u003epack_size = '0';\n$request-\u003esetup-\u003epack_amount = 3;\n$request-\u003esetup-\u003ecash_on_delivery-\u003eamount = 1000;\n$request-\u003esetup-\u003ecash_on_delivery-\u003etax = 100;\n$request-\u003esetup-\u003ereturn_label = false;\n$request-\u003esetup-\u003eprint_start_location = 1;\n$request-\u003esetup-\u003etest = true;\n\n$response = $client-\u003esendCreateShipmentRequest($request);\n\nif ($response-\u003ehasErrors()) {\n    // Check for exact errors\n    foreach ($response-\u003egetMessages() as $message) {\n        if ($message-\u003egetErrorCode() !== '') {\n            // That's the error\n            echo \"{$message-\u003egetErrorCode()}: {$message-\u003egetMessage()}\\n\";\n        }\n    }\n\n    return; // This is a failure.\n}\n\n/** @var $response \\ShipAndCoSDK\\Responses\\ShipmentResponse */\necho \"{$response-\u003eid}\\t{$response-\u003estate}\\n\";\n\necho \"Shipping Label: {$response-\u003edelivery-\u003elabel}\\n\";\n\nforeach ($response-\u003edelivery-\u003etracking_numbers as $trackingNumber) {\n    echo \"Tracking Number: {$trackingNumber}\\n\";\n}\n```\n\nTo safeguard you against unexpected billing charges, shipment requests are [using the test environment](https://developer.shipandco.com/en/#t-ship_post) _by default_ (thus creating dummy labels). Make sure to set `test` to `false` in `setup` section to receive live labels.\n\nJust like so:\n\n```php\n$request-\u003esetup-\u003etest = false;\n```\n\n## License\n\nThis project is licensed [under the terms of the MIT license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanmai%2Fshipandco-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsanmai%2Fshipandco-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanmai%2Fshipandco-sdk/lists"}