Annytab Dox Trade v1

This is a documentation of Annytab Dox Trade v1, our own royalty-free standard that represent a trade document (business document) that can be used for sales and purchases in a company. The sales routine of a company means, among other things, to receive requests for quotation from customers, to create quotations, to receive orders from customers and to send invoices/bills to customers. The purchase routine of a company means, among other things, to send quotation requests to suppliers, to receive quotes, to send purchase orders to suppliers and to receive invoices from suppliers.

This standard for business documents can be used for quotation request, quotation, order, order confirmation, invoice, credit invoice, cash receipt and payment reminder. All these documents have the same layout, depending on the type of document you can can ignore some data in the document. A variable determines the kind of document (document_type). A credit invoice (credit_invoice) is a negative invoice and should have negative quantities in product rows and negative totals.

This standard is based on JSON, a compact and text-based format that is used to exchange data. It’s easy to serialize objects to JSON and it’s easy to deserialize JSON to objects. This standard is available in a NuGet package: a-dox-standards (NuGet Gallery).

AnnytabDoxTrade [Model]

Property
Type
Description
id
string
A local identity for the document that is set by the person who creates the document. A consecutive number in an erp-system (quotation number, order number or invoice number).
document_type
string
A string that indicates the type of document. Can assume any of the following values: request_for_quotation, quotation, order, order_confirmation, invoice, credit_invoice, cash_receipt, payment_reminder.
payment_reference
string
The reference to be given when paying the invoice. May be an invoice number, an OCR number, or another type of identity.
issue_date
string
The date the document was created. The date should be entered as yyyy-MM-dd (2017-09-31).
due_date
string
The date when the invoice should be paid at latest. The date should be entered as yyyy-MM-dd (2017-09-31).
delivery_date
string
I an invoice it refers to the date when the goods were delivered to the customer. In a quotation request or an order it means the desired delivery date, in a quotation it means the estimated delivery date. The date should be entered as yyyy-MM-dd (2017-09-31), enter an empty string or null if the delivery date does not need to be specified.
offer_expires_date
string
The date when the offer in a quotation expires, the offer is not valid after this date. The date should be entered as yyyy-MM-dd (2017-09-31), enter an empty string or null if the date does not need to be specified.
seller_references
Dictionary<string, string>
Here you can enter references relating to the seller, for example, the buyer can enter his internal supplier number for the seller. Possible keys: supplier_id, quotation_id, order_id, invoice_id.
buyer_references
Dictionary<string, string>
Here you can enter references relating to the buyer, for example, the seller may enter his internal customer number for the buyer. Possible keys: customer_id, request_for_quotation_id and order_id.
terms_of_delivery
string
A 3-digit code according to Incoterms 2010 or later that specifies the terms of delivery.
terms_of_payment
string
A code that specifies the payment terms for the invoice. There are no standard to use, these codes are common internationally: PIA, 7, 10, 30, 60, 90, EOM, 1% 10 Net 30, COD, Cash account, Letter of credit, Bill of exchange, CND, CBS, CIA, CWO, 1MD, 2MD, Contrast, Stage payment.
mode_of_delivery
string
A code that indicates how the products are delivered (delivery method), such as Mail, Email, Web, DHL, UPS.
total_weight_kg
decimal
The total weight in kilograms for the entire delivery, is mainly used for statistical purposes (Intrastat).
penalty_interest
decimal
A decimal numeral indicating the default interest on late payment of the invoice. A default interest rate of 10 % is stated as 0.10 and a default interest rate of 12.5 % is stated as 0.125.
currency_code
string
A 3-letter code according to ISO 4217 that specifies the currency applicable to the amounts in the document.
vat_country_code
string
A 2-letter country code according to ISO 3166-1 that specifies which country’s VAT or Sales Tax that is applied in the invoice.
vat_state_code
string
A 2-letter code indicating which state’s VAT or Sales Tax that is applied in the invoice. Applicable to countries that have states, such as the United States.
comment
string
Here you can enter a text/html message.
seller_information
PartyInformation
This model contains information about the seller, see the description for PartyInformation below.
buyer_information
PartyInformation
This model contains information about the buyer, see the description for PartyInformation below.
delivery_information
PartyInformation
This model contains information about the recipient and the place to which the goods are to be delivered, see the description for PartyInformation below.
payment_options
IList<PaymentOption>
A list of payment options, see the description for PaymentOption below.
product_rows
IList<ProductRow>
A list of product rows, see the description for ProductRow below.
vat_specification
IList<VatSpecification>
A list of VAT-specifications or Sales Tax specifications, see the description for VatSpecification below.
subtotal
decimal
The total net amount for the entire document, excluding VAT/Sales Tax and expressed in the specified currency.
vat_total
decimal
The total Value Added Tax/Sales Tax for the entire document, expressed in the specified currency.
rounding
decimal
The rounding amount expressed in the specified currency, does not affect the total value added tax/sales tax.
total
decimal
Here is the total amount for the entire document, including Value Added Tax/Sales Tax, adjusted for rounding. The amount is expressed in the specified currency.
paid_amount
decimal
The total amount paid by the customer before the document was issued.
balance_due
decimal
The total amount that the buyer owes to the seller, total amount less the amount paid.

