Create a middleware to issue tax coupons for inStore
A middleware is a software that acts as a bridge connecting the module that issues the tax coupon with the inStore system. It is usually installed in the store's network and needs to contain the following endpoints to receive the information sent by VTEX servers:
- Endpoint to receive the orders from VTEX to invoice them.
- Endpoint to issue the return invoice.
These endpoints must be sent to our Support for the inStore team to configure them in the store that wants to install the middleware.
Billing endpoints
The two billing endpoints required will either be on a machine with a fixed IP in the store itself or on an open HTTPS
endpoint on the Internet.
When implementing the billing endpoint, ensure that it can receive requests for the POST
method from VTEX. The body sent by VTEX will be equivalent to the Get order response body, with the addition of the following information:
Request body example
{
ā¦
"items": [...],
"id": "1234568358",
"type": "Input"
}
Attribute | Description |
type
|
Defines the type of the endpoint, if it is a billing ("Output" ) or if it is a return ("Input" ).
|
items
|
If "type": "Input" , it shows which products were returned.
|
id
|
If "type": "Input" , it indicates whether the return was successful.
|
After this step, you must invoice the order with the Receita Federal (brazilian equivalent of IRS) using the response from the POST
endpoint and send the tax coupon file and the coupon number within a JSON to VTEX in the following format:
{
"invoiceNumber": "123456789",
"invoiceUrl": "https://www.taxcoupon.com",
"printUrl": "https://www.taxcoupon.com",
"shouldPrintInvoice": true
}
Attribute | Description |
|
Tax coupon number. Mandatory field. |
|
Link following the 'https://' protocol that identifies the tax coupon. It can be used to print the tax coupon if the field printUrl is not sent. Mandatory field.
|
|
'https://' link or file path with the tax coupon that will be printed. If this field is sent empty the field invoiceUrl will be printed instead.
|
|
Indicates to the inStore that it should print the file. This is a boolean an the default value is true .
|
Once receiving the response for both billing and return scenarios, inStore saves the tax invoice in VTEXās OMS and changes the order's status to the Invoiced status.
When returning an error code - as 4xx
or 5xx
- together with the previous JSON (both for billing and return), inStore understands that there was a billing error and warns the seller to take appropriate action.
{
"message": "Contains an explanation of the invoice error"
}
Data required to issue the tax coupon
To issue the tax coupon with name and value of the product, type and receipt of card payments, NCM and ICMS of each product, customer's email and name, you must get the following information from the Get order response body:
items
paymentData.transactions.payments
customData.customApps.fields
TaxCode
clientProfileData
It is possible that the customer makes the purchase anonymously. To confirm this, simply check if the
clientProfileData.firstName
field has theisAnonymous
value in the order JSON. In this case, you cannot send the tax coupon by email.
inStore customization
To customize the inStore devices to send requests to the correct IP, you need to edit inStore's JavaScript file.
At the beginning of the file, insert the following code by replacing the IP_GLOBAL
variable's value with the printer IP:
var IP_GLOBAL = 'XX.Y.ZZ.AA'
window.ORDER_PLACED_HOOK_GLOBAL = {
url: 'http://' + IP_GLOBAL + ':6061/invoice-order',
cancelUrl: 'http://' + IP_GLOBAL + ':6061/invoice-order',
invoiceEndpoints: {
Output: 'http://' + IP_GLOBAL + ':6060/api/vtex/order',
Input: 'http://' + IP_GLOBAL + ':6060/api/vtex/cancela',
},
}
Add a reference of the above configuration in the orderPlacedHook
variable:
window.INSTORE_CONFIG = {
payments: window.PAYMENTS_FILTER_GLOBAL,
orderPlacedHook: window.ORDER_PLACED_HOOK_GLOBAL,
}
With this customization, inStore will request the printing of the tax coupon with the integrated biller.
Device pairing
inStore does not require a fixed IP for the invoice, allowing inStore devices to communicate between themselves through pairing performed in the inStore menu Configure device option.
With this option to configure inStore billing, perform the same IP configuration, but the IP_GLOBAL
value will always take precedence:
var IP_GLOBAL = 'localhost'
This means that it will always communicate with the biller through the same machine since the dispatch would be done between inStore devices. Check a complete JSON example of a order.
Updated 21 days ago