Auto CFDI invoicing

These endpoints manage Auto CFDI invoicing (CFDI: Mexico's electronic invoice) in your tenant (the space in Fiscalapi that holds your issuers, recipients, credits, and data). They cover the add-on settings (add-on: an extra you add to your subscription), which define the auto-invoice window and your portal's privacy notice; the name of your auto-invoice portal (auto-invoice: a CFDI your customer requests from a ticket; you remain the issuer); and the usage report for tickets (sales receipts your customers can later turn into CFDIs) and credits. Tickets have their own resource, tickets.

Read the introduction to Auto CFDI invoicing to learn about the flow, ticket credits, permissions, and the portal name rules.

GET/api/v4/auto-invoice/settings

Get the settings

This endpoint returns the Auto CFDI invoicing settings of your tenant. If you never saved them, it returns the default settings: the auto-invoice window lasts until the end of the payment month, and there's no privacy notice.

Response

Name
allowBillingOutsideMonth
Type
boolean?
Description
true if a ticket paid in another month can still be auto-invoiced.
Name
allowBillingOutsideYear
Type
boolean?
Description
true if a ticket paid in another year can still be auto-invoiced.
Name
privacyNoticeUrl
Type
string?
Description
The URL of the privacy notice your portal shows, or null if you haven't set it.

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

Update the settings

This endpoint replaces all the Auto CFDI invoicing settings of your tenant: a field you don't send takes its default value. Only the owner (the person who created the tenant) can use it, and it requires Auto CFDI invoicing in your subscription.

Your portal serves your customers when your subscription includes Auto CFDI invoicing, you have a portal name, and you set up the privacy notice. If any of the three is missing, the portal shows that you don't offer online invoicing and doesn't stamp (stamping: the certification by a SAT-authorized provider that makes a CFDI valid).

Model

Name
allowBillingOutsideMonth
Type
boolean?
Description
true to allow auto-invoicing a ticket paid in another month. See Auto-invoice window.
Default:
false
Name
allowBillingOutsideYear
Type
boolean?
Description
true to allow auto-invoicing a ticket paid in another year. Requires allowBillingOutsideMonth set to true.
Default:
false
Name
privacyNoticeUrl
Type
string?
Description
The https URL of your privacy notice, up to 2,048 characters. Your portal shows it to your customers.

Errors

Failures arrive as a validation failure on the field.

Status	When it happens	Message
400	You allow another year without allowing another month.	Para permitir facturar fuera del año también debes permitir facturar fuera del mes.
400	The URL isn't a valid https URL.	La URL del aviso de privacidad debe ser una URL https válida.
400	The URL is longer than 2,048 characters.	La URL del aviso de privacidad no puede exceder 2048 caracteres.
403	You aren't the owner.	No tienes permiso para administrar la configuración de Auto CFDI.
403	Your subscription doesn't include Auto CFDI invoicing. See Permissions and subscription.	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

Get the portal name

This endpoint returns the current name of your portal. If you don't have one yet, its fields are null.

Response

Name
name
Type
string?
Description
The current name of the portal, or null.
Name
assignedAt
Type
string?
Description
The date and time the name became current, or null.
Name
nextChangeAllowedAt
Type
string?
Description
When you can change the name again, or null if you can change it now.

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

Check whether a name is available

This endpoint tells you whether you can use a portal name. A name that is invalid, reserved, or held by another tenant isn't an error: the response has available set to false, with the reason. A name that's already yours, current or previous, is available. Only the owner can use it, and it requires Auto CFDI invoicing in your subscription.

Query parameters

Name
name
Type
string
required
Description
The name you want to check.

Response

Name
name
Type
string?
Description
The normalized name, the one that would be saved.
Name
available
Type
boolean?
Description
true if you can use the name.
Name
reason
Type
string?
expandable
Description
Why the name isn't available, or null if it is.
Type
enum:
Values
"invalidFormat""reserved""taken"

Errors

Status	When it happens	Message
403	You aren't the owner.	No tienes permiso para administrar la configuración de Auto CFDI.
403	Your subscription doesn't include Auto CFDI invoicing. See Permissions and subscription.	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

Change the portal name

This endpoint sets the name of your portal. The previous name stays reserved for your tenant and redirects to the new one. Only the owner can use it, and it requires Auto CFDI invoicing in your subscription.

Model

Name
name
Type
string
required
Description
The new portal name. See the rules in Portal name.

Errors

In the early-change message, <fecha> is the day, in Mexico local time, from which you can change the name again.

Status	When it happens	Message
400	The name doesn't follow the format. It arrives as a validation failure on 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	The name is reserved. It arrives as a validation failure on Name.	Ese nombre está reservado. Elige otro.
400	Fewer than 30 days have passed since the last change.	Solo puedes cambiar el nombre una vez cada 30 días. Próximo cambio disponible: <fecha>.
403	You aren't the owner.	No tienes permiso para administrar la configuración de Auto CFDI.
403	Your subscription doesn't include Auto CFDI invoicing. See Permissions and subscription.	Para administrar la configuración de Auto CFDI tu suscripción debe incluir: Auto CFDI.
409	Another tenant has the name.	Ese nombre ya está en uso. Elige otro.
409	Another portal name change is in progress. Retry the request.	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

Get the usage report

This endpoint returns the Auto CFDI invoicing usage for a period in two blocks: the tickets paid in the period, by issuing person (person: any individual or legal entity registered in your tenant) and status, and the ticket credits used by each person who recorded tickets. They're separate blocks because the person who records a ticket might not be its issuer. It doesn't require Auto CFDI invoicing in your subscription.

Query parameters

Name
from
Type
string
required
Description
The first day of the period, inclusive, as a Mexico calendar date in YYYY-MM-DD format.
Name
to
Type
string
required
Description
The last day of the period, inclusive, in the same format. The period can last up to 366 days.
Name
personId
Type
string?
Description
The ID of a person in your tenant: the report includes only their tickets as issuer and their credits as the person who recorded the tickets.

Response

Name
from
Type
string?
Description
The first day of the period.
Name
to
Type
string?
Description
The last day of the period.
Name
issuers
Type
array of objects?
One row per issuing person with tickets paid in the period, sorted by RFC (Mexico's taxpayer ID, Registro Federal de Contribuyentes). The five status counters add up to ingested.
Name
personId
Type
string?
Description
The ID of the issuing person.
Name
tin
Type
string?
Description
The RFC of the issuing person.
Name
legalName
Type
string?
Description
The legal name (as registered with the SAT) of the issuing person.
Name
ingested
Type
integer?
Description
Tickets paid in the period.
Name
pending
Type
integer?
Description
Tickets waiting for an auto-invoice or a global invoice (factura global, one CFDI that groups a period's sales to the general public).
Name
inProgress
Type
integer?
Description
Tickets being stamped, in invoicing or globalizing.
Name
invoiced
Type
integer?
Description
Auto-invoiced tickets.
Name
globalized
Type
integer?
Description
Tickets included in a global invoice.
Name
cancelled
Type
integer?
Description
Canceled tickets.
Name
payers
Type
array of objects?
One row per person who used ticket credits in the period, sorted by RFC.
Name
personId
Type
string?
Description
The ID of the person who recorded the tickets.
Name
tin
Type
string?
Description
The person's RFC, if they have one.
Name
legalName
Type
string?
Description
The person's legal name.
Name
ticketCreditsConsumed
Type
integer?
Description
Ticket credits used in the period.
Name
totals
Type
object?
Description
The sum of the issuers counters and of ticketCreditsConsumed in payers.

Errors

Validation failures arrive in ValidationFailure with the parameter. In the messages, <id> is the ID you sent.

Status	When it happens	Message
400	The from parameter is missing.	'from' es obligatorio: una fecha YYYY-MM-DD de México.
400	The to parameter is missing.	'to' es obligatorio: una fecha YYYY-MM-DD de México.
400	The from date isn't in YYYY-MM-DD format.	'from' debe ser una fecha YYYY-MM-DD.
400	The to date isn't in YYYY-MM-DD format.	'to' debe ser una fecha YYYY-MM-DD.
400	The start of the period is after its end.	'from' no puede ser posterior a 'to'.
400	The period is longer than 366 days.	El periodo de 'from' a 'to' no puede pasar de 366 días.
404	The person doesn't exist in your tenant.	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
}