Registrar compra

Registra el comprobante de un proveedor. Los ítems con `varianteId` de un producto que controla stock entran al inventario (tipo `02`) al costo sin IGV; los demás quedan como gasto.

POSThttps://api.facturalo.pe/api/v3/compras

Parámetros del body

Campo

Descripción

proveedor.numeroDocumento

stringrequerido

RUC (11) o DNI (8) del proveedor. Si no existe, se crea.Ej: 20131312955

proveedor.razonSocial

stringrequerido

Razón social o nombre.Ej: DISTRIBUIDORA EJEMPLO S.A.C.

proveedor.direccion

stringopcional

Dirección (opcional).

tipoDocumento

stringrequerido

01 factura o 03 boleta.Ej: 01

serie

stringrequerido

Serie del comprobante del proveedor.Ej: F001

numero

stringrequerido

Número (solo dígitos).Ej: 887

fecha

stringrequerido

Fecha de emisión YYYY-MM-DD. Es la fecha del movimiento en el kárdex.Ej: 2026-11-03

moneda

stringopcional

PEN (default), USD o EUR.

tipoCambio

numberopcional

Obligatorio si la moneda no es PEN: pasa el costo a soles.

establecimientoId

stringopcional

Almacén donde entra la mercadería. Default: el principal.

origen

stringopcional

manual (default) o sunat si el detalle vino de SUNAT.

totales

objectopcional

gravado, exonerado, inafecto, igv, otros, total. Si no se envían, se calculan de los ítems.

nota

stringopcional

Hasta 250 caracteres.

items[].descripcion

stringrequerido

Descripción como figura en el comprobante.

items[].cantidad

numberrequerido

Mayor a 0.

items[].valorUnitario

numberrequerido

Valor unitario sin IGV, en la moneda de la compra.

items[].total

numberrequerido

Total de la línea con impuestos.

items[].descuento

numberopcional

Descuento de la línea (se resta del costo).

items[].varianteId

stringopcional

Producto (variante) de tu catálogo. Si controla stock, entra al inventario. null = gasto o servicio.

items[].series

arrayopcional

Números de serie / IMEI, si el producto los controla.

items[].codigoProveedor

stringopcional

Código del ítem en el comprobante del proveedor (sirve para recordarlo).

items[].unidad

stringopcional

Unidad de medida (tabla 6). Default NIU.

items[].recordar

booleanopcional

Default true: guarda la relación ítem → producto para las próximas compras de este proveedor.

formaPago

stringopcional

CONTADO (default) o CREDITO. Al crédito, la deuda con el proveedor va a cuentas por pagar.

cuotas

arrayopcional

Al crédito: [{fecha, monto}] (YYYY-MM-DD); deben sumar el total. Sin cuotas, una sola a 30 días.

Language

Credentials

Header

Authorization

Token de la empresa · HTTP directo

Fetch Request

$ # Node 18+ fetch

const response = await fetch("https://api.facturalo.pe/api/v3/compras", {
  method: "POST",
  headers: {
    "Authorization": "sk_test_…",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "proveedor": {
      "numeroDocumento": "20131312955",
      "razonSocial": "DISTRIBUIDORA EJEMPLO S.A.C."
    },
    "tipoDocumento": "01",
    "serie": "F001",
    "numero": "887",
    "fecha": "2026-11-03",
    "moneda": "PEN",
    "origen": "manual",
    "items": [
      {
        "descripcion": "POLO ALGODON AZUL TALLA M",
        "cantidad": 12,
        "valorUnitario": 18.5,
        "total": 261.96,
        "varianteId": "a32fc76c-49f8-48c9-933f-62d3e8da007d"
      },
      {
        "descripcion": "FLETE LIMA",
        "cantidad": 1,
        "valorUnitario": 30,
        "total": 35.4,
        "varianteId": null
      }
    ]
  })
});

const data = await response.json();
console.log(data);

HTTP directo · funciona con cualquier cliente HTTP

Response

Elige un ejemplo de respuesta:

application/json

201Created

{
  "success": true,
  "message": "Compra registrada.",
  "data": {
    "id": "9f2c1a7e-3b4d-4e5f-8a9b-0c1d2e3f4a5b",
    "tipoDocumento": "01",
    "serie": "F001",
    "numero": "887",
    "fecha": "2026-11-03",
    "proveedor": {
      "id": "4b1e2c3d-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "numeroDocumento": "20131312955",
      "razonSocial": "DISTRIBUIDORA EJEMPLO S.A.C.",
      "direccion": "AV. EJEMPLO 123, LIMA"
    },
    "moneda": "PEN",
    "total": 297.36,
    "origen": "sunat",
    "estado": "registrada",
    "tipoCambio": null,
    "totales": {
      "gravado": 252,
      "exonerado": 0,
      "inafecto": 0,
      "igv": 45.36,
      "otros": 0,
      "total": 297.36
    },
    "establecimiento": {
      "id": "11111111-2222-3333-4444-555555555555",
      "nombre": "Principal"
    },
    "nota": null,
    "items": [
      {
        "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "descripcion": "POLO ALGODON AZUL TALLA M",
        "codigoProveedor": null,
        "unidad": "NIU",
        "cantidad": 12,
        "valorUnitario": 18.5,
        "total": 261.96,
        "series": [],
        "producto": {
          "varianteId": "a32fc76c-49f8-48c9-933f-62d3e8da007d",
          "descripcion": "Polo algodón azul - M",
          "sku": "POLO-AZ-M"
        },
        "entroAlStock": true
      },
      {
        "id": "d2e3f4a5-b6c7-4d8e-9f0a-1b2c3d4e5f6a",
        "descripcion": "FLETE LIMA",
        "codigoProveedor": null,
        "unidad": "ZZ",
        "cantidad": 1,
        "valorUnitario": 30,
        "total": 35.4,
        "series": [],
        "producto": null,
        "entroAlStock": false
      }
    ],
    "creado": "2026-11-03T15:20:11-05:00"
  }
}