Facturapi (2.0)

Download OpenAPI specification:Download

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

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.

Clientes

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:

SecretLiveKeySecretTestKey

Request Body schema: application/json
required

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.
email	string <email> Dirección de correo electrónico al cual enviar las facturas generadas.
phone	string Teléfono del cliente.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

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

Response samples

Content type

application/json

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

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:

SecretLiveKeySecretTestKey

query Parameters

q	string Consulta. Texto a buscar en `legal_name` (nombre fiscal) o en `tax_id` (RFC).
	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

Content type

application/json

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

Obtener cliente por ID

Regresa el objeto 'Customer' relacionado al id especificado.

Authorizations:

SecretLiveKeySecretTestKey

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

Content type

application/json

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

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:

SecretLiveKeySecretTestKey

path Parameters

customer_id

required

string

ID del objeto a editar

Request Body schema: application/json
required

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.
email	string <email> Dirección de correo electrónico al cual enviar las facturas generadas.
phone	string Teléfono del cliente.
	object Domicilio fiscal.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

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

Response samples

200
400
401
500

Content type

application/json

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

Eliminar cliente

Elimina el cliente de tu organización. Las facturas asociadas al cliente no se eliminarán.

Authorizations:

SecretLiveKeySecretTestKey

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

Content type

application/json

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

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:

SecretLiveKey

path Parameters

customer_id

required

string

ID del objeto Customer a validar

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

Productos

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:

SecretLiveKeySecretTestKey

Request Body schema: application/json
required

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`.
tax_included	boolean or null Default: true `true`: Indica que todos los impuestos aplicables están incluídos en el precio (atributo price) y se desglosarán automáticamente al emitir la factura. `false`: Indica que el atributo price no incluye impuestos, por lo que aquellos impuestos a aplicar se sumarán en el precio final.
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" Código que representa si el bien o servicio es objeto de impuesto o no. Este atributo corresponde al campo "ObjetoImp" en el CFDI. `01`: No objeto de impuesto. `02`: Sí objeto de impuesto. `03`: Sí objeto de impuesto, pero no obligado a desglose. `04`: Sí objeto de impuesto, y no causa impuesto. `05`: Sí objeto de impuesto, IVA crédito PODEBI.
	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 `"H87"` (elemento) es la clave para representar una pieza o unidad de venta (lápiz, cuaderno, televisión, etc). Si la unidad de tu producto es kilogramos, litros, horas u otra unidad, puedes encontrar la clave utilizando nuestra herramienta de búsqueda de claves.
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 `unit_key`.
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

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

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:

SecretLiveKeySecretTestKey

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

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

Obtener producto por ID

Regresa el objeto Product relacionado al id especificado.

Authorizations:

SecretLiveKeySecretTestKey

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

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

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:

SecretLiveKeySecretTestKey

path Parameters

product_id

required

string

ID del objeto a editar

Request Body schema: application/json
required

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`.
tax_included	boolean or null Default: true `true`: Indica que todos los impuestos aplicables están incluídos en el precio (atributo price) y se desglosarán automáticamente al emitir la factura. `false`: Indica que el atributo price no incluye impuestos, por lo que aquellos impuestos a aplicar se sumarán en el precio final.
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" Código que representa si el bien o servicio es objeto de impuesto o no. Este atributo corresponde al campo "ObjetoImp" en el CFDI. `01`: No objeto de impuesto. `02`: Sí objeto de impuesto. `03`: Sí objeto de impuesto, pero no obligado a desglose. `04`: Sí objeto de impuesto, y no causa impuesto. `05`: Sí objeto de impuesto, IVA crédito PODEBI.
	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 `"H87"` (elemento) es la clave para representar una pieza o unidad de venta (lápiz, cuaderno, televisión, etc). Si la unidad de tu producto es kilogramos, litros, horas u otra unidad, puedes encontrar la clave utilizando nuestra herramienta de búsqueda de claves.
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 `unit_key`.
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

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

Eliminar producto

Elimina el producto de tu organización. Las facturas asociadas al producto no se eliminarán.

Authorizations:

SecretLiveKeySecretTestKey

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

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

Facturas

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:

SecretLiveKeySecretTestKey

query Parameters

async

boolean

