Sales - Functionele beschrijving velden verkoopfacturen XML

Deze pagina beschrijft de functionele uitwerking in de software van een aantal van de velden in de verkoopfacturen XML. Deze dient te worden aangeleverd met de webservicemethode Sales - ProcessSalesInvoices(sessionID, administrationId, xmlDoc).

LET OP!

Het doornemen van het onderstaande XML-schema is aanbevolen, deze informatie is het meest volledig en in het Engels beschreven.

Webadres van het XML schema van de verkoopfacturen

http://www.yukiworks.nl/schemas/SalesInvoices.xsd

Voorbeeld XML schema

<SalesInvoices xmlns="urn:xmlns:http://www.theyukicompany.com:salesinvoices" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

        <SalesInvoice>

                <Reference>XX-1234</Reference>

                <Subject>Testfactuur - 1</Subject>

                <PaymentMethod>ElectronicTransfer</PaymentMethod>

                <PaymentID>1234-456</PaymentID>

                <PurchaseOrderNumber>123</PurchaseOrderNumber>

                <Process>true</Process>

                <EmailToCustomer>false</EmailToCustomer>

                <Layout />

                <Date>2021-08-01</Date>

                <DueDate>2021-09-01</DueDate>

                <PriceList />

                <Currency />

                <ProjectID />

                <ProjectCode />

                <Remarks />
                <Contact>

                        <ContactCode>1122</ContactCode>

                        <FullName>Apple Sales International</FullName>

                        <FirstName />

                        <MiddleName />

                        <LastName />

                        <Gender>Male</Gender>

                        <CountryCode>NL</CountryCode>

                        <City>Rotterdam</City>

                        <Zipcode>1234 AA</Zipcode>

                        <AddressLine_1>Bergweg 25</AddressLine_1>

                        <AddressLine_2 />

                        <Website />

                        <CoCNumber />

                        <VATNumber />

                        <ContactType>Company</ContactType>

                        <BankAccount />

                        <PhoneHome />
                        <MobileHome />

                </Contact>
                <ContactPerson>

                        <FirstName>Piet</FirstName>

                        <LastName>Pietersen</LastName>
                        <Gender>Male</Gender>

                        <EmailAddress>piet@pietersen.com</EmailAddress>

                </ContactPerson>
                <InvoiceLines>

                        <InvoiceLine>

                                <Description>Regel 1</Description>

                                <Remarks />

                                <ProductQuantity>2</ProductQuantity>

                                <Product>

                                        <Description>Product 1</Description>

                                        <Reference>TP-1122</Reference>

                                        <Category xsi:nil="true" />

                                        <SalesPrice>14.88</SalesPrice>

                                        <VATPercentage>21.00</VATPercentage>

                                        <VATIncluded>true</VATIncluded>

                                        <VATType>1</VATType>

                                        <GLAccountCode></GLAccountCode>

                                        <Remarks />

                                </Product>

                                <AccrualDate>2021-08-01</AccruelDate>

                                <AccrualPeriods>1</AccruelPeriods>

                                <AccrualInterval>1</AccruelInterval>

                        </InvoiceLine>

                </InvoiceLines>

        </SalesInvoice>
</SalesInvoices>

Omschrijving velden

Hieronder vind je een omschrijving van de velden. Het XML-schema bevat zelf ook een omschrijving van de velden en welke waarden en datatypes erin worden verwacht.

SalesInvoice: Reference

In dit veld kun je het factuurnummer opnemen.

• Factuur wordt buiten Yuki afgehandeld, afgedrukt en/of verzonden. De factuur heeft dus een factuurnummer buiten Yuki gekregen.
  Het veld 'Reference' bevat het factuurnummer en het veld 'Process' heeft de waarde 'true' zodat Yuki weet dat de factuur met de aangeleverde gegevens direct mag worden verwerkt
• Factuur moet nog binnen Yuki met de hand worden verwerkt, afgedrukt en/of verzonden, de factuur krijgt dan een factuurnummer van Yuki.
  Het veld 'Reference' verwijderen en het veld 'Process' moet de waarde 'false' bevatten.

SalesInvoice: PaymentMethod

De betaalwijze van de factuur. Mogelijke opties:

