Consulta el saldo de timbres de tu cuenta o de tus subcuentas, y abona o retira timbres a tus clientes desde tu código.
Ver librerías✓Antes de empezar
- 1Obtén un Bearer Token de tu cuenta distribuidora con tu usuario y contraseña de SW. Se recomienda usar un token infinito. Todas las operaciones lo piden en el header
Authorization. - 2Ubica el
idUserde la subcuenta con API Usuarios V2 › Consultar. - 3Antes de Eliminar, revisa su
stampsBalancecon Consultar › Por ID: no puedes retirar más timbres de los que tiene.
💡 Nota Importante: Mi saldo devuelve los timbres de la cuenta dueña del token. Por ID, Añadir y Eliminar operan sobre tus subcuentas.
URL´s
Marca tu ambiente activo. Los botones de copiar y los ejemplos de código de abajo se arman con la base que elijas aquí.
🛠️ Pruebas:
https://api.test.sw.com.mx
🚀 Productivo:
https://api.sw.com.mx
🔗 Endpoint
Tres acciones sobre el saldo de timbres. Elige una y abajo se arma su referencia completa: endpoint, headers, parámetros, ejemplo y respuesta.
Abona una cantidad de timbres a una de tus subcuentas. La respuesta trae su nuevo saldo.
POST/management/v2/api/dealers/users/{userId}/stamps
Propiedad
Uso
Descripción
Authorization
REQUERIDO
Bearer {token} — token de tu cuenta distribuidora.
Content-Type
REQUERIDO
application/json — el cuerpo va como JSON.
Propiedad
Tipo
Uso
Descripción
userId
guid
REQUERIDO
ID de la subcuenta a la que se le agregarán timbres. Se obtiene con API Usuarios V2 › Consultar (idUser).
Propiedad
Tipo
Uso
Descripción
stamps
int
REQUERIDO
Cantidad de timbres a abonar.
comment
string
OPCIONAL
Comentario agregado al movimiento.
Revisa los timbres disponibles, usados y asignados de la cuenta asociada al token.
GET/management/v2/api/users/balance
Revisa los timbres disponibles de una de tus subcuentas, filtrando por su ID.
GET/management/v2/api/dealers/balance/users/{idUser}
Propiedad
Uso
Descripción
Authorization
REQUERIDO
Bearer {token} — token de tu cuenta distribuidora.
Propiedad
Tipo
Uso
Descripción
idUser
guid
REQUERIDO
ID de la subcuenta a consultar. Se obtiene con API Usuarios V2 › Consultar (idUser).
Retira una cantidad de timbres de una de tus subcuentas. La respuesta trae su nuevo saldo.
DELETE/management/v2/api/dealers/users/{userId}/stamps
🚨 Importante: no puedes retirar más timbres de los que la subcuenta tiene disponibles. Consulta antes su saldo con Consultar › Por ID. Los timbres retirados vuelven a la cuenta padre.
Propiedad
Uso
Descripción
Authorization
REQUERIDO
Bearer {token} — token de tu cuenta distribuidora.
Content-Type
REQUERIDO
application/json — el cuerpo va como JSON.
Propiedad
Tipo
Uso
Descripción
userId
guid
REQUERIDO
ID de la subcuenta a la que se le retirarán timbres. Se obtiene con API Usuarios V2 › Consultar (idUser).
Propiedad
Tipo
Uso
Descripción
stamps
int
REQUERIDO
Cantidad de timbres a descontar.
comment
string
OPCIONAL
Comentario agregado al movimiento.
Ejemplo Request
💡 Nota: Estos ejemplos están basados en los SDK de SW, pero puedes armar la petición directamente contra la API REST en el lenguaje que prefieras.
Respuesta
Propiedad
Tipo
Descripción
status
string
Estado de la respuesta: "success" o "error".
data
int | null
Total de timbres de la subcuenta después del abono.
Causa: El userId no existe o no pertenece a tu cuenta distribuidora.
Solución: Confirma el idUser con API Usuarios V2 › Consultar, usando el token de la cuenta distribuidora.
Propiedad
Tipo
Descripción
status
string
Estado de la respuesta: "success" o "error".
message
string
Solo aparece en respuestas de error. Describe la causa del fallo.
Propiedad
Tipo
Descripción
status
string
Estado de la respuesta: "success" o "error".
data
object | null
Saldo de la cuenta.
data.stampsBalance
int
Timbres disponibles.
data.stampsUsed
int
Timbres consumidos.
data.stampsAssigned
int
Total de timbres asignados.
data.isUnlimited
boolean
Indica si la cuenta tiene timbres ilimitados.
data.expirationDate
string | null
Fecha de vencimiento del saldo, si aplica.
data.lastTransaction
object | null
Último movimiento de timbres. Ver campos abajo.
Causa: El token no corresponde a una cuenta válida.
Solución: Genera un token nuevo con Autenticación V2 y repite la consulta.
Propiedad
Tipo
Descripción
status
string
Estado de la respuesta: "success" o "error".
message
string
Solo aparece en respuestas de error. Describe la causa del fallo.
Propiedad
Tipo
Descripción
status
string
Estado de la respuesta: "success" o "error".
data
object | null
Saldo de la cuenta.
data.stampsBalance
int
Timbres disponibles.
data.stampsUsed
int
Timbres consumidos.
data.stampsAssigned
int
Total de timbres asignados.
data.isUnlimited
boolean
Indica si la cuenta tiene timbres ilimitados.
data.expirationDate
string | null
Fecha de vencimiento del saldo, si aplica.
data.lastTransaction
object | null
Último movimiento de timbres. Ver campos abajo.
Causa: La subcuenta no pertenece a la cuenta distribuidora del token.
Solución: Verifica el idUser con API Usuarios V2 › Consultar, usando el token de la cuenta padre.
Propiedad
Tipo
Descripción
status
string
Estado de la respuesta: "success" o "error".
message
string
Solo aparece en respuestas de error. Describe la causa del fallo.
Propiedad
Tipo
Descripción
status
string
Estado de la respuesta: "success" o "error".
data
int | null
Total de timbres de la subcuenta después de retirar.
Causa: El userId no existe o no pertenece a tu cuenta distribuidora.
Solución: Confirma el idUser con API Usuarios V2 › Consultar, usando el token de la cuenta distribuidora.
Propiedad
Tipo
Descripción
status
string
Estado de la respuesta: "success" o "error".
message
string
Solo aparece en respuestas de error. Describe la causa del fallo.
Causa: La cantidad a retirar es mayor que el saldo disponible de la subcuenta.
Solución: Consulta su stampsBalance con Consultar › Por ID y envía una cantidad igual o menor.
Propiedad
Tipo
Descripción
status
string
Estado de la respuesta: "success" o "error".
message
string
Solo aparece en respuestas de error. Describe la causa del fallo.
📋 Campos de data.lastTransaction
El objeto trae 10 campos que describen el último movimiento de timbres de la cuenta, ya sea abono o retiro. Da clic en Ver los 10 campos para desplegar la tabla.
Campo
Tipo
Descripción
folio
int
Folio consecutivo del movimiento.
idUser
guid
ID de la cuenta que realizó el movimiento.
idUserReceiver
guid
ID de la cuenta que recibió el movimiento.
nameReceiver
string
Cuenta receptora: correo, RFC y nombre.
stampsIn
int | null
Timbres abonados. null si fue un retiro.
stampsOut
int | null
Timbres retirados. null si fue un abono.
stampsCurrent
int
Saldo de la cuenta después del movimiento.
comment
string | null
Comentario capturado en el movimiento.
date
string
Fecha y hora del movimiento.
isEmailSent
boolean
Indica si se envió notificación por correo.