PartyInformation [Model]

Property
Type
Description
person_id
string
An identity number for the person. For example: company id or social security number. It is used with the country code (country_code) to identify a natural or legal person.
person_name
string
The name of the natural or legal person.
address_line_1
string
The first address line. May contain a C/O reference, a street name, a building number and an apartment number and more.
address_line_2
string
The second address line. May contain a C/O reference, a street name, a building number and an apartment number and more.
address_line_3
string
The third address line. May contain a C/O reference, a street name, a building number and an apartment number and more.
postcode
string
A postcode (zip-code) for the party, an alphanumeric combination that is used to identify a geographic area.
city_name
string
The city name for the party, a geographic area with its own postal address.
country_name
string
A country name for the party.
country_code
string
A 2-letter country code in accordance with ISO 3166-1 that represents the country.
state_code
string
A 2-letter code indicating the state for the party.
contact_name
string
The name of the party’s contact person, the contact’s name may differ from the party’s name.
phone_number
string
The telephone number of the party or the party’s contact person.
email
string
An email address for the party or party’s contact person.
vat_number
string
The VAT-number or Sales Tax number for the party.

PaymentOption [Model]

Property
Type
Description
name
string
A standard name for the payment option. For example: IBAN, BG, PG, SWISH, PAYPAL or BANK.
account_reference
string
The account identification of the payment option, such as account number, email address, or a url. An account number must be entered without spaces and hyphen. If an account has a clearing number, this is entered in front of the account number as a single number.
bank_identifier_code
string
The bank’s BIC-code. BIC is an international standard used to identify a bank in international money transfers.
bank_name
string
The name of the bank.
bank_country_code
string
A 2-letter country code according to ISO 3166-1 for the bank.

ProductRow [Model]

Property
Type
Description
product_code
string
A unique item number for the product. The product code is a short code used to identify the product.
manufacturer_code
string
Manufacturer Part Number (MPN). This manufacturer code is used to identify the product if there is no gtin for the product.
gtin
string
The product’s GTIN, a global item number that only consists of numbers. The GTIN is used to identify consumer products and may be of different lengths (8, 12, 13, 14). GTIN is useful because it can translate into a barcode that can be read by a scanner.
product_name
string
A descriptive name for the product and its characteristics.
vat_rate
decimal
The VAT-/Sales Tax rate applicable to the product. Entered as a decimal numeral, 25 % is written as 0.25.
quantity
decimal
The quantity quoted/ordered/delivered of the product. The number of units for the product line.
unit_code
string
A unit code according to ISO 20022 regarding the specified quantity.
unit_price
decimal
The price for a unit of the product excluding VAT/Sales Tax, expressed in the currency of the document.
subrows
IList<ProductRow>
A list of inbound product rows, used for bundle products that contains other products.

VatSpecification [Model]

Property
Type
Description
tax_rate
decimal
Here is a VAT-/Sales Tax rate as a decimal numeral. A tax rate of 25 % is stated as 0.25.
taxable_amount
decimal
The total tax base for the specified VAT-/Sales Tax rate.
tax_amount
decimal
The total VAT-/Sales Tax amount for the VAT-/Sales Tax rate, the tax rate multiplied by the taxable amount (tax base).

JSON Example

