Certificado digital para firmar documentos en SIFEN

Subida del certificado digital PKCS12 y Código de Seguridad del Contribuyente (CSC) por sesión Keycloak.

Esta API utiliza autenticación Keycloak. Ver Autenticación para obtener un token JWT.

Cada contribuyente debe tener cargado un certificado digital válido — emitido por un prestador de servicios de certificación autorizado — junto con su Código de Seguridad del Contribuyente (CSC) asignado por la SET, para poder firmar y transmitir documentos electrónicos.

POST /api/v1/contribuyentes/:id/certificado

Sube el certificado PKCS12 y el CSC asociado al contribuyente.

Autenticación

Authorization: Bearer {keycloak-jwt} (requerido). El usuario debe ser propietario del contribuyente.

Content-Type

multipart/form-data

Form fields

Campo	Tipo	Requerido	Descripción
`file`	`file`	✅	Archivo PKCS12 (`.p12` o `.pfx`)
`password`	`string`	✅	Contraseña del certificado
`idCsc`	`string`	✅	ID del CSC (1, 2, etc. — el que tengas activo en e-Kuatia)
`csc`	`string`	✅	Valor del CSC asignado por SET
`ambiente`	`string`	✅	`TEST` o `PROD`

El archivo del certificado y la contraseña se almacenan encriptados en reposo. Nunca compartas la contraseña por canales inseguros (chat, email no cifrado, repos públicos). Si sospechás que se filtró, pedile a tu prestador de certificación que revoque el certificado, generá uno nuevo y volvé a subirlo.

Respuesta exitosa

Status: 200 OK

{
  "data": {
    "certificadoId": 87
  },
  "timestamp": "2026-04-27T14:32:18Z",
  "errors": null
}

Errores

Status	Tipo	Causa
`400`	`validation-error`	Faltan campos o el archivo no es PKCS12 válido
`400`	`validation-error`	Contraseña incorrecta — no se puede abrir el `.p12`
`403`	`access-denied`	El usuario no es propietario del contribuyente
`404`	`contribuyente-not-found`	El `:id` no existe

Ejemplo

curl -X POST https://api.sifende.com.py/api/v1/contribuyentes/12/certificado \
  -H "Authorization: Bearer $KEYCLOAK_JWT" \
  -F "file=@./certificado-80012345.p12" \
  -F "password=miClaveSecreta" \
  -F "idCsc=1" \
  -F "csc=ABCD1234EFGH5678IJKL9012MNOP3456" \
  -F "ambiente=TEST"

Solo hay un certificado activo a la vez. Subir uno nuevo reemplaza al anterior; si todavía era válido, se desactiva. Esta operación no es reversible: guardá una copia segura del archivo original.

Verificar el estado del certificado

No existe un endpoint GET /certificado. El estado del certificado se expone como el campo tieneCertificado (boolean) dentro del ContribuyenteDTO.

curl https://api.sifende.com.py/api/v1/contribuyentes/12/perfil \
  -H "Authorization: Bearer $KEYCLOAK_JWT" \
  | jq '.data.tieneCertificado'

Cambiar de ambiente (TEST → PROD)

Para pasar de pruebas a producción debés:

Solicitar el CSC de producción en Marangatu
Volver a llamar este endpoint con ambiente=PROD y los datos productivos

Ver la guía de producción para el checklist completo.

Certificado Digital