Register blocked value

Blocks part of a transaction line: associates a blocked value with one line of an existing transaction, e.g. the total line of a purchase invoice.

Twinfield documentation: Transaction blocked value.

This example changes data in Twinfield. Only run it on a test administration, and remove the blocked value again with Unregister blocked value.

The command goes to the TransactionBlockedValueService, a Command & Query web service. It returns nothing; when Twinfield refuses it, you get a CommandQueryFaultException with errorCode BlockedValueCannotBeRegistered (see TransactionBlockedValueServiceFaultCode).

The line is the id of a line of the transaction: $transaction->total->id for the total line, $line->id for a detail line. The value has at most two decimals.

Code

$twinfield = Example::twinfield();

// E.g. `INK 202600021 1 50.00`: day book, transaction number, line id and the value to block.
[, $dayBook, $number, $line, $value] = array_pad($argv ?? [], 5, null);

if ($dayBook === null || $number === null || $line === null || $value === null) {
    echo 'Usage: php example.php <day book> <transaction number> <line id> <value>', PHP_EOL;

    exit(0);
}

try {
    $twinfield->transactionBlockedValues()->register($dayBook, (int) $number, (int) $line, Amount::fromString($value));
} catch (CommandQueryFaultException $exception) {
    echo 'Refused (', $exception->errorCode, '): ', $exception->errorMessage, PHP_EOL;

    exit(1);
}

echo 'Blocked ', $value, ' on line ', $line, ' of ', $dayBook, ' ', $number, PHP_EOL;

Run

The write guard of the examples blocks changes unless you allow them for a company in TWINFIELD_WRITE_COMPANIES:

TWINFIELD_COMPANY=1002_3 TWINFIELD_ALLOW_WRITES=1002_3 php examples/transaction-blocked-values/register-blocked-value/example.php INK 202600021 1 50.00

Blocked 50.00 on line 1 of INK 202600021

XML

What the SDK sends to Twinfield and what Twinfield sends back, for a call like the one in this example. The responses come from the tests, with example data.

RegisterBlockedAmountForTransaction

Twinfield documentation: Transaction blocked value: RegisterBlockedAmountForTransaction.

$twinfield->transactionBlockedValues()->register('MEMO', 202100001, 1, '2000.00');

The SDK sends this in the SOAP body to TransactionBlockedValueService.svc, with SOAPAction http://www.twinfield.com/TransactionBlockedValueService/Process; the access token goes in the SOAP header:

<Command xmlns="http://www.twinfield.com/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:a="http://schemas.datacontract.org/2004/07/Twinfield.WebServices.TransactionBlockedValueService" i:type="a:RegisterBlockedAmountForTransaction">
  <a:BlockedValue>2000.00</a:BlockedValue>
  <a:CompanyCode>1000</a:CompanyCode>
  <a:TransactionCode>MEMO</a:TransactionCode>
  <a:TransactionLineId>1</a:TransactionLineId>
  <a:TransactionNumber>202100001</a:TransactionNumber>
</Command>

Twinfield answers with an empty SOAP body: the command succeeded.

Source

View examples/transaction-blocked-values/register-blocked-value/example.php on GitHub.