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.
default_invoice_use	string Default CFDI use for the customer.

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,
"default_invoice_use": "G01",
"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,
"default_invoice_use": "G01",
"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,
"default_invoice_use": "G01",
"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,
"default_invoice_use": "G01",
"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.
default_invoice_use	string Default CFDI use for the customer.
	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,
"default_invoice_use": "G01",
"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,
"default_invoice_use": "G01",
"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,
"default_invoice_use": "G01",
"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" "06" "07" "08" 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. `06`: Subect to tax IVA, but not IVA transferred. `07`: Not Subject to tax IVA, but required IEPS breakdown. `08`: Not Subject to tax IVA, and not required IEPS breakdown.
	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" "06" "07" "08" 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. `06`: Subect to tax IVA, but not IVA transferred. `07`: Not Subject to tax IVA, but required IEPS breakdown. `08`: Not Subject to tax IVA, and not required IEPS breakdown.
	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": [ ]
}
],
"payment_related_ids": [ ],
"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": [ ]
}
],
"payment_related_ids": [ ],
"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": [ ]
}
],
"payment_related_ids": [ ],
"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,
"default_invoice_use": "G01",
"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": [ ]
}
],
"payment_related_ids": [ ],
"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": [ ]
}
],
"payment_related_ids": [ ],
"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": [ ]
}
],
"payment_related_ids": [ ],
"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,
"default_invoice_use": "G01",
"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": [ ]
}
],
"payment_related_ids": [ ],
"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": [ ]
}
],
"payment_related_ids": [ ],
"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,
"default_invoice_use": "G01",
"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"
}
}
]
}

Organization detail

Returns the detail of a organization registered under your account.

Authorizations:

SecretLiveKeySecretTestKey

Responses

Request samples

cURL
Node.js
C#
PHP

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

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"
}
}

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

{"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"
}
}

Upload certificates (CSD)

Upload the files of the Digital Seal Certificate (Certificado de Sello Digital or CSD) provided by the SAT.

This call should also be used to replace existing certificates in case new ones are requested.

When updating your certificates, the RFC will be read and automatically assigned to legal.tax_id.

Don't use this endpoint to upload the FIEL certificate. The CSD is different from the FIEL certificate (Firma Electrónica). Please ask your accountant for the CSD.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID of the organization to upload certificates

Request Body schema: multipart/form-data
required

cerFile required	string <binary> Binary content of the file with extension `.cer` of the CSD certificate.
keyFile required	string <binary> Binary content of the file with extension `.key` of the CSD certificate.
password required	string Password of the certificate key.

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/certificate \
  -X PUT \
  -H "Authorization: Bearer sk_user_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F 'cer=@/path/to/your/CSD.cer' \
  -F 'key=@/path/to/your/CSD.key' \
  -F 'password=CONTRASEÑA_DEL_CERTIFICADO'

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"
}
}

Delete certificates (CSD)

Removes the certificates (CSD) from your organization.

Deleting the certificates will not affect the invoices already issued, but you will not be able to issue new invoices until you upload new certificates.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID of the organization to delete certificates

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/certificate \
  -X DELETE \
  -H "Authorization: Bearer sk_user_API_KEY"

Response samples

200
400
401
404
500

Content type

application/json

{"updated_at": "2019-08-24T14:15:22Z"
}

Upload logo

Upload the organization's logo. The logo will be displayed on the PDFs and emails sent to your customers.

The file must be an image in JPG or PNG format and have a size not greater than 500 KB. The recommended dimensions are 800 × 500px.

If the organization already has a logo, this call replaces the previous logo.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID of the organization

Request Body schema: multipart/form-data
required

file

required

string <binary>

Binary content of the file with the image to be used as a logo.

Supported formats:

jpg
png
svg

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/logo \
  -X PUT \
  -H "Authorization: Bearer sk_user_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F 'file=@/path/to/your/logo.jpg'

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"
}
}

Edit customization

Update the information related to the organization's identity or branding.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID of the organization

Request Body schema: application/json
required

color	string <hex> Distinctive color of the brand in Hexadecimal RGB representation of 6 characters.
next_folio_number	integer Folio number that will be assigned to the next invoice created in this organization in the Live environment. It will be automatically incremented for each new invoice.
next_folio_number_test	integer Folio number that will be assigned to the next invoice created in this organization in the Test environment. It will be automatically incremented for each new invoice.
	object Configure which optional fields you want to show in the PDF. The SAT does not require these fields to be shown, but they can be activated according to the organization's preference.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"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
}
}

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"
}
}

Edit receipts settings

Update the organization's receipts settings.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID of the organization

Request Body schema: application/json
required

periodicity	string Default: "month" Enum: "day" "week" "fortnight" "month" "two_months" Periodicity with which the company decides to issue a global invoice (to the general public) for all the receipts not invoiced. This value is used as the default when creating a global invoice.
duration_days	integer Default: 7 Maximum number of days to invoice through the self-invoicing portal after the receipt is issued and before the last day of the period defined by the `periodicity` attribute. The value `0` deactivates this option, making the receipts always expire on the last day of the period.
next_folio_number	integer Folio number that will be assigned to the next receipt created in this organization in the Live environment.
next_folio_number_test	integer Folio number that will be assigned to the next receipt created in this organization in the Test environment.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"periodicity": "day",
"duration_days": 7,
"next_folio_number": 0,
"next_folio_number_test": 0
}

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"
}
}

Check domain availability

Check if an identifier is available to choose as a domain for the autofactura portal.

Authorizations:

SecretUsertKey

query Parameters

domain

required

string (DomainField) [ 4 .. 50 ] characters ^[a-z][a-z0-9-_]{2,48}[a-z0-9]$

Domain name. Alphanumeric characters are allowed, only lowercase, hyphen (-) and underscore (_). It must start with a letter and end in a letter or number.

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/organizations/domain-check?domain=empresa-demo \
  -H "Authorization: Bearer sk_user_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"available": true
}

Choose self-invoice domain

Choose the domain that this organization will use in its self-invoice microsite. Once you choose the domain, you must contact us if you need to change it.

The domain you choose will be the one that appears in the self_invoice_url field when creating a new receipt, as follows:

https://factura.space/{DOMAIN}/{RECEIPT_KEY}

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID of the organization

Request Body schema: application/json
required

domain

required

string (DomainField) [ 4 .. 50 ] characters ^[a-z][a-z0-9-_]{2,48}[a-z0-9]$

Domain name. Alphanumeric characters are allowed, only lowercase, hyphen (-) and underscore (_). It must start with a letter and end in a letter or number.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"domain": "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"
}
}

Retrieve organization by ID

Retrieve the organization by its ID.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID of the organization

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
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"
}
}

Delete organization

Delete the organization from your Facturapi account. Once deleted, you will not be able to access its resources, such as clients, products, invoices, receipts, or retentions.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID of the organization

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
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"
}
}

Retrieve Test API Key

Retrieve API Key for the Test environment of the organization.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID of the organization

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

"sk_test_API_KEY"

Renew Test API Key

Renew the Test environment secret key of the organization and immediately invalidate the previous one.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID of the organization

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/apikeys/test \
  -X PUT \
  -H "Authorization: Bearer sk_user_API_KEY"

