Facturapi (2.0)

Download OpenAPI specification:Download

Facturapi: soporte@facturapi.io URL: https://www.facturapi.io

On this page, we list all the methods available in the Facturapi API, as well as the complete reference of the parameters you can send. To see the nested properties of an object or an array of objects, you can click on the field name to expand it.

The Facturapi API is designed with the REST standard in mind. The API endpoints are grouped by resources, have predictable URLs, the responses are in JSON format, and we use standard HTTP response codes, authentication, and verbs.

During development, you can use the Facturapi API in the Test environment, and the invoices you issue will not be sent to the SAT (Mexican Tax Authority) and will not have fiscal validity.

The secret key you use to authenticate will determine both the environment in which the invoice will be created (Test or Live), as well as the organization to use as the issuer of your invoice or as the owner of the resource you request to create.

Customers

Create Customer

Register a new customer in Facturapi.

This call validates that the fiscal data matches the records of the SAT for that RFC, otherwise the call will return an error indicating the issue.

Once the customer is created and a response object is obtained, we recommend saving the ID in your database along with the customer information. Later, you can call the Create Invoice endpoint by passing the customer ID instead of repeating the information.

Finally, keep in mind that the customers you create in the Test environment are not shared with the Live environment.

Authorizations:

SecretLiveKeySecretTestKey

Request Body schema: application/json
required

legal_name required	string Legal name or business name of the customer. without the corporate regime (e.g.: S.A. de C.V.).
tax_id required	string In Mexican clients, it contains the customer's RFC. For foreigners, it is optional and represents the tax identification number, that is, the equivalent to the RFC in the customer's country.
tax_system required	string = 3 characters Required for national clients. Key of the customer's tax regime, from the Tax Regime Catalog.
required	object Fiscal address.
email	string <email> Email address to which to send the generated invoices.
phone	string Customer's phone number.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"tax_system": "601",
"email": "email@example.com",
"phone": 6474010101,
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
}

Response samples

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"tax_system": "601",
"email": "email@example.com",
"phone": 6474010101,
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
}

List customers

Returns a paginated list of all customers in an organization or performs a search according to parameters.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

q	string Free text field. Search word matches with `legal_name` or `tax_id` fields.
	object (DateRange) Object with requested date range.
page	integer >= 1 Page of results to return, starting from page 1.
limit	integer [ 1 .. 100 ] Default: 50 Number from 1 to 100 representing the maximum amount of results to return for pagination purposes.

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/customers \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -G \
  -d 'q=Dunder' \
  -d 'date[gt]=2021-07-14T06:00:00.000Z' \
  -d 'date[lt]=2021-08-14T06:00:00.000Z' \
  -d 'page=1'

Response samples

200
400
401
404
500

Content type

application/json

{"page": 1,
"total_pages": 1,
"total_results": 1,
"data": [{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"tax_system": "601",
"email": "email@example.com",
"phone": 6474010101,
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
}
]
}

Retrieve customer by ID

Returns the 'Customer' object with the specified ID. If the customer does not exist, a 404 error will be returned.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

customer_id

required

string

Customer ID

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/customers/590ce6c56d04f840aa8438af \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"tax_system": "601",
"email": "email@example.com",
"phone": 6474010101,
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
}

Edit Customer

Updates the information of an existing customer, setting only the values for the paramenters that are sent. Undefined values will not be modified.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

customer_id

required

string

ID of the object to edit

Request Body schema: application/json
required

legal_name	string Legal name or business name of the customer. without the corporate regime (e.g.: S.A. de C.V.).
tax_id	string In Mexican clients, it contains the customer's RFC. For foreigners, it is optional and represents the tax identification number, that is, the equivalent to the RFC in the customer's country.
tax_system	string = 3 characters Required for national clients. Key of the customer's tax regime, from the Tax Regime Catalog.
email	string <email> Email address to which to send the generated invoices.
phone	string Customer's phone number.
	object Fiscal address.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"tax_system": "601",
"email": "email@example.com",
"phone": 6474010101,
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
}

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"tax_system": "601",
"email": "email@example.com",
"phone": 6474010101,
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
}

Delete Customer

Deletes a customer. The invoices linked to the customer will not be deleted.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

customer_id

required

string

ID of the object to delete

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/customers/590ce6c56d04f840aa8438af \
  -X DELETE \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"tax_system": "601",
"email": "email@example.com",
"phone": 6474010101,
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
}

Validate Customer Tax Info

Validates that the customer's fiscal information matches the SAT records.

Its main function is to validate that the registered customer data continues to meet the SAT validation.

Note: The operations of creating a customer, editing a customer, and creating an invoice already perform a validation of the customer's information, so it is not necessary to call this endpoint before performing these operations.

Authorizations:

SecretLiveKey

path Parameters

customer_id

required

string

ID of the customer

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/customers/590ce6c56d04f840aa8438af/tax-info-validation \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"is_valid": true,
"errors": [{"path": "tax_system",
"message": "El RégimenFiscal no coincide con el registrado para el RFC en la lista de contribuyentes obligados del SAT."
}
]
}

Products

Create Product

Register a new product or service in your Facturapi catalog.

You can use the product ID to create invoices without having to send all the product data each time.

Keep in mind that the products you create in the Test environment are not shared with the Live environment.

Authorizations:

SecretLiveKeySecretTestKey

Request Body schema: application/json
required

description required	string Description of the good or service as it will appear on the invoice.
product_key required	string Key from the SAT catalog of products/services. We provide a more convenient way to find it using our key search tool.
price required	number Price per unit of the good or service. This value will represent the price with or without VAT, depending on the value of `tax_included`.
tax_included	boolean or null Default: true `true`: Indicates that all applicable taxes are included in the price (price attribute) and will be automatically broken down when the invoice is issued. `false`: Indicates that the price attribute does not include taxes, so those taxes to be applied will be added to the final price.
taxability	string Default: "`\"01\"` if the `taxes` array is empty; `\"02\"` if the `taxes` array has at least one element.\n" Enum: "01" "02" "03" "04" "05" Code that represents whether the good or service is subject to tax or not. This attribute corresponds to the "ObjetoImp" field in the CFDI. `01`: Not subject to tax. `02`: Subject to tax. `03`: Subject to tax, but not required to break down. `04`: Subject to tax, but does not cause tax. `05`: Subject to tax, VAT credit PODEBI.
	Array of objects or null (Tax) Default: "IVA (VAT) transferred 16%" List of taxes that must be applied to this product. If the parameter is omitted or null, it will be saved with an element representing the transferred IVA (VAT) of 16%, which is the most common tax. If an empty array is explicitly sent, it is understood that the product is exempt from taxes.
	Array of objects (LocalTax) Default: [] Array of local taxes (state or municipal), if any.
