---
name: faktura-consultar-varios-ruc-a-la-vez
description: "Consultar varios RUC a la vez con la API de Faktura (facturación electrónica SUNAT, Perú). Hasta 1000 RUC por llamada; los repetidos se consultan una vez. Un RUC inválido no hace fallar la llamada: se informa en invalid. Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Consultar varios RUC a la vez — Faktura API

## Propósito

Le da a tu asistente el contexto para **consultar varios RUC a la vez** con la API de Faktura: Hasta 1000 RUC por llamada; los repetidos se consultan una vez. Un RUC inválido no hace fallar la llamada: se informa en invalid.

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

## Endpoint

| Ambiente | Petición |
| --- | --- |
| Pruebas | `POST https://faktura-test.cgallardo.me/v1/lookup/ruc` |
| Producción | `POST https://faktura.cgallardo.me/v1/lookup/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`.

## Ejemplo

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/lookup/ruc \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "rucs": ["20131312955", "10467793549", "20600000005", "123"] }'
```

## Respuesta `200 OK`

```json
{
  "items": [
    { "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" },
    { "ruc": "10467793549", "name": "PERSONA DE PRUEBA", "status": "ACTIVO", "address_condition": "HABIDO", "is_active_and_found": true, "ubigeo": "150101", "address": null }
  ],
  "not_found": ["20600000005"],
  "invalid": ["123"],
  "as_of": "2026-11-13"
}
```

`items` no sigue el orden de la petición; relaciónalos por `ruc`.

## Errores

| Estado | `reason` | Causa |
| --- | --- | --- |
| `422` | `ValidationFailed` | `rucs` falta, está vacío o tiene más de 1000 elementos. |
| `503` | `RucLookupUnavailable` | El servicio de consulta no está disponible temporalmente. |

Usa el mismo padrón que [Consultar un RUC](https://faktura-doc.cgallardo.me/endpoints/consultas/ruc/), con los mismos campos.

## 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
