FracTuyo

Library for generating electronic invoices with JavaScript (compatible with TypeScript). This library follows 🇵🇪 Sunat's regulations on invoices.

When items are added, receipt amounts are calculated.

It doesn't contain anything visual so it doesn't generate a PDF file for printing either.

This library is similar to Greenter (PHP), but although Sunat has not standardized all its channels to reach its servers, Fractuyo uses the same interface for everything.

What do you need?

To generate a document you only need the data.

To sign the document you will need a digital certificate and the private key.

What documents can you generate?

Invoice

This is the main document. Two types can be represented: factura and boleta de venta.

Note

Two types can be generated: credit note and debit note.

Despatch

For carrier or remitter.

Usage

// needed classes
import { Invoice, Person, Taxpayer, Identification } from "fractuyo";

const customer = new Person();
customer.setName("George A. Garro");
customer.setIdentification(new Identification(6, "10000000001"));

const taxpayer = new Taxpayer();
taxpayer.setIdentification(new Identification(6, "20000000001"));
taxpayer.setName("Monsters Inc.");
 // SOAP credentials
taxpayer.setSolUser("usuarioSOL");
taxpayer.setSolPass("claveSOL");
 // REST credentials
taxpayer.setSolId("id");
taxpayer.setSolSecret("secret");
 // for XML signature using digital certificate
taxpayer.setCert("rsaCertContent");
taxpayer.setKey("rsaKeyContent");

const receipt = new Invoice(taxpayer, customer);
receipt.setCurrencyId("USD");
receipt.setTypeCode(1); // factura
receipt.setSerie("F000");
receipt.setNumeration(19970601);

const product = new Item("Description");
product.setIgvPercentage(18);
product.setExemptionReasonCode(10);
product.setQuantity(1);
product.setUnitValue(100.00);

product.calcMounts();
// after applying previous calculations.
receipt.addItem(product);

receipt.toXml();
// maybe pass window.crypto
receipt.finalize(cryptoLibrary); // sign

// you must save this XML
console.log(receipt.toString());

// send signed XML inside ZIP
const zipStream = await receipt.createZip();
const serverZipStream = await receipt.declare(zipStream);

// also for despatch use receipt.handleTicket()
// save server answer

const [ serverCode, serverDescription ] = await receipt.handleProof(serverZipStream);

Endpoints

You may not need to use the methods of the Endpoint class, as the classes that handle the documents use them internally.

The library includes the HTTP endpoints for SUNAT, both for testing and for production use.

import { Endpoint } from "fractuyo";

Deployment or test

The generation of documents up to the inclusion of the electronic signature is identical in both deployment mode and test mode.

By default, the test endpoints are assigned, and you can switch to the production endpoint by using the following code (in any place, just once before sending out because is static):

const receipt = new Invoice(taxpayer, customer);
Endpoint.setDeploymentMode(true); // false for test
receipt.declare(zipStream);

Change endpoints

If the endpoints are not what you need, then you can assign your own endpoints for both modes individually.

let deploymentMode = true; // or false for test
Endpoint.setUrl(Endpoint.INDEX_INVOICE, "new URL", deploymentMode);
Endpoint.setUrl(Endpoint.INDEX_RETENTION, "new URL", deploymentMode);
// and used for despatchs
Endpoint.setUrl(Endpoint.INDEX_TOKEN, "new URL", deploymentMode);
Endpoint.setUrl(Endpoint.INDEX_SEND, "new URL", deploymentMode);
Endpoint.setUrl(Endpoint.INDEX_STATUS, "new URL", deploymentMode);

View documentation or source code to check URL structure.

Ready-to-use software

For businesses and developers in Peru seeking a complete billing solution or professional technical advice, we recommend Efactubit. This Windows desktop application is powered by this library and offers:

• Simple and intuitive forms: Forget about complex XML structures; issue your documents in seconds with a user-friendly interface.
• Personalized PDF generation: Distinguish your business with unique, custom-designed PDF templates that look professional and premium, avoiding the generic look of standard billing systems.
• Expert support & advice: Get guidance on library integration and Peruvian electronic billing requirements.

Learn more, download it, or contact support for Efactubit or Fractuyo at efactubit.efectibit.com.

Los mensajes pueden estar en español para mayor comodidad o en inglés, así como el software.

Installation

# Using npm
npm install fractuyo

Test locally

Clone the project.

  git clone https://github.com/terexor/fractuyo.git

Go to the project directory.

  cd fractuyo

Install dependencies.

  npm install

Start test of invoice with AVA.

  npm run test:invoice

In addition to invoice are available credit, debit and despatch.

Validating against XSD schemas

Follow these steps to run XSD validation tests:

1. Add XSD files Place the required .xsd files inside the folder:

tests/xsd/2.1/

The official XSD files provided by Sunat or OASIS are usually organized in the following subfolders, which must be preserved:

tests/xsd/2.1/common/
tests/xsd/2.1/maindoc/

2. Enable validation tests Test functions related to XSD validation — such as those under "signing note" — contain a return statement that skips execution. To actually run those tests, remove the return line inside that test function.

FAQ

Does it generate documents with all the necessary XML tags?

This library has not been tested yet with all possible cases and there may be some missing tags so we ask you to help us with that by reporting or fixing it.

Why is everything written in English?

Because I suspect that more people may use or contribute to this library. Also many variables have the names of XML tags defined in UBL.

Why JavaScript?

Because it can be used directly from the web browser. There is only one technical problem with the web browser when sending to the Sunat server and that is that the Sunat server does not include the necessary header so that the web browser does not block the request.