Timbrado

Endpoints de sesión para gestión del timbrado electrónico (autorización SET) por contribuyente.

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

El timbrado es la autorización emitida por SET (registrada en MARANGATÚ) que habilita al contribuyente a emitir documentos electrónicos. Cada contribuyente tiene un único timbrado activo a la vez.

Endpoints

Método	Path	Descripción
`GET`	`/api/v1/contribuyentes/:id/timbrado`	Obtener el timbrado actual
`POST`	`/api/v1/contribuyentes/:id/timbrado`	Crear el timbrado
`PUT`	`/api/v1/contribuyentes/:id/timbrado`	Actualizar el timbrado
`DELETE`	`/api/v1/contribuyentes/:id/timbrado`	Eliminar el timbrado

El número de timbrado, fechaInicio y fechaFin deben coincidir exactamente con lo que SET registró en MARANGATÚ. Datos incorrectos producen el rechazo SIFEN 1108 (Timbrado no válido) en cada documento emitido.

CreateTimbradoRequest / UpdateTimbradoRequest

Campo	Tipo	Requerido (POST)	Descripción
`numeroTimbrado`	`int` (8 dígitos, positivo)	✅	Número de timbrado asignado por SET
`fechaInicio`	`date` (`YYYY-MM-DD`)	✅	Fecha de inicio de vigencia
`fechaFin`	`date` (`YYYY-MM-DD`)	✅	Fecha de expiración del timbrado

En PUT todos los campos son opcionales: sólo se actualizan los que vengan en el body.

fechaFin es la fecha de expiración del timbrado. No se pueden emitir documentos electrónicos con fecha posterior a fechaFin. Renová el timbrado en SET antes de que expire y actualizalo aquí.

TimbradoDTO

Campo	Tipo	Descripción
`timbradoId`	`long`	ID interno
`contribuyenteId`	`long`	Contribuyente al que pertenece
`numeroTimbrado`	`int`	Número de timbrado
`fechaInicio`	`date`	Inicio de vigencia
`fechaFin`	`date`	Fin de vigencia
`fechaCreacion`	`datetime`	Alta en Sifende
`fechaEdicion`	`datetime`	Última modificación

Ejemplos

Crear timbrado

curl -X POST https://api.sifende.com.py/api/v1/contribuyentes/12/timbrado \
  -H "Authorization: Bearer $KEYCLOAK_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "numeroTimbrado": 12345678,
    "fechaInicio": "2026-01-01",
    "fechaFin": "2027-12-31"
  }'

Respuesta 201 Created:

{
  "status": "success",
  "payload": {
    "timbradoId": 34,
    "contribuyenteId": 12,
    "numeroTimbrado": 12345678,
    "fechaInicio": "2026-01-01",
    "fechaFin": "2027-12-31",
    "fechaCreacion": "2026-04-15T10:30:00",
    "fechaEdicion": "2026-04-15T10:30:00"
  }
}

Consultar timbrado actual

curl https://api.sifende.com.py/api/v1/contribuyentes/12/timbrado \
  -H "Authorization: Bearer $KEYCLOAK_JWT"

Eliminar timbrado

curl -X DELETE https://api.sifende.com.py/api/v1/contribuyentes/12/timbrado \
  -H "Authorization: Bearer $KEYCLOAK_JWT"

Respuesta: 204 No Content.

Errores

Status	Tipo	Causa
`400`	`validation-error`	Número fuera de rango, fecha inválida, `fechaFin` < `fechaInicio`
`404`	`timbrado-not-found`	El contribuyente no tiene timbrado cargado
`409`	`validation-error`	Ya existe un timbrado activo (usá `PUT` o `DELETE` primero)

On this page