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.
default_invoice_use	string Uso de CFDI por defecto.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

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

Response samples

Content type

application/json

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

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

Obtener cliente por ID

Regresa el objeto 'Customer' relacionado al id especificado.

Authorizations:

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

Editar cliente

Actualiza la información de un cliente existente, asignando los valores de los parámetros enviados. Los parámetros que no se envíen en la petición no se modificarán.

Authorizations:

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

Response samples

200
400
401
500

Content type

application/json

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

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

Validar información fiscal

Valida que la información fiscal del cliente coincida con los registros del SAT.

Su función principal es validar que los datos del cliente registraado siguen cumpliendo la validación del SAT.

:::tip Las operaciones de crear cliente, editar cliente y crear factura ya realizan una validación de la información del cliente, por lo que no es necesario llamar a este endpoint antes de realizar dichas operaciones. :::

Authorizations:

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" "06" "07" "08" Código que representa si el bien o servicio es objeto de impuesto o no. Este atributo corresponde al campo "ObjetoImp" en el CFDI. `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. `06`: Sí objeto de impuesto, no IVA trasladado. `07`: No traslado de IVA, pero desglose de IEPS. `08`: No traslado de IVA sin desglose de IEPS.
	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": {"0": {"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
}

Listar productos

Regresa una lista paginada de todos los productos de una organización o realiza una búsqueda de acuerdo a parámetros

Authorizations:

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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
}
]
}

Obtener producto por ID

Regresa el objeto Product relacionado al id especificado.

Authorizations:

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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
}

Editar producto

Actualiza la información de un producto existente, asignando los valores de los parámetros enviados. Los parámetros que no se envíen en la petición no se modificarán.

Authorizations:

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" "06" "07" "08" Código que representa si el bien o servicio es objeto de impuesto o no. Este atributo corresponde al campo "ObjetoImp" en el CFDI. `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. `06`: Sí objeto de impuesto, no IVA trasladado. `07`: No traslado de IVA, pero desglose de IEPS. `08`: No traslado de IVA sin desglose de IEPS.
	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": {"0": {"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
}

Eliminar producto

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

Authorizations:

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": {"0": {"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": { }
}
],
"received_payment_ids": { },
"target_invoice_ids": { },
"currency": "MXN",
"exchange": 1,
"complements": { },
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": { }
}
],
"received_payment_ids": { },
"target_invoice_ids": { },
"currency": "MXN",
"exchange": 1,
"complements": { },
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": { }
}
],
"received_payment_ids": { },
"target_invoice_ids": { },
"currency": "MXN",
"exchange": 1,
"complements": { },
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": [{"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
],
"customs_keys": ["string"
],
"complement": "string",
"third_party": {"legal_name": "The Michael Scott Paper Company",
"tax_id": "MIC920101HN7",
"tax_system": "601",
"zip": "01234"
},
"property_tax_account": "0102030405"
}
],
"payment_form": "03",
"payment_method": "PUE",
"use": "G01",
"currency": "MXN",
"exchange": 0,
"conditions": "string",
"related_documents": [{"relationship": "string",
"documents": { }
}
],
"global": {"periodicity": "day",
"months": "01",
"year": 2022
},
"export": "01",
"complements": [{"type": "custom",
"data": "string"
}
],
"customer": {"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"tax_system": "601",
"email": "email@example.com",
"phone": 6474010101,
"default_invoice_use": "G01",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
},
"status": "draft",
"date": "2019-08-24T14:15:22Z",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"external_id": "string",
"idempotency_key": "string",
"folio_number": 0,
"series": "string",
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": { }
}
],
"currency": "MXN",
"exchange": 1,
"complements": { },
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": { }
}
],
"received_payment_ids": { },
"target_invoice_ids": { },
"currency": "MXN",
"exchange": 1,
"complements": { },
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": { }
}
],
"currency": "MXN",
"exchange": 1,
"complements": { },
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": { }
}
],
"received_payment_ids": { },
"target_invoice_ids": { },
"currency": "MXN",
"exchange": 1,
"complements": { },
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": { }
}
],
"received_payment_ids": { },
"target_invoice_ids": { },
"currency": "MXN",
"exchange": 1,
"complements": { },
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": [{"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
],
"customs_keys": ["string"
],
"complement": "string",
"third_party": {"legal_name": "The Michael Scott Paper Company",
"tax_id": "MIC920101HN7",
"tax_system": "601",
"zip": "01234"
},
"property_tax_account": "0102030405"
}
],
"date": "2021-09-10T15:21:23.456Z",
"payment_form": "03",
"folio_number": 120,
"currency": "MXN",
"exchange": 1,
"branch": "string",
"external_id": "string",
"idempotency_key": "string"
}

Response samples

200
400
401
404
500

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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"external_id": "string",
"idempotency_key": "string",
"payment_form": "03",
"folio_number": 120,
"currency": "MXN",
"exchange": 1,
"branch": "string"
}

Listar recibos

Regresa una lista paginada de todos los recibos de una organización o realiza una búsqueda de acuerdo a parámetros

Authorizations:

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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"external_id": "string",
"idempotency_key": "string",
"payment_form": "03",
"folio_number": 120,
"currency": "MXN",
"exchange": 1,
"branch": "string"
}
]
}

Obtener recibo por ID

Regresa el objeto 'Receipt' relacionado al id especificado.

Authorizations:

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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"external_id": "string",
"idempotency_key": "string",
"payment_form": "03",
"folio_number": 120,
"currency": "MXN",
"exchange": 1,
"branch": "string"
}

Cancelar recibo

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

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

Authorizations:

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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"external_id": "string",
"idempotency_key": "string",
"payment_form": "03",
"folio_number": 120,
"currency": "MXN",
"exchange": 1,
"branch": "string"
}

Descargar PDF

Descarga el recibo digital en formato PDF.

Authorizations:

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,
"default_invoice_use": "G01",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
},
"use": "G01",
"conditions": "string",
"folio_number": "autoincremental",
"series": "string",
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": { },
"pdf_options": {"codes": true,
"product_key": true,
"round_unit_price": false,
"tax_breakdown": true,
"ieps_breakdown": true
}
}

Response samples

200
400
401
404
500

Content type

application/json