• Unspecified (bij de betaalwijze van de factuur wordt dan in Yuki 'Overschrijving' ingevuld)
• ElectronicTransfer (overschrijving)
• DirectCollection (betaalwijze 'Incasso' dient eerst in de factuurinstellingen te worden geactiveerd)
• ToSettle
• CreditCard
• DebitCard (pinbetaling)
• Cash
• iDeal
• Online.

SalesInvoice: PaymentID

In de dit veld kan je het betalingskenmerk meegeven.

SalesInvoice: PurchaseOrderNumber

In dit veld kan je het order nummer mee geven.

SalesInvoice: Process

Met dit veld geef je aan of je de factuur direct wilt verwerken. Als je ervoor kiest om de factuur te verwerken dien je ook het juiste factuurnummer op te geven in het veld 'Reference'.

Bij de waarde 'true' wordt de factuur in Yuki verwerkt en indien aangegeven verstuurd. Is de waarde 'false' dan wordt de factuur klaargezet in 'Te verzenden' en moet de factuur nog verwerkt worden.

Als de TAG Process ontbreekt, gaat Yuki uit van de waarde 'false'.

SalesInvoice: EmailToCustomer

Als je ervoor kiest om een factuur te verwerken kun je in dit veld aangeven of je wilt dat deze factuur direct via Yuki naar de klant moet worden ge-e-maild. Deze functionaliteit dient eerst in de factuurinstellingen te worden ingesteld.

Indien je niet wilt dat de factuur verstuurd wordt kun je het weglaten of de waarde 'false' opnemen. 

SalesInvoice: Lay-out

In dit veld kun je de gewenste factuur lay-out opgeven. Als je deze leeg laat, wordt de standaard factuur lay-out genomen.

SalesInvoice: Date

De factuurdatum.

SalesInvoice: DueDate

De vervaldatum.

SalesInvoice: PriceList

In dit veld kun je de gewenste prijslijst opgeven. Als je deze leeg laat wordt de standaard prijslijst genomen.

Als je een combinatie van prijzen inclusief en exclusief btw aanbiedt, is het zinvol dat je een prijslijst inclusief of exclusief meegeeft. Stel dat de prijs inclusief btw is, dan komt die weliswaar goed op de factuur. Is het artikel echter in een prijslijst opgeslagen exclusief btw en je maakt met hetzelfde artikel een factuur met de Yuki verkoopmodule dan wordt de prijs als exclusief btw beschouwd en zal als zodanig opgevoerd worden op de factuur.

LET OP!

De prijzen, btw-codes en omzetrekeningen die je meegeeft in de factuur zijn leidend.

SalesInvoice: Currency

De valuta van de verkoopfactuur. Als het veld niet ingevuld is, is de default waarde 'EUR'.

Als er geen prijslijst opgegeven is, wordt naar de standaard prijslijst gekeken. Als deze niet in vreemde valuta is dan krijg je de melding 'The pricelist's currency "EUR" does not match with the invoice's'.

Als de Currency afwijkt van de vreemde valuta in de prijslijst, krijg je onderstaande melding 'The pricelist's currency "USD" does not match with the invoice's'.

Als het veld 'Currency' niet gevuld is en het veld 'Pricelist' wel en deze is in vreemde valuta dan krijg je onderstaande melding 'The pricelist's currency "USD" does not match with the invoice's'.

SalesInvoice: ProjectID

De ID van het project waaraan je het document wilt koppelen. Het meegeven van deze parameter maakt de parameter 'ProjectCode' overbodig.  

Een gebruiker met de rol 'Directie' dient wel de bundel Medium, Large of Unlimited te hebben gekozen via de Yuki Store in het domein.

SalesInvoice: ProjectCode

De code van het project waaraan je het document wilt koppelen. Deze parameter wordt alleen gebruikt als de parameter 'ProjectID' niet wordt meegegeven. 

Een gebruiker met de rol 'Directie' dient wel de bundel Medium, Large of Unlimited te hebben gekozen via de Yuki Store in het domein.

Salesinvoice: Remarks

De ingegeven informatie komt niet op de factuur maar wordt als notitie bij de verkoopfactuur opgeslagen.

