Emitir factura de compra

POST /api/v1/facturas-compra

Emite una factura electrónica de compra (tipo 08), también llamada autofactura: el comprobante que la ley exige que emita el comprador cuando le compra a un proveedor de régimen especial — agricultores, pescadores artesanales, recolectores informales y otros regímenes que Hacienda no obliga a emitir su propia FE.

Es el único comprobante de la API que no documenta una venta del tenant. El tenant es quien lo emite, pero el objeto emisor que se envía en el body identifica al proveedor, no a un receptor del tenant.

En cuanto a asincronía funciona igual que POST /facturas: la respuesta es inmediata con estado procesando y el estado final llega por webhook o por polling a GET /facturas-compra/{clave}.

Autenticación y permisos

Headers

POST /api/v1/facturas-compra HTTP/1.1
Host: api.pos.lxsyscr.com
X-Api-Key: lxs_live_a1b2c3d4_001122...
Content-Type: application/json
Idempotency-Key: 9c2a1234-5678-4b5e-9c2a-4f1c8a8a2c4f
Accept: application/json

Request body

Ver FacturaCompraApiRequestDto para el schema completo.

Ejemplo — proveedor ya existente, línea del catálogo de compra:

{
  "idUsuario": 7,
  "emisor": { "idEmisor": 15 },
  "condicionVenta": "01",
  "medioPago": "01",
  "moneda": "CRC",
  "lineas": [
    { "idProducto": 8, "cantidad": 100 }
  ]
}

Ejemplo — proveedor nuevo (se da de alta) y línea ad-hoc:

{
  "idUsuario": 7,
  "emisor": {
    "identificacion": "1-0234-0567",
    "tipoIdentificacion": "01",
    "nombre": "Juan",
    "apellidos": "Pérez Solano",
    "correo": "juan.perez@correo.cr",
    "telefono": "88001122",
    "codigoActividadEmisor": "011101"
  },
  "condicionVenta": "01",
  "medioPago": "01",
  "moneda": "CRC",
  "comentario": "Compra de café en fruta — cosecha agosto",
  "lineas": [
    {
      "descripcion": "Café en fruta",
      "codigoCabys": "8511200000100",
      "unidadMedida": "Kg",
      "cantidad": 250,
      "precioUnitario": 450.00
    }
  ]
}

Respuestas

201 Created

HTTP/1.1 201 Created
Location: /api/v1/facturas-compra/50615012600310112345600100001080000000123456789012
Content-Type: application/json

{
  "clave": "50615012600310112345600100001080000000123456789012",
  "numeroConsecutivo": "00100001080000000123",
  "tipoDocumento": "08",
  "estadoHacienda": "procesando",
  "totalComprobante": 112500.00,
  "moneda": "CRC",
  "fechaEmision": "2026-08-05T14:10:00Z"
}

Es el mismo shape de FacturaApiResponseDto — no hay un DTO de respuesta distinto para compra.

400 Bad Request

{ "error": "Debe incluir al menos una línea." }

{ "error": "Debe indicar idEmisor o identificacion del proveedor." }

{ "error": "tipoIdentificacion y nombre son obligatorios para dar de alta al proveedor." }

{ "error": "descripcion y codigoCabys son obligatorios para dar de alta la línea." }

{ "error": "El teléfono del proveedor no tiene un formato válido." }

401 Unauthorized / 403 Forbidden

Mismo comportamiento que POST /facturas, con el scope facturas-compra:write.

{ "error": "La API key no tiene el scope requerido para esta operación." }

409 Conflict / 413 Payload Too Large / 429 Too Many Requests / 500 Internal Server Error

Idénticos a los de POST /facturas.

Reglas de negocio

• Tarifa 0% exenta. La factura de compra no lleva IVA, ni descuentos, ni exoneraciones, ni otros cargos — esos campos no deben enviarse y se ignoran si se incluyen. El totalComprobante es la suma simple de cantidad × precioUnitario de cada línea.
• El catálogo de líneas es propio y separado. lineas[].idProducto apunta al catálogo de factura de compra (producto_factura_compra), que no es el catálogo de inventario que usan las ventas. Un idProducto que existe en Ventas puede no existir aquí, y viceversa — no debe reutilizarse sin verificarlo previamente. Si no se dispone del id, debe enviarse descripcion + codigoCabys y la línea se resuelve o se crea: ver FacturaCompraApiLineaDto.
• Teléfono y correo del proveedor se validan y normalizan con las mismas reglas que el POS. Un formato inválido responde 400, no un comprobante emitido con datos basura.
• Hacienda valida la identificación del proveedor. Si la cédula no existe en su padrón, el comprobante se acepta de igual forma en el sistema del tenant (queda procesando → recibido), pero Hacienda lo rechaza. Si el proveedor es nuevo, debe verificarse la identificación antes de emitir.