Certificados CSD

Los Certificados de Sello Digital (CSD) son archivos emitidos por el SAT y es el mecanismo que permiten firmar digitalmente las facturas CFDI. Cada certificado CSD se emite en pares, es decir un archivo de certificado (.cer) y una llave privada (.key) componen un par CSD, y ambos archivos deben ser cargados al emisor para poder firmar las facturas.

En fiscalapi, una emisor (persona) puede tener múltiples pares de certificados CSD asociados. Este modelo permite gestionar tanto la carga del certificado como su llave privada correspondiente.

Modelo TaxFile

El modelo TaxFile representa un componente individual de un par CSD - ya sea el certificado (.cer) o la llave privada (.key), pero no ambos al mismo tiempo. Cada TaxFile tiene un fileType que indica si es un certificado o una llave privada, y un sequence que se incrementa en uno por cada par de certificado y llave privada cargado al emisor.

Modelo

Name
personId
Type
string
required
Description
Id de la persona propietaria del certificado.
Name
tin
Type
string
required
Description
RFC del propietario del certificado. Debe coincidir con el RFC del certificado.
Name
base64File
Type
string
required
Description
Archivo certificado o llave privada en formato base64. Para certificados debe ser el archivo .cer codificado en base64, para llaves privadas debe ser el archivo .key codificado en base64.
Name
fileType
Type
integer
required
Description
Tipo de archivo que se está enviando.
Type
enum:
Values
01
Name
password
Type
string
required
Description
Contraseña de la llave privada. Independientemente si se envía un certificado o una llave privada, siempre se debe enviar la contraseña de la llave privada.
Name
validFrom
Type
date?
Description
Fecha de inicio de vigencia del certificado o llave privada. Calculado automáticamente.
Name
validTo
Type
date?
Description
Fecha de fin de vigencia del certificado o llave privada. Calculado automáticamente.
Name
sequence
Type
integer?
Description
Numero de secuencia que identifica el par entre certificado y llave privada. Sólo con fines informativos.

GET/api/v4/tax-files

Listar certificados

Este endpoint te permite listar todos los certificados de todas las personas de su cuenta de fiscalapi.

Query parameters

Name
pageNumber
Type
int
required
Description
El número de página que se desea recuperar.
Default:
1
Name
pageSize
Type
int
required
Description
Valor entre 1 y 50 inclusivo para indicar la cantidad de registros devueltos por página.
Default:
10

Request

POST

/api/v4/tax-files

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

Response

{
    "data": {
        "items": [
            {
                "personId": "bfb7fc25-5b16-42d3-b67c-fd784e3e7461",
                "tin": "EKU9003173C9",
                "base64File": "base_64_file...",
                "fileType": 0,
                "password": "12345678a",
                "validFrom": "2023-05-17T23:43:51.0000000",
                "validTo": "2027-05-17T23:43:51.0000000",
                "sequence": 1,
                "id": "7626304b-47a9-4a42-82f7-43c7d4ed6081",
                "createdAt": "2025-01-11T13:55:57.5333153",
                "updatedAt": "2025-01-11T13:55:57.5333163"
            },
            {
                "personId": "bfb7fc25-5b16-42d3-b67c-fd784e3e7461",
                "tin": "EKU9003173C9",
                "base64File": "base_64_file...",
                "fileType": 1,
                "password": "12345678a",
                "validFrom": "2023-05-17T23:43:51.0000000",
                "validTo": "2027-05-17T23:43:51.0000000",
                "sequence": 1,
                "id": "f09554bb-0289-42fd-96c0-46f35ecbc2f4",
                "createdAt": "2025-01-11T13:56:05.8341325",
                "updatedAt": "2025-01-11T13:56:05.8341328"
            }
        ],
        "pageNumber": 1,
        "totalPages": 4,
        "totalCount": 8,
        "hasPreviousPage": false,
        "hasNextPage": true
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

GET/api/v4/tax-files/{id}

Obtener certificado por ID

Este endpoint le permite obtener un certificado por su ID.

Request

POST

/api/v4/tax-files/7626304b-47a9-4a42-82f7-43c7d4ed6081

curl --location 'https://test.fiscalapi.com/api/v4/tax-files/7626304b-47a9-4a42-82f7-43c7d4ed6081' \
--header 'X-TENANT-KEY: <tenant>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

{
    "data": {
        "personId": "bfb7fc25-5b16-42d3-b67c-fd784e3e7461",
        "tin": "EKU9003173C9",
        "base64File": "base_64_file...",
        "fileType": 0,
        "password": "12345678a",
        "validFrom": "2023-05-17T23:43:51.0000000",
        "validTo": "2027-05-17T23:43:51.0000000",
        "sequence": 1,
        "id": "7626304b-47a9-4a42-82f7-43c7d4ed6081",
        "createdAt": "2025-01-11T13:55:57.5333153",
        "updatedAt": "2025-01-11T13:55:57.5333163"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

GET/api/v4/tax-files/{id}/default-values

Obtener certificados por defecto

Este endpoint te devuelve el último par (.cer y .key) de certificados CSD cargados vigentes y válidos para una persona (emisor o receptor). Este par de certificados son los que se utilizarán por defecto para firmar las facturas cuando las peticiones se realizan por referencias.

Request

POST

/api/v4/tax-files

curl --location 'https://test.fiscalapi.com/api/v4/tax-files/123/default-values' \
--header 'X-TENANT-KEY: <tenant>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

{
    "data": [
        {
            "personId": "1",
            "tin": "JUFA7608212V6",
            "base64File": "base_64_file...",
            "fileType": 0,
            "password": "12345678a",
            "validFrom": "2023-05-18T02:58:56.0000000",
            "validTo": "2027-05-18T02:58:56.0000000",
            "sequence": 5,
            "id": "dc17bc3f-bc5c-4212-8192-99d778fb2bc4",
            "createdAt": "2025-01-11T15:40:31.7585889",
            "updatedAt": "2025-01-11T15:40:31.7585987"
        },
        {
            "personId": "1",
            "tin": "JUFA7608212V6",
            "base64File": "base_64_file...",
            "fileType": 1,
            "password": "12345678a",
            "validFrom": "2023-05-18T02:58:56.0000000",
            "validTo": "2027-05-18T02:58:56.0000000",
            "sequence": 5,
            "id": "b4c2ac83-c82c-4e48-bcf3-a60f88fa9a58",
            "createdAt": "2025-01-11T15:40:37.2208845",
            "updatedAt": "2025-01-11T15:40:37.2208849"
        }
    ],
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

POST/api/v4/tax-files

Subir certificados

Este endpoint te permite subir los certificados de una persona (emisor o receptor) a fiscalapi. Para completar la carga de certificados, debes enviar dos peticiones, una para el certificado (.cer) y otra para la llave privada (.key), ambas para la misma persona.

Modelo

Name
personId
Type
string
required
Description
Id de la persona propietaria del certificado CSD (Certificado de Sello Digital).
Name
tin
Type
string
required
Description
RFC del propietario del certificado. Debe coincidir con el RFC del certificado CSD.
Name
base64File
Type
string
required
Description
Archivo en formato base64. Para certificados debe codificar el archivo .cer, para llaves privadas debe codificar el archivo .key.
Name
fileType
Type
int
required
Description
Tipo de archivo que se está enviando.
Type
enum:
Values
01
Name
password
Type
string
required
Description
Contraseña de la llave privada. Independientemente si sube un certificado o una llave privada, siempre se debe enviar la contraseña de la llave privada.

Request

POST

/api/v4/tax-files

curl --location 'https://test.fiscalapi.com/api/v4/tax-files' \
--header 'X-TENANT-KEY: <tenant>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api_key>' \
--data '{
  "personId": "1",
  "tin": "FUNK671228PH6",
  "base64File": "base_64_file...",
  "fileType": 0,
  "password": "12345678a"
}'

Response

{
    "data": {
        "personId": "1",
        "tin": "JUFA7608212V6",
        "base64File": "base_64_file...",
        "fileType": 0,
        "password": "12345678a",
        "validFrom": "2023-05-18T02:58:56.0000000",
        "validTo": "2027-05-18T02:58:56.0000000",
        "sequence": 5,
        "id": "dc17bc3f-bc5c-4212-8192-99d778fb2bc4",
        "createdAt": "2025-01-11T15:40:31.7585889",
        "updatedAt": "2025-01-11T15:40:31.7585987"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

DELETE/api/v4/tax-files/{id}

Eliminar certificado

Este endpoint te permite eliminar un certificado por su ID. Para completar la eliminación de un par de certificados CSD, debes enviar dos peticiones, una para el certificado (.cer) y otra para la llave privada (.key), ambas para la misma persona.

Request

POST

/api/v4/tax-files

curl --location --request DELETE 'https://test.fiscalapi.com/api/v4/tax-files/b14c7056-d5d3-49d2-97c9-db437b0b1204' \
--header 'X-TENANT-KEY: <tenant>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>'

Response

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