API Reference

Compras

Documentos de compra recibidos. Soporta dos flujos: creación manual o importación del XML del proveedor (o del envoltorio SRI). El parser lxml extrae emisor, clave de acceso, número, fecha, subtotales por tarifa, IVA, total y las líneas — el cliente revisa y confirma con un POST.

Eventos

Cada compra emite compra.creada al persistirse. Más eventos (pagos, anulación) se agregan en fases 2.3 y siguientes.

Registrar una compra (manual)

POST /api/v1/compras — Crea una compra y sus detalles

Body

Parámetro	Tipo	Descripción
`total` required	number	Importe total del documento.
`proveedor_tipo_id` required	string	Tipo de identificación del proveedor (tabla SRI).
`proveedor_identificacion` required	string	RUC/cédula/doc. del proveedor.
`proveedor_razon_social` required	string	Razón social del proveedor.
`proveedor_direccion` optional	string	Dirección del proveedor.
`email` optional	string	Email del proveedor.
`tipo_doc` optional	string	Tipo de documento sustento. Default 01.
`numero_doc` required	string	Número del documento (15 dígitos, con/sin guiones).
`fecha_emision` required	datetime	Fecha de emisión (ISO 8601).
`clave_acceso` optional	string	Clave de acceso SRI (49 dígitos). UNIQUE por tenant.
`fecha_vencimiento` optional	date	Fecha de vencimiento del crédito.
`categoria` optional	string	Categoría del gasto.
`notas` optional	string	Notas internas.
`detalles` required	array	Líneas opcionales. Mismo shape que Factura.
`subtotal_0..exento, iva` optional	number	Subtotales por tarifa (modo sin líneas).
`xml_original` optional	string	XML original (si fue importada). Para auditoría.
`sucursal_id` optional	integer	Sucursal de trazabilidad.
`idempotency_key` optional	string	Idempotencia (también header Idempotency-Key).

Respuesta (201 Created)

{
  "id": 1,
  "tipo_doc": "01",
  "numero_doc": "001-001-000000001",
  "fecha_emision": "2026-07-01T10:00:00",
  "proveedor_razon_social": "PROVEEDOR S.A.",
  "proveedor_identificacion": "1798888888001",
  "total": 115.0,
  "estado_pago": "PENDIENTE",
  "categoria": "Servicios básicos",
  "detalles": [
    { "...": "..." }
  ]
}

Importar un XML (preview sin persistir)

POST /api/v1/compras/importar-xml — Recibe el XML (multipart) y devuelve un preview; NO persiste

Acepta tanto

El envoltorio SRI: <autorizacion><comprobante>...</autorizacion> con el comprobante embebido como CDATA.
El XML plano del ERP del proveedor: <factura id="comprobante">... directo.

Body: multipart/form-data

Parámetro	Tipo	Descripción
`file` required	file	Archivo .xml del comprobante.

Respuesta (200 OK)

{
  "tipo_doc": "01",
  "numero_doc": "001-001-000000099",
  "fecha_emision": "2026-07-01T10:00:00",
  "clave_acceso": "0103202601179888888800110010010000000991234567813",
  "proveedor_tipo_id": "04",
  "proveedor_identificacion": "1798888888001",
  "proveedor_razon_social": "PROVEEDOR S.A.",
  "subtotal_15": 100.0,
  "iva": 15.0,
  "total": 115.0,
  "detalles": [
    { "codigo_principal": "P1", "descripcion": "Servicio X", "cantidad": 1, "precio_unitario": 100, "tarifa_iva": 15, "iva_codigo": "4" }
  ],
  "proveedor_existe": true
}

Deduplicación por clave_acceso

Si reimportas el mismo XML, el backend detecta el duplicado por clave_acceso y devuelve la compra existente (200 OK) en vez de crear una nueva (201).

Listado

GET /api/v1/compras?q=opcional&estado_pago=opcional&include_inactivos=bool — Listado con búsqueda por RUC/razón social/número/clave

Obtener una compra

GET /api/v1/compras/{id} — Detalle completo, con líneas

Actualizar (PATCH)

PATCH /api/v1/compras/{id} — Edita categoría, notas, fecha_vencimiento, sucursal, líneas

Eliminar (baja lógica)

DELETE /api/v1/compras/{id} — Marca activo=False. NO borra físicamente.

Autocompletar categorías

GET /api/v1/compras/_meta/categorias — Lista las categorías distintas ya usadas por el tenant