unit_key	string or null Default: "H87" Key of the unit of measure, from the SAT catalog. The default value `"H87"` (element) is the key to represent a piece or sales unit (pencil, notebook, television, etc). If the unit of your product is kilograms, liters, hours, or any other unit, we provide a convenient way to find the key using our key search tool.
unit_name	string or null Default: "Elemento" Name of the unit of measure used to express the quantity. It must be related to the unit key `unit_key`.
sku	string or null Internal identifier designated by the company. It can have any value.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
}

Response samples

200
400
401
404
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
}

List products

Returns a paginated list of all products in an organization or performs a search according to parameters.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

q	string Free text field. Search word matches with `description` or `sku` fields.
sku	string Search word matches specifically with `sku` field.
page	integer >= 1 Page of results to return, starting from page 1.
limit	integer [ 1 .. 100 ] Default: 50 Number from 1 to 100 representing the maximum amount of results to return for pagination purposes.

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/products \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -G \
  -d 'q=ukelele' \
  -d 'page=1'

Response samples

200
400
401
404
500

Content type

application/json

{"page": 1,
"total_pages": 1,
"total_results": 1,
"data": [{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
}
]
}

Retrieve product by ID

Returns the Product object with the specified ID. If the product does not exist, a 404 error will be returned.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

product_id

required

string

Product ID

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/products/590e22c26d04f840aa8438b2 \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
}

Edit product

Updates the information of an existing product, setting only the values for the paramenters that are sent. Undefined values will not be modified.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

product_id

required

string

Product ID

Request Body schema: application/json
required

description required	string Description of the good or service as it will appear on the invoice.
product_key required	string Key from the SAT catalog of products/services. We provide a more convenient way to find it using our key search tool.
price required	number Price per unit of the good or service. This value will represent the price with or without VAT, depending on the value of `tax_included`.
tax_included	boolean or null Default: true `true`: Indicates that all applicable taxes are included in the price (price attribute) and will be automatically broken down when the invoice is issued. `false`: Indicates that the price attribute does not include taxes, so those taxes to be applied will be added to the final price.
taxability	string Default: "`\"01\"` if the `taxes` array is empty; `\"02\"` if the `taxes` array has at least one element.\n" Enum: "01" "02" "03" "04" "05" Code that represents whether the good or service is subject to tax or not. This attribute corresponds to the "ObjetoImp" field in the CFDI. `01`: Not subject to tax. `02`: Subject to tax. `03`: Subject to tax, but not required to break down. `04`: Subject to tax, but does not cause tax. `05`: Subject to tax, VAT credit PODEBI.
	Array of objects or null (Tax) Default: "IVA (VAT) transferred 16%" List of taxes that must be applied to this product. If the parameter is omitted or null, it will be saved with an element representing the transferred IVA (VAT) of 16%, which is the most common tax. If an empty array is explicitly sent, it is understood that the product is exempt from taxes.
	Array of objects (LocalTax) Default: [] Array of local taxes (state or municipal), if any.
unit_key	string or null Default: "H87" Key of the unit of measure, from the SAT catalog. The default value `"H87"` (element) is the key to represent a piece or sales unit (pencil, notebook, television, etc). If the unit of your product is kilograms, liters, hours, or any other unit, we provide a convenient way to find the key using our key search tool.
unit_name	string or null Default: "Elemento" Name of the unit of measure used to express the quantity. It must be related to the unit key `unit_key`.
sku	string or null Internal identifier designated by the company. It can have any value.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
}

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
}

Delete Product

Deletes the product from your organization. The invoices linked with the product will not be deleted.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

product_id

required

string

Product ID to delete

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/products/590e22c26d04f840aa8438b2 \
  -X DELETE \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
}

Invoices

Create invoice (CFDI 4.0)

Creates a new Invoice. If the invoice is created in the Live environment, it will be stamped and sent to the SAT.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

async

boolean

Useful for large invoices. If sent false or not sent, the call will wait for the SAT to respond by stamping the invoice. If sent true, the call will return immediately with the invoice object in status pending, and its status can be checked for a change to valid at a later time.

Request Body schema: application/json
required

One of

required	Customer (object) or customer_id (string) Customer receiving the invoice.
required	Array of objects (LineItem) <= 5000 items Concepts to include in the invoice. The maximum number of elements that you can include in an invoice is 5,000. If you need to issue an invoice with more than 5,000 concepts, you can divide the transaction into several invoices.
payment_form required	string = 2 characters Código que representa la forma de pago, de acuerdo al catálogo del SAT.
use required	string Default: "G01" Code of Use of CFDI according to the SAT catalog. You can see the codes in this table, or use the constants included in our libraries. For global invoices you must use the code `S01`.
type	string Default: "I" Value: "I" Type of document. The default value is `“I”` (Income).
payment_method	string Default: "PUE" Enum: "PUE" "PPD" Code of the payment method according to the SAT catalog. `PUE`: Payment in One Installment (paid in full at the time of the transaction) `PPD`: Payment in Installments or Deferred (partial or deferred payment)
currency	string Default: "MXN" Currency code, according to the standard ISO 4217.
exchange	number Default: 1 Exchange rate according to the currency used. It represents the number of Mexican pesos (MXN) equivalent to one unit of the currency indicated in the `currency` attribute.
conditions	string or null [ 1 .. 1000 ] characters Payment conditions. Free text field usually used to specify payment terms, such as the due date.
	Array of objects (RelatedDocumentInput) Default: [] Documents related to the invoice.
	object or null Required object when creating a global invoice.
export	string Default: "01" Enum: "01" "02" "03" "04" Indicates if the invoice covers an export operation. `01`: Not applicable `02`: Definitive with key A1 `03`: Temporary `04`: Definitive with key different from A1 or when there is no sale in terms of the CFF
	Array of objects (CustomComplement) Default: [] Complements to include in the invoice. You can include any complement in the invoice if you build the XML node of the complement yourself and use the `custom` type. It is necessary to add the complement information to the PDF separately using the `pdf_custom_section` parameter.
status	string Default: "pending" Initial status of the invoice. If `draft` is sent, the invoice will be saved as a draft and will not be stamped or sent to the SAT. Also, when sending `draft`, all required fields become optional. If omitted, the default status is `pending` and once stamped (in the response) this field will be updated to `valid`. For asynchronous invoices, this field will remain `pending` until the invoice is stamped. pending
date	string <date-time> Default: "now" Date of issuance of the invoice in ISO8601 format (UTC String). It cannot be earlier than 72 hours in the past, nor later than the present.
	object You can use this parameter to specify the address where the invoice was issued. This field is optional and if not sent, the invoice will be issued with the address of the organization.
