Autenticación

Los dos modos de autenticación en Sifende — API key para integraciones ERP y Keycloak JWT para frontends personalizados.

Sifende soporta dos modos de autenticación según el caso de uso. Para integraciones backend (ERP, e-commerce, scripts) usás API key. Para construir un frontend propio sobre la plataforma, usás Keycloak JWT.

API Key (integraciones máquina a máquina)

Es el modo principal para sistemas que emiten documentos automáticamente desde un backend.

Formato

Authorization: Bearer sk_live_abc123xyz...

El header es Authorization: Bearer, no X-Api-Key. El valor incluye el prefijo (sk_live_ para producción o sk_test_ para pruebas).

Ejemplo

curl -X POST https://api.sifende.com.py/api/v1/documento-electronico \
  -H "Authorization: Bearer sk_live_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{ "tipoDocumento": "FACTURA_ELECTRONICA", ... }'

Cuándo usar API key

Tu ERP emite facturas automáticamente desde el backend.
Un script periódico que sincroniza ventas y emite NCE.
Pruebas con curl, Postman o un cliente HTTP propio.
Integración mobile que delega la emisión a tu backend.

Ciclo de vida del API key

Operación	Descripción
Crear	Desde el panel: Configuración → API Keys → Nueva clave. La clave completa solo se muestra una vez.
Rotar	Generás una clave nueva sin invalidar la anterior; cuando tu sistema esté usando la nueva, eliminás la vieja.
Eliminar	Revoca la clave inmediatamente; cualquier request con esa clave pasa a recibir `401`.

Cada API key está vinculada a un solo contribuyente. Si tenés varios contribuyentes, generá una clave por cada uno.

Buenas prácticas de seguridad

Nunca hardcodees la clave en el código fuente. Usá variables de entorno o un secret manager (AWS Secrets Manager, Vault, GCP Secret Manager).
Nunca la expongas en código frontend, repos públicos o logs.
Rotala cada 90 días o por ahí. No hace falta más, pero tampoco menos.
Si sospechás que se filtró, revocala en el momento.
Usá sk_test_ en desarrollo y sk_live_ solo en producción, para no emitir documentos reales por error.

Keycloak JWT (frontend personalizado)

Para aplicaciones que construyen una UI propia sobre Sifende usando OAuth 2.0 / OpenID Connect.

Si tu integración es desde un backend, no necesitás esto. Usá API key.

Flujo

El usuario se autentica vía Keycloak (login con email + contraseña, o IDP social).

Recibe un JWT access_token con duración limitada.

El frontend lo envía en cada request: Authorization: Bearer {jwt}.

El backend de Sifende valida la firma del JWT y extrae el ID del usuario.

Endpoints de sesión

Los endpoints autenticados con JWT viven bajo /api/v1/contribuyentes/:id/... y verifican que el usuario autenticado sea propietario del contribuyente.

curl https://api.sifende.com.py/api/v1/contribuyentes/123/lotes \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

¿Cuál usar?

Caso de uso	Auth recomendada
Integración ERP	API key
Script backend de sincronización	API key
App mobile (vía backend propio)	API key
Frontend web propio	Keycloak JWT
Pruebas con `curl` o Postman	API key

Errores de autenticación

Status	Descripción
`401 Unauthorized`	Clave ausente, inválida o revocada
`403 Forbidden`	Clave válida pero sin acceso al recurso (por ejemplo, intentás operar sobre un contribuyente que no es tuyo)

Para más detalles, ver Referencia: Autenticación y la guía de API Keys.

On this page