Auto CFDI

Estos endpoints administran Auto CFDI en tu cuenta: la configuración del módulo, que define la vigencia de la autofactura y el aviso de privacidad de tu portal, el nombre de tu portal de autofactura y el reporte de consumo de tickets y créditos. Los tickets tienen su propio recurso, tickets.

Revisa la introducción a Auto CFDI para conocer el flujo, los créditos de ticket, los permisos y las reglas del nombre del portal.

GET/api/v4/auto-invoice/settings

Obtener configuración

Este endpoint devuelve la configuración de Auto CFDI de tu cuenta. Si nunca la guardaste, responde la configuración por omisión: vigencia hasta el fin del mes del pago y sin aviso de privacidad.

Respuesta

Name
allowBillingOutsideMonth
Type
boolean?
Description
true si un ticket pagado en otro mes todavía se puede autofacturar.
Name
allowBillingOutsideYear
Type
boolean?
Description
true si un ticket pagado en otro año todavía se puede autofacturar.
Name
privacyNoticeUrl
Type
string?
Description
URL del aviso de privacidad que muestra tu portal, o null si no la has configurado.

Request

GET

/api/v4/auto-invoice/settings

curl --location 'https://test.fiscalapi.com/api/v4/auto-invoice/settings' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

{
    "data": {
        "allowBillingOutsideMonth": false,
        "allowBillingOutsideYear": false,
        "privacyNoticeUrl": null
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

PUT/api/v4/auto-invoice/settings

Actualizar configuración

Este endpoint reemplaza la configuración completa de Auto CFDI de tu cuenta: un campo que no envías toma su valor por omisión. Solo el owner lo usa y exige Auto CFDI en tu suscripción.

Tu portal atiende a tus clientes cuando tu suscripción incluye Auto CFDI, tienes un nombre de portal y configuraste el aviso de privacidad. Sin alguno de los tres, el portal muestra que no ofreces facturación en línea y no timbra.

Modelo

Name
allowBillingOutsideMonth
Type
boolean?
Description
true para permitir autofacturar un ticket pagado en otro mes. Ver Vigencia de la autofactura.
Default:
false
Name
allowBillingOutsideYear
Type
boolean?
Description
true para permitir autofacturar un ticket pagado en otro año. Exige allowBillingOutsideMonth en true.
Default:
false
Name
privacyNoticeUrl
Type
string?
Description
URL https de tu aviso de privacidad, de hasta 2048 caracteres. Tu portal la muestra a tus clientes.

Errores

Las fallas llegan como falla de validación en el campo.

Estado	Cuándo ocurre	Mensaje
400	Permites otro año sin permitir otro mes.	Para permitir facturar fuera del año también debes permitir facturar fuera del mes.
400	La URL no es una URL https válida.	La URL del aviso de privacidad debe ser una URL https válida.
400	La URL pasa de 2048 caracteres.	La URL del aviso de privacidad no puede exceder 2048 caracteres.
403	No eres el owner.	No tienes permiso para administrar la configuración de Auto CFDI.
403	Tu suscripción no incluye Auto CFDI. Ver Permisos y suscripción.	Para administrar la configuración de Auto CFDI tu suscripción debe incluir: Auto CFDI.

Request

PUT

/api/v4/auto-invoice/settings

curl --location --request PUT 'https://test.fiscalapi.com/api/v4/auto-invoice/settings' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api_key>' \
--data-raw '{
  "allowBillingOutsideMonth": true,
  "allowBillingOutsideYear": false,
  "privacyNoticeUrl": "https://www.example.com/aviso-de-privacidad"
}'

Response

{
    "data": {
        "allowBillingOutsideMonth": true,
        "allowBillingOutsideYear": false,
        "privacyNoticeUrl": "https://www.example.com/aviso-de-privacidad"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

GET/api/v4/auto-invoice/portal-name

Obtener nombre del portal

Este endpoint devuelve el nombre vigente de tu portal. Si todavía no tienes uno, sus campos van en null.

Respuesta

Name
name
Type
string?
Description
Nombre vigente del portal, o null.
Name
assignedAt
Type
string?
Description
Fecha y hora en que el nombre pasó a vigente, o null.
Name
nextChangeAllowedAt
Type
string?
Description
Desde cuándo puedes volver a cambiar el nombre, o null si puedes cambiarlo ya.

Request

GET

/api/v4/auto-invoice/portal-name

curl --location 'https://test.fiscalapi.com/api/v4/auto-invoice/portal-name' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

{
    "data": {
        "name": "escuela-kemper",
        "assignedAt": "2026-10-01T09:15:00.000",
        "nextChangeAllowedAt": "2026-10-31T09:15:00.000"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

GET/api/v4/auto-invoice/portal-names/availability

Consultar disponibilidad del nombre

Este endpoint indica si puedes usar un nombre de portal. Un nombre inválido, reservado o de otra cuenta no es un error: responde available en false con su razón. Un nombre que ya es tuyo, vigente o anterior, está disponible. Solo el owner lo usa y exige Auto CFDI en tu suscripción.

Query parameters

Name
name
Type
string
required
Description
Nombre que quieres consultar.

Respuesta

Name
name
Type
string?
Description
Nombre normalizado, el que se guardaría.
Name
available
Type
boolean?
Description
true si puedes usar el nombre.
Name
reason
Type
string?
expandible
Description
Por qué no está disponible, o null si lo está.
Type
enum:
Values
"invalidFormat""reserved""taken"

Errores

Estado	Cuándo ocurre	Mensaje
403	No eres el owner.	No tienes permiso para administrar la configuración de Auto CFDI.
403	Tu suscripción no incluye Auto CFDI. Ver Permisos y suscripción.	Para administrar la configuración de Auto CFDI tu suscripción debe incluir: Auto CFDI.

Request

GET

/api/v4/auto-invoice/portal-names/availability?name=escuela-kemper

curl --location 'https://test.fiscalapi.com/api/v4/auto-invoice/portal-names/availability?name=escuela-kemper' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

{
    "data": {
        "name": "escuela-kemper",
        "available": true,
        "reason": null
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

PUT/api/v4/auto-invoice/portal-name

Cambiar nombre del portal

Este endpoint asigna el nombre de tu portal. El nombre anterior queda reservado para tu cuenta y redirige al nuevo. Solo el owner lo usa y exige Auto CFDI en tu suscripción.

Modelo

Name
name
Type
string
required
Description
Nuevo nombre del portal. Ver las reglas en Nombre del portal.

Errores

En el mensaje del cambio anticipado, <fecha> es el día, en hora de México, desde el que puedes volver a cambiarlo.

Estado	Cuándo ocurre	Mensaje
400	El nombre no cumple el formato. Llega como falla de validación en Name.	El nombre debe tener de 3 a 40 caracteres (minúsculas, números y guiones), empezar con letra y no llevar "--" ni terminar en guion.
400	El nombre está reservado. Llega como falla de validación en Name.	Ese nombre está reservado. Elige otro.
400	No han pasado 30 días desde el último cambio.	Solo puedes cambiar el nombre una vez cada 30 días. Próximo cambio disponible: <fecha>.
403	No eres el owner.	No tienes permiso para administrar la configuración de Auto CFDI.
403	Tu suscripción no incluye Auto CFDI. Ver Permisos y suscripción.	Para administrar la configuración de Auto CFDI tu suscripción debe incluir: Auto CFDI.
409	Otra cuenta tiene el nombre.	Ese nombre ya está en uso. Elige otro.
409	Hay otro cambio del nombre en curso. Repite la solicitud.	Hay otro cambio del nombre del portal en curso. Intenta de nuevo en unos segundos.

Request

PUT

/api/v4/auto-invoice/portal-name

curl --location --request PUT 'https://test.fiscalapi.com/api/v4/auto-invoice/portal-name' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api_key>' \
--data-raw '{
  "name": "escuela-kemper"
}'

Response

{
    "data": {
        "name": "escuela-kemper",
        "assignedAt": "2026-10-01T09:15:00.000",
        "nextChangeAllowedAt": "2026-10-31T09:15:00.000"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

GET/api/v4/auto-invoice/reports/consumption

Obtener reporte de consumo

Este endpoint devuelve el consumo de Auto CFDI de un periodo en dos bloques: los tickets pagados en el periodo por persona emisora y estado, y los créditos de ticket que consumió cada persona que registró tickets. Son bloques distintos porque quien registra el ticket puede no ser su emisor. No exige Auto CFDI en tu suscripción.

Query parameters

Name
from
Type
string
required
Description
Primer día del periodo, incluido, como fecha civil de México con el formato YYYY-MM-DD.
Name
to
Type
string
required
Description
Último día del periodo, incluido, con el mismo formato. El periodo dura como máximo 366 días.
Name
personId
Type
string?
Description
ID de una persona de tu cuenta: el reporte solo trae sus tickets como emisora y sus créditos como quien los registró.

Respuesta

Name
from
Type
string?
Description
Primer día del periodo.
Name
to
Type
string?
Description
Último día del periodo.
Name
issuers
Type
array of objects?
Una fila por persona emisora con tickets pagados en el periodo, ordenadas por RFC. Los cinco contadores de estado suman ingested.
Name
personId
Type
string?
Description
ID de la persona emisora.
Name
tin
Type
string?
Description
RFC de la persona emisora.
Name
legalName
Type
string?
Description
Razón social de la persona emisora.
Name
ingested
Type
integer?
Description
Tickets pagados en el periodo.
Name
pending
Type
integer?
Description
Tickets que esperan autofactura o factura global.
Name
inProgress
Type
integer?
Description
Tickets que se están timbrando, en invoicing o globalizing.
Name
invoiced
Type
integer?
Description
Tickets autofacturados.
Name
globalized
Type
integer?
Description
Tickets en una factura global.
Name
cancelled
Type
integer?
Description
Tickets cancelados.
Name
payers
Type
array of objects?
Una fila por persona que consumió créditos de ticket en el periodo, ordenadas por RFC.
Name
personId
Type
string?
Description
ID de la persona que registró los tickets.
Name
tin
Type
string?
Description
RFC de la persona, si lo tiene.
Name
legalName
Type
string?
Description
Razón social de la persona.
Name
ticketCreditsConsumed
Type
integer?
Description
Créditos de ticket consumidos en el periodo.
Name
totals
Type
object?
Description
Suma de los contadores de issuers y de ticketCreditsConsumed de payers.

Errores

Las fallas de validación llegan en ValidationFailure con el parámetro. En los mensajes, <id> es el id enviado.

Estado	Cuándo ocurre	Mensaje
400	Falta from.	'from' es obligatorio: una fecha YYYY-MM-DD de México.
400	Falta to.	'to' es obligatorio: una fecha YYYY-MM-DD de México.
400	La fecha de from no tiene el formato YYYY-MM-DD.	'from' debe ser una fecha YYYY-MM-DD.
400	La fecha de to no tiene el formato YYYY-MM-DD.	'to' debe ser una fecha YYYY-MM-DD.
400	El inicio del periodo es posterior al fin.	'from' no puede ser posterior a 'to'.
400	El periodo pasa de 366 días.	El periodo de 'from' a 'to' no puede pasar de 366 días.
404	La persona no existe en tu cuenta.	No such resource for the given Id: <id>

Request

GET

/api/v4/auto-invoice/reports/consumption?from=2026-10-01&to=2026-10-31

curl --location 'https://test.fiscalapi.com/api/v4/auto-invoice/reports/consumption?from=2026-10-01&to=2026-10-31' \
--header 'X-TENANT-KEY: <tenant_key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

{
    "data": {
        "from": "2026-10-01",
        "to": "2026-10-31",
        "issuers": [
            {
                "personId": "4b1c2d3e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
                "tin": "EKU9003173C9",
                "legalName": "ESCUELA KEMPER URGATE",
                "ingested": 120,
                "pending": 30,
                "inProgress": 0,
                "invoiced": 45,
                "globalized": 40,
                "cancelled": 5
            }
        ],
        "payers": [
            {
                "personId": "4b1c2d3e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
                "tin": "EKU9003173C9",
                "legalName": "ESCUELA KEMPER URGATE",
                "ticketCreditsConsumed": 120
            }
        ],
        "totals": {
            "ingested": 120,
            "pending": 30,
            "inProgress": 0,
            "invoiced": 45,
            "globalized": 40,
            "cancelled": 5,
            "ticketCreditsConsumed": 120
        }
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}