external_id	string or null Optional identifier that you can use to relate this invoice to your records and later search by this number. Facturapi does not validate that this field is unique.
idempotency_key	string or null Unique identifier that you can use to avoid duplicates when retrying a request. It can be any text string, as long as it is unique for each document. If left blank, it will not be taken into account.
folio_number	integer Default: "autoincremental" Number of folio assigned by the company for internal control. If omitted, the autoincremental value of the organization will be assigned.
series	string or null <= 25 characters Series. Aplanumeric characters designated by the company for internal control and without fiscal relevance.
pdf_custom_section	string or null <xml> In case you need to include more information in the PDF, this field allows you to insert HTML code with your own content. For security reasons, the code you can send is limited to the following tags: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `div`, `p`, `span`, `small`, `br`, `b`, `i`, `ul`, `ol`, `li`, `strong`, `table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, and `td`. Attributes and styles are not allowed.
addenda	string or null <xml> XML code with the Addenda that needs to be added to the invoice.
	Array of objects (Namespace) Default: [] If you included the `complements` parameter, this field is optional; however, if you included the `addenda` parameter, you must send the necessary information to include these namespaces in the XML document.
	object Configure which optional fields you want to show in the PDF. The SAT does not require showing these fields, but they can be activated according to the customer's preference for the current invoice. Use this field for invoice generation requests in which you need to use a different configuration than the pdf_extra field of the organization.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

Example

Income

{ }

Response samples

200
400
401
404
500

Content type

application/json

Example

pending

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "pending",
"cancellation_status": "none",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"date": "now",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"type": "I",
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"total": 10944.82,
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"folio_number": 914,
"series": "F",
"external_id": "string",
"idempotency_key": "string",
"payment_form": 6,
"is_ready_to_stamp": true,
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": [ ]
}
],
"currency": "MXN",
"exchange": 1,
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
],
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
}
}

List invoices

Returns a paginated list of all invoices in an organization or performs a search according to parameters.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

q	string Text to search in the invoice. The search will be performed by partial matches in the fields: `items[].product.description` `customer.legal_name` And by exact matches in the fields: `id` `uuid` `customer.tax_id` `folio_number` `total`
customer	string Filter by customer ID. Exact match.
type	string Enum: "I" "E" "P" "N" "T" Filter by invoice type. Exact match.
payment_method	string Enum: "PUE" "PPD" Payment method. Exact match.
	object (DateRange) Object with requested date range.
page	integer >= 1 Page of results to return, starting from page 1.
limit	integer [ 1 .. 100 ] Default: 50 Number from 1 to 100 representing the maximum amount of results to return for pagination purposes.

Responses

Request samples

cURL
Node.js
C#
PHP

# All invoices from the organization
curl "https://www.facturapi.io/v2/invoices" \
  -G \
  -H "Authorization: Bearer sk_test_API_KEY"

# All invoices issued to a certain customer
curl "https://www.facturapi.io/v2/invoices" \
  -G \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -d "customer=58e93bd8e86eb318b0197456"

# Page 3 of the search results for free text
# of invoices issued to a certain customer between 2017 and 2019
curl "https://www.facturapi.io/v2/invoices" \
  -G \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -d "q=Aspiradora+Robot&customer=58e93bd8e86eb318b0197456&date[gte]=2017-01-01T00:00:00.000Z&date[lt]=2020-01-01T00:00:00.000Z&page=3&limit=10"

Response samples

200
400
401
404
500

Content type

application/json

{"page": 1,
"total_pages": 1,
"total_results": 1,
"data": [{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "valid",
"cancellation_status": "none",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"date": "now",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"type": "I",
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"total": 10944.82,
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"folio_number": 914,
"series": "F",
"external_id": "string",
"idempotency_key": "string",
"payment_form": 6,
"is_ready_to_stamp": true,
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": [ ]
}
],
"currency": "MXN",
"exchange": 1,
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
],
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
}
}
]
}

Retrieve invoice by ID

Returns the Invoice object with the specified ID. If the invoice does not exist, a 404 error will be returned.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

invoice_id

required

string

ID of the invoice

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "valid",
"cancellation_status": "none",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"date": "now",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"type": "I",
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"total": 10944.82,
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"folio_number": 914,
"series": "F",
"external_id": "string",
"idempotency_key": "string",
"payment_form": 6,
"is_ready_to_stamp": true,
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": [ ]
}
],
"currency": "MXN",
"exchange": 1,
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
],
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
}
}

Edit draft invoice

Updates the information of a draft invoice, setting only the values for the paramenters that are sent. Undefined values will not be modified.

In the Invoice response object, Facturapi will automatically assign the is_ready_to_stamp field with the value true if the invoice passes the minimum validation required to be stamped; otherwise, the is_ready_to_stamp field will be false.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

invoice_id

required

string

ID of the invoice to edit

Request Body schema: application/json
required

One of

type	string Enum: "I" "E" "P" "N" "T" Type of document. It can have the values `"I"`: Income, `"P"`: Payment, `"E"`: Egress, `"N"`: Payroll, `"T"`: Transfer.
	Array of objects (LineItem) <= 5000 items Concepts to include in the invoice. The maximum number of elements that you can include in an invoice is 5,000. If you need to issue an invoice with more than 5,000 concepts, you can divide the transaction into several invoices.
payment_form	string = 2 characters Payment form code according to the Payment Form catalog.
payment_method	string Enum: "PUE" "PPD" Code of the payment method according to the SAT catalog. `PUE`: Payment in One Installment (paid in full at the time of the transaction) `PPD`: Payment in Installments or Deferred (partial or deferred payment)
use	string Code of Use of CFDI according to the SAT catalog. You can see the codes in this table, or use the constants included in our libraries. For global invoices you must use the code `S01`.
currency	string Currency code, according to the standard ISO 4217.
exchange	number Echange rate for the currency used. It represents the number of pesos mexicanos (MXN) equivalent to one unit of the currency indicated in the `currency`.
conditions	string or null [ 1 .. 1000 ] characters Payment conditions. Free text field usually used to specify payment terms, such as the due date.
	Array of objects (RelatedDocumentInput) Documents related to the invoice.
	object or null Object required when creating a global invoice.
export	string Enum: "01" "02" "03" "04" Indicates if the invoice covers an export operation. `01`: Not applicable `02`: Definitive with key A1 `03`: Temporary `04`: Definitive with key different from A1 or when there is no sale in terms of the CFF
	Array of objects (CustomComplement) Complements to include in the invoice. You can include any complement in the invoice if you build the XML node of the complement yourself and use the `custom` type. It is necessary to add the complement information to the PDF separately using the `pdf_custom_section` parameter.
	Customer (object) or customer_id (string) Customer receiving the invoice.
status	string Value: "draft" Initial status of the invoice. It is only possible to edit an invoice with status `draft`, and it is not possible to change the status when editing, so the only allowed value is `draft`.
date	string <date-time> Date of issuance of the invoice in ISO8601 format (UTC String). It cannot be earlier than 72 hours in the past, nor later than the present.
	object You can use this parameter to specify the address where the invoice was issued. This field is optional and if not sent, the invoice will be issued with the address of the organization.
external_id	string or null Optional identifier that you can use to relate this invoice to your records and later search by this number. Facturapi does not validate that this field is unique.
idempotency_key	string or null Unique identifier that you can use to avoid duplicates when retrying a request. It can be any text string, as long as it is unique for each document. If left blank, it will not be taken into account.
folio_number	integer Folio number assigned by the company for internal control. If omitted, the autoincremental value of the organization will be assigned. This field does not have any fiscal relevance.
series	string or null <= 25 characters Series. Alphanumeric characters designated by the company for internal control and without fiscal relevance.
pdf_custom_section	string or null <xml> In case you need to include more information in the PDF, this field allows you to insert HTML code with your own content. For security reasons, the code you can send is limited to the following tags: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `div`, `p`, `span`, `small`, `br`, `b`, `i`, `ul`, `ol`, `li`, `strong`, `table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, and `td`. Attributes and styles are not allowed.
addenda	string or null <xml> XML code with the Addendum to add to the invoice.
	Array of objects (Namespace) If you included the `complements` parameter, this field is optional; however, if you included the `addenda` parameter, you must send the necessary information to include these namespaces in the XML document.
	object Configure which optional fields you want to show in the PDF. The SAT does not require showing these fields, but they can be activated according to the customer's preference for the current invoice. Use this field for invoice generation requests in which you need to use a different configuration than the pdf_extra field of the organization.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

