@chalatech/turbopyme-react

Un conjunto de React Hooks personalizados y componentes "headless" (sin estilos forzados) para integrarse fácilmente con la API de Turbopyme y emitir Documentos Tributarios Electrónicos (DTE) para El Salvador.

Esta librería facilita la autenticación, el manejo de catálogos del Ministerio de Hacienda, y los complejos flujos de emisión de Facturas y Comprobantes de Crédito Fiscal.

⚡ TL;DR - Resumen Rápido

| Categoría | Nombre | Descripción | | :--- | :--- | :--- | | Hooks | useCatalogs | Carga catálogos de Hacienda (giros, ubicaciones). | | | useDteEmission | Firma y envía Facturas (FE) y Crédito Fiscal (CCF). | | | useCustomerProfile | Gestiona perfiles y datos fiscales de clientes. | | Componentes | <LocationSelect /> | Selector doble de Depto/Municipio vinculado. | | | <SearchableActivitySelect /> | Buscador de actividades económicas (giros). | | Validación | receptorFacturaSchema | Esquema Zod para clientes (DUI/Pasaporte). | | | receptorCCFSchema | Esquema Zod para empresas (NIT/NRC/Ubicación). | | | documentLineSchema | Esquema Zod para ítems de venta. |

🚀 Instalación

npm install @chalatech/turbopyme-react zod

(Nota: Esta librería utiliza zod para la validación de esquemas y está construida para react >= 18).

⚙️ Configuración Inicial

Para que los hooks puedan comunicarse con la API de Turbopyme, debes envolver tu aplicación (o la parte de tu app que facturará) con el TurbopymeProvider.

import { TurbopymeProvider } from '@chalatech/turbopyme-react';

function App() {
  return (
    <TurbopymeProvider 
      initialBaseUrl="https://app.turbopyme.com/api/v1"
      initialToken="eyJhbGciOiJIUzI1NiIsIn..." // Tu token JWT de sesión
    >
      <TuAplicacion />
    </TurbopymeProvider>
  );
}

🛠 Funcionalidades y Hooks Principales

1. useCatalogs (Catálogos de Hacienda)

Obtiene y almacena en memoria los catálogos oficiales necesarios para llenar un DTE, como Actividades Económicas, Departamentos y Municipios.

Ejemplo de uso:

import { useEffect } from 'react';
import { useCatalogs } from '@chalatech/turbopyme-react';

const CatalogoVista = () => {
  const { 
    activities, 
    locations, 
    fetchEconomicActivities, 
    fetchLocations, 
    loadingLocations 
  } = useCatalogs();

  useEffect(() => {
    fetchEconomicActivities();
    fetchLocations();
  }, []);

  if (loadingLocations) return <p>Cargando departamentos...</p>;

  return (
    <ul>
      {locations.map(depto => (
        <li key={depto.code}>{depto.value} (Municipios: {depto.municipios.length})</li>
      ))}
    </ul>
  );
};

2. useDteEmission (Emisión de DTEs)

Expone las funciones necesarias para enviar la carga (payload) a la API de Turbopyme para ser firmada y enviada a Hacienda. Soporta Factura Electrónica (FE) y Comprobante de Crédito Fiscal (CCF).

Ejemplo de Emisión de Factura (con datos reales simulados):

import { useDteEmission } from '@chalatech/turbopyme-react';

const Facturador = () => {
  const { emitFactura, loadingFactura } = useDteEmission();

  const manejarCobro = async () => {
    const payloadFactura = {
      receptor: {
        nombre: "Juan Pérez",
        tipoDocumento: "13", // 13 = DUI
        numDocumento: "01234567-8",
        correo: "[email protected]"
      },
      cuerpoDocumento: [
        {
          numItem: 1,
          tipoItem: 1, // 1 = Bienes
          cantidad: 2,
          codigo: "PROD-001",
          descripcion: "Zapatos de Cuero",
          precioUni: 45.00,
          montoDescu: 0,
          ventaGravada: 90.00,
          tributos: ["20"] // 20 = IVA Mínimo
        }
      ],
      resumen: {
        totalGravada: 90.00,
        montoTotalOperacion: 90.00,
        totalPagar: 90.00
      }
    };

    try {
      const resultado = await emitFactura(payloadFactura);
      console.log('✅ Sello de recepción:', resultado.sello_recepcion);
      console.log('📄 Código de generación:', resultado.generation_code);
    } catch (error) {
      console.error('❌ Fallo al emitir:', error);
    }
  };

  return (
    <button onClick={manejarCobro} disabled={loadingFactura}>
      {loadingFactura ? 'Emitiendo...' : 'Emitir Factura de $90.00'}
    </button>
  );
};

