Orders

Every online transaction that results in a paid order or purchase within an online shop, SaaS, or other platforms must be meticulously handled within Take a NAP. This documentation provides a detailed guide to managing orders, including their creation, deletion, and the association with receipts.

​

Understanding Orders

An order in Take a NAP represents a transaction that has been successfully completed. It’s not just a record of a sale; it’s a critical component in the compliance process with various regulations, including interpretations of Article 18.

​

Why Create Orders?

1. Compliance: Ensuring that every transaction is recorded in accordance with Bulgarian laws.
2. Audit Trail: All orders are included in the audit XML file, automatically sent to the shop’s email, providing a transparent record.
3. Receipt Management: While not all orders require a receipt, creating an order ensures its inclusion in the audit XML file.

​

Handling Receipts

Not all orders have receipts associated with them. For example, orders paid with Postal Payment may not require the issuance of a receipt. However, they must still be recorded as orders.

​

Deleting and Replacing Orders

There is no option to modify an existing order, if changes are needed, the existing order must be deleted, and a new one must be created to replace it.

​

Support for Multiple Currencies

When a currency other than BGN is provided, Take a NAP will automatically convert each individual price to BGN using the daily exchange rate provided by the Bulgarian National Bank. This conversion is done separately for each price, and as a result, there may be rounding discrepancies for which Take a NAP is not responsible. To avoid any potential inconsistencies, it is strongly recommended that developers using the Take a NAP API provide all prices in BGN.

​

Managing Orders

In this section, we’ll cover how to create and delete orders using the Take a NAP API.

​

Creating an Order

Use the following endpoint to create an order:

POST /public-api/v1/order

const axios = require('axios');

const orderData = {
  internalId: 'ID1047',
  internalNumber: '1047',
  internalCreatedAt: '2023-07-24T09:09:42.349Z',
  customer: {
    email: '[email protected]',
    phone: '+359888888888',
    firstName: 'Ivan',
    lastName: 'Ivanov',
  },
  lineItems: [
    {
      name: 'Cute Pillow',
      quantity: 1,
      price: 15.0,
      discount: 10,
      vatRate: 20,
      vatGroup: 'GROUP_B',
    },
  ],
  paymentType: 'PAYMENT_PROCESSOR',
  paymentProcessorName: 'Stripe',
  transactionId: 'ch_1J2L3K4M5N6O7P8Q9R0S1T2U',
  precision: 2,
  currency: 'BGN',
  shopId: '1b5d1089-6f89-49bc-aad5-0c29404f44e2',
};

axios
  .post('https://api.takeanap.bg/public-api/v1/order', orderData)
  .then((response) => {
    console.log('Order created:', response.data);
  })
  .catch((error) => {
    console.error('Error creating order:', error);
  });

​

Headers

• x-api-key: Take a NAP API key
• x-signature: Signed payload with Take a NAP API secret

​

Request Body

Refer to the CreateOrderDto schema in the API reference.

​

Response

Refer to the OrderDto schema in the API reference.

​

Deleting an Order

Use the following endpoint to delete an order:

DELETE /public-api/v1/order/{id}

Please note that deleting an order will permanently remove all associated data, including the order details and any related receipts. This action is irreversible. If you need to modify an order, you must delete the existing order and create a new one with the updated information. Proceed with caution when performing this operation.

const axios = require('axios');

const url =
  'https://api.takeanap.bg/public-api/v1/order/27f48fed-17ba-47a1-89fc-6314af015e4a';

axios
  .delete(url)
  .then((response) => {
    console.log('Order deleted successfully');
  })
  .catch((error) => {
    console.error('Error deleting order:', error);
  });

​

Headers

• x-api-key: Take a NAP API key
• x-signature: Signed payload with Take a NAP API secret

​

Request Body

None

​

Response

Refer to the DeleteOrderResponseDto schema in the API reference.

​

How are totals and subtotals calculated?

​

Line Item Calculations

• Price: The price of an item is calculated based on the unit price.
• Net Price: The net price of an item is calculated by subtracting the VAT rate from the price.
• Subtotal Net: The net subtotal of an item is calculated by multiplying the net price by the quantity.
• Price VAT: The VAT for the price of an item is calculated by subtracting the net price from the price.
• Subtotal VAT: The VAT for the subtotal of an item is calculated by multiplying the VAT for the price by the quantity. If a discount is applied, the VAT for the discount is subtracted from the subtotal VAT.
• Subtotal: The subtotal for an item is calculated by multiplying the price by the quantity. If a discount is applied, the discount including VAT is subtracted from the subtotal.

​

Order Calculations

• Total: The total for the order is calculated by summing the subtotals of all items.
• Net Total: The net total for the order is calculated by subtracting the total VAT from the total.
• Total VAT: The total VAT for the order is calculated by summing the VAT for the subtotals of all items.
• Total Discount: The total discount for the order is calculated by summing the discounts for all items.

​

Discount Calculation

• Discounts are applied by subtotal, affecting how the discount is subtracted in the calculations for subtotal, subtotal VAT, and total discount.

​

Currency and Precision

• Calculations are done with specified currency and precision, ensuring accurate and consistent results.