Compras

Referencia detallada de los recursos de Compras de la API de YoFacturo: proveedores, gastos e insumos. Para cada recurso se documentan sus campos, los endpoints CRUD, los scopes necesarios y ejemplos de uso.

Todos los recursos comparten el mismo conjunto de endpoints CRUD y operaciones masivas. La autenticación se hace con el header X-API-Key y cada operación requiere el scope correspondiente: el sufijo :read para lectura y :write para escritura.

Proveedores

El recurso de Proveedores administra el padrón de proveedores de la cuenta: datos de contacto, información fiscal para facturación de compras y categorización. Es la base sobre la que se vinculan los gastos y los insumos.

Endpoint base: /api/v1/suppliers

Scopes: suppliers:read, suppliers:write

Campos

Campo	Tipo	Requerido	Notas
`name`	string	Sí	Nombre del proveedor. Entre 2 y 200 caracteres. Único campo obligatorio.
`email`	string	No	Correo electrónico del proveedor. Debe tener formato de email válido.
`phone`	string	No	Teléfono de contacto.
`tax_id`	string	No	Identificación fiscal (CUIT/CUIL). Hasta 50 caracteres.
`fiscal_info`	object	No	Datos fiscales para facturación: tipo_documento (integer), numero_documento (string), condicion_iva ("responsable_inscripto" \| "monotributo" \| "exento"), razon_social, domicilio_comercial, provincia, codigo_postal, pais.
`contact_name`	string	No	Nombre de la persona de contacto. Hasta 200 caracteres.
`address`	string \| object	No	Domicilio. Puede ser un string o un objeto con street, city, state, zip y country.
`status`	string	No	Estado del proveedor.
`category`	string	No	Categoría del proveedor.
`payment_terms`	string	No	Condiciones de pago acordadas.
`website`	string	No	Sitio web del proveedor.
`notes`	string	No	Notas u observaciones.
`tags`	array	No	Etiquetas para clasificar el proveedor.
`product_ids`	array	No	IDs de productos asociados a este proveedor.

Endpoints

Método	Endpoint	Descripción
`GET`	`/api/v1/suppliers/list/`	Listar registros (filtros y paginación)
`GET`	`/api/v1/suppliers/{id}/`	Obtener un registro por su ID
`POST`	`/api/v1/suppliers/`	Crear un registro
`PUT`	`/api/v1/suppliers/{id}/`	Actualizar un registro
`DELETE`	`/api/v1/suppliers/{id}/`	Eliminar un registro
`POST`	`/api/v1/suppliers/bulk/create/`	Crear varios registros en una sola llamada
`PUT`	`/api/v1/suppliers/bulk/update/`	Actualizar varios registros en una sola llamada
`POST`	`/api/v1/suppliers/bulk/delete/`	Eliminar varios registros en una sola llamada

Ejemplo — Petición

POST /api/v1/suppliers/
{
  "name": "Distribuidora del Sur S.A.",
  "email": "[email protected]",
  "phone": "+54 11 4555-1234",
  "tax_id": "30-71234567-9",
  "fiscal_info": {
    "tipo_documento": 80,
    "numero_documento": "30712345679",
    "condicion_iva": "responsable_inscripto",
    "razon_social": "Distribuidora del Sur S.A."
  },
  "contact_name": "Laura Gómez",
  "category": "mayorista",
  "payment_terms": "30 días",
  "tags": ["bebidas", "preferente"]
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0d1",
    "name": "Distribuidora del Sur S.A.",
    "email": "[email protected]",
    "phone": "+54 11 4555-1234",
    "tax_id": "30-71234567-9",
    "contact_name": "Laura Gómez",
    "category": "mayorista",
    "payment_terms": "30 días",
    "status": "active",
    "tags": ["bebidas", "preferente"]
  }
}

Gastos

El recurso de Gastos registra las erogaciones de la cuenta con su importe, alícuota de IVA y categoría. Permite llevar el control de egresos, asociarlos a un proveedor y conciliarlos con los comprobantes de compra.

Endpoint base: /api/v1/expenses

Scopes: expenses:read, expenses:write

Campos

