API

Documentación para desarrolladores

Recursos: Compras

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"]
  }
}

Consumos de insumos

Registra la salida de stock de uno o más insumos (por ejemplo, para producción interna) sin generar un gasto: el gasto ya se imputó cuando se compró el insumo. Un consumo es inmutable una vez confirmado —no hay endpoint de edición—; para corregirlo, se revierte (repone el stock con movimientos compensatorios) y se registra uno nuevo si hace falta.

Endpoint base: /api/v1/supply-consumptions

Scopes: supplies:read, supplies:write

Campos

Body de POST /api/v1/supply-consumptions/:

Campo	Tipo	Requerido	Notas
`items`	array	Sí	Líneas del consumo. Mínimo 1 elemento (ver tabla de campos del item).
`consumption_date`	string (fecha)	No	Fecha del consumo.
`customer_id`	string \| null	No	ID del cliente asociado al consumo, si corresponde.
`reference`	string	No	Referencia libre. Hasta 200 caracteres.
`notes`	string	No	Notas internas. Hasta 1000 caracteres.

Cada elemento del array items:

Campo	Tipo	Requerido	Notas
`supply_id`	string	Sí	ID del insumo a consumir.
`quantity`	número	Sí	Cantidad a descontar. Debe ser mayor que 0.
`notes`	string	No	Notas de la línea. Hasta 500 caracteres.

Endpoints

A diferencia de Proveedores, Gastos e Insumos, este recurso no expone edición ni operaciones masivas: no hay PUT ni endpoints /bulk/*.

Método	Endpoint	Descripción
`GET`	`/api/v1/supply-consumptions/list/`	Listar los consumos de insumos (con filtros y paginación)
`GET`	`/api/v1/supply-consumptions/{id}/`	Obtener un consumo por su ID
`POST`	`/api/v1/supply-consumptions/`	Registrar un consumo (descuenta stock de cada insumo del array items)
`DELETE`	`/api/v1/supply-consumptions/{id}/`	Eliminar un consumo (solo el autor, dentro de una ventana de 24 horas)

Ejemplo — Petición

POST /api/v1/supply-consumptions/
{
  "consumption_date": "2026-07-04",
  "reference": "Producción lote #58",
  "items": [
    {
      "supply_id": "66f3c4d5e6f7a8b9c0d1e2f3",
      "quantity": 5,
      "notes": "Uso en línea de producción 2"
    }
  ]
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "7a8b9c0d1e2f3a4b5c6d7e8f",
    "consumption_date": "2026-07-04",
    "items": [
      {
        "supply_id": "66f3c4d5e6f7a8b9c0d1e2f3",
        "supply_name": "Resma de papel A4",
        "quantity": 5,
        "unit": "caja",
        "unit_cost": 3200.00,
        "subtotal": 16000.00,
        "notes": "Uso en línea de producción 2"
      }
    ],
    "reference": "Producción lote #58",
    "notes": "",
    "total_cost": 16000.00,
    "status": "confirmed",
    "customer_name": "",
    "created_at": "2026-07-04T15:20:00",
    "updated_at": "2026-07-04T15:20:00",
    "created_by": "[email protected]"
  }
}

Listar consumos

curl "https://api.yo-facturo.com/api/v1/supply-consumptions/list/?page=1&limit=20" \
  -H "X-API-Key: TU_TOKEN"

Revertir un consumo

POST /{id}/revert repone el stock de cada insumo del consumo con movimientos compensatorios y marca el consumo como reverted. Este endpoint no acepta API token: a diferencia del resto de este recurso, requiere una sesión de usuario logueado en el panel (no tiene api_key_scopes configurado), así que no es invocable desde una integración externa con X-API-Key.

Forma de la respuesta (llamado desde el panel, no desde la API pública):

{
  "success": true,
  "message": "Consumption reverted successfully",
  "data": {
    "_id": "7a8b9c0d1e2f3a4b5c6d7e8f",
    "status": "reverted",
    "reverted_at": "2026-07-04T16:05:00",
    "reverted_by": "[email protected]",
    "total_cost": 16000.00
  }
}