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 y actualizar datos básicos.

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`	Actualiza email/teléfono

Todas las respuestas usan el envelope estándar:

{ "data": { /* ... */ }, "timestamp": "2026-04-27T14:32:18Z", "errors": null }

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:

{
  "data": [
    {
      "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"
    }
  ],
  "timestamp": "2026-04-27T14:32:18Z",
  "errors": null
}

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": "[email protected]",
  "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

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

Contribuyentes

On this page