Response samples

200
400
401
500

Content type

application/json

"sk_test_API_KEY"

List Live API Keys

List secret keys of the organization's Live environment.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

Organization ID

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

[{"first_12": "string",
"created_at": "2019-08-24T14:15:22Z",
"id": "string"
}
]

Renew Live API Key

Generate a new Live environment secret key for the organization. This operation does not invalidate previously generated keys.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID of the organization

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/apikeys/live \
  -X PUT \
  -H "Authorization: Bearer sk_user_API_KEY"

Response samples

200
400
401
500

Content type

application/json

"sk_live_API_KEY"

Revoke Live API Key

Revoke the Live API Key of your organization.as

Authorizations:

SecretUsertKey

path Parameters

organization_id required	string Organization ID
id required	string ID of the Live API Key

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/apikeys/live/66f2ec798ca5a9b80c97db71 \
  -X DELETE \
  -H "Authorization: Bearer sk_user_API_KEY"

Response samples

200
400
401
500

Content type

application/json

[{"first_12": "string",
"created_at": "2019-08-24T14:15:22Z",
"id": "string"
}
]

Listado de series

Listado de series creadas para la personalización de organización. La cual lleva control de foliaje para cada tipo de factura si está asignada en las personalización de organización.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/series-group \
  -X GET \
  -H "Authorization: Bearer sk_user_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"data": [{"series": "New",
"next_folio": 123,
"next_folio_test": 123
}
]
}

Create Series

Create a new folio series for the organization. Series are useful for keeping track of the forms issued for each type of invoice

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Request Body schema: application/json

series required	string <= 55 characters Series name
next_folio required	integer Folio number that will be assigned to the next invoice in the Live environment (and will automatically increase with each new invoice).
next_folio_test required	integer Folio number that will be assigned to the next invoice in the Test environment (and will automatically increase with each new invoice).

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"series": "string",
"next_folio": 0,
"next_folio_test": 0
}

Response samples

200
400
401
500

Content type

application/json

{"series": "New",
"next_folio": 123,
"next_folio_test": 123
}

Update Series

Edit the folio number of the series in the Test and Live environments of the organization.

Authorizations:

SecretUsertKey

path Parameters

organization_id required	string ID de la organización
series_name required	string Series name

Request Body schema: application/json

next_folio	integer Folio number that will be assigned to the next invoice in the Live environment (and will automatically increase with each new invoice).
next_folio_test	integer Folio number that will be assigned to the next invoice in the Test environment (and will automatically increase with each new invoice).

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"next_folio": 0,
"next_folio_test": 0
}

Response samples

200
400
401
500

Content type

application/json

{"series": "New",
"next_folio": 123,
"next_folio_test": 123
}

Delete serie

Delete the series

Authorizations:

SecretUsertKey

path Parameters

organization_id required	string Organization Id
series_name required	string Series Name

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/organizations/5a2a307be93a2f00129ea035/series-group/New \
  -X DELETE \
  -H "Authorization: Bearer sk_user_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"series": "New",
"next_folio": 123,
"next_folio_test": 123
}

Tools

Health check

Check the health of the Facturapi API.

Authorizations:

SecretLiveKeySecretTestKey

Responses

Response samples

200

Content type

application/json

{"ok": true
}

Validate RFC (tax_id)

Check the status of an RFC in the list of EFOS (Empresas que Facturan Operaciones Simuladas). When appearing in this list, the RFC is or was suspected of engaging in simulated fiscal operations (factureras).

The response (detailed below) includes the results of this validation. It includes the boolean property is_valid, which Facturapi resolves by interpreting the response. A value of true for this property indicates that the RFC has no issues to resolve and is free of problems; and the opposite for false.

Additionally, you can check the data property to see the raw values of the query to the SAT.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

tax_id

required

string

Example: tax_id=BBA830831LJ2

RFC a validar

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/tools/tax_id_validation?tax_id=BBA830831LJ2 \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
500

Content type

application/json

{"efos": {"is_valid": true,
"data": {"mensaje": "string",
"fechaLista": "Information updated on September 17, 2023",
"detalles": [{"rfc": "NOR170627727",
"razonSocial": "NORMANDIA FERRE,",
"situacionContribuyente": "Definitivo",
"numFechaPresuncion": "500-05-2020-23758 de fecha 03 de noviembre de 2020",
"pubFechaSatPresuntos": "03/11/2020",
"numGlobalPresuncion": "500-05-2020-23758 de fecha 03 de noviembre de 2020",
"pubFechaDofPresuntos": "18/11/2020",
"pubSatDefinitivos": "500-05-2021-151",
"pubDofDefinitivos": "25/05/2021",
"numFechaSentFav": "500-05-2021-15156 de fecha 25 de mayo de 2021",
"pubSatSentFav": "08/06/2021"
}
]
}
}
}

Keys from SAT's catálogos

These are the main catalogs from SAT, included here for convenience. This is by no means the full list. You can find these and more catalogs on the official SAT website: http://omawww.sat.gob.mx/tramitesyservicios/Paginas/anexo_20_version3-3.htm

Forma de Pago

(Payment Form)

Key	Description (Spanish)	Description (English)
"01"	Efectivo	Cash
"02"	Cheque nominativo	Nominal check
"03"	Transferencia electrónica de fondos	Electronic transfer of funds
"04"	Tarjeta de crédito	Credit card
"05"	Monedero electrónico	Electronic wallet
"06"	Dinero electrónico	Mobile payment
"08"	Vales de despensa	Food vouchers
"12"	Dación en pago	Payment in kind
"13"	Pago por subrogación	Subrogation payment
"14"	Pago por consignación	Consignment payment
"15"	Condonación	Debt Forgiveness or Cancellation
"17"	Compensación	Settling Debts with Existing Credits
"23"	Novación	Novation
"24"	Confusión	Confusion
"25"	Remisión de deuda	Remission
"26"	Prescripción o caducidad	Expiration of the term
"27"	A satisfacción del acreedor	Satisfactory payment
"28"	Tarjeta de débito	Debit card
"29"	Servicio	Service payment
"30"	Aplicación de anticipos	Application of advanced payments
"31"	Intermediario pagos	Payment intermediation
"99"	Por definir	Pending definition

Método de Pago

(Payment Method)

Key	Description (Spanish)	Description (English)
"PUE"	Pago en Una [sola] Exhibición	Payment in a single installment
"PPD"	Pago en Parcialidades o Diferido	Payment in installments or deferred

Uso del CFDI

(CFDI use)