Campo	Tipo	Requerido	Notas
`amount`	number	Sí	Importe del gasto. Mayor que 0 y menor que 1 billón.
`description`	string	Sí	Descripción del gasto. Entre 1 y 500 caracteres.
`tax_rate`	number	Sí	Alícuota de IVA (porcentaje AFIP). Valores válidos: 0, 2.5, 5, 10.5, 21, 27.
`category`	string	No	Categoría del gasto. Entre 1 y 100 caracteres. Soporta categorías personalizadas.
`date`	string	No	Fecha del gasto en formato YYYY-MM-DD.
`payment_method`	string	No	Método de pago utilizado.
`status`	string	No	Estado del gasto: "pending", "approved", "paid", "cancelled" o "refunded".
`vendor`	string	No	Nombre del proveedor asociado al gasto.
`receipt_url`	string	No	URL del comprobante o factura del gasto.
`recurring`	boolean	No	Indica si el gasto es recurrente.
`recurring_period`	string	No	Período de recurrencia (por ejemplo "monthly", "weekly").
`notes`	string	No	Notas adicionales.
`tags`	array	No	Etiquetas para clasificar el gasto.
`iva_items`	array	No	Desglose de IVA AFIP. Cada item con Id (código de alícuota: 3, 4, 5, 6, 8, 9), BaseImp (base imponible) e Importe (importe de IVA).

Endpoints

Método	Endpoint	Descripción
`GET`	`/api/v1/expenses/list/`	Listar registros (filtros y paginación)
`GET`	`/api/v1/expenses/{id}/`	Obtener un registro por su ID
`POST`	`/api/v1/expenses/`	Crear un registro
`PUT`	`/api/v1/expenses/{id}/`	Actualizar un registro
`DELETE`	`/api/v1/expenses/{id}/`	Eliminar un registro
`POST`	`/api/v1/expenses/bulk/create/`	Crear varios registros en una sola llamada
`PUT`	`/api/v1/expenses/bulk/update/`	Actualizar varios registros en una sola llamada
`POST`	`/api/v1/expenses/bulk/delete/`	Eliminar varios registros en una sola llamada

Ejemplo — Petición

POST /api/v1/expenses/
{
  "amount": 48500.00,
  "description": "Compra de insumos de oficina",
  "tax_rate": 21,
  "category": "insumos",
  "date": "2026-05-21",
  "payment_method": "transferencia",
  "status": "paid",
  "vendor": "Distribuidora del Sur S.A.",
  "tags": ["oficina"]
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f2b3c4d5e6f7a8b9c0d1e2",
    "amount": 48500.00,
    "description": "Compra de insumos de oficina",
    "tax_rate": 21,
    "category": "insumos",
    "date": "2026-05-21",
    "payment_method": "transferencia",
    "status": "paid",
    "vendor": "Distribuidora del Sur S.A.",
    "tags": ["oficina"]
  }
}

Insumos

El recurso de Insumos define los artículos que la cuenta compra de forma habitual, con su unidad de medida, precio unitario, proveedor e importe de gasto por defecto. Sirve para agilizar la carga de gastos recurrentes.

Endpoint base: /api/v1/supplies

Scopes: supplies:read, supplies:write

Campos

Campo	Tipo	Requerido	Notas
`name`	string	Sí	Nombre del insumo. Entre 1 y 200 caracteres.
`default_amount`	number	Sí	Importe de gasto por defecto para este insumo. Mayor o igual a 0.
`description`	string	No	Descripción del insumo. Hasta 500 caracteres.
`supplier_id`	string	No	ID del proveedor del insumo.
`unit`	string	No	Unidad de medida (unidad, caja, kg, etc.). Hasta 50 caracteres.
`unit_price`	number \| null	No	Precio por unidad. Mayor o igual a 0.
`tags`	array	No	Etiquetas para clasificar el insumo.
`status`	string	No	Estado del insumo.

Endpoints

Método	Endpoint	Descripción
`GET`	`/api/v1/supplies/list/`	Listar registros (filtros y paginación)
`GET`	`/api/v1/supplies/{id}/`	Obtener un registro por su ID
`POST`	`/api/v1/supplies/`	Crear un registro
`PUT`	`/api/v1/supplies/{id}/`	Actualizar un registro
`DELETE`	`/api/v1/supplies/{id}/`	Eliminar un registro
`POST`	`/api/v1/supplies/bulk/create/`	Crear varios registros en una sola llamada
`PUT`	`/api/v1/supplies/bulk/update/`	Actualizar varios registros en una sola llamada
`POST`	`/api/v1/supplies/bulk/delete/`	Eliminar varios registros en una sola llamada

Ejemplo — Petición

POST /api/v1/supplies/
{
  "name": "Resma de papel A4",
  "default_amount": 3200.00,
  "description": "Resma de 500 hojas, 75 g/m²",
  "supplier_id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "unit": "caja",
  "unit_price": 3200.00,
  "tags": ["oficina", "papeleria"]
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f3c4d5e6f7a8b9c0d1e2f3",
    "name": "Resma de papel A4",
    "default_amount": 3200.00,
    "description": "Resma de 500 hojas, 75 g/m²",
    "supplier_id": "66f1a2b3c4d5e6f7a8b9c0d1",
    "unit": "caja",
    "unit_price": 3200.00,
    "status": "active",
    "tags": ["oficina", "papeleria"]
  }
}