API: consultar el contribuyente emisor

GET /api/v1/contribuyente — consulta los datos y la configuración de emisión del contribuyente autenticado por API key.

GET /api/v1/contribuyente

Devuelve los datos del contribuyente emisor tal como se usan al emitir en el ambiente de la API key, y si su configuración permite emitir.

Autenticación

Authorization: Bearer {api-key} — requerido

La API key determina el contribuyente y el ambiente consultados. El endpoint no acepta RUC ni ID de contribuyente en el path, query o body.

Ejemplo

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

Respuesta exitosa

Status: 200 OK

La respuesta es el objeto del contribuyente directamente, sin envelope.

{
  "ruc": "80012345",
  "digitoVerificador": "1",
  "razonSocial": "Ejemplo S.A.",
  "nombreFantasia": "Ejemplo",
  "tipoContribuyente": "PERSONA_JURIDICA",
  "ambiente": "PROD",
  "actividadesEconomicas": [
    { "codigo": "56101", "descripcion": "Restaurantes" }
  ],
  "direccion": "Av. Mcal. López",
  "numeroCasa": 1234,
  "departamento": { "codigo": 1, "descripcion": "CAPITAL" },
  "distrito": { "codigo": 1, "descripcion": "ASUNCION (DISTRITO)" },
  "ciudad": { "codigo": 1, "descripcion": "ASUNCION (DISTRITO)" },
  "telefono": "021123456",
  "email": "[email protected]",
  "timbrado": { "numero": 12345678, "fechaInicioVigencia": "2026-01-15" },
  "establecimientos": [
    {
      "numeroEstablecimiento": 1,
      "nombreSucursal": "Casa central",
      "activo": true,
      "puntosExpedicion": [ { "puntoExpedicion": 1, "activo": true } ]
    }
  ],
  "logoUrl": "https://storage.googleapis.com/sifende-assets/logos/112/3f0c8f5e-6b2a-4d7e-9a51-2c4e8b7d9f10.png",
  "estadoConfiguracion": {
    "certificadoConfigurado": true,
    "certificadoVence": "2027-03-01",
    "certificadoVigente": true,
    "cscConfigurado": true,
    "timbradoVigente": true,
    "direccionConfigurada": true,
    "actividadEconomicaConfigurada": true,
    "listoParaEmitir": true
  }
}

Campos

Todos los campos están siempre presentes; los marcados | null valen null cuando el dato no está cargado.

Campo	Tipo	Descripción
`ruc`	`string`	RUC sin dígito verificador
`digitoVerificador`	`string`	Dígito verificador del RUC
`razonSocial`	`string`	Razón social del emisor
`nombreFantasia`	`string \| null`	Nombre de fantasía
`tipoContribuyente`	`string`	`PERSONA_FISICA` o `PERSONA_JURIDICA`
`ambiente`	`string`	Ambiente de la API key: `DEV`, `PROD` o `SANDBOX`
`actividadesEconomicas`	`array`	Actividades económicas (`codigo`, `descripcion`) que se informan en el documento; vacío si no hay ninguna
`direccion`	`string \| null`	Dirección del emisor
`numeroCasa`	`integer \| null`	Número de casa
`departamento`	`object \| null`	`codigo` y `descripcion` SIFEN del departamento
`distrito`	`object \| null`	`codigo` y `descripcion` SIFEN del distrito; es opcional aunque haya dirección
`ciudad`	`object \| null`	`codigo` y `descripcion` SIFEN de la ciudad
`telefono`	`string`	Teléfono del emisor
`email`	`string`	Email del emisor
`timbrado`	`object \| null`	Timbrado del ambiente de la API key: `numero` y `fechaInicioVigencia`
`establecimientos`	`array`	Establecimientos con sus puntos de expedición
`logoUrl`	`string \| null`	URL pública y estable del logo cargado en Personalización
`estadoConfiguracion`	`object`	Estado de la configuración necesaria para emitir

El timbrado electrónico no tiene fecha de fin, así que no hay fechaFinVigencia.

numeroEstablecimiento y puntoExpedicion son los valores que enviás en la emisión. activo refleja el estado configurado en el panel; la emisión por API no lo valida.

Estado de la configuración

Campo	Tipo	Descripción
`certificadoConfigurado`	`boolean`	Hay un certificado digital activo
`certificadoVence`	`string (fecha) \| null`	Fin de vigencia del certificado, en hora de Paraguay; `null` sin certificado o si no se puede leer
`certificadoVigente`	`boolean`	El certificado es válido en este momento
`cscConfigurado`	`boolean`	Hay un CSC con su ID cargado para el ambiente de la API key
`timbradoVigente`	`boolean`	El timbrado del ambiente ya comenzó su vigencia, según la fecha de Paraguay
`direccionConfigurada`	`boolean`	Hay una dirección del emisor cargada
`actividadEconomicaConfigurada`	`boolean`	Hay al menos una actividad económica
`listoParaEmitir`	`boolean`	La emisión no va a fallar por configuración del emisor

listoParaEmitir reproduce los controles de configuración que la emisión hace antes de asignar número. Con false, POST /api/v1/documento-electronico responde, según el dato faltante, configuracion-incompleta, certificate-not-found, certificado-no-vigente o timbrado-no-vigente. No contempla el cupo del plan, que se consulta en Consultar Plan y Consumo.

En SANDBOX, Sifende genera el timbrado y el CSC de prueba en la primera emisión y no exige la vigencia del certificado, pero sí un certificado activo. Antes de esa emisión, timbrado puede ser null con timbradoVigente: true.

Errores

Status	Descripción
`401`	API key ausente, inválida o revocada
`403`	`plan-operation-not-allowed`: con una API key de PROD, el plan no incluye la API de integración
`500`	Error interno al consultar el contribuyente

Consultar Contribuyente