Útil para facturas de gran tamaño. Si se envía false o no se envía, la llamada esperará a que el SAT responda timbrando la factura. Si se envía true, la llamada regresará inmediatamente con el objeto invoice en status pending, y podrá consultarse su cambio de status a `valid`` en un momento posterior.

Request Body schema: application/json
required

One of

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 `S01`.
type	string Default: "I" Value: "I" Tipo de comprobante. El valor default es `“I”` (Ingreso).
payment_method	string Default: "PUE" Enum: "PUE" "PPD" Código del método de pago según el catálogo del SAT. `PUE`: Pago en Una sola Exhibición `PPD`: Pago en Parcialidades o Diferido
currency	string Default: "MXN" Código de la moneda, acorde al estándar ISO 4217.
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 `currency`.
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. `01`: No aplica `02`: Definitiva con clave A1 `03`: Temporal `04`: Definitiva con clave distinta a A1 o cuando no existe enajenación en términos del CFF
	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 `custom`. Es necesario agregar la información del complemento al PDF por separado usando el parámetro `pdf_custom_section`.
status	string Default: "pending" Estado inicial de la factura. Si se envía `draft`, la factura se guardará como borrador y no se timbrará ni se enviará al SAT. También al enviar `draft`, todos los campos requeridos se vuelven opcionales. Si se omite, el estado por default es `pending` y una vez timbrada (en la respuesta) este campo se actualizará a `valid`. Para facturas asíncronas, este campo se quedará en `pending` hasta que se timbre la factura. pending
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: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `div`, `p`, `span`, `small`, `br`, `b`, `i`, `ul`, `ol`, `li`, `strong`, `table`, `thead`, `tbody`, `tfoot`, `tr`, `th` y `td`. No se permiten atributos ni estilos.
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 `complements`, este campo es opcional; en cambio si inclusite el parámetro `addenda`, debes enviar la información necesaria para incluir estos namespaces en el documento XML.
	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

Content type

application/json

Example

Ingreso

{ }

Response samples

200
400
401
404
500

Content type

application/json

Example

pending

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

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:

SecretLiveKeySecretTestKey

query Parameters

q	string Consulta. Texto a buscar en la factura. La búsqueda se realizará por coincidencias parciales en los campos: `items[].product.description` `customer.legal_name` Y por coincidencias exactas en los campos: `id` `uuid` `customer.tax_id` `folio_number` `total`
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

Content type

application/json

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

Obtener factura por ID

Regresa el objeto 'Invoice' relacionado al id especificado.

Authorizations:

SecretLiveKeySecretTestKey

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

Content type

application/json

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

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:

SecretLiveKeySecretTestKey

path Parameters

invoice_id

required

string

ID del objeto a editar

Request Body schema: application/json
required

One of

type	string Enum: "I" "E" "P" "N" "T" Tipo de comprobante. Puede tener los valores `"I"`: Ingreso, `"P"`: Pago, `"E"`: Egreso, `"N"`: Nómina, `"T"`: Traslado.
	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. `PUE`: Pago en Una sola Exhibición `PPD`: Pago en Parcialidades o Diferido
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 `S01`.
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 `currency`.
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. `01`: No aplica `02`: Definitiva con clave A1 `03`: Temporal `04`: Definitiva con clave distinta a A1 o cuando no existe enajenación en términos del CFF
	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 `custom`. Es necesario agregar la información del complemento al PDF por separado usando el parámetro `pdf_custom_section`.
	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 `draft`, y no es posible cambiar el status al editar, por lo que el único valor permitido es `draft`.
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: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `div`, `p`, `span`, `small`, `br`, `b`, `i`, `ul`, `ol`, `li`, `strong`, `table`, `thead`, `tbody`, `tfoot`, `tr`, `th` y `td`. No se permiten atributos ni estilos.
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 `complements`, este campo es opcional; en cambio si inclusite el parámetro `addenda`, debes enviar la información necesaria para incluir estos namespaces en el documento XML.
	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

Content type

application/json

Example

Ingreso

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

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 propiedad status: "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 propiedades status: "valid" y cancellation_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:

SecretLiveKeySecretTestKey

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.

01: Comprobante emitido con errores con relación. Cuando la factura contiene algún error en las cantidades, claves o cualquier otro dato y ya se ha emitido el comprobante que la sustituye, el cual deberá indicarse por medio del atributo substitution.
02: Comprobante emitido con errores sin relación. Cuando la factura contiene algún error en las cantidades, claves o cualquier otro dato y no se requiere relacionar con otra factura.
03: No se llevó a cabo la operación. Cuando la venta o transacción no se concretó.
04: Operación nominativa relacionada en la factura global. Cuando se requiere cancelar una factura al público en general porque el cliente solicita su comprobante.

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

Content type

application/json

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

Copiar a borrador

Crea una copia en borrador de la factura especificada.

Authorizations:

SecretLiveKeySecretTestKey

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

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

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:

SecretLiveKeySecretTestKey

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 false o no se envía, la llamada esperará a que el SAT responda timbrando la factura. Si se envía true, la llamada regresará inmediatamente con el objeto invoice en status pending, y podrá consultarse su cambio de status a `valid`` en un momento posterior.

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
409
500

Content type

application/json

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

Descargar acuse de cancelación

Descarga acuse de recibo de cancelación de una factura en un archivo xml o pdf.

Authorizations:

SecretLiveKeySecretTestKey

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

Content type

application/json

{"message": "string"
}

Descargar factura

Descarga tu Factura en PDF, XML o ambos en un archivo comprimido ZIP.

Authorizations:

SecretLiveKeySecretTestKey

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

Content type

application/json

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

SecretLiveKeySecretTestKey

path Parameters

invoice_id

required

string

ID del objeto a obtener

Request Body schema: application/json
optional

	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

Content type

application/json

{"email": "otro@correo.com"
}

Response samples

200
400
401
500

