API: consultar un RUC o cédula en el padrón de la SET

GET /api/v1/padron/:documento — buscá un RUC o cédula en el padrón de la SET y obtené razón social, estado y domicilio fiscal con los códigos geográficos de SIFEN.

GET /api/v1/padron/:documento

Busca un RUC o una cédula en el padrón de la SET y devuelve lo que la SET tiene registrado: nombre o razón social, estado, tipo de contribuyente y domicilio fiscal.

Sirve para dos cosas concretas:

Validar el RUC antes de facturar. Si el documento no está en el padrón, SIFEN va a rechazar la factura con el código 1306. Consultar acá te evita el rechazo.
Precargar el receptor. El domicilio viene con los códigos geográficos de SIFEN, así que podés completar el bloque receptor de un documento electrónico sin pedirle la dirección al cliente.

Es de sólo lectura: no emite nada, no consume tu plan de consumo y no altera el dato, que sale tal cual del padrón de la SET.

Autenticación

Authorization: Bearer {api-key} (requerido)

Path parameters

Parámetro	Tipo	Descripción
`documento`	`string`	RUC o cédula, con o sin puntos y con o sin dígito verificador

Sifende normaliza el valor antes de consultar: saca los puntos, saca el dígito verificador si viene y se queda con entre 5 y 12 dígitos. Estas tres formas consultan el mismo contribuyente:

GET /api/v1/padron/80002201
GET /api/v1/padron/80002201-7
GET /api/v1/padron/80.002.201-7

El campo numeroDocumento de la respuesta siempre vuelve normalizado, sin DV.

Respuesta exitosa

Status: 200 OK

La respuesta usa el envelope estándar { data, timestamp, errors }. Los nombres de campo y las enumeraciones son los mismos del receptor de un documento electrónico.

{
  "data": {
    "numeroDocumento": "80002201",
    "tipoContribuyente": "CONTRIBUYENTE",
    "tipoDocumento": null,
    "tipoContribuyenteReceptor": "PERSONA_JURIDICA",
    "digitoVerificador": "7",
    "nombreRazonSocial": "BANCO ITAU PARAGUAY S.A",
    "nombreComercial": null,
    "email": "contacto@ejemplo.com.py",
    "estado": "ACTIVO",
    "estadoRuc": "ACT",
    "tipoSociedad": {
      "codigo": "SOCIEDAD_ANONIMA",
      "descripcion": "SOCIEDAD ANONIMA"
    },
    "esPersonaJuridica": true,
    "esEntidadPublica": false,
    "exportador": false,
    "domicilio": {
      "departamento": { "codigo": 1, "nombre": "CAPITAL" },
      "distrito": { "codigo": 1, "nombre": "ASUNCION (DISTRITO)" },
      "localidad": { "codigo": 1, "nombre": "ASUNCION (DISTRITO)" },
      "barrio": null,
      "direccion": "SANTA TERESA ENTRE HERMINIO MALDONADO Y AVENIDA AVIADORES DEL CHACO",
      "numeroPuerta": null,
      "referencias": null
    },
    "consultadoEn": "2026-09-08T14:30:12Z"
  },
  "timestamp": "2026-09-08T14:30:12Z",
  "errors": null
}

Campos

Campo	Tipo	Descripción
`numeroDocumento`	`string`	RUC base o número de cédula, normalizado: sólo dígitos, sin DV
`tipoContribuyente`	`enum`	`CONTRIBUYENTE` si el documento está inscripto como tal; `NO_CONTRIBUYENTE` si sólo figura como ciudadano
`tipoDocumento`	`enum \| null`	`CEDULA_PARAGUAYA` para un no contribuyente; `null` para un contribuyente, que se identifica por RUC
`tipoContribuyenteReceptor`	`enum \| null`	`PERSONA_FISICA` o `PERSONA_JURIDICA`. `null` para un no contribuyente
`digitoVerificador`	`string \| null`	Dígito verificador del RUC. `null` para una cédula que no es RUC
`nombreRazonSocial`	`string`	Razón social o nombre completo, tal cual figura en la SET
`nombreComercial`	`string \| null`	Nombre de fantasía, si está declarado
`email`	`string \| null`	Correo registrado ante la SET, si existe
`estado`	`string \| null`	Estado del contribuyente tal como lo informa la SET, por ejemplo `ACTIVO`
`estadoRuc`	`enum \| null`	Código SET del estado: `ACT`, `SUS`, `SAD`, `BLQ`, `CAN` o `CDE`. Es el mismo valor que usa el contribuyente en Sifende
`tipoSociedad`	`object \| null`	Tipo societario: `codigo` y `descripcion`
`esPersonaJuridica`	`boolean`	Atajo de `tipoContribuyenteReceptor = PERSONA_JURIDICA`
`esEntidadPublica`	`boolean`	`true` para organismos y entidades del Estado
`exportador`	`boolean`	`true` si está registrado como exportador
`domicilio`	`object \| null`	Domicilio fiscal con los códigos geográficos de SIFEN, si el padrón lo tiene
`consultadoEn`	`string (RFC 3339)`	Momento en que Sifende obtuvo el dato del padrón

Objeto `domicilio`

Campo	Tipo	Descripción
`departamento`	`object \| null`	`codigo` y `nombre`, con el nombre oficial del catálogo de departamentos
`distrito`	`object \| null`	`codigo` y `nombre`
`localidad`	`object \| null`	`codigo` y `nombre`
`barrio`	`string \| null`	Barrio declarado
`direccion`	`string \| null`	Calle y referencia de la dirección fiscal
`numeroPuerta`	`string \| null`	Número de puerta
`referencias`	`string \| null`	Referencias adicionales del domicilio