Example

Income

{"type": "I",
"items": [{"quantity": 1,
"discount": 0,
"product": {"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": [{"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
],
"customs_keys": ["string"
],
"complement": "string",
"third_party": {"legal_name": "The Michael Scott Paper Company",
"tax_id": "MIC920101HN7",
"tax_system": "601",
"zip": "01234"
},
"property_tax_account": "0102030405"
}
],
"payment_form": "03",
"payment_method": "PUE",
"use": "G01",
"currency": "MXN",
"exchange": 0,
"conditions": "Fecha límite de pago: 28/feb/2025",
"related_documents": [{"relationship": "string",
"documents": [ ]
}
],
"global": {"periodicity": "day",
"months": "01",
"year": 2022
},
"export": "01",
"complements": [{"type": "custom",
"data": "string"
}
],
"customer": {"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"tax_system": "601",
"email": "email@example.com",
"phone": 6474010101,
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
},
"status": "draft",
"date": "2019-08-24T14:15:22Z",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"external_id": "string",
"idempotency_key": "string",
"folio_number": 0,
"series": "string",
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
],
"pdf_options": {"codes": true,
"product_key": true,
"round_unit_price": false,
"tax_breakdown": true,
"ieps_breakdown": true
}
}

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "draft",
"cancellation_status": "none",
"verification_url": null,
"date": null,
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"type": "I",
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"total": 0,
"uuid": 0,
"folio_number": 914,
"series": "F",
"external_id": "string",
"idempotency_key": "string",
"payment_form": 6,
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": [ ]
}
],
"currency": "MXN",
"exchange": 1,
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
],
"is_ready_to_stamp": true,
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
}
}

Cancel invoice

Creates a cancellation request to the SAT for the specified invoice.

When using this method, 3 possible results can occur:

The call returns an error with the explanation of why the cancellation could not be completed.
The call is successful and returns an invoice object with the property status: "canceled".
The call is successful, but the cancellation requires confirmation from your client, in which case the response will be the invoice object with the properties status: "valid" and cancellation_status: "pending".

In the third scenario, the value of cancellation_status will be automatically updated by Facturapi when your client accepts, rejects, or lets the request expire, so that when you query an invoice (using Get Invoice), the cancellation_status property will reflect the most recent status of the request.

Check the possible values of cancellation_status below.

After the cancellation, the invoice will no longer be valid, the object will change its status to "canceled" and will still be available for future queries.

If the status of the invoice is draft, this method will delete it from the database.

If the status of the invoice is canceled, this method will return an error.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

invoice_id

required

string

ID of the invoice to cancel

query Parameters

motive

required

string

Enum: "01" "02" "03" "04"

Key representing the motive for the cancellation of the invoice.

Possible values:

01: Invoice issued with errors with relation. When the invoice contains any errors in quantities, keys, or any other data and the replacement invoice has already been issued, which should be indicated through the substitution attribute.
02: Invoice issued with errors without relation. When the invoice contains any errors in quantities, keys, or any other data and it is not required to be related to another invoice.
03: Operation not carried out. When the sale or transaction was not completed.
04: Nominative operation related to the global invoice. When it is necessary to cancel an invoice to the general public because the customer requests their invoice.

substitution

string

ID of the invoice that replaces the invoice being canceled.

You can use either the ID assigned by Facturapi or the fiscal folio (UUID).

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d?motive=02 \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -X DELETE

Response samples

200
400
401
409
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "valid",
"cancellation_status": "none",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"date": "now",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"type": "I",
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"total": 10944.82,
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"folio_number": 914,
"series": "F",
"external_id": "string",
"idempotency_key": "string",
"payment_form": 6,
"is_ready_to_stamp": true,
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": [ ]
}
],
"currency": "MXN",
"exchange": 1,
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
],
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
}
}

Copy to draft

Creates a new draft invoice with the same information as the specified invoice.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

invoice_id

required

string

ID of the invoice to copy

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/copy \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -X POST

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "draft",
"cancellation_status": "none",
"verification_url": null,
"date": null,
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"type": "I",
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"total": 0,
"uuid": 0,
"folio_number": 914,
"series": "F",
"external_id": "string",
"idempotency_key": "string",
"payment_form": 6,
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": [ ]
}
],
"currency": "MXN",
"exchange": 1,
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
],
"is_ready_to_stamp": true,
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
}
}

Stamp draft invoice

Stamps a draft invoice and sends it to the SAT for validation.

When using this method, the value of the is_ready_to_stamp field (assigned by Facturapi) must be true. Otherwise, the call will return an error. To get the value of is_ready_to_stamp, use the Get Invoice method.

This method does not allow editing the invoice, only stamping it. If you need to edit information in the invoice before stamping it, use the Edit Draft Invoice method.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

invoice_id

required

string

ID of the invoice to stamp

query Parameters

async

boolean

Useful for large invoices. If sent false or not sent, the call will wait for the SAT to respond by stamping the invoice. If sent true, the call will return immediately with the invoice object in status pending, and its status can be checked for a change to valid at a later time.

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/stamp \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -X POST

Response samples