Key | Description (Spanish) | Description (English) | Allowed Fiscal Regimes :-----:| ----------- | ----------- "G01" | Adquisición de mercancías. | Purchase of goods | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626 "G02" | Devoluciones, descuentos y bonificaciones. | Returns, discounts and bonuses | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626 "G03" | Gastos en general. | General expenses | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626 "I01" | Construcciones. | Constructions | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626 "I02" | Mobiliario y equipo de oficina por inversiones. | Furniture and office equipment for investments | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626 "I03" | Equipo de transporte. | Transportation equipment | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626 "I04" | Equipo de computo y accesorios. | Computer equipment and accessories | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626 "I05" | Dados, troqueles, moldes, matrices y herramental. | Dies, molds, matrices and tools | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626 "I06" | Comunicaciones telefónicas. | Telephone communications | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626 "I07" | Comunicaciones satelitales. | Satellite communications | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626 "I08" | Otra maquinaria y equipo. | Other machinery and equipment | 601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626 "D01" | Honorarios médicos, dentales y gastos hospitalarios. | Medical, dental and hospital expenses. | 605, 606, 608, 611, 612, 614, 607, 615, 625 "D02" | Gastos médicos por incapacidad o discapacidad. | Medical expenses for disability. | 605, 606, 608, 611, 612, 614, 607, 615, 625 "D03" | Gastos funerales. | Funeral expenses. | 605, 606, 608, 611, 612, 614, 607, 615, 625 "D04" | Donativos. | Donations. | 605, 606, 608, 611, 612, 614, 607, 615, 625 "D05" | Intereses reales efectivamente pagados por créditos hipotecarios (casa habitación). | Real interest actually paid for mortgage loans (housing). | 605, 606, 608, 611, 612, 614, 607, 615, 625 "D06" | Aportaciones voluntarias al SAR. | Voluntary contributions to the SAR. | 605, 606, 608, 611, 612, 614, 607, 615, 625 "D07" | Primas por seguros de gastos médicos. | Premiums for medical expenses insurance. | 605, 606, 608, 611, 612, 614, 607, 615, 625 "D08" | Gastos de transportación escolar obligatoria. | Mandatory school transportation expenses. | 605, 606, 608, 611, 612, 614, 607, 615, 625 "D09" | Depósitos en cuentas para el ahorro, primas que tengan como base planes de pensiones. | 605, 606, 608, 611, 612, 614, 607, 615, 625 "D10" | Pagos por servicios educativos (colegiaturas). | 605, 606, 608, 611, 612, 614, 607, 615, 625 "S01" | Sin efectos fiscales. | 601, 603, 605, 606, 608, 610, 611, 612, 614, 616, 620, 621, 622, 623, 624, 607, 615, 625, 626 "CP01" | Pagos | 601, 603, 605, 606, 608, 610, 611, 612, 614, 616, 620, 621, 622, 623, 624, 607, 615, 625, 626 "CN01" | Nómina | 605

Relación entre facturas

(Relation between invoices)

Key	Description (Spanish)	Description (English)
"01"	Nota de crédito de los documentos relacionados	Credit note of the related documents
"02"	Nota de débito de los documentos relacionados	Debit note of the related documents
"03"	Devolución de mercancía sobre facturas o traslados previos	Return of goods on invoices or previous transfers
"04"	Sustitución de los CFDI previos	Replacement of previous CFDI
"05"	Traslados de mercancias facturados previamente	Transfers of goods previously invoiced
"06"	Factura generada por los traslados previos	Invoice generated by previous transfers
"07"	CFDI por aplicación de anticipo	CFDI by advance payment application
"08"	Factura generada por pagos en parcialidades	Invoice generated by payments in installments
"09"	Factura generada por pagos diferidos	Invoice generated by deferred payments

Régimen Fiscal

(Fiscal Regimes or Tax Systems)

Key	Description (Spanish)	Description (English)
"601"	General de Ley Personas Morales	General Law of Legal Entities
"603"	Personas Morales con Fines no Lucrativos	Non-profit Legal Entities
"605"	Sueldos y Salarios e Ingresos Asimilados a Salarios	Wages and Salaries and Assimilated Income
"606"	Arrendamiento	Rent
"608"	Demás ingresos	Other income
"609"	Consolidación	Consolidation
"610"	Residentes en el Extranjero sin Establecimiento Permanente en México	Non-residents with no Permanent Establishment in Mexico
"611"	Ingresos por Dividendos (socios y accionistas)	Dividends (partners and shareholders)
"612"	Personas Físicas con Actividades Empresariales y Profesionales	Individuals with Business and Professional Activities
"614"	Ingresos por intereses	Interest income
"616"	Sin obligaciones fiscales	No tax obligations
"620"	Sociedades Cooperativas de Producción que optan por diferir sus ingresos	Production Cooperatives that choose to defer their income
"621"	Incorporación Fiscal	Fiscal Incorporation
"622"	Actividades Agrícolas, Ganaderas, Silvícolas y Pesqueras	Agricultural, Livestock, Forestry and Fishing Activities
"623"	Opcional para Grupos de Sociedades	Optional for Groups of Companies
"624"	Coordinados	Coordinated
"628"	Hidrocarburos	Hydrocarbons
"607"	Régimen de Enajenación o Adquisición de Bienes	Regime of Alienation or Acquisition of Goods
"629"	De los Regímenes Fiscales Preferentes y de las Empresas Multinacionales	Of Preferential Tax Regimes and Multinational Companies
"630"	Enajenación de acciones en bolsa de valores	Sale of shares on the stock exchange
"615"	Régimen de los ingresos por obtención de premios	Regime of income from obtaining prizes
"625"	Régimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas	Regime of Business Activities with income through Technological Platforms
"626"	Régimen Simplificado de Confianza	Simplified Trust Regime

Meses y bimestres

(Months and bimesters)

Key	Description (Spanish)	Description (English)
01	Enero	January
02	Febrero	February
03	Marzo	March
04	Abril	April
05	Mayo	May
06	Junio	June
07	Julio	July
08	Agosto	August
09	Septiembre	September
10	Octubre	October
11	Noviembre	November
12	Diciembre	December
13	Enero-Febrero	January-February
14	Marzo-Abril	March-April
15	Mayo-Junio	May-June
16	Julio-Agosto	July-August
17	Septiembre-Octubre	September-October
18	Noviembre-Diciembre	November-December

Tipo de Contrato

(Type of Contract)

Key	Description (Spanish)	Description (English)
"01"	Contrato de trabajo por tiempo indeterminado	Indefinite term employment contract
"02"	Contrato de trabajo para obra determinada	Employment contract for a specific work
"03"	Contrato de trabajo por tiempo determinado	Employment contract for a fixed term
"04"	Contrato de trabajo por temporada	Seasonal employment contract
"05"	Contrato de trabajo sujeto a prueba	Employment contract subject to trial
"06"	Contrato de trabajo con capacitación inicial	Employment contract with initial training
"07"	Modalidad de contratación por pago de hora laborada	Modality of hiring by payment of hours worked
"08"	Modalidad de trabajo por comisión laboral	Labor commission work modality
"09"	Modalidades de contratación donde no existe relación de trabajo	Hiring modalities where there is no employment relationship
"10"	Jubilación, pensión, retiro.	Retirement, pension, retirement.
"99"	Otro contrato	Other contract

Tipo de Jornada

(Type of Labor Day)

Key	Description (Spanish)	Description (English)
"01"	Diurna	Daytime
"02"	Nocturna	Night
"03"	Mixta	Mixed
"04"	Por hora	By the hour
"05"	Reducida	Reduced
"06"	Continuada	Continued
"07"	Partida	Split
"08"	Por turnos	By shifts
"99"	Otra Jornada	Other day

Tipo de Régimen

