§ 01 Hecho para SUNAT

UBL 2.1

Esquema oficial SUNAT

XMLDSig + SHA-256

Firma digital

7+

Documentos SUNAT

OpenAPI

SDKs tipados

§ 02 Ver el código

Python

invoice = Invoice(
  serie="F001",
  numero=1,
  proveedor=Proveedor(
      ruc="12345678901",
      razonSocial="Mi Empresa S.A.C.",
      nombreComercial="Mi Empresa",
      address={
          "ubigeo": "150101",
          "departamento": "Lima",
          "provincia": "Lima",
          "distrito": "Lima",
          "direccion": "Av. Ejemplo 123",
      },
  ),
  cliente=Cliente(
      tipoDocumentoIdentidad="6",
      numeroDocumentoIdentidad="98765432101",
      nombre="Cliente Ejemplo S.A.C.",
      address={
          "ubigeo": "150101",
          "departamento": "Lima",
          "provincia": "Lima",
          "distrito": "Lima",
          "direccion": "Calle Ficticia 456",
      },
  ),
  detalles=[
      DocumentoVentaDetalle(
          cantidad=2,
          descripcion="Producto de ejemplo",
          precio=50.00,
          unidadMedida="NIU",
      )
  ],
  moneda="PEN",
)

TypeScript

import { createInvoice, type Proveedor, type Cliente, type DocumentoVentaDetalle } from "@openubl/sdk";
import { zInvoice } from "@openubl/sdk/zod.gen";

const proveedor: Proveedor = {
  ruc: "20100066603",
  razonSocial: "Softgreen S.A.C.",
};

const cliente: Cliente = {
  nombre: "Carlos",
  numeroDocumentoIdentidad: "12121212121",
  tipoDocumentoIdentidad: "6",
};

const detalle: DocumentoVentaDetalle = {
  descripcion: "Item",
  cantidad: 10,
  precio: 100,
};

const invoice = zInvoice.parse({
  serie: "F001",
  numero: 1,
  proveedor,
  cliente,
  detalles: [detalle],
  moneda: "PEN",
});

const { data, error } = await createInvoice({
  body: invoice,
});

if (error) {
  throw new Error(JSON.stringify(error));
}

console.log(data.xml); // XML UBL 2.…

cURL

curl -X POST http://localhost:8000/api/v1/invoice/create \
-H "Content-Type: application/json" \
-d '{
  "serie": "F001",
  "numero": 1,
  "proveedor": {
    "ruc": "20100111111",
    "razonSocial": "Mi Empresa S.A.C."
  },
  "cliente": {
    "nombre": "Juan Perez",
    "numeroDocumentoIdentidad": "12345678",
    "tipoDocumentoIdentidad": "1"
  },
  "detalles": [
    {
      "descripcion": "Producto A",
      "cantidad": 2,
      "precio": 100.00
    }
  ],
  "moneda": "PEN"
}'

§ 03 ¿Qué puedes hacer?

Generar XML

Crea XML UBL 2.1 conforme a las especificaciones de SUNAT para todos los documentos electrónicos soportados.

Firmar documentos

Firma digitalmente tus comprobantes con XMLDSig y SHA-256 requeridos por SUNAT e INDECOPI/IOFE.

Validar con SUNAT

Valida la estructura y contenido de tus documentos antes del envío oficial.

SDK TypeScript

Cliente tipado con Zod y @hey-api/client-fetch generado desde OpenAPI.

API REST

Integra vía API REST con tipado Pydantic y documentación OpenAPI interactiva.

Clientes tipados

Usa clientes TypeScript con autocompletado de endpoints y validación estática.

Flujo de trabajo

1. Modelar — Define el documento con modelos Pydantic (Invoice, CreditNote, DebitNote, etc.).

2. Renderizar — Convierte el modelo a XML UBL 2.1 con render() o to_xml().

3. Firmar — Aplica firma digital XMLDSig con RSA-SHA-256 y SHA-256 usando tu certificado PEM.

4. Enviar — Envía el ZIP firmado a SUNAT y recibe el CDR de confirmación.

Soporte multi-lenguaje

openUBL se puede usar desde Python y TypeScript:

+- Python — Biblioteca nativa con modelos Pydantic +- TypeScript / JavaScript — SDK npm @openubl/sdk