200
400
401
409
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "valid",
"cancellation_status": "none",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"date": "now",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"type": "I",
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"total": 10944.82,
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"folio_number": 914,
"series": "F",
"external_id": "string",
"idempotency_key": "string",
"payment_form": 6,
"is_ready_to_stamp": true,
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": [ ]
}
],
"currency": "MXN",
"exchange": 1,
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
],
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
}
}

Cancellation receipt

Download the cancellation receipt of a canceled invoice in an xml or pdf file.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

invoice_id required	string ID of the invoice to download the cancellation receipt
format required	string Enum: "xml" "pdf" Format of the file to download

Responses

Request samples

cURL
Node.js
C#
PHP

# Cancellation receipt xml
curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/cancellation_receipt/xml \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -X GET

# Cancellation receipt pdf
curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/cancellation_receipt/pdf \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -X GET

Response samples

400
401
500

Content type

application/json

{"message": "string"
}

Download invoice

Download your invoice in PDF, XML, or both in a ZIP file.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

invoice_id required	string ID of the invoice to download
format required	string Enum: "xml" "pdf" "zip" Format of the file to download

Responses

Request samples

cURL
Node.js
C#
PHP

## Download PDF and XML compressed in a ZIP file
curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/zip \
  -H "Authorization: Bearer sk_test_API_KEY"

## Download only the PDF
curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/pdf \
  -H "Authorization: Bearer sk_test_API_KEY"

## Download only the XML
curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/xml \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

400
401
500

Content type

application/json

{"message": "string"
}

Send invoice by email

Sends an email to the address of your client with the XML and PDF files attached to the message.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

invoice_id

required

string

ID of the invoice to send

Request Body schema: application/json
optional

	string or Array of strings Email address to send the invoice. If not sent, the email registered by the customer will be used.
One of string <email> Email address to send the invoice.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"email": "another@email.com"
}

Response samples

200
400
401
500

Content type

application/json

{"ok": true
}

Update invoice status

Consults the status of a stamped invoice at the SAT and updates the invoice object with the most recent information.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

invoice_id

required

string

ID of the invoice to update

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/status \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -X PUT

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "valid",
"cancellation_status": "none",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"date": "now",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"type": "I",
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"total": 10944.82,
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"folio_number": 914,
"series": "F",
"external_id": "string",
"idempotency_key": "string",
"payment_form": 6,
"is_ready_to_stamp": true,
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": [ ]
}
],
"currency": "MXN",
"exchange": 1,
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
],
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
}
}

E-Receipts

Create e-receipt

Creates a new e-Receipt, which acts as a sales note.

Every receipt will have an auto-generated URL that the client can visit to fill in their fiscal data in a microsite with the organization's branding.

Authorizations:

SecretUsertKey

Request Body schema: application/json
required

required	Array of objects (LineItem) <= 5000 items Concepts to include in the receipt. The maximum number of elements that you can include in a receipt is 5,000. If you need to issue a receipt with more than 5,000 concepts, you can divide the transaction into several receipts.
payment_form required	string Payment form code according to the Payment Form catalog.
date	string <date-time> Date of issuance of the receipt in ISO8601 format (UTC String).
folio_number	integer Autoincremental. Number of the receipt for internal control and without fiscal relevance.
currency	string Currency code, according to the standard ISO 4217.
exchange	number >= 0 Exchange rate according to the currency used. It represents the number of Mexican pesos (MXN) equivalent to one unit of the currency indicated in the `currency` attribute.
branch	string Name of the branch where the receipt was issued.
external_id	string or null Optional identifier that you can use to relate this receipt to your records and later search by this number. Facturapi does not validate that this field is unique.
idempotency_key	string or null Unique identifier that you can use to avoid duplicates when retrying a request. It can be any text string, as long as it is unique for each document. If left blank, it will not be taken into account.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"items": [{"quantity": 1,
"discount": 0,
"product": {"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": [{"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
],
"customs_keys": ["string"
],
"complement": "string",
"third_party": {"legal_name": "The Michael Scott Paper Company",
"tax_id": "MIC920101HN7",
"tax_system": "601",
"zip": "01234"
},
"property_tax_account": "0102030405"
}
],
"date": "2021-09-10T15:21:23.456Z",
"payment_form": "03",
"folio_number": 120,
"currency": "MXN",
"exchange": 1,
"branch": "string",
"external_id": "string",
"idempotency_key": "string"
}

Response samples

200
400
401
404
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"date": "2021-09-10T15:21:23.456Z",
"expires_at": "2021-09-17T15:21:23.456Z",
"status": "open",
"self_invoice_url": "https://factura.space/empresa-demo/r9YqYarL",
"total": 356.78,
"invoice": "614496b471d422de4b6cfcc4",
"key": "r9YqYarL",
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"external_id": "string",
"idempotency_key": "string",
"payment_form": "03",
"folio_number": 120,
"currency": "MXN",
"exchange": 1,
"branch": "string"
}

List e-recipts

Returns a paginated list of all the receipts of an organization or performs a search according to parameters.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

q	string Search. Text to search in the description of the receipt's items or the SKU.
payment_form	string = 2 characters Example: payment_form=02 Code representing the payment form, according to the SAT catalog. If included, the receipts will be grouped and listed according to the payment form.
	object (DateRange) Object with requested date range.
page	integer >= 1 Page of results to return, starting from page 1.
limit	integer [ 1 .. 100 ] Default: 50 Number from 1 to 100 representing the maximum amount of results to return for pagination purposes.

Responses

Request samples

cURL
Node.js
C#
PHP

# All receipts of the organization
curl "https://www.facturapi.io/v2/receipts" \
  -G \
  -H "Authorization: Bearer sk_test_API_KEY"

# Page 3 of search results for free text search
# of receipts created between 2017 and 2019
curl "https://www.facturapi.io/v2/receipts" \
  -G \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -d "q=Aspiradora+Robot&date[gte]=2017-01-01T00:00:00.000Z&date[lt]=2020-01-01T00:00:00.000Z&page=3&limit=10"

Response samples

200
400
401
404
500

Content type

application/json

{"page": 1,
"total_pages": 1,
"total_results": 1,
"data": [{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"date": "2021-09-10T15:21:23.456Z",
"expires_at": "2021-09-17T15:21:23.456Z",
"status": "open",
"self_invoice_url": "https://factura.space/empresa-demo/r9YqYarL",
"total": 356.78,
"invoice": "614496b471d422de4b6cfcc4",
"key": "r9YqYarL",
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"external_id": "string",
"idempotency_key": "string",
"payment_form": "03",
"folio_number": 120,
"currency": "MXN",
"exchange": 1,
"branch": "string"
}
]
}

Retrieve e-receipt by ID

Retrieves an e-Receipt by its ID.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

