Crea, consulta, actualiza y elimina las cuentas hijas de tu cuenta distribuidora. Las mismas que supervisas en Portal SW › Clientes, desde tu código.
✓Antes de empezar
- 1Obtén un Bearer Token con tu usuario y contraseña de SW. Se recomienda usar un token infinito. Todas las operaciones lo piden en el header
Authorization. - 2Crea la cuenta hija con Crear. La respuesta trae su
idUser. - 3Actualizar y Eliminar piden ese
userIden el path. Si no lo guardaste, recupéralo con Consultar.
💡 Nota Importante: para pausar una cuenta usa Activar/Desactivar. Eliminar borra la cuenta y no procede si todavía tiene timbres.
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
Cuatro acciones sobre las cuentas hijas. Elige una y abajo se arma su referencia completa: endpoint, headers, parámetros, ejemplo y respuesta.
Crea una cuenta hija desde tu cuenta distribuidora, con sus timbres iniciales. Después la puedes supervisar en Portal SW › Clientes.
POST/management/v2/api/dealers/users
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
name
string
REQUERIDO
Nombre del usuario.
taxId
string
REQUERIDO
RFC del usuario.
email
string
REQUERIDO
Correo del usuario. Será su username.
stamps
int
REQUERIDO
Timbres a asignar en la creación.
isUnlimited
boolean
REQUERIDO
Indica si tendrá timbres ilimitados.
password
string
REQUERIDO
Contraseña del usuario. Revisa las políticas abajo.
notificationEmail
string
OPCIONAL
Correo donde recibirá notificaciones.
phone
string
OPCIONAL
Número de teléfono del usuario.
Mínimo 8 caracteres
Al menos una letra mayúscula
Al menos una letra minúscula
Al menos un número
Al menos un símbolo especial
Sin espacios en blanco
Distinta al nombre de usuario
Sin símbolos fuera de la lista aceptada
Devuelve los usuarios asociados a tu token, paginados de 10 en 10. Sin filtros trae todas tus cuentas hijas.
GET/management/v2/api/dealers/users
Propiedad
Uso
Descripción
Authorization
REQUERIDO
Bearer {token} — token de tu cuenta distribuidora.
💡 Todos los filtros son opcionales y se pueden combinar con &.
Propiedad
Tipo
Uso
Descripción
TaxId
string
OPCIONAL
RFC ligado al usuario a consultar.
Email
string
OPCIONAL
Correo del usuario a consultar.
Name
string
OPCIONAL
Nombre del usuario a consultar.
IdUser
guid
OPCIONAL
GUID identificador del usuario.
IsActive
boolean
OPCIONAL
Filtra usuarios activos (true) o inactivos (false).
Page
int
OPCIONAL
Página a extraer. Por defecto 1.
PerPage
int
OPCIONAL
Registros por página. Por defecto 10, máximo 50.
Filtra la lista por el RFC ligado al usuario.
GET/management/v2/api/dealers/users?TaxId=XIA190128J61
Propiedad
Uso
Descripción
Authorization
REQUERIDO
Bearer {token} — token de tu cuenta distribuidora.
💡 Todos los filtros son opcionales y se pueden combinar con &.
Propiedad
Tipo
Uso
Descripción
TaxId
string
OPCIONAL
RFC ligado al usuario a consultar.
Email
string
OPCIONAL
Correo del usuario a consultar.
Name
string
OPCIONAL
Nombre del usuario a consultar.
IdUser
guid
OPCIONAL
GUID identificador del usuario.
IsActive
boolean
OPCIONAL
Filtra usuarios activos (true) o inactivos (false).
Page
int
OPCIONAL
Página a extraer. Por defecto 1.
PerPage
int
OPCIONAL
Registros por página. Por defecto 10, máximo 50.
Trae un usuario específico por su GUID. Útil para verificar su estado y saldo antes de actualizarlo.
GET/management/v2/api/dealers/users?IdUser=a8b8881a-3456-481b-96b9-e02fd895f5be
Propiedad
Uso
Descripción
Authorization
REQUERIDO
Bearer {token} — token de tu cuenta distribuidora.
💡 Todos los filtros son opcionales y se pueden combinar con &.
Propiedad
Tipo
Uso
Descripción
TaxId
string
OPCIONAL
RFC ligado al usuario a consultar.
Email
string
OPCIONAL
Correo del usuario a consultar.
Name
string
OPCIONAL
Nombre del usuario a consultar.
IdUser
guid
OPCIONAL
GUID identificador del usuario.
IsActive
boolean
OPCIONAL
Filtra usuarios activos (true) o inactivos (false).
Page
int
OPCIONAL
Página a extraer. Por defecto 1.
PerPage
int
OPCIONAL
Registros por página. Por defecto 10, máximo 50.
Combina filtros con “&”. En el ejemplo: un correo específico y solo si la cuenta está activa.
GET/management/v2/api/dealers/users?Email=correo@example.com&IsActive=true
Propiedad
Uso
Descripción
Authorization
REQUERIDO
Bearer {token} — token de tu cuenta distribuidora.
💡 Todos los filtros son opcionales y se pueden combinar con &.
Propiedad
Tipo
Uso
Descripción
TaxId
string
OPCIONAL
RFC ligado al usuario a consultar.
Email
string
OPCIONAL
Correo del usuario a consultar.
Name
string
OPCIONAL
Nombre del usuario a consultar.
IdUser
guid
OPCIONAL
GUID identificador del usuario.
IsActive
boolean
OPCIONAL
Filtra usuarios activos (true) o inactivos (false).
Page
int
OPCIONAL
Página a extraer. Por defecto 1.
PerPage
int
OPCIONAL
Registros por página. Por defecto 10, máximo 50.
Modifica los datos de una cuenta hija: nombre, RFC, correo de notificaciones, teléfono o timbres ilimitados.
PUT/management/v2/api/dealers/users/{userId}
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 del usuario. Se obtiene con Consultar (idUser).
Propiedad
Tipo
Uso
Descripción
iduser
guid
REQUERIDO
ID del usuario a actualizar. Debe coincidir con el del path.
name
string
OPCIONAL
Nuevo nombre del usuario.
taxId
string
OPCIONAL
Nuevo RFC del usuario.
notificationEmail
string
OPCIONAL
Nuevo correo de notificaciones.
phone
string
OPCIONAL
Nuevo número telefónico.
isUnlimited
boolean
OPCIONAL
Indica si tendrá timbres ilimitados.
Cambia la contraseña de una cuenta hija desde tu cuenta distribuidora. No modifica ningún otro dato.
PATCH/management/v2/api/dealers/users/{userId}/password
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 del usuario. Se obtiene con Consultar (idUser).
Propiedad
Tipo
Uso
Descripción
newPassword
string
REQUERIDO
Nueva contraseña. No puede ir vacía ni repetir una anterior.
Mínimo 8 caracteres
Al menos una letra mayúscula
Al menos una letra minúscula
Al menos un número
Al menos un símbolo especial
Sin espacios en blanco
Distinta al nombre de usuario
Sin símbolos fuera de la lista aceptada
Activa o desactiva una cuenta hija. Es la opción recomendada para pausar una cuenta temporalmente.
PATCH/management/v2/api/dealers/users/{userId}
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 del usuario. Se obtiene con Consultar (idUser).
Propiedad
Tipo
Uso
Descripción
isActive
boolean
REQUERIDO
true para activar, false para desactivar.
Elimina de forma definitiva una cuenta hija que ya no necesites.
DELETE/management/v2/api/dealers/users/{userId}
Propiedad
Uso
Descripción
Authorization
REQUERIDO
Bearer {token} — token de tu cuenta distribuidora.
Propiedad
Tipo
Uso
Descripción
userId
guid
REQUERIDO
ID del usuario. Se obtiene con Consultar (idUser).
Ejemplo Request
data-repo=”https://github.com/orgs/lunasoft/repositories” data-repo-label=”Ver todos los SDK en GitHub →”>
>
>
>
>
>
>
>
>
💡 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
Indica el estado de la respuesta.
data
object | null
Datos del usuario creado. Guarda idUser para las demás operaciones.
Causa: El correo ya pertenece a otro usuario. El email funciona como username, así que no se puede repetir.
Solución: Usa otro correo. Si la cuenta ya existía, búscala con Consultar ?Email= y actualízala en lugar de crearla de nuevo.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
message
string
Solo aparece en respuestas de error. Describe la razón del error.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
data
array | null
Lista de usuarios. Cada elemento trae los datos de un usuario registrado.
meta
object | null
Paginación: página actual, registros por página y totales.
links
object | null
Rutas Self, First y End para navegar entre páginas.
Causa: Algún filtro trae un formato inválido. El caso más común es un IdUser que no es un GUID completo.
Solución: Envía IdUser con sus 36 caracteres (32 dígitos y 4 guiones) y codifica en la URL los valores con espacios o símbolos, como Name o Email.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
message
string
Solo aparece en respuestas de error. Describe la razón del error.
messageDetail
string
Detalle adicional del error cuando existe.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
data
array | null
Lista de usuarios. Cada elemento trae los datos de un usuario registrado.
meta
object | null
Paginación: página actual, registros por página y totales.
links
object | null
Rutas Self, First y End para navegar entre páginas.
Causa: Algún filtro trae un formato inválido. El caso más común es un IdUser que no es un GUID completo.
Solución: Envía IdUser con sus 36 caracteres (32 dígitos y 4 guiones) y codifica en la URL los valores con espacios o símbolos, como Name o Email.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
message
string
Solo aparece en respuestas de error. Describe la razón del error.
messageDetail
string
Detalle adicional del error cuando existe.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
data
array | null
Lista de usuarios. Cada elemento trae los datos de un usuario registrado.
meta
object | null
Paginación: página actual, registros por página y totales.
links
object | null
Rutas Self, First y End para navegar entre páginas.
Causa: Algún filtro trae un formato inválido. El caso más común es un IdUser que no es un GUID completo.
Solución: Envía IdUser con sus 36 caracteres (32 dígitos y 4 guiones) y codifica en la URL los valores con espacios o símbolos, como Name o Email.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
message
string
Solo aparece en respuestas de error. Describe la razón del error.
messageDetail
string
Detalle adicional del error cuando existe.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
data
array | null
Lista de usuarios. Cada elemento trae los datos de un usuario registrado.
meta
object | null
Paginación: página actual, registros por página y totales.
links
object | null
Rutas Self, First y End para navegar entre páginas.
Causa: Algún filtro trae un formato inválido. El caso más común es un IdUser que no es un GUID completo.
Solución: Envía IdUser con sus 36 caracteres (32 dígitos y 4 guiones) y codifica en la URL los valores con espacios o símbolos, como Name o Email.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
message
string
Solo aparece en respuestas de error. Describe la razón del error.
messageDetail
string
Detalle adicional del error cuando existe.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
data
string
UUID del usuario actualizado.
Causa: Todos los valores enviados son iguales a los que ya tiene el usuario: no hay nada que cambiar.
Solución: Envía solo las propiedades que cambian y deja el resto en null. Consulta el usuario por ID para comparar sus valores actuales.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
message
string
Solo aparece en respuestas de error. Describe la razón del error.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
data
string | null
Confirmación de la petición.
Causa: La nueva contraseña ya se usó antes en esa cuenta.
Solución: Genera una contraseña nueva que cumpla las políticas: mayúscula, minúscula, número, símbolo y mínimo 8 caracteres.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
data
object | null
Datos del usuario activado o desactivado.
Causa: La petición llegó sin cuerpo, o sin el header Content-Type: application/json.
Solución: Envía el JSON {“isActive”: true|false} con el header Content-Type: application/json.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
message
string
Solo aparece en respuestas de error. Describe la razón del error.
Causa: La cuenta todavía tiene timbres asignados.
Solución: Retira los timbres con la API Balance V2 antes de eliminar, o desactiva la cuenta en su lugar.
Propiedad
Tipo
Descripción
status
string
Indica el estado de la respuesta.
message
string
Solo aparece en respuestas de error. Describe la razón del error.
En SW® somos mejores para TI, es por ello que tu opinión es muy importante, por favor ayúdanos calificando este articulo y dejando tus comentarios.