Stamps

A stamp is one credit, used each time you stamp a CFDI (Mexico's electronic invoice) with the SAT (Mexico's tax authority, Servicio de Administración Tributaria). In Fiscalapi, each person (any individual or legal entity registered in your tenant) has their own stamp balance. You can move stamps between the people in your tenant (the space in Fiscalapi that holds your issuers, recipients, credits, and data) with transfers and withdrawals. Every transaction is recorded, and you can retrieve it by its ID or in a paginated list.

Transferring and withdrawing stamps use the same endpoint (POST /api/v4/stamps) and the same body, described in Transfer stamps. Both operations return data: true when they succeed.

The same transaction ledger handles three credit types. The creditType field tells them apart, and their balances never mix. Each type affects its own balance on the person, and the person returns those balances in balances, one element per type:

`creditType`	What it moves	Person's balance
`1` (default)	Stamps.	`availableBalance`
`2`	Validation credits, used when you validate a CFDI with the SAT through SAT validations.	`availableValidationBalance`
`3`	Ticket credits, used when you record a ticket (a sales receipt your customer can later turn into a CFDI) in Auto CFDI invoicing.	The `balances` element for type 3.

Transaction model

The transaction model (StampTransaction) represents a stamp transaction between two people. It's the model that List transactions and Get a transaction by ID return.

Properties

Name
consecutive
Type
integer | number?
Description
The transaction's sequential number, assigned by Fiscalapi.
Name
fromPerson
Type
object (Person)?
The source person of the transaction (the person who sends the stamps).
Name
tin
Type
string?
Description
The source person's RFC (Mexico's taxpayer ID, Registro Federal de Contribuyentes).
Name
legalName
Type
string?
Description
The source person's legal name (as registered with the SAT), or their name if they're an individual.
Name
id
Type
string?
Description
The source person's unique identifier.
Name
toPerson
Type
object (Person)?
The destination person of the transaction (the person who receives the stamps).
Name
tin
Type
string?
Description
The destination person's RFC.
Name
legalName
Type
string?
Description
The destination person's legal name, or their name if they're an individual.
Name
id
Type
string?
Description
The destination person's unique identifier.
Name
amount
Type
integer | number?
Description
The number of stamps in the transaction.
Name
transactionType
Type
integer | number?
expandable
Description
The transaction type.
Type
enum:
Values
123
Name
transactionStatus
Type
integer | number?
expandable
Description
The transaction status.
Type
enum:
Values
123
Name
referenceId
Type
string?
Description
The reference identifier associated with the transaction.
Name
comments
Type
string?
Description
Comments on the transaction. It can be null.
Name
creditType
Type
integer | number?
expandable
Description
The credit type the transaction affects.
Type
enum:
Values
123
Name
id
Type
string?
Description
The transaction's unique identifier, assigned by Fiscalapi.

GET/api/v4/stamps

List transactions

This endpoint returns a paginated list of stamp transactions, ten per page by default. Use the query parameters to choose the page and its size.

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 transactions per page, from 1 to 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>

Get a transaction by ID

This endpoint retrieves a stamp transaction by its ID.

Errors

In the message, which arrives in details, <id> is the transaction ID.

Status	When it happens	Message
404	The transaction doesn't exist or belongs to another tenant.	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

Transfer stamps

This endpoint transfers stamps from one person to another.

Request body

Name
fromPersonId
Type
string
required
Description
The ID of the person who sends the stamps.
Name
toPersonId
Type
string
required
Description
The ID of the person who receives the stamps.
Name
amount
Type
integer | number
required
Description
The number of stamps to transfer.
Name
comments
Type
string?
Description
A comment on the transfer, up to 100 characters.
Name
creditType
Type
integer | number?
expandable
Description
The credit type to transfer: 1 stamps, 2 validation credits, or 3 ticket credits. Fiscalapi checks the source's balance in that credit type, and any other value returns 400.
Type
enum:
Values
123
Default:
1

The transfer is atomic. The source and the destination must be different people, the source's balance must cover the amount, and both IDs must be GUIDs. The system people (0, 1, and -1) don't have an ID in that format, so they can't be the source or the destination: the endpoint returns 400.

Errors

In the insufficient balance message, n is the source's available balance and m is the required amount.

Status	When it happens	Message
400	The source ID isn't a GUID, such as a system person's ID. It arrives as a validation failure on FromPersonId.	La persona origen debe ser un identificador GUID de 36 caracteres (formato 8-4-4-4-12)
400	The destination ID isn't a GUID, such as a system person's ID. It arrives as a validation failure on ToPersonId.	La persona destino debe ser un identificador GUID de 36 caracteres (formato 8-4-4-4-12)
400	The source and the destination are the same person.	No puedes transferir timbres a ti mismo
403	The source's balance isn't enough.	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

Withdraw stamps

This endpoint withdraws stamps from one person and returns them to another. It uses the same endpoint and body as Transfer stamps, with the same rules and errors.

Request body

Name
fromPersonId
Type
string
required
Description
The ID of the person the stamps are withdrawn from.
Name
toPersonId
Type
string
required
Description
The ID of the person the stamps are returned to.
Name
amount
Type
integer | number
required
Description
The number of stamps to withdraw.
Name
comments
Type
string?
Description
A comment on the withdrawal, up to 100 characters.
Name
creditType
Type
integer | number?
expandable
Description
The credit type to withdraw: 1 stamps, 2 validation credits, or 3 ticket credits.
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
}