(Type of Regime)

Key	Description (Spanish)	Description (English)
"02"	Sueldos (Incluye ingresos señalados en la fracción I del artículo 94 de LISR)	Salaries (Includes income referred to in section I of article 94 of LISR)
"03"	Jubilados	Retirees
"04"	Pensionados	Pensioners
"05"	Asimilados Miembros Sociedades Cooperativas Produccion	Assimilated Members of Production Cooperatives
"06"	Asimilados Integrantes Sociedades Asociaciones Civiles	Assimilated Members of Civil Associations
"07"	Asimilados Miembros Consejos Administración Sociedades Mercantiles	Assimilated Members of the Boards of Directors of Commercial Companies
"08"	Asimilados comisionistas	Assimilated commission agents
"09"	Asimilados Honorarios	Assimilated Fees
"10"	Asimilados acciones	Assimilated shares
"11"	Asimilados otros	Assimilated others
"12"	Jubilados o Pensionados	Retirees or Pensioners
"13"	Indemnización o Separación	Compensation or Separation
"99"	Otro Regimen	Other Regime

Riesgo del Puesto

(Risk of the Position)

Key	Description (Spanish)	Description (English)
"1"	Clase I	Class I
"2"	Clase II	Class II
"3"	Clase III	Class III
"4"	Clase IV	Class IV
"5"	Clase V	Class V
"99"	No aplica	Does not apply

Periodicidad del Pago

(Payment Frequency)

Key	Description (Spanish)	Description (English)
"01"	Diario	Daily
"02"	Semanal	Weekly
"03"	Catorcenal	Biweekly
"04"	Quincenal	Fortnightly
"05"	Mensual	Monthly
"06"	Bimestral	Bimonthly
"07"	Unidad obra	Work unit
"08"	Comisión	Commission
"09"	Precio alzado	Fixed price
"10"	Decenal	Ten-day
"99"	Otra Periodicidad	Other Frequency

Tipo de Percepción

(Type of Earnings)

Key	Description (Spanish)	Description (English)
"001"	Sueldos, Salarios Rayas y Jornales	Wages, Salaries, Stripes and Wages
"002"	Gratificación Anual (Aguinaldo)	Annual Bonus (Aguinaldo)
"003"	Participación de los Trabajadores en las Utilidades PTU	Participation of Workers in Profits PTU
"004"	Reembolso de Gastos Médicos Dentales y Hospitalarios	Reimbursement of Medical, Dental and Hospital Expenses
"005"	Fondo de Ahorro	Savings Fund
"006"	Caja de ahorro	Savings box
"009"	Contribuciones a Cargo del Trabajador Pagadas por el Patrón	Contributions to be paid by the Worker Paid by the Employer
"010"	Premios por puntualidad	Punctuality Awards
"011"	Prima de Seguro de vida	Life Insurance Premium
"012"	Seguro de Gastos Médicos Mayores	Major Medical Expenses Insurance
"013"	Cuotas Sindicales Pagadas por el Patrón	Union Dues Paid by the Employer
"014"	Subsidios por incapacidad	Disability Subsidies
"015"	Becas para trabajadores y/o hijos	Scholarships for workers and / or children
"019"	Horas extra	Extra hours
"020"	Prima dominical	Sunday premium
"021"	Prima vacacional	Vacation premium
"022"	Prima por antigüedad	Seniority premium
"023"	Pagos por separación	Separation payments
"024"	Seguro de retiro	Retirement insurance
"025"	Indemnizaciones	Indemnities
"026"	Reembolso por funeral	Funeral refund
"027"	Cuotas de seguridad social pagadas por el patrón	Social security fees paid by the employer
"028"	Comisiones	Commissions
"029"	Vales de despensa	Food vouchers
"030"	Vales de restaurante	Restaurant vouchers
"031"	Vales de gasolina	Gasoline vouchers
"032"	Vales de ropa	Clothing vouchers
"033"	Ayuda para renta	Help for rent
"034"	Ayuda para artículos escolares	Help for school supplies
"035"	Ayuda para anteojos	Help for glasses
"036"	Ayuda para transporte	Transportation help
"037"	Ayuda para gastos de funeral	Help for funeral expenses
"038"	Otros ingresos por salarios	Other income from salaries
"039"	Jubilaciones, pensiones o haberes de retiro en una sola exhibición	Retirement, pensions or retirement benefits in a single exhibition
"044"	Jubilaciones, pensiones o haberes de retiro en parcialidades	Retirement, pensions or retirement benefits in installments
"045"	Ingresos en acciones o títulos valor que representan bienes	Income in shares or securities representing goods
"046"	Ingresos asimilados a salarios	Income assimilated to salaries
"047"	Alimentación diferentes a los establecidos en el Art 94 último párrafo LISR	Food other than those established in Art 94 last paragraph LISR
"048"	Habitación	Room
"049"	Premios por asistencia	Attendance awards
"050"	Viáticos	Travel allowances
"051"	Pagos por gratificaciones, primas, compensaciones, recompensas u otros en parcialidades	Payments for bonuses, bonuses, compensations, rewards or others in installments
"052"	Pagos por jubilación en parcialidades derivados de una resolución judicial	Retirement payments in installments derived from a judicial resolution
"053"	Pagos por jubilación en una sola exhibición derivados de la ejecución de una resolución judicial	Retirement payments in a single exhibition derived from the execution of a judicial resolution

Tipo de Horas

(Type of Hours)

Key	Description (Spanish)	Description (English)
"01"	Dobles	Doubles
"02"	Triples	Triples
"03"	Simples	Singles

Tipo de Deducción

(Type of Deduction)

