Overview
The /dte/facturas route allows you to create an invoice (factura) for your business by sending the required data. The invoice is processed and sent to Hacienda, and a response is provided indicating success or failure.
Request Details
URL: https://api.smartbill.lat/v1/dte/factura
HTTP Method: POST
Headers:
- Content-Type: application/json
- X-Smartbill-Public-Key: API Public key
- X-Smartbill-Private-Key: API private key
Structure
In the body of the request, you will need to include the structure for "dteJson". This key acts as the container for the invoice details, ensuring that Smartbill can accurately process the request and generate the corresponding document.
Receptor
This section contains information about the recipient of the invoice. It includes basic details such as the name, identification number, phone, email, and address of the receptor.
In cases where the recipient prefers not to provide specific information, you can simply send the value as the string "Others". Smartbill will automatically populate the necessary details as if the recipient were a generic client, ensuring the process continues smoothly.
documentType
string
Required
Type of the document of the client who recieves the document
identification
string
Required
The value representing the document of the recipient.
name
string
Required
The full name of the recipient.
string | null
The email address of the recipient, where the client will receive the sent document.
address
Object | null
This value is optional. It is an object containing the department, town, district and details of the recipient's address. When it is not sent, San Salvador Centro / San Salvador is used.
departament
string
“Departamento” refers to the recipient's department. This value is a string and must match one of the codes from the departments list, which can be found on the Resources page.
town
string
Refers to the recipient's “municipio” (2024 territorial division, e.g. "23" for San Salvador Centro). This value is a string and must match one of the codes from the municipio list, which can be found in the Departaments file on the Resources page. Municipio codes from before the 2024 reform are still accepted and are converted automatically to the new municipio and district.
district
string | null
Refers to the recipient's “distrito” inside the municipio. Must match one of the district codes of that municipio (Departaments file on the Resources page). If it is not sent or is not valid, Smartbill uses the first district of the municipio.
details
string
Specifies the detailed location address of the recipient.
phone
string | null
The phone number of the recipient.
retainsRenta
boolean | null
Indicates whether the recipient will retain 10% of the rent. Hacienda currently does not allow renta retention on facturas, so sending true returns an error.
taxPayerType
string | null
Indicates whether the recipient is a “big contributor” or a “small contributor.” By default, it is set to “small.” If set to “big,” the application will handle the necessary calculations for processing the 1% IVA retention.
Products
This section contains information about the products of the invoice. It includes basic information as unit price, description and quantity.
Also the products is an Array of values, so you can add multiple items.
Max 500 characters
description
string
Required
A brief description of the product or service.
sellType
string
Required
Refers to whether the product/service is “gravada,” “exenta,” or “no sujeta.” If “exenta” or “no sujeta” is selected, the system will automatically exclude the IVA from the product.
itemType
string
Required
Specifies whether the item is a product or a service or boths
unitPrice
number
Required
Sets the unit price of the item.
quantity
number
Required
Sets the amount of the product(s) for the item.
unit
number | null
Sets the unit type of the product. This value must match one of the codes from the list of unit types found in the Resources page.
tributes
string[] | null
This is an array of strings where you must add the code(s) of the tribute(s) that you want to include as part of the item. The list of available tribute codes can be found on the Resources page.
hasRenta
boolean | null
Specifies whether the item retains 10% of rent. This value is informational: the 10% is calculated and saved with the document for your Smartbill reports, but it is not deducted from totalPagar, since Hacienda's current structure has no renta retention for this document.
descuAmount
number | null
Specifies whether the item has a discount. This value is a number.
Apendice / Not required
This section is intended only for cases involving work with the government through a bidding process. The data or configurations described here are not required for standard requests and should only be included if explicitly needed to meet the requirements of the bidding process. If this does not apply to your case, this section can be omitted.
In case you use this section, make sure to fill in all three values.
tag
string
Refers to the “Etiqueta” value provided by the government.
value
string
Refers to the "Valor" value provided by the government.
field
string
Refers to the “Campo” value provided by the government.
Extension / Not required
This section is used only if you need to add extra values to the document, such as specifying the name and document number of the person receiving the document.
docuEntrega
string | null
The document number of the person issuing the DTE.
nombEntrega
string | null
The name of the person issuing the DTE.
nombRecibe
string | null
The name of the person receiving the document.
docuRecibe
string | null
The document number of the person receiving the DTE.
placaVehiculo
string | null
The plate number of the vehicle transporting the product.
otrosDocumentos / Not required
In this section, you can include any additional documents, such as a “carnet de exento,” an insurance policy, or any other document you want to attach to your document.
name
string
Required
The name of the document you want to attach
value
string
Required
The value of the extra document
payment / Not required
In this section, you can specify the type of payment. If the payment type is “credit,” you can also provide the time extension for these payments.
type
string
Specifies whether the payment is made as “contado” (a single payment) or as “credit” (multiple payments).
timeFormat
string
Specifies whether the payment schedule is based on days, months, or years.
duration
number
Specifies the length of the payment schedule in terms of days, months, or years.
propina / Not required
This section is used only if you want to include the value of a tip, which will be added to the total of the document.
propina
number | null
The value of the total tip that will be added.
Emission date / Not required
By default the factura is issued with the current date and time in El Salvador. Send day and time only if you need a different emission date.
day
number | null
Day of the current month, for example 15. Must be a whole number between 1 and today's day. If it is not sent, today is used.
time
string | null
Emission time in 24 hour format "HH:mm:ss", El Salvador time, for example "14:30:00". It can be sent with or without day. If it is not sent, the current time is used. When the document is dated today, it cannot be later than the current time.
Example
This section demonstrates how easily you can create a “factura” by simply specifying the recipient as “others” in the JSON and including only the basic information for each item.
Response
In this section, you can see two types of responses: a successful response and an error response. Both types share the same structure