Timbres

Un timbre es el crédito que se consume cada vez que timbras un CFDI ante el SAT. En Fiscalapi, cada persona tiene su propio saldo de timbres, y puedes moverlos entre las personas de tu cuenta con transferencias y retiros. Cada movimiento queda registrado y puedes consultarlo por su ID o en una lista paginada.

Transferir y retirar timbres usan el mismo endpoint (POST /api/v4/stamps) y el mismo cuerpo, descrito en Transferir timbres. Ambas operaciones devuelven data: true cuando terminan con éxito.

El mismo registro de movimientos maneja tres tipos de crédito, que se distinguen por el campo creditType y nunca mezclan sus saldos. Cada tipo afecta un saldo de la persona, que los devuelve en balances, un elemento por tipo:

`creditType`	Qué mueve	Saldo de la persona
`1` (valor por omisión)	Timbres.	`availableBalance`
`2`	Créditos de validación, que se consumen al validar un CFDI ante el SAT con validaciones SAT.	`availableValidationBalance`
`3`	Créditos de ticket, que se consumen al registrar un ticket de Auto CFDI.	El elemento de `balances` del tipo 3.

Modelo movimiento

El modelo movimiento (StampTransaction) representa una transacción de timbres entre dos personas. Es el modelo que devuelven Listar movimientos y Obtener movimiento por ID.

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
123
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, diez por página de forma predeterminada. Usa los parámetros de consulta para elegir la página y su tamaño.

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 movimientos por página, de 1 a 50.
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 obtiene un movimiento de timbres por su ID.

Errores

En el mensaje, que llega en details, <id> es el id del movimiento.

Estado	Cuándo ocurre	Mensaje
404	El movimiento no existe o pertenece a otra cuenta.	No such resource for the given Id: <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 transfiere timbres de una persona a otra.

Para reintentar sin riesgo de transferir dos veces, envía el encabezado opcional Idempotency-Key. Consulta Solicitudes idempotentes.

Modelo

Name
fromPersonId
Type
string
required
Description
ID de la persona que envía los timbres.
Name
toPersonId
Type
string
required
Description
ID de la persona que recibe los timbres.
Name
amount
Type
integer | number
required
Description
Cantidad de timbres que se transfieren.
Name
comments
Type
string?
Description
Comentario de la transferencia, de hasta 100 caracteres.
Name
creditType
Type
integer | number?
expandible
Description
Tipo de crédito que se transfiere: 1 timbres, 2 créditos de validación o 3 créditos de ticket. Se revisa el saldo del origen en ese tipo de crédito, y cualquier otro valor responde 400.
Type
enum:
Values
123
Default:
1

La transferencia es atómica. Origen y destino deben ser personas distintas, el saldo del origen debe alcanzar y los dos ID deben ser un GUID. Las personas de sistema (0, 1 y -1) no tienen un ID con ese formato, así que no pueden ser origen ni destino: el endpoint responde 400.

Errores

En el mensaje de saldo insuficiente, n es el saldo disponible del origen y m es la cantidad requerida.

Estado	Cuándo ocurre	Mensaje
400	El ID de origen no es un GUID, como el de una persona de sistema. Llega como falla de validación en FromPersonId.	La persona origen debe ser un identificador GUID de 36 caracteres (formato 8-4-4-4-12)
400	El ID de destino no es un GUID, como el de una persona de sistema. Llega como falla de validación en ToPersonId.	La persona destino debe ser un identificador GUID de 36 caracteres (formato 8-4-4-4-12)
400	Origen y destino son la misma persona.	No puedes transferir timbres a ti mismo
403	El saldo del origen no alcanza.	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": "5c0e1a3b-8f2d-4e6a-9b71-3d4c2f8e6a10",
  "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 retira timbres de una persona y los devuelve a otra. Usa el mismo endpoint y el mismo cuerpo que Transferir timbres, con las mismas reglas y errores.

Modelo

Name
fromPersonId
Type
string
required
Description
ID de la persona de la que se retiran los timbres.
Name
toPersonId
Type
string
required
Description
ID de la persona a la que se devuelven los timbres.
Name
amount
Type
integer | number
required
Description
Cantidad de timbres a retirar.
Name
comments
Type
string?
Description
Comentario del retiro, de hasta 100 caracteres.
Name
creditType
Type
integer | number?
expandible
Description
Tipo de crédito que se retira: 1 timbres, 2 créditos de validación o 3 créditos de ticket.
Type
enum:
Values
123
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": "1a18f812-c623-448f-a222-9b7e4e3fd4b2",
  "toPersonId": "5c0e1a3b-8f2d-4e6a-9b71-3d4c2f8e6a10",
  "amount": 99,
  "comments": "No se confirmó el pago..."
}'

Response

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