Empezar

Quickstart

Emite tu primera factura SUNAT en menos de 5 minutos. Sin tarjeta, sin homologar tu certificado, sin esperas.

Prerequisitos

  • Una cuenta gratis — regístrate aquí.
  • curl, Node 18+, Python 3.8+ o PHP 8.0+ — elige tu favorito.

No necesitas tu .pfx

El sandbox usa el certificado demo de SUNAT. Cuando estés listo para producción, subes el tuyo desde /app/credentials.

1. Tu API key de prueba

Al crear tu cuenta te entregamos una key con prefijo fwk_test_. Cópiala desde el dashboard (Settings → API keys) y exponla como variable de entorno:

Tu key sandbox
export FW_KEY=fwk_test_K7H9M3J2N4P5Q6R8S1T0U2V3W4X5Y6Z7

Solo se ve UNA vez

Por seguridad, el token completo solo aparece al crear la key. Si la pierdes, revócala y crea una nueva.

2. Emite una factura

Envía un POST a /v1/documents con un Idempotency-Key (cualquier UUID v4) para que reintentos no dupliquen el documento.

curl
curl -X POST https://api.fiscal-web.pe/v1/documents \
  -H "Authorization: Bearer $FW_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "invoice",
    "series": "F001",
    "receiver": {
      "id_kind": "ruc",
      "id_value": "20512333797",
      "name": "ACME SAC"
    },
    "items": [
      {
        "description": "Servicio profesional",
        "quantity": "1",
        "unit_price": "100.00"
      }
    ]
  }'
Node.js (@fiscal-web/node)
import { FiscalWeb } from "@fiscal-web/node";

const fw = new FiscalWeb({ apiKey: process.env.FW_KEY });

const doc = await fw.documents.create({
  kind: "invoice",
  series: "F001",
  receiver: {
    idKind: "ruc",
    idValue: "20512333797",
    name: "ACME SAC",
  },
  items: [
    { description: "Servicio profesional", quantity: "1", unitPrice: "100.00" },
  ],
});

console.log(doc.id, doc.state);
Python (fiscal-web)
import os
from fiscal_web import FiscalWeb

fw = FiscalWeb(api_key=os.environ["FW_KEY"])

doc = fw.documents.create(
    kind="invoice",
    series="F001",
    receiver={"id_kind": "ruc", "id_value": "20512333797", "name": "ACME SAC"},
    items=[
        {"description": "Servicio profesional", "quantity": "1", "unit_price": "100.00"}
    ],
)

print(doc.id, doc.state)
PHP (fiscal-web/php)
<?php
require 'vendor/autoload.php';

use FiscalWeb\Client;

$fw = new Client(['api_key' => getenv('FW_KEY')]);

$doc = $fw->documents->create([
    'kind' => 'invoice',
    'series' => 'F001',
    'receiver' => [
        'id_kind' => 'ruc',
        'id_value' => '20512333797',
        'name' => 'ACME SAC',
    ],
    'items' => [
        [
            'description' => 'Servicio profesional',
            'quantity' => '1',
            'unit_price' => '100.00',
        ],
    ],
]);

echo $doc->id . ' ' . $doc->state . PHP_EOL;

Si todo va bien, recibes una respuesta 201 con el documento:

201 Created
{
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "kind": "invoice",
  "series": "F001",
  "number": 1,
  "state": "pending",
  "mode": "test",
  "issued_at": "2026-05-15T18:32:00Z"
}

El estado pending significa que recibimos el documento, lo firmamos y lo enviamos a homologación SUNAT. Normalmente tarda 2-6 segundos.

3. Recibe el CDR por webhook

Cuando SUNAT responde con el CDR, te enviamos un POST firmado a la URL que registres en /app/webhooks. Aprende a verificar firmas en Verificar firmas.

Siguiente paso