ES | EN

📄 MIPYME Documents

Create a new document

POST
Endpoint URL https://api-billing.koywe.com/V1/documents
Requires authentication

Authentication

Send header Authorization: Bearer <token> (obtained from POST /auth) for protected endpoints.

Parameters

NameLocationTypeRequiredDescription
generate_stampqueryinteger—Generate the stamp image file (where applicable)

Request body — fields

FieldTypeRequiredDescription
optionsobjectOptional—
options.draft_onlyintegerOptionalAllows generating the document in draft mode only, without sending it to the SII.
The document remains stored as not issued, useful for testing, validation, or internal review before final issuance.
VALID ONLY FOR CHILE
options.draft_previewintegerOptionalGenerates a preview of the document (base64) in draft mode without saving or sending it to the SII.
Allows reviewing the content, data, and layout of the document before final generation or issuance.
VALID ONLY FOR CHILE
options.send_emailenum(0, 1)OptionalAutomatically email the generated document to receiver_email. 1 = send (default), 0 = do not send. VALID ONLY FOR COLOMBIA.
options.template_idintegerOptionalIt corresponds to the ID of the print template for the document. If not provided, the default template will be used.
options.gross_valuesintegerOptionalThis field is only valid for electronic receipts (document_type_id = 39, Chile) and allows the values to be entered as gross amounts (including VAT) for the line items, with the total being directly calculated as the multiplication of the item prices by the quantities. The total calculated in this way will be slightly different from the one obtained by rounding the net amounts and calculating VAT on the net total. The amounts will be adjusted and saved as net values in Koywe, but respecting the rounding applied to the gross amounts.
options.rounding_typestringOptionalYou can input values as "net" or "gross".
Rounding on gross values will calculate the total value for each line including VAT, and then adjust the document's VAT totals to match the final amount.
Rounding on net values will calculate the multiplications of net values line by line, and then apply the VAT to the total net amount to get the VAT and the total.
options.company_webstringOptionalYou can enter a website URL, which will replace the one registered in the Koywe account data and will be reflected in the automatic email sent to the recipient. It must start with http:// or https://.
options.company_emailstringOptionalYou can enter an email, which will replace the one registered in the Koywe account data and will be reflected in the automatic email sent to the document recipient.
options.pdf_transfer_copyintegerOptionalWhen set to 1, the response will include in electronic_document the field document_transfer_copy_pdf with the transfer copy (copia cedible) PDF in base64. VALID ONLY FOR CHILE.
headerobjectOptional—
header.account_idintegerOptionalId of the associated account
header.document_type_idintegerAlways requiredDocument type ID according to document type table.
Chile :
2 = Factura electrónica
32 = Factura exenta electrónica
37 = Boleta electrónica
41 = Boleta exenta electrónica
54 = Guía de despacho electrónica
17 = Nota de débito electrónica
16 = Nota de crédito electrónica
46 = Factura exportación electrónica
47 = Nota de débito de exportación electrónica
48 = Nota de crédito de exportación electrónica
header.document_sequence_codestringOptionalIdentifies the document series, used to determine the document type and the branch or issuing point according to each country’s regulations. (ONLY Peru, Argentina and Colombia)
header.issue_datestring (date)Always requiredDocument issue date
Format: YYYY-MM-DD
header.document_numberintegerOptionalAllows defining the folio to be used for issuing the document. By default, this field should NOT be used, so the folio is automatically assigned by the sequence.
header.issuer_tax_id_codestringOptionalIssuer tax id code
header.issuer_tax_id_typestringOptionalIssuer tax id type
header.issuer_legal_namestringOptionalIssuer legal name
header.issuer_addressstringAlways requiredIssuer address
header.issuer_districtstringAlways requiredIssuer district name
header.issuer_citystringAlways requiredIssuer city name
header.issuer_country_idstringOptionalIssuer country id
header.issuer_phonestringAlways requiredIssuer phone number
header.issuer_activitystringAlways requiredIssuer economic activity
header.issuer_postalcodestringOptionalIssuer postal code
header.receiver_tax_id_codestringRequired when: invoices, credit notes, debit notes, named receipts, and exempt named receipts, and optional for other documentsRequired for invoices, credit notes, debit notes, named receipts, and exempt named receipts, and optional for other documents.
RUT without dots, with a hyphen
Format: NNNNNNNN-X
header.receiver_tax_id_typestringOptionalReceiver tax id type
header.receiver_legal_namestringRequired when: invoices, credit notes, debit notes, named receipts, and exempt named receiptsRequired for invoices, credit notes, debit notes, named receipts, and exempt named receipts. Optional for other documents.
Legal name of the document receiver.
header.receiver_addressstringAlways requiredRequired for invoices, credit notes, debit notes, named receipts, and exempt named receipts. Optional for other documents.
Address of the document receiver.
header.receiver_districtstringAlways requiredRequired for invoices, credit notes, debit notes, named receipts, and exempt named receipts. Optional for other documents.
District of the document receiver.
header.receiver_citystringAlways requiredRequired for invoices, credit notes, debit notes, named receipts, and exempt named receipts. Optional for other documents.
City of the document receiver.
header.receiver_phonestringAlways requiredRequired for invoices, credit notes, debit notes, named receipts, and exempt named receipts. Optional for other documents.
Phone of the document receiver.
header.receiver_activitystringAlways requiredRequired for invoices, credit notes, and debit notes.
Optional for other documents.
Receiver activity of the document receiver.
Named receipts should NOT include this field.
header.receiver_postalcodestringOptionalOptional postal code according to the national format.
header.receiver_state_idintegerOptionalRefers to the recipient's state. Empty if it doesn't apply. This is a required field on some countries, check the examples for your country
header.receiver_county_idstringOptionalRequired only for Colombia as it replaces receiver_city and receiver_district. Please check the county_id codes table in Colombia examples.
header.receiver_country_idintegerOptionalRefers to the recipient's country. If not provided, the default is the same country as the issuer. It is mainly used for export documents.
header.receiver_emailstringOptionalEmail for document sending.
header.payment_conditionsstringAlways requiredPayment dates separated by commas
0 = cash
30 = 30 days
0,30 = 50% cash, 50% in 30 days
0,30,60 = 33% cash, 33% in 30 days, 34% in 60 days.
header.seller_idintegerOptionalUser ID (Koywe) that will be assigned as the seller associated with the document.
header.currency_idintegerOptionalOnly for export documents.
Valid values according to the table in annexes.
header.exchange_rate_valueintegerOptionalOnly when currency_id is defined and its value is a foreign currency.
header.service_indicatorintegerOptionalIt is optional to complete for export documents.
Valid values:
1 = Invoice for periodic household services.
2 = Invoice for other periodic services.
3 = Service Invoice
4 = Hospitality Services
5 = International Land Transport Service
header.sale_modalityintegerOptionalOnly for export documents: optional.
Valid values:
1 = Sale agreed
2 = Under condition
3 = Free consignment
4 = Consignment with minimum sale
9 = No payment
header.sale_clauseintegerOptionalOnly for export documents: optional.
Valid values:
1 = CIF
2 = CFR
3 = EXW
4 = FAS
5 = FOB
6 = S/CL
9 = DDP
10 = FCA
11 = CPT
12 = CIP
17 = DAT
18 = DAP
8 = Other
header.guide_typeintegerOptionalRequired ONLY for dispatch guides.
1 = Operation constitutes sale
2 = Sales to be made
3 = Consignments
4 = Free delivery
5 = Internal transfers
6 = Other non-sale transfers
7 = Return guide
8 = Transfer for export (non-sale)
9 = Sale for export
header.transfer_typeintegerOptionalRequired ONLY for dispatch guides that are not internal transfers.
1 = Dispatch on behalf of the recipient
2 = Dispatch on behalf of the issuer to recipient's facilities
3 = Dispatch on behalf of the issuer to other facilities
header.branch_office_codestringOptionalThis field should only be completed for companies that use branches.
To issue from the head office, this field should NOT be entered.
The code entered must correspond to the 'internal code' entered in Koywe.
header.observationsstringOptionalEnter a observations. The observations field allows you to include additional information. Its use is optional and can serve different purposes, providing flexibility to customize the document with complementary data that facilitate communication between issuer and recipient.
header.deployment_observationsintegerOptional0 = do not include remark in XML or PDF
1 = include remark in XML and PDF
2 = include remark in PDF and do NOT include in XML
3 = include remark in XML and do NOT include in PDF
In all cases, regardless of its display, the remark will be saved in Koywe and will be visible in the document details on facto.cl.
If this option is not entered, the default value is considered to be 1, which will display the remark in the XML and PDF.
header.port_disembarkationstringOptionalEnter a port disembarkation.
header.port_embarkationstringOptionalEnter a port embarkation.
header.gross_weightstringOptionalEnter a gross weight.
header.shipping_addressstringOptionalEnter a shipping address.
header.additionalobjectOptional—
header.additional.mx_headerobjectOptional—
header.additional.mx_header.receiver_cfdi_usagestringOptionalTax usage according to Mexican CFDI usage codes. You can find all receiver_cfdi_usage codes on Mexico code table page.
header.additional.mx_shippingobjectOptional—
header.additional.mx_shipping.distancestringOptional—
header.additional.mx_shipping.transport_codestringOptional—
header.additional.mx_shipping.transport_method_namestringOptional—
header.additional.mx_shipping.transport_tax_id_typestringOptional—
header.additional.mx_shipping.transport_tax_id_codestringOptional—
header.additional.mx_shipping.transport_licensestringOptional—
header.additional.mx_shipping.originobjectOptional—
header.additional.mx_shipping.origin.tax_id_typestringOptional—
header.additional.mx_shipping.origin.tax_id_codestringOptional—
header.additional.mx_shipping.origin.date_timestring (date-time)Optional—
header.additional.mx_shipping.origin.address_state_idstringOptional—
header.additional.mx_shipping.origin.address_country_idstringOptional—
header.additional.mx_shipping.origin.address_postalcodestringOptional—
header.additional.mx_shipping.destinationobjectOptional—
header.additional.mx_shipping.destination.tax_id_typestringOptional—
header.additional.mx_shipping.destination.tax_id_codestringOptional—
header.additional.mx_shipping.destination.date_timestring (date-time)Optional—
header.additional.mx_shipping.destination.address_state_idstringOptional—
header.additional.mx_shipping.destination.address_country_idstringOptional—
header.additional.mx_shipping.destination.address_postalcodestringOptional—
header.additional.mx_shipping.merchandiseobjectOptional—
header.additional.mx_shipping.merchandise.total_weightstringOptional—
header.additional.mx_shipping.merchandise.sct_permission_codestringOptional—
header.additional.mx_shipping.merchandise.sct_permission_numberstringOptional—
header.additional.mx_shipping.merchandise.vehicle_configurationstringOptional—
header.additional.mx_shipping.merchandise.vehicle_weightstringOptional—
header.additional.mx_shipping.merchandise.vehicle_license_platestringOptional—
header.additional.mx_shipping.merchandise.vehicle_yearstringOptional—
header.additional.mx_shipping.merchandise.insurance_companystringOptional—
header.additional.mx_shipping.merchandise.insurance_identifierstringOptional—
header.additional.mx_shipping.merchandise.detailsarray<object>Optional—
header.additional.mx_shipping.merchandise.details[].product_codestringOptional—
header.additional.mx_shipping.merchandise.details[].descriptionstringOptional—
header.additional.mx_shipping.merchandise.details[].quantitystringOptional—
header.additional.mx_shipping.merchandise.details[].weightstringOptional—
header.additional.mx_exportsobjectOptional—
header.additional.mx_exports.termsstringOptional—
header.additional.mx_exports.exchange_ratenumber (float)Optional—
header.additional.mx_exports.totalintegerOptional—
header.additional.mx_exports.originobjectOptional—
header.additional.mx_exports.origin.address_streetstringOptional—
header.additional.mx_exports.origin.address_city_idstringOptional—
header.additional.mx_exports.origin.address_county_idstringOptional—
header.additional.mx_exports.origin.address_state_idstringOptional—
header.additional.mx_exports.origin.address_country_idstringOptional—
header.additional.mx_exports.origin.address_postalcodestringOptional—
header.additional.mx_exports.destinationobjectOptional—
header.additional.mx_exports.destination.tax_id_typestringOptional—
header.additional.mx_exports.destination.tax_id_codestringOptional—
header.additional.mx_exports.destination.address_streetstringOptional—
header.additional.mx_exports.destination.address_state_idstringOptional—
header.additional.mx_exports.destination.address_country_idstringOptional—
header.additional.mx_exports.destination.address_postalcodestringOptional—
header.additional.mx_exports.merchandiseobjectOptional—
header.additional.mx_exports.merchandise.detailsarray<object>Optional—
header.additional.mx_exports.merchandise.details[].customs_codestringOptional—
header.additional.mx_exports.merchandise.details[].customs_quantitystringOptional—
header.additional.mx_exports.merchandise.details[].skustringOptional—
header.additional.mx_exports.merchandise.details[].customs_measure_unitstringOptional—
header.additional.mx_exports.merchandise.details[].customs_unit_valuestringOptional—
header.additional.mx_exports.merchandise.details[].customs_total_valuestringOptional—
header.additional.co_headerobjectOptional—
header.additional.co_header.reported_payment_codeintegerOptionalReported payment code according to the DIAN payment codes of Colombia. You can find all reported_payment_code codes on the Colombia examples page. If this field is not sent, its default value will be "cash".
header.additional.pe_headerobjectOptional—
header.additional.pe_header.operation_typestringOptionalOperation type according to Peruvian SUNAT operation codes. You can find all operation_type codes on Peru examples page.
header.additional.ar_headerobjectOptional—
header.additional.ar_header.invoice_conceptintegerOptionalIndicates whether the invoice corresponds to products (1), services (2), or both (3).
header.additional.ar_header.items_quantityintegerOptionalRepresents the total number of line items included in the invoice.
header.additional.ar_header.service_date_fromstringOptionalIndicates the start date of the service period covered by the invoice.
header.additional.ar_header.service_date_tostringOptionalIndicates the end date of the service period covered by the invoice.
header.additional.ar_header.receiver_vat_condition_idstringOptionalIdentifies the VAT status of the receiver according to tax regulations.
header.additional.pe_retention_headerobjectOptional—
header.additional.pe_retention_header.pe_sunat_retention_system_codestringOptional—
header.additional.pe_retention_header.pe_sunat_retention_percentnumberOptional—
header.additional.pe_retention_header.pe_sunat_total_paidnumberOptional—
header.additional.pe_shippingobjectOptional—
header.additional.pe_shipping.handling_codestringOptionalIt corresponds to the reason for the transfer, being a sale (1), a purchase (2), or other reasons (13).
header.additional.pe_shipping.special_instructionsintegerOptionalThis field contains specific SUNAT transport indicators that define particular shipping or logistics conditions, such as total transfer, vehicle return, subcontracted transport, or freight payer details.
1 = SUNAT_Envio_IndicadorTrasladoTotal - Corresponds to the indicator for the total transfer of goods.

