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       if (empty($entityParams['id'])) {
 143         $entityParams['status_id'] = 'Pending';
 144       }
 145       if (!empty($params['contribution_recur_id'])) {
 146         $entityParams['contribution_recur_id'] = $params['contribution_recur_id'];
 147       }
 148       $entityParams['skipLineItem'] = TRUE;
 149       $entityResult = civicrm_api3('Membership', 'create', $entityParams);
 150       foreach ($entityParams['line_references'] as $lineIndex) {
 151         $order->setLineItemValue('entity_id', $entityResult['id'], $lineIndex);
 152       }
 153     }
 154   }
 155
 156   $params['line_item'][$order->getPriceSetID()] = $order->getLineItems();
 157
 158   $contributionParams = $params;
 159   // If this is nested we need to set sequential to 0 as sequential handling is done
 160   // in create_success & id will be miscalculated...
 161   $contributionParams['sequential'] = 0;
 162   foreach ($contributionParams as $key => $value) {
 163     // Unset chained keys so the code does not attempt to do this chaining twice.
 164     // e.g if calling 'api.Payment.create' We want to finish creating the order first.
 165     // it would probably be better to have a full whitelist of contributionParams
 166     if (substr($key, 0, 3) === 'api') {
 167       unset($contributionParams[$key]);
 168     }
 169   }
 170
 171   $contribution = civicrm_api3('Contribution', 'create', $contributionParams);
 172   $contribution['values'][$contribution['id']]['line_item'] = array_values($order->getLineItems());
 173
 174   return civicrm_api3_create_success($contribution['values'] ?? [], $params, 'Order', 'create');
 175 }
 176
 177 /**
 178  * Delete a Order.
 179  *
 180  * @param array $params
 181  *   Input parameters.
 182  *
 183  * @return array
 184  * @throws API_Exception
 185  * @throws CiviCRM_API3_Exception
 186  */
 187 function civicrm_api3_order_delete(array $params): array {
 188   $contribution = civicrm_api3('Contribution', 'get', [
 189     'return' => ['is_test'],
 190     'id' => $params['id'],
 191   ]);
 192   if ($contribution['id'] && $contribution['values'][$contribution['id']]['is_test'] == TRUE) {
 193     $result = civicrm_api3('Contribution', 'delete', $params);
 194   }
 195   else {
 196     throw new API_Exception('Only test orders can be deleted.');
 197   }
 198   return civicrm_api3_create_success($result['values'], $params, 'Order', 'delete');
 199 }
 200
 201 /**
 202  * Cancel an Order.
 203  *
 204  * @param array $params
 205  *   Input parameters.
 206  *
 207  * @return array
 208  * @throws \CiviCRM_API3_Exception
 209  */
 210 function civicrm_api3_order_cancel(array $params) {
 211   $contributionStatuses = CRM_Contribute_PseudoConstant::contributionStatus(NULL, 'name');
 212   $params['contribution_status_id'] = array_search('Cancelled', $contributionStatuses);
 213   $result = civicrm_api3('Contribution', 'create', $params);
 214   return civicrm_api3_create_success($result['values'], $params, 'Order', 'cancel');
 215 }
 216
 217 /**
 218  * Adjust Metadata for Cancel action.
 219  *
 220  * The metadata is used for setting defaults, documentation & validation.
 221  *
 222  * @param array $params
 223  *   Array of parameters determined by getfields.
 224  */
 225 function _civicrm_api3_order_cancel_spec(array &$params) {
 226   $params['contribution_id'] = [
 227     'api.required' => 1,
 228     'title' => 'Contribution ID',
 229     'type' => CRM_Utils_Type::T_INT,
 230   ];
 231 }
 232
 233 /**
 234  * Adjust Metadata for Create action.
 235  *
 236  * The metadata is used for setting defaults, documentation & validation.
 237  *
 238  * @param array $params
 239  *   Array of parameters determined by getfields.
 240  */
 241 function _civicrm_api3_order_create_spec(array &$params) {
 242   $params['contact_id'] = [
 243     'name' => 'contact_id',
 244     'title' => 'Contact ID',
 245     'type' => CRM_Utils_Type::T_INT,
 246     'api.required' => TRUE,
 247   ];
 248   $params['total_amount'] = [
 249     'name' => 'total_amount',
 250     'title' => 'Total Amount',
 251   ];
 252   $params['skipCleanMoney'] = [
 253     'api.default' => TRUE,
 254     'title' => 'Do not attempt to convert money values',
 255     'type' => CRM_Utils_Type::T_BOOLEAN,
 256   ];
 257   $params['financial_type_id'] = [
 258     'name' => 'financial_type_id',
 259     'title' => 'Financial Type',
 260     'type' => CRM_Utils_Type::T_INT,
 261     'api.required' => TRUE,
 262     'table_name' => 'civicrm_contribution',
 263     'entity' => 'Contribution',
 264     'bao' => 'CRM_Contribute_BAO_Contribution',
 265     'pseudoconstant' => [
 266       'table' => 'civicrm_financial_type',
 267       'keyColumn' => 'id',
 268       'labelColumn' => 'name',
 269     ],
 270   ];
 271 }
 272
 273 /**
 274  * Adjust Metadata for Delete action.
 275  *
 276  * The metadata is used for setting defaults, documentation & validation.
 277  *
 278  * @param array $params
 279  *   Array of parameters determined by getfields.
 280  */
 281 function _civicrm_api3_order_delete_spec(array &$params) {
 282   $params['contribution_id'] = [
 283     'api.required' => TRUE,
 284     'title' => 'Contribution ID',
 285     'type' => CRM_Utils_Type::T_INT,
 286   ];
 287   $params['id']['api.aliases'] = ['contribution_id'];
 288 }