Autenticación

Todas las solicitudes a la API requieren autenticación mediante un client secret. Esta página explica cómo funciona la autenticación y las mejores prácticas para mantener sus credenciales seguras.

Cómo Funciona

La API utiliza un esquema de autenticación simple basado en headers. A cada operador se le asigna un client secret único (un UUID) que debe incluirse en cada solicitud.

Formato del Header

X-Client-Secret: your-uuid-secret-here

Ejemplo de Solicitud Completa

curl -X GET 'https://api.syssoft1.com/api/client/reports/transactions' \
  -H 'Accept: application/json' \
  -H 'X-Client-Secret: fd5a9710-d7f8-47af-a2c5-d553f9029706'

Respuestas de Error

Header Faltante

Si el header X-Client-Secret no se incluye en la solicitud:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "Invalid or inactive client secret",
  "error": "unauthorized"
}

Secret Inválido

Si el secret proporcionado no coincide con ningún cliente activo:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "Invalid or inactive client secret",
  "error": "unauthorized"
}

Cliente Inactivo

Si su cuenta de cliente ha sido desactivada, recibirá la misma respuesta 401 Unauthorized. Contacte a su administrador para reactivar el acceso.

Mejores Prácticas de Seguridad

Nunca Exponga su Secret en Código del Lado del Cliente

Su client secret nunca debe aparecer en JavaScript del frontend, código fuente de aplicaciones móviles o cualquier código que se ejecute en el navegador. Un secret filtrado otorga acceso completo a sus datos de reportes.

Recomendaciones

• Almacene el secret en variables de entorno en su servidor (ej., CLIENT_API_SECRET).
• Realice las llamadas a la API desde su backend — nunca desde el navegador.
• Use HTTPS — todas las solicitudes a api.syssoft1.com se sirven sobre TLS.
• Rote su secret si sospecha que ha sido comprometido (contacte a su administrador).
• Restrinja el acceso al secret dentro de su organización solo a quienes lo necesiten.

Evite

• No incluya el secret en archivos fuente que se suben al control de versiones.
• No comparta el secret por canales inseguros (email, chat sin encriptación).
• No incluya el secret en parámetros de consulta de la URL — use el header en su lugar.
• No registre el valor completo del secret en los logs de la aplicación.

Ejemplo: Integración del Lado del Servidor

Node.js (usando fetch)

const CLIENT_SECRET = process.env.CLIENT_API_SECRET;

const response = await fetch(
  'https://api.syssoft1.com/api/client/reports/transactions?page=1',
  {
    headers: {
      'Accept': 'application/json',
      'X-Client-Secret': CLIENT_SECRET,
    },
  }
);

const data = await response.json();

Python (usando requests)

import os
import requests

CLIENT_SECRET = os.environ['CLIENT_API_SECRET']

response = requests.get(
    'https://api.syssoft1.com/api/client/reports/transactions',
    params={'page': 1},
    headers={
        'Accept': 'application/json',
        'X-Client-Secret': CLIENT_SECRET,
    },
)

data = response.json()

PHP (usando cURL)

$clientSecret = getenv('CLIENT_API_SECRET');

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.syssoft1.com/api/client/reports/transactions?page=1',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-Client-Secret: ' . $clientSecret,
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);