{"id": "590ce6c56d04f840aa8438af",
"created_at": "2017-05-05T20:55:33.468Z",
"livemode": false,
"status": "valid",
"cancellation_status": "none",
"verification_url": "https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id=45BEC0CA-5F1E-491E-9417-698EA48C382A&re=AAA010101AAA&rr=ABC101010111&tt=345.600000&fe=bWApPw==",
"date": "now",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora"
},
"type": "I",
"customer": {"id": "58e93bd8e86eb318b0197456",
"legal_name": "Dunder Mifflin",
"tax_id": "ABC101010111",
"address": {"country": "MEX"
}
},
"total": 10944.82,
"uuid": "39c85a3f-275b-4341-b259-e8971d9f8a94",
"folio_number": 914,
"series": "F",
"external_id": "string",
"idempotency_key": "string",
"payment_form": 6,
"is_ready_to_stamp": true,
"items": [{"quantity": 1,
"discount": 0,
"product": {"id": "58e93bd8e86eb318b0197454",
"description": "Ukelele",
"product_key": 60131324,
"price": 345.6,
"tax_included": true,
"taxability": "01",
"taxes": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": { }
}
],
"received_payment_ids": { },
"target_invoice_ids": { },
"currency": "MXN",
"exchange": 1,
"complements": { },
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"related_documents": [{"relationship": "string",
"documents": { }
}
],
"received_payment_ids": { },
"target_invoice_ids": { },
"currency": "MXN",
"exchange": 1,
"complements": { },
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"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,
"default_invoice_use": "G01",
"address": {"street": "Blvd. Atardecer",
"exterior": 142,
"interior": 4,
"neighborhood": "Centro",
"city": "Huatabampo",
"municipality": "Huatabampo",
"zip": 86500,
"state": "Sonora",
"country": "MEX"
}
},
"cve_retenc": 26,
"fecha_exp": "2021-09-15T06:03:23.000Z",
"desc_retenc": "string",
"folio_int": "R123",
"periodo": {"mes_ini": 9,
"mes_fin": 9,
"ejerc": 2021
},
"totales": {"monto_tot_operacion": 0,
"monto_tot_grav": 0,
"monto_tot_exent": 0,
"monto_tot_ret": 0,
"imp_retenidos": [{"base_ret": 0,
"impuesto": "IVA",
"monto_ret": 0,
"tipo_pago_ret": 1
}
]
},
"external_id": "string",
"idempotency_key": "string",
"complements": { },
"pdf_custom_section": "string",
"addenda": "string",
"namespaces": [{"prefix": "iedu",
"uri": "http://www.sat.gob.mx/iedu",
"schema_location": "http://www.sat.gob.mx/sitio_interet/cfd/iedu/iedu.xsd"
}
]
}

Response samples

200
400
401
404
500

Content type

application/json

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

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

Detalle de organización

Retorna el detalle de la organización actualmente autenticada.

Authorizations:

SecretLiveKeySecretTestKey

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
404
500

Content type

application/json

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

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

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

Subir certificados (CSD)

Sube los archivos del Certificado de Sello Digital (CSD) proporcionado por el SAT. Esta llamada también debe usarse para reemplazar los certificados existentes en caso de solicitar nuevos.

Al actualizar tus certificados se leerá el RFC y asignará automáticamente a legal.tax_id.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Request Body schema: multipart/form-data
required

cerFile required	string <binary> Contenido binario del archivo con extensión `.cer` del certificado CSD.
keyFile required	string <binary> Contenido binario del archivo con extensión `.key` del certificado CSD.
password required	string Contraseña de la llave del certificado.

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
404
500

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

Eliminar certificados (CSD)

Elimina los certificados (CSD) de tu organización.

Esto no afecta a las facturas ya emitidas, pero no podrás emitir nuevas facturas hasta que subas nuevos certificados.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
404
500

Content type

application/json

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

Subir logotipo

Sube el logotipo de la organización que será colocado en el PDF y en los correos que se envían al cliente con la factura adjunta.

El archivo debe ser una imagen en formato JPG o PNG y tener un tamaño no mayor a 500 KB. Las dimensiones recomendadas son 800 × 500px.

Si la organización ya tiene un logotipo, esta llamada reemplaza el logotipo anterior.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Request Body schema: multipart/form-data
required

file

required

string <binary>

Contenido binario del archivo con la imagen que se usará como logotipo. Formatos soportados:

jpg
png
svg

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
404
500

Content type

application/json

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

Editar personalización

Actualiza la información relacionada con la identidad o branding de la organización.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Request Body schema: application/json
required

color	string <hex> Color distintivo de la marca en representación Hexadecimal RGB de 6 caracteres.
next_folio_number	integer Número de folio que se asignará a la siguiente factura en ambiente Live (y que se incrementará automáticamente por cada nueva factura).
next_folio_number_test	integer Número de folio que se asignará a la siguiente factura en ambiente Test (y que se incrementará automáticamente por cada nueva factura).
	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 de la organización.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"color": "BADA55",
"next_folio_number": 123,
"next_folio_number_test": 123,
"pdf_extra": {"codes": true,
"product_key": true,
"round_unit_price": false,
"tax_breakdown": true,
"ieps_breakdown": true
}
}

Response samples

200
400
401
404
500

Content type

application/json

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

Editar config. recibos

Actualiza la configuración de recibos de la organización.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Request Body schema: application/json
required

periodicity	string Default: "month" Enum: "day" "week" "fortnight" "month" "two_months" Periodicidad con la que la empresa decide realizar una factura global (al público en general) por todos los recibos no facturados. Este valor se utiliza como default al crear una factura global.
duration_days	integer Default: 7 Días máximos para facturar por medio del portal de autofactura después de emitido el recibo y antes del último día del periodo definido por el atributo `periodicity`. El valor `0` desactiva esta opción, haciendo que los recibos expiren siempre el último día del periodo.
next_folio_number	integer Número de folio que se asignará al siguiente recibo creado en esta organización en ambiente Live.
next_folio_number_test	integer Número de folio que se asignará al siguiente recibo creado en esta organización en ambiente Test.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

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

Response samples

200
400
401
404
500

Content type

application/json

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

Revisar dominio disponible

Revisa si un identificador está disponible para elegir como dominio para el portal de autofactura.

Authorizations:

SecretUsertKey

query Parameters

domain

required

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

Nombre del dominio. Se permiten caracteres alfanuméricos, sólo minúsculas, guión (-) y guión bajo (_). Debe empezar con una letra y terminar en letra o número.

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

{"available": true
}

Elegir dominio de autofactura

Elige el dominio que utilizará esta organización en su micrositio de autofactura. Una vez elegido el dominio, deberás ponerte en contacto con nosotros si necesitas cambiarlo.

