Autenticación

Métodos de Autenticación

La Tsalva API usa dos esquemas de autenticación:

• Autenticación básica HTTP (Basic Auth) — usada por prácticamente todos los endpoints (oferta, no-asignacion, asignacion, cancelacion, asignacion-directa, add-address, types, queries/history, queries/history-options).
• API key (x-apikey) — usada exclusivamente por PUT /api/v3/aceptacion.

Autenticación Básica HTTP

Todas las peticiones deben incluir el header Authorization con las credenciales codificadas en Base64.

Authorization: Basic <credenciales_base64>

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

Cómo se validan las credenciales

En el servidor, la contraseña se transforma con SHA-256 (hash hexadecimal) antes de compararse contra el registro del usuario de API. El usuario viaja en texto plano dentro del par Base64; la contraseña nunca se compara en claro contra la base de datos. Por eso siempre debes enviar tus credenciales exactamente como te fueron entregadas.

Esquema de Seguridad

securitySchemes:
  basicAuth:
    type: http
    scheme: basic
  apiKeyAuth:
    type: apiKey
    in: header
    name: x-apikey

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

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. El prefijo de la API es /api/v3.

cURL

# Opción 1: Usar --user (automáticamente codifica en Base64)
curl -X POST "[URL_API]/api/v3/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/v3/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/v3/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/v3/oferta', data, config);

Python

import requests
from requests.auth import HTTPBasicAuth
import base64

# Opción 1: Usando HTTPBasicAuth
response = requests.post(
    '[URL_API]/api/v3/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/v3/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/v3/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);
?>

Autenticación por API key (PUT /api/v3/aceptacion)

El endpoint PUT /api/v3/aceptacion no usa Basic Auth. En su lugar, la clave de acceso se envía en el header x-apikey:

x-apikey: <clave_de_acceso>

curl -X PUT "[URL_API]/api/v3/aceptacion" \
  -H "x-apikey: tu_clave_de_acceso" \
  -H "Content-Type: application/json" \
  -d '{ "uuid": "..." }'

Errores del validador de API key

Estas respuestas siguen el formato { status, msg, timestamp }:

Código	msg	Causa
401	No se ha brindado la clave de acceso.	Falta el header x-apikey
401	La clave de acceso no es correcta.	La clave no existe o es ambigua
401	La solicitud no puede ser completada, debido a que el estado del usuario de API es 'INACTIVO', comuniquese con el administrador del API.	Usuario de API inactivo
403	La solicitud no puede ser completada, debido a que no tiene permiso de acceso a este endpoint, comuniquese con el administrador del API.	La clave no tiene permiso para el endpoint
500	Error interno en la validación de la clave de acceso.	Error interno al validar

// Ejemplo de error de API key (401)
{
  "status": false,
  "msg": "La clave de acceso no es correcta.",
  "timestamp": "2026-07-07T12:00:00.000Z"
}

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]"

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 faltantes');
    }

    if (response.status === 403) {
      throw new Error('Usuario inactivo o sin permiso al endpoint');
    }

    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 (Basic Auth)

Los errores del validador de Basic Auth pasan por el manejador global de errores y devuelven el formato { error, message, errorId, timestamp }. El campo message contiene el texto exacto según el caso:

Código	message (exacto)	Causa
401	No se han brindado las credenciales de acceso.	No se envió el header o falta usuario/contraseña
401	Las credenciales de acceso no son correctas.	Usuario o contraseña inválidos
403	El estado del usuario de API es 'INACTIVO'.	Usuario de API deshabilitado
403	No tiene permiso de acceso a este endpoint.	El usuario no tiene habilitado este endpoint

// Ejemplo de error de credenciales (401)
{
  "error": true,
  "message": "Las credenciales de acceso no son correctas.",
  "errorId": "err_1720353600000_a1b2c3d4e",
  "timestamp": "2026-07-07T12:00:00.000Z"
}

// Ejemplo de usuario inactivo (403)
{
  "error": true,
  "message": "El estado del usuario de API es 'INACTIVO'.",
  "errorId": "err_1720353600000_f5g6h7i8j",
  "timestamp": "2026-07-07T12:00:00.000Z"
}

Prueba tu Autenticación

Usa este endpoint simple para verificar que tus credenciales funcionan:

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

Una respuesta exitosa (200) 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.