2 = SUNAT_Envio_IndicadorRetornoVehiculoEnvaseVacio – Corresponds to the indicator for the return of a vehicle carrying empty containers or packaging.

3 = SUNAT_Envio_IndicadorRetornoVehiculoVacio – Corresponds to the indicator for the return of an empty vehicle.

4 = SUNAT_Envio_IndicadorTransbordoProgramado – Corresponds to the indicator for a scheduled transshipment.

5 = SUNAT_Envio_IndicadorTrasporteSubcontratado – Subcontracted transport indicator: corresponds to the indicator for the total transfer of the DAM or DS.

6 = SUNAT_Envio_IndicadorPagadorFlete_Remitente – Indicator for freight payer: sender.

7 = SUNAT_Envio_IndicadorPagadorFlete_Subcontratador – Indicator for freight payer: subcontractor.

8 = SUNAT_Envio_IndicadorPagadorFlete_Tercero – Indicator for freight payer: third party.

9 = SUNAT_Envio_IndicadorTrasladoVehiculoM1L – Indicates whether the transport is carried out using a light vehicle classified under category M1 or L, according to SUNAT transport regulations.
header.additional.pe_shipping.handling_instructionsstringOptionalDescription of the reason for transfer.
header.additional.pe_shipping.gross_weight_measurestringOptionalRefers to the total gross weight of the shipment, including the weight of goods, packaging, and any containers.
header.additional.pe_shipping.gross_weight_measure_idstringOptionalIdentifies the unit of measurement used for the gross weight, such as kilograms (KG) or tons (T). See more in the unit_measure table.
header.additional.pe_shipping.shipment_stageobjectOptional—
header.additional.pe_shipping.shipment_stage.transport_mode_codestringOptionalDefines whether the transport is public (01) or private (02). Other values are not accepted.
header.additional.pe_shipping.shipment_stage.transit_periodstringOptionalIndicates the estimated duration or time frame of the goods' transportation from origin to destination.
header.additional.pe_shipping.shipment_stage.driver_personobjectOptional—
header.additional.pe_shipping.shipment_stage.driver_person.driver_idstringOptionalRefers to the DNI number of the driver responsible for the transport.
header.additional.pe_shipping.shipment_stage.driver_person.first_namestringOptionalIndicates the driver's given name as registered for the transport operation.
header.additional.pe_shipping.shipment_stage.driver_person.family_namestringOptionalIndicates the driver’s last name or surname as registered for the transport operation.
header.additional.pe_shipping.shipment_stage.driver_person.identity_document_referencestringOptionalRefers to the driver’s license code or identification document number used to authorize the transport operation.
header.additional.pe_shipping.shipment_stage.carrier_partyobjectOptional—
header.additional.pe_shipping.shipment_stage.carrier_party.party_identificationstringOptionalIdentifies the carrier entity responsible for the transportation service, typically using a tax identification number (e.g., RUC)
header.additional.pe_shipping.shipment_stage.carrier_party.party_legal_entity_namestringOptionalSpecifies the legal name of the carrier company responsible for the transportation service.
header.additional.pe_shipping.shipment_stage.carrier_party.party_legal_entity_idstringOptionalThe code of the ‘Authorized issuing entity – carrier’.
header.additional.pe_shipping.shipment_stage.carrier_party.agent_party_idstringOptional—
header.additional.pe_shipping.deliveryobjectOptional—
header.additional.pe_shipping.delivery.delivery_addressobjectOptional—
header.additional.pe_shipping.delivery.delivery_address.idstringOptionalCode identifying the delivery location, usually corresponding to the geographical code (UBIGEO) assigned by the Peruvian authority.
header.additional.pe_shipping.delivery.delivery_address.city_subdivision_namestringOptionalName of the urban subdivision or neighborhood (e.g., urbanization, residential area).
header.additional.pe_shipping.delivery.delivery_address.city_namestringOptionalName of the province or city where the delivery point is located.
header.additional.pe_shipping.delivery.delivery_address.country_subentitystringOptionalName of the department or region associated with the delivery address.
header.additional.pe_shipping.delivery.delivery_address.districtstringOptionalName of the district where the delivery location is situated.
header.additional.pe_shipping.delivery.delivery_address.address_linestringOptionalFull address or detailed description of the delivery point.
header.additional.pe_shipping.delivery.delivery_address.country_idstringOptionalNumeric or alphanumeric code representing the country (e.g., “83” for Peru).
header.additional.pe_shipping.delivery.dispatchobjectOptional—
header.additional.pe_shipping.delivery.dispatch.idstringOptionalCode identifying the dispatch location, usually corresponding to the geographical code (UBIGEO) assigned by the Peruvian authority.
header.additional.pe_shipping.delivery.dispatch.city_subdivision_namestringOptionalName of the urban subdivision or neighborhood (e.g., urbanization, residential area) where the dispatch point is located.
header.additional.pe_shipping.delivery.dispatch.city_namestringOptionalName of the province or city from which the goods are dispatched.
header.additional.pe_shipping.delivery.dispatch.country_subentitystringOptionalName of the department or region associated with the dispatch address.
header.additional.pe_shipping.delivery.dispatch.districtstringOptionalName of the district where the dispatch location is situated.
header.additional.pe_shipping.delivery.dispatch.address_linestringOptionalFull address or detailed description of the dispatch point.
header.additional.pe_shipping.delivery.dispatch.country_idstringOptionalNumeric or alphanumeric code representing the country (e.g., “83” for Peru).
header.additional.pe_shipping.transport_handling_unitobjectOptional—
header.additional.pe_shipping.transport_handling_unit.transport_equipment_idstringOptionaldentifies the code or license plate number of the transport equipment (e.g., truck, trailer, or container) used to move the goods.
detailsarray<object>Optional—
details[].quantitynumber (float)Always requiredQuantity (can have up to 6 decimals, separate with a dot, not with a comma).
details[].skustringOptionalUnique internal SKU that identifies the product
details[].line_descriptionstringAlways requiredShort description to be included in the invoice as line title. Max 100 chars.
details[].unit_pricenumber (float)Always requiredUnit price (can have up to 6 decimals, separate with a dot, not with a comma). If using the 'gross_values' option, it must be the value including VAT.
details[].long_descriptionstringOptionalAllows adding an additional long description to the detail description for the document.
details[].unit_measurestringAlways requiredUnit that this line is measured in.
details[].modifier_amountnumberOptionalAmount to discount or surcharge.
If it is a discount, use a negative value.
If this is used, do not use discount_or_surcharge_percentage.
details[].modifier_percentagenumber (float)OptionalPercentage to discount or surcharge. If it is a discount, use a negative value. If this is used, do not use discount_or_surcharge_amount.
details[].total_taxesnumber (float)OptionalTotal taxes for this line.
details[].total_amount_linenumber (float)Always requiredTotal amount for this line, including taxes and modifiers.
details[].taxesarray<object>Optional—
details[].taxes[].tax_type_idstringAlways requiredIdentifier of the tax type.
details[].taxes[].tax_percentagenumber (float)Always requiredPercentage of the tax.
details[].taxes[].tax_amountnumber (float)Always requiredAmount of the tax.
details[].additionalobjectOptional—
details[].additional.mx_detailobjectOptionalThese are additional fields you will need to use when adding details to your documents in Mexico
details[].additional.mx_detail.product_service_identifierstringOptionalThis is the SAT code for the product or service you are buying/selling for tax purposes. Please see the SAT website for coding. If ommited, the generic code 01010101 will be used
details[].additional.mx_detail.measure_unit_codestringOptionalThis is the SAT code for the measurement unit of this product or service. Please check the SAT website for codes. If ommited, the generic code E48 will be used
referencesarray<object>Optional—
references[].document_type_idintegerOptionalDocument type of the referenced document.
references[].reference_typeintegerOptionalChile: Otros documentos que no son documentos
tributarios electrónicos: (debe usarse código
referencia = 5)
801 = Orden de compra
802 = Nota de pedido
803 = Contrato
804 = Resolución
805 = Proceso ChileCompra
806 = Ficha ChileCompra
807 = DUS
808 = B/L (Conocimiento de embarque)
809 = AWB (Air Will Bill)
810 = MIC/DTA
811 = Carta de Porte
812 = Resolución del SNA donde califica
Servicios de Exportación
813 = Pasaporte
814 = Certificado de Depósito Bolsa Prod. Chile.
815 = Vale de Prenda Bolsa Prod.
references[].reference_numberstringOptionalEnter the document_number to reference: use reference_number or reference_document_id, but never both together. In the case of a global reference, it must be 0.
references[].reference_document_idintegerOptionalEnter the document_id to reference: use reference_document_id or reference_number, but never both together.
references[].reference_codeintegerAlways required1 = cancel
2 = correct text
3 = correct quantity
4 = set
5 = reference to other non-tax documents
6 = reference to dispatch guide
7 = global reference to a type of document (allows reducing the amount for all documents of this type for this particular client).
references[].descriptionstringAlways requiredReference description.
references[].reference_datestring (date)OptionalIt should only be entered when using a reference that is not an electronic tax document. (YYYY-MM-DD).
references[].additionalobjectOptional—
references[].additional.pe_retention_detailsobjectOptional—
references[].additional.pe_retention_details.reference_paid_amountnumberOptional—
references[].additional.pe_retention_details.reference_total_invoice_amountnumberOptional—
references[].additional.pe_retention_details.reference_paid_datestring (date)Optional—
references[].additional.pe_retention_details.reference_payment_idstringOptional—
references[].additional.pe_retention_details.pe_reference_sunat_retention_amountnumberOptional—
references[].additional.pe_retention_details.pe_reference_sunat_retention_datestring (date)Optional—
references[].additional.pe_retention_details.calculation_ratenumberOptional—
references[].additional.pe_retention_details.currency_idstringOptional—
globals_discounts_surchargesarray<object>Optional—
globals_discounts_surcharges[].discount_surcharge_codestringAlways requiredDA = Global discount on taxable
DE = Global discount on exempt
RA = Global surcharge on taxable
RE = Global surcharge on exempt
globals_discounts_surcharges[].discount_surcharge_valueinteger (float)Always requiredValue of the discount or surcharge.
globals_discounts_surcharges[].discount_surcharge_typestringAlways required$ = Value will be applied as an amount
% = Value will be applied as a percentage of the amount
totalsobjectOptional—
totals.vat_credit_construction_companyintegerOptional65% credit for construction companies. Article 21 of Decree Law No. 910/75.
This is the only code that operates in the opposite manner to the rest, as it is subtracted from the general VAT. It corresponds to VAT * 0.65.
NOT supported in the case of 'gross_values' (Chile).
totals.net_amountintegerAlways requiredRequired, except in the case of gross values.
Total value of taxable items. It should NOT be entered if using the 'gross_values' option.
totals.taxes_amountintegerOptionalSum of other taxes, can be negative if there are withholding taxes. NOT supported in the case of 'gross_values'.
totals.total_amountintegerAlways requiredFinal value.
payment_linkobjectOptional—
payment_link.payment_urlstringOptionalURL of the payment link for the document if you want to provide it yourself to be included in the document.

