api/v3/Order.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * This api exposes CiviCRM Order objects, an abstract entity
  14  * comprised of contributions and related line items.
  15  *
  16  * @package CiviCRM_APIv3
  17  */
  18
  19 /**
  20  * Retrieve a set of Order.
  21  *
  22  * @param array $params
  23  *  Input parameters.
  24  *
  25  * @return array
  26  *   Array of Order, if error an array with an error id and error message
  27  * @throws \CiviCRM_API3_Exception
  28  */
  29 function civicrm_api3_order_get(array $params): array {
  30   $contributions = [];
  31   $params['api.line_item.get'] = ['qty' => ['<>' => 0]];
  32   $isSequential = FALSE;
  33   if (!empty($params['sequential'])) {
  34     $params['sequential'] = 0;
  35     $isSequential = TRUE;
  36   }
  37   $result = civicrm_api3('Contribution', 'get', $params);
  38   if (!empty($result['values'])) {
  39     foreach ($result['values'] as $key => $contribution) {
  40       $contributions[$key] = $contribution;
  41       $contributions[$key]['line_items'] = $contribution['api.line_item.get']['values'];
  42       unset($contributions[$key]['api.line_item.get']);
  43     }
  44   }
  45   $params['sequential'] = $isSequential;
  46   return civicrm_api3_create_success($contributions, $params, 'Order', 'get');
  47 }
  48
  49 /**
  50  * Adjust Metadata for Get action.
  51  *
  52  * The metadata is used for setting defaults, documentation & validation.
  53  *
  54  * @param array $params
  55  *   Array of parameters determined by getfields.
  56  */
  57 function _civicrm_api3_order_get_spec(array &$params) {
  58   $params['id']['api.aliases'] = ['order_id'];
  59   $params['id']['title'] = ts('Contribution / Order ID');
  60 }
  61
  62 /**
  63  * Add or update a Order.
  64  *
  65  * @param array $params
  66  *   Input parameters.
  67  *
  68  * @return array
  69  *   Api result array
  70  *
  71  * @throws \CiviCRM_API3_Exception
  72  * @throws API_Exception
  73  */
  74 function civicrm_api3_order_create(array $params): array {
  75   civicrm_api3_verify_one_mandatory($params, NULL, ['line_items', 'total_amount']);
  76   if (empty($params['skipCleanMoney'])) {
  77     // We have to do this for v3 api - sadly. For v4 it will be no more.
  78     foreach (['total_amount', 'net_amount', 'fee_amount', 'non_deductible_amount'] as $field) {
  79       if (isset($params[$field])) {
  80         $params[$field] = CRM_Utils_Rule::cleanMoney($params[$field]);
  81       }
  82     }
  83     $params['skipCleanMoney'] = TRUE;
  84   }
  85   $params['contribution_status_id'] = 'Pending';
  86   $order = new CRM_Financial_BAO_Order();
  87   $order->setDefaultFinancialTypeID($params['financial_type_id'] ?? NULL);
  88
  89   if (!empty($params['line_items']) && is_array($params['line_items'])) {
  90     foreach ($params['line_items'] as $index => $lineItems) {
  91       if (!empty($lineItems['params'])) {
  92         $order->setEntityParameters($lineItems['params'], $index);
  93       }
  94       foreach ($lineItems['line_item'] as $innerIndex => $lineItem) {
  95         $lineIndex = $index . '+' . $innerIndex;
  96         $order->setLineItem($lineItem, $lineIndex);
  97         $order->addLineItemToEntityParameters($lineIndex, $index);
  98       }
  99     }
 100   }
 101   else {
 102     $order->setPriceSetToDefault('contribution');
 103     $order->setLineItem([
 104       // Historically total_amount in this case could be tax
 105       // inclusive if tax is also supplied.
 106       // This is inconsistent with the contribution api....
 107       'line_total' => ((float) $params['total_amount'] - (float) ($params['tax_amount'] ?? 0)),
 108       'financial_type_id' => (int) $params['financial_type_id'],
 109     ], 0);
 110   }
 111   // Only check the amount if line items are set because that is what we have historically
 112   // done and total amount is historically only inclusive of tax_amount IF
 113   // tax amount is also passed in it seems
 114   if (isset($params['total_amount']) && !empty($params['line_items'])) {
 115     $currency = $params['currency'] ?? CRM_Core_Config::singleton()->defaultCurrency;
 116     if (!CRM_Utils_Money::equals($params['total_amount'], $order->getTotalAmount(), $currency)) {
 117       throw new CRM_Contribute_Exception_CheckLineItemsException();
 118     }
 119   }
 120   $params['total_amount'] = $order->getTotalAmount();
 121
 122   foreach ($order->getEntitiesToCreate() as $entityParams) {
 123     if ($entityParams['entity'] === 'participant') {
 124       if (isset($entityParams['participant_status_id'])
 125         && (!CRM_Event_BAO_ParticipantStatusType::getIsValidStatusForClass($entityParams['participant_status_id'], 'Pending'))) {
 126         throw new CiviCRM_API3_Exception('Creating a participant via the Order API with a non "pending" status is not supported');
 127       }
 128       $entityParams['participant_status_id'] = $entityParams['participant_status_id'] ?? 'Pending from incomplete transaction';
 129       $entityParams['status_id'] = $entityParams['participant_status_id'];
 130       $entityParams['skipLineItem'] = TRUE;
 131       $entityResult = civicrm_api3('Participant', 'create', $entityParams);
 132       // @todo - once membership is cleaned up & financial validation tests are extended
 133       // we can look at removing this - some weird handling in removeFinancialAccounts
 134       $params['contribution_mode'] = 'participant';
 135       $params['participant_id'] = $entityResult['id'];
 136       foreach ($entityParams['line_references'] as $lineIndex) {
 137         $order->setLineItemValue('entity_id', $entityResult['id'], $lineIndex);
 138       }
 139     }
 140
 141     if ($entityParams['entity'] === 'membership') {
 142       $entityParams['status_id'] = 'Pending';
 143       if (!empty($params['contribution_recur_id'])) {
 144         $entityParams['contribution_recur_id'] = $params['contribution_recur_id'];
 145       }
 146       $entityParams['skipLineItem'] = TRUE;
 147       $entityResult = civicrm_api3('Membership', 'create', $entityParams);
 148       foreach ($entityParams['line_references'] as $lineIndex) {
 149         $order->setLineItemValue('entity_id', $entityResult['id'], $lineIndex);
 150       }
 151     }
 152   }
 153
 154   $params['line_item'][$order->getPriceSetID()] = $order->getLineItems();
 155
 156   $contributionParams = $params;
 157   // If this is nested we need to set sequential to 0 as sequential handling is done
 158   // in create_success & id will be miscalculated...
 159   $contributionParams['sequential'] = 0;
 160   foreach ($contributionParams as $key => $value) {
 161     // Unset chained keys so the code does not attempt to do this chaining twice.
 162     // e.g if calling 'api.Payment.create' We want to finish creating the order first.
 163     // it would probably be better to have a full whitelist of contributionParams
 164     if (substr($key, 0, 3) === 'api') {
 165       unset($contributionParams[$key]);
 166     }
 167   }
 168
 169   $contribution = civicrm_api3('Contribution', 'create', $contributionParams);
 170   $contribution['values'][$contribution['id']]['line_item'] = array_values($order->getLineItems());
 171
 172   return civicrm_api3_create_success($contribution['values'] ?? [], $params, 'Order', 'create');
 173 }
 174
 175 /**
 176  * Delete a Order.
 177  *
 178  * @param array $params
 179  *   Input parameters.
 180  *
 181  * @return array
 182  * @throws API_Exception
 183  * @throws CiviCRM_API3_Exception
 184  */
 185 function civicrm_api3_order_delete(array $params): array {
 186   $contribution = civicrm_api3('Contribution', 'get', [
 187     'return' => ['is_test'],
 188     'id' => $params['id'],
 189   ]);
 190   if ($contribution['id'] && $contribution['values'][$contribution['id']]['is_test'] == TRUE) {
 191     $result = civicrm_api3('Contribution', 'delete', $params);
 192   }
 193   else {
 194     throw new API_Exception('Only test orders can be deleted.');
 195   }
 196   return civicrm_api3_create_success($result['values'], $params, 'Order', 'delete');
 197 }
 198
 199 /**
 200  * Cancel an Order.
 201  *
 202  * @param array $params
 203  *   Input parameters.
 204  *
 205  * @return array
 206  * @throws \CiviCRM_API3_Exception
 207  */
 208 function civicrm_api3_order_cancel(array $params) {
 209   $contributionStatuses = CRM_Contribute_PseudoConstant::contributionStatus(NULL, 'name');
 210   $params['contribution_status_id'] = array_search('Cancelled', $contributionStatuses);
 211   $result = civicrm_api3('Contribution', 'create', $params);
 212   return civicrm_api3_create_success($result['values'], $params, 'Order', 'cancel');
 213 }
 214
 215 /**
 216  * Adjust Metadata for Cancel action.
 217  *
 218  * The metadata is used for setting defaults, documentation & validation.
 219  *
 220  * @param array $params
 221  *   Array of parameters determined by getfields.
 222  */
 223 function _civicrm_api3_order_cancel_spec(array &$params) {
 224   $params['contribution_id'] = [
 225     'api.required' => 1,
 226     'title' => 'Contribution ID',
 227     'type' => CRM_Utils_Type::T_INT,
 228   ];
 229 }
 230
 231 /**
 232  * Adjust Metadata for Create action.
 233  *
 234  * The metadata is used for setting defaults, documentation & validation.
 235  *
 236  * @param array $params
 237  *   Array of parameters determined by getfields.
 238  */
 239 function _civicrm_api3_order_create_spec(array &$params) {
 240   $params['contact_id'] = [
 241     'name' => 'contact_id',
 242     'title' => 'Contact ID',
 243     'type' => CRM_Utils_Type::T_INT,
 244     'api.required' => TRUE,
 245   ];
 246   $params['total_amount'] = [
 247     'name' => 'total_amount',
 248     'title' => 'Total Amount',
 249   ];
 250   $params['skipCleanMoney'] = [
 251     'api.default' => TRUE,
 252     'title' => 'Do not attempt to convert money values',
 253     'type' => CRM_Utils_Type::T_BOOLEAN,
 254   ];
 255   $params['financial_type_id'] = [
 256     'name' => 'financial_type_id',
 257     'title' => 'Financial Type',
 258     'type' => CRM_Utils_Type::T_INT,
 259     'api.required' => TRUE,
 260     'table_name' => 'civicrm_contribution',
 261     'entity' => 'Contribution',
 262     'bao' => 'CRM_Contribute_BAO_Contribution',
 263     'pseudoconstant' => [
 264       'table' => 'civicrm_financial_type',
 265       'keyColumn' => 'id',
 266       'labelColumn' => 'name',
 267     ],
 268   ];
 269 }
 270
 271 /**
 272  * Adjust Metadata for Delete action.
 273  *
 274  * The metadata is used for setting defaults, documentation & validation.
 275  *
 276  * @param array $params
 277  *   Array of parameters determined by getfields.
 278  */
 279 function _civicrm_api3_order_delete_spec(array &$params) {
 280   $params['contribution_id'] = [
 281     'api.required' => TRUE,
 282     'title' => 'Contribution ID',
 283     'type' => CRM_Utils_Type::T_INT,
 284   ];
 285   $params['id']['api.aliases'] = ['contribution_id'];
 286 }