sunapi365

Official JavaScript and TypeScript SDK for SUNAPI.

This package is prepared as a real npm library for production use. It exposes the public SUNAPI surface with a clean domain-based API, generated type declarations, and support for modern JavaScript, CommonJS, and TypeScript consumers.

Why this package exists

SUNAPI covers products, customers, tickets, receipts, invoices, notes, summaries, dispatch guides, credentials, settings, and webhooks. A public SDK must make those resources easy to discover without hiding the underlying API model.

This package is organized to do that:

• one public package for JavaScript and TypeScript
• typed resources grouped by domain
• ESM and CommonJS support from the same publication
• a production-ready default endpoint with local override support

Install

npm install sunapi365

pnpm add sunapi365

bun add sunapi365

Quick start

import { auth, companies, createSunApiSdk } from "sunapi365";

const sdk = createSunApiSdk();

const tokens = await auth.oauthClientCredentials(
  sdk,
  "YOUR_CLIENT_ID",
  "YOUR_CLIENT_SECRET",
);

sdk.setAccessToken(tokens.accessToken);

const companyList = await companies.list(sdk);

What the package supports

This package is designed for:

• JavaScript via import
• JavaScript via require
• TypeScript with generated .d.ts

CommonJS example:

const { createSunApiSdk, auth } = require("sunapi365");

const sdk = createSunApiSdk();

Public entrypoints

Root import:

import { createSunApiSdk, products, tickets, documents } from "sunapi365";

Subpath imports:

import { createSunApiSdk } from "sunapi365/client";
import { products } from "sunapi365/products";
import type { TicketCreateInput } from "sunapi365/types";

Available subpaths:

• sunapi365/client
• sunapi365/errors
• sunapi365/types
• sunapi365/auth
• sunapi365/catalogs
• sunapi365/companies
• sunapi365/branches
• sunapi365/customers
• sunapi365/products
• sunapi365/settings
• sunapi365/tickets
• sunapi365/cash
• sunapi365/documents
• sunapi365/credentials
• sunapi365/webhooks

Package layout

sdk/
  src/
    index.ts
    resources/
      client.ts
      errors.ts
      types.ts
      internal.ts
      auth.ts
      catalogs.ts
      companies.ts
      branches.ts
      customers.ts
      products.ts
      settings.ts
      tickets.ts
      cash.ts
      documents.ts
      credentials.ts
      webhooks.ts
  dist/

Endpoint strategy

The SDK defaults to the production API:

https://api.sunapi.site

That is the right default for a public npm package. Consumers can still override baseUrl for local development, staging, proxy routing, or tests.

const sdk = createSunApiSdk({
  baseUrl: "http://localhost:3000",
});

Authentication

Supported OAuth grants:

• clientCredentials
• password
• refreshToken

Server-to-server integrations should prefer clientCredentials.

const tokens = await auth.oauthClientCredentials(
  sdk,
  "YOUR_CLIENT_ID",
  "YOUR_CLIENT_SECRET",
);

Document example

import { auth, createSunApiSdk } from "sunapi365";
import { invoices } from "sunapi365/documents";

const sdk = createSunApiSdk();
const tokens = await auth.oauthClientCredentials(
  sdk,
  "YOUR_CLIENT_ID",
  "YOUR_CLIENT_SECRET",
);

sdk.setAccessToken(tokens.accessToken);

const created = await invoices.create(sdk, "sandbox", {
  companyId: "YOUR_COMPANY_ID",
  branchId: "YOUR_BRANCH_ID",
  processingMode: "sync",
  series: "F001",
  issueDate: "2026-04-15",
  currency: "PEN",
  paymentType: "cash",
  paymentMethod: "transferencia",
  client: {
    documentType: "6",
    documentNumber: "RUC_CLIENTE_DEMO",
    legalName: "CLIENTE DEMO S.A.C.",
  },
  details: [
    {
      code: "PROD-001",
      description: "Producto demo",
      unit: "NIU",
      quantity: 1,
      unitPrice: 100,
      igvPercent: 18,
      igvAffectationType: "10",
    },
  ],
});

await invoices.sendToSunat(sdk, "sandbox", created.data.id, "sync");

Ticket and POS example

import { auth, createSunApiSdk } from "sunapi365";
import { tickets } from "sunapi365/tickets";

const sdk = createSunApiSdk();
const tokens = await auth.oauthClientCredentials(
  sdk,
  "YOUR_CLIENT_ID",
  "YOUR_CLIENT_SECRET",
);

sdk.setAccessToken(tokens.accessToken);

const created = await tickets.create(sdk, {
  companyId: "YOUR_COMPANY_ID",
  branchId: "YOUR_BRANCH_ID",
  customerName: "Cliente demo",
  targetDocumentType: "receipt",
  currency: "PEN",
  items: [
    {
      productId: "YOUR_PRODUCT_ID",
      quantity: 1,
      unitPrice: 30,
    },
  ],
});

await tickets.pay(sdk, created.data.id, {
  method: "cash",
  amount: 30,
});

Publication readiness

The package is already prepared with:

• exports for root and subpath entrypoints
• generated ESM, CommonJS, and type declarations
• npm metadata for homepage, repository, and issues
• publishConfig.access = public
• a README structured for package discovery and installation