Una capa tipada entre tu backend y el servicio de Visioner7

Primeros pasos

Instala la capa de integración

El SDK se distribuye como paquete scoped y depende de @nestjs/axios para realizar las peticiones HTTP hacia el servicio contratado.

npm install @angelitosystems/sdk-visioner7
npm install @nestjs/axios axios reflect-metadata rxjs

Si el proyecto vive dentro de un monorepo o como código interno, también puede integrarse como librería privada, por ejemplo en libs/sdk-visioner7/, o distribuirse mediante un registro privado de paquetes.

Primeros pasos

Requisitos

• NestJS 12 y TypeScript en el proyecto host.
• Node.js en una versión moderna con soporte activo.
• @nestjs/axios, axios, reflect-metadata y rxjs como dependencias del proyecto.
• Credenciales vigentes del servicio contratado (token de autenticación y, según la operación, token de negocio o credenciales SOL).

Configuración

Registra el módulo

Usa forRoot para una configuración directa, o forRootAsync cuando las credenciales provienen de variables de entorno o de un ConfigService. El módulo puede registrarse como global para evitar importaciones repetidas donde se use SDKVisioner7Service.

import { Module } from '@nestjs/common';
import { SDKVisioner7Module } from '@angelitosystems/sdk-visioner7';

@Module({
  imports: [
    SDKVisioner7Module.forRoot({
      baseUrl: 'https://visioner7-api.com/api',
      authToken: process.env.SDK_VISIONER7_AUTH_TOKEN,
      businessToken: process.env.SDK_VISIONER7_BUSINESS_TOKEN,
      timeout: 15000,
    }),
  ],
})
export class AppModule {}

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { SDKVisioner7Module } from '@angelitosystems/sdk-visioner7';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),

    SDKVisioner7Module.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        baseUrl: config.get<string>('SDK_VISIONER7_BASE_URL'),
        authToken: config.get<string>('SDK_VISIONER7_AUTH_TOKEN'),
        businessToken: config.get<string>('SDK_VISIONER7_BUSINESS_TOKEN'),
        timeout: 15000,
      }),
    }),
  ],
})
export class AppModule {}

Configuración

Variables de entorno

Nunca almacenes credenciales reales directamente en el código fuente. Usa variables de entorno, un secret manager o los secretos administrados por tu proveedor de infraestructura.

SDK_VISIONER7_BASE_URL=https://visioner7-api.com/api
SDK_VISIONER7_AUTH_TOKEN=your_token_here
SDK_VISIONER7_BUSINESS_TOKEN=your_business_token_here

Uso

Inyecta el servicio donde lo necesites

Una vez registrado el módulo, SDKVisioner7Service queda disponible para cualquier servicio de dominio o controlador de NestJS.

import { Injectable } from '@nestjs/common';
import { SDKVisioner7Service } from '@angelitosystems/sdk-visioner7';

@Injectable()
export class FacturacionService {
  constructor(private readonly sdkVisioner7Service: SDKVisioner7Service) {}

  async validarCliente(ruc: string) {
    const response = await this.sdkVisioner7Service.lookupTaxpayer(ruc);
    return response.taxpayer;
  }
}

Referencia de API

Tres grupos de operaciones

Cada grupo se identifica con un color a lo largo de toda la guía, para que sea fácil ubicar a qué frente pertenece cada método.

Consultar RUC

const response = await sdkVisioner7Service.lookupTaxpayer('20611187719');
console.log(response.taxpayer.businessName);

const domicilio = await sdkVisioner7Service.lookupEstablishments(
  '20611187719',
  EstablishmentQueryType.FISCAL_ADDRESS,
);

const persona = await sdkVisioner7Service.lookupPerson('10292315');
console.log(persona.person.givenNames);

const response = await sdkVisioner7Service.getExchangeRate({ year: 2025, month: 7 });

const compra = response.data.find(item => item.side === 'C')?.value;
const venta = response.data.find(item => item.side === 'V')?.value;

Guías de remisión

const resultado = await sdkVisioner7Service.issueRemittanceGuide({
  processType: '1',
  companyDocumentNumber: 'YOUR_RUC',
  companySolUsername: 'YOUR_SOL_USER',
  companySolPassword: 'YOUR_SOL_PASSWORD',
  signaturePassword: 'YOUR_SIGNATURE_PASSWORD',
  idToken: 'YOUR_ID_TOKEN',
  tokenKey: 'YOUR_TOKEN_KEY',
  documentTypeCode: '09',
  documentNumber: 'T001-00000002',
  documentDate: '2025-08-10',
  companyDocumentType: '6',
  companyBusinessName: 'EMPRESA DE EJEMPLO S.A.C.',
  recipientDocumentType: '6',
  recipientDocumentNumber: 'YOUR_CLIENT_RUC',
  recipientBusinessName: 'CLIENTE DE EJEMPLO S.A.C.',
  shipmentItem: '1',
  transferReasonCode: '01',
  transferReasonDescription: 'VENTA',
  grossWeightUnit: 'KGM',
  grossWeight: '10.00',
  transportModalityCode: '01',
  startDate: '2025-08-10',
  originUbigeoCode: '150101',
  originAddress: 'AV. EJEMPLO 123',
  destinationUbigeoCode: '150101',
  destinationAddress: 'AV. DESTINO 456',
  items: [
    { item: '1', unitOfMeasure: 'NIU', quantity: '1', orderItem: '1', description: 'PRODUCTO DE EJEMPLO', code: 'PROD001' },
  ],
});
// los valores mostrados son ilustrativos: sustitúyelos por los de tu propio entorno