El dominio que elijas será el que aparecerá en el campo self_invoice_url al crear un nuevo recibo, de la siguiente manera:

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

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Request Body schema: application/json
required

domain

required

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

Nombre del dominio. Se permiten caracteres alfanuméricos, sólo minúsculas, guión (-) y guión bajo (_). Debe empezar con una letra y terminar en letra o número.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"domain": "string"
}

Response samples

200
400
401
404
500

Content type

application/json

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

Obtener organización por ID

Regresa el objeto 'Organization' relacionado al id especificado.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

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

Eliminar organización

Elimina la organización de tu cuenta de Facturapi. Una vez eliminada, ya no podrás acceder a sus recursos, tales como clientes, productos, facturas, recibos o retenciones.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID del objeto a eliminar

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

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

Obtener Test Api Key

Obtiene la llave secreta de ambiente Test de la organización.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

"sk_test_API_KEY"

Renovar Test API Key

Renueva la llave secreta de ambiente Test de la organización e invalida inmediatamente la anterior.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

"sk_test_API_KEY"

Listar Live API Keys

Listar llaves secretas de ambiente Live de la organización.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

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

Renovar Live API Key

Genera una nueva llave secreta de ambiente Live de la organización. Esta operación no invalida las llaves generadas previamente.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

"sk_live_API_KEY"

Revocar Live API Key

Revocar Live Api Key de tu organización.

Authorizations:

SecretUsertKey

path Parameters

organization_id required	string ID de la organización
id required	string ID de la llave secreta a eliminar

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

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

Listado de series

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

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

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

Crear serie

Crea una nueva serie de folios para la organización. Las series son útiles para llevar un control de los folios emitidos para cada tipo de factura.

Authorizations:

SecretUsertKey

path Parameters

organization_id

required

string

ID de la organización

Request Body schema: application/json

series required	string <= 55 characters Nombre de la serie.
next_folio required	integer Número de folio que se asignará a la siguiente factura en ambiente Live (y que se incrementará automáticamente por cada nueva factura).
next_folio_test required	integer Número de folio que se asignará a la siguiente factura en ambiente Test (y que se incrementará automáticamente por cada nueva factura).

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

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

Response samples

200
400
401
500

Content type

application/json

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

Editar serie

Edita el número de foliaje de la serie en ambientes Test y Live de la organización.

Authorizations:

SecretUsertKey

path Parameters

organization_id required	string ID de la organización
series_name required	string Nombre de la serie

Request Body schema: application/json

next_folio	integer Número de folio que se asignará a la siguiente factura en ambiente Live (y que se incrementará automáticamente por cada nueva factura).
next_folio_test	integer Número de folio que se asignará a la siguiente factura en ambiente Test (y que se incrementará automáticamente por cada nueva factura).

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

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

Response samples

200
400
401
500

Content type

application/json

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

Eliminar serie

Elimina la serie previamente creada

Authorizations:

SecretUsertKey

path Parameters

organization_id required	string ID de la organización
series_name required	string Nombre de la serie

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

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

Herramientas

Health check (Pulso)

Indica el estatus de disponibilidad de la API.

Authorizations:

SecretLiveKeySecretTestKey

Responses

Response samples

200

Content type

application/json

{"ok": true
}

Validar RFC

Consulta el estado de un RFC en la lista de EFOS (Empresas que Facturan Operaciones Simuladas). Al aparecer en esta lista, el RFC es o fue sospechoso de incurrir en simulación de operaciones fiscales (empresas factureras).

La respuesta (detallada más abajo) incluye los resultados de esta validación. Se incluye la propiedad booleana is_valid, que Facturapi resuelve interpretando la respuesta. Un valor de true para esta propiedad indica que el RFC no tiene asuntos por resolver y está libre de problemas; y lo contrario para false.

Adicionalmente puedes consultar la propiedad data para ver los valores en bruto de la consulta al SAT.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

tax_id

required

string

Example: tax_id=BBA830831LJ2

RFC a validar

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

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

Claves de catálogos

Principales catálogos del SAT, incluídos aquí por conveniencia. Puedes consultar estos y más catálogos desde el portal oficial del SAT: http://omawww.sat.gob.mx/tramitesyservicios/Paginas/anexo_20_version3-3.htm

Forma de pago

Clave	Descripción
"01"	Efectivo
"02"	Cheque nominativo
"03"	Transferencia electrónica de fondos
"04"	Tarjeta de crédito
"05"	Monedero electrónico
"06"	Dinero electrónico
"08"	Vales de despensa
"12"	Dación en pago
"13"	Pago por subrogación
"14"	Pago por consignación
"15"	Condonación
"17"	Compensación
"23"	Novación
"24"	Confusión
"25"	Remisión de deuda
"26"	Prescripción o caducidad
"27"	A satisfacción del acreedor
"28"	Tarjeta de débito
"29"	Tarjeta de servicios
"30"	Aplicación de anticipos
"31"	Intermediario pagos
"99"	Por definir

Método de pago

Clave	Descripción
"PUE"	Pago en una sola exhibición (de contado).
"PPD"	Pago en parcialidades o diferido (total o parcialmente a crédito). Requiere expedir un comprobante de pago cuando se reciba un pago subsecuente.

Uso CFDI

Clave	Descripción	Régimen Fiscal
"G01"	Adquisición de mercancías.	601, 603, 606, 612, 620, 621, 622, 623, 624, 625,626
"G02"	Devoluciones, descuentos o bonificaciones.	601, 603, 606, 612, 620, 621, 622, 623, 624, 625,626
"G03"	Gastos en general.	601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
"I01"	Construcciones.	601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
"I02"	Mobiliario y equipo de oficina por inversiones.	601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
"I03"	Equipo de transporte.	601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
"I04"	Equipo de computo y accesorios.	601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
"I05"	Dados, troqueles, moldes, matrices y herramental.	601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
"I06"	Comunicaciones telefónicas.	601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
"I07"	Comunicaciones satelitales.	601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
"I08"	Otra maquinaria y equipo.	601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
"D01"	Honorarios médicos, dentales y gastos hospitalarios.	605, 606, 608, 611, 612, 614, 607, 615, 625
"D02"	Gastos médicos por incapacidad o discapacidad.	605, 606, 608, 611, 612, 614, 607, 615, 625
"D03"	Gastos funerales.	605, 606, 608, 611, 612, 614, 607, 615, 625
"D04"	Donativos.	605, 606, 608, 611, 612, 614, 607, 615, 625
"D05"	Intereses reales efectivamente pagados por créditos hipotecarios (casa habitación).	605, 606, 608, 611, 612, 614, 607, 615, 625
"D06"	Aportaciones voluntarias al SAR.	605, 606, 608, 611, 612, 614, 607, 615, 625
"D07"	Primas por seguros de gastos médicos.	605, 606, 608, 611, 612, 614, 607, 615, 625
"D08"	Gastos de transportación escolar obligatoria.	605, 606, 608, 611, 612, 614, 607, 615, 625
"D09"	Depósitos en cuentas para el ahorro, primas que tengan como base planes de pensiones.	605, 606, 608, 611, 612, 614, 607, 615, 625
"D10"	Pagos por servicios educativos (colegiaturas).	605, 606, 608, 611, 612, 614, 607, 615, 625
"S01"	Sin efectos fiscales.	601, 603, 605, 606, 608, 610, 611, 612, 614, 616, 620, 621, 622, 623, 624, 607, 615, 625, 626
"CP01"	Pagos	601, 603, 605, 606, 608, 610, 611, 612, 614, 616, 620, 621, 622, 623, 624, 607, 615, 625, 626
"CN01"	Nómina	605

Relación entre facturas

Clave	Descripción
"01"	Nota de crédito de los documentos relacionados
"02"	Nota de débito de los documentos relacionados
"03"	Devolución de mercancía sobre facturas o traslados previos
"04"	Sustitución de los CFDI previos
"05"	Traslados de mercancias facturados previamente
"06"	Factura generada por los traslados previos
"07"	CFDI por aplicación de anticipo
"08"	Factura generada por pagos en parcialidades
"09"	Factura generada por pagos diferidos

Régimen Fiscal

Clave	Descripción
"601"	General de Ley Personas Morales
"603"	Personas Morales con Fines no Lucrativos
"605"	Sueldos y Salarios e Ingresos Asimilados a Salarios
"606"	Arrendamiento
"608"	Demás ingresos
"609"	Consolidación
"610"	Residentes en el Extranjero sin Establecimiento Permanente en México
"611"	Ingresos por Dividendos (socios y accionistas)
"612"	Personas Físicas con Actividades Empresariales y Profesionales
"614"	Ingresos por intereses
"616"	Sin obligaciones fiscales
"620"	Sociedades Cooperativas de Producción que optan por diferir sus ingresos
"621"	Incorporación Fiscal
"622"	Actividades Agrícolas, Ganaderas, Silvícolas y Pesqueras
"623"	Opcional para Grupos de Sociedades
"624"	Coordinados
"628"	Hidrocarburos
"607"	Régimen de Enajenación o Adquisición de Bienes
"629"	De los Regímenes Fiscales Preferentes y de las Empresas Multinacionales
"630"	Enajenación de acciones en bolsa de valores
"615"	Régimen de los ingresos por obtención de premios
"625"	Régimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas
"626"	Régimen Simplificado de Confianza

Meses y bimestres

Clave	Descripción
01	Enero
02	Febrero
03	Marzo
04	Abril
05	Mayo
06	Junio
07	Julio
08	Agosto
09	Septiembre
10	Octubre
11	Noviembre
12	Diciembre
13	Enero-Febrero
14	Marzo-Abril
15	Mayo-Junio
16	Julio-Agosto
17	Septiembre-Octubre
18	Noviembre-Diciembre

Tipo de Contrato

Clave	Descripción
"01"	Contrato de trabajo por tiempo indeterminado
"02"	Contrato de trabajo para obra determinada
"03"	Contrato de trabajo por tiempo determinado
"04"	Contrato de trabajo por temporada
"05"	Contrato de trabajo sujeto a prueba
"06"	Contrato de trabajo con capacitación inicial
"07"	Modalidad de contratación por pago de hora laborada
"08"	Modalidad de trabajo por comisión laboral
"09"	Modalidades de contratación donde no existe relación de trabajo
"10"	Jubilación, pensión, retiro.
"99"	Otro contrato

Tipo de Jornada

Clave	Descripción
"01"	Diurna
"02"	Nocturna
"03"	Mixta
"04"	Por hora
"05"	Reducida
"06"	Continuada
"07"	Partida
"08"	Por turnos
"99"	Otra Jornada

Tipo de Régimen

Clave	Descripción
"02"	Sueldos (Incluye ingresos señalados en la fracción I del artículo 94 de LISR)
"03"	Jubilados
"04"	Pensionados
"05"	Asimilados Miembros Sociedades Cooperativas Produccion
"06"	Asimilados Integrantes Sociedades Asociaciones Civiles
"07"	Asimilados Miembros consejos
"08"	Asimilados comisionistas
"09"	Asimilados Honorarios
"10"	Asimilados acciones
"11"	Asimilados otros
"12"	Jubilados o Pensionados
"13"	Indemnización o Separación
"99"	Otro Regimen

Riesgo del Puesto

Clave	Descripción
"1"	Clase I
"2"	Clase II
"3"	Clase III
"4"	Clase IV
"5"	Clase V
"99"	No aplica

Periodicidad del Pago

Clave	Descripción
"01"	Diario
"02"	Semanal
"03"	Catorcenal
"04"	Quincenal
"05"	Mensual
"06"	Bimestral
"07"	Unidad obra
"08"	Comisión
"09"	Precio alzado
"10"	Decenal
"99"	Otra Periodicidad

Tipo de Percepción

Clave	Descripción
"001"	Sueldos, Salarios Rayas y Jornales
"002"	Gratificación Anual (Aguinaldo)
"003"	Participación de los Trabajadores en las Utilidades PTU
"004"	Reembolso de Gastos Médicos Dentales y Hospitalarios
"005"	Fondo de Ahorro
"006"	Caja de ahorro
"009"	Contribuciones a Cargo del Trabajador Pagadas por el Patrón
"010"	Premios por puntualidad
"011"	Prima de Seguro de vida
"012"	Seguro de Gastos Médicos Mayores
"013"	Cuotas Sindicales Pagadas por el Patrón
"014"	Subsidios por incapacidad
"015"	Becas para trabajadores y/o hijos
"019"	Horas extra
"020"	Prima dominical
"021"	Prima vacacional
"022"	Prima por antigüedad
"023"	Pagos por separación
"024"	Seguro de retiro
"025"	Indemnizaciones
"026"	Reembolso por funeral
"027"	Cuotas de seguridad social pagadas por el patrón
"028"	Comisiones
"029"	Vales de despensa
"030"	Vales de restaurante
"031"	Vales de gasolina
"032"	Vales de ropa
"033"	Ayuda para renta
"034"	Ayuda para artículos escolares
"035"	Ayuda para anteojos
"036"	Ayuda para transporte
"037"	Ayuda para gastos de funeral
"038"	Otros ingresos por salarios
"039"	Jubilaciones, pensiones o haberes de retiro
"044"	Jubilaciones, pensiones o haberes de retiro en parcialidades
"045"	Ingresos en acciones o títulos valor que representan bienes
"046"	Ingresos asimilados a salarios
"047"	Alimentación diferentes a los establecidos en el Art 94 último párrafo LISR
"048"	Habitación
"049"	Premios por asistencia
"050"	Viáticos
"051"	Pagos por gratificaciones, primas, compensaciones, recompensas u otros en parcialidades
"052"	Pagos por jubilación en parcialidades derivados de una resolución judicial
"053"	Pagos por jubilación en una sola exhibición derivados de la ejecución de una resolución judicial

Tipo de Horas

Clave	Descripción
"01"	Dobles
"02"	Triples
"03"	Simples

Tipo de Deducción

Clave	Descripción
"001"	Seguridad social
"002"	ISR
"003"	Aportaciones a retiro, cesantía en edad avanzada y vejez.
"004"	Otros
"005"	Aportaciones a Fondo de vivienda
"006"	Descuento por incapacidad
"007"	Pensión alimenticia
"008"	Renta
"009"	Préstamos provenientes del Fondo Nacional de la Vivienda para los Trabajadores
"010"	Pago por crédito de vivienda
"011"	Pago de abonos INFONACOT
"012"	Anticipo de salarios
"013"	Pagos hechos con exceso al trabajador
"014"	Errores
"015"	Pérdidas
"016"	Averías
"017"	Adquisición de artículos producidos por la empresa o establecimiento
"018"	Cuotas para la constitución y fomento de sociedades cooperativas y de cajas de ahorro
"019"	Cuotas sindicales
"020"	Ausencia (Ausentismo)
"021"	Cuotas obrero patronales
"022"	Impuestos Locales
"023"	Aportaciones voluntarias
"024"	Ajuste en Gratificación Anual (Aguinaldo) Exento
"025"	Ajuste en Gratificación Anual (Aguinaldo) Gravado
"026"	Ajuste en Participación de los Trabajadores en las Utilidades PTU Exento
"027"	Ajuste en Participación de los Trabajadores en las Utilidades PTU Gravado
"028"	Ajuste en Reembolso de Gastos Médicos Dentales y Hospitalarios Exento
"029"	Ajuste en Fondo de ahorro Exento
"030"	Ajuste en Caja de ahorro Exento
"031"	Ajuste en Contribuciones a Cargo del Trabajador Pagadas por el Patrón Exento
"032"	Ajuste en Premios por puntualidad Gravado
"033"	Ajuste en Prima de Seguro de vida Exento
"034"	Ajuste en Seguro de Gastos Médicos Mayores Exento
"035"	Ajuste en Cuotas Sindicales Pagadas por el Patrón Exento
"036"	Ajuste en Subsidios por incapacidad Exento
"037"	Ajuste en Becas para trabajadores y/o hijos Exento
"038"	Ajuste en Horas extra Exento
"039"	Ajuste en Horas extra Gravado
"040"	Ajuste en Prima dominical Exento
"041"	Ajuste en Prima dominical Gravado
"042"	Ajuste en Prima vacacional Exento
"043"	Ajuste en Prima vacacional Gravado
"044"	Ajuste en Prima por antigüedad Exento
"045"	Ajuste en Prima por antigüedad Gravado
"046"	Ajuste en Pagos por separación Exento
"047"	Ajuste en Pagos por separación Gravado
"048"	Ajuste en Seguro de retiro Exento
"049"	Ajuste en Indemnizaciones Exento
"050"	Ajuste en Indemnizaciones Gravado
"051"	Ajuste en Reembolso por funeral Exento
"052"	Ajuste en Cuotas de seguridad social pagadas por el patrón Exento
"053"	Ajuste en Comisiones Gravado
"054"	Ajuste en Vales de despensa Exento
"055"	Ajuste en Vales de restaurante Exento
"056"	Ajuste en Vales de gasolina Exento
"057"	Ajuste en Vales de ropa Exento
"058"	Ajuste en Ayuda para renta Exento
"059"	Ajuste en Ayuda para artículos escolares Exento
"060"	Ajuste en Ayuda para anteojos Exento
"061"	Ajuste en Ayuda para transporte Exento
"062"	Ajuste en Ayuda para gastos de funeral Exento
"063"	Ajuste en Otros ingresos por salarios Exento
"064"	Ajuste en Otros ingresos por salarios Gravado
"065"	Ajuste en Jubilaciones, pensiones o haberes de retiro en una sola exhibición Exento
"066"	Ajuste en Jubilaciones, pensiones o haberes de retiro en una sola exhibición Gravado
"067"	Ajuste en Pagos por separación Acumulable
"068"	Ajuste en Pagos por separación No acumulable
"069"	Ajuste en Jubilaciones, pensiones o haberes de retiro en parcialidades Exento
"070"	Ajuste en Jubilaciones, pensiones o haberes de retiro en parcialidades Gravado
"071"	Ajuste en Subsidio para el empleo (efectivamente entregado al trabajador)
"072"	Ajuste en Ingresos en acciones o títulos valor que representan bienes Exento
"073"	Ajuste en Ingresos en acciones o títulos valor que representan bienes Gravado
"074"	Ajuste en Alimentación Exento
"075"	Ajuste en Alimentación Gravado
"076"	Ajuste en Habitación Exento
"077"	Ajuste en Habitación Gravado
"078"	Ajuste en Premios por asistencia
"079"	Ajuste en Pagos distintos a los listados
"080"	Ajuste en Viáticos gravados
"081"	Ajuste en Viáticos (entregados al trabajador)
"082"	Ajuste en Fondo de ahorro Gravado
"083"	Ajuste en Caja de ahorro Gravado
"084"	Ajuste en Prima de Seguro de vida Gravado
"085"	Ajuste en Seguro de Gastos Médicos Mayores Gravado
"086"	Ajuste en Subsidios por incapacidad Gravado
"087"	Ajuste en Becas para trabajadores y/o hijos Gravado
"088"	Ajuste en Seguro de retiro Gravado
"089"	Ajuste en Vales de despensa Gravado
"090"	Ajuste en Vales de restaurante Gravado
"091"	Ajuste en Vales de gasolina Gravado
"092"	Ajuste en Vales de ropa Gravado
"093"	Ajuste en Ayuda para renta Gravado
"094"	Ajuste en Ayuda para artículos escolares Gravado
"095"	Ajuste en Ayuda para anteojos Gravado
"096"	Ajuste en Ayuda para transporte Gravado
"097"	Ajuste en Ayuda para gastos de funeral Gravado
"098"	Ajuste a ingresos asimilados a salarios gravados
"099"	Ajuste a ingresos por sueldos y salarios gravados
"100"	Ajuste en Viáticos exentos
"101"	ISR Retenido de ejercicio anterior
"102"	Ajuste a pagos por gratificaciones, primas, compensaciones, recompensas u otros
"103"	Ajuste a pagos en parcialidades derivados de una resolución judicial gravados
"104"	Ajuste a pagos en parcialidades derivados de una resolución judicial exentos
"105"	Ajuste a pagos en una sola exhibición derivados de una resolución judicial gravados
"106"	Ajuste a pagos en una sola exhibición derivados de una resolución judicial exentos
"107"	Ajuste al Subsidio Causado

Tipo de Otro Pago

Clave	Descripción
"001"	Reintegro de ISR pagado en exceso.
"002"	Subsidio para el empleo (efectivamente entregado al trabajador).
"003"	Viáticos (entregados al trabajador).
"004"	Aplicación de saldo a favor por compensación anual.
"005"	Reintegro de ISR retenido en exceso de ejercicio anterior
"006"	Alimentos en bienes (Servicios de comedor y comida).
"007"	ISR ajustado por subsidio.
"008"	Subsidio efectivamente entregado que no correspondía.
"009"	Reembolso de descuentos efectuados para el crédito de vivienda.
"999"	Pagos distintos a los listados.

Tipo de Incapacidad

Clave	Descripción
"01"	Riesgo de trabajo.
"02"	Enfermedad en general.
"03"	Maternidad.
"04"	Licencia por cuidados médicos de hijos diagnosticados con cáncer.

Clave de retención

Clave	Descripción
"01"	Servicios profesionales.
"02"	Regalías por derechos de autor.
"03"	Autotransporte terrestre de carga.
"04"	Servicios prestados por comisionistas.
"05"	Arrendamiento.
"06"	Enajenación de acciones.
"07"	Enajenación de bienes objeto de la LIEPS, a través de mediadores, agentes, representantes, corredores, consignatarios o distribuidores.
"08"	Enajenación de bienes inmuebles consignada en escritura pública.
"09"	Enajenación de otros bienes, no consignada en escritura pública.
"10"	Adquisición de desperdicios industriales.
"11"	Adquisición de bienes consignada en escritura pública.
"12"	Adquisición de otros bienes, no consignada en escritura pública.
"13"	Otros retiros de AFORE.
"14"	Dividendos o utilidades distribuidas.
"15"	Remanente distribuible.
"16"	Intereses.
"17"	Arrendamiento en fideicomiso.
"18"	Pagos realizados a favor de residentes en el extranjero.
"19"	Enajenación de acciones u operaciones en bolsa de valores.
"20"	Obtención de premios.
"21"	Fideicomisos que no realizan actividades empresariales.
"22"	Planes personales de retiro.
"23"	Intereses reales deducibles por créditos hipotecarios.
"24"	Operaciones Financieras Derivadas de Capital.
"25"	Otro tipo de retenciones.
"26"	Servicios mediante Plataformas Tecnológicas

Validez de obligaciones

Validez	IVA Exento	Tasa 0%	Tasa 8% Fronteriza Norte	Tasa 8% Fronteriza Sur	Tasa 16%
"0"	El contribuyente no está autorizado para emitir facturas
"1"	Sí	Sí	No	No	Sí
"2"	Sí	Sí	Sí	No	Sí
"3"	Sí	Sí	No	Sí	Sí
"4"	Sí	Sí	Sí	Sí	Sí

Situación del contribuyente

Valor	Explicación
"Previsto"	Vía buzón tributario o notificaciones por estrados, el contribuyente recibe un oficio en el que se establece su situación y se le solicita que demuestre la materialidad de las operaciones facturadas.
"Presunto"	El contribuyente notificado se considera presunto cuando, en su página web, la autoridad emite sus datos dentro de la relación de los EFOS, es decir, en las listas negras del SAT.
"Desvirtuado"	En este caso, el contribuyente acusado de operaciones inexistentes ya aportó a la autoridad la documentación e información pertinente para desvirtuar los hechos que llevaron a notificarlo.
"Definitivo"	En este caso, el EFO no atendió el llamado de la autoridad en el plazo de 15 días, a partir de la última notificación; o bien, no pudo desvirtuar los hechos imputados.
"Sentencia favorable"	Los contribuyentes EFOS “definitivos” que se inconforman e interponen algún medio de defensa, el cual concluye a su favor, son clasificados en la lista de “sentencia favorable”.
"EFOS de información suprimida"	En esta categoría, se encuentran los EFOS “presuntos” y “definitivos” que presentaron algún medio de defensa (amparo, juicio de nulidad) y, por lo tanto, un juez ordenó suprimir sus datos de la lista, sin ser eliminados.

Clave Producto/Servicio

Busca en el catálogo Productos/Servicios del SAT, el cual contiene la clave a incluir en la factura.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

q	string Consulta. Texto a buscar en la descripción de la clasificación.
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/catalogs/products?q=ukelele \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
404
500

Content type

application/json

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

Unidades de medida

Busca en el catálogo de Unidades de Medida del SAT.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

q	string Consulta. Texto a buscar en la descripción de la unidad de medida.
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/catalogs/units?q=pulgada \
  -H "Authorization: Bearer sk_test_API_KEY"

Response samples

200
400
401
404
500

Content type

application/json

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

Eventos

Los eventos ocurren cuando Facturapi realiza una operación de manera asíncrona, es decir, fuera del ciclo de vida de una petición a la API.

Para recibir estos eventos en tu servidor, puedes registrar una URL de escucha creando un Webhook desde tu dashboard: https://dashboard.facturapi.io/integration/webhooks

Factura global creada Webhook

Notifica acerca de la creación de una factura global a partir de e-Receipts.

Request Body schema: application/json
required

id	string ID del evento
created_at	string <date-time> Fecha y hora de creación del evento
livemode	boolean Indica si el evento se generó en modo test (false) o en modo producción (true).
organization	string ID de la organización a la que pertenece el evento
type	string Value: "invoice.global_invoice_created" Tipo de evento
	object

Request samples

Payload

Content type

application/json

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

Estatus de factura actualizado Webhook

Notifica acerca del cambio del campo status de una factura.

Se utiliza en el caso de haber creado la factura de manera asíncrona.

Request Body schema: application/json
required

id	string ID del evento
created_at	string <date-time> Fecha y hora de creación del evento
livemode	boolean Indica si el evento se generó en modo test (false) o en modo producción (true).
organization	string ID de la organización a la que pertenece el evento
type	string Value: "invoice.status_updated" Tipo de evento
	object

Request samples

Payload

Content type

application/json

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

Estatus de cancelación actualizado Webhook

Notifica acerca de cambios en el campo cancellation_status de una factura.

Request Body schema: application/json
required

id	string ID del evento
created_at	string <date-time> Fecha y hora de creación del evento
livemode	boolean Indica si el evento se generó en modo test (false) o en modo producción (true).
organization	string ID de la organización a la que pertenece el evento
type	string Value: "invoice.cancellation_status_updated" Tipo de evento
	object

Request samples

Payload

Content type

application/json

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

Autofactura completada Webhook

Notifica acerca de la creación de una autofactura a partir de un e-Receipt.

Request Body schema: application/json
required

id	string ID del evento
created_at	string <date-time> Fecha y hora de creación del evento
livemode	boolean Indica si el evento se generó en modo test (false) o en modo producción (true).
organization	string ID de la organización a la que pertenece el evento
type	string Value: "receipt.self_invoice_complete" Tipo de evento
	object

Request samples

Payload

Content type

application/json

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

Estatus de recibo actualizado Webhook

Notifica acerca de cambios en el campo status de un recibo.

Request Body schema: application/json
required

id	string ID del evento
created_at	string <date-time> Fecha y hora de creación del evento
livemode	boolean Indica si el evento se generó en modo test (false) o en modo producción (true).
organization	string ID de la organización a la que pertenece el evento
type	string Value: "receipt.status_updated" Tipo de evento
	object

Request samples

Payload

Content type

application/json

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

Webhooks

Crear Webhook

Registra un nuevo webhook en tu organización de Facturapi. Utiliza esta llamada para recibir notificaciones de eventos asíncronos a la API. Los webhooks de ambiente test y ambiente live son independientes.

Authorizations:

SecretLiveKeySecretTestKey

Request Body schema: application/json
required

enabled_events required	Array of strings Items Enum: "invoice.global_invoice_created" "invoice.status_updated" "invoice.cancellation_status_updated" "receipt.self_invoice_complete" "receipt.status_updated" "receipt.cancellation_status_updated" Los eventos a los que el webhook se suscribirá.
url required	string URL del webhook a dar de alta para recibir notificaciones.

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"url": "http://my-webstite.com/my/webhook",
"enabled_events": {"0": "receipt.self_invoice_complete"
}
}

Response samples

Content type

application/json

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

Listar webhooks

Retorna una lista de webhooks creados previamente para la organización.

Authorizations:

SecretLiveKeySecretTestKey

query Parameters

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/webhooks \
  -H "Authorization: Bearer sk_test_API_KEY" \
  -G \
  -d 'page=1'

Response samples

200
400
401
404
500

Content type

application/json

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

Obtener webhook por ID

Regresa el objeto "Webhook" relacionado al id especificado.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

webhook_id

required

string

ID del objeto a obtener

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

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

Editar webhook

Actualiza la información de un Webhook existente con los parámetros que envíes en la petición.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

webhook_id

required

string

ID del objeto a editar

Request Body schema: application/json
required

enabled_events required	Array of strings Items Enum: "invoice.global_invoice_created" "invoice.status_updated" "invoice.cancellation_status_updated" "receipt.self_invoice_complete" "receipt.cancellation_status_updated" "receipt.status_updated" Los eventos a los que el webhook se suscribirá.
status	string Enum: "disabled" "enabled" Estatus del webhook

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

{"status": "disabled",
"enabled_events": {"0": "receipt.self_invoice_complete"
}
}

Response samples

200
400
401
500

Content type

application/json

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

Eliminar Webhook

Elimina el webhook pertenciente a la organización.

Authorizations:

SecretLiveKeySecretTestKey

path Parameters

webhook_id

required

string

ID del objeto a eliminar

Responses

Request samples

cURL
Node.js
C#
PHP

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

Response samples

200
400
401
500

Content type

application/json

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

Validar evento de webhook

Valida la firma de un evento recibido mediante un Webhook. Utiliza esta operación para verificar la autenticidad e integridad de un evento recibido, comparando la firma recibida con la generada por Facturapi.

Authorizations:

SecretLiveKeySecretTestKey

Request Body schema: application/json

secret	string Llave secreta del webhook. Se obtiene al crear un webhook o desde el dashboard de Facturapi.
payload	object Objeto ApiEvent recibido mediante el webhook
signature	string Firma del webhook recibida en el header `Facturapi-Signature`

Responses

Request samples

Payload
cURL
Node.js
C#
PHP

Content type

application/json

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

Response samples

200
400
401
404
500

Content type

application/json

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

Objeto Customer

id required	string ID del objeto
created_at required	string <date-time> Fecha de registro
livemode required	boolean Si el valor es `true`, indica que el objeto fue creado en ambiente Live; o si es `false`, en ambiente Test.
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.
default_invoice_use	string Uso de CFDI por defecto.
	object Domicilio fiscal.

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

Objeto Product

id required	string ID del objeto
created_at required	string <date-time> Fecha de registro
livemode required	boolean Si el valor es `true`, indica que el objeto fue creado en ambiente Live; o si es `false`, en ambiente Test.
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" "06" "07" "08" Código que representa si el bien o servicio es objeto de impuesto o no. Este atributo corresponde al campo "ObjetoImp" en el CFDI. `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. `06`: Sí objeto de impuesto, no IVA trasladado. `07`: No traslado de IVA, pero desglose de IEPS. `08`: No traslado de IVA sin desglose de IEPS.
	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.

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

Objeto Invoice

id required	string ID del objeto
created_at required	string <date-time> Fecha de registro
livemode required	boolean Si el valor es `true`, indica que el objeto fue creado en ambiente Live; o si es `false`, en ambiente Test.
status	string Enum: "pending" "valid" "canceled" "draft" Estado actual de la factura.
cancellation_status	string Enum: "none" "pending" "accepted" "rejected" "expired" Estado actual de la solicitud de cancelación, en caso de haberla realizado. Puedes leer más a detalle en la sección de Cancelar Factura).
verification_url	string <uri> Dirección URL para verificar el estado del CFDI en el portal del SAT. Este link es el mismo que aparece en el código QR, en el PDF de la factura.
date	string <date-time> Default: "now" Fecha de expedición del comprobante en formato ISO8601 (UTC String).
	object Domicilio de expedición de la factura.
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.
	object (CuustomerInfo) Objeto con información parcial del cliente receptor del comprobante. Para obtener el objeto `Customer` completo, deberás consultarlo con el método de Obtener Cliente.
total	number Monto total facturado.
uuid	string <uuid> Folio fiscal de la factura, asignado por el SAT.
folio_number	integer Número de folio autoincremental para control interno y sin validez fiscal.
series	string Serie. Caracteres designados por la empresa para control interno y sin validez fiscal. En el PDF se imprime junto al número de folio.
external_id	string Identificador que puedes usar para relacionar esta factura con tus registros para después buscar por este número.
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.
payment_form	string Código que representa la forma de pago, de acuerdo al catálogo del SAT.
is_ready_to_stamp	boolean Este campo es asignado automáticamente por Facturapi. Indica si una factura con status `draft` está completa y lista para intentar timbrarse. Si el valor es `true`, puedes intentar timbrar la factura con el método Timbrar Factura. Si el valor es `false`, debes usar el método Actualizar Factura para completar los campos faltantes. En una factura con status diferente a `draft`, este campo siempre será `false`.
	Array of objects (LineItem) Conceptos incluidos en el comprobante
	Array of objects (RelatedDocument) Documentos relacionados con la factura.
received_payment_ids	Array of strings Default: [] En facturas con tipo I (Ingreso) y método de pago PPD, este campo lista los IDs de los comprobantes de pago cuyo arreglo de documentos relacionados incluye el UUID de esta factura. Este campo es llenado por Facturapi en el momento en que se crea o importa el comprobante de pago (tipo P), siempre y cuando pertenezca a la misma organización.
target_invoice_ids	Array of strings Default: [] En facturas con tipo P (Pago), este arreglo lista los IDs de los comprobantes de ingreso listados en el arreglo de documentos relacionados. Este campo es llenado por Facturapi siempre y cuando el comprobante relacionado también esté registrado en Facturapi y pertenezca a la misma organización.
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`.
	Array of objects (Complement) Default: [] Complementos a incluir en la factura.
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`.
	object (Stamp) Información sobre el timbre fiscal digital agregado por el PAC.

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

Objeto Receipt

id required	string ID del objeto
created_at required	string <date-time> Fecha de registro
livemode required	boolean Si el valor es `true`, indica que el objeto fue creado en ambiente Live; o si es `false`, en ambiente Test.
date	string <date-time> Fecha de emisión del recibo.
expires_at	string <date-time> Fecha de expiración en formato ISO8601 (UTC String). Es la fecha límite para que el cliente pueda facturar su recibo en el portal de autofactura. Se calcula automáticamente a partir de las configuraciones de recibo de la organización.
status	string Enum: "open" "canceled" "invoiced_to_customer" "invoiced_globally" Estado actual del recibo.
self_invoice_url	string <url> Dirección URL para realizar autofactura. Incluye el `key` del recibo. Puedes usarla para generar un botón o un QR de facturación para tus clientes.
total	number Monto total de la operación
invoice	string ID de la factura asociada, en caso de estar facturado.
key	string Autogenerado. Identificador único alfanumérico corto, útil para acceder a la autofactura desde tu micrositio en factura.space
	Array of objects (LineItem) Conceptos incluidos en el recibo
external_id	string or null Identificador que puedes usar para relacionar este recibo con tus registros para después buscar por este número.
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.
payment_form	string Código que representa la forma de pago, según el catálogo del SAT.
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.

{"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": {"0": {"type": "IVA",
"rate": 0.16
}
},
"local_taxes": { },
"unit_key": "H87",
"unit_name": "Elemento",
"sku": "string"
},
"parts": {"description": "string",
"product_key": "string",
"quantity": 1,
"sku": "string",
"unit_price": 0,
"unit_name": "string",
"customs_keys": ["string"
]
}
}
],
"external_id": "string",
"idempotency_key": "string",
"payment_form": "03",
"folio_number": 120,
"currency": "MXN",
"exchange": 1,
"branch": "string"
}

Objeto Retention

id required	string ID del objeto
created_at required	string <date-time> Fecha de registro
livemode required	boolean Si el valor es `true`, indica que el objeto fue creado en ambiente Live; o si es `false`, en ambiente Test.
status	string Enum: "valid" "canceled" Estado actual de la retención.
verification_url	string <uri> Dirección URL para verificar el estado de la retención en el portal del SAT. Este link es el mismo que aparece en el código QR, en el PDF de la retención.
type	string Value: "Retención" Tipo de comprobante.
uuid	string <uuid> Folio fiscal de la retención, asignado por el SAT.
	object (Stamp) Información sobre el timbre fiscal digital agregado por el PAC.
	object (CuustomerInfo) Objeto con información parcial del cliente receptor del comprobante. Para obtener el objeto `Customer` completo, deberás consultarlo con el método de Obtener Cliente.
cve_retenc	string Clave de la retención o información de pagos de acuerdo al catálogo del SAT.
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.
	object Información sobre el periodo de la retención.
	object Información sobre el total de retenciones efectuadas en el periodo correspondiente.
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 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.
complements	Array of strings <xml> (string) [ items <xml > ] Default: [] Arreglo de complementos a incluir en la factura. Cada elemento contiene un `string` con el código XML del complemento.
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`.

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

Objeto Organización

id	string ID del objeto
created_at	string <date-time> Fecha de registro
is_production_ready	boolean Indica si la organización tiene información necesaria para facturar en ambiente Live.
	Array of objects Lista de pasos que se necesitan completar para que esta organización pueda emitir facturas válidas en ambiente Live.
	object Datos fiscales de la empresa.
	object Configuración de personalización de la organización, que se utilizarán para reflejar el branding y las preferencias de PDFs de la organización. Estos datos se pueden actualizar en cualquier momento.
	object Información últil sobre el certificado de sello digital (CSD) de la organización, que se utilizará para firmar las facturas.

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

Facturapi (2.0)

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