{
  "id": "d82f56c8-7f87-402d-bbce-3af3e8287e67",
  "document_type": "invoice",
  "payment_reference": "D-2000",
  "issue_date": "2017-12-04",
  "due_date": "2018-01-03",
  "delivery_date": "2017-12-04",
  "offer_expires_date": null,
  "seller_references": {
    "supplier_id": "test"
  },
  "buyer_references": {
    "customer_id": "F557882"
  },
  "terms_of_delivery": "CIF",
  "terms_of_payment": "30",
  "mode_of_delivery": "UPS",
  "total_weight_kg": 10,
  "penalty_interest": 0.2,
  "currency_code": "USD",
  "vat_country_code": "SE",
  "vat_state_code": null,
  "comment": "Thank you for buying from us.",
  "seller_information": {
    "person_id": "778899-7447",
    "person_name": "Supplier Inc",
    "address_line_1": "Abroad way 55",
    "address_line_2": null,
    "address_line_3": null,
    "postcode": "CA90009",
    "city_name": "San Francisco",
    "country_name": "USA",
    "country_code": "US",
    "state_code": "CA",
    "contact_name": "Brenda Meatloaf",
    "phone_number": "+8800004545",
    "email": "olle@annytab.se",
    "vat_number": "778899-7447"
  },
  "buyer_information": {
    "person_id": "556864-2747",
    "person_name": "A Name Not Yet Taken AB",
    "address_line_1": "Skonertgatan 12",
    "address_line_2": "Kronobränneriet",
    "address_line_3": "",
    "postcode": "30238",
    "city_name": "Halmstad",
    "country_name": "Sweden",
    "country_code": "SE",
    "state_code": "",
    "contact_name": "Fredrik Stigsson",
    "phone_number": "",
    "email": "dox@annytab.se",
    "vat_number": "SE556864274701"
  },
  "delivery_information": null,
  "payment_options": [
    {
      "name": "IBAN",
      "account_reference": "SE4680000816959239073274",
      "bank_identifier_code": "SWEDSESS",
      "bank_name": "Swedbank AB",
      "bank_country_code": "SE"
    },
    {
      "name": "BG",
      "account_reference": "7893514",
      "bank_identifier_code": "BGABSESS",
      "bank_name": "Bankgirocentralen BGC AB",
      "bank_country_code": "SE"
    },
    {
      "name": "BANK",
      "account_reference": "816959239073274",
      "bank_identifier_code": "SWEDSESS",
      "bank_name": "Swedbank AB",
      "bank_country_code": "SE"
    },
    {
      "name": "SWISH",
      "account_reference": "1235370366",
      "bank_identifier_code": "SWEDSESS",
      "bank_name": "Swedbank AB",
      "bank_country_code": "SE"
    },
    {
      "name": "PAYPAL.ME",
      "account_reference": "https://www.paypal.me/annytab",
      "bank_identifier_code": "",
      "bank_name": "PayPal",
      "bank_country_code": "US"
    }
  ],
  "product_rows": [
    {
      "product_code": null,
      "manufacturer_code": null,
      "gtin": null,
      "product_name": "Support",
      "vat_rate": 0.25,
      "quantity": 10.46,
      "unit_code": "h",
      "unit_price": 11.44,
      "subrows": null
    },
    {
      "product_code": "C-546",
      "manufacturer_code": "TT99878",
      "gtin": null,
      "product_name": "Computer",
      "vat_rate": 0.12,
      "quantity": 1,
      "unit_code": "pcs",
      "unit_price": 499.99,
      "subrows": null
    },
    {
      "product_code": "D-4879",
      "manufacturer_code": null,
      "gtin": "0000001",
      "product_name": "Desk",
      "vat_rate": 0.06,
      "quantity": 2,
      "unit_code": "pcs",
      "unit_price": 2,
      "subrows": null
    }
  ],
  "vat_specification": [
    {
      "tax_rate": 0.25,
      "taxable_amount": 119.6624,
      "tax_amount": 29.9156
    },
    {
      "tax_rate": 0.12,
      "taxable_amount": 499.99,
      "tax_amount": 59.9988
    },
    {
      "tax_rate": 0.06,
      "taxable_amount": 4,
      "tax_amount": 0.24
    }
  ],
  "subtotal": 624,
  "vat_total": 90.1544,
  "rounding": -0.1544,
  "total": 714,
  "paid_amount": 0,
  "balance_due": 714
}