receipt_id

required

string

ID of the receipt to retrieve

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/receipts/58e93bd8e86eb318b019743d \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"date": "2021-09-10T15:21:23.456Z",
"expires_at": "2021-09-17T15:21:23.456Z",
"status": "open",
"self_invoice_url": "https://factura.space/empresa-demo/r9YqYarL",
"total": 356.78,
"invoice": "614496b471d422de4b6cfcc4",
"key": "r9YqYarL",
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"external_id": "string",
"idempotency_key": "string",
"payment_form": "03",
"folio_number": 120,
"currency": "MXN",
"exchange": 1,
"branch": "string"
}

Cancel e-receipt

Cancel a receipt by changing its status property to "canceled".

Once canceled, the receipt cannot be invoiced.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

receipt_id

required

string

ID of the receipt to cancel

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/receipts/5ebd8e56f5687a013ca0df46 \
  -X DELETE \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"date": "2021-09-10T15:21:23.456Z",
"expires_at": "2021-09-17T15:21:23.456Z",
"status": "open",
"self_invoice_url": "https://factura.space/empresa-demo/r9YqYarL",
"total": 356.78,
"invoice": "614496b471d422de4b6cfcc4",
"key": "r9YqYarL",
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"external_id": "string",
"idempotency_key": "string",
"payment_form": "03",
"folio_number": 120,
"currency": "MXN",
"exchange": 1,
"branch": "string"
}

Download PDF

Download the electronic receipt in PDF format.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

receipt_id

required

string

ID of the receipt to download

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/receipts/58e93bd8e86eb318b019743d/pdf \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

400
401
500

Content type

application/json

{"message": "string"
}

Send e-receipt by email

Send the e-receipt by email to the customer.

The email sent will be customized with the logo and colors of the organization that created it, and will include a button to invoice the receipt, as well as the receipt attached as a PDF to the message.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

receipt_id

required

string

ID of the e-receipt to send

Request Body schema: application/json
optional

required	string or Array of strings Email address to send the e-receipt. If not sent, the email registered by the customer will be used.
One of string <email> Email address to send the e-receipt.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"email": "other@email.com"
}

Response samples

200
400
401
500

Content type

application/json

{"ok": true
}

Convert e-receipt to invoice

Creates a new invoice from a receipt. Once invoiced, the receipt's status will change to "invoiced_to_customer".

Only open receipts (status = "open") can be invoiced.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

receipt_id

required

string

ID of the receipt to invoice

Request Body schema: application/json
required