Contact: Contact

In het Contact element wordt de relatie/klant van een factuur opgegeven. Er zal eerst naar een bestaande relatie in het adresboek van Yuki gezocht worden. Er wordt gezocht:

• Indien een relatiecode is opgegeven: op relatiecode via het veld 'ContactCode'
• Indien niet gevonden of geen relatiecode opgegeven: op volledige naam via het veld 'FullName'

Indien geen bestaande relatie wordt gevonden wordt een nieuwe relatie aangemaakt.

Contact: gevonden met ContactCode = relatiecode op de adreskaart

• Als een relatiecode wordt gebruikt worden de adresgegevens van een bestaande relatie altijd overschreven met de huidige waarde in het XML-bronbestand.
• Om een veld niet te overschrijven kan het element volledig worden weggelaten uit het XML-bronbestand.
• Om een veld leeg te maken moet het element als lege node worden opgenomen (bijv <CocNumber />).

Contact: gevonden met FullName = naam of bedrijfsnaam op de adreskaart

• Als een relatie met dezelfde naam wordt gevonden worden alleen de lege velden van die relatie aangevuld met gegevens uit het XML-bronbestand.
• Voor de adresgegevens geldt ook dat alleen gegevens worden aangevuld als de bestaande gegevens overeenkomen.
  Bijvoorbeeld het adres 'Dorpstraat 40, Ons Dorp' zal worden aangevuld tot 'Dorpstraat 40, 1234 XX, Ons Dorp' indien in de XML het adres en woonplaats hetzelfde zijn en ook de postcode is opgegeven.

Contact: EmailAddress

Het is mogelijk om één e-mailadres mee te geven. Dit adres wordt bij de adreskaart van de klant opgeslagen en krijgt het type 'Factuur'. Als het adres op termijn wijzigt kun je dit bij een nieuwe factuur via de webservice meesturen, het 'oude' e-mailadres wordt dan type 'Overig' en het nieuwe e-mailadres type 'Factuur'.

Contact: BankAccount

Indien een rekeningnummer wordt opgegeven wordt deze als bankrekening voor de relatie opgeslagen. Het rekeningnummer wordt ook gebruikt als rekeningnummer voor deze factuur. Het is dus mogelijk om meerdere rekeningnummers voor dezelfde klant aan te leggen.

Contact: BIC

Indien een BIC code wordt opgegeven wordt deze als BIC code bij de bankrekening voor de relatie opgeslagen. Het rekeningnummer met BIC code wordt ook gebruikt als rekeningnummer voor deze factuur.

LET OP!

Hierdoor is het dus mogelijk om ook buitenlandse bankrekeningen aan te maken.

InvoiceLine: Description

De omschrijving van de factuurregel. Als dit veld leeg of niet aanwezig is wordt de omschrijving uit 'Product Description' gebruikt. 

InvoiceLine: Remarks

Dit is een extra omschrijving die je kunt meegeven per factuurregel. De tekst wordt onder de huidige regel op een nieuwe regel geplaatst.

LET OP!

Een newline geef je aan met de code &#13;

InvoiceLine: ProductQuantity

De kwantiteit van het verkoopartikel in de factuurregel.

InvoiceLine: LineAmount

Hier kan een regelbedrag opgegeven worden. Wanneer dit bedrag is opgegeven wordt de berekening van het regelbedrag op basis van het opgegeven aantal producten (ProductQuantity) en de prijs (/Product/SalesPrice) overgeslagen. Wanneer /Product/VATIncluded gelijk is aan 'true' is dit bedrag inclusief btw, anders is het bedrag exclusief btw.

LET OP!

Het wordt niet aangeraden dit veld te gebruiken. Er wordt namelijk afgeweken van de Yuki rekenmethodes!

InvoiceLine: LineVATAmount

Hier kan een regel-btw-bedrag opgegeven worden. Wanneer dit bedrag is opgegeven wordt de berekening van het regel-btw-bedrag op basis van het regelbedrag en het gebruikte btw-percentage overgeslagen.

LET OP!

Het wordt niet aangeraden dit veld te gebruiken. Er wordt namelijk afgeweken van de Yuki rekenmethodes!

Product: Description

