Integración de la API de Contifico: Automatizando la Facturación ERP en Ecuador

En el ecosistema empresarial ecuatoriano, Contifico (parte de la suite corporativa de Siigo) se ha consolidado como una de las plataformas de planificación de recursos empresariales (ERP) en la nube más dominantes. Al desarrollar software SaaS para comercios locales —tales como carritos de compra o portales contables— integrar la API de Contifico nos permite delegar la contabilidad legal, el control de inventario físico y la conciliación bancaria a un sistema certificado, sin tener que reinventar la rueda en nuestro backend.

¿Cómo funciona la arquitectura de la API de Contifico?

La API de Contifico está estructurada bajo estándares **REST**. Para poder realizar peticiones autenticadas, es mandatorio generar una API Key (Token de Autorización) desde la sección de configuración del administrador de Contifico y enviarla en las cabeceras HTTP de cada solicitud.

Paso 1: Configurar el Cliente HTTP Seguro

Para iniciar la integración, estructuramos un cliente HTTP centralizado utilizando Axios en Node.js, configurando las variables de entorno de forma segura para no exponer nuestras credenciales en el código fuente.

import axios from 'axios';

const CONTIFICO_BASE_URL = 'https://api.contifico.com/v1';

// Cliente HTTP reutilizable con cabeceras de autorización obligatorias
export const contificoClient = axios.create({
  baseURL: CONTIFICO_BASE_URL,
  headers: {
    'Authorization': process.env.CONTIFICO_API_KEY, // Token privado desde variables de entorno
    'Content-Type': 'application/json'
  }
});

Paso 2: Registro Automático de Facturas y Emisión al SRI

Para registrar una nueva venta y generar una factura legal autorizada por el SRI, realizamos una solicitud POST al endpoint `/documento/` enviando la información estructurada del cliente, los servicios y el método de pago local.

interface DetalleFactura {
  producto_id: string;
  cantidad: number;
  precio: number;
  porcentaje_iva: number;
}

interface DocumentoInput {
  rucCliente: string;
  items: DetalleFactura[];
  formaPago: string; // E.g., 'TARJETA DE CREDITO' o 'EFECTIVO'
}

export async function emitirFacturaContifico({ rucCliente, items, formaPago }: DocumentoInput) {
  try {
    const payload = {
      tipo: 'FAC', // FAC identifica un documento tipo Factura
      fecha: new Date().toLocaleDateString('es-EC'),
      cliente: {
        ruc: rucCliente
      },
      detalles: items.map(item => ({
        producto_id: item.producto_id,
        cantidad: item.cantidad,
        precio: item.precio,
        porcentaje_iva: item.porcentaje_iva
      })),
      pagos: [{
        medio: formaPago,
        // Sumatoria del total con IVA incluido para cuadrar la forma de pago
        valor: items.reduce((total, i) => total + (i.cantidad * i.precio * (1 + i.porcentaje_iva / 100)), 0)
      }]
    };

    const response = await contificoClient.post('/documento/', payload);
    
    return {
      success: true,
      documentoId: response.data.id,
      claveAccesoSri: response.data.clave_acceso // Clave de acceso de 49 dígitos para el SRI
    };
  } catch (error: any) {
    console.error('Fallo en la facturación de Contifico:', error.response?.data || error.message);
    return { success: false, error: error.message };
  }
}

Sincronización Automatizada de Stock de Inventario

Una de las ventajas cruciales de esta API es que, al registrar una factura, Contifico reduce automáticamente la cantidad física de inventario en bodega. Para mantener sincronizado nuestro catálogo local de forma asíncrona, podemos planificar tareas programadas (Cron Jobs) que consulten periódicamente las cantidades actualizadas mediante el endpoint `/producto/`.