Tax files

CSD certificates (CSD: Certificado de Sello Digital, the digital seal certificate used to sign CFDIs) are the .cer and .key files that the SAT (Mexico's tax authority, Servicio de Administración Tributaria) issues to a person (any individual or legal entity registered in your tenant). With them, the person digitally signs (seals) the invoices they issue. Use these endpoints to upload, retrieve, and delete each person's tax files (the CSD and e.firma .cer and .key files you upload for a person).

Tax files can't be edited: PUT /api/v4/tax-files/<id> doesn't exist and returns 405 Method Not Allowed. To change a person's tax files, upload the new pair (.cer and .key) and delete the old ones.

Other people's tax files

Tax files are credentials of the person they belong to. The tenant owner (tenant: the space in Fiscalapi that holds your issuers, recipients, credits, and data; owner: the person who created the tenant) manages the tax files of every person in the tenant; everyone else manages only their own. When the tax files belong to another person, the endpoints respond as follows for anyone who isn't the owner:

Endpoint	Response for anyone who isn't the owner
List tax files	Doesn't return them.
Get a tax file by ID	Returns 404, the same as for a tax file that doesn't exist.
Delete a tax file	Doesn't delete it and responds the same as for a tax file that doesn't exist (`succeeded: false`).
Upload tax files, Get the default tax files, and Get the default tax file references	Return 403.

TaxFile model

The TaxFile model represents a single file that belongs to a person: the certificate (.cer) or the private key (.key), never both at once.

Properties

Name
id
Type
string?
Description
The file's unique identifier, assigned by Fiscalapi.
Name
personId
Type
string
required
Description
The ID of the person the file belongs to.
Name
tin
Type
string?
Description
The RFC (Mexico's taxpayer ID, Registro Federal de Contribuyentes) of the person the file belongs to. Fiscalapi always saves and returns the person's RFC. It's optional when you upload the file; if you send it, it must be the person's RFC.
Name
base64File
Type
string
required
Description
The content of the .cer or .key file in base64, depending on the value of fileType.
Name
fileType
Type
integer | number
required
Description
The file type.
Type
enum:
Values
012
Name
password
Type
string
required
Description
The private key password. When you upload a file, you always send it, whether it's the certificate or the private key. In responses, it arrives empty (""), except in Get the default tax files, the only endpoint that returns it.
Name
validFrom
Type
date?
Description
The start date of the validity period of the certificate or private key. Fiscalapi calculates it.
Name
validTo
Type
date?
Description
The expiration date of the certificate or private key. Fiscalapi calculates it.
Name
sequence
Type
integer | number?
Description
The sequence number that identifies the certificate and private key pair. Fiscalapi calculates it.

GET/api/v4/tax-files

List tax files

This endpoint returns a paginated list of tax files, ten per page by default. Set the page and its size with the query parameters. Each item includes the file content (base64File) but not the private key password, which arrives empty. To get it, use Get the default tax files.

Query parameters

Name
pageNumber
Type
integer | number
required
Description
The page number you want to retrieve.
Default:
1
Name
pageSize
Type
integer | number
required
Description
The number of tax files per page, from 1 to 50.
Default:
10

Request

GET

/api/v4/tax-files

curl --location 'https://test.fiscalapi.com/api/v4/tax-files?pageNumber=1&pageSize=2' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api-key>'

This example omits the Base64 content because of its size.

Response

{
    "data": {
        "items": [
            {
                "personId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
                "tin": "EKU9003173C9",
                "base64File": "<base64>",
                "fileType": 0,
                "password": "",
                "validFrom": "2023-05-18T05:43:51.0000000",
                "validTo": "2027-05-18T05:43:51.0000000",
                "sequence": 3,
                "id": "18152a11-2962-43bf-93e0-559b70159ab8",
                "createdAt": "2025-04-27T14:38:13.7898462",
                "updatedAt": "2025-04-27T14:38:13.7898466"
            },
            {
                "personId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
                "tin": "EKU9003173C9",
                "base64File": "<base64>",
                "fileType": 1,
                "password": "",
                "validFrom": "2023-05-18T05:43:51.0000000",
                "validTo": "2027-05-18T05:43:51.0000000",
                "sequence": 3,
                "id": "18152a11-2962-43bf-93e0-559b70159ab8",
                "createdAt": "2025-04-27T14:38:13.7898462",
                "updatedAt": "2025-04-27T14:38:13.7898466"
            }
        ],
        "pageNumber": 1,
        "totalPages": 4,
        "totalCount": 7,
        "hasPreviousPage": false,
        "hasNextPage": true
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

GET/api/v4/tax-files/<id>

Get a tax file by ID

This endpoint returns a tax file by its ID. The response includes the file content (base64File) but not the private key password, which arrives empty. To get it, use Get the default tax files.

Request

GET

/api/v4/tax-files/<id>

curl --location 'https://test.fiscalapi.com/api/v4/tax-files/18152a11-2962-43bf-93e0-559b70159ab8' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api-key>'

This example omits the Base64 content because of its size.

Response

{
    "data": {
        "personId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
        "tin": "EKU9003173C9",
        "base64File": "<base64>",
        "fileType": 1,
        "password": "",
        "validFrom": "2023-05-18T05:43:51.0000000",
        "validTo": "2027-05-18T05:43:51.0000000",
        "sequence": 3,
        "id": "18152a11-2962-43bf-93e0-559b70159ab8",
        "createdAt": "2025-04-27T14:38:13.7898462",
        "updatedAt": "2025-04-27T14:38:13.7898466"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

GET/api/v4/tax-files/<personId>/default-values

Get the default tax files

This endpoint returns a person's default tax files: their most recent tax files (.cer and .key) that are current and valid. The response includes the content of each file (base64File) and the private key password (password). It's the only tax files endpoint that returns the password; the list, the retrieval by ID, and the upload response return it empty. To get only their references, use Get the default tax file references.

If only one of the person's two files is current, upload the missing one. If the person has no current tax files, the endpoint returns 200 with an empty data ([]). Only the person themselves or the tenant owner can get their default tax files.

Errors

In the messages, <personId> is the person's ID. The messages arrive in the details field of the response model.

Status	When it happens	Message
404	The person has a current certificate but no current private key.	No se encontró la llave privada de la persona: <personId>
404	The person has a current private key but no current certificate.	No se encontró el certificado de la persona: <personId>
404	The person doesn't exist.	La persona '<personId>' no existe
400	The person has no RFC.	La persona '<personId>' no tiene datos fiscales
403	The requester is neither the person nor the tenant owner.	Solo el propietario de la cuenta puede gestionar las credenciales de otra persona: correo, contraseña, API keys y certificados.

Request

GET

/api/v4/tax-files/<personId>/default-values

curl --location 'https://test.fiscalapi.com/api/v4/tax-files/bef56254-0892-4558-95c3-f9c8729e4b0e/default-values' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

This example omits the Base64 content because of its size.

Response

{
    "data": [
        {
            "personId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
            "tin": "EKU9003173C9",
            "base64File": "<base64>",
            "fileType": 0,
            "password": "12345678a",
            "validFrom": "2023-05-18T05:43:51.0000000",
            "validTo": "2027-05-18T05:43:51.0000000",
            "sequence": 3,
            "id": "5bcd4db0-5a6e-466e-84fe-9c344b4624e7",
            "createdAt": "2025-04-27T14:22:17.9052365",
            "updatedAt": "2025-04-27T14:22:17.9052370"
        },
        {
            "personId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
            "tin": "EKU9003173C9",
            "base64File": "<base64>",
            "fileType": 1,
            "password": "12345678a",
            "validFrom": "2023-05-18T05:43:51.0000000",
            "validTo": "2027-05-18T05:43:51.0000000",
            "sequence": 3,
            "id": "18152a11-2962-43bf-93e0-559b70159ab8",
            "createdAt": "2025-04-27T14:38:13.7898462",
            "updatedAt": "2025-04-27T14:38:13.7898466"
        }
    ],
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

GET/api/v4/tax-files/<personId>/default-references

Get the default tax file references

This endpoint returns the references to a person's default tax files: the same tax files (.cer and .key) as Get the default tax files, without the file content or the password. They're the tax files Fiscalapi uses to seal the invoices by reference (you send the IDs of people and products already saved in Fiscalapi) that this person issues.

The response has two items, the certificate ("fileType": 0) and the private key ("fileType": 1), each with its ID, RFC, and validity period; the file and the password arrive empty (""). If only one of the person's two files is current, upload the missing one. Only the person themselves or the tenant owner can get the references to their tax files, the same rule as Get the default tax files.

Errors

In the messages, <personId> is the person's ID. The messages arrive in the details field of the response model.

Status	When it happens	Message
404	The person has no current tax files.	No se encontró tal recurso. Verifica los archivos fiscales de la persona: <personId>
404	The person has a current certificate but no current private key.	No se encontró la llave privada de la persona: <personId>
404	The person has a current private key but no current certificate.	No se encontró el certificado de la persona: <personId>
404	The person doesn't exist.	La persona '<personId>' no existe
400	The person has no RFC.	La persona '<personId>' no tiene datos fiscales
403	The requester is neither the person nor the tenant owner.	Solo el propietario de la cuenta puede gestionar las credenciales de otra persona: correo, contraseña, API keys y certificados.

Request

GET

/api/v4/tax-files/<personId>/default-references

curl --location 'https://test.fiscalapi.com/api/v4/tax-files/bef56254-0892-4558-95c3-f9c8729e4b0e/default-references' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

{
    "data": [
        {
            "personId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
            "tin": "EKU9003173C9",
            "base64File": "",
            "fileType": 0,
            "password": "",
            "validFrom": "2023-05-18T05:43:51.0000000",
            "validTo": "2027-05-18T05:43:51.0000000",
            "sequence": 3,
            "id": "5bcd4db0-5a6e-466e-84fe-9c344b4624e7",
            "createdAt": "2025-04-27T14:22:17.9052365",
            "updatedAt": "2025-04-27T14:22:17.9052370"
        },
        {
            "personId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
            "tin": "EKU9003173C9",
            "base64File": "",
            "fileType": 1,
            "password": "",
            "validFrom": "2023-05-18T05:43:51.0000000",
            "validTo": "2027-05-18T05:43:51.0000000",
            "sequence": 3,
            "id": "18152a11-2962-43bf-93e0-559b70159ab8",
            "createdAt": "2025-04-27T14:38:13.7898462",
            "updatedAt": "2025-04-27T14:38:13.7898466"
        }
    ],
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

POST/api/v4/tax-files

Upload tax files

This endpoint uploads a person's certificate (.cer) or private key (.key) to Fiscalapi. To complete the upload, send two requests with the same personId: one for the .cer file and one for the .key file.

Request body

Name
personId
Type
string
required
Description
The ID of the person the file belongs to.
Name
tin
Type
string?
Description
The RFC of the person the file belongs to. If you omit it or send it empty, Fiscalapi uses the person's RFC. If you send it, it must be the person's RFC, case-insensitive; otherwise, the endpoint returns 400 with a validation failure on Tin. This check happens after Fiscalapi verifies that you can manage the person's tax files (otherwise, it returns 403). Fiscalapi doesn't save the value you send: the file's RFC is always the person's.
Name
base64File
Type
string
required
Description
The content of the .cer or .key file in base64, depending on the value of fileType.
Name
fileType
Type
integer | number
required
Description
The file type.
Type
enum:
Values
012
Fiscalapi rejects any other value, including 4 (Pfx): you upload the certificate and the private key separately.
Name
password
Type
string
required
Description
The private key password. You always send it, whether it's the certificate or the private key. When you upload a private key (fileType 1 or 3), the password must open it; otherwise, Fiscalapi rejects the file.

The response includes the saved file with an empty password (""): Fiscalapi stores the password encrypted and doesn't include it in this response.

Errors

In the last message, <valor> is the value you sent.

Status	When it happens	Message
403	You upload another person's tax files and you aren't the tenant owner. The message arrives in the `details` field of the response model.	Solo el propietario de la cuenta puede gestionar las credenciales de otra persona: correo, contraseña, API keys y certificados.
400	The password doesn't open the private key. It arrives as a validation failure on Password. See Certificates and private keys.	La contraseña de la llave privada (.key) es incorrecta o el archivo no es una llave privada.
400	The file type is `4` (Pfx). It arrives as a validation failure on FileType.	'File Type' 4 (Pfx) no se admite: el certificado (.cer) y la llave privada (.key) se cargan por separado (fileType 0 y 1 para el CSD, 2 y 3 para la FIEL).
400	The file type isn't one of the listed values. It arrives as a validation failure on FileType.	'File Type' tiene un rango de valores que no incluye '<valor>'.

Request

POST

/api/v4/tax-files

curl --location 'https://test.fiscalapi.com/api/v4/tax-files' \
--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 '{
  "personId": "<personId>",
  "tin": "FUNK671228PH6",
  "base64File": "archivo_en_base64...",
  "fileType": 0,
  "password": "12345678a"
}'

Response

{
    "data": {
        "personId": "78d380fd-1b69-4e3c-8bc0-4f57737f7d5f",
        "tin": "FUNK671228PH6",
        "base64File": "archivo_cer_base64...",
        "fileType": 0,
        "password": "",
        "validFrom": "2023-05-18T08:35:37.0000000",
        "validTo": "2027-05-18T08:35:37.0000000",
        "sequence": 3,
        "id": "54cbe2e6-4956-4eb4-958d-3701079c47b3",
        "createdAt": "2025-05-01T08:37:26.9754720",
        "updatedAt": "2025-05-01T08:37:26.9754726"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

DELETE/api/v4/tax-files/<id>

Delete a tax file

This endpoint deletes a tax file by its ID. To delete a person's tax files, send two requests with the ID of each file: one for the .cer and one for the .key.

This is a soft delete: the tax file no longer appears in any query (the list, the retrieval by ID, and the default tax files), and Fiscalapi stops using it for stamping (the certification by a SAT-authorized provider that makes a CFDI valid). The file and its password are erased; only the tax file's record remains (its type, RFC, validity period, and who deleted it and when). To use it again, upload it again.

If Fiscalapi deletes the tax file, the endpoint returns 200 with "data": true. If the tax file doesn't exist, was already deleted, or belongs to another person, it returns 400 with "data": false (see Other people's tax files).

Request

DELETE

/api/v4/tax-files/<id>

curl --location --request DELETE 'https://test.fiscalapi.com/api/v4/tax-files/3e6a8d54-9255-4267-b617-ef848211b1bc' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api-key>'

Response

{
    "data": true,
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}