---
name: faktura-consultar-un-ruc
description: "Consultar un RUC con la API de Faktura (facturación electrónica SUNAT, Perú). Sirve para autocompletar los datos del cliente en tu POS antes de emitir. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Consultar un RUC — Faktura API

## Propósito

Le da a tu asistente el contexto para **consultar un RUC** con la API de Faktura: Sirve para autocompletar los datos del cliente en tu POS antes de emitir.

Instalación en Claude Code: guarda este archivo como `.claude/skills/faktura-consultar-un-ruc/SKILL.md` en tu proyecto. Fuente: https://faktura-doc.cgallardo.me/endpoints/consultas/ruc/

## Endpoint

| Ambiente | Petición |
| --- | --- |
| Pruebas | `GET https://faktura-test.cgallardo.me/v1/lookup/ruc/{ruc}` |
| Producción | `GET https://faktura.cgallardo.me/v1/lookup/ruc/{ruc}` |

## Autenticación y cabeceras

- `Authorization: Bearer <api key>`. En pruebas, una clave `sk_test_` (SUNAT beta, sin valor tributario); en producción, la `sk_live_`. El ambiente lo decide la clave.
- `Content-Type: application/json` en las peticiones con cuerpo.
- `Idempotency-Key` (recomendada al emitir): repetir la petición con la misma clave y el mismo cuerpo devuelve el mismo comprobante, sin duplicarlo.
- Errores: JSON `{ "reason": "<código>", "details": [...] }`. `401` clave inválida o vencida, `403` alcance insuficiente, `422` datos inválidos, `429` límite de 120 peticiones por minuto (respeta `Retry-After`), `500` solo con `traceId`.

Consulta el **padrón reducido de RUC** publicado por SUNAT y actualizado diariamente en Faktura. No depende de los servicios en línea de SUNAT en el momento de la petición, por lo que responde en milisegundos incluso si SUNAT presenta intermitencias. `as_of` indica la fecha de publicación del padrón usado.

## Ejemplo

```bash
curl https://faktura-test.cgallardo.me/v1/lookup/ruc/20131312955 -H "Authorization: Bearer sk_test_..."
```

## Respuesta `200 OK`

```json
{
  "ruc": "20131312955",
  "name": "EMPRESA DE PRUEBA S.A.C.",
  "status": "ACTIVO",
  "address_condition": "HABIDO",
  "is_active_and_found": true,
  "ubigeo": "150122",
  "address": "AV. LARCO NRO. 123 INT. 402 URB. MIRAFLORES",
  "as_of": "2026-11-13"
}
```

| Campo | Descripción |
| --- | --- |
| `status` | Estado del contribuyente (`ACTIVO`, `BAJA DE OFICIO`, `SUSPENSION TEMPORAL`…). |
| `address_condition` | Condición del domicilio (`HABIDO`, `NO HALLADO`, `NO HABIDO`…). |
| `is_active_and_found` | `true` si está `ACTIVO` y `HABIDO`. Es informativo: la API no bloquea facturas a contribuyentes en otro estado. |
| `address`, `ubigeo` | Domicilio fiscal armado como lo muestra SUNAT; `null` si el padrón no lo trae. |
| `as_of` | Fecha (hora de Perú) en que SUNAT publicó el padrón consultado. |

## Errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `422` | `InvalidRuc` | No tiene 11 dígitos o el dígito verificador es incorrecto (se valida antes de consultar). |
| `404` | `RucNotFound` | No figura en el padrón. |
| `503` | `RucLookupUnavailable` | El servicio de consulta no está disponible temporalmente. Reintenta más tarde. |

Para muchos RUC a la vez, usa [Consultar varios RUC](https://faktura-doc.cgallardo.me/endpoints/consultas/ruc-lote/).

## Reglas generales de la API

- Montos en las respuestas como texto decimal (`"16.00"`); en las peticiones, número o texto.
- Fechas `YYYY-MM-DD` en hora de Perú (`America/Lima`); identificadores UUID.
- Un comprobante emitido responde `201` con `status: "pending"`: el número ya es tuyo. El resultado de SUNAT llega después (webhook o `GET /v1/documents/{id}`).
- Documentación completa: https://faktura-doc.cgallardo.me/ · Toda la API en una skill: https://faktura-doc.cgallardo.me/skills/faktura-api.md
