Payments Write

pixiCreateBankline

Creates a new bank header together with a single bank line (bank transaction) and returns the keys of both new records.

Imports a single bank transaction into Pixi, for example for later matching against Aufträge or Rechnungen.

Steps:

Determines the database (home) currency via pixi.GetDatabaseCurrency(). This is the currency whose code matches the setting HomeCurrency and that is marked as parent currency.
If SourceType is NULL or empty, it is set to API.
Inserts a new record into BankHeader with SourceType, the current server time as BankImportDate and BankFileName.
Inserts one record into BankLines that references the new header:
- BankDate = BankDate.
- BookDate = month and day of BankDate as a four-character string MMDD (e.g. 0315).
- BusinessCode is always 051.
- BankCode = BLZ, AccountNr, CustomerName, BankText01–BankText03, ParsedBIC = BIC, ParsedIBAN = IBAN, AccountingBankAccount.
- CurrencyId = CurrencyId, or the database currency if CurrencyId is not given.
Returns one row with the new BankHeaderKey and BanklineKey.

Every call creates its own bank header; several lines cannot be added to an existing header with this call.

Notes

No explicit transaction is used. If the insert into BankLines fails, the already inserted BankHeader record remains without lines.
No validation is performed: duplicates are not detected, IBAN/BIC are not checked, and the amount sign is taken as passed.
BankFileName, BankDate, BankAmount, BankText01–BankText03, BLZ, AccountNr and CustomerName have no default value and must be present in the request (they may be empty or NULL as far as the table allows).
If BankDate is NULL, BookDate is also NULL.
If no currency matching the HomeCurrency setting is found and CurrencyId is not passed, CurrencyId is stored as NULL.
BLZ and AccountNr are char parameters and are padded with spaces; SourceType is limited to 3 characters.
BanklineKey comes from SCOPE_IDENTITY() and is therefore returned as a decimal value.

Tables used

BankHeader · Write BankLines · Write Currency · Read Settings · Read

Parameter	Type	Default	Description
`BankFileName` Required	varchar(1024) string	–	Name of the bank file or source the transaction comes from; stored in `BankHeader.BankFileName`. Example: `shop-payments-2024-03-15.csv`
`BankDate` Required	datetime dateTime	–	Date of the bank transaction. Also used to derive `BookDate` (format `MMDD`). Example: `2024-03-15T00:00:00`
`BankAmount` Required	money decimal	–	Amount of the transaction. Example: `149.90`
`BankText01` Required	varchar(1024) string	–	First line of the payment reference / booking text. Example: `Order 100234`
`BankText02` Required	varchar(1024) string	–	Second line of the payment reference / booking text. Example: `Invoice RE-2024-0815`
`BankText03` Required	varchar(1024) string	–	Third line of the payment reference / booking text.
`BLZ` Required	char(11) string	–	Bank code of the counterparty; stored in `BankLines.BankCode`. Example: `37040044`
`AccountNr` Required	char(24) string	–	Account number of the counterparty. Example: `0532013000`
`CustomerName` Required	varchar(60) string	–	Name of the account holder / payer. Example: `Max Mustermann`
`BIC`	varchar(50) string	NULL	BIC of the counterparty; stored in `BankLines.ParsedBIC`. Example: `COBADEFFXXX`
`IBAN`	varchar(150) string	NULL	IBAN of the counterparty; stored in `BankLines.ParsedIBAN`. Example: `DE89370400440532013000`
`AccountingBankAccount`	varchar(250) string	NULL	Own bank account (accounting account) the transaction belongs to. Example: `1200`
`SourceType`	varchar(3) string	API	Source type stored in `BankHeader.SourceType`. `NULL` or an empty string is replaced by `API`. Example: `API`
`CurrencyId`	smallint int	NULL	Id of the currency of the amount. If `NULL`, the database (home) currency is used. Example: `1`

Result set 1 · On success

Keys of the newly created bank header and bank line.