Los codigo de departamento, distrito y localidad son los códigos oficiales de SIFEN, los mismos que se usan en las direcciones del documento electrónico.

Del padrón al receptor

Los campos de identidad se copian al bloque receptor con el mismo nombre y el mismo valor, sin traducción. Sólo el domicilio cambia de forma:

Campo del padrón	Campo del receptor
`tipoContribuyente`	`tipoContribuyente`
`tipoContribuyenteReceptor`	`tipoContribuyenteReceptor`
`tipoDocumento`	`tipoDocumento` (sólo para `NO_CONTRIBUYENTE`)
`numeroDocumento`	`numeroDocumento`
`digitoVerificador`	`digitoVerificador`
`nombreRazonSocial`	`nombreRazonSocial`
`email`	`email`
`domicilio.direccion`	`direccion`
`domicilio.departamento.nombre`	`departamento`
`domicilio.distrito.codigo`	`codigoDistrito`
`domicilio.localidad.nombre`	`ciudad`

{
  "receptor": {
    "tipoContribuyente": "CONTRIBUYENTE",
    "tipoOperacion": "B2B",
    "tipoContribuyenteReceptor": "PERSONA_JURIDICA",
    "numeroDocumento": "80002201",
    "digitoVerificador": "7",
    "nombreRazonSocial": "BANCO ITAU PARAGUAY S.A",
    "direccion": "SANTA TERESA ENTRE HERMINIO MALDONADO Y AVENIDA AVIADORES DEL CHACO",
    "departamento": "CAPITAL",
    "codigoDistrito": 1,
    "ciudad": "ASUNCION (DISTRITO)",
    "email": "contacto@ejemplo.com.py"
  }
}

El padrón es la fuente de la verdad para el nombre y el estado, no para lo que tu cliente quiere ver impreso. Si el cliente te pide otra razón social o su nombre de fantasía, mandá el valor que corresponda al negocio; SIFEN valida el RUC y el DV, no el texto exacto de nombreRazonSocial.

Datos parciales

domicilio y email pueden venir en null cuando el padrón no tiene el dato o la consulta se resolvió con datos parciales.

Si tu integración arma el receptor con el domicilio, verificá que no sea null antes de usarlo, o reintentá la consulta más tarde.

Cédula que no es contribuyente

Cuando el documento figura como ciudadano pero no como contribuyente, la respuesta trae la identidad y nada más, ya con los valores que espera un receptor B2C:

{
  "data": {
    "numeroDocumento": "1234567",
    "tipoContribuyente": "NO_CONTRIBUYENTE",
    "tipoDocumento": "CEDULA_PARAGUAYA",
    "tipoContribuyenteReceptor": null,
    "digitoVerificador": null,
    "nombreRazonSocial": "JUAN PEREZ GONZALEZ",
    "nombreComercial": null,
    "email": null,
    "estado": null,
    "estadoRuc": null,
    "tipoSociedad": null,
    "esPersonaJuridica": false,
    "esEntidadPublica": false,
    "exportador": false,
    "domicilio": null,
    "consultadoEn": "2026-09-08T14:31:47Z"
  },
  "timestamp": "2026-09-08T14:31:47Z",
  "errors": null
}

Ese caso se factura como B2C identificado: tipoContribuyente: "NO_CONTRIBUYENTE" con tipoDocumento: "CEDULA_PARAGUAYA", tal cual vienen. Ver Receptor B2B y B2C.

tipoContribuyente: "NO_CONTRIBUYENTE" no es un error: significa que la persona existe pero no está inscripta en el IVA. No le emitas una factura B2B, porque SIFEN la rechaza.

Caché y límites

consultadoEn indica cuándo se obtuvo el dato. El resultado puede reflejar una consulta anterior; no implica una actualización con cada llamada.

Límite	Valor
Por API key	60 consultas por minuto
Por contribuyente	120 consultas por minuto

Al superarlos, la API responde 429 rate-limit-exceeded con el header Retry-After en segundos. Esperá ese tiempo antes de reintentar en lugar de reintentar en loop.

Errores

Status	Tipo	Descripción
`400`	`invalid-format`	El documento no queda entre 5 y 12 dígitos después de sacar puntos y DV
`401`	—	API key ausente, inválida o revocada
`404`	`ruc-not-found`	El documento no está en el padrón
`429`	`rate-limit-exceeded`	Se superó el límite por minuto. Incluye `Retry-After` en segundos
`502`	`padron-no-disponible`	El padrón no respondió. Reintentá en unos minutos

{
  "type": "https://sifende.com.py/docs/solucion-problemas/ruc-not-found",
  "title": "RUC no encontrado",
  "status": 404,
  "detail": "El documento 80099999 no figura en el padrón de la SET",
  "instance": "/api/v1/padron/80099999"
}

El 404 es final: un documento que no figura en el padrón responde 404 en todas las consultas, no 502.

Próximos pasos

Receptor B2B y B2C para armar el bloque con los datos que trajiste del padrón.
Modelo Receptor para el schema completo de campos.
Geografía si necesitás poblar selectores de departamento, distrito y ciudad a mano.
Rechazos SIFEN para los códigos 1306 y 1309, los rechazos que esta consulta previene.

Consultar el Padrón