Create article
This example changes data in Twinfield. It deletes the article again, but only run it on a test administration.
Twinfield documentation: Articles.
Creates an article with two sub-articles and deletes it again. It uses the code you pass, or else the first unused code from EXAMPLE999 down (Example::unusedArticleCode()). The revenue account and the VAT code are the second and third argument, or else the first profit and loss account and the high sales VAT code of the company.
Describe the article with ArticleInput. Every method returns a new input:
| Method | What it sets |
|---|---|
ArticleInput::normal($code, $name), ::discount(), ::premium() |
An ordinary article, a deduction or a premium; code (at most 16 characters) and name (at most 40). |
shortName(), unitNames('Piece', 'Pieces') |
At most 20 characters each; null removes them. |
vatCode('VH') |
The default VAT code. |
percentage() |
The price of a discount or premium is a percentage. |
allowChangeVatCode(), allowChangeUnitPrice(), allowDiscountOrPremium(), allowDecimalQuantity() |
What may be changed on the invoice line. Not sent when you do not call them, so Twinfield uses its defaults. |
performanceType(), allowChangePerformanceType() |
For ICT VAT codes. |
subArticle(SubArticleInput) |
Adds a sub-article, or replaces the one with the same code. |
An article needs at least one sub-article, described with SubArticleInput:
| Method | What it sets |
|---|---|
SubArticleInput::create($name, $generalLedgerAccount, $code) |
Name (at most 80 characters), the revenue account and the code. The code may be left out when the article has one sub-article. |
unitPriceExcl('750.00') or unitPriceInc('907.50') |
The price excluding or including VAT; setting one clears the other. |
units(), shortName(), costCenter(), freeText3() |
Optional. |
Prices are numeric strings or Amount objects with at most two decimals, never floats. Invalid input throws an InvalidArgumentException before anything is sent.
Twinfield itself has one call for create and update. The SDK makes the difference explicit:
create()reads first and throws anArticleAlreadyExistsExceptionwhen the code exists, so you never overwrite an article by accident.update()throws anArticleNotFoundExceptionwhen the code does not exist (see Update article price).save()does what Twinfield does, without the check.
All three read the article back afterwards, so you get the complete Article. When Twinfield refuses the article, for example because the VAT code does not exist, you get a ProcessXmlException with the message per element.
$twinfield = Example::twinfield();
$articles = $twinfield->articles();
$article = $articles->create( ArticleInput::normal($code, 'Example bike') ->shortName('Example bike') ->unitNames('Piece', 'Pieces') ->vatCode($vatCode) ->subArticle(SubArticleInput::create("Example lady's bike", $account, $code . '-L')->unitPriceExcl('750.00')) ->subArticle(SubArticleInput::create("Example man's bike", $account, $code . '-M')->unitPriceExcl('760.00')),);
// Clean up: delete the example article again.$articles->delete($article->code);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/articles/create-article/example.phpcomposer test:write also runs this example, after you confirm the company code.
Created EXAMPLE999 Example bike (VAT code VH) EXAMPLE999-L Example lady's bike: 750.00 excl., 907.50 incl. EXAMPLE999-M Example man's bike: 760.00 excl., 919.60 incl.Deleted EXAMPLE999What 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.
Create/Update/Delete
Section titled “Create/Update/Delete”Twinfield documentation: Articles: Create/Update/Delete.
$twinfield->articles()->create( ArticleInput::normal('BIKE', 'Bike summer edition') ->shortName('Bike summer') ->unitNames('Piece', 'Pieces') ->vatCode('VH') ->subArticle(SubArticleInput::create("Lady's bike summer edition", '8050', 'BIKE.L')->unitPriceExcl('750.00')) ->subArticle(SubArticleInput::create("Man's bike summer edition", '8051', 'BIKE.M')->unitPriceExcl('760.00')),);The SDK sends this XML as xmlRequest of ProcessXmlString to processxml.asmx:
<article> <header> <office>1000</office> <code>BIKE</code> <type>normal</type> <name>Bike summer edition</name> <shortname>Bike summer</shortname> <unitnamesingular>Piece</unitnamesingular> <unitnameplural>Pieces</unitnameplural> <vatcode>VH</vatcode> </header> <lines> <line> <unitspriceexcl>750.00</unitspriceexcl> <unitspriceinc/> <units>1</units> <name>Lady's bike summer edition</name> <shortname/> <subcode>BIKE.L</subcode> <freetext1>8050</freetext1> <freetext2/> <freetext3/> </line> <line> <unitspriceexcl>760.00</unitspriceexcl> <unitspriceinc/> <units>1</units> <name>Man's bike summer edition</name> <shortname/> <subcode>BIKE.M</subcode> <freetext1>8051</freetext1> <freetext2/> <freetext3/> </line> </lines></article>Twinfield answers with this XML in ProcessXmlStringResult:
<article result="1"> <header status="active"> <office>1000</office> <code>BIKE</code> <type>normal</type> <name>Bike summer edition</name> <shortname>Bike summer</shortname> <unitnamesingular>Piece</unitnamesingular> <unitnameplural>Pieces</unitnameplural> <vatcode>VH</vatcode> <allowchangevatcode>false</allowchangevatcode> <performancetype/> <allowchangeperformancetype>false</allowchangeperformancetype> <percentage>false</percentage> <allowdiscountorpremium>true</allowdiscountorpremium> <allowchangeunitsprice>false</allowchangeunitsprice> <allowdecimalquantity>false</allowdecimalquantity> </header> <lines> <line inuse="true" status="active"> <unitspriceexcl>750.00</unitspriceexcl> <unitspriceinc>907.50</unitspriceinc> <units>1</units> <name>Lady's bike summer edition</name> <shortname>Lady summer</shortname> <subcode>BIKE.L</subcode> <freetext1 name="Bike lady" shortname="" dimensiontype="PNL">8050</freetext1> <freetext2 name="" shortname="" dimensiontype=""/> <freetext3/> <freetext4/> <freetext5/> <freetext6/> </line> <line inuse="false" status="active"> <unitspriceexcl>760.00</unitspriceexcl> <unitspriceinc>919.60</unitspriceinc> <units>1</units> <name>Man's bike summer edition</name> <shortname/> <subcode>BIKE.M</subcode> <freetext1 name="Bike man" shortname="" dimensiontype="PNL">8051</freetext1> <freetext2 name="Sales" shortname="" dimensiontype="KPL">00001</freetext2> <freetext3>Summer</freetext3> <freetext4/> <freetext5/> <freetext6/> </line> <line inuse="false" status="deleted"> <unitspriceexcl>350.00</unitspriceexcl> <unitspriceinc>423.50</unitspriceinc> <units>1</units> <name>Kid's bike summer edition</name> <shortname>Kid summer</shortname> <subcode>BIKE.K</subcode> <freetext1 name="" shortname="" dimensiontype="PNL">8052</freetext1> <freetext2 name="" shortname="" dimensiontype=""/> <freetext3/> <freetext4/> <freetext5/> <freetext6/> </line> </lines></article>create() first reads the article, to check that the code is free, and reads it back after saving: see Read article. The response follows the documentation; it is not recorded yet.
Source
Section titled “Source”View examples/articles/create-article/example.php on GitHub.
Twinfield and Wolters Kluwer are trademarks of Wolters Kluwer. Their names and logos are used only to refer to their products.