Code Example

// Create an invoice
AnnytabDoxTrade post = new AnnytabDoxTrade();
post.id = invoice.id;
post.document_type = "invoice";
post.payment_reference = invoice.invoice_number;
post.issue_date = invoice.invoice_date.ToString("yyyy-MM-dd");
post.due_date = invoice.invoice_date.AddDays(30).ToString("yyyy-MM-dd");
post.delivery_date = invoice.invoice_date.ToString("yyyy-MM-dd");
post.seller_references = new Dictionary<string, string>();
post.seller_references.Add("supplier_id", "T2000");
post.seller_references.Add("quotation_id", "546");
post.seller_references.Add("order_id", "1890");
post.buyer_references = new Dictionary<string, string>();
post.buyer_references.Add("customer_id", invoice.member_id);
post.buyer_references.Add("request_for_quotation_id", "55");
post.buyer_references.Add("order_id", "504");
post.terms_of_delivery = "EXW";
post.terms_of_payment = "Net 30";
post.mode_of_delivery = "WEB";
post.total_weight_kg = 0M;
post.penalty_interest = 0.10M;
post.currency_code = invoice.currency_code;
post.vat_country_code = "SE";
post.vat_state_code = "";
post.comment = tt.Get("invoice_text");
post.seller_information = new PartyInformation()
{
    person_id = "556864-2747",
    person_name = "A Name Not Yet Taken AB",
    address_line_1 = "Skonertgatan 12",
    address_line_2 = "Kronobränneriet",
    address_line_3 = "",
    postcode = "30238",
    city_name = "Halmstad",
    country_name = "Sweden",
    country_code = "SE",
    state_code = "",
    contact_name = "Fredrik Stigsson",
    phone_number = "",
    email = "info@annytab.se",
    vat_number = "SE556864274701"
};
post.buyer_information = new PartyInformation
{
    person_id = invoice.person_id,
    person_name = invoice.invoice_name,
    address_line_1 = invoice.invoice_address_1,
    address_line_2 = invoice.invoice_address_2,
    address_line_3 = "",
    postcode = invoice.invoice_postcode,
    city_name = invoice.invoice_city,
    country_name = invoice.invoice_country,
    country_code = invoice.invoice_country_code,
    state_code = "",
    contact_name = invoice.contact_name,
    phone_number = invoice.phone_number,
    email = invoice.invoice_email,
    vat_number = invoice.vat_number
};
post.payment_options = new List<PaymentOption>
{
    new PaymentOption
    {
        name = "IBAN",
        account_reference = "SE4680000816959239073274",
        bank_identifier_code = "SWEDSESS",
        bank_name = "Swedbank AB",
        bank_country_code = "SE"
    },
    new PaymentOption
    {
        name = "BG",
        account_reference = "7893514",
        bank_identifier_code = "BGABSESS",
        bank_name = "Bankgirocentralen BGC AB",
        bank_country_code = "SE"
    },
    new PaymentOption
    {
        name = "SWISH",
        account_reference = "1235370366",
        bank_identifier_code = "SWEDSESS",
        bank_name = "Swedbank AB",
        bank_country_code = "SE"
    }
};
post.product_rows = new List<ProductRow>
{
    new ProductRow
    {
        product_code = "GiB",
        manufacturer_code = "GiB",
        gtin = "",
        product_name = tt.Get("gibibytes"),
        vat_rate = invoice.vat_rate,
        quantity = invoice.gib,
        unit_code = "PIEC",
        unit_price = invoice.unit_price,
        subrows = new List<ProductRow>()
    }
};
post.vat_specification = new List<VatSpecification>
{
    new VatSpecification
    {
        tax_rate = invoice.vat_rate,
        taxable_amount = invoice.net_amount,
        tax_amount = invoice.vat_amount,
    }
};
post.subtotal = invoice.net_amount;
post.vat_total = invoice.vat_amount;
post.rounding = 0M;
post.total = invoice.gross_amount;
post.paid_amount = invoice.paid == true ? invoice.gross_amount : 0;
post.balance_due = invoice.gross_amount - post.paid_amount;

// Convert the object to a byte array
byte[] array = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(post));

// Write to the stream
stream.Write(array, 0, array.Length);

Leave a Reply

Your email address will not be published. Required fields are marked *