Key	Description (Spanish)	Description (English)
"001"	Seguridad social	Social security
"002"	ISR	ISR (Income Tax)
"003"	Aportaciones a retiro, cesantía en edad avanzada y vejez.	Contributions to retirement, old age and old age.
"004"	Otros	Others
"005"	Aportaciones a Fondo de vivienda	Contributions to Housing Fund
"006"	Descuento por incapacidad	Disability discount
"007"	Pensión alimenticia	Alimony
"008"	Renta	Rent
"009"	Préstamos provenientes del Fondo Nacional de la Vivienda para los Trabajadores	Loans from the National Housing Fund for Workers
"010"	Pago por crédito de vivienda	Payment for housing credit
"011"	Pago de abonos INFONACOT	Payment of INFONACOT installments
"012"	Anticipo de salarios	Salary advance
"013"	Pagos hechos con exceso al trabajador	Payments made in excess to the worker
"014"	Errores	Errors
"015"	Pérdidas	Losses
"016"	Averías	Breakdowns
"017"	Adquisición de artículos producidos por la empresa o establecimiento	Acquisition of items produced by the company or establishment
"018"	Cuotas para la constitución y fomento de sociedades cooperativas y de cajas de ahorro	Fees for the constitution and promotion of cooperative societies and savings banks
"019"	Cuotas sindicales	Union fees
"020"	Ausencia (Ausentismo)	Absence (Absenteeism)
"021"	Cuotas obrero patronales	Worker-employer fees
"022"	Impuestos Locales	Local Taxes
"023"	Aportaciones voluntarias al SAR	Voluntary contributions to the SAR
"024"	Ajuste en Gratificación Anual (Aguinaldo) Exento	Adjustment in Annual Bonus (Aguinaldo) Exempt
"025"	Ajuste en Gratificación Anual (Aguinaldo) Gravado	Adjustment in Annual Bonus (Aguinaldo) Taxed
"026"	Ajuste en Participación de los Trabajadores en las Utilidades PTU Exento	Adjustment in Workers' Participation in Profits PTU Exempt
"027"	Ajuste en Participación de los Trabajadores en las Utilidades PTU Gravado	Adjustment in Workers' Participation in Profits PTU Taxed
"028"	Ajuste en Reembolso de Gastos Médicos Dentales y Hospitalarios Exento	Adjustment in Reimbursement of Medical, Dental and Hospital Expenses Exempt
"029"	Ajuste en Fondo de ahorro Exento	Adjustment in Savings Fund Exempt
"030"	Ajuste en Caja de ahorro Exento	Adjustment in Savings Box Exempt
"031"	Ajuste en Contribuciones a Cargo del Trabajador Pagadas por el Patrón Exento	Adjustment in Contributions to be paid by the Worker Paid by the Employer Exempt
"032"	Ajuste en Premios por puntualidad Gravado	Adjustment in Punctuality Awards Taxed
"033"	Ajuste en Prima de Seguro de vida Exento	Adjustment in Life Insurance Premium Exempt
"034"	Ajuste en Seguro de Gastos Médicos Mayores Exento	Adjustment in Major Medical Expenses Insurance Exempt
"035"	Ajuste en Cuotas Sindicales Pagadas por el Patrón Exento	Adjustment in Union Dues Paid by the Employer Exempt
"036"	Ajuste en Subsidios por incapacidad Exento	Adjustment in Disability Subsidies Exempt
"037"	Ajuste en Becas para trabajadores y/o hijos Exento	Adjustment in Scholarships for workers and / or children Exempt
"038"	Ajuste en Horas extra Exento	Adjustment in Extra hours Exempt
"039"	Ajuste en Horas extra Gravado	Adjustment in Extra hours Taxed
"040"	Ajuste en Prima dominical Exento	Adjustment in Sunday premium Exempt
"041"	Ajuste en Prima dominical Gravado	Adjustment in Sunday premium Taxed
"042"	Ajuste en Prima vacacional Exento	Adjustment in Vacation premium Exempt
"043"	Ajuste en Prima vacacional Gravado	Adjustment in Vacation premium Taxed
"044"	Ajuste en Prima por antigüedad Exento	Adjustment in Seniority premium Exempt
"045"	Ajuste en Prima por antigüedad Gravado	Adjustment in Seniority premium Taxed
"046"	Ajuste en Pagos por separación Exento	Adjustment in Separation payments Exempt
"047"	Ajuste en Pagos por separación Gravado	Adjustment in Separation payments Taxed
"048"	Ajuste en Seguro de retiro Exento	Adjustment in Retirement insurance Exempt
"049"	Ajuste en Indemnizaciones Exento	Adjustment in Indemnities Exempt
"050"	Ajuste en Indemnizaciones Gravado	Adjustment in Indemnities Taxed
"051"	Ajuste en Reembolso por funeral Exento	Adjustment in Funeral refund Exempt
"052"	Ajuste en Cuotas de seguridad social pagadas por el patrón Exento	Adjustment in Social security fees paid by the employer Exempt
"053"	Ajuste en Comisiones Gravado	Adjustment in Commissions Taxed
"054"	Ajuste en Vales de despensa Exento	Adjustment in Food vouchers Exempt
"055"	Ajuste en Vales de restaurante Exento	Adjustment in Restaurant vouchers Exempt
"056"	Ajuste en Vales de gasolina Exento	Adjustment in Gasoline vouchers Exempt
"057"	Ajuste en Vales de ropa Exento	Adjustment in Clothing vouchers Exempt
"058"	Ajuste en Ayuda para renta Exento	Adjustment in Help for rent Exempt
"059"	Ajuste en Ayuda para artículos escolares Exento	Adjustment in Help for school supplies Exempt
"060"	Ajuste en Ayuda para anteojos Exento	Adjustment in Help for glasses Exempt
"061"	Ajuste en Ayuda para transporte Exento	Adjustment in Transportation help Exempt
"062"	Ajuste en Ayuda para gastos de funeral Exento	Adjustment in Help for funeral expenses Exempt
"063"	Ajuste en Otros ingresos por salarios Exento	Adjustment in Other income from salaries Exempt
"064"	Ajuste en Otros ingresos por salarios Gravado	Adjustment in Other income from salaries Taxed
"065"	Ajuste en Jubilaciones, pensiones o haberes de retiro en una sola exhibición Exento	Adjustment in Retirement, pensions or retirement benefits in a single exhibition Exempt
"066"	Ajuste en Jubilaciones, pensiones o haberes de retiro en una sola exhibición Gravado	Adjustment in Retirement, pensions or retirement benefits in a single exhibition Taxed
"067"	Ajuste en Pagos por separación Acumulable	Adjustment in Separation payments Accumulable
"068"	Ajuste en Pagos por separación No acumulable	Adjustment in Separation payments Non-accumulable
"069"	Ajuste en Jubilaciones, pensiones o haberes de retiro en parcialidades Exento	Adjustment in Retirement, pensions or retirement benefits in installments Exempt
"070"	Ajuste en Jubilaciones, pensiones o haberes de retiro en parcialidades Gravado	Adjustment in Retirement, pensions or retirement benefits in installments Taxed
"071"	Ajuste en Subsidio para el empleo (efectivamente entregado al trabajador)	Adjustment in Employment subsidy (effectively delivered to the worker)
"072"	Ajuste en Ingresos en acciones o títulos valor que representan bienes Exento	Adjustment in Income in shares or securities representing goods Exempt
"073"	Ajuste en Ingresos en acciones o títulos valor que representan bienes Gravado	Adjustment in Income in shares or securities representing goods Taxed
"074"	Ajuste en Alimentación Exento	Adjustment in Food Exempt
"075"	Ajuste en Alimentación Gravado	Adjustment in Food Taxed
"076"	Ajuste en Habitación Exento	Adjustment in Room Exempt
"077"	Ajuste en Habitación Gravado	Adjustment in Room Taxed
"078"	Ajuste en Premios por asistencia Exento	Adjustment in Attendance awards Exempt
"079"	Ajuste en Pagos distintos a los listados Exento	Adjustment in Payments other than those listed Exempt
"080"	Ajuste en Viáticos gravados	Adjustment in Taxable travel expenses
"081"	Ajuste en Viáticos (entregados al trabajador)	Adjustment in Travel expenses (delivered to the worker)
"082"	Ajuste en Fondo de ahorro Gravado	Adjustment in Savings Fund Taxed
"083"	Ajuste en Caja de ahorro Gravado	Adjustment in Savings Box Taxed
"084"	Ajuste en Prima de Seguro de vida Gravado	Adjustment in Life Insurance Premium Taxed
"085"	Ajuste en Seguro de Gastos Médicos Mayores Gravado	Adjustment in Major Medical Expenses Insurance Taxed
"086"	Ajuste en Subsidios por incapacidad Gravado	Adjustment in Disability Subsidies Taxed
"087"	Ajuste en Becas para trabajadores y/o hijos Gravado	Adjustment in Scholarships for workers and / or children Taxed
"088"	Ajuste en Seguro de retiro Gravado	Adjustment in Retirement insurance Taxed
"089"	Ajuste en Vales de despensa Gravado	Adjustment in Food vouchers Taxed
"090"	Ajuste en Vales de restaurante Gravado	Adjustment in Restaurant vouchers Taxed
"091"	Ajuste en Vales de gasolina Gravado	Adjustment in Gasoline vouchers Taxed
"092"	Ajuste en Vales de ropa Gravado	Adjustment in Clothing vouchers Taxed
"093"	Ajuste en Ayuda para renta Gravado	Adjustment in Help for rent Taxed
"094"	Ajuste en Ayuda para artículos escolares Gravado	Adjustment in Help for school supplies Taxed
"095"	Ajuste en Ayuda para anteojos Gravado	Adjustment in Help for glasses Taxed
"096"	Ajuste en Ayuda para transporte Gravado	Adjustment in Transportation help Taxed
"097"	Ajuste en Ayuda para gastos de funeral Gravado	Adjustment in Help for funeral expenses Taxed
"098"	Ajuste a ingresos asimilados a salarios gravados	Adjustment to income assimilated to taxed salaries
"099"	Ajuste a ingresos por sueldos y salarios gravados	Adjustment to income for taxed wages and salaries
"100"	Ajuste en Viáticos exentos	Adjustment in Exempt travel expenses
"101"	ISR Retenido de ejercicio anterior	ISR Retained from previous exercise
"102"	Ajuste a pagos por gratificaciones, primas, compensaciones, recompensas u otros gravados	Adjustment to payments for bonuses, bonuses, compensations, rewards or others taxed
"103"	Ajuste a pagos en parcialidades derivados de una resolución judicial gravados	Adjustment to payments in installments derived from a judicial resolution taxed
"104"	Ajuste a pagos en parcialidades derivados de una resolución judicial exentos	Adjustment to payments in installments derived from a judicial resolution exempt
"105"	Ajuste a pagos en una sola exhibición derivados de una resolución judicial gravados	Adjustment to payments in a single exhibition derived from a judicial resolution taxed
"106"	Ajuste a pagos en una sola exhibición derivados de una resolución judicial exentos	Adjustment to payments in a single exhibition derived from a judicial resolution exempt
"107"	Ajuste al Subsidio Causado	Adjustment to Accrued Subsidy

