Ir al contenido

Guía: tu primera boleta en 10 minutos

Necesitas la API key de prueba (sk_test_…) que te entregó Faktura. Todo lo de esta guía va a SUNAT beta y no tiene validez tributaria.

Ventana de terminal
export FAKTURA_KEY="sk_test_..."
curl https://faktura-test.cgallardo.me/v1/me -H "Authorization: Bearer $FAKTURA_KEY"

Debes ver tu RUC y "sunat_environment": "beta". Si recibes 401, revisa que copiaste la clave completa (Autenticación).

Ventana de terminal
curl https://faktura-test.cgallardo.me/v1/series -H "Authorization: Bearer $FAKTURA_KEY"

Anota el code de la serie con document_type: "03" (por ejemplo B001).

Ventana de terminal
curl -X POST https://faktura-test.cgallardo.me/v1/receipts \
-H "Authorization: Bearer $FAKTURA_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: mi-primera-boleta-001" \
-d '{
"series": "B001",
"customer": { "doc_type": "NONE" },
"items": [ { "description": "Café americano", "quantity": 2, "unit_price": 8.00 } ]
}'

La respuesta 201 trae el número asignado (full_number), los totales calculados (S/ 16.00, de los cuales S/ 2.44 son IGV), el total en letras y status: "pending". Guarda el id.

Ventana de terminal
curl https://faktura-test.cgallardo.me/v1/documents/<id> -H "Authorization: Bearer $FAKTURA_KEY"

En uno o dos segundos verás "status": "accepted" y "sunat": {"code": "0", "description": "La Boleta numero B001-1, ha sido aceptada", …}.

Ventana de terminal
curl -OJ https://faktura-test.cgallardo.me/v1/documents/<id>/xml -H "Authorization: Bearer $FAKTURA_KEY"
curl -OJ https://faktura-test.cgallardo.me/v1/documents/<id>/cdr -H "Authorization: Bearer $FAKTURA_KEY"

6. Prueba los casos que tu POS va a encontrar

Sección titulada «6. Prueba los casos que tu POS va a encontrar»
Caso Qué enviar Qué esperar
Cliente con DNI "customer": {"doc_type": "DNI", "doc_number": "45678912", "name": "MARIA PEREZ"} 201
Venta de más de S/ 700 sin cliente "customer": {"doc_type": "NONE"} con un total mayor 422 ReceiptRequiresCustomerDocument
Bolsa plástica ítem con "icbper": true S/ 0.50 más por bolsa en totals.icbper
Producto exonerado ítem con "igv_type": "exonerado" IGV 0 en esa línea
Reintento por corte de red la misma petición con la misma Idempotency-Key 200 con el mismo comprobante

Cuando Faktura confirme que tu empresa tiene certificado digital y usuario SOL (GET /v1/me muestra has_certificate y has_sol_credentials en true) y tus series de producción, cambia la clave por la sk_live_…. El código no cambia.