README

Descripción

SDK oficial para integrar aplicaciones con Softan Connect en PHP. Expone métodos de alto nivel para crear y validar tokens y OTP. Incluye utilidades CLI para configurar credenciales y administrar entornos (stg/prod).

Comandos CLI (referencia rápida)

Requisitos

• PHP 8.0 o superior
• Composer 2

Instalación

composer require softan/connect-php-sdk:^0.0.6

Luego inicializa la configuración con tus credenciales (stg por defecto):

php vendor/bin/connect-setup.php

Alternativa: instalación desde GitHub (VCS)

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

Quickstart

1. Instalar el SDK:

composer require softan/connect-php-sdk:^0.0.6

1. Configurar credenciales:

php vendor/bin/connect-setup.php

1. Usar en código:

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

use SoftanConnect\Services;

$userId = 12345;
$resCreate = Services::requestToken(["user_id" => $userId]);

$token = $resCreate['data']['token'] ?? $resCreate['Response']['token'] ?? null;

if ($token) {
    $resStatus = Services::tokenStatus(["token" => $token, "user_id" => $userId]);
    var_dump($resStatus);
} else {
    echo "No se obtuvo token. Revisa credenciales y entorno.";
}

Primeros pasos (CLI)

Configuración inicial (stg)

php vendor/bin/connect-setup.php

Solicita: developer email, API Key (X-API-KEY), X-Connect-Info y App Identifier. Valida las credenciales contra la API antes de guardar.

Modo no interactivo:

php vendor/bin/connect-setup.php \
  --email="dev@example.com" \
  --api-key="<X-API-KEY>" \
  --connect-info="<X-Connect-Info>" \
  --app-id="SOM-XXXX" \
  --env=stg \
  --verify-tls=true

Agregar entorno de producción

php vendor/bin/connect-add-env.php

Solicita: API Key, X-Connect-Info y App Identifier. Configura producción usando la base URL definida en sdk_meta.json, sin pisar la configuración existente.

Cambiar entorno activo

php vendor/bin/connect-switch-env.php

Lista los entornos disponibles y permite seleccionar cuál usar como activo.

Uso en código

use SoftanConnect\Services;

// Token: crear
$resCreate = Services::requestToken(["user_id" => 12345]);

// Token: estado
$resStatus = Services::tokenStatus(["token" => "<TOKEN>", "user_id" => 12345]);

// OTP: crear
$resOtp = Services::requestOtp(["user_id" => 12345]);

// OTP: validar
$resVal = Services::validateOtp(["otp_code" => 123456, "user_id" => 12345]);

// Validar credenciales del desarrollador
$resCreds = Services::validateCredentials();

Entornos

• El entorno por defecto es stg.
• Para agregar prod: php vendor/bin/connect-add-env.php
• Para cambiar el activo: php vendor/bin/connect-switch-env.php
• Todas las llamadas usan automáticamente el entorno activo para base URL y headers.

Configuración

La configuración se gestiona en sdk_config.json (creado por los scripts CLI, no versionar). Contiene las credenciales por entorno y el entorno activo.

{
  "developer_email": "dev@example.com",
  "app_identifier": "SOM-XXXX",
  "active_environment": "stg",
  "environments": {
    "stg": {
      "api_key": "...",
      "connect_info": "...",
      "connect_sdk": "..."
    }
  }
}

TLS

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

Services::requestToken($data, null, false);
Services::tokenStatus($data, null, false);
Services::requestOtp($data, null, false);
Services::validateOtp($data, null, false);

Caché de tokens

El SDK cachea respuestas de tokens y OTP para reducir llamadas repetitivas:

• TTL por defecto: 3600 segundos (1 hora)
• Directorio: cache/ junto a sdk_config.json

Para personalizar:

{
  "cache": {
    "dir": "/ruta/absoluta/opcional",
    "ttl_seconds": 1800
  }
}

Solución de problemas

• 403 en tokens/otp: verifica que configuraste credenciales y que el entorno activo es correcto.
• 0 o 404: puede indicar user_id inválido o inactivo.
• Conflicto de binarios: todos los scripts de Softan Connect usan el prefijo connect- para evitar conflictos con otros paquetes (connect-setup.php, connect-add-env.php, connect-switch-env.php).

Compatibilidad

• PHP: 8.0+
• 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).