📄 MIPYME Documents

Create a new document

POST

Endpoint URL https://apifacto.com/v1/documents

Requires authentication

Authentication

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

Parameters

Name	Location	Type	Required	Description
`generate_stamp`	`query`	integer	—	Generate the stamp image file (where applicable)

Request body — fields

Field	Type	Required	Description
`options`	object	Optional	—
`options.draft_only`	integer	Optional	Allows 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_preview`	integer	Optional	Generates 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_email`	enum(0, 1)	Optional	Automatically email the generated document to receiver_email. 1 = send (default), 0 = do not send. VALID ONLY FOR COLOMBIA.
`options.template_id`	integer	Optional	It corresponds to the ID of the print template for the document. If not provided, the default template will be used.
`options.gross_values`	integer	Optional	This 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_type`	string	Optional	You 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_web`	string	Optional	You 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_email`	string	Optional	You 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_copy`	integer	Optional	When 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.
`header`	object	Optional	—
`header.account_id`	integer	Optional	Id of the associated account
`header.document_type_id`	integer	Always required	Document 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_code`	string	Optional	Identifies 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_date`	string (date)	Always required	Document issue date Format: YYYY-MM-DD
`header.document_number`	integer	Optional	Allows 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_code`	string	Optional	Issuer tax id code
`header.issuer_tax_id_type`	string	Optional	Issuer tax id type
`header.issuer_legal_name`	string	Optional	Issuer legal name
`header.issuer_address`	string	Always required	Issuer address
`header.issuer_district`	string	Always required	Issuer district name
`header.issuer_city`	string	Always required	Issuer city name
`header.issuer_country_id`	string	Optional	Issuer country id
`header.issuer_phone`	string	Always required	Issuer phone number
`header.issuer_activity`	string	Always required	Issuer economic activity
`header.issuer_postalcode`	string	Optional	Issuer postal code
`header.receiver_tax_id_code`	string	Required when: invoices, credit notes, debit notes, named receipts, and exempt named receipts, and optional for other documents	Required 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_type`	string	Optional	Receiver tax id type
`header.receiver_legal_name`	string	Required when: invoices, credit notes, debit notes, named receipts, and exempt named receipts	Required for invoices, credit notes, debit notes, named receipts, and exempt named receipts. Optional for other documents. Legal name of the document receiver.
`header.receiver_address`	string	Always required	Required for invoices, credit notes, debit notes, named receipts, and exempt named receipts. Optional for other documents. Address of the document receiver.
`header.receiver_district`	string	Always required	Required for invoices, credit notes, debit notes, named receipts, and exempt named receipts. Optional for other documents. District of the document receiver.
`header.receiver_city`	string	Always required	Required for invoices, credit notes, debit notes, named receipts, and exempt named receipts. Optional for other documents. City of the document receiver.
`header.receiver_phone`	string	Always required	Required for invoices, credit notes, debit notes, named receipts, and exempt named receipts. Optional for other documents. Phone of the document receiver.
`header.receiver_activity`	string	Always required	Required 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_postalcode`	string	Optional	Optional postal code according to the national format.
`header.receiver_state_id`	integer	Optional	Refers 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_id`	string	Optional	Required only for Colombia as it replaces receiver_city and receiver_district. Please check the county_id codes table in Colombia examples.
`header.receiver_country_id`	integer	Optional	Refers 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_email`	string	Optional	Email for document sending.
`header.payment_conditions`	string	Always required	Payment 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_id`	integer	Optional	User ID (Koywe) that will be assigned as the seller associated with the document.
`header.currency_id`	integer	Optional	Only for export documents. Valid values according to the table in annexes.
`header.exchange_rate_value`	integer	Optional	Only when currency_id is defined and its value is a foreign currency.
`header.service_indicator`	integer	Optional	It 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_modality`	integer	Optional	Only 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_clause`	integer	Optional	Only 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_type`	integer	Optional	Required 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_type`	integer	Optional	Required 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_code`	string	Optional	This 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.observations`	string	Optional	Enter 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_observations`	integer	Optional	0 = 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_disembarkation`	string	Optional	Enter a port disembarkation.
`header.port_embarkation`	string	Optional	Enter a port embarkation.
`header.gross_weight`	string	Optional	Enter a gross weight.
`header.shipping_address`	string	Optional	Enter a shipping address.
`header.additional`	object	Optional	—
`header.additional.mx_header`	object	Optional	—
`header.additional.mx_header.receiver_cfdi_usage`	string	Optional	Tax usage according to Mexican CFDI usage codes. You can find all receiver_cfdi_usage codes on Mexico code table page.
`header.additional.mx_shipping`	object	Optional	—
`header.additional.mx_shipping.distance`	string	Optional	—
`header.additional.mx_shipping.transport_code`	string	Optional	—
`header.additional.mx_shipping.transport_method_name`	string	Optional	—
`header.additional.mx_shipping.transport_tax_id_type`	string	Optional	—
`header.additional.mx_shipping.transport_tax_id_code`	string	Optional	—
`header.additional.mx_shipping.transport_license`	string	Optional	—
`header.additional.mx_shipping.origin`	object	Optional	—
`header.additional.mx_shipping.origin.tax_id_type`	string	Optional	—
`header.additional.mx_shipping.origin.tax_id_code`	string	Optional	—
`header.additional.mx_shipping.origin.date_time`	string (date-time)	Optional	—
`header.additional.mx_shipping.origin.address_state_id`	string	Optional	—
`header.additional.mx_shipping.origin.address_country_id`	string	Optional	—
`header.additional.mx_shipping.origin.address_postalcode`	string	Optional	—
`header.additional.mx_shipping.destination`	object	Optional	—
`header.additional.mx_shipping.destination.tax_id_type`	string	Optional	—
`header.additional.mx_shipping.destination.tax_id_code`	string	Optional	—
`header.additional.mx_shipping.destination.date_time`	string (date-time)	Optional	—
`header.additional.mx_shipping.destination.address_state_id`	string	Optional	—
`header.additional.mx_shipping.destination.address_country_id`	string	Optional	—
`header.additional.mx_shipping.destination.address_postalcode`	string	Optional	—
`header.additional.mx_shipping.merchandise`	object	Optional	—
`header.additional.mx_shipping.merchandise.total_weight`	string	Optional	—
`header.additional.mx_shipping.merchandise.sct_permission_code`	string	Optional	—
`header.additional.mx_shipping.merchandise.sct_permission_number`	string	Optional	—
`header.additional.mx_shipping.merchandise.vehicle_configuration`	string	Optional	—
`header.additional.mx_shipping.merchandise.vehicle_weight`	string	Optional	—
`header.additional.mx_shipping.merchandise.vehicle_license_plate`	string	Optional	—
`header.additional.mx_shipping.merchandise.vehicle_year`	string	Optional	—
`header.additional.mx_shipping.merchandise.insurance_company`	string	Optional	—
`header.additional.mx_shipping.merchandise.insurance_identifier`	string	Optional	—
`header.additional.mx_shipping.merchandise.details`	array<object>	Optional	—
`header.additional.mx_shipping.merchandise.details[].product_code`	string	Optional	—
`header.additional.mx_shipping.merchandise.details[].description`	string	Optional	—
`header.additional.mx_shipping.merchandise.details[].quantity`	string	Optional	—
`header.additional.mx_shipping.merchandise.details[].weight`	string	Optional	—
`header.additional.mx_exports`	object	Optional	—
`header.additional.mx_exports.terms`	string	Optional	—
`header.additional.mx_exports.exchange_rate`	number (float)	Optional	—
`header.additional.mx_exports.total`	integer	Optional	—
`header.additional.mx_exports.origin`	object	Optional	—
`header.additional.mx_exports.origin.address_street`	string	Optional	—
`header.additional.mx_exports.origin.address_city_id`	string	Optional	—
`header.additional.mx_exports.origin.address_county_id`	string	Optional	—
`header.additional.mx_exports.origin.address_state_id`	string	Optional	—
`header.additional.mx_exports.origin.address_country_id`	string	Optional	—
`header.additional.mx_exports.origin.address_postalcode`	string	Optional	—
`header.additional.mx_exports.destination`	object	Optional	—
`header.additional.mx_exports.destination.tax_id_type`	string	Optional	—
`header.additional.mx_exports.destination.tax_id_code`	string	Optional	—
`header.additional.mx_exports.destination.address_street`	string	Optional	—
`header.additional.mx_exports.destination.address_state_id`	string	Optional	—
`header.additional.mx_exports.destination.address_country_id`	string	Optional	—
`header.additional.mx_exports.destination.address_postalcode`	string	Optional	—
`header.additional.mx_exports.merchandise`	object	Optional	—
`header.additional.mx_exports.merchandise.details`	array<object>	Optional	—
`header.additional.mx_exports.merchandise.details[].customs_code`	string	Optional	—
`header.additional.mx_exports.merchandise.details[].customs_quantity`	string	Optional	—
`header.additional.mx_exports.merchandise.details[].sku`	string	Optional	—
`header.additional.mx_exports.merchandise.details[].customs_measure_unit`	string	Optional	—
`header.additional.mx_exports.merchandise.details[].customs_unit_value`	string	Optional	—
`header.additional.mx_exports.merchandise.details[].customs_total_value`	string	Optional	—
`header.additional.co_header`	object	Optional	—
`header.additional.co_header.reported_payment_code`	integer	Optional	Reported 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_header`	object	Optional	—
`header.additional.pe_header.operation_type`	string	Optional	Operation type according to Peruvian SUNAT operation codes. You can find all operation_type codes on the Peru examples page. For detraction invoices use 1001 (general), 1003 (passenger transport) or 1004 (cargo transport).
`header.additional.pe_detraction`	object	Optional	Required when the invoice is subject to SUNAT detraction (operation_type 1001, 1003 or 1004). See Peru examples.
`header.additional.pe_detraction.code`	string	Optional	SUNAT detraction catalog code. Examples: 022 general (1001), 028 passenger transport (1003), 027 cargo transport (1004).
`header.additional.pe_detraction.percent`	number	Optional	Detraction percentage applied to the invoice total.
`header.additional.pe_detraction.amount`	number	Optional	Detraction amount (typically percent of total_amount).
`header.additional.pe_detraction.nation_bank_account`	string	Optional	Banco de la Nación account number where the detraction is deposited.
`header.additional.pe_detraction.nation_bank_account_hide`	enum(true)	Optional	Optional. Send true to hide the Banco de la Nación account on the printed document (PDF). The account is still sent to SUNAT in the XML. Only true is accepted; any other value (including false) returns an error. Omit the field to print the account.
`header.additional.pe_detraction.payment_means_code`	string	Optional	SUNAT payment means code for the detraction. 001 = deposit to Banco de la Nación account.
`header.additional.pe_cargo_transport`	object	Optional	Required when operation_type is 1004 (cargo transport detraction). Omitting it causes E-Fact error 3116.
`header.additional.pe_cargo_transport.origin_ubigeo`	string	Optional	UBIGEO code of the cargo origin.
`header.additional.pe_cargo_transport.origin_address`	string	Optional	Detailed address of the cargo origin.
`header.additional.pe_cargo_transport.destination_ubigeo`	string	Optional	UBIGEO code of the cargo destination.
`header.additional.pe_cargo_transport.destination_address`	string	Optional	Detailed address of the cargo destination.
`header.additional.pe_cargo_transport.trip_detail`	string	Optional	Description of the trip.
`header.additional.pe_cargo_transport.service_reference_amount`	number	Optional	Reference amount of the transport service.
`header.additional.pe_cargo_transport.effective_load_reference_amount`	number	Optional	Reference amount of the effective load.
`header.additional.pe_cargo_transport.payload_reference_amount`	number	Optional	Reference amount of the payload.
`header.additional.ar_header`	object	Optional	—
`header.additional.ar_header.invoice_concept`	integer	Optional	Indicates whether the invoice corresponds to products (1), services (2), or both (3).
`header.additional.ar_header.items_quantity`	integer	Optional	Represents the total number of line items included in the invoice.
`header.additional.ar_header.service_date_from`	string	Optional	Indicates the start date of the service period covered by the invoice.
`header.additional.ar_header.service_date_to`	string	Optional	Indicates the end date of the service period covered by the invoice.
`header.additional.ar_header.receiver_vat_condition_id`	string	Optional	Identifies the VAT status of the receiver according to tax regulations.
`header.additional.pe_retention_header`	object	Optional	—
`header.additional.pe_retention_header.pe_sunat_retention_system_code`	string	Optional	—
`header.additional.pe_retention_header.pe_sunat_retention_percent`	number	Optional	—
`header.additional.pe_retention_header.pe_sunat_total_paid`	number	Optional	—
`header.additional.pe_shipping`	object	Optional	—
`header.additional.pe_shipping.handling_code`	string	Optional	It corresponds to the reason for the transfer, being a sale (1), a purchase (2), or other reasons (13).
`header.additional.pe_shipping.special_instructions`	integer	Optional	This 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_instructions`	string	Optional	Description of the reason for transfer.
`header.additional.pe_shipping.gross_weight_measure`	string	Optional	Refers to the total gross weight of the shipment, including the weight of goods, packaging, and any containers.
`header.additional.pe_shipping.gross_weight_measure_id`	string	Optional	Identifies 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_stage`	object	Optional	—
`header.additional.pe_shipping.shipment_stage.transport_mode_code`	string	Optional	Defines whether the transport is public (01) or private (02). Other values are not accepted.
`header.additional.pe_shipping.shipment_stage.transit_period`	string	Optional	Indicates the estimated duration or time frame of the goods' transportation from origin to destination.
`header.additional.pe_shipping.shipment_stage.driver_person`	object	Optional	—
`header.additional.pe_shipping.shipment_stage.driver_person.driver_id`	string	Optional	Refers to the DNI number of the driver responsible for the transport.
`header.additional.pe_shipping.shipment_stage.driver_person.first_name`	string	Optional	Indicates the driver's given name as registered for the transport operation.
`header.additional.pe_shipping.shipment_stage.driver_person.family_name`	string	Optional	Indicates the driver’s last name or surname as registered for the transport operation.
`header.additional.pe_shipping.shipment_stage.driver_person.identity_document_reference`	string	Optional	Refers to the driver’s license code or identification document number used to authorize the transport operation.
`header.additional.pe_shipping.shipment_stage.carrier_party`	object	Optional	—
`header.additional.pe_shipping.shipment_stage.carrier_party.party_identification`	string	Optional	Identifies 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_name`	string	Optional	Specifies the legal name of the carrier company responsible for the transportation service.
`header.additional.pe_shipping.shipment_stage.carrier_party.party_legal_entity_id`	string	Optional	The code of the ‘Authorized issuing entity – carrier’.
`header.additional.pe_shipping.shipment_stage.carrier_party.agent_party_id`	string	Optional	—
`header.additional.pe_shipping.delivery`	object	Optional	—
`header.additional.pe_shipping.delivery.delivery_address`	object	Optional	—
`header.additional.pe_shipping.delivery.delivery_address.party_tax_id_code`	string	Required when: document_type_id 100 and 101	Identity document number. Destinatario (DeliveryCustomerParty): the person or company that receives the goods. Required for document_type_id 100 and 101.
`header.additional.pe_shipping.delivery.delivery_address.party_tax_id_type`	enum(PE-RUC, PE-DNI, PE-CE, PE-PAS, PE-XXX)	Optional	Identity document type, same values as receiver_tax_id_type.
`header.additional.pe_shipping.delivery.delivery_address.party_legal_name`	string	Optional	Full name or legal name.
`header.additional.pe_shipping.delivery.delivery_address.ubigeo_code`	string	Optional	6-digit UBIGEO code of the arrival point (punto de llegada), e.g. 130101. Required.
`header.additional.pe_shipping.delivery.delivery_address.id`	string	Optional	Deprecated: former name of ubigeo_code. Still accepted; if both are sent they must match.
`header.additional.pe_shipping.delivery.delivery_address.city_subdivision_name`	string	Optional	Name of the urban subdivision or neighborhood (e.g., urbanization, residential area).
`header.additional.pe_shipping.delivery.delivery_address.city_name`	string	Optional	Name of the province or city where the delivery point is located.
`header.additional.pe_shipping.delivery.delivery_address.country_subentity`	string	Optional	Name of the department or region associated with the delivery address.
`header.additional.pe_shipping.delivery.delivery_address.district`	string	Optional	Name of the district where the delivery location is situated.
`header.additional.pe_shipping.delivery.delivery_address.address_line`	string	Optional	Full address or detailed description of the delivery point.
`header.additional.pe_shipping.delivery.delivery_address.country_id`	string	Optional	Numeric or alphanumeric code representing the country (e.g., “83” for Peru).
`header.additional.pe_shipping.delivery.dispatch`	object	Optional	—
`header.additional.pe_shipping.delivery.dispatch.party_tax_id_code`	string	Required when: document_type_id 101 (guía de remisión transportista); not accepted for 100, where the remitente is the issuer	Identity document number. Remitente (DespatchParty): the person or company that sends the goods. Required for document_type_id 101 (guía de remisión transportista); not accepted for 100, where the remitente is the issuer.
`header.additional.pe_shipping.delivery.dispatch.party_tax_id_type`	enum(PE-RUC, PE-DNI, PE-CE, PE-PAS, PE-XXX)	Optional	Identity document type, same values as receiver_tax_id_type.
`header.additional.pe_shipping.delivery.dispatch.party_legal_name`	string	Optional	Full name or legal name.
`header.additional.pe_shipping.delivery.dispatch.ubigeo_code`	string	Optional	6-digit UBIGEO code of the departure point (punto de partida), e.g. 150101. Required.
`header.additional.pe_shipping.delivery.dispatch.id`	string	Optional	Deprecated: former name of ubigeo_code. Still accepted; if both are sent they must match.
`header.additional.pe_shipping.delivery.dispatch.city_subdivision_name`	string	Optional	Name of the urban subdivision or neighborhood (e.g., urbanization, residential area) where the dispatch point is located.
`header.additional.pe_shipping.delivery.dispatch.city_name`	string	Optional	Name of the province or city from which the goods are dispatched.
`header.additional.pe_shipping.delivery.dispatch.country_subentity`	string	Optional	Name of the department or region associated with the dispatch address.
`header.additional.pe_shipping.delivery.dispatch.district`	string	Optional	Name of the district where the dispatch location is situated.
`header.additional.pe_shipping.delivery.dispatch.address_line`	string	Optional	Full address or detailed description of the dispatch point.
`header.additional.pe_shipping.delivery.dispatch.country_id`	string	Optional	Numeric or alphanumeric code representing the country (e.g., “83” for Peru).
`header.additional.pe_shipping.transport_handling_unit`	object	Optional	—
`header.additional.pe_shipping.transport_handling_unit.transport_equipment_id`	string	Optional	dentifies the code or license plate number of the transport equipment (e.g., truck, trailer, or container) used to move the goods.
`details`	array<object>	Optional	—
`details[].quantity`	number (float)	Always required	Quantity (can have up to 6 decimals, separate with a dot, not with a comma).
`details[].sku`	string	Optional	Unique internal SKU that identifies the product
`details[].line_description`	string	Always required	Short description to be included in the invoice as line title. Max 100 chars.
`details[].unit_price`	number (float)	Always required	Unit 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_description`	string	Optional	Allows adding an additional long description to the detail description for the document.
`details[].unit_measure`	string	Always required	Unit that this line is measured in.
`details[].modifier_amount`	number	Optional	Amount 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_percentage`	number (float)	Optional	Percentage 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_taxes`	number (float)	Optional	Total taxes for this line.
`details[].total_amount_line`	number (float)	Always required	Total amount for this line, including taxes and modifiers.
`details[].taxes`	array<object>	Optional	—
`details[].taxes[].tax_type_id`	string	Always required	Identifier of the tax type.
`details[].taxes[].tax_percentage`	number (float)	Always required	Percentage of the tax.
`details[].taxes[].tax_amount`	number (float)	Always required	Amount of the tax.
`details[].additional`	object	Optional	—
`details[].additional.mx_detail`	object	Optional	These are additional fields you will need to use when adding details to your documents in Mexico
`details[].additional.mx_detail.product_service_identifier`	string	Optional	This 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_code`	string	Optional	This 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
`references`	array<object>	Optional	—
`references[].document_type_id`	integer	Optional	Document type of the referenced document.
`references[].reference_type`	integer	Optional	Chile: 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_number`	string	Optional	Enter 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_id`	integer	Optional	Enter the document_id to reference: use reference_document_id or reference_number, but never both together.
`references[].reference_code`	integer	Always required	1 = 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[].description`	string	Always required	Reference description.
`references[].reference_date`	string (date)	Optional	It should only be entered when using a reference that is not an electronic tax document. (YYYY-MM-DD).
`references[].additional`	object	Optional	—
`references[].additional.pe_retention_details`	object	Optional	—
`references[].additional.pe_retention_details.reference_paid_amount`	number	Optional	—
`references[].additional.pe_retention_details.reference_total_invoice_amount`	number	Optional	—
`references[].additional.pe_retention_details.reference_paid_date`	string (date)	Optional	—
`references[].additional.pe_retention_details.reference_payment_id`	string	Optional	—
`references[].additional.pe_retention_details.pe_reference_sunat_retention_amount`	number	Optional	—
`references[].additional.pe_retention_details.pe_reference_sunat_retention_date`	string (date)	Optional	—
`references[].additional.pe_retention_details.calculation_rate`	number	Optional	—
`references[].additional.pe_retention_details.currency_id`	string	Optional	—
`globals_discounts_surcharges`	array<object>	Optional	—
`globals_discounts_surcharges[].discount_surcharge_code`	string	Always required	DA = Global discount on taxable DE = Global discount on exempt RA = Global surcharge on taxable RE = Global surcharge on exempt
`globals_discounts_surcharges[].discount_surcharge_value`	integer (float)	Always required	Value of the discount or surcharge.
`globals_discounts_surcharges[].discount_surcharge_type`	string	Always required	$ = Value will be applied as an amount % = Value will be applied as a percentage of the amount
`totals`	object	Optional	—
`totals.vat_credit_construction_company`	integer	Optional	65% 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_amount`	integer	Always required	Required, 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_amount`	integer	Optional	Sum of other taxes, can be negative if there are withholding taxes. NOT supported in the case of 'gross_values'.
`totals.total_amount`	integer	Always required	Final value.
`payment_link`	object	Optional	—
`payment_link.payment_url`	string	Optional	URL 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"
            },
            "pe_detraction": {
                "code": "string",
                "percent": 0,
                "amount": 0,
                "nation_bank_account": "string",
                "nation_bank_account_hide": true,
                "payment_means_code": "string"
            },
            "pe_cargo_transport": {
                "origin_ubigeo": "string",
                "origin_address": "string",
                "destination_ubigeo": "string",
                "destination_address": "string",
                "trip_detail": "string",
                "service_reference_amount": 0,
                "effective_load_reference_amount": 0,
                "payload_reference_amount": 0
            },
            "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

Request POST /documents

curl -X POST \
  "https://apifacto.com/v1/documents" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"..."}'

Response

{
    "document_id": 0,
    "document_status": 0,
    "header": {
        "account_id": 0,
        "document_type_id": 0,
        "document_type_taxbureau": "string",
        "document_number": 0,
        "received_issued_flag": 0,
        "taxbureau_validation_status": 0,
        "issue_date": "string",
        "issuer_tax_id_code": "string",
        "issuer_tax_id_type": "string",
        "issuer_legal_name": "string",
        "issuer_address": "string",
        "issuer_district": "string",
        "issuer_city": "string",
        "issuer_state_id": 0,
        "issuer_country_id": 0,
        "issuer_phone": "string",
        "issuer_activity": "string",
        "customer_supplier_id": 0,
        "receiver_tax_id_code": "string",
        "receiver_tax_id_type": "string",
        "receiver_legal_name": "string",
        "receiver_address": "string",
        "receiver_district": "string",
        "receiver_city": "string",
        "receiver_state_id": 0,
        "receiver_country_id": 0,
        "receiver_phone": "string",
        "receiver_activity": "string",
        "receiver_postalcode": "string",
        "payment_conditions": "string",
        "currency_id": 0,
        "exchange_rate_value": 0,
        "sale_modality": 0,
        "sale_clause": 0,
        "transportation_doc_type": 0,
        "transportation_doc_billing": 0,
        "document_status": 0
    },
    "details": [
        {
            "quantity": 0,
            "line_description": "string",
            "unit_measure": "string",
            "unit_price": 0,
            "long_description": "string",
            "modifier_amount": 0,
            "total_taxes": 0,
            "modifier_percentage": 0,
            "total_amount_line": 0
        }
    ],
    "totals": {
        "net_amount": 0,
        "taxes_amount": 0,
        "total_amount": 0
    },
    "electronic_document": {
        "document_xml": "string",
        "document_cdr": "string",
        "document_cdr_filename": "F001-00000001.cdr",
        "document_pdf": "string",
        "stamp_img": "string",
        "document_transfer_copy_pdf": "string"
    },
    "payment_link": {
        "payment_url": "string"
    },
    "result": {
        "status": 0,
        "error_message": "string"
    }
}

{
    "error": "Invalid document type ID"
}

{
    "error": "Invalid or expired token"
}

{
    "error": "Internal server error"
}