Tipo de Otro Pago

(Type of Other Payment)

Key	Description (Spanish)	Description (English)
"001"	Reintegro de ISR pagado en exceso.	Refund of ISR paid in excess.
"002"	Subsidio para el empleo (efectivamente entregado al trabajador).	Employment subsidy (effectively delivered to the worker).
"003"	Viáticos (entregados al trabajador).	Travel expenses (delivered to the worker).
"004"	Aplicación de saldo a favor por compensación anual.	Application of balance in favor by annual compensation.
"005"	Reintegro de ISR retenido en exceso de ejercicio anterior	Refund of ISR retained in excess of previous exercise
"006"	Alimentos en bienes (Servicios de comedor y comida).	Food in goods (Dining and food services).
"007"	ISR ajustado por subsidio.	ISR adjusted by subsidy.
"008"	Subsidio efectivamente entregado que no correspondía.	Subsidy effectively delivered that did not correspond.
"009"	Reembolso de descuentos efectuados para el crédito de vivienda.	Refund of discounts made for housing credit.
"999"	Pagos distintos a los listados.	Payments other than those listed.

Tipo de Incapacidad

(Type of Disability)

Key	Description (Spanish)	Description (English)
"01"	Riesgo de trabajo.	Work risk.
"02"	Enfermedad en general.	General illness.
"03"	Maternidad.	Maternity.
"04"	Licencia por cuidados médicos de hijos diagnosticados con cáncer.	License for medical care of children diagnosed with cancer.

Clave de retención

(Retention Key)

Key	Description (Spanish)	Description (English)
"01"	Servicios profesionales.	Professional services.
"02"	Regalías por derechos de autor.	Royalties for copyright.
"03"	Autotransporte terrestre de carga.	Land cargo transportation.
"04"	Servicios prestados por comisionistas.	Services provided by commission agents.
"05"	Arrendamiento.	Lease.
"06"	Enajenación de acciones.	Sale of shares.
"07"	Enajenación de bienes objeto de la LIEPS, a través de mediadores, agentes, representantes, corredores, consignatarios o distribuidores.	Sale of goods subject to LIEPS, through mediators, agents, representatives, brokers, consignees or distributors.
"08"	Enajenación de bienes inmuebles consignada en escritura pública.	Sale of real estate consigned in a public deed.
"09"	Enajenación de otros bienes, no consignada en escritura pública.	Sale of other goods, not consigned in a public deed.
"10"	Adquisición de desperdicios industriales.	Acquisition of industrial waste.
"11"	Adquisición de bienes consignada en escritura pública.	Acquisition of goods consigned in a public deed.
"12"	Adquisición de otros bienes, no consignada en escritura pública.	Acquisition of other goods, not consigned in a public deed.
"13"	Otros retiros de AFORE.	Other withdrawals from AFORE.
"14"	Dividendos o utilidades distribuidas.	Dividends or distributed profits.
"15"	Remanente distribuible.	Distributable remnant.
"16"	Intereses.	Interests.
"17"	Arrendamiento en fideicomiso.	Lease in trust.
"18"	Pagos realizados a favor de residentes en el extranjero.	Payments made in favor of residents abroad.
"19"	Enajenación de acciones u operaciones en bolsa de valores.	Sale of shares or operations on the stock exchange.
"20"	Obtención de premios.	Obtaining prizes.
"21"	Fideicomisos que no realizan actividades empresariales.	Trusts that do not carry out business activities.
"22"	Planes personales de retiro.	Personal retirement plans.
"23"	Intereses reales deducibles por créditos hipotecarios.	Real interests deductible for mortgage loans.
"24"	Operaciones Financieras Derivadas de Capital.	Capital Derivative Financial Operations.
"25"	Otro tipo de retenciones.	Other types of retentions.
"26"	Servicios mediante Plataformas Tecnológicas	Services through Technological Platforms

Validez de obligaciones

(Validity of obligations)

Validity	Exempt IVA	Rate 0%	Rate 8% Noth Border	Rate 8% South Border	Rate 16%
"0"	The taxpayer is not authorized to issue invoices
"1"	Yes	Yes	No	No	Yes
"2"	Yes	Yes	Yes	No	Yes
"3"	Yes	Yes	No	Yes	Yes
"4"	Yes	Yes	Yes	Yes	Yes

Situación del contribuyente

(Taxpayer situation)

