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:  * Credit memo API
 29:  *
 30:  * @category   Mage
 31:  * @package    Mage_Sales
 32:  * @author     Magento Core Team <core@magentocommerce.com>
 33:  */
 34: class Mage_Sales_Model_Order_Creditmemo_Api extends Mage_Sales_Model_Api_Resource
 35: {
 36: 
 37:     /**
 38:      * Initialize attributes mapping
 39:      */
 40:     public function __construct()
 41:     {
 42:         $this->_attributesMap = array(
 43:             'creditmemo' => array('creditmemo_id' => 'entity_id'),
 44:             'creditmemo_item' => array('item_id' => 'entity_id'),
 45:             'creditmemo_comment' => array('comment_id' => 'entity_id')
 46:         );
 47:     }
 48: 
 49:     /**
 50:      * Retrieve credit memos list. Filtration could be applied
 51:      *
 52:      * @param null|object|array $filters
 53:      * @return array
 54:      */
 55:     public function items($filters = null)
 56:     {
 57:         $creditmemos = array();
 58:         /** @var $apiHelper Mage_Api_Helper_Data */
 59:         $apiHelper = Mage::helper('api');
 60:         $filters = $apiHelper->parseFilters($filters, $this->_attributesMap['creditmemo']);
 61:         /** @var $creditmemoModel Mage_Sales_Model_Order_Creditmemo */
 62:         $creditmemoModel = Mage::getModel('sales/order_creditmemo');
 63:         try {
 64:             $creditMemoCollection = $creditmemoModel->getFilteredCollectionItems($filters);
 65:             foreach ($creditMemoCollection as $creditmemo) {
 66:                 $creditmemos[] = $this->_getAttributes($creditmemo, 'creditmemo');
 67:             }
 68:         } catch (Exception $e) {
 69:             $this->_fault('invalid_filter', $e->getMessage());
 70:         }
 71:         return $creditmemos;
 72:     }
 73: 
 74:     /**
 75:      * Make filter of appropriate format for list method
 76:      *
 77:      * @deprecated since 1.7.0.1
 78:      * @param array|null $filter
 79:      * @return array|null
 80:      */
 81:     protected function _prepareListFilter($filter = null)
 82:     {
 83:         // prepare filter, map field creditmemo_id to entity_id
 84:         if (is_array($filter)) {
 85:             foreach ($filter as $field => $value) {
 86:                 if (isset($this->_attributesMap['creditmemo'][$field])) {
 87:                     $filter[$this->_attributesMap['creditmemo'][$field]] = $value;
 88:                     unset($filter[$field]);
 89:                 }
 90:             }
 91:         }
 92:         return $filter;
 93:     }
 94: 
 95:     /**
 96:      * Retrieve credit memo information
 97:      *
 98:      * @param string $creditmemoIncrementId
 99:      * @return array
100:      */
101:     public function info($creditmemoIncrementId)
102:     {
103:         $creditmemo = $this->_getCreditmemo($creditmemoIncrementId);
104:         // get credit memo attributes with entity_id' => 'creditmemo_id' mapping
105:         $result = $this->_getAttributes($creditmemo, 'creditmemo');
106:         $result['order_increment_id'] = $creditmemo->getOrder()->load($creditmemo->getOrderId())->getIncrementId();
107:         // items refunded
108:         $result['items'] = array();
109:         foreach ($creditmemo->getAllItems() as $item) {
110:             $result['items'][] = $this->_getAttributes($item, 'creditmemo_item');
111:         }
112:         // credit memo comments
113:         $result['comments'] = array();
114:         foreach ($creditmemo->getCommentsCollection() as $comment) {
115:             $result['comments'][] = $this->_getAttributes($comment, 'creditmemo_comment');
116:         }
117: 
118:         return $result;
119:     }
120: 
121:     /**
122:      * Create new credit memo for order
123:      *
124:      * @param string $creditmemoIncrementId
125:      * @param array $creditmemoData array('qtys' => array('sku1' => qty1, ... , 'skuN' => qtyN),
126:      *      'shipping_amount' => value, 'adjustment_positive' => value, 'adjustment_negative' => value)
127:      * @param string|null $comment
128:      * @param bool $notifyCustomer
129:      * @param bool $includeComment
130:      * @param string $refundToStoreCreditAmount
131:      * @return string $creditmemoIncrementId
132:      */
133:     public function create($creditmemoIncrementId, $creditmemoData = null, $comment = null, $notifyCustomer = false,
134:         $includeComment = false, $refundToStoreCreditAmount = null)
135:     {
136:         /** @var $order Mage_Sales_Model_Order */
137:         $order = Mage::getModel('sales/order')->load($creditmemoIncrementId, 'increment_id');
138:         if (!$order->getId()) {
139:             $this->_fault('order_not_exists');
140:         }
141:         if (!$order->canCreditmemo()) {
142:             $this->_fault('cannot_create_creditmemo');
143:         }
144:         $creditmemoData = $this->_prepareCreateData($creditmemoData);
145: 
146:         /** @var $service Mage_Sales_Model_Service_Order */
147:         $service = Mage::getModel('sales/service_order', $order);
148:         /** @var $creditmemo Mage_Sales_Model_Order_Creditmemo */
149:         $creditmemo = $service->prepareCreditmemo($creditmemoData);
150: 
151:         // refund to Store Credit
152:         if ($refundToStoreCreditAmount) {
153:             // check if refund to Store Credit is available
154:             if ($order->getCustomerIsGuest()) {
155:                 $this->_fault('cannot_refund_to_storecredit');
156:             }
157:             $refundToStoreCreditAmount = max(
158:                 0,
159:                 min($creditmemo->getBaseCustomerBalanceReturnMax(), $refundToStoreCreditAmount)
160:             );
161:             if ($refundToStoreCreditAmount) {
162:                 $refundToStoreCreditAmount = $creditmemo->getStore()->roundPrice($refundToStoreCreditAmount);
163:                 $creditmemo->setBaseCustomerBalanceTotalRefunded($refundToStoreCreditAmount);
164:                 $refundToStoreCreditAmount = $creditmemo->getStore()->roundPrice(
165:                     $refundToStoreCreditAmount*$order->getStoreToOrderRate()
166:                 );
167:                 // this field can be used by customer balance observer
168:                 $creditmemo->setBsCustomerBalTotalRefunded($refundToStoreCreditAmount);
169:                 // setting flag to make actual refund to customer balance after credit memo save
170:                 $creditmemo->setCustomerBalanceRefundFlag(true);
171:             }
172:         }
173:         $creditmemo->setPaymentRefundDisallowed(true)->register();
174:         // add comment to creditmemo
175:         if (!empty($comment)) {
176:             $creditmemo->addComment($comment, $notifyCustomer);
177:         }
178:         try {
179:             Mage::getModel('core/resource_transaction')
180:                 ->addObject($creditmemo)
181:                 ->addObject($order)
182:                 ->save();
183:             // send email notification
184:             $creditmemo->sendEmail($notifyCustomer, ($includeComment ? $comment : ''));
185:         } catch (Mage_Core_Exception $e) {
186:             $this->_fault('data_invalid', $e->getMessage());
187:         }
188:         return $creditmemo->getIncrementId();
189:     }
190: 
191:     /**
192:      * Add comment to credit memo
193:      *
194:      * @param string $creditmemoIncrementId
195:      * @param string $comment
196:      * @param boolean $notifyCustomer
197:      * @param boolean $includeComment
198:      * @return boolean
199:      */
200:     public function addComment($creditmemoIncrementId, $comment, $notifyCustomer = false, $includeComment = false)
201:     {
202:         $creditmemo = $this->_getCreditmemo($creditmemoIncrementId);
203:         try {
204:             $creditmemo->addComment($comment, $notifyCustomer)->save();
205:             $creditmemo->sendUpdateEmail($notifyCustomer, ($includeComment ? $comment : ''));
206:         } catch (Mage_Core_Exception $e) {
207:             $this->_fault('data_invalid', $e->getMessage());
208:         }
209: 
210:         return true;
211:     }
212: 
213:     /**
214:      * Cancel credit memo
215:      *
216:      * @param string $creditmemoIncrementId
217:      * @return boolean
218:      */
219:     public function cancel($creditmemoIncrementId)
220:     {
221:         $creditmemo = $this->_getCreditmemo($creditmemoIncrementId);
222: 
223:         if (!$creditmemo->canCancel()) {
224:             $this->_fault('status_not_changed', Mage::helper('sales')->__('Credit memo cannot be canceled.'));
225:         }
226:         try {
227:             $creditmemo->cancel()->save();
228:         } catch (Exception $e) {
229:             $this->_fault('status_not_changed', Mage::helper('sales')->__('Credit memo canceling problem.'));
230:         }
231: 
232:         return true;
233:     }
234: 
235:     /**
236:      * Hook method, could be replaced in derived classes
237:      *
238:      * @param  array $data
239:      * @return array
240:      */
241:     protected function _prepareCreateData($data)
242:     {
243:         $data = isset($data) ? $data : array();
244: 
245:         if (isset($data['qtys']) && count($data['qtys'])) {
246:             $qtysArray = array();
247:             foreach ($data['qtys'] as $qKey => $qVal) {
248:                 // Save backward compatibility
249:                 if (is_array($qVal)) {
250:                     if (isset($qVal['order_item_id']) && isset($qVal['qty'])) {
251:                         $qtysArray[$qVal['order_item_id']] = $qVal['qty'];
252:                     }
253:                 } else {
254:                     $qtysArray[$qKey] = $qVal;
255:                 }
256:             }
257:             $data['qtys'] = $qtysArray;
258:         }
259:         return $data;
260:     }
261: 
262:     /**
263:      * Load CreditMemo by IncrementId
264:      *
265:      * @param mixed $incrementId
266:      * @return Mage_Core_Model_Abstract|Mage_Sales_Model_Order_Creditmemo
267:      */
268:     protected function _getCreditmemo($incrementId)
269:     {
270:         /** @var $creditmemo Mage_Sales_Model_Order_Creditmemo */
271:         $creditmemo = Mage::getModel('sales/order_creditmemo')->load($incrementId, 'increment_id');
272:         if (!$creditmemo->getId()) {
273:             $this->_fault('not_exists');
274:         }
275:         return $creditmemo;
276:     }
277: 
278: }
279: