# Get api lite4cfdis
Source: https://facturama.mintlify.app/api-reference/endpoint/api-lite/get-api-lite4cfdis
api-reference/openapi.json get /api-lite/4/cfdis/{cfdiId}
# Get api lite4cfdisxml
Source: https://facturama.mintlify.app/api-reference/endpoint/api-lite/get-api-lite4cfdisxml
api-reference/openapi.json get /api-lite/4/cfdis/xml/{cfdiId}
# Post api lite4cfdis
Source: https://facturama.mintlify.app/api-reference/endpoint/api-lite/post-api-lite4cfdis
api-reference/openapi.json post /api-lite/4/cfdis
# Catalogo de bancos
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/catalogo-de-bancos
api-reference/openapi.json get /catalogs/Banks
# Catalogo de las formas de pago
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/catalogo-de-las-formas-de-pago
api-reference/openapi.json get /Catalogs/PaymentForms
# Catalogo de los nombres que pueden establecer en el PDF (default 1 = factura)
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/catalogo-de-los-nombres-que-pueden-establecer-en-el-pdf-default-1-=-factura
api-reference/openapi.json get /Catalogs/NameIds
# Catalogo de metodos de pago
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/catalogo-de-metodos-de-pago
api-reference/openapi.json get /Catalogs/PaymentMethods
# Catalogo de monedas
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/catalogo-de-monedas
api-reference/openapi.json get /Catalogs/Currencies
# Catalogo de monedas
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/catalogo-de-monedas-1
api-reference/openapi.json get /Catalogs/Countries
# Catalogo de Regimenes Fiscales
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/catalogo-de-regimenes-fiscales
api-reference/openapi.json get /Catalogs/FiscalRegimens
# Catalogo de Tipos de Cfdi.
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/catalogo-de-tipos-de-cfdi
api-reference/openapi.json get /Catalogs/CfdiTypes
# Catalogo de Tipos de Relación
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/catalogo-de-tipos-de-relación
api-reference/openapi.json get /Catalogs/RelationTypes
# Catalogo de unidades.
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/catalogo-de-unidades
api-reference/openapi.json get /Catalogs/Units
# Catalogo de Usos de Cfdi, algunos usos aplican solo para personas Físicas y otros solo para Morales
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/catalogo-de-usos-de-cfdi-algunos-usos-aplican-solo-para-personas-físicas-y-otros-solo-para-morales
api-reference/openapi.json get /Catalogs/CfdiUses
# obtiene el catalogos de carta porte c_ClaveUnidadPeso
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/obtiene-el-catalogos-de-carta-porte-c_claveunidadpeso
api-reference/openapi.json get /catalogs/cartaporte/ClaveUnidadPeso
# obtiene el catalogos de carta porte c_MaterialPeligroso
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/obtiene-el-catalogos-de-carta-porte-c_materialpeligroso
api-reference/openapi.json get /catalogs/cartaporte/MaterialPeligroso
# obtiene el catalogos de carta porte c_TipoEmbalaje
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/obtiene-el-catalogos-de-carta-porte-c_tipoembalaje
api-reference/openapi.json get /catalogs/cartaporte/TipoEmbalaje
# Obtiene los codigos de productos y servicios.
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/obtiene-los-codigos-de-productos-y-servicios
api-reference/openapi.json get /Catalogs/ProductsOrServices
# Obtiene los codigos postales.
Source: https://facturama.mintlify.app/api-reference/endpoint/catálogos-sat/obtiene-los-codigos-postales
api-reference/openapi.json get /Catalogs/PostalCodes
# Obtiene el catálogo de productos y servicios paginado
(versión octubre de 2020, sucesión del original /product)
Source: https://facturama.mintlify.app/api-reference/endpoint/clientes/obtiene-el-catálogo-de-productos-y-servicios-paginadoversión-octubre-de-2020-sucesión-del-original-product
api-reference/openapi.json get /customers
# Obtiene el catálogo de productos y servicios paginado
(versión octubre de 2020, sucesión del original /product)
Source: https://facturama.mintlify.app/api-reference/endpoint/clientes/obtiene-el-catálogo-de-productos-y-servicios-paginadoversión-octubre-de-2020-sucesión-del-original-product-1
api-reference/openapi.json get /clients
# Cancela un CFDI (Version 2018 - Actualizado para 2022 con Motivo de cancelación)
En el caso de que se requiera autorizacion, realiza la petición
Source: https://facturama.mintlify.app/api-reference/endpoint/factura-cfdi/cancela-un-cfdi-version-2018--actualizado-para-2022-con-motivo-de-cancelaciónen-el-caso-de-que-se-requiera-autorizacion-realiza-la-petición
api-reference/openapi.json delete /cfdi/{id}
# Crea un cfdi de emision.
Source: https://facturama.mintlify.app/api-reference/endpoint/factura-cfdi/crea-un-cfdi-de-emision
api-reference/openapi.json post /3/cfdis
# Devuelve los pagos asociados a una factura con pago por definir
Source: https://facturama.mintlify.app/api-reference/endpoint/factura-cfdi/devuelve-los-pagos-asociados-a-una-factura-con-pago-por-definir
api-reference/openapi.json get /cfdi/status
# Obtiene el acuse de un cfdi
Source: https://facturama.mintlify.app/api-reference/endpoint/factura-cfdi/obtiene-el-acuse-de-un-cfdi
api-reference/openapi.json get /acuse/{format}/{type}/{id}
# Obtiene el archivo de la factura en una sucesión de caracteres base64 en el formato deseado.
Source: https://facturama.mintlify.app/api-reference/endpoint/factura-cfdi/obtiene-el-archivo-de-la-factura-en-una-sucesión-de-caracteres-base64-en-el-formato-deseado
api-reference/openapi.json get /cfdi/{format}/{type}/{id}
# Obtiene el detalle del CFDi con el id y tipo seleccionado
Source: https://facturama.mintlify.app/api-reference/endpoint/factura-cfdi/obtiene-el-detalle-del-cfdi-con-el-id-y-tipo-seleccionado
api-reference/openapi.json get /cfdi/{id}
# Cargar Logo
Source: https://facturama.mintlify.app/api-reference/endpoint/mi-cuenta/cargar-logo
api-reference/openapi.json put /TaxEntity/UploadLogo
# Crea un nueva Serie
Source: https://facturama.mintlify.app/api-reference/endpoint/mi-cuenta/crea-un-nueva-serie
api-reference/openapi.json post /serie/{idBranchOffice}
# Elimina la Serie
Source: https://facturama.mintlify.app/api-reference/endpoint/mi-cuenta/elimina-la-serie
api-reference/openapi.json delete /serie/{idBranchOffice}/{name}
# Obtiene todos las Series asociados a la Sucursal
Source: https://facturama.mintlify.app/api-reference/endpoint/mi-cuenta/obtiene-todos-las-series-asociados-a-la-sucursal
api-reference/openapi.json get /serie/{idBranchOffice}
# Sube la FIEL al servidor de facturama
Source: https://facturama.mintlify.app/api-reference/endpoint/mi-cuenta/sube-la-fiel-al-servidor-de-facturama
api-reference/openapi.json put /TaxEntity/UploadFiel
# Sube los CSD al servidor de facturama
Source: https://facturama.mintlify.app/api-reference/endpoint/mi-cuenta/sube-los-csd-al-servidor-de-facturama
api-reference/openapi.json put /TaxEntity/UploadCsd
# Obtiene el catálogo de productos y servicios paginado
(versión octubre de 2020, sucesón del original /product).
Source: https://facturama.mintlify.app/api-reference/endpoint/productos-o-servicios/obtiene-el-catálogo-de-productos-y-servicios-paginadoversión-octubre-de-2020-sucesón-del-original-product
api-reference/openapi.json get /products
# Crea un CFDi de retención
Source: https://facturama.mintlify.app/api-reference/endpoint/retenciones/crea-un-cfdi-de-retención
api-reference/openapi.json post /2/retenciones
# Descarga la Retencion en xml, pdf o html
Source: https://facturama.mintlify.app/api-reference/endpoint/retenciones/descarga-la-retencion-en-xml-pdf-o-html
api-reference/openapi.json get /retenciones/{id}/{format}
# Cancelar CFDI
Source: https://facturama.mintlify.app/es/api-lite/cancelar-cfdi
Cancela CFDIs emitidos indicando el motivo correcto. Entiende el flujo de aceptación y los estados de cancelación.
## Motivos de cancelación (CFDI 4.0)
Desde 2022, toda cancelación requiere un motivo:
| Clave | Motivo | Cuándo usar |
| ----- | -------------------------------------------------- | ------------------------------------------ |
| `01` | Comprobante emitido con errores **con** relación | Hay un CFDI sustituto que corrige el error |
| `02` | Comprobante emitido con errores **sin** relación | No se emitirá sustituto |
| `03` | No se llevó a cabo la operación | La venta o servicio no se realizó |
| `04` | Operación nominativa relacionada en factura global | Para CFDIs incluidos en factura global |
## Cancelar un CFDI
```http theme={null}
DELETE /api-lite/cfdis/{Id}?motive={motive}&uuidReplacement={uuidReplacement}
```
Identificador del documento a cancelar. Lo encontrarás en el campo "Id" en la respuesta de emisión de la factura o al consultar las facturas emitidas.
Motivo de cancelación, explicados en la tabla anterior (01, 02, 03, 04).
UUID del comprobante que sustituye al cancelado (solamente requerido para el motivo de cancelación «01 - Comprobante emitido con errores con relación»).
Utilizar el campo **uuidReplacement** cuando este no es requerido puede causar errores o evitar que la factura no sea cancelada, incluso si se asigna un valor nulo o vacío.
Para sandbox, solamente se pueden cancelar las facturas que utilicen el RFC de **EKU9003173C9** como emisor.
**Ejemplo — Motivo 02 (sin sustituto):**
```bash theme={null}
curl --request DELETE \
--url 'https://apisandbox.facturama.mx/api-lite/cfdis/_l0qPog2qSpryRUq1qfCrg2?motive=02' \
--header 'Authorization: Basic BASE64_CREDENCIALES'
```
**Ejemplo — Motivo 01 (con CFDI sustituto):**
```bash theme={null}
curl --request DELETE \
--url 'https://apisandbox.facturama.mx/api-lite/cfdis/_l0qPog2qSpryRUq1qfCrg2?motive=01&uuidReplacement=5e09160f-a206-44d7-b389-4f243585e76a' \
--header 'Authorization: Basic BASE64_CREDENCIALES'
```
## Respuesta a una solicitud de cancelación
```json theme={null}
{
"Status": "canceled",
"Message": "Cancelado: Cancelado sin aceptación",
"IsCancelable": "Cancelable sin aceptacion",
"Uuid": "026826D4-CED0-4A3F-B6A3-890B20BD587B",
"RequestDate": "2025-04-29T10:05:17",
"ExpirationDate": "2025-05-06T10:05:17",
"AcuseXmlBase64": "PD94bWwgdmVyc2lv.....",
"CancelationDate": "2025-04-29T10:05:17",
"AcuseStatus": 201,
"AcuseStatusDetails": "Solicitud de cancelación recibida."
}
```
* `Status` Estado de la cancelación
* `canceled` Cancelada
* `active` No se puede cancelar, tiene documentos relacionados
* `pending` Pendiente de aceptación por parte del receptor
* `Message` Detalle del status de cancelación.
* `IsCancelable` Indica si la factura es cancelable y bajo qué condiciones, o si no es cancelable.
* `Cancelable sin aceptación`
* `Cancelable con aceptación`
* `No cancelable`
* `Uuid` UUID del CFDI por cancelar
* `RequestDate` Fecha de solicitud de cancelación
* `ResponseDate` Fecha de respuesta del SAT
* `ExpirationDate` Fecha límite en que el receptor puede emitir una respuesta
* `AcuseXmlBase64` XML del acuse en formato Base64
* `AcuseStatus` Código del status de la cancelación
* `AcuseStatusDetails` Descripción del `AcuseStatus` de la cancelación
## Flujo de cancelación
Dependiendo del monto y el receptor, la cancelación puede requerir aceptación:
```
Solicitud de cancelación
↓
¿Requiere aceptación del receptor?
↙ ↘
No Sí
↓ ↓
Cancelado Pendiente (72 hrs)
↙ ↘
Aceptada Rechazada
```
**Cancelación inmediata (sin aceptación):**
* CFDIs emitidos mismo día dentro de los primeros 3 días
* Montos menores a \$1,000 MXN
* CFDIs de nómina y traslado
**Requieren aceptación del receptor:**
* CFDIs de montos mayores o con más de 3 días de emitidos
## Consultar estado de un CFDI
```http theme={null}
GET /api-lite/cfdis/{Id}
```
Identificador único del CFDI.
El campo `Status` en la respuesta indica el estado actual dentro de Facturama:
| Estado | Descripción |
| -------- | ---------------------- |
| `active` | CFDI vigente |
| `cancel` | Cancelado exitosamente |
## Obtener acuse de cancelación
Después de una cancelación exitosa:
```http theme={null}
GET /acuse/{format}/issuedLite/{Id}
```
Formato del archivo a obtener (pdf|html).
Identificador único del CFDI.
Devuelve el acuse de cancelación emitido por el SAT en Base64.
En el sandbox, las cancelaciones son inmediatas y no requieren aceptación del receptor.
# Cargar CSDs
Source: https://facturama.mintlify.app/es/api-lite/cargar-csds
Los Certificados de Sello Digital (CSD) son archivos emitidos por el SAT que permiten firmar digitalmente los CFDI y validar la identidad fiscal del emisor.
En API Multiemisor, cada RFC que emita facturas debe tener sus propios certificados registrados previamente.
Sin un CSD válido, no será posible emitir CFDI desde la API.
Consideraciones importantes:
* Cada RFC requiere un conjunto independiente de certificados.
* Los CSD registrados en API Multiemisor son independientes de los configurados en la plataforma web de Facturama.
* La administración de CSD en API Multiemisor se realiza exclusivamente mediante peticiones HTTP.
* En el ambiente Sandbox puedes utilizar los certificados de prueba proporcionados por el SAT. Consulta estos certificados en la sección [Certificados de prueba](/es/catalogos/csds-pruebas).
Flujo de administración de CSD
Registrar CSD -> Emitir CFDI -> Actualizar CSD (si expira o cambia) -> Eliminar CSD (opcional)
### Registrar un CSD
Registra por primera vez los certificados asociados a un RFC.
```http Endpoint theme={null}
POST /api-lite/csds
```
```json Body theme={null}
{
"Rfc": "EKU9003173C9",
"Certificate": "MIIFuzCCA6OgAwIBAgIUMzAwMDEwM...",
"PrivateKey": "MIIFDjBABgkqhkiG9w0BBQ0wMzAb...",
"PrivateKeyPassword": "12345678a"
}
```
| Campo | Descripción |
| ------------------ | -------------------------------------- |
| Rfc | RFC al que pertenecen los certificados |
| Certificate | Archivo .cer convertido a Base64 |
| PrivateKey | Archivo .key convertido a Base64 |
| PrivateKeyPassword | Contraseña del certificado |
Un código de respuesta 200 OK indica que los certificados fueron registrados
correctamente y ya pueden utilizarse para emitir CFDI
### Actualizar un CSD
Actualiza los certificados previamente registrados para un RFC.
Utiliza esta operación cuando:
* El certificado haya expirado.
* El certificado haya sido renovado.
* La contraseña del certificado haya cambiado.
```http Endpoint theme={null}
PUT /api-lite/csds/{rfc}
```
La estructura es idéntica a la utilizada para registrar un CSD.
```json Body theme={null}
{
"Rfc": "EKU9003173C9",
"Certificate": "MIIFuzCCA6OgAwIBAgIUMzAwMDEwM...",
"PrivateKey": "MIIFDjBABgkqhkiG9w0BBQ0wMzAb...",
"PrivateKeyPassword": "12345678a"
}
```
### Listar CSDs
Lista de los CSDs cargados.
```http endpoint theme={null}
GET /api-lite/csds
```
```json Respuesta theme={null}
[
{
"Rfc": "ZUÑ920208KL4",
"Certificate": "MIIFsDCCA5igAwIBAgIUMzAwMDEwMDAwMD",
"PrivateKey": "MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhki",
"PrivateKeyPassword": "12345678a",
"CsdExpirationDate": "2027-01-18T14:12:06",
"UploadDate": "2023-06-30T17:49:50.533"
},
{
"Rfc": "JUFA7608212V6",
"Certificate": "",
"PrivateKey": "",
"PrivateKeyPassword": "",
"CsdExpirationDate": "",
"UploadDate": ""
}
.
.
.
{},
]
```
### Obtener CSD a partir del RFC
Buscar los CSDs de un RFC en especifico
```http theme={null}
GET /api-lite/csds/{rfc}
```
### Eliminar un CSD
Elimina los certificados asociados a un RFC.
```http Endpoint theme={null}
DELETE /api-lite/csds/{rfc}
```
# Consultar CFDI
Source: https://facturama.mintlify.app/es/api-lite/consultar-cfdi
Consulta y filtra los CFDI emitidos con la API Multiemisor mediante paginación y palabras clave.
API Multiemisor permite realizar una búsqueda aplicando filtros para las facturas que se han emitido desde tu cuenta.
## Endpoint
```http theme={null}
GET /cfdi?type=issuedLite&page={page}
```
Corresponde al tipo de CFDI que se está intentando consultar. Al ser API Multiemisor, el único valor disponible es:
**`issuedLite`**, para las facturas de **ingreso, egreso, nómina y complementos**.
Este endpoint solo mostrará los documentos emitidos en API Multiemisor.
## Cantidad de resultados obtenidos
El endpoint realiza una búsqueda paginada, por lo que cada llamada realizada al endpoint regresará una página con solamente 10 resultados. Para poder navegar entre páginas para visualizar los diferentes resultados, se debe hacer uso del parámetro `page`.
```http theme={null}
GET /cfdi?type=issuedLite&page=0
```
Número entero que identifica la página de resultados a consultar.
**Donde:**
* `page`=0 = Representa los primeros 10 elementos (del 1 al 10).
* `page`=1 = Representa los segundos 10 elementos (del 11 al 20).
## Otros filtros para la búsqueda
### Estado de la factura
```http theme={null}
GET /cfdi?type=issuedLite&page=0&status={status}
```
Permite indicar el status de las facturas que se desea consultar.
**Los valores disponibles:**
* `all`: Representa todas las facturas disponibles independientemente de su status actual (activas, pendientes, canceladas).
* `active`: Representa todas las facturas que se encuentran activas/vigentes.
* `canceled`: Representa todas las facturas canceladas.
### Folio de la factura
```http theme={null}
GET /cfdi?type=issuedLite&page=0&folio={folio}
```
Permite indicar el folio exacto que se desea consultar. La respuesta mostrará todas las facturas que tengan el valor especificado.
### Rango de folios de la factura
```http theme={null}
GET /cfdi?type=issuedLite&page=0&folioStart={folioStart}&folioEnd={folioEnd}
```
Parámetro para indicar el número de folio desde el cual se comenzarán a mostrar las facturas.
Parámetro para indicar el número de folio hasta el cual se mostrarán las facturas.
Combinar el parámetro `folio` con `folioStart` y `folioEnd` en la misma búsqueda puede generar respuestas erróneas del contenido filtrado.
### Rango de fechas de emisión
```http theme={null}
GET /cfdi?type=issuedLite&page=0&dateStart={dateStart}&dateEnd={dateEnd}
```
Parámetro para indicar la fecha y hora de inicio desde la cual se comenzarán a mostrar las facturas, especificado en formato `aaaa-mm-ddThh:mm:ss`.
Parámetro para indicar la fecha y hora de finalización hasta la cual se mostrarán las facturas, especificado en formato `aaaa-mm-ddThh:mm:ss`.
### RFC emisor
```http theme={null}
GET /cfdi?type=issuedLite&page=0&rfcIssuer={rfcIssuer}
```
Parámetro para indicar el RFC del emisor de la factura. Puede indicarse completo o solo una parte del mismo.
### Nombre / Razón Social del receptor
```http theme={null}
GET /cfdi?type=issuedLite&page=0&taxEntityName={taxEntityName}
```
Parámetro para indicar el nombre o razón social del receptor de la factura. Puede indicarse completo o solo una parte del mismo.
### Endpoint completo
```http theme={null}
GET /cfdi?type=issuedLite&folioStart=100&folioEnd=200&rfcIssuer=EKU9003173C9&rfc=XAXX&taxEntityName=Publico&dateStart=2026-06-17&dateEnd=2026-06-17&status=active&page=0
```
# Crear CFDI
Source: https://facturama.mintlify.app/es/api-lite/crear-cfdi
Emite facturas electrónicas de ingreso, egreso, traslado y pago usando diferentes RFCs emisores
## Emisión de CFDI en API Multiemisor
La API Multiemisor permite emitir CFDI utilizando diferentes RFC emisores desde una misma integración.
Para emitir comprobantes con un RFC determinado, es necesario que dicho emisor tenga previamente registrados sus Certificados de Sello Digital (CSD).
> Cada RFC emisor debe contar con sus propios CSD registrados antes de poder generar CFDI.
>
> Consulta la guía de administración de CSD: [Administración de CSD](/es/api-lite/cargar-csds)
## Endpoint V4 Nuevo
```http theme={null}
POST /api-lite/4/cfdis
```
## Datos Generales
```json theme={null}
{
"NameId": "1",
"Currency": "MXN",
"Folio": "100",
"Serie": "FA",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2024-02-20T12:00:00",
"PaymentConditions": "CREDITO A SIETE DÍAS",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "01",
"LogoUrl": "http:tu_dominio.com/imagen.jpg"
}
```
[Idempotencia y reintentos](/es/cfdi40/idempotencia)
Facturama identifica una operación por la combinación de `Folio` y `Date`. Para
evitar comprobantes duplicados, ambos valores deben generarse una sola vez al
iniciar la operación y reutilizarse sin cambios en cada reintento.
Identificador único de la operación, generado por tu sistema.
Fecha y hora de inicio de la operación, en formato `YYYY-MM-DDTHH:mm:ss`.
No regeneres `Folio` ni `Date` en los reintentos, y no uses la fecha/hora
actual del sistema para recalcular `Date`. Cualquier cambio en estos valores
hará que Facturama trate el reintento como una operación nueva.
Por ejemplo, una operación con:
```json theme={null}
{
"Folio": 100,
"Date": "2026-05-15T22:17:44"
}
```
Conserva estos mismos valores en cada reintento, sin importar cuánto tiempo
haya pasado desde la solicitud original.
### Nodo `Issuer`
Se debe incluir el nodo `Issuer`, que identifica al RFC que emitirá el comprobante.
```json theme={null}
{
"Issuer": {
"Rfc": "EKU9003173C9",
"Name": "ESCUELA KEMPER URGATE",
"FiscalRegime": "601"
}
}
```
### Nodo `Receiver`
Se debe incluir el nodo `Receiver`, que identifica al RFC receptor del comprobante.
```json theme={null}
{
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "G01",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991"
}
}
```
### Conceptos
```json theme={null}
"Items":[
{
"ProductCode": "10101504",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes":[
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}],
"Total": 116
}]
```
### Forma Completa
```json theme={null}
{
"NameId": "1",
"Currency": "MXN",
"Folio": "100",
"Serie": "FA",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2024-02-20T12:00:00",
"PaymentConditions": "CREDITO A SIETE DIAS",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "01",
"LogoUrl": "http:tu_dominio.com/imagen.jpg",
"Issuer": {
"Rfc": "EKU9003173C9",
"Name": "ESCUELA KEMPER URGATE",
"FiscalRegime": "601"
},
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "G01",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991"
},
"Items": [
{
"ProductCode": "10101504",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 116
},
{
"ProductCode": "10101504",
"IdentificationNumber": "001",
"Description": "SERVICIO DE COLOCACION",
"Unit": "NO APLICA",
"UnitCode": "E49",
"UnitPrice": 100.0,
"Quantity": 15.0,
"Subtotal": 1500.0,
"Discount": 0.0,
"TaxObject": "02",
"Taxes": [
{
"Total": 240.0,
"Name": "IVA",
"Base": 1500.0,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 1740.0
}
]
}
```
## Referencia de API
Para consultar la definición completa de los campos disponibles, parámetros y ejemplos de respuesta, consulta la documentación de referencia:
* [Referencia de API - Crear CFDI Multiemisor](/api-reference/endpoint/api-lite/post-api-lite4cfdis)
## Información adicional para la representación impresa
Además de los datos fiscales requeridos por el SAT, es posible incluir información complementaria para personalizar la representación impresa del CFDI.
Entre los campos opcionales disponibles se encuentran:
* Logo del emisor.
* Dirección del emisor.
* Dirección del receptor.
* Observaciones o notas adicionales.
Estos campos no forman parte de la información fiscal del comprobante, pero pueden utilizarse para enriquecer la versión PDF o impresa.
```json theme={null}
{
"Observations": "Elemento Observaciones solo visible en PDF",
"LogoUrl": "http:tu_dominio.com/imagen.jpg",
"Issuer": {
"Rfc": "EKU9003173C9",
"Name": "ESCUELA KEMPER URGATE",
"FiscalRegime": "601",
"Address": {
"Street": "Calle de prueba",
"ExteriorNumber": "51",
"InteriorNumber": null,
"Neighborhood": "Colonia de prueba",
"ZipCode": "78000",
"Locality": "",
"Municipality": "",
"State": "San Luis Potosí",
"Country": "México"
}
},
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "G01",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991",
"Address": {
"Street": "Calle de prueba",
"ExteriorNumber": "51",
"InteriorNumber": null,
"Neighborhood": "Colonia de prueba",
"ZipCode": "86991",
"Locality": "",
"Municipality": "",
"State": "TABASCO",
"Country": "México"
}
}
}
```
Para la versión 4 de la API multiemisor, el JSON regresa el XML de la factura en la respuesta de la petición.
```json Respuesta theme={null}
{
"Id": "7I-r4pU5j2EuMFz0FFTERA2",
"XmlBase64": "PD94bWwgdmVyc2lvbj0iMS4wIiB......",
"OriginalString": "||4.0|FA|100|2026-06-24T09:59:48|03|......",
"TaxStamp": {
"Version": "1.1",
"Uuid": "b9bb9c00-65aa-4413-b524-d8b7b29e215a",
"Date": "2026-06-24T09:59:48",
"CfdiSign": "my6dG5gmjQ3Tsb+acPTWDmShjFQaOKITfP.....",
"SatCertNumber": "30001000000500003456",
"SatSign": "C1aEGGdDaYfiK9DQHz5t2FKQZ1JpFA...",
"RfcProvCertif": "SPR190613I52",
"TaxStampOriginalString": "||1.1|b9bb9c00-65aa-4413...."
}
}
```
**Donde**
* `Id` : Identificador único de la factura
* `XmlBase64`: Contenido del XML en base64
* `OriginalString` : Cadena Original
* `TaxStamp.Uuid` : Identificador único de la factura ante el SAT
## Endpoint V3
```http theme={null}
POST /api-lite/3/cfdis
```
Para la versión 3 de la API multiemisor, el JSON regresa un resumen general de la factura.
## Respuesta exitosa
```json theme={null}
{
"Id": "DznlumtVtkA3ya4JXAeGWw2",
"CfdiType": "ingreso",
"Type": "I - ingreso",
"Serie": "FAC",
"Folio": "100",
"Date": "2026-06-11T16:05:51",
"CertNumber": "30001000000500003416",
"PaymentTerms": "03 - Transferencia electrónica de fondos",
"PaymentConditions": "CREDITO A SIETE DIAS",
"PaymentMethod": "PUE - Pago en una sola exhibición",
"PaymentAccountNumber": "",
"PaymentBankName": "",
"ExpeditionPlace": "78000",
"ExchangeRate": 0.0,
"Currency": "MXN - Peso Mexicano",
"Subtotal": 100.0,
"Discount": 0.0,
"Total": 116.0,
"Observations": "Elemento Observaciones solo visible en PDF",
"OrderNumber": "TEST-001",
"Issuer": {
"FiscalRegime": "601 - General de Ley Personas Morales",
"Rfc": "EKU9003173C9",
"TaxName": "ESCUELA KEMPER URGATE",
"Email": "correo@prueba.com",
"Phone": "9999999999",
"TaxAddress": {
"Street": "Calle de prueba",
"ExteriorNumber": "123",
"InteriorNumber": "",
"Neighborhood": "Prueba",
"ZipCode": "42501",
"Municipality": "Pruebas",
"State": "ESTADO DE MEXICO",
"Country": "México"
}
},
"Receiver": {
"Rfc": "URE180429TM6",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"Email": ""
},
"Items": [
{
"ProductCode": "10101504",
"IdentificationNumber": "EDL",
"UnitCode": "MTS",
"Discount": 0.0,
"CuentaPredial": "",
"Quantity": 2.0,
"Unit": "MTS - NO APLICA",
"Description": "Estudios de laboratorio",
"UnitValue": 50.0,
"Total": 100.0
}
],
"Taxes": [
{
"Total": 16.0,
"Name": "IVA",
"Rate": 0.16,
"Type": "transferred"
}
],
"Complement": {
"TaxStamp": {
"Uuid": "5e09160f-a206-44d7-b389-4f243585e76a",
"Date": "2026-06-11T16:05:52",
"SatCertNumber": "30001000000500003456",
"RfcProvCertif": "SPR190613I52"
}
},
"Status": "active",
"OriginalString": "||4.0|FAC|100|2026-06-11T16:05:51|03|30001000000500003416|.......|"
}
```
# Flujo en API Multiemisor
Source: https://facturama.mintlify.app/es/api-lite/pasos-api-multiemisor
Conoce el flujo para registrar CSDs y emitir CFDI con la API Multiemisor (API Lite).
La modalidad API Multiemisor permite emitir CFDI utilizando múltiples RFC emisores desde una misma cuenta de Facturama.
Para ello, es necesario registrar previamente los Certificados de Sello Digital (CSD) de cada emisor que participará en el proceso de facturación.
Consideraciones importantes.
Antes de comenzar, toma en cuenta los siguientes aspectos:
API Multiemisor y API Web están incluidas dentro de la misma suscripción anual
de API.
Ambas modalidades pueden utilizarse simultáneamente.
Las operaciones realizadas mediante API Multiemisor no son visibles en el
portal web de Facturama.
La administración de facturas, consultas, descargas y cancelaciones debe
realizarse mediante peticiones HTTP o utilizando alguno de los SDK
disponibles.
### Flujo de facturación
El proceso de facturación en API Multiemisor consta de cuatro etapas principales:
Carga de CSD -> Emisión de CFDI -> Consulta y Descarga -> Cancelación (opcional)
### 1 - Registrar los Certificados de Sello Digital (CSD)
Antes de emitir un CFDI con un RFC determinado, es necesario registrar sus certificados de sello digital.
Este procedimiento se realiza una sola vez por emisor y únicamente será necesario repetirlo cuando:
* El certificado expire.
* El certificado sea revocado.
* Se requiera actualizar la información del CSD.
Una vez registrados, los certificados quedarán asociados al RFC correspondiente para futuras emisiones.
[Ir a Cargar CSDs](/es/api-lite/cargar-csds)
### 2 - Emitir un CFDI
Para generar una factura se debe realizar una petición POST al endpoint de CFDI de API Multiemisor.
```http theme={null}
POST /api-lite/4/cfdis
```
Además de los datos fiscales del comprobante, es obligatorio incluir el nodo Issuer, el cual identifica el RFC que emitirá el CFDI.
Ejemplo
```json theme={null}
{
"Issuer": {
"Rfc": "EKU9003173C9",
"Name": "ESCUELA KEMPER URGATE",
"FiscalRegime": "601"
},
"CfdiType": "I",
"Folio": "100",
"Receiver": {},
"Items": []
}
```
El RFC indicado en Issuer debe contar previamente con sus CSD registrados en la cuenta.
[Ir a Crear CFDI](/es/api-lite/crear-cfdi)
### 3 - Consultar y descargar comprobantes
A diferencia de API Web, los CFDI emitidos mediante API Multiemisor no pueden visualizarse desde el portal web.
Para obtener información de una factura es necesario utilizar los endpoints de consulta correspondientes.
Consultar detalle de una factura
```http theme={null}
GET /api-lite/cfdis/{Id}
```
Identificador único del CFDI generado.
Mediante los endpoints disponibles también es posible:
* Consultar el detalle completo de un CFDI.
* Descargar archivos XML.
* Descargar representaciones PDF.
* Descargar formatos HTML.
* Enviar facturas por correo electrónico.
[Ir a Consultar CFDI](/es/api-lite/consultar-cfdi)
### 4 - Cancelar un CFDI
Si es necesario invalidar un comprobante emitido, se debe utilizar el endpoint de cancelación de API Multiemisor.
```http theme={null}
DELETE /api-lite/cfdis/{Id}
```
Debido a que los comprobantes no son administrables desde el portal web, todo el proceso de cancelación debe realizarse mediante API o SDK.
[Ir a Cancelar CFDI](/es/api-lite/cancelar-cfdi)
# Ambientes
Source: https://facturama.mintlify.app/es/api-reference/ambientes
Facturama ofrece dos ambientes independientes: Sandbox para pruebas sin validez fiscal y Producción para emitir CFDIs reales ante el SAT.
## Sandbox
Ambiente de pruebas. Los CFDIs generados aquí no tienen validez fiscal y no se reportan al SAT. Usa las mismas credenciales de tu cuenta sandbox en dev.facturama.mx.
Crear cuenta sandbox →
## Producción
Ambiente real. Los CFDIs se timbran ante el SAT y tienen plena validez fiscal. Requiere una cuenta de producción activa en facturama.mx.
Ir a producción →
## Comparación de ambientes
| Característica | Sandbox | Producción |
| ----------------- | ------------------------- | ------------------ |
| Base URL | `apisandbox.facturama.mx` | `api.facturama.mx` |
| Validez fiscal | No | Sí |
| Cuentas | `dev.facturama.mx` | `app.facturama.mx` |
| Folios consumidos | No | Sí |
| Timbrado SAT | Simulado | Real (PAC) |
**Migrar a producción** — Solo cambia el host de la URL base. El resto del payload, headers y autenticación son idénticos entre ambos ambientes.
# Crear una cuenta
Source: https://facturama.mintlify.app/es/api-reference/crear-una-cuenta
Para usar la API necesitas una cuenta en Facturama. El ambiente sandbox es gratuito y te permite probar sin emitir CFDIs con validez fiscal.
## Cuenta Sandbox
La cuenta sandbox es independiente de producción. Regístrate en dev.facturama.mx y obtén acceso inmediato a todos los endpoints de la API sin costo.
## Cuenta Producción
Para emitir CFDIs con validez fiscal ante el SAT necesitas una cuenta de producción activa en app.facturama.mx con una suscripción vigente.
## Tus credenciales
Las credenciales de la API son el mismo usuario y contraseña que usas para iniciar sesión en el portal. No se genera un API key separado.
Guarda bien tus credenciales — Si olvidas tu contraseña, recupérala desde el portal. No hay forma de recuperarla desde la API.
# Introducción
Source: https://facturama.mintlify.app/es/api-reference/introduction
La API más completa de México para emitir, gestionar y cancelar CFDIs desde tu propio sistema — en minutos, no en meses.
## ¿Por qué Facturama?
Cada empresa en México está obligada a emitir facturas electrónicas válidas ante el SAT. El problema: construir esa integración desde cero es costoso, complejo y cambia con cada actualización fiscal.
**Facturama resuelve eso de una vez por todas.**
Con una sola integración obtienes:
Emite CFDIs 4.0 con validez fiscal ante el SAT en tiempo real. Sin esperas, sin colas.
Prueba toda la API sin costo y sin emitir CFDIs reales. Tu equipo puede desarrollar con confianza.
Claves de productos, regímenes fiscales, unidades de medida y más — siempre actualizados.
Cancela CFDIs, gestiona complementos de pago, carta porte, retenciones y más.
## Lo que puedes construir
* **Sistemas de facturación** integrados directo en tu ERP o punto de venta
* **Portales de autoservicio** donde tus clientes generan sus propias facturas
* **Automatización contable** que emite, envía y archiva CFDIs sin intervención humana
* **Marketplaces** que facturan a nombre de múltiples emisores
## Autenticación
Facturama usa **HTTP Basic Auth**. Tus credenciales son el mismo usuario y contraseña con los que entras al portal — no hay pasos extra ni API keys adicionales.
```http theme={null}
Authorization: Basic base64(usuario:contraseña)
```
¿Aún no tienes cuenta? Empieza gratis en el sandbox — sin tarjeta de crédito, acceso inmediato a todos los endpoints.
Gratis, inmediato y sin compromiso.
Cuando estés listo para emitir CFDIs reales.
# Colección Postman
Source: https://facturama.mintlify.app/es/api-reference/postman
Importa la colección oficial de Postman para explorar y probar todos los endpoints de la API de Facturama sin escribir código.
## ¿Qué incluye la colección?
La colección agrupa todos los endpoints de la API Web de Facturama: autenticación, clientes, productos, emisión de CFDIs, cancelación y consultas. Cada request incluye ejemplos de body y variables de entorno preconfiguradas.
## Configuración rápida
## Variables de entorno
| Variable | Descripción |
| ---------- | -------------------------------------------- |
| `baseUrl` | URL base del ambiente (sandbox o producción) |
| `username` | Tu usuario de Facturama |
| `password` | Tu contraseña de Facturama |
| Variable | Valor |
| ---------- | --------------------------------- |
| `baseUrl` | `https://apisandbox.facturama.mx` |
| `username` | `tu-usuario-sandbox` |
| `password` | `tu-contraseña-sandbox` |
| Variable | Valor |
| ---------- | -------------------------- |
| `baseUrl` | `https://api.facturama.mx` |
| `username` | `tu-usuario-produccion` |
| `password` | `tu-contraseña-produccion` |
Usa environments de Postman para alternar fácilmente entre sandbox y producción sin modificar los requests.
## Descargar la colección
# SDKs oficiales
Source: https://facturama.mintlify.app/es/api-reference/sdks
Facturama mantiene SDKs oficiales en GitHub para los lenguajes más populares. Todos son open source y soportan la API Web de Facturama.
Instala el SDK de tu lenguaje para evitar construir los headers, codificación Base64 y manejo de errores desde cero.
### PHP + Multiemisor
API Web y API Multiemisor
```bash theme={null}
composer require facturama/facturama-sdk-php
```
[Ver en GitHub →](https://github.com/Facturama/facturama-php-sdk)
***
### .NET / C# + Multiemisor
API Web y API Multiemisor
```bash theme={null}
dotnet add package Facturama
```
[Ver en GitHub →](https://github.com/Facturama/facturama-dotnet-sdk)
***
### Python
API Web
```bash theme={null}
pip install facturama
```
[Ver en GitHub →](https://github.com/Facturama/facturama-python-sdk)
***
### Java
API Web
```xml theme={null}
```
[Ver en GitHub →](https://github.com/Facturama/facturama-java-sdk)
***
### JavaScript
API Web (Browser / bundler)
```bash theme={null}
npm install facturama-javascript-sdk
```
[Ver en GitHub →](https://github.com/Facturama/facturama-javascript-sdk)
***
### Node.js
API Web (Node.js)
```bash theme={null}
npm install facturama-nodejs-sdk
```
[Ver en GitHub →](https://github.com/Facturama/facturama-nodejs-sdk)
***
### Ruby
API Web
```bash theme={null}
gem install facturama
```
[Ver en GitHub →](https://github.com/Facturama/facturama-ruby-sdk)
# Cancelar CFDI
Source: https://facturama.mintlify.app/es/api-web/cancelar-cfdi
Cancela CFDIs emitidos indicando el motivo correcto. Entiende el flujo de aceptación y los estados de cancelación.
## Motivos de cancelación (CFDI 4.0)
Desde 2022, toda cancelación requiere un motivo:
| Clave | Motivo | Cuándo usar |
| ----- | -------------------------------------------------- | ------------------------------------------ |
| `01` | Comprobante emitido con errores **con** relación | Hay un CFDI sustituto que corrige el error |
| `02` | Comprobante emitido con errores **sin** relación | No se emitirá sustituto |
| `03` | No se llevó a cabo la operación | La venta o servicio no se realizó |
| `04` | Operación nominativa relacionada en factura global | Para CFDIs incluidos en factura global |
## Cancelar un CFDI
```http theme={null}
DELETE /cfdi/{id}?type={type}&motive={motivo}&uuidReplacement={uuid}
```
Identificador del documento a cancelar. Lo encontrarás en el campo `Id` en la respuesta de emisión de la factura o al consultar las facturas emitidas.
Para API Web se utiliza `issued` para facturas de ingreso, egreso y complementos, mientras que se utiliza `payroll` para los comprobantes de nómina.
Motivo de cancelación explicados en la tabla anterior (01, 02, 03, 04).
UUID del comprobante que sustituye al cancelado (solamente requerido para el motivo de cancelación «01 - Comprobante emitido con errores con relación»).
Utilizar el campo **uuidReplacement** cuando este no es requerido puede causar errores o evitar que la factura no sea cancelada, incluso si se asigna un valor nulo o vacío.
Para sandbox, solamente se pueden cancelar las facturas que utilicen el RFC de **EKU9003173C9** como emisor.
**Ejemplo — Motivo 02 (sin sustituto):**
```bash theme={null}
curl --request DELETE \
--url 'https://apisandbox.facturama.mx/cfdi/_l0qPog2qSpryRUq1qfCrg2?motive=02' \
--header 'Authorization: Basic YOUR_BASE64_CREDENTIALS'
```
**Ejemplo — Motivo 01 (con CFDI sustituto):**
```bash theme={null}
curl --request DELETE \
--url 'https://apisandbox.facturama.mx/cfdi/_l0qPog2qSpryRUq1qfCrg2?motive=01&uuidReplacement=5e09160f-a206-44d7-b389-4f243585e76a' \
--header 'Authorization: Basic YOUR_BASE64_CREDENTIALS'
```
## Respuesta a una solicitud de cancelación
```json theme={null}
{
"Status": "canceled",
"Message": "Cancelado: Cancelado sin aceptación",
"IsCancelable": "Cancelable sin aceptacion",
"Uuid": "026826D4-CED0-4A3F-B6A3-890B20BD587B",
"RequestDate": "2025-04-29T10:05:17",
"ExpirationDate": "2025-05-06T10:05:17",
"AcuseXmlBase64": "PD94bWwgdmVyc2lv.....",
"CancelationDate": "2025-04-29T10:05:17",
"AcuseStatus": 201,
"AcuseStatusDetails": "Solicitud de cancelación recibida."
}
```
* `Status` Estado de la cancelación.
* `canceled` Cancelada.
* `active` El CFDI sigue vigente; la cancelación no se realizó.
* `pending` Pendiente de aceptación por parte del receptor.
* `Message` Detalle del status de cancelación.
* `IsCancelable` Indica si la factura es cancelable y bajo que condiciones, o si no es cancelable.
* `Cancelable sin aceptación`
* `Cancelable con aceptación`
* `No cancelable`
* `Uuid` UUID del CFDI por cancelar.
* `RequestDate` Fecha de solicitud de cancelación.
* `ResponseDate` Fecha de respuesta del SAT.
* `ExpirationDate` Fecha límite en que el receptor puede emitir una respuesta.
* `AcuseXmlBase64` XML del acuse en formato Base64.
* `AcuseStatus` Código del status de la cancelación.
* `AcuseStatusDetails` Descripción del `AcuseStatus` de la cancelación.
## Flujo de cancelación
Dependiendo del monto y el receptor, la cancelación puede requerir aceptación:
```
Solicitud de cancelación
↓
¿Requiere aceptación del receptor?
↙ ↘
No Sí
↓ ↓
Cancelado Pendiente (72 hrs)
↙ ↘
Aceptada Rechazada
```
**Cancelación inmediata (sin aceptación):**
* CFDIs emitidos mismo día dentro de los primeros 3 días
* Montos menores a 1,000 MXN
* CFDIs de nómina y traslado
**Requieren aceptación del receptor:**
* CFDIs de montos mayores o con más de 3 días de emitidos
## Consultar estado de un CFDI
```http theme={null}
GET /cfdi/{Id}?type=issued
```
### Parámetros de consulta
Identificador único del CFDI.
## Respuesta exitosa
```json theme={null}
{
"Id": "DznlumtVtkA3ya4JXAeGWw2",
.
.
.
"Issuer":
{ },
"Receiver":
{ },
"Items": [
{ }
],
"Taxes": [
{ }
],
"Complement":
{
"TaxStamp":
{ }
},
"Status": "active",
"OriginalString": ""
}
```
El campo `Status` en la respuesta indica el estado actual dentro de Facturama:
| Estado | Descripción |
| ---------- | ---------------------- |
| `active` | CFDI vigente |
| `canceled` | Cancelado exitosamente |
## Obtener acuse de cancelación
Después de una cancelación exitosa:
```http theme={null}
GET /acuse/{format}/{type}/{id}
```
Formato del archivo a obtener (pdf|html).
Tipo del CFDI.
Identificador del CFDI.
Devuelve el acuse de cancelación emitido por el SAT en Base64.
En el sandbox, las cancelaciones son inmediatas y no requieren aceptación del receptor.
# Clientes
Source: https://facturama.mintlify.app/es/api-web/clientes
Gestiona el catálogo de receptores de tus facturas. Registra, consulta, valida, actualiza y elimina clientes.
## ¿Para qué sirve el catálogo de clientes?
El catálogo de clientes almacena los datos fiscales de quienes reciben tus facturas. Aunque puedes enviar los datos del receptor directamente en cada CFDI, usar el catálogo te permite:
* Reutilizar datos sin repetirlos en cada factura
* Validar el RFC del cliente contra la base del SAT
* Buscar clientes por nombre o RFC
## Crear un cliente
```http theme={null}
POST /Client
```
```json theme={null}
{
"Rfc": "",
"Name": "",
"FiscalRegime": "",
"Email": "",
"EmailOp1": "",
"CfdiUse": "",
"TaxResidence": "",
"NumRegIdTrib": "",
"TaxZipCode": "",
"Address": {
"Street": "",
"ExteriorNumber": "",
"InteriorNumber": "",
"Neighborhood": "",
"ZipCode": "",
"Locality": "",
"Municipality": "",
"State": "",
"Country": ""
}
}
```
RFC del receptor del comprobante fiscal.
Nombre o razón social del receptor.
Clave del régimen fiscal del receptor.
Correo electrónico principal del receptor.
Correo electrónico adicional del receptor.
Clave del uso de CFDI que tendrá el comprobante.
Clave del país de residencia fiscal del propietario.
Número de registro de identificación tributaria del propietario.
Código postal del domicilio fiscal del receptor.
Domicilio del receptor.
Calle del domicilio.
Número exterior del domicilio.
Número interior del domicilio.
Colonia o asentamiento del domicilio.
Código postal del domicilio.
Localidad del domicilio.
Municipio o alcaldía del domicilio.
Estado del domicilio.
País del domicilio.
```json theme={null}
{
"Rfc": "URE180429TM6",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"Email": "correo1@ejemplo.mx",
"EmailOp1": "correo2@ejemplo.com",
"CfdiUse": "G01",
"TaxResidence": "",
"NumRegIdTrib": "",
"TaxZipCode": "86991",
"Address": {
"Street": "Calle de Pruebas",
"ExteriorNumber": "123",
"InteriorNumber": "456",
"Neighborhood": "Colonia de Pruebas",
"ZipCode": "86991",
"Locality": "",
"Municipality": "",
"State": "TABASCO",
"Country": "Mex"
}
}
```
```json theme={null}
{
"Id": "GQSinri92qqz4cWFAoqKew2",
"Address": {
"Street": "Calle de Pruebas",
"ExteriorNumber": "123",
"InteriorNumber": "456",
"Neighborhood": "Colonia de prueba",
"ZipCode": "86991",
"Locality": "SAN LUIS POTOSI",
"Municipality": "SAN LUIS POTOSI",
"State": "SAN LUIS POTOSI",
"Country": "MEXICO"
},
"Rfc": "URE180429TM6",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"Email": "correo1@ejemplo.mx",
"EmailOp1": "correo2@ejemplo.com",
"CfdiUse": "G01",
"TaxResidence": "",
"NumRegIdTrib": "131494-1055",
"TaxZipCode": "86991"
}
```
## Consultar clientes
```http Lista solo los 100 primeros registros theme={null}
GET /Client
```
### Lista paginada
```http theme={null}
GET /clients?start=0&length=100&search=
```
Posición del registro
Tamaño del resultado, valor esperado de (1 a 100)
Texto o palabra clave para buscar
### Consultar por Id
```http theme={null}
GET /Client/{Id}
```
Identificador unico del cliente
## Actualizar un cliente
```http theme={null}
PUT /Client/{Id}
```
Envía el objeto completo del cliente con los campos modificados.
## Eliminar un cliente
```http theme={null}
DELETE /Client/{Id}
```
Eliminar un cliente del catálogo no afecta los CFDIs ya emitidos.
## RFC genéricos
| Tipo | RFC |
| ----------------------------- | --------------- |
| Público en general (nacional) | `XAXX010101000` |
| Extranjero | `XEXX010101000` |
# Consultar CFDI
Source: https://facturama.mintlify.app/es/api-web/consultar-cfdi
Consulta los CFDIs emitidos o recibidos mediante filtros de búsqueda.
## Consulta por ID
Permite obtener un resumen del CFDI emitido.
```http theme={null}
GET /cfdi/{Id}?type={Type}
```
### Parámetros de consulta
Identificador único del CFDI.
Corresponde al tipo de CFDI que se está intentando consultar, valores permitidos.
| Valor | Descripción |
| ---------- | ---------------- |
| `issued` | CFDIs emitidos. |
| `received` | CFDIs recibidos. |
| `payroll` | CFDIs de nómina. |
Este endpoint solo mostrará los documentos emitidos en API Web.
## Otros filtros para la búsqueda
### Búsqueda paginada
```http Endpoint theme={null}
GET /cfdi?type=issued&page=0
```
Número entero que identifica la página de resultados a consultar.
Ejemplos:
* `page=0` = Representa los primeros 10 elementos (del 1 al 10).
* `page=1` = Representa los segundos 10 elementos (del 11 al 20).
### Búsqueda por estado del CFDI
```http Endpoint theme={null}
GET /cfdi?type=issued&page=0&status=all
```
Permite indicar el status de las facturas que se desea consultar.
**Donde:**
* `all`: Representa todas las facturas disponibles independientemente de su status actual (activas, pendientes, canceladas).
* `active`: Representa todas las facturas que se encuentran activas/vigentes.
* `canceled`: Representa todas las facturas canceladas.
### Búsqueda por folio del CFDI
```http theme={null}
GET /cfdi?type=issued&page=0&folio=999
```
Permite indicar el folio exacto que se desea consultar. La respuesta mostrará todas las facturas que tengan el valor especificado.
### Rango de folios de la factura
```http theme={null}
GET /cfdi?type=issued&page=0&folioStart=1&folioEnd=99
```
Parámetro para indicar el número de folio desde el cual se comenzarán a mostrar las facturas.
Parámetro para indicar el número de folio hasta el cual se mostrarán las facturas.
Combinar el parámetro `folio` con `folioStart` y `folioEnd` en la misma búsqueda puede generar respuestas erróneas del contenido filtrado.
### Búsqueda por rango de fechas de emisión
```http theme={null}
GET /cfdi?type=issued&page=0&dateStart=2026-01-01T00:00:00&dateEnd=2026-01-31T23:59:59
```
Parámetro para indicar la fecha y hora de inicio desde la cual se comenzarán a mostrar las facturas, especificado en formato `aaaa-mm-ddThh:mm:ss`.
Parámetro para indicar la fecha y hora de finalización hasta la cual se mostrarán las facturas, especificado en formato `aaaa-mm-ddThh:mm:ss`.
### Búsqueda por nombre o razón social del receptor
```http theme={null}
GET /cfdi?type=issued&page=0&taxEntityName=ESCUELA
```
Parámetro para indicar el nombre o razón social del receptor de la factura. Puede indicarse completo o solo una parte del mismo.
### Otros filtros disponibles
Parámetro para indicar el número de orden.
Parámetro para indicar la serie.
Parámetro para indicar el método de pago (PUE || PPD).
## Consideraciones
* El parámetro **`type`** es obligatorio.
* Todos los demás parámetros son opcionales.
* Los filtros pueden combinarse para realizar búsquedas más precisas.
* Los parámetros **`rfc`** y **`taxEntityName`** aceptan coincidencias parciales.
* Las fechas deben enviarse con el formato **`aaaa-mm-ddThh:mm:ss`**.
* La paginación inicia en la página **0**.
* Cada solicitud devuelve un máximo de **10 registros**.
# Crear CFDI
Source: https://facturama.mintlify.app/es/api-web/crear-cfdi
Emite facturas electrónicas de ingreso, egreso, traslado y pago. Conoce los tipos de CFDI y cuándo usar cada uno.
## Tipos de CFDI
| Tipo | Clave | Descripción |
| -------- | ----- | ----------------------------------------- |
| Ingreso | `I` | Factura por venta de bienes o servicios |
| Egreso | `E` | Nota de crédito, devolución o descuento |
| Traslado | `T` | Movimiento de mercancías (sin cobro) |
| Nómina | `N` | Recibo de nómina para empleados |
| Pago | `P` | Complemento de pago para cobros diferidos |
## Endpoint
```http theme={null}
POST /3/cfdis
```
## Estructura del CFDI de Ingreso
```json Datos generales theme={null}
"NameId": "",
"Currency": "",
"Folio": "",
"Serie": "",
"CfdiType": "",
"PaymentForm": "",
"PaymentMethod": "",
"OrderNumber": "",
"ExpeditionPlace": "",
"Date": "",
"PaymentConditions": "",
"Observations": "",
"Exportation": "",
```
```json Datos del receptor theme={null}
"Receiver":
{
"Rfc": "",
"CfdiUse": "",
"Name": "",
"FiscalRegime": "",
"TaxZipCode": ""
}
```
```json Conceptos theme={null}
"Items": [
{
"ProductCode": "",
"IdentificationNumber": "",
"Description": "",
"Unit": "",
"UnitCode": "",
"UnitPrice": 0.0,
"Quantity": 0.0,
"Subtotal": 0.0,
"TaxObject": "",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 0.0,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 0.0
}
]
```
[Consulta las referencias API](/api-reference/endpoint/factura-cfdi/crea-un-cfdi-de-emision)
Ejemplo completo de un CFDI de ingreso:
```json theme={null}
{
"NameId": "1",
"Currency": "MXN",
"Folio": "100",
"Serie": "FAC",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2026-05-15T22:17:44",
"PaymentConditions": "CREDITO A SIETE DIAS",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "01",
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "CP01",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991"
},
"Items": [
{
"ProductCode": "10101504",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 116
}
]
}
```
[Idempotencia y reintentos](/es/cfdi40/idempotencia)
Facturama identifica una operación por la combinación de `Folio` y `Date`. Para
evitar comprobantes duplicados, ambos valores deben generarse una sola vez al
iniciar la operación y reutilizarse sin cambios en cada reintento.
Identificador único de la operación, generado por tu sistema.
Fecha y hora de inicio de la operación, en formato `YYYY-MM-DDTHH:mm:ss`.
No regeneres `Folio` ni `Date` en los reintentos, y no uses la fecha/hora
actual del sistema para recalcular `Date`. Cualquier cambio en estos valores
hará que Facturama trate el reintento como una operación nueva.
Por ejemplo, una operación con:
```json theme={null}
{
"Folio": 100,
"Date": "2026-05-15T22:17:44"
}
```
Conserva estos mismos valores en cada reintento, sin importar cuánto tiempo
haya pasado desde la solicitud original.
## Respuesta exitosa
```json theme={null}
{
"Id": "DznlumtVtkA3ya4JXAeGWw2",
"CfdiType": "ingreso",
"Type": "I - ingreso",
"Serie": "FAC",
"Folio": "100",
"Date": "2026-06-11T16:05:51",
"CertNumber": "30001000000500003416",
"PaymentTerms": "03 - Transferencia electrónica de fondos",
"PaymentConditions": "CREDITO A SIETE DIAS",
"PaymentMethod": "PUE - Pago en una sola exhibición",
"PaymentAccountNumber": "",
"PaymentBankName": "",
"ExpeditionPlace": "78000",
"ExchangeRate": 0.0,
"Currency": "MXN - Peso Mexicano",
"Subtotal": 100.0,
"Discount": 0.0,
"Total": 116.0,
"Observations": "Elemento Observaciones solo visible en PDF",
"OrderNumber": "TEST-001",
"Issuer": {
"FiscalRegime": "601 - General de Ley Personas Morales",
"Rfc": "EKU9003173C9",
"TaxName": "ESCUELA KEMPER URGATE",
"Email": "correo@prueba.com",
"Phone": "9999999999",
"TaxAddress": {
"Street": "Calle de prueba",
"ExteriorNumber": "123",
"InteriorNumber": "",
"Neighborhood": "Prueba",
"ZipCode": "42501",
"Municipality": "Pruebas",
"State": "ESTADO DE MEXICO",
"Country": "México"
}
},
"Receiver": {
"Rfc": "URE180429TM6",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"Email": ""
},
"Items": [
{
"ProductCode": "10101504",
"IdentificationNumber": "EDL",
"UnitCode": "MTS",
"Discount": 0.0,
"CuentaPredial": "",
"Quantity": 2.0,
"Unit": "MTS - NO APLICA",
"Description": "Estudios de laboratorio",
"UnitValue": 50.0,
"Total": 100.0
}
],
"Taxes": [
{
"Total": 16.0,
"Name": "IVA",
"Rate": 0.16,
"Type": "transferred"
}
],
"Complement": {
"TaxStamp": {
"Uuid": "5e09160f-a206-44d7-b389-4f243585e76a",
"Date": "2026-06-11T16:05:52",
"SatCertNumber": "30001000000500003456",
"RfcProvCertif": "SPR190613I52"
}
},
"Status": "active",
"OriginalString": "||4.0|FAC|100|2026-06-11T16:05:51|03|30001000000500003416|.......|"
}
```
## Ejemplos de algunos catálogos utilizados
### Formas de pago (PaymentForm)
| Clave | Descripción |
| ----- | -------------------------- |
| `01` | Efectivo |
| `02` | Cheque nominativo |
| `03` | Transferencia electrónica |
| `04` | Tarjeta de crédito |
| `28` | Tarjeta de débito |
| `99` | Por definir (usar con PPD) |
### Métodos de pago (PaymentMethod)
| Clave | Descripción | Cuándo usar |
| ----- | -------------------------------- | ------------------------------------------------------ |
| `PUE` | Pago en una sola exhibición | Cobro inmediato o al contado |
| `PPD` | Pago en parcialidades o diferido | Crédito o pagos futuros — requiere complemento de pago |
Si usas `PPD`, debes emitir un **Complemento de Pago** cada vez que el cliente
realice un pago. Usa `PaymentForm: "99"` en la factura original.
## Nodo relación
Nodo usado para expresar la información de los comprobantes fiscales relacionados:
```json theme={null}
{
"Relations": {
"Type": "01",
"Cfdis": [
{
"Uuid": "45ab1a98-1709-446a-8759-e45a8d76b557"
}
]
}
}
```
```json Ejemplo de uso. theme={null}
{
"NameId": "2",
"Currency": "MXN",
"Folio": "100",
"Serie": "NDC",
"CfdiType": "E",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2024-06-25T12:00:00",
"PaymentConditions": "Nota de credito",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "01",
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "CP01",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991"
},
"Relations": {
"Type": "01",
"Cfdis": [
{
"Uuid": "45ab1a98-1709-446a-8759-e45a8d76b557"
}
]
},
"Items": [
{
"Quantity": 1,
"ProductCode": "86121500",
"UnitCode": "E48",
"Unit": "Unidad de servicio",
"Description": "Pago inicial del 50% por el desarrollo del sitio web personal.",
"IdentificationNumber": "980000",
"UnitPrice": 500.00,
"Subtotal": 500.00,
"TaxObject": "02",
"Taxes": [
{
"Name": "IVA",
"Rate": 0.16,
"Total": 80,
"Base": 500,
"IsRetention": false,
"IsFederalTax": false
}
],
"Total": 580.00
}
]
}
```
Tipos de relación más comunes:
| 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 |
# Descargar documentos
Source: https://facturama.mintlify.app/es/api-web/descargar-documentos
Descarga el PDF, XML de tus CFDIs en Base64, envíalos por email.
## Formatos disponibles
Facturama puede entregar los documentos en los siguientes formatos:
| Formato | Descripción |
| ------- | -------------------------------------- |
| `pdf` | PDF del CFDI para presentar al cliente |
| `xml` | XML sellado y timbrado por el SAT |
| `html` | Vista HTML del CFDI |
## Descargar por formato
```http theme={null}
GET /cfdi/{format}/{type}/{id}
```
Formato del archivo a obtener (pdf | xml | html).
Tipo del CFDI (issued | payroll).
Identificador del CFDI.
```bash Ejemplos theme={null}
# Descargar PDF
curl --url 'https://apisandbox.facturama.mx/cfdi/pdf/issued/jh054AaC04b1wcqSUHYcw2' \
--header 'Authorization: Basic YOUR_BASE64_CREDENTIALS'
# Descargar XML
curl --url 'https://apisandbox.facturama.mx/cfdi/xml/issued/jh054AaC04b1wcqSUHYcw2' \
--header 'Authorization: Basic YOUR_BASE64_CREDENTIALS'
```
**Respuesta:** El contenido del archivo en **Base64**.
La respuesta retorna el '**HTTP Response**' si la petición fue exitosa con un código 200
```json theme={null}
{
"ContentEncoding": "base64",
"ContentType": "pdf",
"ContentLength": 28458,
"Content": "JVBERi0xLjQKMSAwIG9iago8P....."
}
```
## Enviar por email
```http theme={null}
POST /Cfdi?CfdiType={CfdiType}&CfdiId={CfdiId}&Email={Email}&Subject={Subject}&Comments={Comments}
```
Tipo del CFDI (issued | payroll).
Identificador del CFDI.
Email al que se enviará la factura.
Asunto del correo.
Breve descripción o comentario.
## Respuesta de la petición
La respuesta retorna el '**HTTP Response**' si la petición fue exitosa con un código de estado 200:
```json theme={null}
{
"msj": "El mensaje se ha enviado correctamente",
"success": true
}
```
Solo se permite enviar 5 veces una misma factura en un periodo de 12 hrs.
# Productos y servicios
Source: https://facturama.mintlify.app/es/api-web/productos
Gestiona el catálogo de productos y servicios que aparecen en tus facturas, con sus claves SAT, unidades e impuestos.
## ¿Para qué sirve el catálogo de productos?
El catálogo de productos almacena los bienes y servicios que facturas. Cada producto debe tener:
* `CodeProdServ`: clave del catálogo SAT (ClaveProdServ) que clasifica el producto
* `UnitCode`: clave de la unidad de medida del catálogo SAT (ClaveUnidad)
* `Taxes`: IVA, IEPS u otros que apliquen
## Crear un producto
```http theme={null}
POST /Product
```
```json theme={null}
{
"Unit": "",
"UnitCode": "",
"IdentificationNumber": "",
"Name": "",
"Description": "",
"Price": 0.0,
"CodeProdServ": "",
"ObjetoImp": "",
"Taxes": [
{
"Name": "IVA",
"Rate": 0.16,
"IsRetention": false,
"IsFederalTax": true,
"IsQuota": false
}
]
}
```
La unidad de medida aplicable para la cantidad expresada en el producto
Código correspondiente a la Unidad conforme al catalogo del SAT
Número de serie del producto
Nombre del producto
Descripción del producto
Valor o precio unitario del producto
Clave del Producto o servicio segun el catalogo del SAT
Clave correspondiente para indicar si la operación comercial es objeto o no de impuesto
Impuestos federales aplicables al producto
```json theme={null}
{
"Unit": "Servicio",
"UnitCode": "E48",
"IdentificationNumber": "PRUEBA001",
"Name": "Producto de prueba",
"Description": "Producto de prueba IVA al 16%",
"Price": 999.9999,
"CodeProdServ": "01010101",
"ObjetoImp": "02",
"Taxes": [
{
"Name": "IVA",
"Rate": 0.16,
"IsRetention": false,
"IsFederalTax": true,
"IsQuota": false
}
]
}
```
## Consultar productos
```http Lista solo los 100 primeros registros theme={null}
GET /Product
```
### Lista paginada
```http theme={null}
GET /products?start=0&length=100&search=
```
Posición del registro
Tamaño del resultado, valor esperado de (1 a 100)
Texto o palabra clave para buscar
### Consultar por Id
```http theme={null}
GET /Product/{Id}
```
Identificador único del producto.
## Actualizar
```http theme={null}
PUT /Product/{Id}
```
Envía el objeto completo del producto con los campos modificados.
## Eliminar un producto
```http theme={null}
DELETE /Product/{Id}
```
Eliminar un producto del catálogo no afecta los CFDIs ya emitidos.
## Claves SAT más comunes
### Claves de producto (ClaveProdServ)
| Clave | Descripción |
| ---------- | ---------------------------------------- |
| `01010101` | No existe en el catálogo (genérica) |
| `81111500` | Servicios de tecnología de información |
| `80131501` | Servicios de consultoría de negocios |
| `43232408` | Software para aplicaciones empresariales |
| `50202306` | Mercancías de comercio general |
Usa el endpoint `GET /catalogs/ProductsOrServices?keyword=software` para buscar la clave correcta para tu producto.
### Claves de unidad (ClaveUnidad)
| Clave | Descripción |
| ----- | ------------------ |
| `H87` | Pieza |
| `E48` | Unidad de servicio |
| `KGM` | Kilogramo |
| `LTR` | Litro |
| `MTR` | Metro |
| `ACT` | Actividad |
## Configuración de impuestos
### IVA 16% (más común)
```json theme={null}
{
"Name": "IVA",
"Rate": 0.16,
"IsRetention": false,
"IsFederalTax": true
}
```
### IVA retenido (servicios profesionales)
```json theme={null}
{
"Name": "IVA RET",
"Rate": 0.106667,
"IsRetention": true,
"IsFederalTax": true
}
```
### ISR retenido (honorarios)
```json theme={null}
{
"Name": "ISR",
"Rate": 0.10,
"IsRetention": true,
"IsFederalTax": true
}
```
### Tasa 0% (exportaciones, alimentos, medicamentos)
```json theme={null}
{
"Name": "IVA",
"Rate": 0.00,
"IsRetention": false,
"IsFederalTax": true
}
```
### IEPS
```json theme={null}
{
"Name": "IEPS",
"Rate": 0.00,
"IsRetention": false,
"IsFederalTax": true,
"IsQuota": false
}
```
# Bienvenidos
Source: https://facturama.mintlify.app/es/bienvenidos
Todo lo que necesitas para integrar la API de Facturama y emitir CFDIs válidos ante el SAT desde tu propio sistema.
## Bienvenido al portal para desarrolladores
La API de Facturama te permite automatizar la emisión, consulta y cancelación de facturas electrónicas (CFDIs) directamente desde tu aplicación, sin depender de portales manuales.
Si es tu primera vez trabajando con facturación electrónica en México, te recomendamos comenzar por entender el sistema antes de escribir la primera línea de código.
Aprende qué es un CFDI, quiénes intervienen, qué es el SAT y el RFC, y cómo funciona el proceso de timbrado — en la sección **El sistema de facturación en México**.
***
## Empieza a integrar
Si ya conoces el contexto fiscal, estos son los tres pasos para hacer tu primera llamada a la API:
Regístrate gratis en [dev.facturama.mx](https://dev.facturama.mx/api/registro). No requiere tarjeta ni suscripción. Tus credenciales de acceso son las mismas que usarás en la API.
Facturama usa HTTP Basic Auth. Solo necesitas codificar tu usuario y contraseña en Base64 y agregarlo al header `Authorization`.
[Ver guía de autenticación →](/es/guias/autenticacion)
Sigue el ejemplo paso a paso para crear un CFDI de ingreso con el mínimo de campos requeridos y recibir el XML timbrado.
[Ver tu primera factura →](/es/guias/primera-factura)
***
## ¿Qué puedes construir?
Emite facturas automáticamente al cerrar una venta o generar una orden.
Permite que tus clientes soliciten su factura desde tu sitio web o app.
Factura a nombre de múltiples emisores con la API Multiemisor.
Genera recibos de nómina y comprobantes de retención para tus colaboradores.
***
## Ambientes disponibles
| Ambiente | URL base | Uso |
| -------------- | --------------------------------- | -------------------------- |
| **Sandbox** | `https://apisandbox.facturama.mx` | Pruebas sin validez fiscal |
| **Producción** | `https://api.facturama.mx` | CFDIs reales ante el SAT |
Cambia de sandbox a producción con solo cambiar el host de la URL. El payload, los headers y la autenticación son idénticos en ambos ambientes.
***
## Explora el resto de la documentación
Todos los endpoints con playground interactivo y ejemplos de respuesta.
PHP, Python, .NET, Node.js, Java, Ruby y JavaScript.
Carta Porte, comercio exterior, retenciones y más.
# Certificados de Prueba (CSD)
Source: https://facturama.mintlify.app/es/catalogos/csds-pruebas
Usa los certificados CSD de prueba del SAT para emitir CFDI en el entorno Sandbox sin validez fiscal.
Los Certificados de Sello Digital (CSD) de prueba permiten generar CFDI en el ambiente Sandbox sin necesidad de utilizar certificados reales emitidos para tu RFC.
Los CFDI generados con estos certificados son únicamente para pruebas y **no tienen validez fiscal ante el SAT**.
## Consideraciones importantes
Antes de utilizar los certificados de prueba, toma en cuenta lo siguiente:
* Son válidos únicamente en el entorno Sandbox.
* No pueden utilizarse en producción.
* Todas las llaves privadas utilizan la misma contraseña.
* Los datos del receptor deben cumplir las validaciones de CFDI 4.0.
* La razón social debe enviarse en mayúsculas y sin régimen societario cuando aplique.
[Descarga los certificados de pruebas](https://cdnfacturama.azureedge.net/content/csd-pruebas.zip)
## Contraseña de los certificados
Todos los certificados de prueba utilizan la siguiente contraseña:
```text theme={null}
12345678a
```
## RFC recomendado para pruebas
Para la mayoría de las integraciones se recomienda utilizar el siguiente RFC emisor:
| Campo | Valor |
| ------------- | ----------------------- |
| RFC | `EKU9003173C9` |
| Nombre Fiscal | `ESCUELA KEMPER URGATE` |
| Código Postal | `42501` |
Este RFC es el emisor de pruebas más utilizado en la documentación y ejemplos de Facturama.
## Certificados disponibles
Facturama proporciona múltiples RFC de prueba para simular distintos escenarios fiscales.
### Personas Físicas
| RFC | Nombre Fiscal | Código Postal | Obligaciones |
| --------------- | ------------------------ | ------------- | ------------ |
| `CACX7605101P8` | XOCHILT CASAS CHAVEZ | 36257 | 2 |
| `FUNK671228PH6` | KARLA FUENTE NOLASCO | 01160 | 1 |
| `IAÑL750210963` | LUIS IAN ÑUZCO | 82525 | 1 |
| `JUFA7608212V6` | ADRIANA JUAREZ FERNANDEZ | 01160 | 1 |
| `KAHO641101B39` | OSCAR KALA HAAK | 76074 | 1 |
| `KICR630120NX3` | RODRIGO KITIA CASTRO | 36246 | 1 |
| `MISC491214B86` | CECILIA MIRANDA SANCHEZ | 01010 | 1 |
| `RAQÑ7701212M3` | ÑEVES RAMIREZ QUEZADA | 78905 | 1 |
| `WATM640917J45` | MARIA WATEMBER TORRES | 43543 | 1 |
| `WERX631016S30` | XAIME WEIR ROJO | 01279 | 1 |
| `XAMA620210DQ5` | ALBA XKARAJAM MENDEZ | 01219 | 1 |
| `XIQB891116QE4` | BERENICE XIMO QUEZADA | 40968 | 4 |
| `XOJI740919U48` | INGRID XODAR JIMENEZ | 76028 | 1 |
***
### Personas Morales
| RFC | Razón Social | Código Postal | Obligaciones | SCNF |
| -------------- | ---------------------------------- | ------------- | ------------ | ---- |
| `EKU9003173C9` | ESCUELA KEMPER URGATE | 42501 | 1 | No |
| `H&E951128469` | HERRERIA & ELECTRICOS | 06002 | 1 | No |
| `IIA040805DZ4` | INDISTRIA ILUMINADORA DE ALMACENES | 62661 | 1 | No |
| `IVD920810GU2` | INNOVACION VALOR Y DESARROLLO | 63901 | 1 | No |
| `IXS7607092R5` | INTERNACIONAL XIMBO Y SABORES | 23004 | 1 | No |
| `JES900109Q90` | JIMENEZ ESTRADA SALAS | 37161 | 1 | No |
| `KIJ0906199R1` | KERNEL INDUSTIA JUGUETERA | 28971 | 1 | No |
| `L&O950913MSA` | LUCES & OBRAS | 60922 | 1 | Sí |
| `OÑO120726RX3` | ORGANICOS ÑAVEZ OSORIO | 40501 | 1 | Sí |
| `URE180429TM6` | UNIVERSIDAD ROBOTICA ESPAÑOLA | 86991 | 1 | No |
| `XIA190128J61` | XENON INDUSTRIAL ARTICLES | 76343 | 1 | No |
| `ZUÑ920208KL4` | ZAPATERIA URTADO ÑERI | 34541 | 1 | No |
***
## Uso en API Web
En API Web, los certificados pueden cargarse desde:
* La plataforma de Facturama.
* Los endpoints de administración de certificados.
Una vez configurados, los CFDI emitidos utilizarán automáticamente los certificados asociados a la cuenta.
## Uso en API Multiemisor
En API Multiemisor, los certificados deben cargarse explícitamente mediante la API.
```http theme={null}
POST /api-lite/csds
```
La carga de certificados en API Multiemisor es independiente de la configuración realizada en la plataforma web.
### Ejemplo
```json theme={null}
{
"Rfc": "EKU9003173C9",
"Certificate": "",
"PrivateKey": "",
"PrivateKeyPassword": "12345678a"
}
```
## Obligaciones fiscales soportadas
Los certificados de prueba están configurados para simular distintos escenarios fiscales, incluyendo:
| Clave | Descripción |
| ----- | -------------------------------------------------------------------------------------- |
| 1 | Habilitado para facturar (IVA exento, tasa 0% y 16%) |
| 2 | Habilitado para facturar (IVA exento, tasa 0%, 8% y 16%) - Zona Fronteriza Norte |
| 3 | Habilitado para facturar (IVA exento, tasa 0%, 8% y 16%) - Zona Fronteriza Sur |
| 4 | Habilitado para facturar (IVA exento, tasa 0%, 8% y 16%) - Zona Fronteriza Norte y Sur |
***
## Siguiente paso
Una vez cargados los certificados:
1. Configura el emisor que utilizarás en las pruebas.
2. Crea tu primer CFDI.
3. Valida el XML y PDF generados.
4. Implementa el mismo flujo utilizando certificados reales en producción.
# Catálogos SAT
Source: https://facturama.mintlify.app/es/catalogos/vision-general
Consulta los catálogos oficiales del SAT directamente desde la API: claves de productos, unidades, regímenes fiscales, formas de pago y más.
## ¿Para qué sirven los catálogos?
Los catálogos del SAT contienen las claves válidas que debes usar al emitir un CFDI. En lugar de buscarlas manualmente, Facturama expone endpoints para consultarlos y filtrarlos con una palabra clave.
## Catálogos disponibles
| Catálogo | Endpoint | Uso en CFDI |
| --------------------- | ---------------------------------- | ------------------------------- |
| Productos y Servicios | `GET /catalogs/ProductsOrServices` | `Items[].ProductCode` |
| Unidades de Medida | `GET /catalogs/Units` | `Items[].UnitCode` |
| Códigos Postales | `GET /catalogs/PostalCodes` | `ExpeditionPlace`, `TaxZipCode` |
| Monedas | `GET /catalogs/Currencies` | `Currency` |
| Formas de Pago | `GET /catalogs/PaymentForms` | `PaymentForm` |
| Métodos de Pago | `GET /catalogs/PaymentMethods` | `PaymentMethod` |
| Tipos de CFDI | `GET /catalogs/CfdiTypes` | `CfdiType` |
| Regímenes Fiscales | `GET /catalogs/FiscalRegimes` | `FiscalRegime` |
| Usos de CFDI | `GET /catalogs/CfdiUses` | `CfdiUse` |
| Impuestos Federales | `GET /catalogs/TaxFederals` | `Taxes[].Name` |
| Tipos de Relación | `GET /catalogs/RelationTypes` | `Relations.Type` |
| Addendas | `GET /catalogs/Addendas` | `Addenda` |
## Buscar por palabra clave
Todos los catálogos aceptan el parámetro `keyword` para filtrar:
```http theme={null}
GET /api/catalogs/ProductsOrServices?keyword=software
GET /api/catalogs/Units?keyword=kilogramo
GET /api/catalogs/FiscalRegimes?keyword=sueldos
```
**Respuesta típica:**
```json theme={null}
[
{
"Value": "81111500",
"Name": "Servicios de tecnología de información"
},
{
"Value": "81112100",
"Name": "Servicios de programación informática"
}
]
```
## Regímenes fiscales más comunes
| Clave | Régimen |
| ----- | ------------------------------------------------------------------------------------------ |
| `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 |
| `612` | Personas Físicas con Actividades Empresariales y Profesionales |
| `616` | Sin obligaciones fiscales |
| `621` | Incorporación Fiscal |
| `625` | Régimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas |
| `626` | Régimen Simplificado de Confianza (RESICO) |
## Usos de CFDI más comunes
| Clave | Uso | Aplica a |
| ------ | --------------------------------------------------- | -------- |
| `G01` | Adquisición de mercancias | PM y PF |
| `G03` | Gastos en general | PM y PF |
| `P01` | Por definir | PM y PF |
| `S01` | Sin efectos fiscales | PM y PF |
| `CP01` | Pagos | PM y PF |
| `D01` | Honorarios médicos, dentales y gastos hospitalarios | Solo PF |
| `I01` | Construcciones | PM y PF |
## Catálogos para Carta Porte
Los catálogos de Carta Porte están en una ruta diferente:
```http theme={null}
GET /api/catalogs/cartaporte/{catalogo}
```
| Catálogo | Parámetro |
| ---------------------------- | ---------------------- |
| Tipos de permiso SCT | `TipoPermiso` |
| Configuración autotransporte | `ConfigAutotransporte` |
| Clave unidad de peso | `ClaveUnidadPeso` |
| Tipos de embalaje | `TipoEmbalaje` |
| Estaciones | `Estaciones` |
| Material peligroso | `MaterialPeligroso` |
# Factura Global
Source: https://facturama.mintlify.app/es/cfdi40/factura-global
Consolida las ventas al público en general en un solo CFDI por período diario, semanal, quincenal o mensual.
## ¿Qué es la Factura Global?
La Factura Global permite consolidar todas las ventas realizadas al público en general (sin RFC específico del cliente) en un solo CFDI por período, en lugar de emitir una factura individual por cada venta.
Es obligatoria para contribuyentes que realizan operaciones con el público en general y no emiten CFDI individual por cada venta.
## Periodicidades disponibles
| Clave | Período |
| ----- | -------------------------------- |
| `01` | Diario |
| `02` | Semanal |
| `03` | Quincenal |
| `04` | Mensual |
| `05` | Bimestral (solo para RIF/RESICO) |
## Meses disponibles
| Clave | Período |
| ----- | ------------------- |
| `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 |
## Estructura del CFDI Global
```json La factura global debe llevar el nodo Información Global theme={null}
"GlobalInformation": {
"Periodicity": "04",
"Months": "04",
"Year": "2024"
}
```
## Campos del nodo `GlobalInformation`
| Campo | Tipo | Descripción |
| ------------- | ------ | ---------------------------- |
| `Periodicity` | String | Clave del período (01-05) |
| `Months` | String | Mes(es) cubiertos (01-12) |
| `Year` | String | Año del período (ej. "2024") |
```json Ejemplo completo theme={null}
{
"NameId": "34",
"Folio": "100",
"Serie": "GLOBAL",
"CfdiType": "I",
"Currency": "MXN",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2024-06-25T12:00:00",
"PaymentConditions": "CREDITO A SIETE DIAS",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "01",
"GlobalInformation": {
"Periodicity": "04",
"Months": "04",
"Year": "2024"
},
"Receiver": {
"Rfc": "XAXX010101000",
"Name": "PUBLICO EN GENERAL",
"CfdiUse": "S01",
"TaxZipCode": "78000",
"FiscalRegime": "616"
},
"Items": [
{
"ProductCode": "10101504",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 116
}
]
}
```
## Reglas importantes
Los tickets de caja registradora que ampara la factura global **no deben
haberse facturado individualmente** a ningún cliente. Si un cliente solicita
factura después, se debe emitir una nota de crédito y una factura
individual.
* El RFC del receptor siempre es `XAXX010101000`
* El Nombre Fiscal debe ser `PUBLICO EN GENERAL`
* El uso del CFDI siempre es `S01`
* El régimen del receptor siempre es `616`
* El monto debe incluir **todas** las ventas del período sin CFDI individual
# Factura Venta a Publico en General
Source: https://facturama.mintlify.app/es/cfdi40/factura-publico-en-general
CFDI a RFC genérico para acreditar las ventas al público en general sin requerir los datos fiscales del cliente.
## ¿Qué es la Factura Venta a Publico en General?
Es una factura que se hace por la venta de un producto o servicio al cliente pero sin usar los datos reales del cliente.
## Estructura del CFDI
```json theme={null}
{
"NameId": "1",
"Folio": "100",
"Serie": "FAC-VPG",
"CfdiType": "I",
"Currency": "MXN",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2024-06-25T12:00:00",
"PaymentConditions": "CREDITO A SIETE DIAS",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "01",
"Receiver": {
"Rfc": "XAXX010101000",
"Name": "VENTA PÚBLICO EN GENERAL",
"CfdiUse": "S01",
"TaxZipCode": "78000",
"FiscalRegime": "616"
},
"Items": [
{
"ProductCode": "10101504",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 116
},
{
"ProductCode": "10101504",
"IdentificationNumber": "001",
"Description": "SERVICIO DE COLOCACION",
"Unit": "NO APLICA",
"UnitCode": "E49",
"UnitPrice": 100.0,
"Quantity": 15.0,
"Subtotal": 1500.0,
"Discount": 0.0,
"TaxObject": "02",
"Taxes": [
{
"Total": 240.0,
"Name": "IVA",
"Base": 1500.0,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 1740.0
}
]
}
```
## Reglas importantes
Este tipo de CFDI debe llevar el RFC genérico `XAXX010101000`, pero el nombre fiscal debe ser diferente al de la factura global («PÚBLICO EN GENERAL»). Usa `VENTA PÚBLICO EN GENERAL`.
* El RFC del receptor siempre es `XAXX010101000`
* El nombre fiscal debe ser `VENTA PÚBLICO EN GENERAL` o el nombre del cliente
* El uso del CFDI siempre es `S01`
* El régimen del receptor siempre es `616`
# Idempotencia de Facturas
Source: https://facturama.mintlify.app/es/cfdi40/idempotencia
Cómo evitar facturas duplicadas en reintentos y errores de red. La cadena original y el sello digital como base de la unicidad de un CFDI.
## El problema de los duplicados
Cuando tu sistema emite una factura y la conexión se cae antes de recibir la respuesta, ¿debes reintentar? Si lo haces sin precauciones, podrías generar dos facturas idénticas ante el SAT.
La idempotencia es la propiedad que garantiza que **enviar la misma solicitud más de una vez produce el mismo resultado**: una sola factura, no varias.
## La base técnica: cadena original y sello
### Cadena Original
El SAT define un formato de concatenación (mediante un XSLT) que convierte todos los campos del CFDI en una sola cadena de texto plano. Esa cadena es la **Cadena Original**.
Incluye, entre otros campos:
* Versión
* Fecha
* Sello
* FormaPago
* NoCertificado
* Certificado
* Subtotal
* Moneda
* Total
* Tipo de Comprobante
* Exportación
* Método de Pago
* LugarExpedición
* Datos del Emisor
* Datos del Receptor
* Conceptos y sus detalles (descripción, cantidad, valor unitario, importe, etc.)
* Impuestos (transferidos y retenidos).
Ejemplo de un fragmento de la cadena original podría tener este aspecto:
```
"OriginalString": "||4.0|100|2025-05-18T12:55:02|30001000000500003416|0|XXX|0|P|01|78000|EKU9003173C9|ESCUELA KEMPER URGATE|601|URE180429TM6|UNIVERSIDAD ROBOTICA ESPAÑOLA|86991|601|CP01|84111506|1|ACT|Pago|0|0|01|2.0|1.25|100.00|16.00|116.00|2018-10-04T00:00:00|03|MXN|1|116.00|126456|11c9536f-6bd0-4c32-9337-f8a73a15b775|1111|45|MXN|1|1|116.00|111.75|4.25|02|100.00|001|Tasa|0.012500|1.25|100|002|Tasa|0.160000|16|001|1.250000|100.000000|002|Tasa|0.160000|16.000000||"
```
### Sello Digital del Emisor
La Cadena Original se procesa con SHA-256 y el resultado se firma con la **llave privada del CSD** del emisor usando RSA:
```
CadenaOriginal → SHA-256 → RSA(CSD privada) → SelloDigital
```
Este sello garantiza tres propiedades:
| Propiedad | Significado |
| ---------------- | ---------------------------------------------- |
| **Integridad** | Nadie alteró el contenido del CFDI |
| **Autenticidad** | El sello pertenece al emisor legítimo |
| **No repudio** | El emisor no puede negar haber emitido el CFDI |
### Validación del PAC
Antes de timbrar, el PAC (Facturama) verifica:
1. La estructura XML es válida (esquemas XSD del SAT)
2. El SelloDigital corresponde al CSD del emisor
3. El CFDI no fue timbrado previamente (unicidad)
Si el mismo XML llega dos veces al PAC, **el segundo intento es rechazado** porque el sello ya fue registrado.
## El UUID como identificador único
El PAC genera un **UUID (Folio Fiscal)** al timbrar. Este UUID es único a nivel nacional y queda registrado en el SAT:
```
6128396f-c09b-4ec6-8699-43c5f7e3b230
```
Es el dato definitivo para identificar un CFDI. No puede repetirse, no puede ser reutilizado y permanece en los registros del SAT aunque el CFDI sea cancelado.
## Cómo funciona la idempotencia en la API Web
La API Web de Facturama (un RFC emisor) tiene tres campos que si **no se especifican**, son generados automáticamente en cada llamada:
| Campo | Comportamiento si se omite |
| ------- | ------------------------------------------ |
| `Date` | Se asigna la fecha y hora actual |
| `Folio` | Se asigna el siguiente número de folio |
| `IdCCP` | Se genera un GUID nuevo (para Carta Porte) |
Si omites estos campos y haces dos llamadas con el mismo JSON, Facturama genera dos CFDIs distintos porque `Date` y `Folio` cambian. **Esto rompe la idempotencia.**
### Cómo implementar idempotencia en API Web
Especifica explícitamente los tres campos antes de enviar: `Folio`, `Date` y para Carta Porte `IdCCP`
```json theme={null}
{
"Date": "2024-01-15T10:30:00",
"Folio": "1001",
"Serie": "A",
"CfdiType": "I",
"PaymentMethod": "PUE",
"PaymentForm": "03",
"Receiver": {
"Rfc": "GOCA880521XY3",
"Name": "González Calderón Antonio",
"CfdiUse": "G03",
"FiscalRegime": "612",
"TaxZipCode": "06600"
},
"Items": [...]
}
```
Con `Date` y `Folio` fijos, el XML resultante es idéntico en todos los reintentos. El PAC detectará el duplicado y rechazará el segundo intento y la API mostrará la factura que ya había sido timbrada previamente con los mismos datos.
Puedes usar el `Folio` como clave de idempotencia en tu base de datos. Si ya existe un CFDI con ese folio, no vuelvas a enviarlo.
## El campo IdCCP
Para CFDIs con complemento **Carta Porte**, existe un campo adicional `IdCCP` que identifica la carta porte:
```
Formato: [C]{3}[a-f0-9A-F]{5}-[a-f0-9A-F]{4}-[a-f0-9A-F]{4}-[a-f0-9A-F]{4}-[a-f0-9A-F]{12}
Ejemplo: CCC1a2b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
```
Si no lo especificas, se genera uno nuevo en cada llamada. Especifícalo para garantizar que el complemento de Carta Porte sea idéntico en los reintentos.
## Cuándo usar la idempotencia
Aplica la estrategia de idempotencia cuando el error es **recuperable por reintento**:
| Situación | ¿Reintentar? |
| ---------------------------------------------- | ------------------------------------------- |
| Error 500 del servidor | Sí, con los mismos campos fijos |
| Timeout de conexión | Sí, con los mismos campos fijos |
| Pérdida de conexión antes de recibir respuesta | Sí, con los mismos campos fijos |
| Error 400 (datos inválidos) | No — el error es en tus datos, no en la red |
| Error 401 / 403 (autenticación) | No — revisa tus credenciales |
Ante un error 5xx o un timeout, **no asumir que la factura no se creó**. Primero consulta si existe un CFDI con ese folio antes de reintentar. Si ya existe, usa el UUID existente.
## Flujo recomendado
```
1. Genera Folio + Date antes de enviar la solicitud
2. Guarda estos campos en tu DB como "en proceso"
3. Envía la solicitud a Facturama
4. Si recibes 201 → guarda el UUID, marca como "completado"
5. Si recibes 400 → error en datos, no reintentar
6. Si recibes 5xx o timeout:
a. Consulta GET /cfdi?type=issued&keyword={folio}
b. Si existe → usa el UUID existente
c. Si no existe → reintenta con los mismos Folio + Date
```
```http theme={null}
GET /cfdi?type=issued&keyword=1001
```
Para API multiemisor se utiliza `type` = `issedLite`
# Impuestos de retención
Source: https://facturama.mintlify.app/es/cfdi40/impuestos-retencion
Tipos de impuestos disponibles en los conceptos, IVA, IVA RET, IVA Exento, ISR
## Impuestos Trasladados
Para los impuestos de tipo traslado debe llevar la bandera `IsRetention` desactivada.
```
"IsRetention": false
```
### IVA
```json theme={null}
"Taxes":
[
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false,
"IsFederalTax": true
}
]
```
### IVA Exento
```json theme={null}
"Taxes":
[
{
"Name": "IVA Exento",
"Rate": 0.0,
"Total": 0.0,
"Base": 100,
"IsRetention": false,
"IsFederalTax": true
}
]
```
### IVA tasa cero
```json theme={null}
"Taxes":
[
{
"Name": "IVA",
"Rate": 0.0,
"Total": 0.0,
"Base": 100,
"IsRetention": false,
"IsFederalTax": true
}
]
```
### IEPS
```json theme={null}
"Taxes":
[
{
"Total": 4.3448,
"Name": "IEPS",
"Base": 54.31,
"Rate": 0.08,
"IsRetention": false,
"IsFederalTax": true,
"IsQuota": false
}
]
```
## Impuestos Retenidos
### IVA RET
```json theme={null}
"Taxes":
[
{
"Name": "IVA RET",
"Rate": 0.106668,
"Total": 10.67,
"Base": 100,
"IsRetention": true,
"IsFederalTax": true
}
]
```
### ISR
```json theme={null}
"Taxes":
[
{
"Total": 1.25,
"Name": "ISR",
"Base": 100,
"Rate": 0.0125,
"IsRetention": true,
"IsFederalTax": true
}
]
```
## Impuestos Locales
Se considera impuesto local a cualquier impuesto que no sea de los conocidos (IVA, IVA RET, IEPS, ISR, etc).
Los impuestos locales, pueden llevar cualquier nombre por ejemplo:
* CEDULAR
* RET ICIC
* RET COL PROF
Se aplican por ejemplo para: Honorarios por impartir clases; Honorarios por Arrendamiento; Factura relacionada a la construcción, etc.
En general para quien requiera impuestos locales.
En la sección de impuestos Taxes, se colocan los nodos necesarios de impuestos locales, tal como se agregaría cualquier otro tipo de impuesto (IVA, IVA RET, etc)
```json theme={null}
"Taxes":
[
{
"Total": 3.12,
"Name": "CEDULAR",
"Base": 100,
"Rate": 0.0312,
"IsRetention": false,
"IsFederalTax": false,
"CalculationType": "Rate"
}
]
```
**Donde**
* `IsRetention`: `false` `||` `true`,
* `IsFederalTax`: `false` `||` `true`,
* `CalculationType`: `Rate` `||` `Total`
# Nota de Credito
Source: https://facturama.mintlify.app/es/cfdi40/nota-de-credito
CFDI de tipo egreso que ampara devoluciones, descuentos y bonificaciones.
Una nota de crédito es un documento fiscal o comercial que sirve para anular, corregir o disminuir el importe de una factura previamente emitida.
### Datos especificos
**Nombre en el PDF**
`NameId`: `2` Nombre "Nota de crédito" de acuerdo al catálogo de nombres del CFDI.
```
"NameId": "2"
```
**Tipo de CFDI**
`CfdiType`: `E` Este campo adquiere el valor de E (Egreso).
```
"CfdiType": "E"
```
**Nodo relación**
`Relations`: Se puede agregar el Nodo Relations para referenciar a un CFDI.
```
"Relations":
{
"Type": "01",
"Cfdis": [
{
"Uuid": "45ab1a98-1709-446a-8759-e45a8d76b557"
}
]
}
```
### Tipos de relación
| 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` |
### Estructura completa del CFDI
```json theme={null}
{
"NameId": "2",
"Currency": "MXN",
"Folio": "100",
"Serie": "NDC",
"CfdiType": "E",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2024-06-25T12:00:00",
"PaymentConditions": "Nota de credito",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "01",
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "G02",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991"
},
"Relations": {
"Type": "01",
"Cfdis": [
{
"Uuid": "45ab1a98-1709-446a-8759-e45a8d76b557"
}
]
},
"Items": [
{
"Quantity": 1,
"ProductCode": "86121500",
"UnitCode": "E48",
"Unit": "Unidad de servicio",
"Description": "Pago inicial del 50% por el desarrollo del sitio web personal.",
"IdentificationNumber": "980000",
"UnitPrice": 500.00,
"Subtotal": 500.00,
"TaxObject": "02",
"Taxes": [
{
"Name": "IVA",
"Rate": 0.16,
"Total": 80,
"Base": 500,
"IsRetention": false,
"IsFederalTax": false
}
],
"Total": 580.00
}
]
}
```
# Otros tipos de CFDI
Source: https://facturama.mintlify.app/es/cfdi40/otros-tipos-cfdi
Emite CFDI en otra moneda, de arrendamiento, a cuenta de terceros y por kits.
## CFDI en otra moneda
```json theme={null}
{
"NameId": "1",
"Folio": "100",
"Serie": "FAC",
"CfdiType": "I",
"Exportation": "01",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2024-06-25T12:00:00",
"PaymentConditions": "CREDITO A SIETE DIAS",
"Observations": "Elemento Observaciones solo visible en PDF",
"CurrencyExchangeRate": 20.55,
"Currency": "USD",
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "CP01",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991"
},
"Items": [
{
"ProductCode": "10101504",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 116
},
{
"ProductCode": "10101504",
"IdentificationNumber": "001",
"Description": "SERVICIO DE COLOCACION",
"Unit": "NO APLICA",
"UnitCode": "E49",
"UnitPrice": 100.0,
"Quantity": 15.0,
"Subtotal": 1500.0,
"Discount": 0.0,
"TaxObject": "02",
"Taxes": [
{
"Total": 240.0,
"Name": "IVA",
"Base": 1500.0,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 1740.0
}
]
}
```
**Donde:**
El elemento `CurrencyExchangeRate` se usa para definir el tipo de cambio según el tipo de moneda a `Currency`.
```json theme={null}
"CurrencyExchangeRate": 20.55,
"Currency": "USD",
```
## CFDI de Arrendamiento
```json theme={null}
{
"NameId": "10",
"Currency": "MXN",
"Folio": "100",
"Serie": "FAC",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2024-06-25T12:00:00",
"PaymentConditions": "CFDI de Arrendamiento",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "01",
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "CP01",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991"
},
"Items": [
{
"ProductCode": "80131500",
"IdentificationNumber": "Renta2023",
"Description": "renta Mensual",
"Unit": "Unidad de servicio",
"UnitCode": "E48",
"UnitPrice": 1500,
"Quantity": 1.0,
"Subtotal": 1500,
"TaxObject": "02",
"Taxes": [
{
"Total": 240,
"Name": "IVA",
"Base": 1500,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 1740.00,
"PropertyTaxIDNumber": [
"123456789"
]
}
]
}
```
**Doinde:**
El elemento `PropertyTaxIDNumbe` se utiliza para especificar el número de cuenta predial.
```json theme={null}
"PropertyTaxIDNumber":
[ "123456789" ]
```
## A cuenta de terceros
```json theme={null}
{
"NameId": "29",
"Folio": "100",
"Serie": "FA",
"CfdiType": "I",
"Currency": "MXN",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2024-06-25T12:00:00",
"PaymentConditions": "CREDITO A SIETE DIAS",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "01",
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "G01",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991"
},
"Items": [
{
"ProductCode": "10101504",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 116,
"ThirdPartyAccount": {
"Rfc": "CACX7605101P8",
"Name": "XOCHILT CASAS CHAVEZ",
"FiscalRegime": "616",
"TaxZipCode": "36257"
}
},
{
"ProductCode": "10101504",
"IdentificationNumber": "001",
"Description": "SERVICIO DE COLOCACION",
"Unit": "NO APLICA",
"UnitCode": "E49",
"UnitPrice": 100.0,
"Quantity": 15.0,
"Subtotal": 1500.0,
"Discount": 0.0,
"TaxObject": "02",
"Taxes": [
{
"Total": 240.0,
"Name": "IVA",
"Base": 1500.0,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 1740.0
}
]
}
```
**Donde:**
Se agrega el elemento `ThirdPartyAccount` dentro del concepto.
```json theme={null}
"ThirdPartyAccount":
{
"Rfc": "CACX7605101P8",
"Name": "XOCHILT CASAS CHAVEZ",
"FiscalRegime": "616",
"TaxZipCode": "36257"
}
```
## Kits
```json theme={null}
{
"NameId": "1",
"Currency": "MXN",
"Folio": "100",
"Serie": "KITS",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2026-04-07T10:14:52",
"PaymentConditions": "CREDITO A SIETE DIAS",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "01",
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "CP01",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991"
},
"Items": [
{
"ProductCode": "27113201",
"Description": "Conjuntos generales de herramientas",
"UnitCode": "KT",
"Quantity": 2,
"UnitPrice": 2000,
"Subtotal": 4000,
"TaxObject":"02",
"Taxes": [
{
"Total": 640,
"Name": "IVA",
"Base": 4000,
"Rate": 0.16,
"IsRetention": false
}
],
"Parts": [
{
"Quantity": 20,
"UnitCode": "H87",
"ProductCode": "41116401",
"IdentificationNumber": "4",
"Description": "Martillos de impacto",
"UnitPrice": 100
},
{
"Quantity": 8,
"UnitCode": "H87",
"ProductCode": "27111701",
"IdentificationNumber": "56jy",
"Description": "Destornillador",
"UnitPrice": 250
}
],
"Total": 4640
}
]
}
```
**Donde:**
Se agrega el elemento `Parts` dentro del concepto.
```json theme={null}
"Parts":
{
"Quantity": 20,
"UnitCode": "H87",
"ProductCode": "41116401",
"IdentificationNumber": "4",
"Description": "Martillos de impacto",
"UnitPrice": 100
}
```
# Validaciones
Source: https://facturama.mintlify.app/es/cfdi40/validaciones
Validación de CFDI, CSF
## Validación del status de CFDI vía API
Es posible consultar el status de una factura ante el SAT y sus condiciones de cancelación, sin importar si esta fue emitida desde Facturama o no.
El uso de este endpoint consume 1 folio por cada petición realizada.
### Endpoint
```http theme={null}
GET /cfdi/status?uuid={folio_fiscal_la_factura}&issuerRfc={rfc_emisor}&receiverRfc={rfc_receptor}&total={total_de_la_factura}
```
Folio fiscal de la factura de la cual se desea verificar el status.
RFC completo del emisor de la factura de la cual se desea verificar el status.
RFC completo del receptor de la factura de la cual se desea verificar el status.
Monto total de la factura de la cual se desea verificar el status, con dos decimales (Incluyendo impuestos).
### Datos de la respuesta
* `Status`: Estado de la factura ante el SAT. Los datos posibles para este campo son: `Vigente`, `Cancelado`, `No encontrado`.
* `IsCancelable`: Leyenda que indica si la factura es cancelable o no, y la condiciones en que sería cancelable. Los valores posibles son `No cancelable`, `Cancelable con aceptación` y `Cancelable sin aceptación`.
* `Uuid`: Mismo `UUID` que se ha ingresado en la petición (corresponde al UUID del comprobante).
```json Response theme={null}
{
"Status": "...",
"IsCancelable": "...",
"Uuid": "..."
}
```
En sandbox no se pueden hacer validaciones de status al SAT por ser ambiente de pruebas, todas las respuestas arrojadas serán simuladas.
## Extraer información de la CSF
El uso de este endpoint consume 1 folio por cada petición realizada.
## Endpoint
```http theme={null}
POST /cif
```
También es necesario agregar la siguiente información en el cuerpo de la petición:
* PDF de la CIF convertido a Base64
* Tipo de validación (Siempre será 0 para la CIF)
Al incorporar estos datos al JSON de la petición, quedarán de la siguiente forma:
```json Body Request theme={null}
{
"CifBase64": "JVBERi0xLjcNCiWhs8XXDQoxID......",
"Type": "0"
}
```
El endpoint no funciona para sandbox , solo en ambiente productivo.
```json Response theme={null}
{
"Rfc": "...",
"TaxName": "...",
"StartOperationsDate": "...",
"StartDate": "...",
"LastStatusChangeDate": "...",
"Status": "...",
"TaxRegimeName": "...",
"TaxRegimeCode": "...",
"Email": "...",
"ZipCode": "...",
"FederalEntity": "...",
"Municipality": "...",
"Suburb": "...",
"RoadName": "...",
"RoadType": "...",
"ExternalNumber": "...",
"InternalNumber": "...",
"CreationDate": "...",
"CapitalRegime": "..."
}
```
**Donde**:
* `RFC`: RFC del contribuyente que se está validando.
* `TaxName`: Nombre fiscal / Razón social del contribuyente que se está validando.
* `StartOperationsDate`: Fecha de inicio de operaciones.
* `LastStatusChangeDate`: Fecha de último cambio de estado.
* `Status`: Estado actual en el padrón del contribuyente que se está validando.
* `TaxRegimeName`: Nombre del régimen fiscal al que pertenece contribuyente que se está validando.
* `TaxRegimeCode`: Código correspondiente al régimen fiscal al que pertenece contribuyente que se está validando.
* `Email`: Email del contribuyente que se está validando, como está registrado ante el padrón.
* `ZipCode`: Código postal del contribuyente que se está validando, como está registrado ante el padrón.
* `FederalEntity`: Nombre de la entidad federativa del contribuyente que se está validando, como está registrado ante el padrón.
* `Municipality`: Nombre del municipio o demarcación territorial del contribuyente que se está validando, como está registrado ante el padrón.
* `Suburb`: Nombre de la colonia del contribuyente que se está validando, como está registrado ante el padrón.
* `RoadName`: Nombre de la vialidad del domicilio del contribuyente que se está validando, como está registrado ante el padrón.
* `RoadType`: Tipo de la vialidad del domicilio del contribuyente que se está validando, como está registrado ante el padrón.
* `ExternalNumber`: Número exterior del domicilio del contribuyente que se está validando, como está registrado ante el padrón.
* `InternalNumber`: Número interior del domicilio del contribuyente que se está validando, como está registrado ante el padrón.
* `CreationDate`: Fecha de creación.
* `CapitalRegime`: Régimen capital del contribuyente que se está validando.
# Carta Porte
Source: https://facturama.mintlify.app/es/complementos/carta-porte
Complemento obligatorio para el traslado de mercancías por carretera federal. Requerido desde junio 2021.
## ¿Qué es la Carta Porte?
La Carta Porte es un complemento del CFDI que acredita el traslado legal de mercancías en territorio nacional. Es **obligatoria** para:
* Transportistas que prestan servicio de traslado de bienes
* Propietarios que transportan sus propias mercancías por carretera federal
Sin Carta Porte, las autoridades pueden detener el transporte y aplicar multas.
## ¿Cuándo se requiere?
| Situación | ¿Requiere Carta Porte? |
| -------------------------------------- | ----------------------- |
| Transporte propio en carretera federal | Sí |
| Servicio de flete / logística | Sí |
| Traslado local (mismo municipio) | No |
| Transporte aéreo o marítimo | Sí (versión específica) |
## Tipo de CFDI a usar
| Caso | CfdiType | Descripción |
| ------------------------------- | -------------- | -------------------------------------- |
| Transportista presta servicio | `I` (Ingreso) | El cliente paga por el flete |
| Propietario traslada sus bienes | `T` (Traslado) | Sin cobro, solo acredita el movimiento |
## Estructura básica
```json theme={null}
{
"NameId": "36",
"Currency": "MXN",
"Folio": "1",
"Serie": "CCP",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2024-06-25T12:00:00",
"PaymentConditions": "CARTA PORTE",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "01",
"Receiver": {
"Rfc": "EKU9003173C9",
"Name": "ESCUELA KEMPER URGATE",
"CfdiUse": "S01",
"FiscalRegime": "601",
"TaxZipCode": "42501"
},
"Items": [
{
"ProductCode": "78101800",
"IdentificationNumber": "UT421511",
"Description": "Transporte de carga por carretera",
"UnitCode": "H87",
"Unit": "Pieza",
"UnitPrice": 100.00,
"Quantity": 1,
"Subtotal": 100.0,
"TaxObject": "01",
"Total": 100.0
}
],
"Complemento": {
"CartaPorte31": {
"IdCCP": "CCCBCD94-870A-4332-A52A-A52AA52AA52A",
"TranspInternac": "No",
"TotalDistRec": "1",
"RegistroISTMO": "Sí",
"UbicacionPoloOrigen": "01",
"UbicacionPoloDestino": "01",
"Ubicaciones": [
{
"TipoUbicacion": "Origen",
"IDUbicacion": "OR101010",
"RFCRemitenteDestinatario": "EKU9003173C9",
"NombreRemitenteDestinatario": "NombreRemitenteDestinatario1",
"FechaHoraSalidaLlegada": "2023-08-01T00:00:00",
"Domicilio": {
"Calle": "Calle1",
"NumeroExterior": "211",
"NumeroInterior": "212",
"Colonia": "1957",
"Localidad": "13",
"Referencia": "casa blanca",
"Municipio": "011",
"Estado": "CMX",
"Pais": "MEX",
"CodigoPostal": "13250"
}
},
{
"TipoUbicacion": "Destino",
"IDUbicacion": "DE202020",
"RFCRemitenteDestinatario": "EKU9003173C9",
"NombreRemitenteDestinatario": "NombreRemitenteDestinatario2",
"FechaHoraSalidaLlegada": "2023-08-01T00:00:01",
"DistanciaRecorrida": "1",
"Domicilio": {
"Calle": "Calle2",
"NumeroExterior": "214",
"NumeroInterior": "215",
"Colonia": "0347",
"Localidad": "23",
"Referencia": "casa negra",
"Municipio": "004",
"Estado": "COA",
"Pais": "MEX",
"CodigoPostal": "25350"
}
}
],
"Mercancias": {
"PesoBrutoTotal": "1.0",
"UnidadPeso": "XBX",
"NumTotalMercancias": "1",
"LogisticaInversaRecoleccionDevolucion": "Sí",
"Mercancia": [
{
"BienesTransp": "11121900",
"Descripcion": "Accesorios de equipo de telefonía",
"Cantidad": "1.0",
"ClaveUnidad": "XBX",
"MaterialPeligroso": "No",
"PesoEnKg": "1",
"DenominacionGenericaProd": "DenominacionGenericaProd1",
"DenominacionDistintivaProd": "DenominacionDistintivaProd1",
"Fabricante": "Fabricante1",
"FechaCaducidad": "2028-01-01",
"LoteMedicamento": "LoteMedic1",
"RegistroSanitarioFolioAutorizacion": "RegistroSanita1",
"CantidadTransporta": [
{
"Cantidad": "1",
"IDOrigen": "OR101010",
"IDDestino": "DE202020"
}
]
}
],
"Autotransporte": {
"PermSCT": "TPAF01",
"NumPermisoSCT": "NumPermisoSCT1",
"IdentificacionVehicular": {
"ConfigVehicular": "VL",
"PesoBrutoVehicular": "1",
"PlacaVM": "plac892",
"AnioModeloVM": "2020"
},
"Seguros": {
"AseguraRespCivil": "AseguraRespCivil",
"PolizaRespCivil": "123456789"
},
"Remolques": [
{
"SubTipoRem": "CTR004",
"Placa": "VL45K98"
}
]
}
},
"FiguraTransporte": [
{
"TipoFigura": "01",
"NombreFigura": "NombreFigura",
"RFCFigura": "EKU9003173C9",
"NumLicencia": "a234567890"
}
]
}
}
}
```
## Catálogos clave para Carta Porte
| Catálogo | Endpoint |
| --------------------------- | --------------------------------------------------- |
| Tipos de permiso SCT | `GET /api/catalogs/cartaporte/TipoPermiso` |
| Configuraciones vehiculares | `GET /api/catalogs/cartaporte/ConfigAutotransporte` |
| Claves de unidad de peso | `GET /api/catalogs/cartaporte/ClaveUnidadPeso` |
| Bienes transportados | `GET /api/catalogs/cartaporte/MaterialPeligroso` |
| Claves de estado | `GET /api/cartaporte/Estado` |
# Comercio Exterior
Source: https://facturama.mintlify.app/es/complementos/comercio-exterior
Complemento para exportaciones de mercancías. Requerido en CFDIs que amparan operaciones de comercio internacional.
## ¿Cuándo se requiere?
El complemento de Comercio Exterior se incluye en CFDIs que amparan **exportaciones definitivas** de bienes fuera del territorio nacional.
Es especialmente relevante para:
* Exportadores que emiten factura comercial al extranjero
* Maquiladoras y empresas IMMEX
* Exportaciones temporales de mercancías
## Tipos de exportación
El campo `Export` en el CFDI indica el tipo:
| Clave | Descripción |
| ----- | ---------------------------------- |
| `01` | No aplica (mercado nacional) |
| `02` | Definitiva con clave A1 |
| `03` | Temporal |
| `04` | Definitiva con clave distinta a A1 |
## Estructura del complemento
```json theme={null}
{
"NameId": "26",
"Currency": "MXN",
"Folio": "100",
"Serie": "COMEXT",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2023-04-10T12:55:02-06:00",
"PaymentConditions": "CREDITO A SIETE DIAS",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "02",
"Receiver": {
"Rfc": "XEXX010101000",
"Name": "Nombre cliente extrangero",
"CfdiUse": "S01",
"FiscalRegime": "616",
"TaxZipCode": "78000",
"TaxRegistrationNumber": "123456789",
"TaxResidence": "USA"
},
"Items": [
{
"IdentificationNumber": "131494-1055",
"Quantity": "2",
"ProductCode": "50211503",
"UnitCode": "H87",
"Unit": "PIEZA",
"Description": "ABACO",
"UnitPrice": "200",
"Subtotal": "400.00",
"TaxObject": "02",
"Taxes": [
{
"Name": "IVA",
"Rate": "0.16",
"Total": "64",
"Base": "400",
"IsRetention": "false"
}
],
"Total": "464.00"
}
],
"Complemento": {
"ForeignTrade": {
"Issuer": {
"Address": {
"Street": "Cañada de Gomez",
"ExteriorNumber": "110",
"InteriorNumber": "A",
"Reference": "-",
"Municipality": "028",
"State": "SLP",
"Country": "MEX",
"ZipCode": "78216"
}
},
"Receiver": {
"Address": {
"Street": "Cañada de Gomez",
"ExteriorNumber": "110",
"InteriorNumber": "A",
"Neighborhood": "0939",
"Locality": "ABC",
"Municipality": "028",
"State": "NT",
"Country": "CAN",
"ZipCode": "M3C 0C1"
}
},
"Commodity": [
{
"SpecificDescriptions": [
{
"Brand": "ACME",
"Model": "Blanco",
"SubModel": "Papel",
"SerialNumber": "4556789542156"
}
],
"IdentificationNumber": "131494-1055",
"TariffFraction": "2402200100",
"CustomsQuantity": "2",
"CustomsUnit": "01",
"CustomsUnitValue": "13.23"
}
],
"RequestCode": "A1",
"OriginCertificate": "true",
"Incoterm": "CFR",
"ExchangeRateUSD": "17.441800",
"TotalUSD": "1",
"OriginCertificateNumber": "20001000000300022817",
"ReliableExporterNumber": null,
"Observations": "sample string 8"
}
}
}
```
## Campos principales
| Campo | Descripción |
| --------------------- | ---------------------------------------------------------- |
| `Incoterm` | Término comercial internacional (DAP, FOB, CIF, EXW, etc.) |
| `TipoCambioUSD` | Tipo de cambio peso/dólar del día de la operación |
| `TotalUSD` | Total de la operación en dólares americanos |
| `FraccionArancelaria` | Clave de 10 dígitos del sistema armonizado |
| `NumRegIdTrib` | Número de identificación fiscal del receptor extranjero |
## RFC para extranjeros
Cuando el receptor es extranjero, usa el RFC genérico `XEXX010101000` y proporciona el número de identificación fiscal en el complemento (`NumRegIdTrib`).
# Complemento de Pago 2.0
Source: https://facturama.mintlify.app/es/complementos/complemento-pago
Emite comprobantes de recepción de pago cuando el cliente paga después de la fecha de la factura (método de pago PPD).
## ¿Cuándo usar el complemento de pago?
Cuando emites una factura con método de pago **PPD (Pago en Parcialidades o Diferido)**, estás indicando que el cliente pagará después. Por cada pago que recibas, debes emitir un **Complemento de Pago**.
```
Factura original (PPD) → Cliente paga → Complemento de Pago
```
Si el cliente paga al momento de la compra, usa **PUE** y no necesitas
complemento de pago.
## Flujo completo
```json theme={null}
{
"CfdiType": "I",
"PaymentMethod": "PPD",
"PaymentForm": "99",
...
}
```
Usa `PaymentForm: "99"` (por definir) cuando aún no sabes cómo pagará el cliente.
Ya sea por transferencia, cheque, tarjeta, etc.
Crea un CFDI de tipo `P` relacionado con la factura original.
Consideraciones a tomar en cuenta en el nodo general del CFDI:
* No incluyas conceptos ni `Items`.
* No incluyas `PaymentMethod`.
* No incluyas `PaymentForm`.
* No incluyas `Currency`.
* `CfdiType` debe ser `"P"` (Pago).
* En el nodo `Receiver`, el atributo `CfdiUse` debe ser `"CP01"`.
## Emitir el complemento de pago
Ejemplo usando API web.
```http theme={null}
POST /3/cfdis
```
```json Ejemplo completo theme={null}
{
"NameId": "14",
"Folio": "1",
"Serie": "CP",
"CfdiType": "P",
"ExpeditionPlace": "78000",
"Date": "2024-06-25T12:00:00",
"Observations": "Elemento Observaciones solo visible en PDF",
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "CP01",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991"
},
"Complemento": {
"Payments": [
{
"Date": "2018-10-04",
"PaymentForm": "03",
"Amount": 116,
"OperationNumber": "126456",
"RelatedDocuments": [
{
"Uuid": "23361131-a0e0-4cf6-85d3-47f37679e874",
"PartialityNumber": 1,
"Serie": "ABC",
"Folio": "99",
"Currency": "MXN",
"PreviousBalanceAmount": 116,
"AmountPaid": 116,
"ImpSaldoInsoluto": 0,
"TaxObject": "02",
"Taxes": [
{
"Name": "IVA",
"Rate": 0.16,
"Total": 16,
"Base": 100,
"IsRetention": false
}
]
}
]
}
]
}
}
```
El valor `NameId: "14"` define el nombre del PDF como "Complemento de pago".
Facturama identifica una operación por la combinación de `Folio` y `Date`. Para evitar comprobantes duplicados, genera ambos valores una sola vez al iniciar la operación y reutilízalos sin cambios en cada reintento. Consulta [Idempotencia y reintentos](/es/cfdi40/idempotencia) para más información.
## Elementos del complemento de pago
Fecha y hora en la que el beneficiario recibe el pago.
Clave de la forma en que se realiza el pago.
Clave de la moneda utilizada para realizar el pago conforme a la especificación ISO 4217.
Tipo de cambio de la moneda a la fecha en que se realizó el pago. Atributo condicional: es requerido cuando `Currency` es distinta de `MXN`.
Importe del pago.
Número de cheque, número de autorización, número de referencia, clave de rastreo en caso de ser SPEI, línea de captura o algún número de referencia análogo que identifique la operación que ampara el pago efectuado.
## Información extra
Clave RFC de la entidad emisora de la cuenta origen, es decir, la operadora, el banco, la institución financiera o el emisor de monedero electrónico. Si la entidad es extranjera, registra `XEXX010101000`.
Número de la cuenta con la que se realizó el pago.
Número de cuenta en donde se recibió el pago.
Nombre del banco ordenante.
Clave RFC de la entidad operadora de la cuenta destino, es decir, la operadora, el banco, la institución financiera o el emisor de monedero electrónico.
## Pagos en moneda extranjera
Si el pago es en USD u otra moneda, usa `Currency` e incluye el tipo de cambio en `ExchangeRate`:
```json theme={null}
"Complemento": {
"Payments": [
{
"Currency": "USD",
"ExchangeRate": 17.5,
"Amount": 300.0
}
]
}
```
## Elementos del documento relacionado
```json theme={null}
"RelatedDocuments": [
{
"Uuid": "23361131-a0e0-4cf6-85d3-47f37679e874",
"PartialityNumber": 1,
"Serie": "ABC",
"Folio": "99",
"Currency": "MXN",
"EquivalenceDocRel": 1,
"PreviousBalanceAmount": 116,
"AmountPaid": 116,
"ImpSaldoInsoluto": 0,
"TaxObject": "02",
"Taxes": [
{
"Name": "IVA",
"Rate": 0.16,
"Total": 16,
"Base": 100,
"IsRetention": false
}
]
}
]
```
Atributo requerido para expresar el identificador del documento relacionado con el pago.
Atributo requerido para expresar el número de parcialidad que corresponde al pago.
Atributo opcional para precisar la serie del comprobante para control interno del contribuyente.
Atributo opcional para precisar el folio del comprobante para control interno del contribuyente.
Atributo requerido para identificar la clave de la moneda utilizada en los importes del documento relacionado.
Atributo condicional para expresar el tipo de cambio conforme con la moneda registrada en el documento relacionado. Es requerido cuando la moneda del documento relacionado es distinta de la moneda de pago.
Atributo requerido para expresar el monto del saldo insoluto de la parcialidad anterior.
Atributo requerido para expresar el importe pagado para el documento relacionado.
Atributo requerido para expresar la diferencia entre el importe del saldo anterior y el monto del pago.
Atributo requerido para expresar si el pago del documento relacionado es objeto o no de impuesto.
Nombre del impuesto aplicado al documento relacionado: `IVA`, `IEPS` o `ISR`.
Tasa o cuota del impuesto, expresada en decimales. Por ejemplo, `0.16` para el IVA del 16%.
Importe del impuesto, resultado de multiplicar `Base` por `Rate`.
Base para el cálculo del impuesto, es decir, el monto del pago sin impuestos.
Indica si el impuesto es una retención (`true`) o un traslado (`false`).
# Complemento de Nómina 1.2
Source: https://facturama.mintlify.app/es/complementos/nomina
Emite recibos de nómina timbrados con percepciones, deducciones, otros pagos e incapacidades usando el complemento de nómina 1.2.
## ¿Cuándo emitir un CFDI de nómina?
Emite un CFDI de nómina por cada pago que hagas a un trabajador por concepto de sueldos, salarios o ingresos asimilados. El comprobante usa `CfdiType: "N"` y lleva el complemento de nómina 1.2 dentro del nodo `Complemento.Payroll`.
```
Periodo de pago → Cálculo de percepciones y deducciones → CFDI de nómina timbrado
```
El complemento de nómina vigente es la versión 1.2 (revisión C). Aplica tanto
para trabajadores subordinados (régimen `02` Sueldos) como para asimilados a
salarios (regímenes `05` a `11`).
## Diferencias con una factura de ingreso
| Elemento | Factura de ingreso | CFDI de nómina |
| ------------------ | ------------------ | ------------------- |
| `CfdiType` | `I` | `N` |
| `Items` | Requerido | No se envía |
| `PaymentMethod` | Requerido | Requerido |
| `PaymentForm` | Requerido | No se registra |
| `Receiver.CfdiUse` | `G01`, `G03`, etc. | `CN01` |
| Complemento | Opcional | `Payroll` requerido |
| Tipo de consulta | `issued` | `payroll` |
El nodo `Items` **no se envía** en un CFDI de nómina. Facturama construye el
concepto a partir de los totales del complemento. Enviar conceptos provoca un
error de validación.
## Endpoint
```http theme={null}
POST /3/cfdis
```
[Consulta las referencias API](/api-reference/endpoint/factura-cfdi/crea-un-cfdi-de-emision)
## Estructura del CFDI de nómina
```json Datos generales theme={null}
"NameId": "16",
"Folio": "",
"Serie": "",
"CfdiType": "N",
"PaymentMethod": "PUE",
"ExpeditionPlace": "",
"Date": "",
```
```json Datos del receptor theme={null}
"Receiver":
{
"Rfc": "",
"CfdiUse": "CN01",
"Name": "",
"FiscalRegime": "605",
"TaxZipCode": ""
}
```
```json Complemento de nómina theme={null}
"Complemento":
{
"Payroll": {
"Type": "",
"PaymentDate": "",
"InitialPaymentDate": "",
"FinalPaymentDate": "",
"DaysPaid": 0.0,
"Issuer": {},
"Employee": {},
"Perceptions": {},
"Deductions": {},
"OtherPayments": [],
"Incapacities": []
}
}
```
```json Emisor theme={null}
"Issuer":
{
"EmployerRegistration": "",
"FromEmployerRfc": "",
"Curp": "",
"EntitySNCF" :
{
"OriginSource" : "",
"AmountOriginSource" : ""
}
}
```
```json Empleado theme={null}
"Employee":
{
"Curp": "",
"SocialSecurityNumber": "",
"StartDateLaborRelations": "",
"ContractType": "",
"Unionized": false,
"TypeOfJourney": "",
"RegimeType": "",
"EmployeeNumber": "",
"Department": "",
"Position": "",
"PositionRisk": "",
"FrequencyPayment": "",
"Bank": "",
"BankAccount": "",
"BaseSalary": 0.0,
"DailySalary": 0.0,
"FederalEntityKey": ""
}
```
```json Percepciones theme={null}
"Perceptions":
{
"Details": [
{
"PerceptionType": "",
"Code": "",
"Description": "",
"TaxedAmount": 0.0,
"ExemptAmount": 0.0
}
]
}
```
```json Deducciones theme={null}
"Deductions":
{
"Details": [
{
"DeduccionType": "",
"Code": "",
"Description": "",
"Amount": 0.0
}
]
}
```
```json Otros pagos theme={null}
"OtherPayments": [
{
"OtherPaymentType": "",
"Code": "",
"Description": "",
"Amount": 0.0
}
]
```
```json Incapacidades theme={null}
"Incapacities": [
{
"Days": 0,
"Type": "",
"Amount": 0.0
}
]
```
## Ejemplo completo
Recibo quincenal de un trabajador subordinado con sueldo y vales de despensa:
```json theme={null}
{
"NameId": "16",
"Folio": "1",
"Serie": "NOM",
"CfdiType": "N",
"ExpeditionPlace": "78000",
"PaymentMethod": "PUE",
"Date": "2026-08-15T12:00:00",
"Receiver": {
"Rfc": "CACX7605101P8",
"CfdiUse": "CN01",
"Name": "XOCHILT CASAS CHAVEZ",
"FiscalRegime": "605",
"TaxZipCode": "36257"
},
"Complemento": {
"Payroll": {
"Type": "O",
"PaymentDate": "2026-08-15",
"InitialPaymentDate": "2026-08-01",
"FinalPaymentDate": "2026-08-15",
"DaysPaid": 15,
"Issuer": {
"EmployerRegistration": "B5510768108"
},
"Employee": {
"Curp": "CACX760510MDFSHX09",
"SocialSecurityNumber": "12345678903",
"StartDateLaborRelations": "2021-03-01",
"ContractType": "01",
"Unionized": false,
"TypeOfJourney": "01",
"RegimeType": "02",
"EmployeeNumber": "00042",
"Department": "Administración",
"Position": "Analista de sistemas",
"PositionRisk": "1",
"FrequencyPayment": "04",
"Bank": "002",
"BankAccount": "1234567890123456",
"BaseSalary": 500.00,
"DailySalary": 512.50,
"FederalEntityKey": "SLP"
},
"Perceptions": {
"Details": [
{
"PerceptionType": "001",
"Code": "P001",
"Description": "Sueldo",
"TaxedAmount": 7500.00,
"ExemptAmount": 0.00
},
{
"PerceptionType": "029",
"Code": "P029",
"Description": "Vales de despensa",
"TaxedAmount": 0.00,
"ExemptAmount": 500.00
}
]
},
"Deductions": {
"Details": [
{
"DeduccionType": "001",
"Code": "D001",
"Description": "Seguridad social",
"Amount": 216.35
},
{
"DeduccionType": "002",
"Code": "D002",
"Description": "ISR retenido",
"Amount": 1052.28
}
]
}
}
}
}
```
Consideraciones del nodo general en un CFDI de nómina:
* `CfdiType` debe ser `"N"`.
* No incluyas `Items`.
* No incluyas `PaymentForm`: conforme al Anexo 20, este atributo no se registra cuando el tipo de comprobante es `N`.
* `Currency` debe ser `"MXN"`.
* En el nodo `Receiver`, el atributo `CfdiUse` debe ser `"CN01"`.
* En el nodo `Receiver`, el atributo `FiscalRegime` normalmente es `605` (Sueldos y Salarios e Ingresos Asimilados a Salarios).
## Elementos del complemento de nómina
### Nodo Payroll
Tipo de nómina. Usa `O` para nómina ordinaria y `E` para nómina extraordinaria.
Fecha efectiva de erogación del pago, en formato `YYYY-MM-DD`.
Fecha inicial del periodo de pago.
Fecha final del periodo de pago. Debe ser igual o posterior a `InitialPaymentDate`.
Número de días o fracción que cubre el pago. Acepta hasta tres decimales.
Datos del patrón. Ver [Nodo Issuer](#nodo-issuer).
Datos del trabajador. Ver [Nodo Employee](#nodo-employee).
Percepciones del periodo. Ver [Nodo Perceptions](#nodo-perceptions).
Deducciones aplicadas al trabajador. Ver [Nodo Deductions](#nodo-deductions).
Pagos que no se consideran ingreso por sueldos, como el subsidio para el empleo o los viáticos entregados.
Incapacidades que aplican en el periodo.
### Nodo Issuer
Registro patronal ante el IMSS. Requerido cuando el trabajador está sujeto al régimen obligatorio de seguridad social.
RFC del patrón origen. Se registra en casos de subcontratación laboral o cuando pagas por cuenta de otro patrón.
CURP del patrón cuando es persona física. Debe tener 18 caracteres.
Nodo para entidades y dependencias que aplican el Sistema Nacional de Coordinación Fiscal. Contiene `OriginSource` (`IP`, `IM` o `IF`) y `AmountOriginSource`.
### Nodo Employee
CURP del trabajador. Exactamente 18 caracteres.
Clave del tipo de contrato conforme al catálogo `c_TipoContrato`.
Clave del régimen de contratación conforme al catálogo `c_TipoRegimen`.
Número interno del trabajador. Hasta 15 caracteres, sin el carácter `|`.
Periodicidad de pago conforme al catálogo `c_PeriodicidadPago`.
Clave de la entidad federativa donde el trabajador prestó sus servicios, conforme al catálogo `c_Estado`.
Número de seguridad social del trabajador. Requerido cuando el régimen es `02` Sueldos.
Fecha de inicio de la relación laboral, en formato `YYYY-MM-DD`.
Indica si el trabajador está sindicalizado.
Tipo de jornada conforme al catálogo `c_TipoJornada`.
Departamento o área del trabajador. Hasta 100 caracteres.
Puesto asignado al trabajador. Hasta 100 caracteres.
Clase de riesgo de puesto conforme al catálogo `c_RiesgoPuesto`.
Clave del banco donde depositas la nómina, conforme al catálogo de bancos.
Número de cuenta o CLABE. Entre 10 y 18 dígitos.
Salario base de cotización.
Salario diario integrado.
Nodo para subcontratación laboral. Cada elemento contiene `RfcContractor` y `PercentageTime` (entre `0.001` y `100`).
### Nodo Perceptions
Lista de percepciones del periodo.
Clave del tipo de percepción conforme al catálogo `c_TipoPercepcion`.
Clave de control interno de la percepción. Entre 3 y 15 caracteres.
Concepto de la percepción. Hasta 100 caracteres.
Importe gravado de la percepción.
Importe exento de la percepción.
Detalle de horas extra. Cada elemento contiene `Days`, `HoursType`, `ExtraHours` y `PaidAmount`.
Nodo para ingresos en acciones o títulos valor. Contiene `MarketValue` y `PriceWhenGranting`.
Nodo para jubilaciones, pensiones o haberes de retiro. Contiene `TotalASinglePayment`, `TotalParciality`, `DailyAmount`, `AccumulatedIncome` y `NonAccumulatedIncome`.
Nodo para pagos por separación. Contiene `TotalPaid`, `YearsOfService`, `LastMonthlySalaryOrd`, `AccumulatedIncome` y `NonAccumulatedIncome`.
### Nodo Deductions
Clave del tipo de deducción conforme al catálogo `c_TipoDeduccion`.
Clave de control interno de la deducción. Entre 3 y 15 caracteres.
Concepto de la deducción. Hasta 100 caracteres.
Importe de la deducción. El valor mínimo es `0.01`.
### Nodo OtherPayments
Clave del tipo de otro pago conforme al catálogo `c_TipoOtroPago`.
Clave de control interno del pago. Entre 3 y 15 caracteres.
Concepto del pago. Hasta 100 caracteres.
Importe del pago.
Nodo requerido cuando `OtherPaymentType` es `002`. Contiene `Amount` con el subsidio causado.
Nodo requerido cuando `OtherPaymentType` es `004`. Contiene `PositiveBalance`, `Year` y `RemainingPositiveBalance`.
### Nodo Incapacities
Días de incapacidad en el periodo.
Clave del tipo de incapacidad conforme al catálogo `c_TipoIncapacidad`.
Importe del descuento por la incapacidad.
## Casos especiales
### Horas extra
Registra las horas extra como una percepción de tipo `019` con el detalle de días, tipo de horas e importe pagado:
```json theme={null}
{
"PerceptionType": "019",
"Code": "P019",
"Description": "Horas extra",
"TaxedAmount": 250.00,
"ExemptAmount": 750.00,
"ExtraHours": [
{
"Days": 2,
"HoursType": "02",
"ExtraHours": 6,
"PaidAmount": 1000.00
}
]
}
```
`HoursType` usa `01` para horas dobles, `02` para triples y `03` para simples.
### Incapacidades
Cuando el trabajador tiene días de incapacidad, agrega el nodo `Incapacities` y la deducción `006` correspondiente:
```json theme={null}
{
"Incapacities": [
{
"Days": 3,
"Type": "02",
"Amount": 900.00
}
],
"Deductions": {
"Details": [
{
"DeduccionType": "006",
"Code": "D006",
"Description": "Descuento por incapacidad",
"Amount": 900.00
}
]
}
}
```
### Subsidio para el empleo
El subsidio se registra en `OtherPayments` con la clave `002` y el nodo `EmploymentSubsidy`:
```json theme={null}
{
"OtherPayments": [
{
"OtherPaymentType": "002",
"Code": "OP002",
"Description": "Subsidio para el empleo",
"Amount": 120.00,
"EmploymentSubsidy": {
"Amount": 120.00
}
}
]
}
```
El importe en `Amount` es el subsidio **efectivamente entregado** al
trabajador, mientras que `EmploymentSubsidy.Amount` es el subsidio causado
conforme a la disposición vigente. Calcula ambos valores con tu sistema de
nómina; la API no los deriva por ti.
### Saldo a favor por compensación anual
Usa la clave `004` en `OtherPayments` junto con el nodo `Compensation`:
```json theme={null}
{
"OtherPaymentType": "004",
"Code": "OP004",
"Description": "Aplicación de saldo a favor por compensación anual",
"Amount": 350.00,
"Compensation": {
"PositiveBalance": 1200.00,
"Year": 2025,
"RemainingPositiveBalance": 850.00
}
}
```
### Pagos por separación
Un finiquito o liquidación es nómina extraordinaria (`Type: "E"`). Agrega la percepción `025` y el nodo `Indemnification`:
```json theme={null}
{
"Type": "E",
"Perceptions": {
"Details": [
{
"PerceptionType": "025",
"Code": "P025",
"Description": "Indemnización",
"TaxedAmount": 18000.00,
"ExemptAmount": 6000.00
}
],
"Indemnification": {
"TotalPaid": 24000.00,
"YearsOfService": 5,
"LastMonthlySalaryOrd": 15000.00,
"AccumulatedIncome": 18000.00,
"NonAccumulatedIncome": 6000.00
}
}
}
```
### Jubilaciones y pensiones
Para jubilaciones, pensiones o haberes de retiro, usa la percepción `039` (pago único) o `044` (parcialidades) junto con el nodo `Retirement`:
```json theme={null}
{
"Perceptions": {
"Details": [
{
"PerceptionType": "039",
"Code": "P039",
"Description": "Jubilación en una sola exhibición",
"TaxedAmount": 30000.00,
"ExemptAmount": 10000.00
}
],
"Retirement": {
"TotalASinglePayment": 40000.00,
"AccumulatedIncome": 30000.00,
"NonAccumulatedIncome": 10000.00
}
}
}
```
### Subcontratación laboral
Cuando el trabajador presta servicios a través de subcontratación, registra los contratantes en `Employee.Outsourcing`:
```json theme={null}
{
"Outsourcing": [
{
"RfcContractor": "EKU9003173C9",
"PercentageTime": 60.00
},
{
"RfcContractor": "URE180429TM6",
"PercentageTime": 40.00
}
]
}
```
La suma de `PercentageTime` de todos los contratantes debe ser `100`.
## Catálogos de nómina
Estos catálogos los define el SAT y pueden cambiar. Verifica los valores
vigentes en el catálogo oficial `catCFDI` publicado por el SAT antes de
liberar a Producción.
| Clave | Descripción |
| ----- | ------------------------------------------------------------------- |
| `O` | Ordinaria. Pago periódico conforme a la relación laboral |
| `E` | Extraordinaria. Finiquito, liquidación, PTU, aguinaldo por separado |
```http theme={null}
GET /catalogs/ContractTypes
```
| 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 |
```http theme={null}
GET /catalogs/regimentypes
```
| Clave | Descripción |
| ----- | ------------------------------------------------------------ |
| `02` | Sueldos |
| `03` | Jubilados |
| `04` | Pensionados |
| `05` | Asimilados miembros de sociedades cooperativas de producción |
| `06` | Asimilados integrantes de sociedades y asociaciones civiles |
| `07` | Asimilados miembros de consejos directivos y de vigilancia |
| `08` | Asimilados comisionistas |
| `09` | Asimilados honorarios |
| `10` | Asimilados acciones |
| `11` | Asimilados otros |
| `12` | Jubilados o pensionados |
| `13` | Indemnización o separación |
| `99` | Otro régimen |
```http theme={null}
GET /catalogs/paymentfrequencies
```
| Clave | Descripción |
| ----- | ----------------- |
| `01` | Diario |
| `02` | Semanal |
| `03` | Catorcenal |
| `04` | Quincenal |
| `05` | Mensual |
| `06` | Bimestral |
| `07` | Unidad de obra |
| `08` | Comisión |
| `09` | Precio alzado |
| `10` | Decenal |
| `99` | Otra periodicidad |
```http theme={null}
GET /catalogs/typesofjourney
```
| Clave | Descripción |
| ----- | ------------ |
| `01` | Diurna |
| `02` | Nocturna |
| `03` | Mixta |
| `04` | Por hora |
| `05` | Reducida |
| `06` | Continuada |
| `07` | Partida |
| `08` | Por turnos |
| `99` | Otra jornada |
```http theme={null}
GET /catalogs/positionrisks
```
| Clave | Descripción |
| ----- | ----------- |
| `1` | Clase I |
| `2` | Clase II |
| `3` | Clase III |
| `4` | Clase IV |
| `5` | Clase V |
| `99` | No aplica |
```http theme={null}
GET /catalogs/perceptions
```
| Clave | Descripción |
| ----- | --------------------------------------------------- |
| `001` | Sueldos, salarios, rayas y jornales |
| `002` | Gratificación anual (aguinaldo) |
| `003` | Participación de los trabajadores en las utilidades |
| `005` | Fondo de ahorro |
| `014` | Subsidios por incapacidad |
| `019` | Horas extra |
| `020` | Prima dominical |
| `021` | Prima vacacional |
| `022` | Prima por antigüedad |
| `025` | Indemnizaciones |
| `028` | Comisiones |
| `029` | Vales de despensa |
| `038` | Otros ingresos por salarios |
| `039` | Jubilaciones, pensiones o haberes de retiro |
| `046` | Ingresos asimilados a salarios |
| `050` | Viáticos |
El catálogo `c_TipoPercepcion` completo incluye más de 40 claves.
```http theme={null}
GET /catalogs/deductions
```
| Clave | Descripción |
| ----- | -------------------------------- |
| `001` | Seguridad social |
| `002` | ISR |
| `004` | Otros |
| `005` | Aportaciones a fondo de vivienda |
| `006` | Descuento por incapacidad |
| `007` | Pensión alimenticia |
| `010` | Pago por crédito de vivienda |
| `011` | Pago de abonos INFONACOT |
| `019` | Cuotas sindicales |
| `020` | Ausencia (ausentismo) |
| `022` | Impuestos locales |
El catálogo `c_TipoDeduccion` completo incluye más de 100 claves.
```http theme={null}
GET /catalogs/otherpayments
```
| Clave | Descripción |
| ----- | ------------------------------------------------------------------------------------------------------------------- |
| `001` | Reintegro de ISR pagado en exceso (siempre que no haya sido enterado al SAT) |
| `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 (siempre que no haya sido enterado al SAT) |
| `999` | Pagos distintos a los listados y que no deben considerarse como ingreso por sueldos, salarios o ingresos asimilados |
El catálogo `c_TipoOtroPago` completo incluye 10 claves.
```http theme={null}
GET /catalogs/incapacities
```
| Clave | Descripción |
| ----- | --------------------- |
| `01` | Riesgo de trabajo |
| `02` | Enfermedad en general |
| `03` | Maternidad |
### Consultar el catálogo de bancos
```http theme={null}
GET /catalogs/Banks
```
```json theme={null}
[
{ "Name": "BANAMEX", "Value": "002" },
{ "Name": "BBVA BANCOMER", "Value": "012" },
{ "Name": "SANTANDER", "Value": "014" },
{ "Name": "HSBC", "Value": "021" },
{ "Name": "BANORTE", "Value": "072" },
{ "Name": "STP", "Value": "646" }
]
```
El catálogo `c_Banco` completo incluye más de 100 claves.
## Consultar y descargar el recibo
Los CFDI de nómina usan el tipo `payroll` en lugar de `issued`:
```http theme={null}
GET /cfdi?type=payroll
GET /api/Cfdi/pdf/payroll/{id}
GET /api/Cfdi/xml/payroll/{id}
```
Si consultas con `type=issued` no verás los recibos de nómina. Revisa
[Consultar CFDI](/es/api-web/consultar-cfdi) y
[Descargar documentos](/es/api-web/descargar-documentos).
## Errores comunes
| Error | Causa | Solución |
| ----- | ----------------------------------------------------------- | --------------------------------------------------------- |
| `400` | Enviaste el nodo `Items` en un CFDI con `CfdiType: "N"` | Elimina `Items`. Los importes salen del complemento |
| `400` | `Curp` con formato inválido o distinta de 18 caracteres | Verifica la CURP del trabajador contra el formato oficial |
| `400` | `SocialSecurityNumber` ausente con `RegimeType: "02"` | Registra el número de seguridad social del trabajador |
| `400` | `FinalPaymentDate` anterior a `InitialPaymentDate` | Corrige las fechas del periodo |
| `400` | Suma de `PercentageTime` en `Outsourcing` distinta de `100` | Ajusta los porcentajes de los contratantes |
| `400` | `Amount` de una deducción menor a `0.01` | Omite la deducción en lugar de enviarla en cero |
| `401` | Credenciales incorrectas o de otro ambiente | Usa las credenciales del ambiente correspondiente |
| `422` | El total de deducciones excede el total de percepciones | Revisa el cálculo de nómina antes de timbrar |
| `500` | Error no controlado del servicio | Contacta a soporte con el `Folio` y la fecha del intento |
## Siguientes pasos
Cancela un recibo de nómina timbrado por error.
Obtén el PDF y el XML del recibo para entregarlo al trabajador.
Consulta las claves vigentes directamente desde la API.
Entiende cuándo aplica cada tipo de CFDI.
# Retenciones e información de pagos
Source: https://facturama.mintlify.app/es/complementos/retenciones
Comprobantes fiscales para retenciones de ISR e IVA. Obligatorio para plataformas tecnológicas, arrendamiento y servicios financieros.
## ¿Qué son las retenciones?
Los comprobantes de retención son documentos fiscales independientes del CFDI de ingreso. Se emiten para informar al SAT sobre retenciones de impuestos efectuadas a terceros.
## Casos de uso más comunes
| Caso | Descripción |
| ---------------------------- | ------------------------------------------------------------------------------ |
| **Plataformas tecnológicas** | UBER, Airbnb, Rappi, MercadoLibre deben reportar retenciones a sus prestadores |
| **Intereses** | Instituciones financieras retienen ISR sobre intereses |
## Emitir un comprobante de retención
```http theme={null}
POST /2/retenciones
```
### JSON base
```json theme={null}
{
"FolioInt": "0001",
"FechaExp": "2024-04-17T12:00:01",
"CveRetenc": "01",
"LugarExpRetenc": "78000",
"Emisor": {
"RFCEmisor": "EKU9003173C9",
"NomDenRazSocE": "ESCUELA KEMPER URGATE",
"RegimenFiscalE": "601"
},
"Receptor": {
"Nacionalidad": "Nacional",
"Nacional": {
"RFCRecep": "CACX7605101P8",
"NomDenRazSocR": "XOCHILT CASAS CHAVEZ",
"DomicilioFiscalR": "36257"
}
},
"Periodo": {
"MesIni": "01",
"MesFin": "01",
"Ejerc": "2023"
},
"Totales": {
"montoTotOperacion": "1681.06",
"montoTotGrav": "1681.06",
"montoTotExent": "0.00",
"montoTotRet": "151.29",
"ImpRetenidos": [
{
"BaseRet": "1681.06",
"Impuesto": "01",
"MontoRet": "16.81",
"TipoPagoRet": "04"
},
{
"BaseRet": "268.96",
"Impuesto": "02",
"MontoRet": "134.48",
"TipoPagoRet": "01"
}
]
}
}
```
### Ejemplo — Plataforma tecnológica
```json theme={null}
{
"FolioInt": "0001",
"FechaExp": "2024-04-17T12:00:01",
"CveRetenc": "26",
"LugarExpRetenc": "78180",
"Emisor": {
"RFCEmisor": "EKU9003173C9",
"NomDenRazSocE": "ESCUELA KEMPER URGATE",
"RegimenFiscalE": "601"
},
"Receptor": {
"Nacionalidad": "Nacional",
"Nacional": {
"RFCRecep": "CACX7605101P8",
"NomDenRazSocR": "XOCHILT CASAS CHAVEZ",
"DomicilioFiscalR": "36257"
}
},
"Periodo": {
"MesIni": "01",
"MesFin": "01",
"Ejerc": "2024"
},
"Totales": {
"montoTotOperacion": "1681.06",
"montoTotGrav": "1681.06",
"montoTotExent": "0.00",
"montoTotRet": "151.29",
"ImpRetenidos": [
{
"BaseRet": "1681.06",
"Impuesto": "01",
"MontoRet": "16.81",
"TipoPagoRet": "03"
},
{
"BaseRet": "268.96",
"Impuesto": "02",
"MontoRet": "134.48",
"TipoPagoRet": "01"
}
]
},
"Complemento": {
"ServiciosPlataformasTecnologicas": {
"Servicios": [
{
"ImpuestosTrasladadosdelServicio": {
"Base": "1681.06",
"Impuesto": "02",
"TipoFactor": "Tasa",
"TasaCuota": "0.160000",
"Importe": "268.9696"
},
"ComisionDelServicio": {
"Base": "1681.06",
"Importe": "14.66"
},
"FormaPagoServ": "02",
"TipoDeServ": "05",
"FechaServ": "2024-01-01",
"PrecioServSinIva": "1681.06"
}
],
"Periodicidad": "02",
"NumServ": 1,
"MontToServSIva": "1681.06",
"TotalIvaTrasladado": "268.9696",
"TotalIvaRetenido": "134.48",
"TotalIsrRetenido": "16.81",
"DifIvaEntregadoPrestServ": "134.4896",
"MonTotalporUsoPlataforma": "14.66"
}
}
}
```
## Tipos de servicio para plataformas tecnológicas
| Clave | Descripción |
| ----- | ----------------------------------------------- |
| `01` | Prestación de servicios de transporte |
| `02` | Servicios de hospedaje |
| `03` | Enajenación de bienes y prestación de servicios |
### Complemento de Intereses
```json theme={null}
{
"FolioInt": "0001",
"FechaExp": "2024-04-17T12:00:01",
"CveRetenc": "01",
"LugarExpRetenc": "78000",
"Emisor": {
"RFCEmisor": "EKU9003173C9",
"NomDenRazSocE": "ESCUELA KEMPER URGATE",
"RegimenFiscalE": "601"
},
"Receptor": {
"Nacionalidad": "Nacional",
"Nacional": {
"RFCRecep": "CACX7605101P8",
"NomDenRazSocR": "XOCHILT CASAS CHAVEZ",
"DomicilioFiscalR": "36257"
}
},
"Periodo": {
"MesIni": "01",
"MesFin": "01",
"Ejerc": "2023"
},
"Totales": {
"montoTotOperacion": "1681.06",
"montoTotGrav": "1681.06",
"montoTotExent": "0.00",
"montoTotRet": "151.29",
"ImpRetenidos": [
{
"BaseRet": "1681.06",
"Impuesto": "01",
"MontoRet": "16.81",
"TipoPagoRet": "04"
},
{
"BaseRet": "268.96",
"Impuesto": "02",
"MontoRet": "134.48",
"TipoPagoRet": "01"
}
]
},
"Complemento": {
"Intereses": {
"Version": "1.0",
"SistFinanciero": "SI",
"RetiroAORESRetInt": "NO",
"OperFinancDerivad": "SI",
"MontIntNominal": 134.48,
"MontIntReal": 16.81,
"Perdida": 100
}
}
}
```
## Consultar una retención emitida
```http theme={null}
GET /Retenciones/{id} # detalle por ID
```
## Descargar documentos de retención
```http theme={null}
GET /api/retenciones/{id}/{format} # format: pdf | xml | html
```
## Cancelar una retención
```http theme={null}
DELETE /Retenciones/{id}?motive={motive}&uuidReplacement={uuid}
```
| Clave | Motivo |
| ----- | ------------------------------------------------------------------------- |
| `01` | Comprobante emitido con errores con relación (requiere `uuidReplacement`) |
| `02` | Comprobante emitido con errores sin relación |
| `03` | No se llevó a cabo la operación |
| `04` | Operación nominativa relacionada en factura global |
Los comprobantes de retención tienen su propio UUID independiente del CFDI de ingreso. Ambos documentos coexisten y se relacionan por el período y el RFC del retenido.
# Anatomía de un CFDI
Source: https://facturama.mintlify.app/es/facturacion/anatomia-cfdi
Disección de los componentes de un CFDI 4.0: emisor, receptor, conceptos, impuestos, cadena original, sello y timbre fiscal.
## Visión general
Un CFDI 4.0 válido está compuesto por varias secciones con responsabilidades claras. Aquí se muestra la estructura de arriba hacia abajo.
## 1. Encabezado del comprobante
Contiene los atributos globales del CFDI:
```json theme={null}
{
"NameId": "1",
"Currency": "MXN",
"Folio": "100",
"Serie": "FA",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"OrderNumber": "TEST-001",
"ExpeditionPlace": "78000",
"Date": "2026-05-15T22:17:44",
"PaymentConditions": "CREDITO A SIETE DIAS",
"Observations": "Elemento Observaciones solo visible en PDF",
"Exportation": "01"
}
```
| Campo | Descripción |
| ------------------- | ------------------------------------------------------------------------------ |
| `NameId` | Nombre que se mostrará en el PDF |
| `CfdiType` | Tipo de CFDI: I, E, T, N, P |
| `Date` | Fecha y hora de emisión (ISO 8601) |
| `PaymentForm` | Clave de forma de pago |
| `PaymentMethod` | PUE o PPD |
| `Currency` | Clave ISO 4217 (MXN, USD, EUR…) |
| `ExpeditionPlace` | CP del lugar de expedición |
| `OrderNumber` | Numero de Orden (opcionales) |
| `PaymentConditions` | Condiciones de pago (opcionales) |
| `Observations` | Observaciones, sólo visible en el PDF (opcionales) |
| `Exportation` | Exportación, elemento usando en Comercio Exterior, por default 01 (opcionales) |
## 2. Emisor
```json theme={null}
{
"Issuer": {
"Rfc": "EKU9003173C9",
"Name": "ESCUELA KEMPER URGATE",
"FiscalRegime": "601"
}
}
```
El emisor es el contribuyente que expide el comprobante. Sus datos vienen del CSD configurado en Facturama — la API los inserta automáticamente; no necesitas especificarlos si usas API Web.
| Campo | Descripción |
| -------------- | ---------------------------------------------------- |
| `Rfc` | Rfc del emisor |
| `Name` | Nombre o Razón Social en mayusculas |
| `FiscalRegime` | Régimen fiscal, tal como está dado de alta en el SAT |
## 3. Receptor
```json theme={null}
{
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "G01",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991"
}
}
```
Ademas del `Rfc`, `Name` y `FiscalRegime`, se añaden dos elementos extras `CfdiUse` y `TaxZipCode` todos estos elementos son obligatorios para el receptor.
| Campo | Descripción |
| ------------ | ------------------------------------- |
| `CfdiUse` | Debe ser de acuerdo al régimen fiscal |
| `TaxZipCode` | Código postal del receptor |
## 4. Conceptos (Items)
La lista de bienes o servicios facturados:
```json theme={null}
{
"Items": [
{
"ProductCode": "81111500",
"IdentificationNumber": "EDL",
"Description": "Servicio de desarrollo de software",
"Unit": "NO APLICA",
"UnitCode": "E48",
"UnitPrice": 5000.0,
"Quantity": 2,
"Subtotal": 10000.0,
"TaxObject": "02",
"Discount": 0.0,
"Taxes": [
{
"Total": 1600.0,
"Name": "IVA",
"Base": 10000.0,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 11600.0
}
]
}
```
| Campo | Descripción |
| ------------- | ------------------------------------------------ |
| `ProductCode` | Clave del catálogo SAT de productos y servicios |
| `UnitCode` | Clave de unidad de medida del SAT |
| `UnitPrice` | Precio unitario sin impuestos |
| `Subtotal` | `UnitPrice × Quantity` |
| `Total` | `Subtotal + impuestos trasladados − retenciones` |
## 5. Impuestos
Los impuestos se declaran por concepto y se suman en el total del comprobante:
| Impuesto | Tipo | Tasa típica | Nombre |
| -------------- | -------------------- | -------------------- | ------- |
| IVA trasladado | `IsRetention: false` | 16% | IVA |
| IVA retenido | `IsRetention: true` | 10.67% | IVA RET |
| ISR retenido | `IsRetention: true` | Varía | ISR |
| IEPS | `IsRetention: false` | Varía según producto | IEPS |
## 6. Cadena Original y Sello Digital
Antes de enviarlo al PAC, el XML pasa por un proceso criptográfico:
1. **Cadena Original**: concatenación ordenada de los campos del CFDI en formato de texto plano (definida por el SAT en su XSLT)
2. **Hash SHA-256**: resumen criptográfico de la cadena original
3. **Sello Digital**: el hash firmado con la llave privada del CSD del emisor (RSA)
```
CadenaOriginal → SHA-256 → firmado con CSD → SelloDigital
```
Esto garantiza que nadie puede alterar el contenido del CFDI sin invalidar el sello.
## 7. Timbre Fiscal Digital
Una vez que el PAC valida el XML, agrega el **Timbre Fiscal Digital** como complemento:
```xml theme={null}
```
| Campo | Descripción |
| --------------- | ---------------------------------------------------- |
| `UUID` | Folio Fiscal — identificador único nacional del CFDI |
| `FechaTimbrado` | Timestamp del momento exacto del timbrado |
| `SelloCFD` | Sello del emisor (compacto, en Base64) |
| `SelloSAT` | Sello del PAC (acredita el timbrado) |
El UUID es el dato más importante para el seguimiento de facturas. Guárdalo
siempre junto con la factura. Con él puedes verificar el CFDI en el portal del
SAT o iniciar una cancelación.
## Representación impresa (PDF)
El PDF es la **representación visual** del XML, no el documento fiscal en sí. Debe incluir obligatoriamente el código QR con los datos del CFDI para que el receptor pueda verificarlo.
Facturama genera el PDF automáticamente cuando creas un CFDI. Puedes descargarlo con:
```http theme={null}
GET /cfdi/{format}/{type}/{id}
```
**format**: Formato del archivo a obtener (pdf|html|xml).
**type**: Tipo del CFDI. Para API Web, se utiliza issued para facturas de ingreso, egreso y complementos, mientras que se utiliza payroll para los comprobantes de nómina.
**id**: Identificador del documento a cancelar. Lo encontrarás en el campo "Id" en la respuesta de emisión de la factura, o al consultar las facturas emitidas.
# Cancelación y vigencia
Source: https://facturama.mintlify.app/es/facturacion/cancelacion-y-vigencia
Cuándo y cómo se puede cancelar un CFDI, motivos válidos, plazos y el proceso de aceptación por parte del receptor.
## ¿Se puede cancelar una factura?
Sí, pero con restricciones. El SAT regula estrictamente el proceso de cancelación para evitar que los contribuyentes cancelen facturas de forma arbitraria una vez que el receptor ya las dedujo.
## Motivos de cancelación
Desde el esquema de cancelación 2022, **toda cancelación requiere especificar un motivo**:
| Motivo | Clave | Cuándo usarlo |
| -------------------------------------------------- | ----- | --------------------------------------------------- |
| Comprobante emitido con errores con relación | `01` | Error y se emite una factura sustituta |
| Comprobante emitido con errores sin relación | `02` | Error sin sustituto (monto, RFC, etc.) |
| No se llevó a cabo la operación | `03` | La venta o servicio no se concretó |
| Operación nominativa relacionada en factura global | `04` | Se incluye en factura global en lugar de individual |
Con motivo `01`, debes proporcionar el UUID del CFDI sustituto. El SAT enlaza ambos comprobantes y el receptor puede verificar el reemplazo.
## ¿Quién puede cancelar?
Solo el **emisor** puede solicitar la cancelación. El receptor no puede cancelar una factura que recibió.
## Proceso de cancelación
El flujo depende del monto y del tipo de CFDI:
### Cancelación inmediata (sin aceptación del receptor)
Aplica cuando:
* El monto del CFDI es **menor a \$1,000 MXN**
* El receptor tiene el mismo RFC que el emisor (autoconsumo)
* Pasaron **más de 24 horas** desde el timbrado y el receptor no ha descargado el XML
* Han pasado **más de 72 horas** desde el timbrado en cualquier caso
### Cancelación con aceptación del receptor
Si el monto supera \$1,000 MXN y el receptor descargó el XML en las primeras 24 horas:
```
Emisor solicita cancelación
↓
SAT notifica al receptor (buzón tributario)
↓
Receptor tiene 3 días hábiles para:
✓ Aceptar → CFDI se cancela
✗ Rechazar → CFDI permanece vigente
(sin respuesta) → Se cancela automáticamente
```
## Plazo para cancelar
| Período | Plazo |
| ------------------------------ | -------------------------------------- |
| CFDIs del ejercicio en curso | Hasta el 31 de enero del año siguiente |
| CFDIs de ejercicios anteriores | No se pueden cancelar |
Un CFDI de 2023 ya no puede cancelarse en 2025. Si hubo un error, la solución es emitir un CFDI de Egreso (nota de crédito) referenciando el CFDI original.
## Estados de cancelación
Después de solicitar la cancelación, el CFDI puede estar en los siguientes estados:
| Estado | Descripción |
| ---------- | ---------------------------------- |
| `active` | El CFDI está activo y válido |
| `canceled` | El CFDI fue cancelado exitosamente |
| `pending` | Esperando respuesta del receptor |
## Cancelar en Facturama
```http theme={null}
DELETE /cfdi/{id}?type=issued&motive=02
DELETE /cfdi/{id}?type=issued&motive=01&uuidReplacement={uuid-sustituto}
```
El acuse de cancelación (XML firmado por el SAT) queda disponible en:
```http theme={null}
GET /acuse/{format}/{type/{id}}
```
`{format}`: Formato ( pdf | html )
`{type}`: Tipo de comprobante (issed || payroll) para API Multiemisor ( issuedLite )
`{id}`: Identificador unico de la factura
## Vigencia del CFDI
Un CFDI timbrado tiene vigencia fiscal **mientras no sea cancelado**. No caduca por el paso del tiempo. Sin embargo:
* El SAT verifica CFDIs históricos en auditorías
* Los receptores usan el XML para deducir impuestos en la declaración del período
* Un CFDI cancelado después de que el receptor lo dedujo puede generar inconsistencias fiscales y ajustes en la declaración del receptor
# El ecosistema: SAT, PAC y emisores
Source: https://facturama.mintlify.app/es/facturacion/ecosistema
Cómo interactúan el SAT, los Proveedores Autorizados de Certificación y las empresas emisoras en el ciclo de vida de un CFDI.
## Los tres actores del ciclo fiscal
La emisión de un CFDI involucra tres participantes, cada uno con responsabilidades específicas durante el proceso de certificación y registro del comprobante:
```
Facturama → PAC → SAT
```
| Actor | Rol |
| ---------- | ---------------------------------------------------------------------------------------------------------------- |
| **Emisor** | Proporciona la información fiscal del comprobante. El CFDI es firmado con su Certificado de Sello Digital (CSD). |
| **PAC** | Certifica el CFDI, agrega el Timbre Fiscal Digital y lo reporta al SAT. |
| **SAT** | Registra el CFDI como comprobante fiscal válido y publica las reglas fiscales que deben cumplirse. |
## El SAT
El **Servicio de Administración Tributaria** es la autoridad fiscal de México y es responsable de establecer:
* El estándar XML del CFDI (esquemas XSD)
* Las claves válidas para todos los campos (catálogos)
* Las reglas de validación para cada versión del CFDI
* Los procesos de cancelación y verificación
Durante la emisión de un CFDI, la certificación y el envío al SAT siempre se realizan a través de un PAC autorizado.
## El PAC
El **Proveedor Autorizado de Certificación** es una empresa privada acreditada por el SAT para:
1. Validar la estructura del XML del CFDI
2. Verificar que el CFDI cumpla las reglas técnicas y fiscales vigentes, incluyendo la validez del sello digital del emisor
3. Incorporar el complemento **Timbre Fiscal Digital**, que incluye el UUID, el sello digital del SAT, el sello del PAC y otros datos de certificación.
4. Transmitir el CFDI al SAT para su registro
**Facturama**. Al llamar a la API de Facturama para crear un CFDI, Facturama envía el CFDI al PAC para su certificación y devuelve el XML ya timbrado.
El proceso de timbrado es casi instantáneo. La API de Facturama devuelve el XML timbrado en milisegundos. El SAT recibe el reporte en tiempo real.
## El CSD del emisor
Para poder emitir CFDIs, cada empresa necesita un **Certificado de Sello Digital (CSD)**, que se obtiene en el portal del SAT. El CSD es diferente a la e.firma (antes FIEL). Ambos certificados son emitidos por el SAT, pero tienen propósitos distintos y no son intercambiables.
| Certificado | Uso |
| ------------------ | ------------------------------- |
| **e.firma (FIEL)** | Trámites personales ante el SAT |
| **CSD** | Firma de CFDIs |
Una vez cargado el CSD en la cuenta de Facturama, éste se utiliza automáticamente para firmar los CFDIs emitidos desde la API.
## Flujo completo de un CFDI
```
1. Tu sistema genera el JSON del CFDI
↓
2. Tu aplicación envía el JSON a la API de Facturama (POST /api/3/cfdis)
↓
3. Facturama genera el XML del CFDI a partir del JSON recibido y lo firma utilizando el CSD configurado para el emisor
↓
4. Facturama realiza validaciones preliminares antes de enviar el CFDI al PAC para su certificación
↓
5. El PAC certifica el CFDI, asigna un UUID e incorpora el Timbre Fiscal Digita
↓
6. El PAC reporta el CFDI al SAT y devuelve el XML certificado a Facturama
↓
7. Facturama devuelve la respuesta de la API con el UUID del CFDI, el XML timbrado y, si aplica, la representación impresa en PDF
```
## Ambientes disponibles
Facturama ofrece dos ambientes separados:
| Ambiente | URL base | CFDIs |
| -------------- | --------------------------------- | --------------------------------------------------------------------------------- |
| **Sandbox** | `https://apisandbox.facturama.mx` | Prueba — no tienen validez fiscal |
| **Producción** | `https://api.facturama.mx` | Producción — los CFDIs certificados son reportados al SAT y tienen validez fiscal |
Las credenciales son distintas para cada ambiente. El CSD de prueba también difiere del CSD productivo.
# El RFC
Source: https://facturama.mintlify.app/es/facturacion/el-rfc
El Registro Federal de Contribuyentes identifica a cada entidad fiscal en México. Aprende su estructura, cómo validarlo y los RFC genéricos que usa Facturama.
## ¿Qué es el RFC?
El **Registro Federal de Contribuyentes (RFC)** es el identificador fiscal único asignado por el SAT a cada persona física o moral en México. Aparece tanto en el emisor como en el receptor de cada CFDI.
Sin un RFC válido no es posible emitir ni recibir facturas electrónicas.
## Estructura del RFC
### Personas Morales (empresas)
```
AAA + AAMMDD + HHH
│ │ └── 3 caracteres alfanuméricos de homoclave
│ └────────── Fecha de constitución (año, mes, día)
└────────────────── 3 letras iniciales de la razón social
```
**Ejemplo:** `FAC930701ABC` — empresa Facturama constituida el 1 julio de 1993.
Total: **12 caracteres**
### Personas Físicas (individuos)
```
AAAA + AAMMDD + HHH
│ │ └── 3 caracteres de homoclave
│ └──────────── Fecha de nacimiento (año, mes, día)
└──────────────────── 4 letras: primer apellido (2) + segundo apellido (1) + nombre (1)
```
**Ejemplo:** `GOCA880521XY3` — persona nacida el 21 mayo de 1988.
Total: **13 caracteres**
## RFC genéricos
El SAT define RFC genéricos para situaciones especiales:
| RFC | Cuándo usarlo |
| --------------- | ----------------------------------------------------------------- |
| `XAXX010101000` | Ventas al **público en general** (sin RFC específico del cliente) |
| `XEXX010101000` | Receptor **extranjero** (sin RFC mexicano) |
Estos RFC genéricos tienen validez fiscal y son los únicos aceptados en estos escenarios.
## Expresión regular del RFC
Para validar el formato del RFC en tu código:
```
Persona Moral: ^[A-ZÑ&]{3}[0-9]{2}[01][0-9][0-3][0-9][A-Z0-9]{3}$
Persona Física: ^[A-ZÑ&]{4}[0-9]{2}[01][0-9][0-3][0-9][A-Z0-9]{3}$
```
O una expresión que acepta ambos:
```
^[A-ZÑ&]{3,4}[0-9]{2}[01][0-9][0-3][0-9][A-Z0-9]{3}$
```
## Ejemplo de uso en la API
El RFC aparece en múltiples lugares de un CFDI:
```json theme={null}
"Issuer": {
"Rfc": "EKU9003173C9",
"Name": "ESCUELA KEMPER URGATE",
"FiscalRegime": "601"
},
"Receiver": {
"Rfc": "URE180429TM6",
"CfdiUse": "G01",
"Name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"FiscalRegime": "601",
"TaxZipCode": "86991"
}
```
# ¿Qué es el CFDI?
Source: https://facturama.mintlify.app/es/facturacion/que-es-el-cfdi
El Comprobante Fiscal Digital por Internet es el documento electrónico oficial de México para registrar operaciones fiscales ante el SAT.
## Definición
El **CFDI** (Comprobante Fiscal Digital por Internet) es el formato estándar de factura electrónica en México. Todo ingreso, egreso, nómina o traslado de mercancías debe estar respaldado por un CFDI para tener validez fiscal ante el SAT.
No es solo un archivo PDF. Un CFDI es un **archivo XML** con estructura definida por el SAT que incluye una firma digital que garantiza su autenticidad e integridad.
## ¿Cuándo es obligatorio emitir un CFDI?
| Situación | Obligación |
| ---------------------------------------- | -------------------------------- |
| Venta de bienes o servicios | CFDI de Ingreso |
| Devolución o descuento | CFDI de Egreso (nota de crédito) |
| Traslado de mercancías | CFDI de Traslado |
| Pago de nómina a empleados | CFDI de Nómina |
| Cobro de factura pagada en parcialidades | CFDI de Pago |
## Versión vigente: CFDI 4.0
Desde el **1 de enero de 2022** la versión obligatoria es **CFDI 4.0**. Las versiones anteriores (3.3, 3.2) ya no son válidas para nuevas emisiones.
Los cambios más relevantes de CFDI 4.0 respecto a 3.3:
* El régimen fiscal del receptor es obligatorio
* El código postal fiscal del receptor es obligatorio
* Se eliminó el uso `P01` como valor por defecto (ahora va `S01` para público general)
* El nombre del receptor debe coincidir exactamente con el RFC en el SAT
## Estructura básica
Un CFDI está compuesto por:
1. **Datos del emisor** — quién expide el comprobante
2. **Datos del receptor** — quién lo recibe
3. **Conceptos** — los bienes o servicios facturados
4. **Impuestos** — IVA, ISR, IEPS trasladados o retenidos
5. **Complementos** — información adicional según el tipo de operación
6. **Cadena original + Sello digital** — firma criptográfica del emisor
7. **Timbre fiscal digital** — sello del PAC que acredita el timbrado ante el SAT
El UUID (Folio Fiscal) que aparece en el timbre es el identificador único del CFDI a nivel nacional. Es el dato que el SAT usa para verificar la autenticidad del comprobante.
## ¿Qué NO es un CFDI?
* **El PDF no es el CFDI** — es solo una representación impresa. El documento fiscal válido es el XML.
* Un ticket de caja registradora tampoco es un CFDI, aunque sirva como nota de venta interna.
* Un correo con el monto de un servicio no tiene validez fiscal sin el XML timbrado correspondiente.
## Verificación
Cualquier CFDI puede verificarse en el portal del SAT usando su UUID:
```
https://verificacfdi.facturaelectronica.sat.gob.mx/
```
Allí el SAT indica si el comprobante está **Vigente**, **Cancelado** o si simplemente **no existe** en sus registros.
# Tipos de comprobantes fiscales
Source: https://facturama.mintlify.app/es/facturacion/tipos-de-comprobantes
México define cinco tipos de CFDI según el propósito de la operación: Ingreso, Egreso, Traslado, Nómina y Pago.
## Los cinco tipos de CFDI
El campo `CfdiType` determina la naturaleza del comprobante. Cada tipo tiene reglas propias sobre cuándo emitirlo y qué campos son obligatorios.
| Tipo | Clave | Descripción |
| -------- | ----- | -------------------------------------------------------- |
| Ingreso | `I` | Ingresos por venta de bienes o prestación de servicios |
| Egreso | `E` | Devoluciones, descuentos o bonificaciones |
| Traslado | `T` | Acredita el transporte de mercancías |
| Nómina | `N` | Pagos de sueldos, salarios y asimilados |
| Pago | `P` | Recepción de pagos de facturas emitidas en parcialidades |
## Ingreso (I)
El tipo más común. Se emite cuando vendes un bien o prestas un servicio.
```json theme={null}
{
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE"
}
```
**Cuándo usarlo:**
* Factura a un cliente por servicios profesionales
* Venta de productos físicos
* Venta al público en general (factura global)
## Egreso (E)
Funciona como nota de crédito. Reduce o cancela parcialmente el valor de un CFDI de ingreso previo y va relacionado a una factura.
```json theme={null}
{
"CfdiType": "E",
"Relations": {
"Type": "01",
"Cfdis": [{ "Uuid": "UUID_FACTURA_ORIGINAL" }]
}
}
```
**Cuándo usarlo:**
* Devolución total o parcial de una venta
* Descuento aplicado después de emitir la factura original
* Bonificación acordada con el cliente
El CFDI de Egreso debe relacionarse con el CFDI de Ingreso original usando el
tipo de relación `01` (Nota de Crédito).
## Traslado (T)
No representa un ingreso, solo acredita el movimiento legal de mercancías en territorio nacional. Siempre acompaña a la Carta Porte.
```json theme={null}
{
"CfdiType": "T",
"Items": [
{
"ProductCode": "78101800",
"Description": "Transporte de carga por carretera",
"IdentificationNumber": "1123",
"UnitCode": "E48",
"UnitPrice": 0,
"Quantity": 1,
"Subtotal": 0,
"TaxObject": "01",
"Total": 0
}
],
"Complemento": {
"CartaPorte31": {}
}
}
```
**Cuándo usarlo:**
* Propietario que mueve sus propias mercancías entre almacenes
* Transporte sin cobro de flete
## Nómina (N)
Comprobante que el empleador entrega al empleado por cada período de pago. Incluye el complemento de nómina con datos de percepciones, deducciones y retenciones de ISR.
**Requiere:** Complemento de nómina 1.2 con:
* Tipo de nómina (ordinaria/extraordinaria)
* Período de pago
* Percepciones y deducciones detalladas
* RFC del empleado y CURP
```json theme={null}
{
"CfdiType": "N",
"Complemento": {
"Payroll": {}
}
}
```
## Pago (P)
Se emite cuando el cliente paga una factura que se emitió con método de pago **PPD** (Pago en Parcialidades o Diferido). Complementa la factura original sin cancelarla.
**Flujo típico:**
```
1. Emites CFDI de Ingreso con PaymentMethod = "PPD"
2. El cliente paga parcial o totalmente
3. Emites CFDI de Pago referenciando el CFDI original
4. El SAT cruza la información de ambos comprobantes
```
```json Factura de Ingreso en PPD theme={null}
{
"NameId": "1",
"CfdiType": "I",
"PaymentForm": "99",
"PaymentMethod": "PPD",
"Items": [
{
"ProductCode": "10101504",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 116
}
]
}
```
```json Complemento de Pago theme={null}
{
"NameId": "14",
"CfdiType": "P",
"Complemento": {
"Payments": [
{
"RelatedDocuments": [{}]
}
]
}
}
```
Si emites una factura con `PaymentMethod: "PPD"` y el cliente paga de
inmediato, **debes** emitir un CFDI de Pago. No hacerlo genera inconsistencias
fiscales que pueden derivar en multas.
## Métodos y formas de pago
El `PaymentMethod` y el `PaymentForm` son campos distintos:
| Campo | Valores principales |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| `PaymentMethod` | `PUE` = Pago en una sola exhibición / `PPD` = Pago en parcialidades o diferido |
| `PaymentForm` | `01` = Efectivo / `02` = Cheque / `03` = Transferencia / `04` = Tarjeta de crédito / `28` = Tarjeta de débito |
Cuando `PaymentMethod = "PPD"` y no se conoce aún la forma de pago, usa `PaymentForm = "99"` (Por definir).
# Autenticación
Source: https://facturama.mintlify.app/es/guias/autenticacion
Facturama usa HTTP Basic Auth. Tus credenciales son el usuario y contraseña de tu cuenta — no hay API keys adicionales.
## Cómo funciona
Todas las llamadas a la API requieren el header `Authorization` con tus credenciales codificadas en Base64:
```
Authorization: Basic base64(usuario:contraseña)
```
No se generan tokens ni API keys, el mismo usuario y contraseña que usas para entrar al portal de Facturama son los que usas en la API.
## Credenciales por ambiente
| Ambiente | Web | URL API |
| -------------- | -------------------------------------------- | --------------------------------- |
| **Sandbox** | [dev.facturama.mx](https://dev.facturama.mx) | `https://apisandbox.facturama.mx` |
| **Producción** | [app.facturama.mx](https://app.facturama.mx) | `https://api.facturama.mx` |
Las cuentas de sandbox y producción son independientes. No puedes usar las credenciales de una en la otra.
## Ejemplos de autenticación
```bash CURL theme={null}
curl --location 'https://apisandbox.facturama.mx/Client' \
--header 'Authorization: Basic dHVfdXN1YXJpbzp0dV9jb250cmFzZcOxYQ=='
```
```python Python theme={null}
import requests
import base64
usuario = "tu_usuario"
password = "tu_contraseña"
credentials = base64.b64encode(f"{usuario}:{password}".encode()).decode()
headers = {
"Authorization": f"Basic {credentials}",
"Content-Type": "application/json"
}
response = requests.get(
"https://apisandbox.facturama.mx/client",
headers=headers
)
print(response.json())
```
```php PHP theme={null}
console.log(res.data));
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args)
throws IOException, InterruptedException {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(
"https://apisandbox.facturama.mx/Client"
))
.header(
"Authorization",
"Basic dHVfdXN1YXJpbzp0dV9jb250cmFzZcOxYQ=="
)
.GET()
.build();
HttpResponse response = client.send(
request,
HttpResponse.BodyHandlers.ofString()
);
System.out.println("Status: " + response.statusCode());
System.out.println(response.body());
}
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'uri'
url = URI.parse(
'https://apisandbox.facturama.mx/Client'
)
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url.request_uri)
request['Authorization'] =
'Basic dHVfdXN1YXJpbzp0dV9jb250cmFzZcOxYQ=='
response = http.request(request)
puts "Status: #{response.code}"
puts response.body
```
```csharp C# theme={null}
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
using var client = new HttpClient();
client.DefaultRequestHeaders.Add(
"Authorization",
"Basic dHVfdXN1YXJpbzp0dV9jb250cmFzZcOxYQ=="
);
var response = await client.GetAsync(
"https://apisandbox.facturama.mx/Client"
);
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Status: {(int)response.StatusCode}");
Console.WriteLine(content);
}
}
```
## Cómo generar el Base64
Si necesitas calcular manualmente el token lo puedes hacer desde una terminar:
```bash Bash theme={null}
echo -n "usuario:contraseña" | base64
# Resultado: ddHVfdXN1YXJpbzp0dV9jb250cmFzZcOxYQ==
```
```bash PowerShell theme={null}
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("usuario:contraseña"))
# Resultado: ddHVfdXN1YXJpbzp0dV9jb250cmFzZcOxYQ==
```
[Conversor Base64](/es/herramientas/convertir-base64)
Guarda tus credenciales en variables de entorno — nunca las hardcodees en el código fuente.
## Errores de autenticación
| Código | Descripción |
| ------------------ | ----------------------------------- |
| `401 Unauthorized` | Credenciales incorrectas o ausentes |
# Flujo de integración
Source: https://facturama.mintlify.app/es/guias/flujo-integracion
El flujo completo desde la configuración hasta la descarga del CFDI. Entiende cómo encajan todas las piezas.
## El flujo completo para API Web
```
Crear/buscar lugar de expedición → Emitir CFDI → Descargar PDF/XML → Enviar por correo electronico → (Cancelar si aplica)
```
En la práctica, los catálogos de clientes y productos se gestionan por separado y se reutilizan en múltiples facturas. Para la API no es necesario tener un catálogo de clientes o productos para el timbrado ya que esa información se especifica directamente en el JSON de la petición.
## Paso 1 — Gestionar lugares de expedición
Antes de facturar necesitas agregar el lugar de expedición / sucursal de tu negocio, este procedimiento solo se hace una vez.
```http theme={null}
POST /BranchOffice
```
```json theme={null}
{
"Name": "Sucursal principal ",
"Description": "Sucursal de prueba para la emisión de facturas. ",
"Address": {
"Street": "Av Facturación",
"ExteriorNumber": "123",
"InteriorNumber": "",
"Neighborhood": "Contadores",
"ZipCode": "78000",
"Locality": "Localidad",
"Municipality": "San Luis Potosí",
"State": "San Luis Potosí",
"Country": "México"
}
}
```
Guarda el `ZipCode` ya que lo vas a utilizar como lugar de expedición en la petición principal.
## Paso 2 — Emitir el CFDI
```http theme={null}
POST /3/cfdis
```
```json theme={null}
{
"NameId": "1",
"Folio": "100",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"ExpeditionPlace": "78000",
"Date": "2026-06-14T12:00:00",
"Receiver": {
"Rfc": "XAXX010101000",
"Name": "VENTA PÚBLICO EN GENERAL",
"CfdiUse": "S01",
"TaxZipCode": "78000",
"FiscalRegime": "616"
},
"Items": [
{
"ProductCode": "01010101",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 116
}
]
}
```
Guarda el `Id` del **Response** ya que lo vas a utilizar para las siguientes operaciones.
## Paso 3 — Descargar PDF / XML
Una vez emitido, descarga el PDF y XML :
```http theme={null}
GET /Cfdi/{format}/issued/{Id} # format: pdf | xml | html
```
## Paso 4 — Enviar por correo electrónico
Puedes enviar el pdf y xml por correo electrónico:
```http theme={null}
POST /Cfdi?CfdiType=issued&CfdiId={Id}&Email=correo@ejemplo.com.mx
```
## Paso 5 — Cancelación (si aplica)
Cancelación con motivo 02
```http theme={null}
DELETE /cfdi/{id}?type=issued&motive=02
```
Motivos de cancelación:
* `01` — Comprobante emitido con errores con relación
* `02` — Comprobante emitido con errores sin relación
* `03` — No se llevó a cabo la operación
* `04` — Operación nominativa relacionada en la factura global
## API Web vs API Multiemisor
| Característica | API Web | API Multiemisor |
| -------------- | ------------------------ | ----------------------------------------- |
| Emisores | Uno (tu cuenta) | Múltiples RFC |
| CSD | Gestionado por Facturama | Debes subir el CSD de cada emisor |
| Ideal para | Empresas propias | SaaS, marketplaces, contadores |
| Endpoint base | `/api/3/cfdis` | `/api-lite/3/cfdis` o `/api-lite/4/cfdis` |
## Checklist antes de ir a producción
Crea tu cuenta en [app.facturama.mx](https://app.facturama.mx) o Inicia sesión y verifica que tu cuenta tenga una suscripción activa.
Adquiere la anualidad de la API desde el carrito de compras para habilitar el acceso a la API de producción.
Sube tu Certificado de Sello Digital (.cer y .key). Es obligatorio para emitir CFDIs en producción desde la plataforma web o usando la API web.
De `https://apisandbox.facturama.mx` a `https://api.facturama.mx`. El resto del código no cambia.
Emite una factura real de \$1.00 y verifica que aparezca en el portal del SAT.
Implementa reintentos con backoff exponencial para errores 5xx del SAT.
# Tu primera factura
Source: https://facturama.mintlify.app/es/guias/primera-factura
Crea un CFDI de ingreso válido paso a paso. Usaremos el caso más simple: venta al público en general.
## Antes de empezar
Asegúrate de tener:
* Una cuenta en el [sandbox de Facturama](https://dev.facturama.mx/api/registro)
* Tus credenciales (usuario y contraseña)
* Un cliente HTTP (cURL, Postman o el SDK de tu lenguaje)
## El payload mínimo
Este es el JSON mínimo para emitir un CFDI de ingreso al público en general:
```json JSON theme={null}
{
"NameId": "1",
"Folio": "100",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"ExpeditionPlace": "78000",
"Date": "2026-06-14T12:00:00",
"Receiver": {
"Rfc": "XAXX010101000",
"Name": "VENTA PÚBLICO EN GENERAL",
"CfdiUse": "S01",
"TaxZipCode": "78000",
"FiscalRegime": "616"
},
"Items": [
{
"ProductCode": "01010101",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 116
}
]
}
```
## Explicación campo por campo
| Campo | Valor | Descripción |
| ------------------------------ | ------------------------- | ------------------------------------------------------------ |
| `NameId` | `1` | Nombre que se mostrará en el PDF |
| `Folio` | `100` | Se debe especificar el Folio (atributo para control interno) |
| `CfdiType` | `I` | Ingreso (factura de venta) |
| `PaymentForm` | `03` | Transferencia electrónica |
| `PaymentMethod` | `PUE` | Pago en una sola exhibición |
| `ExpeditionPlace` | `78000` | Código postal del emisor |
| `Receiver.Rfc` | `XAXX010101000` | RFC genérico para público general |
| `Receiver.CfdiUse` | `S01` | Sin efectos fiscales (CFDI 4.0) |
| `Receiver.FiscalRegime` | `616` | Sin obligaciones fiscales |
| `Items[].ProductCode` | `01010101` | Clave SAT genérica |
| `Items[].IdentificationNumber` | `ABCD123456` | Número de serie de un producto |
| `Items[].Description` | `Estudios de laboratorio` | Descripción del concepto (1000 caracteres alfanuméricos) |
| `Items[].Unit` | `NO APLICA` | Unidad de medida aplicable al producto |
| `Items[].UnitCode` | `MTS` | Codigo de unidad de medida aplicable al producto |
| `Items[].UnitPrice` | `50.0` | Precio Unitario |
| `Items[].Quantity` | `1` | Cantidad |
| `Items[].Subtotal` | `100` | Subtotal de la operación |
| `Items[].TaxObject` | `02` | Tipo de impuesto |
| `Items[].Total` | `116.0` | Total del concepto |
| `Items[].Taxes.Total` | `16.0` | Total del impuesto |
| `Items[].Taxes.Name` | `IVA` | Nombre del impuesto |
| `Items[].Taxes.Base` | `100.0` | Base del impuesto |
| `Items[].Taxes.Rate` | `.16` | Porcentaje del impuesto |
| `Items[].Taxes.IsRetention` | `false` | Bandera para diferenciar entre retención y traslado |
## Hacer la petición
```bash cURL theme={null}
curl --request POST \
--url https://apisandbox.facturama.mx/3/cfdis \
--header 'Authorization: Basic BASE64_DE_TUS_CREDENCIALES' \
--header 'Content-Type: application/json' \
--data '{
"NameId": "1",
"Folio": "100",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"ExpeditionPlace": "78000",
"Date": "2026-06-14T12:00:00",
"Receiver": {
"Rfc": "XAXX010101000",
"Name": "VENTA PÚBLICO EN GENERAL",
"CfdiUse": "S01",
"TaxZipCode": "78000",
"FiscalRegime": "616"
},
"Items": [
{
"ProductCode": "01010101",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 116
}
]
}'
```
```python Python theme={null}
import requests, base64
creds = base64.b64encode(b"tu_usuario:tu_contraseña").decode()
headers = {"Authorization": f"Basic {creds}", "Content-Type": "application/json"}
payload = {
"NameId": "1",
"Folio": "100",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"ExpeditionPlace": "78000",
"Date": "2026-06-14T12:00:00",
"Receiver": {
"Rfc": "XAXX010101000",
"Name": "VENTA PÚBLICO EN GENERAL",
"CfdiUse": "S01",
"TaxZipCode": "78000",
"FiscalRegime": "616"
},
"Items": [
{
"ProductCode": "01010101",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 116
}
]
}
r = requests.post("https://apisandbox.facturama.mx/3/cfdis", json=payload, headers=headers)
print(r.json())
```
```java Java theme={null}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args)
throws IOException, InterruptedException {
HttpClient client = HttpClient.newHttpClient();
String json = """
{
"NameId": "1",
"Folio": "100",
"CfdiType": "I",
"PaymentForm": "03",
"PaymentMethod": "PUE",
"ExpeditionPlace": "78000",
"Date": "2026-06-14T12:00:00",
"Receiver": {
"Rfc": "XAXX010101000",
"Name": "VENTA PÚBLICO EN GENERAL",
"CfdiUse": "S01",
"TaxZipCode": "78000",
"FiscalRegime": "616"
},
"Items": [
{
"ProductCode": "01010101",
"IdentificationNumber": "EDL",
"Description": "Estudios de laboratorio",
"Unit": "NO APLICA",
"UnitCode": "MTS",
"UnitPrice": 50,
"Quantity": 2.0,
"Subtotal": 100,
"TaxObject": "02",
"Taxes": [
{
"Total": 16,
"Name": "IVA",
"Base": 100,
"Rate": 0.16,
"IsRetention": false
}
],
"Total": 116
}
]
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(
"https://apisandbox.facturama.mx/3/cfdis"
))
.header(
"Authorization",
"Basic BASE64_DE_TUS_CREDENCIALES"
)
.header(
"Content-Type",
"application/json"
)
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse response = client.send(
request,
HttpResponse.BodyHandlers.ofString()
);
System.out.println("Status: " + response.statusCode());
System.out.println(response.body());
}
}
```
```javascript Node.js theme={null}
const axios = require("axios");
const url = "https://apisandbox.facturama.mx/3/cfdis";
const headers = {
"Authorization": "Basic BASE64_DE_TUS_CREDENCIALES",
"Content-Type": "application/json"
};
const data = {
NameId: "1",
Folio: "100",
CfdiType: "I",
PaymentForm: "03",
PaymentMethod: "PUE",
ExpeditionPlace: "78000",
Date: "2026-06-14T12:00:00",
Receiver: {
Rfc: "XAXX010101000",
Name: "VENTA PÚBLICO EN GENERAL",
CfdiUse: "S01",
TaxZipCode: "78000",
FiscalRegime: "616"
},
Items: [
{
ProductCode: "01010101",
IdentificationNumber: "EDL",
Description: "Estudios de laboratorio",
Unit: "NO APLICA",
UnitCode: "MTS",
UnitPrice: 50,
Quantity: 2.0,
Subtotal: 100,
TaxObject: "02",
Taxes: [
{
Total: 16,
Name: "IVA",
Base: 100,
Rate: 0.16,
IsRetention: false
}
],
Total: 116
}
]
};
axios.post(url, data, { headers })
.then(response => {
console.log("Status:", response.status);
console.log(response.data);
})
.catch(error => {
if (error.response) {
console.error("Status:", error.response.status);
console.error(error.response.data);
} else {
console.error(error.message);
}
});
```
```Csharp C# theme={null}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
using var client = new HttpClient();
client.DefaultRequestHeaders.Add(
"Authorization",
"Basic BASE64_DE_TUS_CREDENCIALES"
);
var json = @"
{
""NameId"": ""1"",
""Folio"": ""100"",
""CfdiType"": ""I"",
""PaymentForm"": ""03"",
""PaymentMethod"": ""PUE"",
""ExpeditionPlace"": ""78000"",
""Date"": ""2026-06-14T12:00:00"",
""Receiver"": {
""Rfc"": ""XAXX010101000"",
""Name"": ""VENTA PÚBLICO EN GENERAL"",
""CfdiUse"": ""S01"",
""TaxZipCode"": ""78000"",
""FiscalRegime"": ""616""
},
""Items"": [
{
""ProductCode"": ""01010101"",
""IdentificationNumber"": ""EDL"",
""Description"": ""Estudios de laboratorio"",
""Unit"": ""NO APLICA"",
""UnitCode"": ""MTS"",
""UnitPrice"": 50,
""Quantity"": 2.0,
""Subtotal"": 100,
""TaxObject"": ""02"",
""Taxes"": [
{
""Total"": 16,
""Name"": ""IVA"",
""Base"": 100,
""Rate"": 0.16,
""IsRetention"": false
}
],
""Total"": 116
}
]
}";
var content = new StringContent(
json,
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync(
"https://apisandbox.facturama.mx/3/cfdis",
content
);
var responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Status: {(int)response.StatusCode}");
Console.WriteLine(responseBody);
}
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'uri'
require 'json'
url = URI.parse(
'https://apisandbox.facturama.mx/3/cfdis'
)
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url.request_uri)
request['Authorization'] =
'Basic BASE64_DE_TUS_CREDENCIALES'
request['Content-Type'] = 'application/json'
request.body = {
NameId: "1",
Folio: "100",
CfdiType: "I",
PaymentForm: "03",
PaymentMethod: "PUE",
ExpeditionPlace: "78000",
Date: "2026-06-14T12:00:00",
Receiver: {
Rfc: "XAXX010101000",
Name: "VENTA PÚBLICO EN GENERAL",
CfdiUse: "S01",
TaxZipCode: "78000",
FiscalRegime: "616"
},
Items: [
{
ProductCode: "01010101",
IdentificationNumber: "EDL",
Description: "Estudios de laboratorio",
Unit: "NO APLICA",
UnitCode: "MTS",
UnitPrice: 50,
Quantity: 2.0,
Subtotal: 100,
TaxObject: "02",
Taxes: [
{
Total: 16,
Name: "IVA",
Base: 100,
Rate: 0.16,
IsRetention: false
}
],
Total: 116
}
]
}.to_json
response = http.request(request)
puts "Status: #{response.code}"
puts response.body
```
## Respuesta exitosa
```json theme={null}
{
"Id": "Y61TLX-Ls_ZJFqzjanPN1w2",
"CfdiType": "ingreso",
"Type": "I - ingreso",
"Serie": "FAC",
"Folio": "100",
"Date": "2026-06-14T12:00:00",
"CertNumber": "30001000000500003416",
"PaymentTerms": "03 - Transferencia electrónica de fondos",
"PaymentConditions": "",
"PaymentMethod": "PUE - Pago en una sola exhibición",
"PaymentAccountNumber": "",
"PaymentBankName": "",
"ExpeditionPlace": "78000",
"ExchangeRate": 0.0,
"Currency": "MXN - Peso Mexicano",
"Subtotal": 100.0,
"Discount": 0.0,
"Total": 116.00,
"Observations": "",
"OrderNumber": "",
"Issuer": {
"FiscalRegime": "601 - General de Ley Personas Morales",
"Rfc": "EKU9003173C9",
"TaxName": "ESCUELA KEMPER URGATE",
"Email": "correo@pruebas.com",
"Phone": "9999999999",
"TaxAddress": {
"Street": "Calle de pruebas",
"ExteriorNumber": "123",
"InteriorNumber": "",
"Neighborhood": "Pruebas",
"ZipCode": "42501",
"Municipality": "Pruebas",
"State": "ESTADO DE MEXICO",
"Country": "México"
},
"IssuedIn": {
"Street": "",
"ExteriorNumber": "",
"Neighborhood": "-",
"ZipCode": "78000",
"Municipality": "",
"State": "",
"Country": "MEXICO"
}
},
"Receiver": {
"Rfc": "XAXX010101000",
"Name": "VENTA PÚBLICO EN GENERAL",
"Email": ""
},
"Items": [
{
"ProductCode": "01010101",
"IdentificationNumber": "EDL",
"UnitCode": "MTS",
"Discount": 0.0,
"CuentaPredial": "",
"Quantity": 2.0,
"Unit": "MTS - NO APLICA",
"Description": "Estudios de laboratorio",
"UnitValue": 50.0,
"Total": 100.0
}
],
"Taxes": [
{
"Total": 16.00,
"Name": "IVA",
"Rate": 0.16,
"Type": "transferred"
}
],
"Complement": {
"TaxStamp": {
"Uuid": "51990f08-5e34-4f5f-a188-bd7e23cd220a",
"Date": "2026-06-14T12:00:01",
"CfdiSign": "H+vvJTkUSRCsyaDfzucoO229RwGw9lgZGONNcYbPUm4giPD7IiwCHx7oXRSC...",
"SatCertNumber": "30001000000500003456",
"SatSign": "KEOuC+0zt4O7DFf2APfzafQdWiIGX3RcQynhfhs3l85V+DHT6eULkPSrJBTjl4Tb....",
"RfcProvCertif": "SPR190613I52"
}
},
"Status": "active",
"OriginalString": "||4.0||100|2026-06-14T12:00:00|03|30001000000500003416||100.0|0.0|MXN|116.00|I|01|PUE|78000|EKU9003173C9|ESCUELA KEMPER URGATE|601|XAXX010101000|VENTA PÚBLICO EN GENERAL|78000|616|S01|01010101|EDL|2|MTS|NO APLICA|Estudios de laboratorio|50|100|02|100|002|Tasa|0.160000|16|100.0|002|Tasa|0.160000|16.00|16.00||"
}
```
El campo `Complement.TaxStamp.Uuid` es el **folio fiscal (UUID)** que identifica de forma única tu CFDI ante el SAT.
## Errores comunes
| Error | Causa | Solución |
| ------------------------------------------ | ------------------------ | ---------------------------------------- |
| `401 Unauthorized` | Credenciales incorrectas | Verifica usuario y contraseña |
| `El RFC del receptor no es válido` | RFC mal formado | Usa `XAXX010101000` para público general |
| `El código postal de expedición no existe` | CP inválido | Usa el CP de tu domicilio fiscal real |
| `La clave de producto no existe` | ClaveProdServ inválida | Consulta el catálogo SAT en la API |
# Conversor Base64 para la API
Source: https://facturama.mintlify.app/es/herramientas/convertir-base64
Genera el token de autenticación, convierte tu CSD y tus archivos a Base64, y decodifica las respuestas de la API sin salir del navegador.
Varios campos de la API de Facturama viajan codificados en Base64: el token de autenticación, los archivos del CSD, el XML que se timbra y los archivos que se descargan. Usa las pestañas de abajo para generar y decodificar esas cadenas.
## Qué hace cada pestaña
| Pestaña | Para qué sirve |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| Token de autenticación | Construye el encabezado `Authorization: Basic` a partir de tu usuario y contraseña |
| CSD a Base64 | Convierte el `.cer` y el `.key` en los valores `Certificate` y `PrivateKey`, y arma el cuerpo de la petición |
| Archivo a Base64 | Codifica cualquier archivo: un XML por timbrar, un PDF, un ZIP |
| Base64 a archivo | Decodifica el campo `Content` de una respuesta y lo descarga con el tipo detectado |
| Texto ↔ Base64 | Conversión rápida en ambos sentidos, para pruebas |
**Todo se ejecuta en tu navegador.** Los archivos, las contraseñas y el texto se procesan en tu dispositivo con las APIs nativas del navegador. Facturama no recibe ninguna copia ni almacena nada de lo que conviertas.
**El Base64 no cifra nada, solo cambia el formato.** La cadena de tu `PrivateKey` y tu contraseña son las credenciales con las que se sellan tus CFDI: cualquiera que las obtenga puede emitir facturas a tu nombre. No las pegues en tickets de soporte, chats ni repositorios, y no uses esta herramienta en una computadora compartida.
## Límites conocidos
La herramienta copia la contraseña al cuerpo de la petición, pero no comprueba que sea la correcta para el `.key`. Verificarlo exige descifrar la llave privada, y las llaves del SAT vienen en PKCS#8 cifrado, a menudo con 3DES, que la API de criptografía del navegador no soporta.
Si la API rechaza tu petición al cargar las credenciales, una contraseña incorrecta es una de las causas posibles y esta herramienta no puede descartarla.
Al subir el `.cer` se lee su extensión `keyUsage` para avisarte si en realidad es una FIEL en lugar de un CSD, y se extrae el RFC para prellenar el campo `Rfc` del cuerpo de la petición. Para revisar el certificado a fondo usa el [inspector de CSD](/es/herramientas/validar-csd).
El tipo se deduce de los primeros bytes del archivo: PDF, ZIP, PNG, JPEG, XML, HTML, certificado DER o texto plano. Es una heurística; si el contenido no coincide con ninguna firma conocida se descarga como texto plano. Puedes escribir el nombre y la extensión que quieras.
## Siguientes pasos
Cómo usar el encabezado que acabas de generar en tus peticiones.
Revisa el certificado a fondo antes de cargarlo en la API.
# Estatus del servicio
Source: https://facturama.mintlify.app/es/herramientas/estatus-servicio
Consulta el estado de los servicios de la API de Facturama y el historial de ventanas de mantenimiento.
Estado de los servicios de la API de Facturama. La página se vuelve a consultar cada 60 segundos.
## Qué significa cada estado
| Estado | Qué esperar |
| ------------- | ----------------------------------------------------------------------------------------------------------- |
| Operando | El servicio responde con normalidad |
| Degradado | El servicio responde, pero con lentitud o errores intermitentes. Considera reintentos con espera progresiva |
| Mantenimiento | Ventana de mantenimiento en curso. El servicio puede rechazar peticiones |
| No disponible | El servicio no responde |
| Desconocido | Esta página no pudo confirmar el estado. **No significa que el servicio esté caído** |
**Esta página no sustituye tu propio monitoreo.** Solo refleja lo que se detectó y confirmó: un incidente puede estar en curso antes de aparecer aquí. Diseña tu integración para tolerar errores `5xx` y timeouts con reintentos, no para consultar esta página.
## Mantenimientos programados
Sin ventanas de mantenimiento programadas en este momento.
## Mantenimientos anteriores
Ventana de mantenimiento del SAT, 00:00 – 07:00 CST. No estuvieron disponibles el Portal Contribuyente CFDI, el Portal Contribuyente CFDI de Retenciones ni Verifica CFDI.
Servicios afectados: timbrado CFDI, CFDI de retenciones.
## Siguientes pasos
Cómo reintentar una emisión sin duplicar comprobantes cuando algo falla.
Revisa un comprobante que se timbró durante un incidente.
# Inspector de CSD
Source: https://facturama.mintlify.app/es/herramientas/validar-csd
Revisa el contenido de tu Certificado de Sello Digital: titular, RFC, número de serie y vigencia, sin salir del navegador.
Sube el archivo `.cer` de tu Certificado de Sello Digital (CSD) para confirmar que es un CSD y no una FIEL, y para leer el titular, el RFC, el número de serie y la vigencia que el SAT le asignó.
## Por qué importa distinguir el CSD de la FIEL
El SAT entrega dos tipos de certificado y no son intercambiables. La FIEL (o e.firma) identifica al contribuyente ante el SAT: sirve para trámites y para solicitar el propio CSD. El CSD es el que sella los CFDI.
Ambos llegan como archivos `.cer` con el mismo aspecto, y confundirlos es una de las causas más comunes de fallo al cargar credenciales. La diferencia está en la extensión `keyUsage` del certificado:
| Certificado | `keyUsage` | Para qué sirve |
| -------------- | ------------------------------------------------------ | --------------------------------------- |
| CSD | `digitalSignature`, `nonRepudiation` | Sellar CFDI |
| FIEL / e.firma | Lo anterior más `keyEncipherment` y `dataEncipherment` | Trámites ante el SAT y solicitar el CSD |
Esta herramienta lee esa extensión y te dice cuál subiste.
**Todo se ejecuta en tu navegador.** El certificado se lee en tu dispositivo con las APIs nativas del navegador. Facturama no recibe ninguna copia de tu certificado ni almacena información de él.
**No subas tu archivo `.key` ni tu contraseña aquí.** Esta herramienta solo necesita el `.cer`, que es la parte pública del certificado. Si lo que buscas es convertir el CSD a Base64 para la API, usa el [conversor Base64](/es/herramientas/convertir-base64), que sí necesita la llave y también la procesa en tu navegador.
## Límites conocidos
Comprobar que un `.cer` y un `.key` son pareja exige descifrar la llave privada, y las llaves del SAT vienen en PKCS#8 cifrado, a menudo con 3DES. La API de criptografía del navegador (Web Crypto) no soporta 3DES ni la importación de PKCS#8 cifrado, así que esa verificación no puede hacerse del lado del cliente.
Si tus credenciales fallan al cargarse, sube el `.cer` aquí para descartar que confundiste el CSD con la FIEL, que es la causa más frecuente.
La herramienta lee el contenido del certificado, pero no comprueba que la autoridad certificadora sea realmente el SAT ni consulta listas de revocación. Un certificado autofirmado se leería sin problema.
Si el certificado no incluye `keyUsage`, no hay forma de distinguir un CSD de una FIEL y la herramienta lo dice explícitamente en lugar de adivinar. Los certificados emitidos por el SAT siempre la incluyen.
## Errores frecuentes
| Mensaje | Causa | Solución |
| --------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------- |
| El archivo no parece un certificado X.509 | Subiste el `.key`, un `.pfx` o un archivo que no es certificado | Sube el archivo `.cer` que te entregó el SAT |
| Este archivo es una FIEL / e.firma, no un CSD | Confundiste los dos certificados | Solicita o localiza tu CSD en el portal del SAT |
| El certificado ya expiró | El CSD venció; los CSD del SAT duran cuatro años | Tramita un CSD nuevo antes de seguir timbrando |
| El certificado todavía no entra en vigor | El reloj de tu equipo está desfasado, o el CSD es futuro | Verifica la fecha de tu sistema |
## Siguientes pasos
Verifica que el sello de un comprobante corresponda a este certificado.
Descarga los certificados de prueba del SAT para trabajar en Sandbox.
# Inspector de FIEL
Source: https://facturama.mintlify.app/es/herramientas/validar-fiel
Revisa el contenido de tu FIEL o e.firma: titular, RFC, CURP, número de serie y vigencia, sin salir del navegador.
Sube el archivo `.cer` de tu FIEL (hoy llamada e.firma) para confirmar que es una FIEL y no un CSD, y para leer el titular, el RFC, la CURP si aplica, el número de serie y la vigencia.
## Qué es la FIEL y en qué se diferencia del CSD
La FIEL, o e.firma, es el certificado que identifica al contribuyente ante el SAT. Se usa para trámites y para solicitar los Certificados de Sello Digital. **No sella CFDI**: eso lo hace el CSD.
Los dos certificados llegan como archivos `.cer` indistinguibles a simple vista. La diferencia está en la extensión `keyUsage`:
| Certificado | `keyUsage` | Para qué sirve |
| -------------- | --------------------------------------------------------------------------- | --------------------------------------- |
| FIEL / e.firma | `digitalSignature`, `nonRepudiation`, `keyEncipherment`, `dataEncipherment` | Trámites ante el SAT y solicitar el CSD |
| CSD | Solo `digitalSignature` y `nonRepudiation` | Sellar CFDI |
Cuando la FIEL pertenece a una persona física, su subject suele traer también la CURP del titular. La herramienta la extrae si está presente.
**Todo se ejecuta en tu navegador.** El certificado se lee en tu dispositivo con las APIs nativas del navegador. Facturama no recibe ninguna copia de tu certificado ni almacena información de él.
**No subas tu archivo `.key` ni tu contraseña aquí.** Esta herramienta solo necesita el `.cer`, que es la parte pública del certificado. La llave privada de tu e.firma da acceso a tus trámites ante el SAT: trátala con más cuidado que la del CSD y no la cargues donde no se necesita.
## Límites conocidos
Comprobar que un `.cer` y un `.key` son pareja exige descifrar la llave privada, y las llaves del SAT vienen en PKCS#8 cifrado, a menudo con 3DES. La API de criptografía del navegador (Web Crypto) no soporta 3DES ni la importación de PKCS#8 cifrado, así que esa verificación no puede hacerse del lado del cliente.
La herramienta lee el contenido del certificado, pero no comprueba que la autoridad certificadora sea realmente el SAT ni consulta listas de revocación. Un certificado autofirmado se leería sin problema.
Si el certificado no incluye `keyUsage`, no hay forma de distinguir una FIEL de un CSD y la herramienta lo dice explícitamente en lugar de adivinar. Los certificados emitidos por el SAT siempre la incluyen.
## Errores frecuentes
| Mensaje | Causa | Solución |
| ------------------------------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------- |
| El archivo no parece un certificado X.509 | Subiste el `.key`, un `.pfx` o un archivo que no es certificado | Sube el archivo `.cer` que te entregó el SAT |
| Este archivo es un Certificado de Sello Digital (CSD), no una FIEL | Confundiste los dos certificados | Localiza tu e.firma; suele estar en la carpeta donde guardaste el trámite |
| El certificado ya expiró | La e.firma venció; dura cuatro años | Renueva tu e.firma en el portal del SAT |
| El certificado todavía no entra en vigor | El reloj de tu equipo está desfasado | Verifica la fecha de tu sistema |
## Siguientes pasos
Revisa el Certificado de Sello Digital con el que sellas tus CFDI.
Verifica la estructura y el sello de un comprobante ya timbrado.
# Validador de XML CFDI 4.0
Source: https://facturama.mintlify.app/es/herramientas/validar-xml
Revisa la estructura de un CFDI 4.0 y verifica que el sello digital corresponda al certificado incluido en el XML, sin salir del navegador.
Sube el XML de tu Comprobante Fiscal Digital por Internet (CFDI) 4.0 para revisar su estructura y verificar que el sello digital corresponda al certificado incluido en el timbrado de tu factura electrónica.
## Qué revisa la herramienta
Compara los nodos y atributos del comprobante contra el esquema base `cfdv40.xsd`: `Comprobante`, `InformacionGlobal`, `CfdiRelacionados`, `Emisor`, `Receptor`, `Conceptos` e `Impuestos`.
Reconstruye la cadena original con las reglas de `cadenaoriginal_4_0.xslt` y verifica la firma `RSASSA-PKCS1-v1_5` con SHA-256 contra la llave pública del atributo `Certificado`. Si el sello coincide, el XML no fue alterado después de firmarse.
Muestra emisor, receptor, tipo de comprobante, total y UUID del timbre para que confirmes de un vistazo que abriste el archivo correcto.
**Todo se ejecuta en tu navegador.** La lectura del XML, el cálculo de la cadena original y la verificación criptográfica del CSD ocurren en tu dispositivo con las APIs nativas del navegador. Facturama no recibe ninguna copia de tu factura electrónica ni almacena información del XML.
**La validación es exclusiva de la estructura y del sello.** No confirmamos si el RFC, la razón social, el código postal o el régimen fiscal del emisor o del receptor son correctos, ni el estatus del CFDI ante el SAT (vigente o cancelado). Ese estatus se consulta en el [servicio de verificación de comprobantes del SAT](https://verificacfdi.facturaelectronica.sat.gob.mx/).
## Límites conocidos
La reconstrucción de la cadena original cubre el CFDI base y el complemento de Pagos 2.0. Los demás complementos del XSLT oficial (Carta Porte, Nómina, Comercio Exterior, entre otros) no están implementados, así que sus nodos no aportan nada a la cadena reconstruida.
Cuando el comprobante incluye uno de esos complementos, la herramienta lo advierte y un resultado de "el sello no corresponde" puede ser un falso negativo. La estructura y los datos generales se validan con normalidad.
`cfdi:Addenda` se detecta y se omite de la validación: es un nodo libre que cada receptor define, así que no tiene un esquema contra el cual validar. Los complementos de concepto (`cfdi:ComplementoConcepto`) se listan, pero no se validan contra sus propios esquemas.
La herramienta extrae del atributo `Certificado` el número de serie, el titular, la vigencia y el RFC, y verifica la firma con su llave pública. No comprueba que el certificado lo haya emitido el SAT ni si fue revocado. Un XML firmado con un certificado autofirmado pasaría la verificación del sello.
## Errores frecuentes
| Mensaje | Causa | Solución |
| -------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| El archivo no es un XML bien formado | El archivo está truncado, tiene caracteres inválidos o es un PDF renombrado | Descarga de nuevo el XML desde tu portal o desde el endpoint de descarga |
| El elemento raíz no es `cfdi:Comprobante` | El archivo es un acuse de cancelación, un XML de retenciones o un CFDI 3.3 | Usa el XML del comprobante emitido en CFDI 4.0 |
| Falta el atributo requerido `Comprobante/@Sello` | El XML es un borrador que todavía no se ha timbrado | Timbra el comprobante antes de validarlo |
| El sello NO corresponde a la cadena original | El XML se editó después de timbrarse, o incluye un complemento no soportado | Revisa el aviso de complementos; si no aparece, el archivo fue alterado |
| El número de serie no coincide con `NoCertificado` | El atributo se capturó a mano y no corresponde al CSD que firmó | Genera el comprobante de nuevo tomando el número de serie del propio CSD |
## Siguientes pasos
Entiende qué representa cada nodo del comprobante que acabas de validar.
Descarga los certificados de prueba del SAT para generar comprobantes en Sandbox.