Skip to main content
POST
/
consulta
/
ruc
Query RUC
curl --request POST \
  --url https://api.example.com/consulta/ruc \
  --header 'Content-Type: application/json' \
  --header 'token: <token>' \
  --data '
{
  "ruc": "<string>"
}
'
{
  "codigoRespuesta": "<string>",
  "mensajeRespuesta": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "datosRUC": {
    "estado": "<string>",
    "nombre": "<string>",
    "RUCdv": "<string>",
    "numeroRUC": 123,
    "facturaElectronica": "<string>",
    "codigoEstado": "<string>"
  }
}

​
Overview

Query taxpayer information from SIFEN using a RUC number. This endpoint returns details about the taxpayer’s registration status, electronic invoice capabilities, and business information.

​
Authentication

​
token
string
required
Authentication token for API access
​
Emisor
string
Emisor identifier. If not provided, the default emisor will be used

​
Request

​
Request Body

​
ruc
string
required
The RUC number to query. Must be a valid Paraguayan RUC format (e.g., “80012345-7”)

​
Example Request

curl -X POST https://api.jsifen.com/consulta/ruc \
  -H "Content-Type: application/json" \
  -H "token: your-api-token" \
  -H "Emisor: 80012345-7" \
  -d '{
    "ruc": "80012345-7"
  }'

​
Response

​
Response Fields

​
codigoRespuesta
string
Response code from SIFEN indicating the query result
​
mensajeRespuesta
string
Descriptive message about the query result
​
statusCode
integer
HTTP status code of the response
​
error
string
Error message if the query failed (null on success)
​
datosRUC
object
Detailed taxpayer information (null if RUC not found)
​
estado
string
Current registration status (e.g., “ACTIVO”, “INACTIVO”)
​
nombre
string
Business or individual name registered with the RUC
​
RUCdv
string
Complete RUC with verification digit
​
numeroRUC
integer
RUC number without verification digit
​
facturaElectronica
string
Electronic invoice capability status (e.g., “SI”, “NO”)
​
codigoEstado
string
State code for the registration status

​
Success Response (200 OK)

{
  "codigoRespuesta": "0",
  "mensajeRespuesta": "Consulta exitosa",
  "statusCode": 200,
  "error": null,
  "datosRUC": {
    "estado": "ACTIVO",
    "nombre": "EMPRESA EJEMPLO S.A.",
    "RUCdv": "80012345-7",
    "numeroRUC": 80012345,
    "facturaElectronica": "SI",
    "codigoEstado": "01"
  }
}

​
RUC Not Found (200 OK)

{
  "codigoRespuesta": "404",
  "mensajeRespuesta": "RUC no encontrado",
  "statusCode": 200,
  "error": null,
  "datosRUC": null
}

​
Error Response (500)

Error interno: [error message]

​
RUC Format

The RUC must follow the Paraguayan format:
  • Base number: 8 digits
  • Verification digit: 1 digit
  • Format: XXXXXXXX-X (e.g., 80012345-7)

​
Use Cases

  • Validate Customer RUC: Verify that a customer’s RUC is valid and active before issuing an electronic invoice
  • Check Electronic Invoice Capability: Determine if a recipient can receive electronic invoices
  • Business Name Lookup: Retrieve the official registered name for a RUC
  • Registration Status Verification: Confirm that a taxpayer is currently active
  • Integration Validation: Validate RUC data during customer onboarding or transaction processing

​
Error Handling

The endpoint returns HTTP 500 with an error message if:
  • The RUC format is invalid
  • SIFEN service is unavailable
  • Authentication fails
  • Network or internal processing errors occur
Note that a valid response (200 OK) with datosRUC: null indicates the RUC was not found in the registry, which is different from an error condition.

Build docs developers (and LLMs) love

Get started for freeTalk to us