Certificados CSD

Los certificados de sello digital (CSD) son los archivos .cer y .key que el SAT emite a una persona para firmar (sellar) digitalmente las facturas que emite. Con estos endpoints subes, consultas y eliminas los certificados de cada persona.

Los certificados no se editan: PUT /api/v4/tax-files/<id> no existe y responde 405 Method Not Allowed. Para cambiar los certificados de una persona, sube el nuevo par (.cer y .key) y elimina los anteriores.

Certificados de otras personas

Un certificado es una credencial de su persona. El owner del tenant gestiona los certificados de todas las personas del tenant; las demás personas, solo los propios. Con los certificados de otra persona, los endpoints responden así para quien no es el owner:

Endpoint	Respuesta para quien no es el owner
Listar certificados	No los devuelve.
Obtener certificado por ID	Responde 404, igual que con un certificado que no existe.
Listar certificados de una persona	Responde 404, igual que con una persona que no existe.
Eliminar certificado	No los elimina y responde igual que con un certificado que no existe (`succeeded: false`).
Subir certificados, Obtener certificados por defecto y Obtener referencias de certificados por defecto	Responden 403.

Modelo TaxFile

El modelo TaxFile representa un solo archivo de una persona: el certificado (.cer) o la llave privada (.key), nunca los dos a la vez.

Propiedades

Name
id
Type
string?
Description
Identificador único del archivo, asignado por Fiscalapi.
Name
personId
Type
string
required
Description
Id de la persona a la que pertenece el archivo.
Name
tin
Type
string?
Description
RFC de la persona a la que pertenece el archivo. Fiscalapi siempre guarda y devuelve el RFC de la persona. Al subir el archivo es opcional; si lo envías, debe ser el RFC de la persona.
Name
base64File
Type
string
required
Description
Contenido del archivo .cer o .key en base64, según el valor de fileType.
Name
fileType
Type
integer | number
required
Description
Tipo de archivo.
Type
enum:
Values
012
Name
password
Type
string
required
Description
Contraseña de la llave privada. Al subir un archivo la envías siempre, sea el certificado o la llave privada. En las respuestas llega vacía (""), salvo en Obtener certificados por defecto, el único endpoint que la devuelve.
Name
validFrom
Type
date?
Description
Fecha de inicio de vigencia del certificado o de la llave privada. Fiscalapi la calcula.
Name
validTo
Type
date?
Description
Fecha de fin de vigencia del certificado o de la llave privada. Fiscalapi la calcula.
Name
sequence
Type
integer | number?
Description
Número de secuencia que identifica el par de certificado y llave privada. Fiscalapi lo calcula.

GET/api/v4/tax-files

Listar certificados

Este endpoint devuelve una lista paginada de certificados, diez por página de forma predeterminada; ajusta la página y su tamaño con los parámetros de consulta. Cada certificado trae su archivo (base64File), pero no la contraseña de la llave privada, que llega vacía. Para obtenerla, usa Obtener certificados por defecto.

Query parameters

Name
pageNumber
Type
integer | number
required
Description
Número de página que quieres consultar.
Default:
1
Name
pageSize
Type
integer | number
required
Description
Cantidad de certificados por página, de 1 a 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>'

En este ejemplo se omite el contenido en Base64 por su tamaño.

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>

Obtener certificado por ID

Este endpoint obtiene un certificado por su id. La respuesta trae el archivo (base64File), pero no la contraseña de la llave privada, que llega vacía. Para obtenerla, usa Obtener certificados por defecto.

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>'

En este ejemplo se omite el contenido en Base64 por su tamaño.

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/people/<personId>/tax-files

Listar certificados de una persona

Este endpoint lista en una sola respuesta, sin paginar, todos los certificados (.cer) y llaves privadas (.key) de CSD y FIEL de una persona, del vencimiento (validTo) más lejano al más cercano. Cada archivo trae solo sus metadatos: no incluye el contenido (base64File) ni la contraseña de la llave privada. Para descargar un archivo, usa Obtener certificado por ID.

Solo la persona misma o el owner del tenant obtienen la lista. Para cualquier otra persona, el endpoint responde 404, igual que con una persona que no existe (ver Certificados de otras personas).

Path parameters

Name
personId
Type
string
required
Description
Id de la persona cuyos certificados quieres listar.

Errores

En el mensaje, <id> es el id de la persona.

Estado	Cuándo ocurre	Mensaje
404	La persona no existe en tu cuenta, o es otra persona y no eres el owner del tenant.	No such resource for the given Id: <id>

Request

GET

/api/v4/people/<personId>/tax-files

curl --location 'https://test.fiscalapi.com/api/v4/people/88f439f3-8d78-4c12-9664-10b58762e688/tax-files' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

{
    "data": [
        {
            "id": "bc43e5af-47d8-4144-a310-7d7b1fe5991f",
            "personId": "88f439f3-8d78-4c12-9664-10b58762e688",
            "tin": "FUNK671228PH6",
            "fileType": 0,
            "validFrom": "2023-05-18T02:35:37.000",
            "validTo": "2027-05-18T02:35:37.000",
            "sequence": 1
        },
        {
            "id": "ee1b9c71-1702-4f2c-8083-f0cd96add7ad",
            "personId": "88f439f3-8d78-4c12-9664-10b58762e688",
            "tin": "FUNK671228PH6",
            "fileType": 1,
            "validFrom": "2023-05-18T02:35:37.000",
            "validTo": "2027-05-18T02:35:37.000",
            "sequence": 1
        }
    ],
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

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

Obtener certificados por defecto

Este endpoint obtiene los certificados por defecto de una persona: sus últimos certificados (.cer y .key) vigentes y válidos. La respuesta incluye el contenido de cada archivo (base64File) y la contraseña de la llave privada (password). Es el único endpoint de certificados que devuelve la contraseña; el listado, la consulta por id y la respuesta de la carga la devuelven vacía. Para obtener solo sus referencias, usa Obtener referencias de certificados por defecto.

Si la persona solo tiene vigente uno de los dos archivos, sube el que falta. Si no tiene ningún certificado vigente, el endpoint responde 200 con data vacía ([]). Solo la persona misma o el owner del tenant obtienen sus certificados por defecto.

Errores

En los mensajes, <personId> es el id de la persona. Los mensajes llegan en details del modelo de respuesta.

Estado	Cuándo ocurre	Mensaje
404	La persona tiene vigente el certificado, pero no la llave privada.	No se encontró la llave privada de la persona: <personId>
404	La persona tiene vigente la llave privada, pero no el certificado.	No se encontró el certificado de la persona: <personId>
404	La persona no existe.	La persona '<personId>' no existe
400	La persona no tiene RFC.	La persona '<personId>' no tiene datos fiscales
403	Quien hace la petición no es la persona ni el owner del tenant.	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>'

En este ejemplo se omite el contenido en Base64 por su tamaño.

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

Obtener referencias de certificados por defecto

Este endpoint obtiene las referencias de los certificados por defecto de una persona: los mismos certificados (.cer y .key) que devuelve Obtener certificados por defecto, sin el contenido del archivo ni la contraseña. Son los certificados con los que Fiscalapi sella las facturas por referencias que emite esa persona.

La respuesta trae dos elementos, el certificado ("fileType": 0) y la llave privada ("fileType": 1), cada uno con su id, RFC y vigencia; el archivo y la contraseña llegan vacíos (""). Si la persona solo tiene vigente uno de los dos archivos, sube el que falta. Solo la persona misma o el owner del tenant obtienen las referencias de sus certificados, la misma regla que Obtener certificados por defecto.

Errores

En los mensajes, <personId> es el id de la persona. Los mensajes llegan en details del modelo de respuesta.

Estado	Cuándo ocurre	Mensaje
404	La persona no tiene ningún certificado vigente.	No se encontró tal recurso. Verifica los archivos fiscales de la persona: <personId>
404	La persona tiene vigente el certificado, pero no la llave privada.	No se encontró la llave privada de la persona: <personId>
404	La persona tiene vigente la llave privada, pero no el certificado.	No se encontró el certificado de la persona: <personId>
404	La persona no existe.	La persona '<personId>' no existe
400	La persona no tiene RFC.	La persona '<personId>' no tiene datos fiscales
403	Quien hace la petición no es la persona ni el owner del tenant.	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

Subir certificados

Este endpoint sube a Fiscalapi el certificado (.cer) o la llave privada (.key) de una persona. Para completar la carga, envía dos peticiones con el mismo personId: una para el archivo .cer y otra para el archivo .key.

Modelo

Name
personId
Type
string
required
Description
Id de la persona a la que pertenece el archivo.
Name
tin
Type
string?
Description
RFC de la persona a la que pertenece el archivo. Si lo omites o lo envías vacío, Fiscalapi usa el RFC de la persona. Si lo envías, debe ser el RFC de la persona, sin distinguir mayúsculas de minúsculas; si no, el endpoint responde 400 con una falla de validación en Tin. Esta comparación ocurre después de verificar que puedes gestionar los certificados de la persona (si no, responde 403). Fiscalapi no guarda el valor que envías: el RFC del archivo siempre es el de la persona.
Name
base64File
Type
string
required
Description
Contenido del archivo .cer o .key en base64, según el valor de fileType.
Name
fileType
Type
integer | number
required
Description
Tipo de archivo.
Type
enum:
Values
012
Fiscalapi rechaza cualquier otro valor, incluido 4 (Pfx): el certificado y la llave privada se cargan por separado.
Name
password
Type
string
required
Description
Contraseña de la llave privada. La envías siempre, sea el certificado o la llave privada. Al subir una llave privada (fileType 1 o 3), la contraseña debe abrirla; si no, Fiscalapi rechaza el archivo.

La respuesta trae el archivo guardado con password vacía (""): Fiscalapi guarda la contraseña cifrada y no la incluye en esta respuesta.

Errores

En el último mensaje, <valor> es el valor que enviaste.

Estado	Cuándo ocurre	Mensaje
403	Subes certificados de otra persona y no eres el owner del tenant. El mensaje llega en `details` del modelo de respuesta.	Solo el propietario de la cuenta puede gestionar las credenciales de otra persona: correo, contraseña, API keys y certificados.
400	La contraseña no abre la llave privada. Llega como falla de validación en Password. Ver Certificados y llaves privadas.	La contraseña de la llave privada (.key) es incorrecta o el archivo no es una llave privada.
400	El tipo de archivo es `4` (Pfx). Llega como falla de validación en 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	El tipo de archivo no es uno de la lista. Llega como falla de validación en 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>

Eliminar certificado

Este endpoint elimina un certificado por su id. Para eliminar los certificados de una persona, envía dos peticiones con el id de cada archivo: una para el .cer y otra para el .key.

La eliminación es lógica: el certificado deja de aparecer en todas las consultas (listado, consulta por id y certificados por defecto) y Fiscalapi deja de usarlo para timbrar. El archivo y su contraseña se borran; solo se conserva el registro del certificado (tipo, RFC, vigencia y quién lo eliminó y cuándo). Para volver a usarlo, súbelo de nuevo.

Si Fiscalapi elimina el certificado, el endpoint responde 200 con "data": true. Si el certificado no existe, ya se había eliminado o es de otra persona, responde 400 con "data": false (ver Certificados de otras personas).

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
}