Content type

application/json

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

SecretLiveKeySecretTestKey

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

Content type

application/json

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

Recibos

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:

SecretUsertKey

Request Body schema: application/json
required

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 `currency`.
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

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

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:

SecretLiveKeySecretTestKey

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

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

Obtener recibo por ID

Regresa el objeto 'Receipt' relacionado al id especificado.

Authorizations:

SecretLiveKeySecretTestKey

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

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

Cancelar recibo

Marca un recibo como cancelado, cambiando su propiedad status a "canceled".

Una vez cancelado, el recibo no podrá ser facturado.

Authorizations:

SecretLiveKeySecretTestKey

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

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

Descargar PDF

Descarga el recibo digital en formato PDF.

Authorizations:

SecretLiveKeySecretTestKey

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

Content type

application/json

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

SecretLiveKeySecretTestKey

path Parameters

receipt_id

required

string

ID del objeto a obtener

Request Body schema: application/json
optional

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

Content type

application/json

{"email": "otro@correo.com"
}

Response samples

200
400
401
500

Content type

application/json

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

SecretLiveKeySecretTestKey

path Parameters

receipt_id

required

string

ID del recibo a facturar

Request Body schema: application/json
required

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: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `div`, `p`, `span`, `small`, `br`, `b`, `i`, `ul`, `ol`, `li`, `strong`, `table`, `thead`, `tbody`, `tfoot`, `tr`, `th` y `td`. No se permiten atributos ni estilos.
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 `complements`, este campo es opcional; en cambio si inclusite el parámetro `addenda`, debes enviar la información necesaria para incluir estos namespaces en el documento XML.
	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

Content type

application/json

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

Response samples

200
400
401
404
500

Content type

application/json

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

Crear factura global

Crea una factura global que incluirá todos los recibos con status = “open” de un cierto periodo.

Authorizations:

SecretLiveKeySecretTestKey

Request Body schema: application/json
required

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` y `to`, las fechas que se asignarán por default dependerán del valor de periodicity.
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" (`periodicity`) en la configuración de recibos de tu organización. Este valor es requerido cuando se envíe el campo `receipts`.
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" (`periodicity`) en la configuración de recibos de tu organización. Este valor es requerido cuando se envíe el campo `receipts`.
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 `from` y `to` serán requeridos y tendrán que cumplir con el campo `periodicity`.

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": "string",
"date": "2022-01-01T00:00:00.000",
"payment_form": "02",
"receipts": ["614496b471d422de4b6cfcc4"
]
}

Response samples

200
400
401
404
500

Content type

application/json

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

Retenciones

Crear retención

Crea una nueva Retención. Si el comprobante es creado en ambiente Live, ésta será timbrado y enviado al SAT.

Authorizations:

SecretLiveKeySecretTestKey

Request Body schema: application/json
required

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 `string` con el código XML de tu complemento tal cual como quieres que se inserte en el XML del CFDI. Sólo se permite un nodo XML raíz por elemento del arreglo.
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 `addenda`.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

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

Response samples

200
400
401
404
500

Content type

application/json

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

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:

SecretLiveKeySecretTestKey

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

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

Obtener retención por ID

Regresa el objeto 'Retention' relacionado al id especificado.

Authorizations:

SecretLiveKeySecretTestKey

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

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

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:

SecretLiveKeySecretTestKey

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

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

Descargar retención

Descarga una retención en PDF, XML o ambos en un archivo comprimido ZIP.

Authorizations:

SecretLiveKeySecretTestKey

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

Content type

application/json

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

SecretLiveKeySecretTestKey

path Parameters

retention_id

required

string

ID del objeto a obtener

Request Body schema: application/json
optional

	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

Content type

application/json

{"email": "otro@correo.com"
}

Response samples

200
400
401
500

Content type

application/json

{"ok": true
}

Organizaciones

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:

SecretUsertKey

Request Body schema: application/json
required

name

required

string <= 100 characters

Nombre comercial de la organización.

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

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:

SecretUsertKey

query Parameters

q	string Consulta. Texto a buscar en `name` (nombre comercial), `legal_name` (nombre fiscal) o en `tax_id` (RFC).
	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

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

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:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Request Body schema: application/json
required

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

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"

Facturapi (2.0)

Clientes

Crear cliente

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Listar clientes

Authorizations:

query Parameters

Responses

Request samples

Response samples

Obtener cliente por ID

Authorizations:

path Parameters

Responses

Request samples

Response samples

Editar cliente

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Eliminar cliente

Authorizations:

path Parameters

Responses

Request samples

Response samples

Validar información fiscal

Authorizations:

path Parameters

Responses

Request samples

Response samples

Productos

Crear producto

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Listar productos

Authorizations:

query Parameters

Responses

Request samples

Response samples

Obtener producto por ID

Authorizations:

path Parameters

Responses

Request samples

Response samples

Editar producto

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Eliminar producto

Authorizations:

path Parameters

Responses

Request samples

Response samples

Facturas

Crear factura (CFDI 4.0)

Authorizations:

query Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Listar facturas

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