Guía rápida — Primera factura

Cómo emitir tu primera factura electrónica con Facturalo: crea tu cuenta en la consola, registra tu empresa, copia el token Demo y envía el JSON a /documentos/enviar.

De cero a tu primera factura ACEPTADA en el entorno Demo, sin certificado ni Clave SOL. Todo lo de la consola se hace en console.facturalo.pe.

1. Crea tu cuenta

Entra a console.facturalo.pe/register, escribe tu correo, ingresa el código que te llega y completa tu DNI, nombres y contraseña.

2. Registra tu empresa

En Empresas → Nueva empresa escribe el RUC: la razón social, la dirección y el ubigeo se completan solos desde SUNAT. Revisa los datos y guarda.

Demo listo desde el inicio

La empresa queda lista para emitir en Demo: Facturalo firma con un certificado de pruebas y usa el usuario SOL de pruebas de SUNAT. Los comprobantes Demo no tienen validez tributaria.

3. Copia el token Demo

En la fila de tu empresa abre el menú ⋯ → Tokens y copia el token de Demo (sk_test_…). Ese token decide el entorno: las facturas y boletas van a SUNAT Beta; las guías de remisión se validan en el entorno de pruebas de Facturalo (XSD y reglas XSL oficiales de SUNAT; SUNAT no ofrece beta pública GRE). Guárdalo en una variable de entorno de tu backend, nunca en el frontend.

4. Envía tu primera factura

Con este JSON ya tienes una factura válida. precioUnitario incluye IGV y, con tipoIgv: "10" (gravado), Facturalo calcula el valor unitario, el IGV y los totales.

factura.jsonjson

{
  "documento": {
    "sunatTransaccion": "0101",
    "tipoComprobante": "01",
    "serie": "F001",
    "correlativo": "1",
    "fechaEmision": "2026-10-30",
    "moneda": "PEN",
    "formaPago": "CONTADO",
    "cliente": {
      "tipoDocumento": "6",
      "numeroDocumento": "20000000001",
      "denominacion": "EMPRESA S.A.C.",
      "direccion": "AV. LIMA 123 - LIMA - LIMA - LIMA"
    },
    "items": [
      {
        "unidadMedida": "NIU",
        "descripcion": "SERVICIO DE CONSULTORÍA",
        "cantidad": 1,
        "precioUnitario": 118,
        "tipoIgv": "10"
      }
    ]
  }
}

POST /documentos/enviarbash

-primary-dark)">curl -X POST https://api.facturalo.pe/api/v3/documentos/enviar \
  -H "Authorization: sk_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: primera-factura-demo" \
  -d @factura.json

El token va sin Bearer. Si reenvías el mismo POST (misma serie/correlativo o el mismo Idempotency-Key), Facturalo no duplica el comprobante: ver Idempotencia. Todos los campos y los demás casos (exonerada, detracción, en dólares, notas…) están en Factura gravada y las páginas siguientes de la referencia.

Si tu sistema está en Node.js o PHP, puedes usar el SDK oficial en lugar de armar la petición HTTP:

Instalar el SDKbash

npm install @facturalo-pe/node
# o en PHP
composer require facturalo-pe/facturalo-php

Node.jsjs

import { readFileSync } from "node:fs";
import { FacturaloClient } from "@facturalo-pe/node";

const factura = JSON.parse(readFileSync("factura.json", "utf8"));
const facturalo = new FacturaloClient({ token: process.env.FACTURALO_TOKEN });

const envio = await facturalo.documentos.enviar(factura.documento, {
  idempotencyKey: "primera-factura-demo",
});
console.log(envio.estado, envio.enlaces.pdf);

PHPphp

<?php
require 'vendor/autoload.php';

use Facturalo\FacturaloClient;

$factura = json_decode(file_get_contents('factura.json'), true);
$facturalo = new FacturaloClient(getenv('FACTURALO_TOKEN'));

$envio = $facturalo->documentos->enviar($factura['documento'], idempotencyKey: 'primera-factura-demo');
echo $envio['estado'], PHP_EOL;

Cada página de la referencia muestra el ejemplo con el SDK en las pestañas Node y PHP. Código fuente: facturalo-node y facturalo-php.

5. Revisa la respuesta

La respuesta llega en segundos con el resultado de SUNAT. Si data.estado es ACEPTADA, ya tienes el PDF, el XML y el CDR en enlaces. Si es RECHAZADA, el motivo está en sunat.codigo y sunat.mensaje.

200 Aceptadajson

{
  "success": true,
  "message": "La Factura numero F001-00000001 ha sido aceptada",
  "data": {
    "estado": "ACEPTADA",
    "entorno": "demo",
    "documento": {
      "id": "83ad82a0-680e-11f1-8e35-2d93ac0f2c84",
      "estado": "ACEPTADA",
      "serie": "F001",
      "correlativo": "00000001",
      "tipo": "FACTURA"
    },
    "sunat": {
      "estado": "ACEPTADA",
      "codigo": "0",
      "mensaje": "La Factura numero F001-00000001 ha sido aceptada",
      "notas": []
    },
    "enlaces": {
      "pdf": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.pdf",
      "pdfTicket": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.ticket.pdf",
      "xml": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.xml",
      "cdr": "https://api.facturalo.pe/api/v3/documentos/83ad82a0-680e-11f1-8e35-2d93ac0f2c84.cdr"
    },
    "hash": "xvQpVbLssRc8FlD8/0LuSYeIPo8=",
    "cadenaQr": "20601476551 | 01 | F001 | 00000001 | 18.00 | 118.00 | 30/10/2026 | 6 | 20000000001 | xvQpVbLssRc8FlD8/0LuSYeIPo8= |"
  }
}

La respuesta solo identifica el comprobante. El detalle completo (cliente, totales, ítems) lo obtienes con GET /documentos/{id}.

6. Pasa a producción

Cuando todo funcione en Demo, sigue el Onboarding Live de la consola (tres pasos):

Activar firma (Alta PSE): desde Empresa en la consola, con la Clave SOL primaria de la empresa damos de alta a nuestro PSE en SUNAT. Desde ahí firmamos y enviamos tus comprobantes: no necesitas certificado digital ni usuario secundario SOL.
Plan: elige un plan activo en Planes. Sin plan no se puede emitir en Live.
API SUNAT (opcional): client_id y client_secret, solo si emites guías de remisión o usas SIRE. Se validan con SUNAT al guardarlas.
Token Live: en ⋯ → Tokens copia el token de Live (sk_live_…) y úsalo en lugar del de Demo. El JSON es el mismo.

¿Prefieres no esperar la respuesta?

Envía "webhook": true y configura tu URL en ⋯ → Webhooks: la API responde 202 EN_PROCESO al instante y el resultado de SUNAT llega a tu webhook como documento.sunat.respuesta.