Contribuyentes

Endpoints de sesión para gestión de contribuyentes (entidades emisoras) via autenticación Keycloak JWT.

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

Estos endpoints permiten administrar los contribuyentes asociados al usuario autenticado: listar, consultar perfil, crear, actualizar datos básicos y consultar el padrón SIFEN por RUC.

Endpoints

Método	Path	Descripción
`GET`	`/api/v1/contribuyentes`	Lista todos los contribuyentes del usuario
`GET`	`/api/v1/contribuyentes/:id`	Detalle básico del contribuyente
`GET`	`/api/v1/contribuyentes/:id/perfil`	Perfil completo (incluye dirección y actividades)
`POST`	`/api/v1/contribuyentes/crear`	Crea un nuevo contribuyente
`PATCH`	`/api/v1/contribuyentes/:id/perfil`	Actualiza email/teléfono
`GET`	`/api/v1/contribuyentes/consulta/:ruc`	Consulta el padrón SIFEN por RUC

Todas las respuestas usan el envelope estándar:

{ "status": "success", "payload": { /* ... */ } }

GET /api/v1/contribuyentes

Lista los contribuyentes del usuario autenticado.

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

Respuesta 200 OK:

{
  "status": "success",
  "payload": [
    {
      "contribuyenteId": 12,
      "ruc": "80012345",
      "dv": "1",
      "razonSocial": "Comercial Guaraní S.A.",
      "tipoContribuyente": "JURIDICA",
      "estadoRuc": "ACTIVO",
      "esFacturadorElectronico": true,
      "tieneCertificado": true,
      "fechaCreacion": "2026-01-15T09:12:30",
      "fechaEdicion": "2026-04-02T11:45:00"
    }
  ]
}

GET /api/v1/contribuyentes/:id/perfil

Devuelve el perfil completo, incluyendo dirección y actividades económicas.

ContribuyenteDTO

Campo	Tipo	Descripción
`contribuyenteId`	`long`	ID interno
`ruc`	`string`	RUC sin DV
`dv`	`string`	Dígito verificador
`razonSocial`	`string`	Razón social registrada
`tipoContribuyente`	`string`	`JURIDICA` o `FISICA`
`email`	`string?`	Email de contacto
`telefono`	`string?`	Teléfono
`direccion`	`object`	Dirección fiscal (departamento, distrito, ciudad, etc.)
`actividadesEconomicas`	`array`	Lista de actividades CIIU asociadas
`estadoRuc`	`string`	Estado en SET (`ACTIVO`, `SUSPENDIDO`, etc.)
`esFacturadorElectronico`	`boolean`	Si está habilitado para emitir DEs
`tieneCertificado`	`boolean`	Si tiene certificado activo cargado
`fechaCreacion`	`datetime`	Fecha de alta en Sifende
`fechaEdicion`	`datetime`	Última modificación

POST /api/v1/contribuyentes/crear

Crea un nuevo contribuyente para el usuario autenticado.

CreateContribuyenteRequest

Campo	Tipo	Requerido	Descripción
`ruc`	`string` (≤20)	✅	RUC sin dígito verificador
`dv`	`string` (1)	✅	Dígito verificador
`razonSocial`	`string` (≤255)	✅	Razón social
`tipoContribuyente`	`string` (≤10)	—	`JURIDICA` o `FISICA`
`email`	`string` (≤100)	—	Email de contacto
`telefono`	`string` (≤20)	—	Teléfono
`estadoRuc`	`string` (≤10)	—	Estado SET
`esFacturadorElectronico`	`boolean`	—	Habilitado para DEs
`actividadesEconomicasCodigos`	`string[]`	—	Códigos CIIU (usar items con `esHoja=true`)
`direccion`	`object`	✅	Dirección fiscal (ver abajo)

Objeto `direccion`

Campo	Tipo	Requerido
`departamentoId`	`int`	✅
`distritoId`	`int`	—
`ciudadId`	`int`	✅
`direccion`	`string` (≤255)	✅
`numeroCasa`	`int`	✅ (`0` si no aplica)
`complementoDir1`	`string` (≤255)	—
`complementoDir2`	`string` (≤255)	—

Ejemplo

{
  "ruc": "80012345",
  "dv": "1",
  "razonSocial": "Comercial Guaraní S.A.",
  "tipoContribuyente": "JURIDICA",
  "email": "facturacion@guarani.com.py",
  "telefono": "021 555 1234",
  "estadoRuc": "ACTIVO",
  "esFacturadorElectronico": true,
  "actividadesEconomicasCodigos": ["4711"],
  "direccion": {
    "departamentoId": 1,
    "distritoId": 1,
    "ciudadId": 1,
    "direccion": "Avda. Mariscal López 1234",
    "numeroCasa": 1234,
    "complementoDir1": "Edificio Torre Sur",
    "complementoDir2": "Piso 4"
  }
}

Respuesta 201 Created con el ContribuyenteDTO recién creado.

PATCH /api/v1/contribuyentes/:id/perfil

Actualiza únicamente email y telefono. Otros campos (RUC, razón social, dirección) son inmutables desde este endpoint; para corregirlos contactá a soporte.

GET /api/v1/contribuyentes/consulta/:ruc

Consulta el padrón de SIFEN para un RUC específico. Útil para validar datos antes de crear el contribuyente o registrar un receptor.

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

La consulta golpea el web service de SIFEN, así que puede tardar algunos segundos. Cacheá el resultado del lado del cliente cuando puedas.

On this page