De omschrijving van het verkoopartikel met een maximum lengte van 60 karakters. Langere omschrijvingen worden ingekort. Deze moet uniek zijn.

Als het artikel niet aanwezig is in Yuki, wordt het aan de hand van de in de XML aanwezige gegevens aangemaakt.

Als het veld 'InvoiceLine: Description' leeg is wordt de Product: Description op de factuur afgedrukt.

Product: Reference

De referentie van het verkoopartikel met een maximum lengte van 40 tekens. Langere referenties worden ingekort. Deze moet uniek zijn.

Product: Category

Dit veld kan in de toekomst gebruikt worden voor het toekennen van categorieën. Momenteel zijn alleen de waarden 'NULL' en '13' toegestaan (13 = categorie verkoopartikelen). Het veld mag niet leeg zijn.

Product: SalesPrice

De verkoopprijs van het verkoopartikel. Dit veld mag leeg zijn of met een 0-waarde worden meegegeven indien het verkoopartikel al reeds is aangemaakt en kan worden gevonden op basis van de omschrijving/referentie.

Alleen als de velden 'Salesprice', 'VATType' en 'VATPercentage' zijn ingevuld gebruikt Yuki de gegevens uit de XML en anders neemt het de informatie uit de prijslijst op.
Als één van de drie elementen ontbreekt moet het artikel zijn aangemaakt in de prijslijst want dan kan Yuki het artikel niet aanmaken in de prijslijst. Dat is dan weer nodig om de factuur te kunnen maken, want daarvoor gebruikt Yuki dan de gegevens van het artikel in de prijslijst.

Product: VATPercentage

Het btw-percentage van het verkoopartikel. Dit veld wordt gebruikt in combinatie met het veld 'VATType' om de btw-code op te halen. Als er geen btw-code met deze combinatie bestaat, wordt de factuur geannuleerd.

Product: VATIncluded

Met dit veld geef je aan of de verkoopprijs inclusief btw is. Dit veld wordt gebruikt in combinatie met de velden 'SalesPrice' en 'VATType' om het btw-bedrag en de verkoopprijs te berekenen. 

De waarde 'false' wordt standaard gebruikt als dit veld leeg wordt meegegeven in combinatie met een verkoopprijs.

Waarde 'false' = verkoopprijs is exclusief btw, waarde 'true' = verkoopprijs is inclusief btw.

Product: VATType

Met dit veld geef je het btw-type van het verkoopartikel aan. Dit veld wordt gebruikt in combinatie met de velden 'SalesPrice' en 'VATType' om het btw-bedrag en de verkoopprijs te berekenen. Mogelijke combinaties van btw-percentage en btw-code zijn:

Btwtype  Percentage      Omschrijving

VATDescription: Remarks

Dit veld kan gebruikt worden in combinatie met VATType '8', dit is niet verplicht. De VATDescription vind je in de btw instellingen van het domein.

Product: GLAccountCode

De code van de grootboekrekening in Yuki.

• Als het verkoopartikel nog niet aanwezig is in Yuki en dit veld is leeg of een ongeldige waarde (een niet actief grootboekrekeningnummer is ook ongeldig) bevat wordt standaard de grootboekrekening met code '80000 Omzet artikelgroep 1' gebruikt.
• Als het verkoopartikel aanwezig is en dit veld is leeg dan wordt het grootboekrekeningnummer gebruikt dat in Yuki aan het artikel gekoppeld is.
• Als het verkoopartikel aanwezig is en dit veld is gevuld met een geldige waarde dan wordt de inhoud van GLAccountCode gebruikt. Overigens wordt het grootboekrekeningnummer bij het bestaande verkoopartikel dan niet gewijzigd.

Product: Remarks

Deze opmerking wordt in Yuki aan het verkoopartikel toegevoegd en is dus niet op de factuur te zien.

InvoiceLine: AccrualDate

Startdatum van de spreiding van de omzet van de verkoopfactuur

InvoiceLIne: AccrualPeriods

Het aantal perioden waarover de omzet van de verkoopfactuur moet worden gespreid bijv. 12 perioden.

InvoiceLine: AccrualInterval

De duur van een periode uitgedrukt in maanden.