---
name: faktura-preguntas-frecuentes
description: "Preguntas frecuentes con la API de Faktura (facturación electrónica SUNAT, Perú). Tres cosas, que se configuran una sola vez al darte de alta: el certificado digital de tu empresa, un usuario SOL secundario (nunca la clave SOL principal) y… Úsala cuando integres esta operación desde tu sistema."
---

# Skill: Preguntas frecuentes — Faktura API

## Propósito

Le da a tu asistente el contexto para **preguntas frecuentes** con la API de Faktura: Tres cosas, que se configuran una sola vez al darte de alta: el certificado digital de tu empresa, un usuario SOL secundario (nunca la clave SOL principal) y…

Instalación en Claude Code: guarda este archivo como `.claude/skills/faktura-preguntas-frecuentes/SKILL.md` en tu proyecto. Fuente: https://faktura-doc.cgallardo.me/preguntas-frecuentes/

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

## ¿Qué necesita mi empresa para emitir comprobantes reales?

Tres cosas, que se configuran una sola vez al darte de alta: el **certificado digital** de tu empresa, un **usuario SOL secundario** (nunca la clave SOL principal) y las **series** que vas a usar (`F001`, `B001`…). Con eso recibes tu clave `sk_live_`. Ver [Autenticación](https://faktura-doc.cgallardo.me/autenticacion/).

## ¿A nombre de quién salen las facturas y boletas?

Siempre a nombre de **tu empresa**: llevan tu RUC, tu razón social, tu nombre comercial, tu dirección, tu logo y la firma digital de tu propio certificado. Nunca salen a nombre de Faktura.

## ¿Desde qué lenguaje o sistema puedo conectarme?

Desde cualquier sistema capaz de hacer peticiones HTTPS con JSON: PHP (Laravel, Symfony…), Node.js, Python, C# (.NET), Java, Go, Ruby, sistemas POS de escritorio o web, ERPs y tiendas en línea. En cada endpoint del portal tienes ejemplos listos en `cURL`, `PHP (Laravel)` y `Node.js`, además de las [colecciones para Postman y Bruno](https://faktura-doc.cgallardo.me/colecciones/).

## ¿Puedo probar sin emitir comprobantes reales?

Sí. Con una clave `sk_test_` todo va a **SUNAT beta**: los comprobantes se firman y se envían igual, pero no tienen valor tributario y sus números no se cruzan con los de producción. Además, el entorno de pruebas es **privado por empresa**: ningún otro integrador puede ver los comprobantes que emitas con tu clave `sk_test_`. Ver [Introducción](https://faktura-doc.cgallardo.me/introduccion/#entornos-prueba-y-producción).

## ¿Qué cambia en mi código para pasar de pruebas a producción?

Solo dos valores de configuración (variables de entorno): la URL base (`https://faktura.cgallardo.me` en lugar de `https://faktura-test.cgallardo.me`) y la API key (`sk_live_…` en lugar de `sk_test_…`). Los endpoints, los campos del JSON y las respuestas son idénticos.

## ¿Cuánto tarda SUNAT en aceptar un comprobante?

La API responde al instante con `201` y `status: "pending"`, y el número ya es tuyo. El envío a SUNAT ocurre en segundo plano y suele resolverse en unos segundos. Ver [Estados y envío a SUNAT](https://faktura-doc.cgallardo.me/estados-y-envio/).

## ¿Cómo sé que SUNAT lo aceptó?

Registra un [webhook](https://faktura-doc.cgallardo.me/webhooks/) y Faktura te avisa (`document.accepted`, `document.rejected`…), o consulta [`GET /v1/documents/{id}`](https://faktura-doc.cgallardo.me/endpoints/comprobantes/ver/) hasta ver un estado final.

## ¿Qué pasa si SUNAT está caído?

Faktura reintenta sola, con espera creciente, hasta obtener respuesta. Tu sistema no tiene que reenviar nada: el comprobante sigue `pending` con su número ya asignado.

## Un comprobante quedó en `failed`, ¿qué hago?

`failed` significa que no llegó a SUNAT por una causa ajena a su contenido, como un usuario SOL incorrecto. Corrige la causa y [reenvíalo](https://faktura-doc.cgallardo.me/endpoints/comprobantes/reintentar/). Uno `rejected` no se reenvía: su contenido es inválido y corresponde emitir otro.

## ¿Puedo emitir una boleta sin pedir el DNI?

Sí, con `customer.doc_type: "NONE"`, si la boleta es en soles y no supera S/ 700.00. Por encima de ese monto, o en dólares, el cliente debe identificarse. Ver [Emitir una boleta](https://faktura-doc.cgallardo.me/endpoints/boletas/).

## ¿Puedo emitir con una fecha anterior?

Sí, con `issue_date`, hasta **3 días atrás** y nunca una fecha futura: sirve para ventas registradas sin conexión. Ver el [ejemplo de contingencia](https://faktura-doc.cgallardo.me/ejemplos/facturas/#con-fecha-de-emisión-anterior-contingencia).

## ¿Cómo anulo un comprobante?

Con [`POST /v1/documents/{id}/void`](https://faktura-doc.cgallardo.me/endpoints/anulacion/) si está dentro del plazo de anulación, o con una [nota de crédito](https://faktura-doc.cgallardo.me/endpoints/nota-de-credito/) si ya pasó o si el cliente devuelve solo una parte. Ver [cuál usar](https://faktura-doc.cgallardo.me/ejemplos/notas-y-anulaciones/#nota-de-crédito-o-anulación).

## ¿Cómo evito emitir dos veces la misma venta si se corta la conexión?

Envía siempre la cabecera `Idempotency-Key` con un valor único por venta. Si repites la petición con la misma clave y el mismo cuerpo, la API devuelve el mismo comprobante en lugar de crear otro. Ver [Idempotencia](https://faktura-doc.cgallardo.me/idempotencia/).

## ¿Los enlaces del PDF vencen?

Los enlaces públicos (`links.public_pdf` y `links.public_ticket`) se pueden compartir sin API key y vencen a los 7 días. El PDF con tu API key ([`GET /v1/documents/{id}/pdf`](https://faktura-doc.cgallardo.me/endpoints/pdf/)) no vence.

## ¿La consulta de RUC consulta a SUNAT en línea?

No. Consulta el padrón reducido de SUNAT actualizado diariamente en Faktura, por lo que responde en milisegundos incluso si SUNAT presenta intermitencias. `as_of` indica la fecha del padrón. Ver [Consultar un RUC](https://faktura-doc.cgallardo.me/endpoints/consultas/ruc/).

## Anexo: Entornos: prueba y producción (de «Introducción»)

El entorno ante SUNAT lo decide **la API key**: el mismo código de integración sirve para ambos.

| API key | Envía a | Uso |
| --- | --- | --- |
| `sk_test_…` | SUNAT **beta** | Desarrollo y pruebas. Los comprobantes no tienen validez tributaria. |
| `sk_live_…` | SUNAT **producción** | Comprobantes reales. Requiere que tu empresa tenga certificado digital y usuario SOL configurados. Una clave de **solo consultas** (RUC y DNI) no los necesita. |

El entorno de **pruebas** (`https://faktura-test.cgallardo.me`) recibe cada versión antes de que llegue a producción y **solo acepta claves `sk_test_`**: una `sk_live_` responde `401`. Los ejemplos de esta documentación usan la URL de pruebas y una clave `sk_test_`. Para pasar a producción cambias dos cosas: la URL base por `https://faktura.cgallardo.me` y la clave por la `sk_live_`.

Una clave puede tener **fecha de vencimiento** (los accesos de prueba la tienen): al vencer responde `401` igual que una revocada, y hay que pedir otra.

Las series y la numeración son independientes por entorno: emitir en prueba nunca consume números de producción. Un comprobante emitido con una clave de prueba no es visible con una clave de producción, y viceversa.

## Anexo: Con fecha de emisión anterior (contingencia) (de «Ejemplos de facturas»)

Si vendiste sin conexión, emite después con la fecha real de la venta en `issue_date`: hasta **3 días atrás**, nunca una fecha futura. En este ejemplo la venta fue el 11 de noviembre y se emite el 13; usa siempre una fecha dentro de ese plazo.

```bash
curl -X POST https://faktura-test.cgallardo.me/v1/invoices \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-pedido-9006" \
  -d '{
    "series": "F001",
    "issue_date": "2026-11-11",
    "customer": { "doc_type": "RUC", "doc_number": "20100070970", "name": "CLIENTE S.A.C." },
    "items": [ { "description": "Laptop", "quantity": 1, "unit_price": 118 } ]
  }'
```

```json
{
  "issue_date": "2026-11-11",
  "totals": {
    "taxed": "100.00", "exempt": "0.00", "unaffected": "0.00", "free": "0.00",
    "igv": "18.00", "icbper": "0.00", "total_taxes": "18.00", "discounts": "0.00", "charges": "0.00", "total": "118.00"
  }
}
```

## Anexo: ¿Nota de crédito o anulación? (de «Ejemplos de notas y anulaciones»)

| Situación | Qué usar |
| --- | --- |
| El comprobante tiene un error y no debió existir | [Anulación](https://faktura-doc.cgallardo.me/ejemplos/notas-y-anulaciones/#anular-una-boleta) (comunicación de baja o resumen diario), o nota de crédito motivo `01` |
| El cliente devuelve parte de lo comprado | Nota de crédito motivo `07` (devolución por ítem) |
| Das un descuento después de emitir | Nota de crédito motivo `04` (descuento global) |
| Cobras intereses o una penalidad | Nota de débito |

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