Search by

softan / users-php-sdk

softansol

SDK PHP para Softan Users — gestion de usuarios y asociaciones de aplicacion

v0.2.8 2026-10-15 20:02 UTC

This package is auto-updated.

Last update: 2026-11-16 18:16:55 UTC


README

Latest Stable Version Total Downloads License

Descripción

SDK oficial para integrar aplicaciones con Softan Users en PHP. Expone métodos estáticos de alto nivel para gestionar usuarios, asociaciones de aplicación y datos comunes (países, tipos de identificación).

Las credenciales de acceso a la API están embebidas en el SDK (sdk_meta.json). No se requiere ninguna configuración manual de API keys.

Requisitos

  • PHP 8.1 o superior
  • Composer 2
  • Extensiones: ext-curl, ext-json

Instalación

composer require softan/users-php-sdk:^0.2.8

Listo. No se necesita ningún paso adicional — las credenciales están embebidas.

Alternativa: instalación desde GitHub (VCS)

composer config repositories.softan-users vcs https://github.com/softansoluciones/softan-users-php-sdk
composer require softan/users-php-sdk:dev-main

Quickstart

<?php
require __DIR__ . '/vendor/autoload.php';

use SoftanUsers\Services;

// Listar todos los usuarios (entorno stg por defecto)
$users = Services::listUsers();

// Crear un usuario (solo nombre, apellido y correo son obligatorios)
$created = Services::createUser([
    'user_name'      => 'Juan',
    'user_last_name' => 'Pérez',
    'user_email'     => 'juan@example.com',
]);

Uso en código

Users

use SoftanUsers\Services;

// Listar todos los usuarios
$list = Services::listUsers();

// Ver un usuario por ID
$user = Services::showUser(42);

// Crear usuario con todos los datos
$created = Services::createUser([
    'user_name'           => 'María',
    'user_last_name'      => 'García',
    'user_email'          => 'maria@example.com',
    'identification_type' => 1,         // Opcional: ID del tipo de identificación
    'user_identification' => '987654',  // Opcional: número de documento
    'country_id'          => 48,        // Opcional: ID del país (Colombia)
    'user_phone'          => '+573001234567',  // Opcional
]);

// Crear usuario solo con los datos obligatorios
$created = Services::createUser([
    'user_name'      => 'Pedro',
    'user_last_name' => 'Ruiz',
    'user_email'     => 'pedro@example.com',
]);

// Actualizar usuario (requiere user_id, nombre, apellido, correo y user_status)
$updated = Services::updateUser([
    'user_id'        => 42,
    'user_name'      => 'María',
    'user_last_name' => 'García',
    'user_email'     => 'maria@example.com',
    'user_status'    => 1,  // 1=activo, 2=inactivo, 3=sin verificar
    'country_id'     => 49, // Opcional: si se envía, reemplaza el valor guardado
]);

// Eliminar usuario
$deleted = Services::deleteUser(42);

Campos opcionales (identification_type, user_identification, country_id, user_phone):

Operación Si no se envían (o van null / '') Si se envían con valor
createUser Se guardan como NULL (sin información) Se guardan
updateUser Se conserva el valor que ya tiene el usuario Reemplazan el valor guardado

Un campo ya guardado no se puede vaciar desde el SDK; solo reemplazar por otro valor.

Filtrar usuarios (server-side)

// Filtrado básico
$result = Services::filterUsers([
    'filters' => ['user_status' => 1, 'user_email' => '%@softansol.com'],
    'page'     => 1,
    'per_page' => 20,
    'order_by' => 'created_at',
    'order_dir'=> 'desc',
]);

// $result['data']['users']      → array de usuarios
// $result['data']['pagination'] → { page, per_page, total, total_pages }

Campos filtrables: user_id, identification_type, user_identification, user_name, user_last_name, user_email, user_phone, country_id, user_status, created_at (range), updated_at (range)

Modos de filtrado:

  • Exacto: 'user_status' => 1
  • LIKE: 'user_email' => '%@softansol.com'
  • IN: 'user_status' => [1, 2]
  • Rango: 'from_created_at' => '2025-01-01', 'to_created_at' => '2025-12-31'

Users Apps (asociaciones usuario-aplicación)

// Listar todas las asociaciones
$associations = Services::listUserApps();

// Ver una asociación por ID
$assoc = Services::showUserApp(10);

// Crear asociación
$created = Services::createUserApp([
    'user_id'        => 42,
    'app_identifier' => 'SOM-XXXX',
]);

// Actualizar asociación
$updated = Services::updateUserApp([
    'user_app_id'     => 10,
    'user_id'         => 42,
    'app_identifier'  => 'SOM-XXXX',
    'user_app_status' => 1,  // 1=activo, 2=inactivo, 3=sin verificar
]);

// Eliminar asociación
$deleted = Services::deleteUserApp(10);

Filtrar asociaciones usuario-aplicación (server-side)

$result = Services::filterUserApps([
    'filters' => ['app_identifier' => 'SOM-65B', 'user_app_status' => 1],
    'page'     => 1,
    'per_page' => 50,
]);

// $result['data']['usersapps']  → array de asociaciones (incluye user_email, user_name)
// $result['data']['pagination'] → { page, per_page, total, total_pages }

Campos filtrables: user_app_id, user_id, app_identifier, user_app_status, user_email, user_name, user_last_name, user_status, created_at (range), updated_at (range)

Commons

// Listar países disponibles
$countries = Services::listCountries();

// Listar tipos de identificación
$idTypes = Services::listIdentificationTypes();

Autenticación

Todas las operaciones del SDK (users, usersapps y datos comunes como países y tipos de identificación) usan el canal internal del API:

Headers enviados Uso
X-API-KEY + X-App-Id Todos los métodos de Services::*

Las credenciales (api_key y app_id) están embebidas en el SDK y se seleccionan automáticamente según el entorno activo. El SDK no usa la public_api_key del API.

Entornos

El SDK incluye credenciales para stg y prod. El entorno por defecto es stg.

El entorno activo se resuelve en este orden (mayor a menor prioridad):

Prioridad Mecanismo
1 SDK::$CONFIG['active_environment'] — override programático
2 sdk_config.json → active_environment — escrito por users-set-env.php
3 sdk_meta.json → default_environment (valor del paquete: stg)

Opción A — CLI (recomendado)

php vendor/bin/users-set-env.php              # interactivo
php vendor/bin/users-set-env.php --env=prod
php vendor/bin/users-set-env.php --env=stg

Escribe sdk_config.json en la raíz del proyecto. El cambio persiste entre requests y sobrevive composer update.

Opción B — Override programático

Útil cuando el entorno se determina en código (multi-tenant, flags de configuración, etc.). Debe ejecutarse antes de la primera llamada a Services::*.

use SoftanUsers\SDK;
use SoftanUsers\Services;

SDK::$CONFIG = ['active_environment' => 'prod'];

$users = Services::listUsers();

TLS

La verificación TLS está habilitada por defecto. Para desarrollo puedes desactivarla por llamada:

Services::listUsers(null, false);        // segundo parámetro: $verifyTLS
Services::createUser($payload, null, false);

Compatibilidad

  • PHP: 8.1+
  • Sistemas: Windows, Linux, macOS

Desarrollo

composer install
composer test

CI: el workflow en .github/workflows/ci.yml valida Composer e integra PHPUnit en PHP 8.1/8.2/8.3.

Licencia

MIT (ver composer.json).