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.
1. Verifica tu clave
Sección titulada «1. Verifica tu clave»export FAKTURA_KEY="sk_test_..."curl https://faktura-test.cgallardo.me/v1/me -H "Authorization: Bearer $FAKTURA_KEY"use Illuminate\Support\Facades\Http;
// En el .env de tu proyecto: FAKTURA_KEY=sk_test_...
$response = Http::withToken(env('FAKTURA_KEY')) ->get('https://faktura-test.cgallardo.me/v1/me');
$data = $response->json();// Antes de ejecutar: export FAKTURA_KEY="sk_test_..."
const response = await fetch('https://faktura-test.cgallardo.me/v1/me', { headers: { Authorization: `Bearer ${process.env.FAKTURA_KEY}`, },});const data = await response.json();Debes ver tu RUC y "sunat_environment": "beta". Si recibes 401, revisa que copiaste la clave completa (Autenticación).
2. Mira tus series
Sección titulada «2. Mira tus series»curl https://faktura-test.cgallardo.me/v1/series -H "Authorization: Bearer $FAKTURA_KEY"use Illuminate\Support\Facades\Http;
$response = Http::withToken(env('FAKTURA_KEY')) ->get('https://faktura-test.cgallardo.me/v1/series');
$data = $response->json();const response = await fetch('https://faktura-test.cgallardo.me/v1/series', { headers: { Authorization: `Bearer ${process.env.FAKTURA_KEY}`, },});const data = await response.json();Anota el code de la serie con document_type: "03" (por ejemplo B001).
3. Emite la boleta
Sección titulada «3. Emite la boleta»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 } ] }'use Illuminate\Support\Facades\Http;
$response = Http::withToken(env('FAKTURA_KEY')) ->withHeaders(['Idempotency-Key' => 'mi-primera-boleta-001']) ->post('https://faktura-test.cgallardo.me/v1/receipts', [ 'series' => 'B001', 'customer' => ['doc_type' => 'NONE'], 'items' => [ [ 'description' => 'Café americano', 'quantity' => 2, 'unit_price' => 8.00, ], ], ]);
$data = $response->json();const response = await fetch('https://faktura-test.cgallardo.me/v1/receipts', { method: 'POST', headers: { Authorization: `Bearer ${process.env.FAKTURA_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'mi-primera-boleta-001', }, body: JSON.stringify({ series: 'B001', customer: { doc_type: 'NONE' }, items: [{ description: 'Café americano', quantity: 2, unit_price: 8.00 }], }),});const data = await response.json();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.
4. Espera la respuesta de SUNAT
Sección titulada «4. Espera la respuesta de SUNAT»curl https://faktura-test.cgallardo.me/v1/documents/<id> -H "Authorization: Bearer $FAKTURA_KEY"use Illuminate\Support\Facades\Http;
$response = Http::withToken(env('FAKTURA_KEY')) ->get('https://faktura-test.cgallardo.me/v1/documents/<id>');
$data = $response->json();const response = await fetch('https://faktura-test.cgallardo.me/v1/documents/<id>', { headers: { Authorization: `Bearer ${process.env.FAKTURA_KEY}`, },});const data = await response.json();En uno o dos segundos verás "status": "accepted" y "sunat": {"code": "0", "description": "La Boleta numero B001-1, ha sido aceptada", …}.
5. Descarga el XML y el CDR
Sección titulada «5. Descarga el XML y el CDR»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"use Illuminate\Support\Facades\Http;
$response = Http::withToken(env('FAKTURA_KEY')) ->get('https://faktura-test.cgallardo.me/v1/documents/<id>/xml');
// Guarda el archivo con el nombre que indica la API (Content-Disposition).preg_match('/filename="?([^";]+)/', $response->header('Content-Disposition'), $match);file_put_contents($match[1], $response->body());
$response2 = Http::withToken(env('FAKTURA_KEY')) ->get('https://faktura-test.cgallardo.me/v1/documents/<id>/cdr');
// Guarda el archivo con el nombre que indica la API (Content-Disposition).preg_match('/filename="?([^";]+)/', $response2->header('Content-Disposition'), $match2);file_put_contents($match2[1], $response2->body());import { writeFile } from 'node:fs/promises';
const response = await fetch('https://faktura-test.cgallardo.me/v1/documents/<id>/xml', { headers: { Authorization: `Bearer ${process.env.FAKTURA_KEY}`, },});
// Guarda el archivo con el nombre que indica la API (Content-Disposition).const [, name] = /filename="?([^";]+)/.exec(response.headers.get('content-disposition'));await writeFile(name, Buffer.from(await response.arrayBuffer()));
const response2 = await fetch('https://faktura-test.cgallardo.me/v1/documents/<id>/cdr', { headers: { Authorization: `Bearer ${process.env.FAKTURA_KEY}`, },});
// Guarda el archivo con el nombre que indica la API (Content-Disposition).const [, name2] = /filename="?([^";]+)/.exec(response2.headers.get('content-disposition'));await writeFile(name2, Buffer.from(await response2.arrayBuffer()));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 |
7. Pasa a producción
Sección titulada «7. Pasa a producción»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.