Autenticación
Cómo autenticarte con la API de Sifende — API key para integraciones ERP y Keycloak JWT para frontends personalizados.
La API de Sifende soporta dos modos de autenticación según el caso de uso:
API Key (integración ERP)
El método principal para integraciones máquina a máquina.
Formato del header
Authorization: Bearer {tu-api-key}El header es Authorization: Bearer, no X-Api-Key. El valor es tu API key completo incluyendo el prefijo sk_live_ o sk_test_.
Ejemplo
curl https://api.sifende.com.py/api/v1/documento-electronico/status/{cdc} \
-H "Authorization: Bearer sk_live_abc123xyz..."Obtener un API key
- Ingresá al panel en app.sifende.com.py
- Andá a Configuración → API Keys
- Hacé click en Nueva clave
- Guardá el valor — no se muestra de nuevo
Cada API key está vinculado a un solo contribuyente. Si tenés múltiples contribuyentes, necesitás una clave por cada uno.
Ciclo de vida del API key
| Estado | Descripción |
|---|---|
| Activo | Acepta requests |
| Rotado | La clave anterior dejó de funcionar, usa la nueva |
| Revocado | La clave fue eliminada permanentemente |
Para rotar una clave sin downtime: ver Rotar API Key.
Errores de autenticación
| Status | Descripción |
|---|---|
401 Unauthorized | API key ausente, inválido o revocado |
403 Forbidden | API key válido pero sin acceso al recurso solicitado |
La respuesta 401 del filtro de autenticación tiene este formato (no es RFC 9457):
{"error": "Invalid or expired API key"}Keycloak JWT (frontend personalizado)
Para aplicaciones que construyen una interfaz propia sobre Sifende usando autenticación OAuth 2.0 / OpenID Connect.
Si estás haciendo una integración ERP o un script backend, no necesitás esto. Usá API key.
Flujo
- El usuario se autentica vía Keycloak (OAuth 2.0)
- Recibe un JWT
access_token - Lo envía en cada request:
Authorization: Bearer {jwt}
Los endpoints de sesión usan el path /api/v1/contribuyentes/{id}/... y verifican que el usuario autenticado sea propietario del contribuyente.
Errores de autenticación (sesión)
{
"type": "https://sifende.com.py/probs/access-denied",
"title": "Acceso denegado",
"status": 403,
"detail": "No tenés acceso a este contribuyente"
}¿Cuál usar?
| Caso de uso | Auth recomendada |
|---|---|
| Integración ERP / script backend | API key |
| Frontend web personalizado | Keycloak JWT |
| Pruebas con curl / Postman | API key |
| App móvil | Keycloak JWT |