Facturapi (2.0)
Download OpenAPI specification:Download
En esta página enlistamos todos los métodos disponibles en la API de Facturapi, así como la referencia completa de los parámetros que acepta cada uno. Para ver las propiedades anidadas de un objeto o arreglo de objetos, puedes hacer clic sobre el nombre del campo y expandirlo.
La API de Facturapi está diseñada con el estándar REST en mente. Los endpoints de la API están agrupados por recursos, tienen URLs predecibles, las respuestas tienen formato JSON y usamos códigos HTTP de respuesta, autenticación y verbos estándar.
Durante el desarrollo, puedes usar la API de Facturapi en ambiente Test y las facturas que emitas no se enviarán al SAT ni tendrán validez fiscal.
La llave secreta que utilices para autenticarte determinará tanto el ambiente en el que se creará la factura (Test o Live), así como la organización a utilizar como emisor de tu factura, o bien como dueña del recurso que solicites crear.
Crear cliente
Registra un nuevo cliente en Facturapi.
Esta llamada valida que los datos fiscales coincidan con los registros del SAT para ese RFC, de lo contrario, la llamada devolverá un error indicando el problema.
Una vez creado el cliente y obtenido un objeto de respuesta, te recomendamos guardar el ID en tu base de datos junto a la información de tu cliente. Posteriormente, puedes llamar al encpoint de Crear Factura pasando el ID del cliente en lugar de repetir la información.
Por último, ten en cuenta que los clientes que crees en ambiente Test no se comparten con el ambiente Live.
Authorizations:
Request Body schema: application/jsonrequired
legal_name required | string Nombre Fiscal o Razón Social del cliente. sin el régimen societario (ej.: S.A. de C.V.). |
tax_id required | string En clientes de México contiene el RFC del cliente. Para extranjeros es opcional y representa el número de registro de identificacón tributaria, es decir, el equivalente al RFC en el país del cliente. |
tax_system required | string = 3 characters Requerido para clientes nacionales. Clave del régimen fiscal del cliente, del catálogo de Regímenes Fiscales. |
required | object Domicilio fiscal. |
string <email> Dirección de correo electrónico al cual enviar las facturas generadas. | |
phone | string Teléfono del cliente. |
default_invoice_use | string Uso de CFDI por defecto. |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "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
- 201
- 400
- 401
- 404
- 500
{- "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"
}
}
Listar clientes
Regresa una lista paginada de todos los clientes de una organización o realiza una búsqueda de acuerdo a parámetros
Authorizations:
query Parameters
q | string Consulta. Texto a buscar en |
object (DateRange) Objeto con rango de fechas solicitado. | |
page | integer >= 1 Página de resultados a regresar, empezando desde la página 1. |
limit | integer [ 1 .. 100 ] Default: 50 Número del 1 al 100 que representa la cantidad máxima de resultados a regresar con motivos de paginación. |
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
{- "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"
}
}
]
}
Obtener cliente por ID
Regresa el objeto 'Customer' relacionado al id
especificado.
Authorizations:
path Parameters
customer_id required | string ID del objeto a obtener |
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
{- "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"
}
}
Editar cliente
Actualiza la información de un cliente existente, asignando los valores de los parámetros enviados. Los parámetros que no se envíen en la petición no se modificarán.
Authorizations:
path Parameters
customer_id required | string ID del objeto a editar |
Request Body schema: application/jsonrequired
legal_name | string Nombre Fiscal o Razón Social del cliente. sin el régimen societario (ej.: S.A. de C.V.). |
tax_id | string En clientes de México contiene el RFC del cliente. Para extranjeros es opcional y representa el número de registro de identificacón tributaria, es decir, el equivalente al RFC en el país del cliente. |
tax_system | string = 3 characters Requerido para clientes nacionales. Clave del régimen fiscal del cliente, del catálogo de Regímenes Fiscales. |
string <email> Dirección de correo electrónico al cual enviar las facturas generadas. | |
phone | string Teléfono del cliente. |
default_invoice_use | string Uso de CFDI por defecto. |
object Domicilio fiscal. |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "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
{- "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"
}
}
Eliminar cliente
Elimina el cliente de tu organización. Las facturas asociadas al cliente no se eliminarán.
Authorizations:
path Parameters
customer_id required | string ID del objeto a eliminar |
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
{- "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"
}
}
Validar información fiscal
Valida que la información fiscal del cliente coincida con los registros del SAT.
Su función principal es validar que los datos del cliente registraado siguen cumpliendo la validación del SAT.
:::tip Las operaciones de crear cliente, editar cliente y crear factura ya realizan una validación de la información del cliente, por lo que no es necesario llamar a este endpoint antes de realizar dichas operaciones. :::
Authorizations:
path Parameters
customer_id required | string ID del objeto |
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
{- "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."
}
]
}
Crear producto
Registra un nuevo producto o servicio en tu catálogo de Facturapi.
Puedes usar el ID del producto para crear facturas sin tener que enviar todos los datos del producto cada vez.
Te en cuenta que los productos que crees en ambiente Test no se comparten con el ambiente Live.
Authorizations:
Request Body schema: application/jsonrequired
description required | string Descripción del bien o servicio como aparecerá en la factura. |
product_key required | string Clave de producto/servicio, del catálogo del SAT. Nosotros te proporcionamos una manera más conveniente de encontrarlo utilizando nuestra herramienta de búsqueda de claves. |
price required | number Precio por unidad del bien o servicio. Este valor representará el precio con IVA incluído o sin él, dependiendo del valor de |
tax_included | boolean or null Default: true
|
taxability | string Default: "'01' si el array `taxes` está vacío; '02' si el array `taxes` tiene por lo menos un elemento.\n" Enum: "01" "02" "03" "04" "05" "06" "07" "08" Código que representa si el bien o servicio es objeto de impuesto o no. Este atributo corresponde al campo "ObjetoImp" en el CFDI.
|
Array of objects or null (Tax) Default: "IVA trasladado 16%" Lista de impuestos que deberán aplicarse a este producto. Si el parámetro se omite o es nulo, se guardará con un elemento que representa el IVA trasladado del 16%, que es el impuesto más común. En caso de mandar explícitamente un arreglo vacío, se entiende que el producto está exento de impuestos. | |
Array of objects (LocalTax) Default: [] Arreglo de impuestos locales (estatales o municipales), en caso de haberlos. | |
unit_key | string or null Default: "H87" Clave de unidad de medida, del catálogo del SAT. El valor por default |
unit_name | string or null Default: "Elemento" Palabra que representa la unidad de medida de tu producto. Debe estar relacionada con la clave de unidad |
sku | string or null Identificador de uso interno designado por la empresa. Puede tener cualquier valor. |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "description": "Ukelele",
- "product_key": 60131324,
- "price": 345.6,
- "tax_included": true,
- "taxability": "01",
- "taxes": {
- "0": {
- "type": "IVA",
- "rate": 0.16
}
}, - "local_taxes": { },
- "unit_key": "H87",
- "unit_name": "Elemento",
- "sku": "string"
}
Response samples
- 200
- 400
- 401
- 404
- 500
{- "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": {
- "0": {
- "type": "IVA",
- "rate": 0.16
}
}, - "local_taxes": { },
- "unit_key": "H87",
- "unit_name": "Elemento",
- "sku": "string"
}
Listar productos
Regresa una lista paginada de todos los productos de una organización o realiza una búsqueda de acuerdo a parámetros
Authorizations:
query Parameters
q | string Consulta. Texto a buscar en la descripción del producto o SKU. |
sku | string SKU del producto. |
page | integer >= 1 Página de resultados a regresar, empezando desde la página 1. |
limit | integer [ 1 .. 100 ] Default: 50 Número del 1 al 100 que representa la cantidad máxima de resultados a regresar con motivos de paginación. |
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
{- "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": {
- "0": {
- "type": "IVA",
- "rate": 0.16
}
}, - "local_taxes": { },
- "unit_key": "H87",
- "unit_name": "Elemento",
- "sku": "string"
}
]
}
Obtener producto por ID
Regresa el objeto Product
relacionado al id
especificado.
Authorizations:
path Parameters
product_id required | string ID del objeto a obtener |
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
{- "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": {
- "0": {
- "type": "IVA",
- "rate": 0.16
}
}, - "local_taxes": { },
- "unit_key": "H87",
- "unit_name": "Elemento",
- "sku": "string"
}
Editar producto
Actualiza la información de un producto existente, asignando los valores de los parámetros enviados. Los parámetros que no se envíen en la petición no se modificarán.
Authorizations:
path Parameters
product_id required | string ID del objeto a editar |
Request Body schema: application/jsonrequired
description required | string Descripción del bien o servicio como aparecerá en la factura. |
product_key required | string Clave de producto/servicio, del catálogo del SAT. Nosotros te proporcionamos una manera más conveniente de encontrarlo utilizando nuestra herramienta de búsqueda de claves. |
price required | number Precio por unidad del bien o servicio. Este valor representará el precio con IVA incluído o sin él, dependiendo del valor de |
tax_included | boolean or null Default: true
|
taxability | string Default: "'01' si el array `taxes` está vacío; '02' si el array `taxes` tiene por lo menos un elemento.\n" Enum: "01" "02" "03" "04" "05" "06" "07" "08" Código que representa si el bien o servicio es objeto de impuesto o no. Este atributo corresponde al campo "ObjetoImp" en el CFDI.
|
Array of objects or null (Tax) Default: "IVA trasladado 16%" Lista de impuestos que deberán aplicarse a este producto. Si el parámetro se omite o es nulo, se guardará con un elemento que representa el IVA trasladado del 16%, que es el impuesto más común. En caso de mandar explícitamente un arreglo vacío, se entiende que el producto está exento de impuestos. | |
Array of objects (LocalTax) Default: [] Arreglo de impuestos locales (estatales o municipales), en caso de haberlos. | |
unit_key | string or null Default: "H87" Clave de unidad de medida, del catálogo del SAT. El valor por default |
unit_name | string or null Default: "Elemento" Palabra que representa la unidad de medida de tu producto. Debe estar relacionada con la clave de unidad |
sku | string or null Identificador de uso interno designado por la empresa. Puede tener cualquier valor. |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "description": "Ukelele",
- "product_key": 60131324,
- "price": 345.6,
- "tax_included": true,
- "taxability": "01",
- "taxes": {
- "0": {
- "type": "IVA",
- "rate": 0.16
}
}, - "local_taxes": { },
- "unit_key": "H87",
- "unit_name": "Elemento",
- "sku": "string"
}
Response samples
- 200
- 400
- 401
- 500
{- "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": {
- "0": {
- "type": "IVA",
- "rate": 0.16
}
}, - "local_taxes": { },
- "unit_key": "H87",
- "unit_name": "Elemento",
- "sku": "string"
}
Eliminar producto
Elimina el producto de tu organización. Las facturas asociadas al producto no se eliminarán.
Authorizations:
path Parameters
product_id required | string ID del objeto a eliminar |
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
{- "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": {
- "0": {
- "type": "IVA",
- "rate": 0.16
}
}, - "local_taxes": { },
- "unit_key": "H87",
- "unit_name": "Elemento",
- "sku": "string"
}
Crear factura (CFDI 4.0)
Crea una nueva Factura. Si la factura es creada en ambiente Live, ésta será timbrada y enviada al SAT.
Authorizations:
query Parameters
async | boolean Útil para facturas de gran tamaño. Si se envía |
Request Body schema: application/jsonrequired
required | Customer (object) or customer_id (string) Cliente receptor de la factura. |
required | Array of objects (LineItem) <= 5000 items Conceptos a incluir en la factura. El número máximo de elementos que puedes incluir en una factura es de 5,000. Si necesitas emitir una factura con más de 5,000 conceptos, puedes dividir la transacción en varias facturas. |
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" Código de Uso CFDI según el catálogo del SAT. Puedes ver los códigos en esta tabla, o utilizar las constantes incluídas en nuestras librerías. Para factura global debe ingresarse la clave |
type | string Default: "I" Value: "I" Tipo de comprobante. El valor default es |
payment_method | string Default: "PUE" Enum: "PUE" "PPD" Código del método de pago según el catálogo del SAT.
|
currency | |
exchange | number Default: 1 Tipo de cambio conforme a la moneda usada. Representa el número de pesos
mexicanos (MXN) que equivalen a una unidad de la divisa señalada en el atributo |
conditions | string or null [ 1 .. 1000 ] characters Condiciones de pago |
Array of objects (RelatedDocumentInput) Default: [] Documentos relacionados con la factura. | |
object or null Objeto requerido al crear una factura global. | |
export | string Default: "01" Enum: "01" "02" "03" "04" Indica si el comprobante ampara una operación de exportación.
|
Array of objects (CustomComplement) Default: [] Complementos a incluir en la factura. Puedes incluir cualquier complemento en la
factura si tú mismo construyes el nodo XML del complemento y usas el tipo | |
status | string Default: "pending" Estado inicial de la factura. Si se envía |
date | string <date-time> Default: "now" Fecha de expedición del comprobante en formato ISO8601 (UTC String). No puede ser anterior a 72 horas en el pasado, ni posterior al presente. |
object Puedes usar este parámetro para especificar el domicilio de expedición de la factura. Este campo es opcional y si no se envía, la factura se expedirá con el domicilio de la organización. | |
external_id | string or null Identificador opcional que puedes usar para relacionar esta factura con tus registros y poder hacer búsquedas usando este identificador. Facturapi no valida que este campo sea único. |
idempotency_key | string or null Identificador único que puedes usar para evitar duplicados al reintentar una petición. Puede ser cualquier cadena de texto, mientras sea única para cada documento. Si se deja en blanco, no se tomará en cuenta. |
folio_number | integer Default: "autoincremental" Número de folio asignado por la empresa para control interno. Si se omite, se asignará el valor autoincremental de la organización. |
series | string or null <= 25 characters Serie. Caracteres designados por la empresa para control interno y sin validez fiscal. |
pdf_custom_section | string or null <xml> En caso de que necesites incluir más información en el PDF, este campo te permite enviar código HTML con tu propio contenido. Por seguridad, el código que puedes enviar está limitado a las siguientes etiquetas: |
addenda | string or null <xml> Código XML con la Addenda que se necesite agregar a la factura. |
Array of objects (Namespace) Default: [] Si incluiste el parámetro | |
object Configura qué campos opcionales se queiren mostrar en el PDF. El SAT no obliga a mostrar estos campos, pero pueden activarse según la preferencia del cliente para la factura en curso. Utiliza este campo para peticiones de generación de facturas en las cuales necesites utilizar una configuración distinta al campo pdf_extra de la organización. |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{ }
Response samples
- 200
- 400
- 401
- 404
- 500
{- "id": "590ce6c56d04f840aa8438af",
- "created_at": "2017-05-05T20:55:33.468Z",
- "livemode": false,
- "status": "pending",
- "cancellation_status": "none",
- "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": {
- "0": {
- "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": { }
}
], - "received_payment_ids": { },
- "target_invoice_ids": { },
- "currency": "MXN",
- "exchange": 1,
- "complements": { },
- "pdf_custom_section": "string",
- "addenda": "string",
- "namespaces": [
- {
- "prefix": "iedu",
}
], - "stamp": {
- "signature": "string",
- "date": "2019-08-24T14:15:22Z",
- "sat_cert_number": "string",
- "sat_signature": "string"
}
}
Listar facturas
Regresa una lista paginada de todas las facturas de una organización o realiza una búsqueda de acuerdo a parámetros
Authorizations:
query Parameters
q | string Consulta. Texto a buscar en la factura. La búsqueda se realizará por coincidencias parciales en los campos:
Y por coincidencias exactas en los campos:
|
customer | string Identificador del cliente. Útil para obtener las facturas emitidas a un sólo cliente. |
type | string Enum: "I" "E" "P" "N" "T" Tipo de factura. Búsqueda por tipo de factura con las claves exactas. |
payment_method | string Enum: "PUE" "PPD" Método de pago. Búsqueda exacta por método de pago. |
object (DateRange) Objeto con rango de fechas solicitado. | |
page | integer >= 1 Página de resultados a regresar, empezando desde la página 1. |
limit | integer [ 1 .. 100 ] Default: 50 Número del 1 al 100 que representa la cantidad máxima de resultados a regresar con motivos de paginación. |
Responses
Request samples
- cURL
- Node.js
- C#
- PHP
# Todas las facturas de la organización curl "https://www.facturapi.io/v2/invoices" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" # Todas las facturas emitidas para cierto cliente curl "https://www.facturapi.io/v2/invoices" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "customer=58e93bd8e86eb318b0197456" # Página 3 de los resultados de búsqueda de texto libre # de facturas emitidas por cierto cliente entre 2017 y 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
{- "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",
- "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": {
- "0": {
- "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": { }
}
], - "received_payment_ids": { },
- "target_invoice_ids": { },
- "currency": "MXN",
- "exchange": 1,
- "complements": { },
- "pdf_custom_section": "string",
- "addenda": "string",
- "namespaces": [
- {
- "prefix": "iedu",
}
], - "stamp": {
- "signature": "string",
- "date": "2019-08-24T14:15:22Z",
- "sat_cert_number": "string",
- "sat_signature": "string"
}
}
]
}
Obtener factura por ID
Regresa el objeto 'Invoice' relacionado al id
especificado.
Authorizations:
path Parameters
invoice_id required | string ID del objeto a obtener |
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
{- "id": "590ce6c56d04f840aa8438af",
- "created_at": "2017-05-05T20:55:33.468Z",
- "livemode": false,
- "status": "valid",
- "cancellation_status": "none",
- "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": {
- "0": {
- "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": { }
}
], - "received_payment_ids": { },
- "target_invoice_ids": { },
- "currency": "MXN",
- "exchange": 1,
- "complements": { },
- "pdf_custom_section": "string",
- "addenda": "string",
- "namespaces": [
- {
- "prefix": "iedu",
}
], - "stamp": {
- "signature": "string",
- "date": "2019-08-24T14:15:22Z",
- "sat_cert_number": "string",
- "sat_signature": "string"
}
}
Editar borrador de factura
Actualiza la información de una factura con status draft
, asignando
los valores de los parámetros enviados. Los parámetros que no se envíen
en la petición no se modificarán.
En el objeto invoice
de respuesta, Facturapi asignará automáticamente
el campo is_ready_to_stamp
con el valor true
si la factura pasa la
validación mínima requerida para ser timbrada; de lo contrario, el campo
is_ready_to_stamp
será false
.
Authorizations:
path Parameters
invoice_id required | string ID del objeto a editar |
Request Body schema: application/jsonrequired
type | string Enum: "I" "E" "P" "N" "T" Tipo de comprobante. Puede tener los valores |
Array of objects (LineItem) <= 5000 items Conceptos a incluir en la factura. El número máximo de elementos que puedes incluir en una factura es de 5,000. Si necesitas emitir una factura con más de 5,000 conceptos, puedes dividir la transacción en varias facturas. | |
payment_form | string = 2 characters Código que representa la forma de pago, de acuerdo al catálogo del SAT. |
payment_method | string Enum: "PUE" "PPD" Código del método de pago según el catálogo del SAT.
|
use | string Código de Uso CFDI según el catálogo del SAT. Puedes ver los códigos en esta tabla, o utilizar las constantes incluídas en nuestras librerías. Para factura global debe ingresarse la clave |
currency | string Código de la moneda, acorde al estándar ISO 4217. |
exchange | number Tipo de cambio conforme a la moneda usada. Representa el número de pesos
mexicanos (MXN) que equivalen a una unidad de la divisa señalada en el atributo |
conditions | string or null [ 1 .. 1000 ] characters Condiciones de pago |
Array of objects (RelatedDocumentInput) Documentos relacionados con la factura. | |
object or null Objeto requerido al crear una factura global. | |
export | string Enum: "01" "02" "03" "04" Indica si el comprobante ampara una operación de exportación.
|
Array of objects (CustomComplement) Complementos a incluir en la factura. Puedes incluir cualquier complemento en la
factura si tú mismo construyes el nodo XML del complemento y usas el tipo | |
Customer (object) or customer_id (string) Cliente receptor de la factura. | |
status | string Value: "draft" Estado inicial de la factura. Sólo es posible editar una factura con status |
date | string <date-time> Fecha de expedición del comprobante en formato ISO8601 (UTC String). No puede ser anterior a 72 horas en el pasado, ni posterior al presente. |
object Puedes usar este parámetro para especificar el domicilio de expedición de la factura. Este campo es opcional y si no se envía, la factura se expedirá con el domicilio de la organización. | |
external_id | string or null Identificador opcional que puedes usar para relacionar esta factura con tus registros y poder hacer búsquedas usando este identificador. Facturapi no valida que este campo sea único. |
idempotency_key | string or null Identificador único que puedes usar para evitar duplicados al reintentar una petición. Puede ser cualquier cadena de texto, mientras sea única para cada documento. Si se deja en blanco, no se tomará en cuenta. |
folio_number | integer Número de folio asignado por la empresa para control interno. Si se omite, se asignará el valor autoincremental de la organización. |
series | string or null <= 25 characters Serie. Caracteres designados por la empresa para control interno y sin validez fiscal. |
pdf_custom_section | string or null <xml> En caso de que necesites incluir más información en el PDF, este campo te permite enviar código HTML con tu propio contenido. Por seguridad, el código que puedes enviar está limitado a las siguientes etiquetas: |
addenda | string or null <xml> Código XML con la Addenda que se necesite agregar a la factura. |
Array of objects (Namespace) Si incluiste el parámetro | |
object Configura qué campos opcionales se queiren mostrar en el PDF. El SAT no obliga a mostrar estos campos, pero pueden activarse según la preferencia del cliente para la factura en curso. Utiliza este campo para peticiones de generación de facturas en las cuales necesites utilizar una configuración distinta al campo pdf_extra de la organización. |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "type": "I",
- "items": [
- {
- "quantity": 1,
- "discount": 0,
- "product": {
- "description": "Ukelele",
- "product_key": 60131324,
- "price": 345.6,
- "tax_included": true,
- "taxability": "01",
- "taxes": {
- "0": {
- "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": "string",
- "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",
}
], - "pdf_options": {
- "codes": true,
- "product_key": true,
- "round_unit_price": false,
- "tax_breakdown": true,
- "ieps_breakdown": true
}
}
Response samples
- 200
- 400
- 401
- 500
{- "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": {
- "0": {
- "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",
}
], - "is_ready_to_stamp": true,
- "stamp": {
- "signature": "string",
- "date": "2019-08-24T14:15:22Z",
- "sat_cert_number": "string",
- "sat_signature": "string"
}
}
Cancelar factura
Realiza una solicitud de cancelación de factura ante el SAT, soportando el esquema de cancelación 2022.
Al usar este método pueden ocurrir 3 posibles resultados:
- Que la llamada regrese un error con la explicación de por qué no se pudo cancelar.
- Que la llamada sea satisfactoria y regrese un objeto
invoice
con la propiedadstatus: "canceled"
. - Que la llamada sea satisfactoria, pero que la cancelación requiera de confirmación de parte de tu cliente, en cuyo caso se obtendrá como respuesta el objeto
invoice
con las propiedadesstatus: "valid"
ycancellation_status: "pending"
.
En el tercer escenario, el valor de cancellation_status
será actualizado automáticamente por Facturapi cuando tu cliente acepte, rechace o deje expirar la solicitud, de tal manera que al consultar una factura (usando Obtener Factura), la propiedad cancellation_status
reflejará el estado más reciente de la soliitud.
Consulta los valores posibles de cancellation_status
más abajo.
Después de la cancelación la factura ya no tendrá validez, el objeto cambiará su status
a "canceled"
y seguirá estando disponible para futuras consultas.
Si el status de la factura es draft
, este método la eliminará de la base de datos.
Si el status de la factura es canceled
, este método regresará un error.
Authorizations:
path Parameters
invoice_id required | string ID de la factura a cancelar |
query Parameters
motive required | string Enum: "01" "02" "03" "04" Clave que representa el motivo de la cancelación de la factura.
|
substitution | string ID de la factura que sustituye a la factura que se está cancelando. Puedes usar el ID de Facturapi o el folio fiscal (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
{- "id": "590ce6c56d04f840aa8438af",
- "created_at": "2017-05-05T20:55:33.468Z",
- "livemode": false,
- "status": "valid",
- "cancellation_status": "none",
- "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": {
- "0": {
- "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": { }
}
], - "received_payment_ids": { },
- "target_invoice_ids": { },
- "currency": "MXN",
- "exchange": 1,
- "complements": { },
- "pdf_custom_section": "string",
- "addenda": "string",
- "namespaces": [
- {
- "prefix": "iedu",
}
], - "stamp": {
- "signature": "string",
- "date": "2019-08-24T14:15:22Z",
- "sat_cert_number": "string",
- "sat_signature": "string"
}
}
Copiar a borrador
Crea una copia en borrador de la factura especificada.
Authorizations:
path Parameters
invoice_id required | string ID de la factura a copiar |
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
{- "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": {
- "0": {
- "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",
}
], - "is_ready_to_stamp": true,
- "stamp": {
- "signature": "string",
- "date": "2019-08-24T14:15:22Z",
- "sat_cert_number": "string",
- "sat_signature": "string"
}
}
Timbrar borrador de factura
Timbra una factura con status draft
y la envía al SAT para su validación.
Al usar este método, el valor del campo is_ready_to_stamp
(asignado por Facturapi)
deberá ser true
. De otra forma, la llamada regresará un error.
Este método no permite editar la factura, sólo timbrarla. Si necesitas editar información en la factura antes de timbrarla, usa el método Editar Borrador de Factura.
Authorizations:
path Parameters
invoice_id required | string ID del objeto a timbrar |
query Parameters
async | boolean Útil para facturas de gran tamaño. Si se envía |
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
{- "id": "590ce6c56d04f840aa8438af",
- "created_at": "2017-05-05T20:55:33.468Z",
- "livemode": false,
- "status": "valid",
- "cancellation_status": "none",
- "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": {
- "0": {
- "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": { }
}
], - "received_payment_ids": { },
- "target_invoice_ids": { },
- "currency": "MXN",
- "exchange": 1,
- "complements": { },
- "pdf_custom_section": "string",
- "addenda": "string",
- "namespaces": [
- {
- "prefix": "iedu",
}
], - "stamp": {
- "signature": "string",
- "date": "2019-08-24T14:15:22Z",
- "sat_cert_number": "string",
- "sat_signature": "string"
}
}
Descargar acuse de cancelación
Descarga acuse de recibo de cancelación de una factura en un archivo xml o pdf.
Authorizations:
path Parameters
invoice_id required | string ID del objeto a obtener |
format required | string Enum: "xml" "pdf" Formato del archivo de descarga |
Responses
Request samples
- cURL
- Node.js
- C#
- PHP
# Acuse de factura cancelada curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/cancellation_receipt/{format} \ -H "Authorization: Bearer sk_test_API_KEY" \ -X GET
Response samples
- 400
- 401
- 500
{- "message": "string"
}
Descargar factura
Descarga tu Factura en PDF, XML o ambos en un archivo comprimido ZIP.
Authorizations:
path Parameters
invoice_id required | string ID del objeto a descargar |
format required | string Enum: "xml" "pdf" "zip" Formato del archivo de descarga |
Responses
Request samples
- cURL
- Node.js
- C#
- PHP
## Descargar PDF y XML comprimidos en archivo ZIP curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/zip \ -H "Authorization: Bearer sk_test_API_KEY" ## Descargar sólo el PDF curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/pdf \ -H "Authorization: Bearer sk_test_API_KEY" ## Descargar sólo el XML curl https://www.facturapi.io/v2/invoices/58e93bd8e86eb318b019743d/xml \ -H "Authorization: Bearer sk_test_API_KEY"
Response samples
- 400
- 401
- 500
{- "message": "string"
}
Enviar factura por correo electrónico
Envía un correo electrónico a la dirección de tu cliente, con los archivos XML y PDF adjuntos al mensaje.
Authorizations:
path Parameters
invoice_id required | string ID del objeto a obtener |
Request Body schema: application/jsonoptional
string or Array of strings Dirección de correo electrónico a enviar la factura. Si no se envía este parámetro, la factura será enviada al correo que el cliente tenga registrado. | |
One of string <email> Dirección de correo eletrónico |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "email": "otro@correo.com"
}
Response samples
- 200
- 400
- 401
- 500
{- "ok": true
}
Actualizar status de factura
Consulta el status de una factura timbrada en el SAT y actualiza el objeto invoice con La información más reciente.
Authorizations:
path Parameters
invoice_id required | string ID del objeto invoice a actualizar |
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
{- "id": "590ce6c56d04f840aa8438af",
- "created_at": "2017-05-05T20:55:33.468Z",
- "livemode": false,
- "status": "valid",
- "cancellation_status": "none",
- "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": {
- "0": {
- "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": { }
}
], - "received_payment_ids": { },
- "target_invoice_ids": { },
- "currency": "MXN",
- "exchange": 1,
- "complements": { },
- "pdf_custom_section": "string",
- "addenda": "string",
- "namespaces": [
- {
- "prefix": "iedu",
}
], - "stamp": {
- "signature": "string",
- "date": "2019-08-24T14:15:22Z",
- "sat_cert_number": "string",
- "sat_signature": "string"
}
}
Crear recibo
Crea un nuevo Recibo, el cual funge como nota de venta.
Todos los recibos generan una URL de autofactura que cliente puede visitar para llenar sus datos fiscales en un micrositio con el branding de la organización.
Authorizations:
Request Body schema: application/jsonrequired
required | Array of objects (LineItem) <= 5000 items Conceptos a incluir en el recibo. El número máximo de elementos que puedes incluir en un recxibo es de 5,000. Si necesitas emitir una recibo con más de 5,000 conceptos, prueba dividir la transacción en varios recibos. |
payment_form required | string Código que representa la forma de pago, según el catálogo del SAT. |
date | string <date-time> Fecha de emisión del recibo. Por defecto se utiliza la fecha actual. |
folio_number | integer Autoincremental. Número de folio del recibo para control interno y sin validez fiscal. |
currency | string Código de la moneda, acorde al estándar ISO 4217. |
exchange | number >= 0 Tipo de cambio conforme a la moneda usada. Representa el número de pesos mexicanos que equivalen a una unidad de la divisa señalada en el atributo |
branch | string Nombre de la sucursal donde se expidió el recibo. |
external_id | string or null Identificador opcional que puedes usar para relacionar este recibo con tus registros y poder hacer búsquedas usando este identificador. Facturapi no valida que este campo sea único. |
idempotency_key | string or null Identificador único que puedes usar para evitar duplicados al reintentar una petición. Puede ser cualquier cadena de texto, mientras sea única para cada documento. Si se deja en blanco, no se tomará en cuenta. |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "items": [
- {
- "quantity": 1,
- "discount": 0,
- "product": {
- "description": "Ukelele",
- "product_key": 60131324,
- "price": 345.6,
- "tax_included": true,
- "taxability": "01",
- "taxes": {
- "0": {
- "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
{- "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",
- "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": {
- "0": {
- "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"
}
Listar recibos
Regresa una lista paginada de todos los recibos de una organización o realiza una búsqueda de acuerdo a parámetros
Authorizations:
query Parameters
q | string Consulta. Texto a buscar en la descripción de los conceptos del recibo o el SKU. |
payment_form | string = 2 characters Example: payment_form=02 Código que representa la forma de pago, de acuerdo al catálogo del SAT. Si se incluye, los recibos se agruparán y se listarán de acuerdo a la forma de pago. |
object (DateRange) Objeto con rango de fechas solicitado. | |
page | integer >= 1 Página de resultados a regresar, empezando desde la página 1. |
limit | integer [ 1 .. 100 ] Default: 50 Número del 1 al 100 que representa la cantidad máxima de resultados a regresar con motivos de paginación. |
Responses
Request samples
- cURL
- Node.js
- C#
- PHP
# Todos los recibos de la organización curl "https://www.facturapi.io/v2/receipts" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" # Página 3 de los resultados de búsqueda de texto libre # de recibos creados entre 2017 y 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
{- "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",
- "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": {
- "0": {
- "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"
}
]
}
Obtener recibo por ID
Regresa el objeto 'Receipt' relacionado al id
especificado.
Authorizations:
path Parameters
receipt_id required | string ID del objeto a obtener |
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
{- "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",
- "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": {
- "0": {
- "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"
}
Cancelar recibo
Marca un recibo como cancelado, cambiando su propiedad status
a "canceled"
.
Una vez cancelado, el recibo no podrá ser facturado.
Authorizations:
path Parameters
receipt_id required | string ID del recibo a cancelar |
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
{- "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",
- "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": {
- "0": {
- "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"
}
Descargar PDF
Descarga el recibo digital en formato PDF.
Authorizations:
path Parameters
receipt_id required | string ID del objeto a descargar |
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
{- "message": "string"
}
Enviar recibo por correo electrónico
Envía un correo electrónico a la dirección de tu cliente.
El correo enviado estará personalizado con el logotipo y los colores de la organización que lo creó, e incluirá un botón para facturar el recibo, así con el recibo en formato PDF adjunto al mensaje.
Authorizations:
path Parameters
receipt_id required | string ID del objeto a obtener |
Request Body schema: application/jsonoptional
required | string or Array of strings Dirección de correo electrónico a enviar el recibo digital. |
One of string <email> Dirección de correo eletrónico |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "email": "otro@correo.com"
}
Response samples
- 200
- 400
- 401
- 500
{- "ok": true
}
Facturar recibo
Crea una factura a partir de un recibo.
Sólo pueden facturarse recibos abiertos (status = "open"
)
Una vez facturado, el status
del recibo cambiará a "invoiced_to_customer"
.
Authorizations:
path Parameters
receipt_id required | string ID del recibo a facturar |
Request Body schema: application/jsonrequired
required | Customer (object) or customer_id (string) Cliente receptor de la factura. |
use | string Default: "G01" Código de Uso CFDI según el catálogo del SAT. Puedes ver los códigos en esta tabla, o utilizar las constantes incluídas en nuestras librerías. |
conditions | string or null [ 1 .. 1000 ] characters Condiciones de pago |
folio_number | integer Default: "autoincremental" Número de folio asignado por la empresa para control interno. Si se omite, se asignará el valor autoincremental de la organización. |
series | string or null <= 25 characters Serie. Caracteres designados por la empresa para control interno y sin validez fiscal. |
pdf_custom_section | string or null <xml> En caso de que necesites incluir más información en el PDF, este campo te permite enviar código HTML con tu propio contenido. Por seguridad, el código que puedes enviar está limitado a las siguientes etiquetas: |
addenda | string or null <xml> Código XML con la Addenda que se necesite agregar a la factura. |
Array of objects (Namespace) Default: [] Si incluiste el parámetro | |
object Configura qué campos opcionales se queiren mostrar en el PDF. El SAT no obliga a mostrar estos campos, pero pueden activarse según la preferencia del cliente para la factura en curso. Utiliza este campo para peticiones de generación de facturas en las cuales necesites utilizar una configuración distinta al campo pdf_extra de la organización. |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "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
{- "id": "590ce6c56d04f840aa8438af",
- "created_at": "2017-05-05T20:55:33.468Z",
- "livemode": false,
- "status": "valid",
- "cancellation_status": "none",
- "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": {
- "0": {
- "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": { }
}
], - "received_payment_ids": { },
- "target_invoice_ids": { },
- "currency": "MXN",
- "exchange": 1,
- "complements": { },
- "pdf_custom_section": "string",
- "addenda": "string",
- "namespaces": [
- {
- "prefix": "iedu",
}
], - "stamp": {
- "signature": "string",
- "date": "2019-08-24T14:15:22Z",
- "sat_cert_number": "string",
- "sat_signature": "string"
}
}
Crear factura global
Crea una factura global que incluirá todos los recibos con status = “open”
de un cierto periodo.
Authorizations:
Request Body schema: application/jsonrequired
periodicity required | string Default: "Propiedad `periodicity` de la configuración de recibos de la organización." Enum: "day" "week" "fortnight" "month" "two_months" Periodicidad que corresponde al rango de fechas utilizado.
Si se omite, se tomará la configuración de recibos de la organización.
Si omites enviar los campos |
from | string <date> Default: "Inicio del último periodo" Fecha inicial de los recibos que se incluirán en la factura global.
Por default, este valor es el inicio del último periodo (día, semana,
quincena o mes), según el valor de "Periodicidad" ( |
to | string <date> Default: "Fin del último periodo" Fecha final de los recibos que se incluirán en la factura global.
Por default, este valor es el fin del último periodo (día, semana,
quincena o mes), según el valor de "Periodicidad" ( |
months | string Default: "Mes contenido en el rango de fechas utilizado." Clave que representa el mes o bimestre de la factura. Consulta los posibles valores en el catálogo de Meses y Bimestres. |
folio_number | integer Default: "autoincremental" Número de folio asignado por la empresa para control interno. Si se omite, se asignará el valor autoincremental de la organización. |
series | string or null <= 25 characters Serie. Caracteres designados por la empresa para control interno y sin validez fiscal. |
date | string <date> Default: "Valor del atributo `to`" Fecha de emisión de la factura. |
payment_form | string = 2 characters description: Código que representa la forma de pago, de acuerdo al catálogo del SAT. Si se incluye, los recibos se agruparán y se crearán la factura global por la forma de pago. |
receipts | Array of strings <hex> [ items <hex > ] Recibos a incluir en la factura global. Si se incluye este parámetro, los parámetros |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "from": "2022-01-01T00:00:00.000",
- "to": "2022-31-01T23:59:59.999",
- "periodicity": "day",
- "months": "01",
- "folio_number": "autoincremental",
- "series": "string",
- "date": "2022-01-01T00:00:00.000",
- "payment_form": "02",
- "receipts": [
- "614496b471d422de4b6cfcc4"
]
}
Response samples
- 200
- 400
- 401
- 404
- 500
{- "id": "590ce6c56d04f840aa8438af",
- "created_at": "2017-05-05T20:55:33.468Z",
- "livemode": false,
- "status": "valid",
- "cancellation_status": "none",
- "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": {
- "0": {
- "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": { }
}
], - "received_payment_ids": { },
- "target_invoice_ids": { },
- "currency": "MXN",
- "exchange": 1,
- "complements": { },
- "pdf_custom_section": "string",
- "addenda": "string",
- "namespaces": [
- {
- "prefix": "iedu",
}
], - "stamp": {
- "signature": "string",
- "date": "2019-08-24T14:15:22Z",
- "sat_cert_number": "string",
- "sat_signature": "string"
}
}
Crear retención
Crea una nueva Retención. Si el comprobante es creado en ambiente Live, ésta será timbrado y enviado al SAT.
Authorizations:
Request Body schema: application/jsonrequired
required | Customer (object) or customer_id (string) Cliente receptor de la factura. |
cve_retenc required | string Clave de la retención o información de pagos de acuerdo al catálogo del SAT. |
required | object Información sobre el periodo de la retención. |
required | object Información sobre el total de retenciones efectuadas en el periodo correspondiente. |
fecha_exp | string <date-time> Fecha de expedición del comprobante en formato ISO8601 (UTC String). |
desc_retenc | string Si la clave de la retención es “25” (Otro tipo de retenciones), este campo se usa para registrar la descripción de la retención. |
folio_int | string Identificador alfanumérico para control interno de la empresa y sin relevancia fiscal. |
external_id | string Identificador opcional que puedes usar para relacionar esta retención con tus registros y poder hacer búsquedas usando este identificador. Facturapi no valida que este campo sea único. |
idempotency_key | string Identificador único que puedes usar para evitar duplicados al reintentar una petición. Puede ser cualquier cadena de texto, mientras sea única para cada documento. |
complements | Array of strings <xml> (string) [ items <xml > ] Default: [] Arreglo de complementos a incluir en la factura. Cada elemento del arreglo deberá contener
un |
pdf_custom_section | string <html> En caso de que necesites incluir más información en el PDF, este campo te permite insertar código HTML con tu propio contenido. |
addenda | string <xml> Código XML con la Addenda que se necesite agregar a la factura. |
Array of objects (Namespace) Namespaces a insertar en el nodo raíz de la factura. Requerido en |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "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",
}
]
}
Response samples
- 200
- 400
- 401
- 404
- 500
{- "id": "590ce6c56d04f840aa8438af",
- "created_at": "2017-05-05T20:55:33.468Z",
- "livemode": false,
- "status": "valid",
- "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",
}
]
}
Listar retenciones
Regresa una lista paginada de todas las retenciones de una organización o realiza una búsqueda de acuerdo a parámetros
Authorizations:
query Parameters
q | string Consulta. Texto a buscar en el nombre fiscal del cliente o su RFC. |
customer | string Identificador del cliente. Útil para obtener las retenciones emitidas a un sólo cliente. |
object (DateRange) Objeto con rango de fechas solicitado. | |
page | integer >= 1 Página de resultados a regresar, empezando desde la página 1. |
limit | integer [ 1 .. 100 ] Default: 50 Número del 1 al 100 que representa la cantidad máxima de resultados a regresar con motivos de paginación. |
Responses
Request samples
- cURL
- Node.js
- C#
- PHP
# Todas las retenciones de la organización curl https://www.facturapi.io/v2/retentions \ -H "Authorization: Bearer sk_test_API_KEY" # Todas las retenciones emitidas para cierto cliente curl "https://www.facturapi.io/v2/retentions" \ -G \ -H "Authorization: Bearer sk_test_API_KEY" \ -d "customer=58e93bd8e86eb318b0197456" # Página 3 de los resultados de búsqueda de texto libre # de retenciones emitidas entre 2017 y 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
{- "page": 1,
- "total_pages": 1,
- "total_results": 1,
- "data": [
- {
- "id": "590ce6c56d04f840aa8438af",
- "created_at": "2017-05-05T20:55:33.468Z",
- "livemode": false,
- "status": "valid",
- "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",
}
]
}
]
}
Obtener retención por ID
Regresa el objeto 'Retention' relacionado al id
especificado.
Authorizations:
path Parameters
retention_id required | string ID del objeto a obtener |
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
{- "id": "590ce6c56d04f840aa8438af",
- "created_at": "2017-05-05T20:55:33.468Z",
- "livemode": false,
- "status": "valid",
- "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",
}
]
}
Cancelar retención
Realiza una solicitud de cancelación de retención ante el SAT.
A diferencia de las facturas comúnes, la cancelación de la retención es inmediata y no requiere autorización de parte del receptor.
Authorizations:
path Parameters
retention_id required | string ID de la retención a cancelar |
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
{- "id": "590ce6c56d04f840aa8438af",
- "created_at": "2017-05-05T20:55:33.468Z",
- "livemode": false,
- "status": "valid",
- "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",
}
]
}
Descargar retención
Descarga una retención en PDF, XML o ambos en un archivo comprimido ZIP.
Authorizations:
path Parameters
retention_id required | string ID del objeto a descargar |
format required | string Enum: "xml" "pdf" "zip" Formato del archivo de descarga |
Responses
Request samples
- cURL
- Node.js
- C#
- PHP
## Descargar PDF y XML comprimidos en archivo ZIP curl https://www.facturapi.io/v2/retentions/58e93bd8e86eb318b019743d/zip \ -H "Authorization: Bearer sk_test_API_KEY" ## Descargar sólo el PDF curl https://www.facturapi.io/v2/retentions/58e93bd8e86eb318b019743d/pdf \ -H "Authorization: Bearer sk_test_API_KEY" ## Descargar sólo el XML curl https://www.facturapi.io/v2/retentions/58e93bd8e86eb318b019743d/xml \ -H "Authorization: Bearer sk_test_API_KEY"
Response samples
- 400
- 401
- 500
{- "message": "string"
}
Enviar retención por correo electrónico
Envía un correo electrónico a la dirección de tu cliente, con los archivos XML y PDF adjuntos al mensaje.
Authorizations:
path Parameters
retention_id required | string ID del objeto a obtener |
Request Body schema: application/jsonoptional
string or Array of strings Dirección de correo electrónico a enviar la retención. Si no se envía este parámetro, la retención será enviada al correo que el cliente tenga registrado. | |
One of string <email> Dirección de correo eletrónico |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "email": "otro@correo.com"
}
Response samples
- 200
- 400
- 401
- 500
{- "ok": true
}
Crear organización
Crea una nueva Organización que pertenecerá a tu cuenta de usuario.
Después de crear la organización y antes de poder emitir facturas con la organización, deberás de terminar de configurarla llamando a los métodos de Actualizar datos fiscales y Subir certificados (CSD)
Recuerda que los folios de tu suscripción podrán ser consumidos por cualquiera de las organizaaciones registradas bajo tu cuenta.
Authorizations:
Request Body schema: application/jsonrequired
name required | string <= 100 characters Nombre comercial de la organización. |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "name": "string"
}
Response samples
- 200
- 400
- 401
- 404
- 500
{- "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"
}
}
Listar organizaciones
Regresa una lista paginada de todas las organizationes registradas bajo tu cuenta, o realiza una búsqueda de acuerdo a parámetros.
Authorizations:
query Parameters
q | string Consulta. Texto a buscar en |
object (DateRange) Objeto con rango de fechas solicitado. | |
page | integer >= 1 Página de resultados a regresar, empezando desde la página 1. |
limit | integer [ 1 .. 100 ] Default: 50 Número del 1 al 100 que representa la cantidad máxima de resultados a regresar con motivos de paginación. |
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
{- "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"
}
}
]
}
Detalle de organización
Retorna el detalle de la organización actualmente autenticada.
Authorizations:
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
{- "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"
}
}
Editar datos fiscales
Actualiza los datos fiscales de la organización.
Si estás buscando cómo editar el RFC, recuerda que la propiedad
tax_id
se asigna automáticamente al subir los Certificados de Sello
Digital.
Authorizations:
path Parameters
organization_id required | string ID de la organización |
Request Body schema: application/jsonrequired
name required | string <= 100 characters Nombre comercial de la organización. |
legal_name required | string <= 100 characters Nombre Fiscal o Razón Social de la organización, sin el régimen societario (ej.: S.A. de C.V.). |
tax_system required | string = 3 characters Código del Régimen Fiscal, del catálogo del SAT. |
required | object (OrganizationAddress) Domicilio fiscal de la organización emisora. |
website | string Sitio web de la organización, que aparecerá en el PDF y correos de facturas y recibos. |
support_email | string Dirección de correo electrónico para aclaraciones. Aparecerá en el PDF y correos de facturas y recibos. |
phone | string Teléfono de la organización, que aparecerá en el PDF y correos de facturas y recibos. |
Responses
Request samples
- Payload
- cURL
- Node.js
- C#
- PHP
{- "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
{- "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"
}
}
Subir certificados (CSD)
Sube los archivos del Certificado de Sello Digital (CSD) proporcionado por el SAT. Esta llamada también debe usarse para reemplazar los certificados existentes en caso de solicitar nuevos.
Al actualizar tus certificados se leerá el RFC y asignará
automáticamente a legal.tax_id
.
Authorizations:
path Parameters
organization_id required | string ID de la organización |
Request Body schema: multipart/form-datarequired
cerFile required | string <binary> Contenido binario del archivo con extensión |
keyFile required | string <binary> Contenido binario del archivo con extensión |
password required | string Contraseña de la llave del certificado. |
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