Consultar RUC

Este endpoint permite consultar información de un RUC (Registro Único de Contribuyente).

---

Entorno

URL Base: https://api.guarani.app

Endpoint

GET /consultas/ruc/{ruc}

Ejemplo de solicitud

curl -X GET "https://api.guarani.app/consultas/ruc/80012345" \
  -H "x-api-key: Bearer <access_token>" \
  -H "Accept: application/json" | jq

Nota: Reemplaza {ruc} por el RUC a consultar (con o sin dígito verificador) y <access_token> con un token JWT válido proporcionado por el equipo Guarani.
Importante:
Es imprescindible incluir un token de acceso válido en el encabezado x-api-key para autenticar y autorizar el uso de este endpoint. Sin este token, la solicitud será rechazada.

---

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
ruc	string	Sí	Número de RUC a consultar (puede incluir o no el dígito verificador separado por guión).

Encabezados de la Solicitud

Encabezado	Valor	Descripción
x-api-key	Bearer <access_token>	Token de acceso válido proporcionado por el equipo Guarani.
Accept	application/json	Indica que la respuesta debe devolverse en formato JSON.

Ejemplo de respuesta

Ejemplo de respuesta exitosa

{
  "success": true,
  "codigo": "200",
  "message": "Operación realizada correctamente.",
  "data": {
    "ruc": "80012345-7",
    "razon_social": "EMPRESA DE EJEMPLO S.A.",
    "estado": "ACTIVO"
  }
}

Ejemplo de respuesta de error

{
  "success": false,
  "codigo": "400",
  "mensaje": "Error al consultar el RUC.",
  "error": "RUC no válido o inexistente."
}

Descripción de Campos de Respuesta

Campos principales

Campo	Tipo	Descripción
ruc	string	Número de RUC con dígito verificador completo.
razon_social	string	Nombre o razón social del contribuyente.
estado	string	Estado del cliente en SIFEN.

Recursos adicionales

Para más información sobre posibles errores y cómo manejarlos, consulta errores