| Value | Description |:-----:|:-----------|:----------- | "Previsto" (Announced) | The taxpayer receives a letter via tax mailbox or notifications by means of a notice board, in which his situation is established and he is asked to demonstrate the materiality of the invoiced operations. | "Presunto" (Pressumed) | The notified taxpayer is considered presumed when, on its website, the authority issues its data within the list of EFOS, that is, in the SAT's blacklists. | "Desvirtuado" (Disproved) | In this case, the taxpayer accused of non-existent operations has already provided the authority with the documentation and information necessary to refute the facts that led to the notification. | "Definitivo" (Definitive) | In this case, the EFO did not respond to the authority's call within 15 days, from the last notification; or could not refute the imputed facts. | "Sentencia favorable" (Favorable sentence) | Taxpayers EFOS "definitive" who are dissatisfied and file some means of defense, which concludes in their favor, are classified in the list of "favorable judgment". | "EFOS de información suprimida" (Redacted information EFOS) | In this category, the EFOS "presumed" and "definitive" are found that presented some means of defense (amparo, nullity trial) and, therefore, a judge ordered to suppress their data from the list, without being eliminated.

Product/Service Key

Search in the SAT Product/Service catalog, which contains the key to include in the invoice.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

q	string Text search. Text to search in the product/service classification description.
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/catalogs/products?q=ukelele \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
404
500

Content type

application/json

{"page": 1,
"total_pages": 1,
"total_results": 1,
"data": [{"key": 60131324,
"description": "Ukelele",
"score": 0.8
}
]
}

Units of Measure

Search in the SAT Units of Measure catalog.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

q	string Query. Text to search in the description of the unit of measure.
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/catalogs/units?q=pulgada \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
404
500

Content type

application/json

{"page": 1,
"total_pages": 1,
"total_results": 1,
"data": [{"key": "INH",
"description": "Pulgada",
"score": 0.9
}
]
}

Events

Events occur when Facturapi performs an operation asynchronously, outside the lifecycle of an API request.

To receive these events on your server, you can register a listening URL by creating a Webhook from your dashboard: https://dashboard.facturapi.io/integration/webhooks

Global invoice created Webhook

Notifies about the creation of a global invoice from e-Receipts.

Request Body schema: application/json
required

id	string ID of the event
created_at	string <date-time> Creation date and time of the event
livemode	boolean Indicates if the event was generated in Test mode (false) or Live mode (true).
organization	string ID of the organization this event is related to
type	string Value: "invoice.global_invoice_created" Type of event
	object

Request samples

Payload

Content type

application/json

{"id": "string",
"created_at": "2019-08-24T14:15:22Z",
"livemode": true,
"organization": "string",
"type": "invoice.global_invoice_created",
"data": {"type": "invoice",
"object": {"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": [ ]
}
],
"payment_related_ids": [ ],
"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"
}
}
}
}

Invoice status updated Webhook

Notifies about changes in the status field of an invoice.

Used in the case of having created the invoice asynchronously (async param).

Request Body schema: application/json
required

id	string ID of the event
created_at	string <date-time> Creation date and time of the event
livemode	boolean Indicates if the event was generated in Test mode (false) or Live mode (true).
organization	string ID of the organization this event is related to
type	string Value: "invoice.status_updated" Type of event
	object

Request samples

Payload

Content type

application/json

{"id": "string",
"created_at": "2019-08-24T14:15:22Z",
"livemode": true,
"organization": "string",
"type": "invoice.status_updated",
"data": {"type": "invoice",
"object": {"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": [ ]
}
],
"payment_related_ids": [ ],
"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 status updated Webhook

Notifies about changes in the cancellation_status field of an invoice.

Request Body schema: application/json
required

id	string ID of the event
created_at	string <date-time> Creation date and time of the event
livemode	boolean Indicates if the event was generated in Test mode (false) or Live mode (true).
organization	string ID of the organization this event is related to
type	string Value: "invoice.cancellation_status_updated" Type of event
	object

Request samples

Payload

Content type

application/json

{"id": "string",
"created_at": "2019-08-24T14:15:22Z",
"livemode": true,
"organization": "string",
"type": "invoice.cancellation_status_updated",
"data": {"type": "invoice",
"object": {"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": [ ]
}
],
"payment_related_ids": [ ],
"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"
}
}
}
}

Self-invoice completed Webhook

Notifies about the completion of a self-invoice.

Request Body schema: application/json
required

id	string ID of the event
created_at	string <date-time> Creation date and time of the event
livemode	boolean Indicates if the event was generated in Test mode (false) or Live mode (true).
organization	string ID of the organization this event is related to
type	string Value: "receipt.self_invoice_complete" Type of event
	object

Request samples

Payload

Content type

application/json

{"id": "string",
"created_at": "2019-08-24T14:15:22Z",
"livemode": true,
"organization": "string",
"type": "receipt.self_invoice_complete",
"data": {"type": "receipt",
"object": {"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"
}
}
}

Receipt status updated Webhook

Notifies about changes in the status field of a receipt.

Request Body schema: application/json
required

id	string ID of the event
created_at	string <date-time> Creation date and time of the event
livemode	boolean Indicates if the event was generated in Test mode (false) or Live mode (true).
organization	string ID of the organization this event is related to
type	string Value: "receipt.status_updated" Type of event
	object

Request samples

Payload

Content type

application/json

{"id": "string",
"created_at": "2019-08-24T14:15:22Z",
"livemode": true,
"organization": "string",
"type": "receipt.status_updated",
"data": {"type": "receipt",
"object": {"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"
}
}
}

Webhooks

Create webhook

Register a new webhook in your Facturapi organization.

Use this call to receive notifications of asynchronous events to the API.

Test and live environment webhooks are independent.

Authorizations:

SecretLiveKeySecretTestKey

Request Body schema: application/json
required

enabled_events required	Array of strings Items Enum: "invoice.global_invoice_created" "invoice.status_updated" "invoice.cancellation_status_updated" "receipt.self_invoice_complete" "receipt.status_updated" "receipt.cancellation_status_updated" Events enabled for the webhook to listen to.
url required	string Full URL of the webhook listener.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"url": "http://webhook_api.com",
"enabled_events": ["receipt.self_invoice_complete"
]
}

Response samples

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"organization": "string",
"enabled_events": ["receipt.cancellation_status"
],
"url": "http://my-website.com/my/webhook",
"status": "enabled"
}

List webhooks

Returns a list of webhooks created previously for the organization.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

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/webhooks \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -G \
  -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,
"organization": "string",
"enabled_events": ["receipt.cancellation_status"
],
"url": "http://my-website.com/my/webhook",
"status": "enabled"
}
]
}

Retrieve webhook by ID

Retrieve the webhook subscription by its ID.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

webhook_id

required

string

ID of the webhook

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/webhooks/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,
"organization": "string",
"enabled_events": ["receipt.cancellation_status"
],
"url": "http://my-website.com/my/webhook",
"status": "enabled"
}

Edit webhook

Update the information of an existing webhook with the parameters you send in the request.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

webhook_id

required

string

ID of the webhook

Request Body schema: application/json
required

enabled_events required	Array of strings Items Enum: "invoice.global_invoice_created" "invoice.status_updated" "invoice.cancellation_status_updated" "receipt.self_invoice_complete" "receipt.status_updated" "receipt.cancellation_status_updated" Events enabled for the webhook to listen to.
status	string Enum: "disabled" "enabled" Status of the webhook.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"status": "disabled",
"enabled_events": ["receipt.self_invoice_complete"
]
}

