1: <?php
  2: /**
  3:  * Magento
  4:  *
  5:  * NOTICE OF LICENSE
  6:  *
  7:  * This source file is subject to the Open Software License (OSL 3.0)
  8:  * that is bundled with this package in the file LICENSE.txt.
  9:  * It is also available through the world-wide-web at this URL:
 10:  * http://opensource.org/licenses/osl-3.0.php
 11:  * If you did not receive a copy of the license and are unable to
 12:  * obtain it through the world-wide-web, please send an email
 13:  * to license@magentocommerce.com so we can send you a copy immediately.
 14:  *
 15:  * DISCLAIMER
 16:  *
 17:  * Do not edit or add to this file if you wish to upgrade Magento to newer
 18:  * versions in the future. If you wish to customize Magento for your
 19:  * needs please refer to http://www.magentocommerce.com for more information.
 20:  *
 21:  * @category    Mage
 22:  * @package     Mage_Sales
 23:  * @copyright   Copyright (c) 2012 Magento Inc. (http://www.magentocommerce.com)
 24:  * @license     http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 25:  */
 26: 
 27: /**
 28:  * Sales order shippment API
 29:  *
 30:  * @category   Mage
 31:  * @package    Mage_Sales
 32:  * @author     Magento Core Team <core@magentocommerce.com>
 33:  */
 34: class Mage_Sales_Model_Order_Shipment_Api extends Mage_Sales_Model_Api_Resource
 35: {
 36:     public function __construct()
 37:     {
 38:         $this->_attributesMap['shipment'] = array('shipment_id' => 'entity_id');
 39: 
 40:         $this->_attributesMap['shipment_item'] = array('item_id'    => 'entity_id');
 41: 
 42:         $this->_attributesMap['shipment_comment'] = array('comment_id' => 'entity_id');
 43: 
 44:         $this->_attributesMap['shipment_track'] = array('track_id'   => 'entity_id');
 45:     }
 46: 
 47:     /**
 48:      * Retrieve shipments by filters
 49:      *
 50:      * @param null|object|array $filters
 51:      * @return array
 52:      */
 53:     public function items($filters = null)
 54:     {
 55:         $shipments = array();
 56:         //TODO: add full name logic
 57:         $shipmentCollection = Mage::getResourceModel('sales/order_shipment_collection')
 58:             ->addAttributeToSelect('increment_id')
 59:             ->addAttributeToSelect('created_at')
 60:             ->addAttributeToSelect('total_qty')
 61:             ->joinAttribute('shipping_firstname', 'order_address/firstname', 'shipping_address_id', null, 'left')
 62:             ->joinAttribute('shipping_lastname', 'order_address/lastname', 'shipping_address_id', null, 'left')
 63:             ->joinAttribute('order_increment_id', 'order/increment_id', 'order_id', null, 'left')
 64:             ->joinAttribute('order_created_at', 'order/created_at', 'order_id', null, 'left');
 65: 
 66:         /** @var $apiHelper Mage_Api_Helper_Data */
 67:         $apiHelper = Mage::helper('api');
 68:         try {
 69:             $filters = $apiHelper->parseFilters($filters, $this->_attributesMap['shipment']);
 70:             foreach ($filters as $field => $value) {
 71:                 $shipmentCollection->addFieldToFilter($field, $value);
 72:             }
 73:         } catch (Mage_Core_Exception $e) {
 74:             $this->_fault('filters_invalid', $e->getMessage());
 75:         }
 76:         foreach ($shipmentCollection as $shipment) {
 77:             $shipments[] = $this->_getAttributes($shipment, 'shipment');
 78:         }
 79: 
 80:         return $shipments;
 81:     }
 82: 
 83:     /**
 84:      * Retrieve shipment information
 85:      *
 86:      * @param string $shipmentIncrementId
 87:      * @return array
 88:      */
 89:     public function info($shipmentIncrementId)
 90:     {
 91:         $shipment = Mage::getModel('sales/order_shipment')->loadByIncrementId($shipmentIncrementId);
 92: 
 93:         /* @var $shipment Mage_Sales_Model_Order_Shipment */
 94: 
 95:         if (!$shipment->getId()) {
 96:             $this->_fault('not_exists');
 97:         }
 98: 
 99:         $result = $this->_getAttributes($shipment, 'shipment');
100: 
101:         $result['items'] = array();
102:         foreach ($shipment->getAllItems() as $item) {
103:             $result['items'][] = $this->_getAttributes($item, 'shipment_item');
104:         }
105: 
106:         $result['tracks'] = array();
107:         foreach ($shipment->getAllTracks() as $track) {
108:             $result['tracks'][] = $this->_getAttributes($track, 'shipment_track');
109:         }
110: 
111:         $result['comments'] = array();
112:         foreach ($shipment->getCommentsCollection() as $comment) {
113:             $result['comments'][] = $this->_getAttributes($comment, 'shipment_comment');
114:         }
115: 
116:         return $result;
117:     }
118: 
119:     /**
120:      * Create new shipment for order
121:      *
122:      * @param string $orderIncrementId
123:      * @param array $itemsQty
124:      * @param string $comment
125:      * @param booleam $email
126:      * @param boolean $includeComment
127:      * @return string
128:      */
129:     public function create($orderIncrementId, $itemsQty = array(), $comment = null, $email = false,
130:         $includeComment = false
131:     ) {
132:         $order = Mage::getModel('sales/order')->loadByIncrementId($orderIncrementId);
133: 
134:         /**
135:           * Check order existing
136:           */
137:         if (!$order->getId()) {
138:              $this->_fault('order_not_exists');
139:         }
140: 
141:         /**
142:          * Check shipment create availability
143:          */
144:         if (!$order->canShip()) {
145:              $this->_fault('data_invalid', Mage::helper('sales')->__('Cannot do shipment for order.'));
146:         }
147: 
148:          /* @var $shipment Mage_Sales_Model_Order_Shipment */
149:         $shipment = $order->prepareShipment($itemsQty);
150:         if ($shipment) {
151:             $shipment->register();
152:             $shipment->addComment($comment, $email && $includeComment);
153:             if ($email) {
154:                 $shipment->setEmailSent(true);
155:             }
156:             $shipment->getOrder()->setIsInProcess(true);
157:             try {
158:                 $transactionSave = Mage::getModel('core/resource_transaction')
159:                     ->addObject($shipment)
160:                     ->addObject($shipment->getOrder())
161:                     ->save();
162:                 $shipment->sendEmail($email, ($includeComment ? $comment : ''));
163:             } catch (Mage_Core_Exception $e) {
164:                 $this->_fault('data_invalid', $e->getMessage());
165:             }
166:             return $shipment->getIncrementId();
167:         }
168:         return null;
169:     }
170: 
171:     /**
172:      * Add tracking number to order
173:      *
174:      * @param string $shipmentIncrementId
175:      * @param string $carrier
176:      * @param string $title
177:      * @param string $trackNumber
178:      * @return int
179:      */
180:     public function addTrack($shipmentIncrementId, $carrier, $title, $trackNumber)
181:     {
182:         $shipment = Mage::getModel('sales/order_shipment')->loadByIncrementId($shipmentIncrementId);
183: 
184:         /* @var $shipment Mage_Sales_Model_Order_Shipment */
185: 
186:         if (!$shipment->getId()) {
187:             $this->_fault('not_exists');
188:         }
189: 
190:         $carriers = $this->_getCarriers($shipment);
191: 
192:         if (!isset($carriers[$carrier])) {
193:             $this->_fault('data_invalid', Mage::helper('sales')->__('Invalid carrier specified.'));
194:         }
195: 
196:         $track = Mage::getModel('sales/order_shipment_track')
197:                     ->setNumber($trackNumber)
198:                     ->setCarrierCode($carrier)
199:                     ->setTitle($title);
200: 
201:         $shipment->addTrack($track);
202: 
203:         try {
204:             $shipment->save();
205:             $track->save();
206:         } catch (Mage_Core_Exception $e) {
207:             $this->_fault('data_invalid', $e->getMessage());
208:         }
209: 
210:         return $track->getId();
211:     }
212: 
213:     /**
214:      * Remove tracking number
215:      *
216:      * @param string $shipmentIncrementId
217:      * @param int $trackId
218:      * @return boolean
219:      */
220:     public function removeTrack($shipmentIncrementId, $trackId)
221:     {
222:         $shipment = Mage::getModel('sales/order_shipment')->loadByIncrementId($shipmentIncrementId);
223: 
224:         /* @var $shipment Mage_Sales_Model_Order_Shipment */
225: 
226:         if (!$shipment->getId()) {
227:             $this->_fault('not_exists');
228:         }
229: 
230:         if(!$track = $shipment->getTrackById($trackId)) {
231:             $this->_fault('track_not_exists');
232:         }
233: 
234:         try {
235:             $track->delete();
236:         } catch (Mage_Core_Exception $e) {
237:             $this->_fault('track_not_deleted', $e->getMessage());
238:         }
239: 
240:         return true;
241:     }
242: 
243:     /**
244:      * Send email with shipment data to customer
245:      *
246:      * @param string $shipmentIncrementId
247:      * @param string $comment
248:      * @return bool
249:      */
250:     public function sendInfo($shipmentIncrementId, $comment = '')
251:     {
252:         /* @var $shipment Mage_Sales_Model_Order_Shipment */
253:         $shipment = Mage::getModel('sales/order_shipment')->loadByIncrementId($shipmentIncrementId);
254: 
255:         if (!$shipment->getId()) {
256:             $this->_fault('not_exists');
257:         }
258: 
259:         try {
260:             $shipment->sendEmail(true, $comment)
261:                 ->setEmailSent(true)
262:                 ->save();
263:             $historyItem = Mage::getResourceModel('sales/order_status_history_collection')
264:                 ->getUnnotifiedForInstance($shipment, Mage_Sales_Model_Order_Shipment::HISTORY_ENTITY_NAME);
265:             if ($historyItem) {
266:                 $historyItem->setIsCustomerNotified(1);
267:                 $historyItem->save();
268:             }
269:         } catch (Mage_Core_Exception $e) {
270:             $this->_fault('data_invalid', $e->getMessage());
271:         }
272: 
273:         return true;
274:     }
275: 
276:     /**
277:      * Retrieve tracking number info
278:      *
279:      * @param string $shipmentIncrementId
280:      * @param int $trackId
281:      * @return mixed
282:      */
283:     public function infoTrack($shipmentIncrementId, $trackId)
284:     {
285:          $shipment = Mage::getModel('sales/order_shipment')->loadByIncrementId($shipmentIncrementId);
286: 
287:         /* @var $shipment Mage_Sales_Model_Order_Shipment */
288: 
289:         if (!$shipment->getId()) {
290:             $this->_fault('not_exists');
291:         }
292: 
293:         if(!$track = $shipment->getTrackById($trackId)) {
294:             $this->_fault('track_not_exists');
295:         }
296: 
297:         /* @var $track Mage_Sales_Model_Order_Shipment_Track */
298:         $info = $track->getNumberDetail();
299: 
300:         if (is_object($info)) {
301:             $info = $info->toArray();
302:         }
303: 
304:         return $info;
305:     }
306: 
307:     /**
308:      * Add comment to shipment
309:      *
310:      * @param string $shipmentIncrementId
311:      * @param string $comment
312:      * @param boolean $email
313:      * @param boolean $includeInEmail
314:      * @return boolean
315:      */
316:     public function addComment($shipmentIncrementId, $comment, $email = false, $includeInEmail = false)
317:     {
318:         $shipment = Mage::getModel('sales/order_shipment')->loadByIncrementId($shipmentIncrementId);
319: 
320:         /* @var $shipment Mage_Sales_Model_Order_Shipment */
321: 
322:         if (!$shipment->getId()) {
323:             $this->_fault('not_exists');
324:         }
325: 
326: 
327:         try {
328:             $shipment->addComment($comment, $email);
329:             $shipment->sendUpdateEmail($email, ($includeInEmail ? $comment : ''));
330:             $shipment->save();
331:         } catch (Mage_Core_Exception $e) {
332:             $this->_fault('data_invalid', $e->getMessage());
333:         }
334: 
335:         return true;
336:     }
337: 
338:     /**
339:      * Retrieve allowed shipping carriers for specified order
340:      *
341:      * @param string $orderIncrementId
342:      * @return array
343:      */
344:     public function getCarriers($orderIncrementId)
345:     {
346:         $order = Mage::getModel('sales/order')->loadByIncrementId($orderIncrementId);
347: 
348:         /**
349:           * Check order existing
350:           */
351:         if (!$order->getId()) {
352:             $this->_fault('order_not_exists');
353:         }
354: 
355:         return $this->_getCarriers($order);
356:     }
357: 
358:     /**
359:      * Retrieve shipping carriers for specified order
360:      *
361:      * @param Mage_Eav_Model_Entity_Abstract $object
362:      * @return array
363:      */
364:     protected function _getCarriers($object)
365:     {
366:         $carriers = array();
367:         $carrierInstances = Mage::getSingleton('shipping/config')->getAllCarriers(
368:             $object->getStoreId()
369:         );
370: 
371:         $carriers['custom'] = Mage::helper('sales')->__('Custom Value');
372:         foreach ($carrierInstances as $code => $carrier) {
373:             if ($carrier->isTrackingAvailable()) {
374:                 $carriers[$code] = $carrier->getConfigData('title');
375:             }
376:         }
377: 
378:         return $carriers;
379:     }
380: 
381: } // Class Mage_Sales_Model_Order_Shipment_Api End
382: