Timbres

Un timbre es el crédito que se consume cada vez que se timbra un CFDI ante el SAT. En Fiscalapi, los timbres se administran a nivel de persona y pueden moverse entre personas de su organización mediante transferencias y retiros. Cada movimiento queda registrado como una transacción que puede consultarse de forma individual o paginada.

Importante: Las operaciones de transferir y retirar timbres usan el mismo endpoint POST /api/v4/stamps con el mismo cuerpo (fromPersonId, toPersonId, amount y comments). Ambas devuelven data: true cuando la operación es exitosa. Los timbres disponibles de cada persona se reflejan en el campo availableBalance del recurso personas.

Este mismo ledger registra dos tipos de crédito, distinguidos por el campo creditType: timbres (1, el valor por omisión) y créditos de validación (2), que se consumen al validar un CFDI ante el SAT con el recurso validaciones SAT. Los saldos nunca se mezclan: creditType: 1 afecta availableBalance y creditType: 2 afecta availableValidationBalance.

Modelo movimiento

El modelo movimiento (StampTransaction) representa una transacción de timbres entre dos personas y es lo que devuelven los endpoints de consulta (GET).

Propiedades

Name
consecutive
Type
integer | number?
Description
Folio consecutivo del movimiento asignado por Fiscalapi.
Name
fromPerson
Type
object (Person)?
Persona origen del movimiento (quien envía los timbres).
Name
tin
Type
string?
Description
RFC de la persona origen.
Name
legalName
Type
string?
Description
Razón social o nombre de la persona origen.
Name
id
Type
string?
Description
Identificador único de la persona origen.
Name
toPerson
Type
object (Person)?
Persona destino del movimiento (quien recibe los timbres).
Name
tin
Type
string?
Description
RFC de la persona destino.
Name
legalName
Type
string?
Description
Razón social o nombre de la persona destino.
Name
id
Type
string?
Description
Identificador único de la persona destino.
Name
amount
Type
integer | number?
Description
Cantidad de timbres involucrados en el movimiento.
Name
transactionType
Type
integer | number?
expandible
Description
Tipo de movimiento.
Type
enum:
Values
123
Name
transactionStatus
Type
integer | number?
expandible
Description
Estatus del movimiento.
Type
enum:
Values
123
Name
referenceId
Type
string?
Description
Identificador de referencia asociado al movimiento.
Name
comments
Type
string?
Description
Comentarios del movimiento. Puede ser null.
Name
creditType
Type
integer | number?
expandible
Description
Tipo de crédito al que afecta el movimiento.
Type
enum:
Values
12
Name
id
Type
string?
Description
Identificador único del movimiento asignado por Fiscalapi.

GET/api/v4/stamps

Listar movimientos

Este endpoint devuelve una lista paginada de movimientos de timbres. De forma predeterminada, se muestran diez movimientos por página, pero puedes ajustar esto con los parámetros de consulta.

Query parameters

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

Request

GET

/api/v4/stamps?pageNumber=1&pageSize=2

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

Response

{
    "data": {
        "items": [
            {
                "consecutive": 11,
                "fromPerson": {
                    "tin": "FAP240304AU3",
                    "legalName": "FISCAL API",
                    "id": "1",
                    "createdAt": "2024-08-10T15:46:30.373",
                    "updatedAt": "2025-11-02T13:12:47.205"
                },
                "toPerson": {
                    "tin": "KAHO641101B39",
                    "legalName": "OSCAR KALA HAAK",
                    "id": "5fd9f48c-a6a2-474f-944b-88a01751d432",
                    "createdAt": "2025-01-07T15:15:00.305",
                    "updatedAt": "2025-11-03T19:19:48.455"
                },
                "amount": 500,
                "transactionType": 1,
                "transactionStatus": 1,
                "referenceId": "7452186b-f890-4cad-90df-f478335ce117",
                "comments": null,
                "creditType": 1,
                "id": "e22e17d1-48c5-49a5-af71-a56cae4bdd95",
                "createdAt": "2025-08-10T12:12:50.496",
                "updatedAt": "2025-08-10T12:12:50.496"
            },
            {
                "consecutive": 12,
                "fromPerson": {
                    "tin": "KAHO641101B39",
                    "legalName": "OSCAR KALA HAAK",
                    "id": "5fd9f48c-a6a2-474f-944b-88a01751d432",
                    "createdAt": "2025-01-07T15:15:00.305",
                    "updatedAt": "2025-11-03T19:19:48.455"
                },
                "toPerson": {
                    "tin": "XAXX010101000",
                    "legalName": "SERVICIO DE ADMINISTRACIÓN TRIBUTARIA",
                    "id": "-1",
                    "createdAt": "2024-08-10T15:46:30.373",
                    "updatedAt": null
                },
                "amount": 1,
                "transactionType": 3,
                "transactionStatus": 1,
                "referenceId": "9e5dfb9f-3d7d-4b43-8414-42bc5b831f3a",
                "comments": "Emisión CFDI",
                "creditType": 1,
                "id": "6253c3ee-45e2-4bb7-8096-30804f98a254",
                "createdAt": "2025-08-10T14:20:14.887",
                "updatedAt": "2025-08-10T14:20:14.887"
            }
        ],
        "pageNumber": 1,
        "totalPages": 21,
        "totalCount": 207,
        "hasPreviousPage": false,
        "hasNextPage": true
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

GET/api/v4/stamps/<id>

Obtener movimiento por ID

Este endpoint te permite obtener un movimiento de timbres por su ID.

Request

GET

/api/v4/stamps/<id>

curl --location 'https://test.fiscalapi.com/api/v4/stamps/77678d6d-94b1-4635-aa91-15cdd7423aab' \
--header 'X-TENANT-KEY: <tenant>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api_key>' \
--data ''

Response

{
    "data": {
        "consecutive": 9,
        "fromPerson": {
            "tin": "FAP240304AU3",
            "legalName": "FISCAL API",
            "id": "1",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": "2025-11-02T13:12:47.205"
        },
        "toPerson": {
            "tin": "KAHO641101B39",
            "legalName": "OSCAR KALA HAAK",
            "id": "5fd9f48c-a6a2-474f-944b-88a01751d432",
            "createdAt": "2025-01-07T15:15:00.305",
            "updatedAt": "2025-11-03T19:19:48.455"
        },
        "amount": 100,
        "transactionType": 1,
        "transactionStatus": 1,
        "referenceId": "46aecf10-5e63-48e9-a101-bbb3cda10b38",
        "comments": null,
        "creditType": 1,
        "id": "77678d6d-94b1-4635-aa91-15cdd7423aab",
        "createdAt": "2025-08-08T21:01:07.583",
        "updatedAt": "2025-08-08T21:01:07.583"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

POST/api/v4/stamps

Transferir timbres

Este endpoint te permite transferir timbres de una persona a otra.

Modelo

Name
fromPersonId
Type
string
required
Description
ID de la persona origen que envía los timbres.
Name
toPersonId
Type
string
required
Description
ID de la persona destino que recibe los timbres.
Name
amount
Type
integer | number
required
Description
Cantidad de timbres a transferir.
Name
comments
Type
string?
Description
Comentarios opcionales sobre la transferencia. Máximo 100 caracteres.
Name
creditType
Type
integer | number?
expandible
Description
Tipo de crédito a transferir. Con 2 se transfieren créditos de validación y el saldo se valida contra availableValidationBalance de la persona origen. Un valor fuera del enum devuelve 400.
Type
enum:
Values
12
Default:
1

La transferencia es atómica. Ten en cuenta estas restricciones:

Origen y destino no pueden ser la misma persona: devuelve 400 con No puedes transferir timbres a ti mismo.
Las personas de sistema (0, 1 y -1) no pueden ser origen ni destino: devuelve 403.
Si el saldo del origen no alcanza, devuelve 403 con Saldo insuficiente. Disponible: n, Requerido: m.

Request

POST

/api/v4/stamps

curl --location 'https://test.fiscalapi.com/api/v4/stamps' \
--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 '{
  "fromPersonId": "1",
  "toPersonId": "bef56254-0892-4558-95c3-f9c8729e4b0e",
  "amount": 1,
  "comments": "Compra 001"
}'

Response

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

POST/api/v4/stamps

Retirar timbres

Este endpoint te permite retirar timbres de una persona. Utiliza el mismo endpoint y modelo que la transferencia.

Modelo

Name
fromPersonId
Type
string
required
Description
ID de la persona origen de la que se retiran los timbres.
Name
toPersonId
Type
string
required
Description
ID de la persona destino a la que se devuelven los timbres.
Name
amount
Type
integer | number
required
Description
Cantidad de timbres a retirar.
Name
comments
Type
string?
Description
Comentarios opcionales sobre el retiro. Máximo 100 caracteres.
Name
creditType
Type
integer | number?
expandible
Description
Tipo de crédito a retirar. Con 2 se retiran créditos de validación.
Type
enum:
Values
12
Default:
1

Request

POST

/api/v4/stamps

curl --location 'https://test.fiscalapi.com/api/v4/stamps' \
--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 '{
  "fromPersonId": "1",
  "toPersonId": "1a18f812-c623-448f-a222-9b7e4e3fd4b2",
  "amount": 99,
  "comments": "No se confirmó el pago..."
}'

Response

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