required	Customer (object) or customer_id (string) Customer receiving the invoice. You can send the customer object directly or the ID of a previously registered customer in Facturapi.
use	string Default: "G01" Code of Use of CFDI according to the SAT catalog. You can see the codes in this table, or use the constants included in our libraries.
conditions	string or null [ 1 .. 1000 ] characters Payment conditions. Free text field usually used to specify payment terms, such as the due date.
folio_number	integer Default: "autoincremental" Number of folio assigned by the company for internal control. If omitted, the autoincremental value of the organization will be assigned.
series	string or null <= 25 characters Series. Aplanumeric characters designated by the company for internal control and without fiscal relevance.
pdf_custom_section	string or null <xml> In case you need to include more information in the PDF, this field allows you to insert HTML code with your own content. For security reasons, the code you can send is limited to the following tags: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `div`, `p`, `span`, `small`, `br`, `b`, `i`, `ul`, `ol`, `li`, `strong`, `table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, and `td`. Attributes and styles are not allowed.
addenda	string or null <xml> XML code with the Addenda that needs to be added to the invoice.
	Array of objects (Namespace) Default: [] If you included the `complements` parameter, this field is optional; however, if you included the `addenda` parameter, you must send the necessary information to include these namespaces in the XML document.
	object Configure which optional fields you want to show in the PDF. The SAT does not require showing these fields, but they can be activated according to the customer's preference for the current invoice. Use this field for invoice generation requests in which you need to use a different configuration than the pdf_extra field of the organization.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"customer": {"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"tax_system": "601",
"email": "email@example.com",
"phone": 6474010101,
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
},
"use": "G01",
"conditions": "string",
"folio_number": "autoincremental",
"series": "string",
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [ ],
"pdf_options": {"codes": true,
"product_key": true,
"round_unit_price": false,
"tax_breakdown": true,
"ieps_breakdown": true
}
}

Response samples

200
400
401
404
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "valid",
"cancellation_status": "none",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"date": "now",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"type": "I",
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"total": 10944.82,
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"folio_number": 914,
"series": "F",
"external_id": "string",
"idempotency_key": "string",
"payment_form": 6,
"is_ready_to_stamp": true,
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": [ ]
}
],
"currency": "MXN",
"exchange": 1,
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
],
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
}
}

Create global invoice

Creates a global invoice that will include all receipts with status = "open" from a certain period.

Authorizations:

SecretLiveKeySecretTestKey

Request Body schema: application/json
required

periodicity required	string Default: "`periodicity` property from the organization's receipt configuration." Enum: "day" "week" "fortnight" "month" "two_months" Periodicity that corresponds to the range of dates used. If omitted, the organization's receipt configuration will be used. If you omit sending the `from` and `to` fields, the default dates will depend on the value of `periodicity`.
from	string <date> Default: "Start of the last period" Initial date of the receipts that will be included in the global invoice. By default, this value is the start of the last period (day, week, fortnight, or month), according to the value of "Periodicity" (`periodicity`) in the receipts configuration of your organization. This value is required when the `receipts` field is sent.
to	string <date> Default: "End of the last period" End date of the receipts that will be included in the global invoice. By default, this value is the end of the last period (day, week, fortnight, or month), according to the value of "Periodicity" (`periodicity`) in the receipts configuration of your organization. This value is required when the `receipts` field is sent.
months	string Default: "Month contained in the range of dates used." Key representing the month or bimester of the invoice. Consult the possible values in the Months and Bimesters catalog.
folio_number	integer Default: "autoincremental" Number of the folio assigned by the company for internal control. If omitted, the incremental value of the organization will be assigned.
series	string or null <= 25 characters Series. Alphanumeric characters designated by the company for internal control and without fiscal validity.
date	string <date> Default: "Value of the `to` field" Date of issuance of the invoice. By default, it takes the value of the `to` field.
payment_form	string = 2 characters Payment form code according to the Payment Form catalog. If included, the receipts will be grouped and the global invoice will be created by the payment form.
receipts	Array of strings <hex> [ items <hex > ] Receipts to include in the global invoice. If this parameter is included, the `from` and `to` parameters will be required and must comply with the `periodicity` field.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"from": "2022-01-01T00:00:00.000",
"to": "2022-31-01T23:59:59.999",
"periodicity": "day",
"months": "01",
"folio_number": "autoincremental",
"series": "F",
"date": "2022-01-01T00:00:00.000",
"payment_form": "02",
"receipts": ["614496b471d422de4b6cfcc4"
]
}

Response samples

200
400
401
404
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "valid",
"cancellation_status": "none",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"date": "now",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"type": "I",
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"total": 10944.82,
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"folio_number": 914,
"series": "F",
"external_id": "string",
"idempotency_key": "string",
"payment_form": 6,
"is_ready_to_stamp": true,
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": [{"type": "IVA",
"rate": 0.16
}
],
"local_taxes": [ ],
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": [ ]
}
],
"currency": "MXN",
"exchange": 1,
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
],
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
}
}

Retentions

Create retention

Create a new Retention. If the invoice is created in Live environment, it will be stamped and sent to SAT.

Authorizations:

SecretLiveKeySecretTestKey

Request Body schema: application/json
required

required	Customer (object) or customer_id (string) Customer receiving the invoice.
cve_retenc required	string Key of the retention or payment information according to the SAT catalog.
required	object Information about the retention period.
required	object Information about the total of retentions made in the corresponding period.
fecha_exp	string <date-time> Date of issuance of the document in ISO8601 format (UTC String).
desc_retenc	string If the retention key is "25" (Other types of retentions), this field is used to register the description of the retention.
folio_int	string Alphanumeric identifier for internal control of the company and without fiscal relevance.
external_id	string Optional identifier that you can use to relate this retention to your records and later search by this number. Facturapi does not validate that this field is unique.
idempotency_key	string Unique identifier that you can use to avoid duplicates when retrying a request. It can be any text string, as long as it is unique for each document.
complements	Array of strings <xml> (string) [ items <xml > ] Default: [] Array of complements to include in the retention. Each element contains a `string` with the XML code of the complement, as you want it to be inserted in the XML of the CFDI. Only one root XML node is allowed per element.
pdf_custom_section	string <html> In case you need to include more information in the PDF, this field allows you to insert HTML code with your own content.
addenda	string <xml> XML code with the Addenda that needs to be added to the invoice.
	Array of objects (Namespace) Namespaces to insert in the root node of the invoice. Required for `addenda`.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"customer": {"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"tax_system": "601",
"email": "email@example.com",
"phone": 6474010101,
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
},
"cve_retenc": 26,
"fecha_exp": "2021-09-15T06:03:23.000Z",
"desc_retenc": "string",
"folio_int": "R123",
"periodo": {"mes_ini": 9,
"mes_fin": 9,
"ejerc": 2021
},
"totales": {"monto_tot_operacion": 0,
"monto_tot_grav": 0,
"monto_tot_exent": 0,
"monto_tot_ret": 0,
"imp_retenidos": [{"base_ret": 0,
"impuesto": "IVA",
"monto_ret": 0,
"tipo_pago_ret": 1
}
]
},
"external_id": "string",
"idempotency_key": "string",
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
]
}

Response samples

200
400
401
404
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "valid",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"type": "Retención",
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
},
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"cve_retenc": 1,
"fecha_exp": "2021-09-15T06:03:23.000Z",
"desc_retenc": "string",
"folio_int": "string",
"periodo": {"mes_ini": 1,
"mes_fin": 1,
"ejerc": 0
},
"totales": {"monto_tot_operacion": 0,
"monto_tot_grav": 0,
"monto_tot_exent": 0,
"monto_tot_ret": 0,
"imp_retenidos": [{"base": 0,
"impuesto": "IVA",
"monto": 0,
"tipo_pago_ret": 1
}
]
},
"external_id": "string",
"idempotency_key": "string",
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
]
}

List retentions

Returns a paginated list of all the retentions of an organization or performs a search according to parameters.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

q	string Text search. Finds retentions with the specified text in the customer's `legal_name` or `tax_id`.
customer	string ID of the customer to filter by. Only retentions issued to this customer will be returned.
	object (DateRange) Object with requested date range.
page	integer >= 1 Page of results to return, starting from page 1.
limit	integer [ 1 .. 100 ] Default: 50 Number from 1 to 100 representing the maximum amount of results to return for pagination purposes.

Responses

Request samples

cURL
Node.js
C#
PHP

# All retentions of the organization
curl https://www.facturapi.io/v2/retentions \
  -H "Authorization: Bearer sk_test_API_KEY"

# All retentions issued for a certain customer
curl "https://www.facturapi.io/v2/retentions" \
  -G \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -d "customer=58e93bd8e86eb318b0197456"

# Page 3 of search results for free text search
# of retentions issued between 2017 and 2019
curl "https://www.facturapi.io/v2/retentions" \
  -G \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -d "q=John+Doe6&date[gte]=2017-01-01T00:00:00.000Z&date[lt]=2020-01-01T00:00:00.000Z&page=3&limit=10"

Response samples

200
400
401
404
500

Content type

application/json

{"page": 1,
"total_pages": 1,
"total_results": 1,
"data": [{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "valid",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"type": "Retención",
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
},
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"cve_retenc": 1,
"fecha_exp": "2021-09-15T06:03:23.000Z",
"desc_retenc": "string",
"folio_int": "string",
"periodo": {"mes_ini": 1,
"mes_fin": 1,
"ejerc": 0
},
"totales": {"monto_tot_operacion": 0,
"monto_tot_grav": 0,
"monto_tot_exent": 0,
"monto_tot_ret": 0,
"imp_retenidos": [{"base": 0,
"impuesto": "IVA",
"monto": 0,
"tipo_pago_ret": 1
}
]
},
"external_id": "string",
"idempotency_key": "string",
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
]
}
]
}

Retrieve retention by ID

Retrieves a retention by its ID.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

retention_id

required

string

ID of the retention to retrieve

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/retentions/6062d9fb226600001cd22f71 \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "valid",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"type": "Retención",
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
},
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"cve_retenc": 1,
"fecha_exp": "2021-09-15T06:03:23.000Z",
"desc_retenc": "string",
"folio_int": "string",
"periodo": {"mes_ini": 1,
"mes_fin": 1,
"ejerc": 0
},
"totales": {"monto_tot_operacion": 0,
"monto_tot_grav": 0,
"monto_tot_exent": 0,
"monto_tot_ret": 0,
"imp_retenidos": [{"base": 0,
"impuesto": "IVA",
"monto": 0,
"tipo_pago_ret": 1
}
]
},
"external_id": "string",
"idempotency_key": "string",
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
]
}

Cancel retention

Request a cancellation of a retention from the SAT.

Unlike regular invoices, retention cancellations are immediate and do not require authorization from the recipient.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

retention_id

required

string

ID of the retention to cancel

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/retentions/6062d9fb226600001cd22f71 \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -X DELETE

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "valid",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"type": "Retención",
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"stamp": {"signature": "string",
"date": "2019-08-24T14:15:22Z",
"sat_cert_number": "string",
"sat_signature": "string"
},
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"cve_retenc": 1,
"fecha_exp": "2021-09-15T06:03:23.000Z",
"desc_retenc": "string",
"folio_int": "string",
"periodo": {"mes_ini": 1,
"mes_fin": 1,
"ejerc": 0
},
"totales": {"monto_tot_operacion": 0,
"monto_tot_grav": 0,
"monto_tot_exent": 0,
"monto_tot_ret": 0,
"imp_retenidos": [{"base": 0,
"impuesto": "IVA",
"monto": 0,
"tipo_pago_ret": 1
}
]
},
"external_id": "string",
"idempotency_key": "string",
"complements": [ ],
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
]
}

Download retention

Download a retention in PDF, XML or both in a ZIP file.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

retention_id required	string ID of the retention to download
format required	string Enum: "xml" "pdf" "zip" Format to download

Responses

Request samples

cURL
Node.js
C#
PHP

## Download PDF and XML compressed in a ZIP file
curl https://www.facturapi.io/v2/retentions/58e93bd8e86eb318b019743d/zip \
  -H "Authorization: Bearer sk_test_API_KEY"

## Download only the PDF
curl https://www.facturapi.io/v2/retentions/58e93bd8e86eb318b019743d/pdf \
  -H "Authorization: Bearer sk_test_API_KEY"

## Download only the XML
curl https://www.facturapi.io/v2/retentions/58e93bd8e86eb318b019743d/xml \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

400
401
500

Content type

application/json

{"message": "string"
}

Send retention by email

Send an email to the customer's address with the XML and PDF files attached to the message.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

retention_id

required

string

ID of the retention to send

Request Body schema: application/json
optional

	string or Array of strings Email address to send the retention. If this parameter is not sent, the retention will be sent to the email that the customer has registered.
One of string <email> Email address to send the retention.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"email": "another@email.com"
}

Response samples

200
400
401
500

Content type

application/json

{"ok": true
}

Organizations

Create organization

Create a new Organization that will belong to your user account.

After creating the organization and before being able to issue invoices with the organization, you will need to finish setting it up by calling the Update legal data and Upload certificates (CSD) methods.

Remember that the stamps of your subscription can be consumed by any of the organizations registered under your account.

Authorizations:

SecretUsertKey

Request Body schema: application/json
required

name

required

string <= 100 characters

Commercial name of the organization.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"name": "string"
}

Response samples

200
400
401
404
500

Content type

application/json

{"id": "5a2a307be93a2f00129ea035",
"created_at": "2017-05-05T20:55:33.468Z",
"is_production_ready": true,
"pending_steps": [{"type": "legal",
"description": "string"
}
],
"legal": {"name": "string",
"legal_name": "string",
"tax_system": "601",
"website": "string",
"phone": "string",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
}
},
"customization": {"has_logo": true,
"color": "BADA55",
"next_folio_number": 123,
"next_folio_number_test": 123,
"pdf_extra": {"codes": true,
"product_key": true,
"round_unit_price": false,
"tax_breakdown": true,
"ieps_breakdown": true
}
},
"certificate": {"has_certificates": true,
"updated_at": "2023-05-05T20:55:33.468Z",
"expires_at": "2025-05-05T20:55:33.468Z"
}
}

List organizations

Returns a paginated list of all the organizations registered under your account, or performs a search according to parameters.

Authorizations:

SecretUsertKey

query Parameters

q	string Free text search. Text to search in `name` (commercial name) or `legal_name` (fiscal name) or `tax_id` (RFC).
	object (DateRange) Object with requested date range.
page	integer >= 1 Page of results to return, starting from page 1.
limit	integer [ 1 .. 100 ] Default: 50 Number from 1 to 100 representing the maximum amount of results to return for pagination purposes.

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/organizations \
  -H "Authorization: Bearer sk_user_API_KEY"

Response samples

200
400
401
404
500

Content type

application/json

{"page": 1,
"total_pages": 1,
"total_results": 1,
"data": [{"id": "5a2a307be93a2f00129ea035",
"created_at": "2017-05-05T20:55:33.468Z",
"is_production_ready": true,
"pending_steps": [{"type": "legal",
"description": "string"
}
],
"legal": {"name": "string",
"legal_name": "string",
"tax_system": "601",
"website": "string",
"phone": "string",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
}
},
"customization": {"has_logo": true,
"color": "BADA55",
"next_folio_number": 123,
"next_folio_number_test": 123,
"pdf_extra": {"codes": true,
"product_key": true,
"round_unit_price": false,
"tax_breakdown": true,
"ieps_breakdown": true
}
},
"certificate": {"has_certificates": true,
"updated_at": "2023-05-05T20:55:33.468Z",
"expires_at": "2025-05-05T20:55:33.468Z"
}
}
]
}

Edit legal data

Update the legal information of the organization.

If you are looking for how to edit the RFC, remember that the tax_id property is automatically assigned when uploading the user's certificates (Certificado de Sello Digital or CSD).

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID of the organization to edit

Request Body schema: application/json
required

name required	string <= 100 characters Commercial name of the organization.
legal_name required	string <= 100 characters Fiscal or Legal Name of the organization, without the corporate regime (e.g.: S.A. de C.V.).
tax_system required	string = 3 characters Fiscal Regime Code, from the SAT catalog.
required	object (OrganizationAddress) Fiscal address of the issuing organization.
website	string Website of the organization, which will be referenced when sending the invoice by email.
support_email	string Email address for clarifications. It will appear in the invoice PDF and emails.
phone	string Phone number of the organization, which will appear in the invoice PDF and emails.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"name": "string",
"legal_name": "string",
"tax_system": "601",
"website": "string",
"support_email": "string",
"phone": "string",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
}
}

Response samples

200
400
401
404
500

Content type

application/json

Facturapi (2.0)

Customers

Create Customer

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List customers

Authorizations:

query Parameters

Responses

Request samples

Response samples

Retrieve customer by ID

Authorizations:

path Parameters

Responses

Request samples

Response samples

Edit Customer

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete Customer

Authorizations:

path Parameters

Responses

Request samples

Response samples

Validate Customer Tax Info

Authorizations:

path Parameters

Responses

Request samples

Response samples

Products

Create Product

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List products

Authorizations:

query Parameters

Responses

Request samples

Response samples

Retrieve product by ID

Authorizations:

path Parameters

Responses

Request samples

Response samples

Edit product

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete Product

Authorizations:

path Parameters

Responses

Request samples

Response samples

Invoices

Create invoice (CFDI 4.0)

Authorizations:

query Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List invoices

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
optional

Request Body schema: application/json
required