3. useCustomerProfile (Gestión de Clientes)

Útil para cargar y actualizar la información fiscal de un cliente específico, ideal para pre-llenar los datos de facturación (NIT, NRC, Actividad Económica).

import { useEffect } from 'react';
import { useCustomerProfile } from '@chalatech/turbopyme-react';

const PerfilCliente = ({ customerId }) => {
  // Inicializamos el hook con el ID del cliente
  const { getCustomer, updateCustomer, loading } = useCustomerProfile(customerId);

  useEffect(() => {
    getCustomer().then(data => console.log('Datos del cliente:', data));
  }, [customerId]);

  const actualizarDatos = async () => {
    await updateCustomer({
      nombreLegal: "Inversiones Tecnologicas S.A. de C.V.",
      nrc: "123456-7",
      nit: "0614-010190-101-1",
      actividadEconomica: "62010" // Desarrollo de sistemas informáticos
    });
  };

  if (loading) return <p>Sincronizando información...</p>;

  return <button onClick={actualizarDatos}>Actualizar Perfil Fiscal</button>;
};

🧩 Componentes UI Incluidos

La librería provee componentes "headless" o sin estilos estrictos. Puedes pasarles tus propias clases de CSS o Tailwind a través de los props.

LocationSelect

Un componente compuesto que maneja automáticamente la relación entre Departamento y Municipio.

import { useState } from 'react';
import { LocationSelect } from '@chalatech/turbopyme-react';

const FormularioDireccion = () => {
  const [depto, setDepto] = useState('06'); // 06 = San Salvador (Catálogo Hacienda)
  const [muni, setMuni] = useState('14'); // 14 = San Salvador centro

  return (
    <LocationSelect 
      departamento={depto}
      municipio={muni}
      onDepartamentoChange={setDepto}
      onMunicipioChange={setMuni}
      // Estilos personalizados
      className="flex flex-col gap-4"
      selectClassName="border p-2 rounded w-full"
    />
  );
};

SearchableActivitySelect

El catálogo de actividades económicas del Ministerio de Hacienda tiene más de 1000 registros. Este componente provee un buscador integrado para filtrar por código o nombre de actividad.

import { useState } from 'react';
import { SearchableActivitySelect } from '@chalatech/turbopyme-react';

const FormularioFiscal = () => {
  const [actividad, setActividad] = useState('62010');

  return (
    <div>
      <label>Actividad Económica (Giro)</label>
      <SearchableActivitySelect
        value={actividad}
        onChange={setActividad}
        placeholder="Ej. Restaurantes, Desarrollo de software..."
        inputClassName="border p-2 w-full rouded"
        listClassName="bg-white border shadow-lg"
        itemClassName="hover:bg-gray-100 p-2"
      />
    </div>
  );
};

👨‍💻 Validación con Zod (dteSchemas)

La librería exporta esquemas ya construidos y validados con las reglas exclusivas del Ministerio de Hacienda de El Salvador. Estos son perfectos para usar junto con react-hook-form y @hookform/resolvers para validar tus UI antes del envío.

Esquemas disponibles:

• receptorFacturaSchema: Valida un cliente común (Factura Electrónica). Exige nombre válido y correos verificados.
• receptorCCFSchema: Valida empresas para un Crédito Fiscal. Obliga a que tengan NIT de 14 dígitos (sin guiones), NRC, Ubicación Exacta y Actividad Económica.
• documentLineSchema: Valida una línea de ítem en la factura (cantidades válidas, mínimo de montos, etc).
• emisorSchema: Valida los datos fiscales de la propia empresa que emite.

Ejemplo de Validación Básica:

import { receptorCCFSchema } from '@chalatech/turbopyme-react';

const datosCliente = {
  nombre: "Distribuidora El Salvador",
  nit: "06141212801015", // sin guiones, ¡válido!
  nrc: "12345-6",
  actividadEconomica: "45200",
  departamento: "06", // San Salvador
  municipio: "14", // San Salvador
  complemento: "Calle San Antonio Abad",
  correo: "[email protected]"
};

try {
  // Parse verificará reglas automáticamente
  const valido = receptorCCFSchema.parse(datosCliente);
  console.log("Datos de empresa correctos:", valido);
} catch (error) {
  // Manejo de los errores tipográficos definidos en español
  console.error(error.errors);
}

📄 Funciones de Construcción (dteBuilders)

La librería también exporta funciones utilitarias que ayudan a estructurar JSON complejos de emisión, listos para enviar a useDteEmission().

📎 Licencia

MIT © Chalatech