Autenticación

Método de Autenticación

Tsalva API utiliza autenticación básica HTTP para todas las operaciones. Todas las peticiones deben incluir el header Authorization con las credenciales codificadas en Base64.

Esquema de Seguridad

securitySchemes:
  basicAuth:
    type: http
    scheme: basic

Obtener Credenciales

Para obtener las credenciales de acceso y la URL de la API, contacta al área de TI de RobPixels:

• Gerencia: gerencia@robpixels.com
• Soporte Técnico: soporte@robpixels.com

Te proporcionarán:

• Usuario: Tu nombre de usuario único
• Contraseña: Tu contraseña de API
• URL Base: La URL completa del endpoint de la API

Información requerida:

• Nombre de la empresa
• NIT o documento de identificación
• Contacto técnico responsable
• Descripción del uso previsto

Formato del Header

Authorization: Basic <credenciales_base64>

Donde <credenciales_base64> es la codificación Base64 de usuario:contraseña.

Ejemplos de Implementación

📍 Importante: En todos los ejemplos siguientes, reemplaza [URL_API] con la URL base proporcionada por el área de TI de RobPixels.

cURL

# Opción 1: Usar --user (automáticamente codifica en Base64)
curl -X POST "[URL_API]/api/v2/oferta" \
  --user "tu_usuario:tu_contraseña" \
  -H "Content-Type: application/json" \
  -d '{"uuid": "..."}'

# Opción 2: Codificación manual
curl -X POST "[URL_API]/api/v2/oferta" \
  -H "Authorization: Basic $(echo -n 'tu_usuario:tu_contraseña' | base64)" \
  -H "Content-Type: application/json" \
  -d '{"uuid": "..."}'

JavaScript (Node.js)

// Usando fetch nativo
const username = 'tu_usuario';
const password = 'tu_contraseña';
const credentials = Buffer.from(`${username}:${password}`).toString('base64');

const response = await fetch('[URL_API]/api/v2/oferta', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    uuid: '123e4567-e89b-12d3-a456-426614174000',
    // ... otros campos
  })
});

// Usando axios
const axios = require('axios');

const config = {
  auth: {
    username: 'tu_usuario',
    password: 'tu_contraseña'
  }
};

const response = await axios.post('[URL_API]/api/v2/oferta', data, config);

Python

import requests
from requests.auth import HTTPBasicAuth
import base64

# Opción 1: Usando HTTPBasicAuth
response = requests.post(
    '[URL_API]/api/v2/oferta',
    auth=HTTPBasicAuth('tu_usuario', 'tu_contraseña'),
    json={
        'uuid': '123e4567-e89b-12d3-a456-426614174000',
        # ... otros campos
    }
)

# Opción 2: Header manual
credentials = base64.b64encode(b'tu_usuario:tu_contraseña').decode('utf-8')
headers = {
    'Authorization': f'Basic {credentials}',
    'Content-Type': 'application/json'
}

response = requests.post(
    '[URL_API]/api/v2/oferta',
    headers=headers,
    json=data
)

PHP

<?php
// Opción 1: Usando cURL con CURLOPT_USERPWD
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => '[URL_API]/api/v2/oferta',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_USERPWD => 'tu_usuario:tu_contraseña',
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'uuid' => '123e4567-e89b-12d3-a456-426614174000',
        // ... otros campos
    ]),
]);

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

// Opción 2: Header manual
$credentials = base64_encode('tu_usuario:tu_contraseña');
$headers = [
    'Authorization: Basic ' . $credentials,
    'Content-Type: application/json',
];

$context = stream_context_create([
    'http' => [
        'method' => 'POST',
        'header' => implode("\r\n", $headers),
        'content' => json_encode($data),
    ],
]);

$response = file_get_contents('[URL_API]/api/v2/oferta', false, $context);
?>

Seguridad y Buenas Prácticas

🔒 Protección de Credenciales

• Nunca hardcodees las credenciales en tu código
• Usa variables de entorno para almacenar credenciales
• Rota las credenciales periódicamente

# Variables de entorno recomendadas
export TSALVA_API_USERNAME="tu_usuario"
export TSALVA_API_PASSWORD="tu_contraseña"
export TSALVA_API_BASE_URL="[URL_API]"

Validación de Certificados

Siempre verifica los certificados SSL en producción:

// ❌ NUNCA en producción
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

// ✅ Verificación adecuada
const https = require('https');
const agent = new https.Agent({
  rejectUnauthorized: true
});

Manejo de Errores de Autenticación

async function makeAuthenticatedRequest(data) {
  try {
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${credentials}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });

    if (response.status === 401) {
      throw new Error('Credenciales inválidas o expiradas');
    }

    if (!response.ok) {
      throw new Error(`Error HTTP: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Error de autenticación:', error.message);
    throw error;
  }
}

Códigos de Error de Autenticación

Código	Descripción	Solución
401	Credenciales inválidas	Verificar usuario y contraseña
403	Acceso denegado	Contactar administrador para permisos
429	Límite de rate excedido	Implementar retry con backoff

Prueba tu Autenticación

Usa este endpoint simple para verificar que tus credenciales funcionan:

curl -X GET "[URL_API]/api/v2/types" \
  --user "tu_usuario:tu_contraseña" \
  -H "Content-Type: application/json"

Una respuesta exitosa (200 Correcto) confirma que tu autenticación está configurada correctamente.

---

Importante

Las credenciales son sensibles. Manténlas seguras y no las compartas. En caso de compromiso, contacta inmediatamente al equipo de TSALVA para rotarlas.

Siguiente paso

Ahora que tienes configurada la autenticación, puedes explorar los códigos de respuesta de la API o volver a la documentación principal.