const estado = await sdkVisioner7Service.getRemittanceGuideTicketStatus({
  ticket: 'YOUR_TICKET',
  companyDocumentNumber: 'YOUR_RUC',
  companySolUsername: 'YOUR_SOL_USER',
  companySolPassword: 'YOUR_SOL_PASSWORD',
  idToken: 'YOUR_ID_TOKEN',
  tokenKey: 'YOUR_TOKEN_KEY',
  documentTypeCode: '31',
  documentNumber: 'V001-00000001',
  processType: '1',
});

Comprobantes electrónicos

const factura = await sdkVisioner7Service.generateVoucher({
  operationType: '0101',
  totalTaxableAmount: '305.08',
  subtotal: '305.08',
  igvPercentage: '18.00',
  totalIgv: '54.92',
  total: '360.00',
  voucherTypeCode: '01',
  currencyCode: 'PEN',
  voucherNumber: 'F001-00000001',
  issueDate: '2025-08-10',
  totalInWords: 'TRESCIENTOS SESENTA CON 00/100 SOLES',
  clientDocumentNumber: 'YOUR_CLIENT_DOCUMENT',
  clientBusinessName: 'CLIENTE DE EJEMPLO',
  clientDocumentType: '6',
  companyDocumentNumber: 'YOUR_RUC',
  companyDocumentType: '6',
  companyBusinessName: 'EMPRESA DE EJEMPLO S.A.C.',
  companySolUsername: 'YOUR_SOL_USER',
  companySolPassword: 'YOUR_SOL_PASSWORD',
  certificatePassword: 'YOUR_CERT_PASSWORD',
  signaturePassword: 'YOUR_SIGNATURE_PASSWORD',
  processType: '1',
  paymentTerms: [{ paymentFormCode: 'Contado', amount: '360.00' }],
  items: [{
    item: '1', unitOfMeasure: 'NIU', quantity: '1.00',
    price: '360.00', amount: '305.08', igv: '54.92',
    code: 'PROD001', description: 'PRODUCTO DE EJEMPLO',
    priceTypeCode: '01', igvPercentage: '18.00', isc: '0.00',
    operationTypeCode: '10', priceWithoutIgv: '305.08',
    icbperFlag: 0, icbperTaxAmount: '0.00', icbperTotalAmount: '0.00',
  }],
});

console.log(factura.sunatMessage, factura.file);

Operación

Manejo de errores

El SDK centraliza los errores mediante SDKVisioner7ApiException, que extiende HttpException de NestJS, para integrarse con los ExceptionFilter globales de tu aplicación.

import { SDKVisioner7ApiException } from '@angelitosystems/sdk-visioner7';

try {
  await sdkVisioner7Service.lookupTaxpayer('00000000000');
} catch (error) {
  if (error instanceof SDKVisioner7ApiException) {
    console.error(error.endpoint, error.providerResponse);
  }
  throw error;
}

Operación

Arquitectura recomendada

El frontend no debe comunicarse directamente con el servicio externo usando credenciales privadas. Las credenciales permanecen exclusivamente en el backend, detrás de SDKVisioner7Service.

Los distintos servicios de dominio de tu backend hablan con SDKVisioner7Service; solo esa capa conoce el servicio externo.

Seguridad

Protección de datos

Las operaciones de consulta y emisión pueden involucrar información empresarial o datos personales. La aplicación que utilice este SDK es responsable de:

• Gestionar adecuadamente las credenciales.
• Implementar controles de acceso.
• Proteger la información almacenada.
• Evitar registrar información sensible innecesariamente.
• Cumplir con la normativa que resulte aplicable.
• Utilizar las credenciales únicamente para las finalidades autorizadas.
• Implementar medidas adecuadas de seguridad.

El SDK no pretende sustituir las obligaciones legales, regulatorias o contractuales del sistema que lo utilice.

Referencia

Glosario

El servicio integra con conceptos tributarios y logísticos de Perú. Esta sección explica cada término que aparece en el SDK y en los payloads del proveedor.

Referencia

Migración v1 → v2

Desde la versión 2.0.0 la API pública del SDK (métodos, clases e interfaces) está nombrada en inglés, y el SDK traduce internamente los payloads hacia el formato del proveedor (capa de mapping/). Los alias antiguos (SunatModule, consultarRuc, etc.) fueron eliminados.

Los payloads y respuestas también llegan tipados en inglés (por ejemplo response.taxpayer.businessName en vez de response.comprobante.desRazonSocial).

Proyecto

Estructura de carpetas

Compilar con npm run build genera los archivos JavaScript y las declaraciones TypeScript en dist/.

La carpeta mapping/ traduce entre la API pública del SDK (en inglés) y el formato que espera el proveedor (campos como txtTOTAL, NRO_DOCUMENTO_EMPRESA, etc.).

La carpeta example/ contiene una integración de referencia completa, registrando el módulo con forRootAsync a partir de ConfigService.

Proyecto

Naturaleza del proyecto y licencia

Este proyecto es una librería de integración independiente. No constituye una API propia de SUNAT ni un producto oficial de Visioner7, y no implica afiliación, asociación, patrocinio o representación por parte de Visioner7. Se limita a ofrecer una interfaz de software para integrar una aplicación con un servicio externo al que el usuario o cliente tenga acceso autorizado.

Licencia

La licencia debe definirse según la forma en que se distribuya la librería. Para uso privado en proyectos propios o de clientes, se recomienda mantener el repositorio privado y establecer por contrato las condiciones de uso, distribución y soporte.

Para conocer las condiciones, disponibilidad y características actuales del servicio externo, consulta directamente visioner7-api.com.