Response samples

200
400
401
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"organization": "string",
"enabled_events": ["receipt.cancellation_status"
],
"url": "http://my-website.com/my/webhook",
"status": "enabled"
}

Delete Webhook

Deletes the webhook subscription from the organization.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

webhook_id

required

string

ID of the webhook

Responses

Request samples

cURL
Node.js
C#
PHP

curl https://www.facturapi.io/v2/webhooks/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,
"organization": "string",
"enabled_events": ["receipt.cancellation_status"
],
"url": "http://my-website.com/my/webhook",
"status": "enabled"
}

Validate Webhook Signature

Validate the signature of an event object received through a Webhook. Use this operation to verify the authenticity and integrity of the event received, comparing the received signature with the one generated by Facturapi.

Authorizations:

SecretLiveKeySecretTestKey

Request Body schema: application/json

secret	string Secret key of the webhook, found in the webhook settings or upon creation.
payload	object Event object received through a webhook.
signature	string Signature from the header "Facturapi-Signature".

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"secret": "string",
"payload": { },
"signature": "string"
}

Response samples

200
400
401
404
500

Content type

application/json

{"id": "string",
"created_at": "2019-08-24T14:15:22Z",
"livemode": true,
"organization": "string",
"type": "invoice.status_updated",
"data": {"type": "invoice",
"object": {"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": [ ]
}
],
"payment_related_ids": [ ],
"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"
}
}
}
}

Customer object

id required	string ID of the object
created_at required	string <date-time> Creation date and time
livemode required	boolean Indicates if the object was created in Live mode (true) or Test mode (false).
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.
default_invoice_use	string Default CFDI use for the customer.
	object Fiscal address.

{"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,
"default_invoice_use": "G01",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
}

Product object

id required	string ID of the object
created_at required	string <date-time> Creation date and time
livemode required	boolean Indicates if the object was created in Live mode (true) or Test mode (false).
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" "06" "07" "08" 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. `06`: Subect to tax IVA, but not IVA transferred. `07`: Not Subject to tax IVA, but required IEPS breakdown. `08`: Not Subject to tax IVA, and not required IEPS breakdown.
	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.

{"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"
}

Invoice object

id required	string ID of the object
created_at required	string <date-time> Creation date and time
livemode required	boolean Indicates if the object was created in Live mode (true) or Test mode (false).
status	string Enum: "pending" "valid" "canceled" "draft" Current status of the invoice.
cancellation_status	string Enum: "none" "pending" "accepted" "rejected" "expired" Current status of the cancellation request, if it has been made. You can read more in the Cancel Invoice section.
verification_url	string <uri> URL to verify the status of the CFDI on the SAT portal. This link is the same as the one that appears in the QR code on the invoice PDF.
date	string <date-time> Default: "now" Date of issuance of the invoice in ISO8601 format (UTC String).
	object Address where the invoice was issued.
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.
	object (CuustomerInfo) Object with partial information of the customer receiving the document. To obtain the complete `Customer` object, you must consult it with the Retrieve Customer method.
total	number Total amount invoiced.
uuid	string <uuid> Fiscal folio of the invoice, assigned by the SAT.
folio_number	integer Autoincremental folio number for internal control and without fiscal relevance.
series	string Series. Alphanumeric characters designated by the company for internal control and without fiscal relevance. In the PDF, it is printed next to the folio number.
external_id	string Identifier that you can use to relate this invoice to your records to later search by this number.
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.
payment_form	string Payment form code according to the Payment Form catalog.
is_ready_to_stamp	boolean This field is automatically assigned by Facturapi. It indicates if an invoice with status `draft` is complete and ready to be stamped. If the value is `true`, you can try to stamp the invoice with the Stamp Invoice method. If the value is `false`, you must use the Update Invoice method to complete the missing fields. In an invoice with a status other than `draft`, this field will always be `false`.
	Array of objects (LineItem) Concepts included in the document.
	Array of objects (RelatedDocument) Documents related to the invoice.
payment_related_ids	Array of strings Default: [] If this invoice has a payment method PPD and type I, this field will have the related payment id of this invoice.
currency	string Currency code, according to the standard ISO 4217.
exchange	number >= 0 Exchange rate for the currency used. It represents the number of Mexican pesos (MXN) equivalent to one unit of the currency indicated in the `currency` attribute.
	Array of objects (Complement) Default: [] Complements to include in the invoice.
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`.
	object (Stamp) Information about the digital stamp added by the PAC.

{"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": [ ]
}
],
"payment_related_ids": [ ],
"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"
}
}

Receipt object

id required	string ID of the object
created_at required	string <date-time> Creation date and time
livemode required	boolean Indicates if the object was created in Live mode (true) or Test mode (false).
date	string <date-time> Date of issuance of the receipt in ISO8601 format (UTC String).
expires_at	string <date-time> Expiration date in ISO8601 format (UTC String). It is the deadline for the customer to invoice their receipt on the autofactura portal. It is calculated automatically from the organization's receipt settings.
status	string Enum: "open" "canceled" "invoiced_to_customer" "invoiced_globally" Estado actual del recibo.
self_invoice_url	string <url> URL to the self-invoice portal. It includes the `key` of the receipt. You can use it to generate a button or a QR code for your customers to invoice their receipts.
total	number Total amount of the operation
invoice	string ID of the associated invoice, if invoiced.
key	string Auto-generated. Short alphanumeric unique identifier, useful for accessing the self-invoice from your microsite on factura.space.
	Array of objects (LineItem) Sale items included in the receipt.
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 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.
payment_form	string Payment form code according to the Payment Form catalog.
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.

{"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"
}

Retention object

id required	string ID of the object
created_at required	string <date-time> Creation date and time
livemode required	boolean Indicates if the object was created in Live mode (true) or Test mode (false).
status	string Enum: "valid" "canceled" Current status of the document.
verification_url	string <uri> URL to verify the status of the retention on the SAT portal. This link is the same as the one that appears in the QR code on the retention PDF.
type	string Value: "Retención" Type of document.
uuid	string <uuid> Fiscal folio of the retention, assigned by the SAT.
	object (Stamp) Information about the digital stamp added by the PAC.
	object (CuustomerInfo) Object with partial information of the customer receiving the document. To obtain the complete `Customer` object, you must consult it with the Retrieve Customer method.
cve_retenc	string Key of the retention or payment information according to the SAT catalog.
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.
	object Information about the retention period.
	object Information about the total of retentions made in the corresponding period.
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 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.
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.
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`.

{"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"
}
]
}

Organization object

id	string ID of the organization, assigned by Facturapi.
created_at	string <date-time> Date and time of creation of the organization.
is_production_ready	boolean Indicates if the organization has the necessary information to issue invoices in the Live environment.
	Array of objects List of steps that need to be completed for this organization to issue valid invoices in the Live environment.
	object Fiscal information of the organization.
	object Organization customization settings, which will be used to reflect the branding and PDF preferences of the organization. This data can be updated at any time.
	object Useful information about the organization's Digital Stamp Certificate (CSD), which will be used to sign the invoices.

{"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"
}
}

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