Request body — JSON example

{
    "options": {
        "draft_only": 0,
        "draft_preview": 0,
        "send_email": 1,
        "template_id": 0,
        "gross_values": "1",
        "rounding_type": "net",
        "company_web": "https://www.company.com/",
        "company_email": "[email protected]",
        "pdf_transfer_copy": 1
    },
    "header": {
        "account_id": "141",
        "document_type_id": "2",
        "document_sequence_code": "F001",
        "issue_date": "string",
        "document_number": 0,
        "issuer_tax_id_code": "string",
        "issuer_tax_id_type": "string",
        "issuer_legal_name": "string",
        "issuer_address": "string",
        "issuer_district": "string",
        "issuer_city": "string",
        "issuer_country_id": "string",
        "issuer_phone": "string",
        "issuer_activity": "string",
        "issuer_postalcode": "string",
        "receiver_tax_id_code": "11111111-1",
        "receiver_tax_id_type": "string",
        "receiver_legal_name": "string",
        "receiver_address": "string",
        "receiver_district": "string",
        "receiver_city": "string",
        "receiver_phone": "string",
        "receiver_activity": "string",
        "receiver_postalcode": "string",
        "receiver_state_id": 0,
        "receiver_county_id": "string",
        "receiver_country_id": 0,
        "receiver_email": "string",
        "payment_conditions": "string",
        "seller_id": 0,
        "currency_id": 0,
        "exchange_rate_value": 0,
        "service_indicator": 0,
        "sale_modality": 0,
        "sale_clause": 0,
        "guide_type": 0,
        "transfer_type": 0,
        "branch_office_code": "string",
        "observations": "string",
        "deployment_observations": 0,
        "port_disembarkation": "string",
        "port_embarkation": "string",
        "gross_weight": "string",
        "shipping_address": "string",
        "additional": {
            "mx_header": {
                "receiver_cfdi_usage": "string"
            },
            "mx_shipping": {
                "distance": "100",
                "transport_code": "01",
                "transport_method_name": "Autotransporte",
                "transport_tax_id_type": "MX-RFC",
                "transport_tax_id_code": "EKU9003173C9",
                "transport_license": "a234567890",
                "origin": {
                    "tax_id_type": "...",
                    "tax_id_code": "...",
                    "date_time": "...",
                    "address_state_id": "...",
                    "address_country_id": "...",
                    "address_postalcode": "..."
                },
                "destination": {
                    "tax_id_type": "...",
                    "tax_id_code": "...",
                    "date_time": "...",
                    "address_state_id": "...",
                    "address_country_id": "...",
                    "address_postalcode": "..."
                },
                "merchandise": {
                    "total_weight": "...",
                    "sct_permission_code": "...",
                    "sct_permission_number": "...",
                    "vehicle_configuration": "...",
                    "vehicle_weight": "...",
                    "vehicle_license_plate": "...",
                    "vehicle_year": "...",
                    "insurance_company": "...",
                    "insurance_identifier": "...",
                    "details": "..."
                }
            },
            "mx_exports": {
                "terms": "FOB",
                "exchange_rate": 20.6708,
                "total": 1624,
                "origin": {
                    "address_street": "...",
                    "address_city_id": "...",
                    "address_county_id": "...",
                    "address_state_id": "...",
                    "address_country_id": "...",
                    "address_postalcode": "..."
                },
                "destination": {
                    "tax_id_type": "...",
                    "tax_id_code": "...",
                    "address_street": "...",
                    "address_state_id": "...",
                    "address_country_id": "...",
                    "address_postalcode": "..."
                },
                "merchandise": {
                    "details": "..."
                }
            },
            "co_header": {
                "reported_payment_code": 0
            },
            "pe_header": {
                "operation_type": "string"
            },
            "ar_header": {
                "invoice_concept": 0,
                "items_quantity": 0,
                "service_date_from": "string",
                "service_date_to": "string",
                "receiver_vat_condition_id": "string"
            },
            "pe_retention_header": {
                "pe_sunat_retention_system_code": "string",
                "pe_sunat_retention_percent": 0,
                "pe_sunat_total_paid": 0
            },
            "pe_shipping": {
                "handling_code": "string",
                "special_instructions": 0,
                "handling_instructions": "string",
                "gross_weight_measure": "string",
                "gross_weight_measure_id": "string",
                "shipment_stage": {
                    "transport_mode_code": "...",
                    "transit_period": "...",
                    "driver_person": "...",
                    "carrier_party": "..."
                },
                "delivery": {
                    "delivery_address": "...",
                    "dispatch": "..."
                },
                "transport_handling_unit": {
                    "transport_equipment_id": "..."
                }
            }
        }
    },
    "details": [
        {
            "quantity": 0,
            "sku": "string",
            "line_description": "string",
            "unit_price": 0,
            "long_description": "string",
            "unit_measure": "string",
            "modifier_amount": 0,
            "modifier_percentage": 0,
            "total_taxes": 0,
            "total_amount_line": 0,
            "taxes": [
                {
                    "tax_type_id": "...",
                    "tax_percentage": "...",
                    "tax_amount": "..."
                }
            ],
            "additional": {
                "mx_detail": {
                    "product_service_identifier": "...",
                    "measure_unit_code": "..."
                }
            }
        }
    ],
    "references": [
        {
            "document_type_id": 0,
            "reference_type": 0,
            "reference_number": "string",
            "reference_document_id": 0,
            "reference_code": 0,
            "description": "string",
            "reference_date": "string",
            "additional": {
                "pe_retention_details": {
                    "reference_paid_amount": "...",
                    "reference_total_invoice_amount": "...",
                    "reference_paid_date": "...",
                    "reference_payment_id": "...",
                    "pe_reference_sunat_retention_amount": "...",
                    "pe_reference_sunat_retention_date": "...",
                    "calculation_rate": "...",
                    "currency_id": "..."
                }
            }
        }
    ],
    "globals_discounts_surcharges": [
        {
            "discount_surcharge_code": "string",
            "discount_surcharge_value": 0,
            "discount_surcharge_type": "string"
        }
    ],
    "totals": {
        "vat_credit_construction_company": 0,
        "net_amount": 0,
        "taxes_amount": 0,
        "total_amount": 0
    },
    "payment_link": {
        "payment_url": "string"
    }
}

Responses

Document created successfully