Ejemplo: crear una venta

Crear una venta es el primer flujo recomendado para probar una integración real: envía un payload de negocio, impacta los efectos que correspondan y devuelve una respuesta tipada con requestId, datos persistidos, efectos y warnings.

import { Lapyme } from "lapyme";

const lapyme = new Lapyme({
  bearerAuth: process.env["LAPYME_API_KEY"] ?? "",
});

const externalOrderId = "shopify-1001";

const sale = await lapyme.sales.create({
  lapymeVersion: "2026-08-20",
  idempotencyKey: `sale:shopify:${externalOrderId}`,
  body: {
    customerId: "9c692e8b-0f9a-4f7c-8b99-061a2eb188ae",
    pointOfSaleId: "8d3e9c5a-0b1d-4a8c-9b55-4f1d6b6d4a10",
    integrationSource: "SHOPIFY",
    integrationId: externalOrderId,
    voucherType: 6,
    invoiceDate: new Date(),
    currency: "ARS",
    notes: `Pedido externo ${externalOrderId}`,
    items: [
      {
        productId: "4fb3af29-4ee4-4a8d-8b20-9a95b2431b73",
        quantity: 1,
        unitPrice: 125000,
        taxRateId: 5,
      },
    ],
    total: 125000,
  },
});

console.log({
  requestId: sale.result.requestId,
  sale: sale.result.data.sale,
  effects: sale.result.data.projectedEffects,
  warnings: sale.result.warnings,
});

lapymeVersion: "2026-08-20" activa el contrato fechado y estricto. En ese contrato, total es el total final esperado y es obligatorio. Para comprobantes A (voucherType 1, 2 y 3), unitPrice es neto sin IVA. Para comprobantes a consumidor final, como B (voucherType 6, 7 y 8) y presupuesto (voucherType 90), unitPrice es final con IVA incluido. Cuando enviás productId, La Pyme resuelve el producto y usa el mismo renglón canónico para stock, contabilidad, fiscalización y respuesta. No necesitás leer el producto de nuevo para calcular importes derivados. Si el total no coincide, el SDK recibe un error 422 BUSINESS_REQUIREMENT_UNMET con un detalle TOTAL_MISMATCH; no se crea la venta ni sus efectos. El contrato fechado rechaza campos desconocidos y campos monetarios derivados, como subtotal, taxAmount, discountAmount, taxIncludedOverride y roundingAdjustment. Omitir lapymeVersion conserva el contrato histórico, pero ese modo está deprecado.

Descargar el comprobante

La respuesta de creación incluye sale.invoicePdf cuando el comprobante ya puede tener un PDF. El valor es una ruta estable de la API, por ejemplo /api/v1/sales/{sale_id}/document. El detalle de la venta también conserva document.file para mantener compatibilidad con las integraciones existentes. La ruta requiere la misma API key con sales:read y responde con un redirect 302 hacia una URL firmada de cinco minutos.

const documentUrl = sale.result.data.sale.invoicePdf;

if (documentUrl) {
  const response = await fetch(`https://api.lapyme.com.ar${documentUrl}`, {
    headers: {
      Authorization: `Bearer ${process.env.LAPYME_API_KEY}`,
    },
    redirect: "follow",
  });

  if (!response.ok) {
    throw new Error(await response.text());
  }

  const invoicePdf = await response.arrayBuffer();
}

Si el comprobante todavía se está generando, el endpoint de descarga responde 409 PRECONDITION_FAILED, retryable: true y Retry-After: 5. Si la generación falló, responde 409 con retryable: false. Descargar el documento no inicia una regeneración.

La ruta autenticada sale.invoicePdf es para integraciones. El Location firmado existe solo para transferir el archivo y no debe persistirse. Los links públicos opacos /comprobantes/d/{token} usados en emails son credenciales de portador distintas; la ruta pública histórica usada por WhatsApp tampoco forma parte del contrato de la API.

Facturar una venta ya importada

Si Tiendanube, Mercado Libre u otra integración ya importó el pedido como una venta, no llames sales.create y no lo conviertas en un order. Facturá el saleId existente con una key estable:

const invoice = await lapyme.sales.invoice({
  saleId: importedSaleId,
  idempotencyKey: `marketplace:invoice:${integrationSource}:${externalOrderId}`,
});

if (invoice.result.data.status === "deferred") {
  // La venta todavía no fue facturada. Volvé a leerla antes de reintentar.
}

Una repetición idéntica devuelve idempotentReplay: true. No uses la misma key para otro saleId. Después de corregir un rechazo final o la configuración fiscal, enviá una key nueva.

Reintentos seguros

Si tu worker, backend o job reintenta la misma venta, reenviá el mismo idempotencyKey. No generes una key nueva para cada intento del mismo pedido. La clave de idempotencia no se guarda como referencia externa de la venta; si necesitás ver o buscar el ID de tu sistema, envialo también en integrationSource e integrationId.

const idempotencyKey = `sale:shopify:${externalOrderId}`;

await lapyme.sales.create({
  lapymeVersion: "2026-08-20",
  idempotencyKey,
  body: salePayload,
});

Usá importes monetarios en centavos. Por ejemplo, $1.250,00 se envía como 125000.

Documentación

SDK

Referencia API

Descargar el comprobante

Facturar una venta ya importada

Reintentos seguros

​Descargar el comprobante

​Facturar una venta ya importada

​Reintentos seguros

Descargar el comprobante

Facturar una venta ya importada

Reintentos seguros