Column	Type	Description
`BankHeaderKey`	int	Key of the new `BankHeader` record.
`BanklineKey` Nullable	numeric(38,0) decimal	Key of the new `BankLines` record (value of `SCOPE_IDENTITY()`).

Response example

<SqlRowSet1>
  <row>
    <BankHeaderKey>1523</BankHeaderKey>
    <BanklineKey>48211</BanklineKey>
  </row>
</SqlRowSet1>

POST https://apigateway.descartes.com/tms/pixi/
Content-Type: text/xml; charset=utf-8
Authorization: Basic BASE64(USERNAME:PASSWORD)

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiCreateBankline>
      <BankFileName>shop-payments-2024-03-15.csv</BankFileName>
      <BankDate>2024-03-15T00:00:00</BankDate>
      <BankAmount>149.90</BankAmount>
      <BankText01>Order 100234</BankText01>
      <BankText02>Invoice RE-2024-0815</BankText02>
      <BankText03>?</BankText03>
      <BLZ>37040044</BLZ>
      <AccountNr>0532013000</AccountNr>
      <CustomerName>Max Mustermann</CustomerName>
      <!-- <BIC>COBADEFFXXX</BIC> -->
      <!-- <IBAN>DE89370400440532013000</IBAN> -->
      <!-- <AccountingBankAccount>1200</AccountingBankAccount> -->
      <!-- <SourceType>API</SourceType> -->
      <!-- <CurrencyId>1</CurrencyId> -->
    </ns1:pixiCreateBankline>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

curl -X POST 'https://apigateway.descartes.com/tms/pixi/' \
  --user 'USERNAME:PASSWORD' \
  --header 'Content-Type: text/xml; charset=utf-8' \
  --data-binary @- <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://apigateway.descartes.com/tms/pixi/">
  <SOAP-ENV:Body>
    <ns1:pixiCreateBankline>
      <BankFileName>shop-payments-2024-03-15.csv</BankFileName>
      <BankDate>2024-03-15T00:00:00</BankDate>
      <BankAmount>149.90</BankAmount>
      <BankText01>Order 100234</BankText01>
      <BankText02>Invoice RE-2024-0815</BankText02>
      <BankText03>?</BankText03>
      <BLZ>37040044</BLZ>
      <AccountNr>0532013000</AccountNr>
      <CustomerName>Max Mustermann</CustomerName>
      <!-- <BIC>COBADEFFXXX</BIC> -->
      <!-- <IBAN>DE89370400440532013000</IBAN> -->
      <!-- <AccountingBankAccount>1200</AccountingBankAccount> -->
      <!-- <SourceType>API</SourceType> -->
      <!-- <CurrencyId>1</CurrencyId> -->
    </ns1:pixiCreateBankline>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML

<?php

$soapClient = new SoapClient(null, [
    'login' => 'USERNAME',
    'password' => 'PASSWORD',
    'location' => 'https://apigateway.descartes.com/tms/pixi/',
    'uri' => 'https://apigateway.descartes.com/tms/pixi/',
]);

$arguments = [
    'BankFileName' => 'shop-payments-2024-03-15.csv',
    'BankDate' => '2024-03-15T00:00:00',
    'BankAmount' => '149.90',
    'BankText01' => 'Order 100234',
    'BankText02' => 'Invoice RE-2024-0815',
    'BankText03' => '?',
    'BLZ' => '37040044',
    'AccountNr' => '0532013000',
    'CustomerName' => 'Max Mustermann',
    // 'BIC' => 'COBADEFFXXX',
    // 'IBAN' => 'DE89370400440532013000',
    // 'AccountingBankAccount' => '1200',
    // 'SourceType' => 'API',
    // 'CurrencyId' => '1',
];

$soapArguments = [];
foreach ($arguments as $name => $value) {
    $soapArguments[] = new SoapVar($value, XSD_STRING, '', '', $name);
}

$response = $soapClient->__soapCall('pixiCreateBankline', $soapArguments);

SQL object:: dbo.pipiCreateBankline