API

Documentación para desarrolladores

Recursos: Ventas

Ventas

Referencia de los recursos de Ventas de la API: ventas, punto de venta, caja registradora, metas de venta, presupuestos y pedidos. Para cada recurso se documentan sus campos, sus endpoints y los scopes necesarios.

Todos los endpoints están bajo la URL base https://api.yo-facturo.com y se autentican con el header X-API-Key. Cada recurso expone los endpoints CRUD estándar (crear, obtener, actualizar, eliminar, listar y operaciones en lote) más los endpoints específicos que se detallan en cada sección. Las respuestas tienen el formato { success, data }.

Ventas

El recurso de ventas registra las operaciones de venta del comercio: ítems vendidos, cliente, importes, impuestos, descuentos y datos de envío. Una venta puede generar opcionalmente una factura electrónica.

Endpoint base: /api/v1/sales

Scopes: sales:read, sales:write

Campos

Campo	Tipo	Requerido	Notas
`items`	array	Sí	Líneas de la venta. Mínimo 1 ítem. Cada ítem incluye publication_id, publication_type, name, quantity, price.
`customer`	string	No	ID del cliente o el valor "no-customer" para venta sin cliente.
`customer_id`	string	No	ID del cliente (forma alternativa a customer).
`payment_method`	string	No	Método de pago de la venta.
`payment`	object	No	Información del pago (método, estado, montos parciales).
`subtotal`	number	No	Subtotal de la venta. Mínimo 0.
`total`	number	No	Importe total de la venta. Mínimo 0.
`tax_type`	string	No	Tipo de impuesto aplicado.
`tax_rate`	number	No	Alícuota de impuesto en porcentaje. Entre 0 y 100.
`discount_type`	string	No	Tipo de descuento aplicado.
`discount_rate`	number	No	Descuento en porcentaje. Entre 0 y 100.
`status`	string	No	Estado de la venta (pending, completed, cancelled, refunded).
`notes`	string	No	Notas u observaciones de la venta.
`sale_origin`	string	No	Origen de la venta. Valores: manual, pos, ecommerce, order, budget, contract, rental_booking, appointment, mercadolibre, tiendanube, shopify, subscription.
`generate_invoice`	boolean	No	Si es true, se genera una factura para la venta tras crearse.
`requires_shipping`	boolean	No	Indica si la venta requiere envío.
`shipping_method`	string	No	Método de envío.
`shipping_cost`	number	No	Costo de envío. Mínimo 0.
`shipping_address`	object	No	Domicilio de envío.
`pricing_options_summary`	object	No	Resumen de opciones de precio aplicadas.

Endpoints

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

Ejemplo — Petición

POST /api/v1/sales/
{
  "customer": "no-customer",
  "items": [
    {
      "publication_id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "publication_type": "product",
      "name": "Producto de ejemplo",
      "quantity": 2,
      "price": 7500.00
    }
  ],
  "payment_method": "cash",
  "subtotal": 15000.00,
  "tax_rate": 21,
  "total": 18150.00,
  "sale_origin": "manual",
  "generate_invoice": false
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0d2",
    "items": [
      { "publication_id": "66f1a2b3c4d5e6f7a8b9c0d1", "name": "Producto de ejemplo", "quantity": 2, "price": 7500.00 }
    ],
    "subtotal": 15000.00,
    "tax_rate": 21,
    "total": 18150.00,
    "status": "pending",
    "sale_origin": "manual",
    "invoice_number": "VTA-20260521-0087"
  }
}

Punto de venta (POS)

El recurso de punto de venta administra las terminales de venta del comercio (cajas físicas o virtuales). Cada terminal tiene una ubicación, una configuración y usuarios asignados, y permite registrar ventas y gestionar sesiones.

Endpoint base: /api/v1/pos

Scopes: pos:read, pos:write

Campos

Campo	Tipo	Requerido	Notas
`name`	string	Sí	Nombre de la terminal de punto de venta. Mínimo 1 carácter.
`location`	string	No	Ubicación física de la terminal.
`description`	string	No	Descripción de la terminal.
`status`	string	No	Estado de la terminal. Valores: active, inactive, maintenance.
`configuration`	object	No	Configuración de la terminal.
`assigned_users`	array	No	IDs de los usuarios asignados a la terminal.

Endpoints

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

Endpoints específicos del punto de venta:

Método	Endpoint	Descripción
`POST`	`/api/v1/pos/{id}/sale/`	Registrar una venta desde una terminal
`GET`	`/api/v1/pos/sessions/{pos_terminal_id}/active`	Obtener la sesión activa de una terminal
`PUT`	`/api/v1/pos/sessions/{pos_terminal_id}/active`	Actualizar la sesión activa de una terminal
`DELETE`	`/api/v1/pos/sessions/{pos_terminal_id}/active`	Cerrar la sesión activa de una terminal

Ejemplo — Petición

POST /api/v1/pos/
{
  "name": "Caja principal",
  "location": "Sucursal Centro",
  "status": "active",
  "assigned_users": ["66f1a2b3c4d5e6f7a8b9c0b1"]
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0b2",
    "name": "Caja principal",
    "location": "Sucursal Centro",
    "status": "active",
    "assigned_users": ["66f1a2b3c4d5e6f7a8b9c0b1"]
  }
}

Caja registradora

El recurso de caja registradora gestiona la apertura, los movimientos de efectivo y el cierre de caja de cada terminal. Permite registrar ingresos y egresos, obtener la conciliación y generar el reporte X.

Endpoint base: /api/v1/cash_register

Scopes: cash_register:read, cash_register:write

Campos del cuerpo para abrir una caja. Los datos completos de una caja (saldo, movimientos, estado) se obtienen con un GET.

Campos

Campo	Tipo	Requerido	Notas
`pos_terminal_id`	string	Sí	ID de la terminal de punto de venta asociada. Mínimo 1 carácter.
`initial_amount`	number	Sí	Monto inicial de apertura de la caja. Mínimo 0.

Endpoints

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

Endpoints específicos de la caja registradora:

Método	Endpoint	Descripción
`POST`	`/api/v1/cash_register/open/`	Abrir una caja registradora
`POST`	`/api/v1/cash_register/{id}/close/`	Cerrar una caja registradora
`POST`	`/api/v1/cash_register/{id}/movement/`	Registrar un movimiento de efectivo (ingreso/egreso)
`GET`	`/api/v1/cash_register/{id}/reconciliation/`	Obtener la conciliación de la caja
`GET`	`/api/v1/cash_register/{id}/x_report/`	Obtener el reporte X de la caja
`GET`	`/api/v1/cash_register/status/{pos_terminal_id}/`	Consultar el estado de caja de una terminal

Ejemplo — Petición

POST /api/v1/cash_register/open/
{
  "pos_terminal_id": "66f1a2b3c4d5e6f7a8b9c0b2",
  "initial_amount": 10000.00
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0c1",
    "pos_terminal_id": "66f1a2b3c4d5e6f7a8b9c0b2",
    "initial_amount": 10000.00,
    "status": "open",
    "opened_at": "2026-05-21T09:00:00Z"
  }
}

Metas de venta

El recurso de metas de venta permite definir objetivos comerciales (facturación, cantidad, clientes, ticket promedio, etc.) por período, asignarlos a un equipo y hacer seguimiento de su progreso e hitos.

Endpoint base: /api/v1/goals

Scopes: sales_goals:read, sales_goals:write

Campos

Campo	Tipo	Requerido	Notas
`name`	string	Sí	Nombre de la meta. Entre 1 y 200 caracteres.
`goal_type`	string	Sí	Tipo de meta. Valores: revenue, quantity, items, customers, average_ticket, product_category, service_bookings, specific_publication, custom.
`target_value`	number	Sí	Valor objetivo a alcanzar. Mínimo 0.
`period`	string	Sí	Período de la meta. Valores: daily, weekly, biweekly, monthly, quarterly, yearly.
`start_date`	string	Sí	Fecha de inicio del período.
`end_date`	string	Sí	Fecha de fin del período.
`description`	string	No	Descripción de la meta.
`status`	string	No	Estado de la meta. Valores: active, paused, completed, failed, cancelled, draft.
`team_members`	array	No	IDs de los miembros del equipo asignados a la meta.
`tags`	array	No	Etiquetas de la meta.
`milestones`	array	No	Hitos intermedios de la meta.
`notifications_enabled`	boolean	No	Habilita las notificaciones de progreso de la meta.

Endpoints

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

Ejemplo — Petición

POST /api/v1/goals/
{
  "name": "Facturación mayo 2026",
  "goal_type": "revenue",
  "target_value": 5000000,
  "period": "monthly",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "status": "active",
  "notifications_enabled": true
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0e1",
    "name": "Facturación mayo 2026",
    "goal_type": "revenue",
    "target_value": 5000000,
    "period": "monthly",
    "start_date": "2026-05-01",
    "end_date": "2026-05-31",
    "status": "active",
    "current_value": 0
  }
}

Presupuestos

El recurso de presupuestos permite crear cotizaciones para los clientes con ítems, validez, términos y condiciones. Un presupuesto puede convertirse en una venta una vez aceptado por el cliente.

Endpoint base: /api/v1/budgets

Scopes: budgets:read, budgets:write

Campos

Campo	Tipo	Requerido	Notas
`items`	array	Sí	Líneas del presupuesto. Mínimo 1 ítem. Cada ítem requiere publication_id, publication_type (product, services o rental) y quantity.
`customer`	object	Sí	Datos del cliente. Requiere customer_id, name e email.
`valid_until`	string	No	Fecha hasta la que el presupuesto es válido.
`valid_days`	number	No	Cantidad de días de validez. Entre 1 y 365.
`notes`	string	No	Notas del presupuesto. Máximo 1000 caracteres.
`terms_and_conditions`	string	No	Términos y condiciones. Máximo 2000 caracteres.
`reference`	string	No	Referencia interna. Máximo 200 caracteres.
`custom_fields`	object	No	Campos personalizados del presupuesto.
`tax_rate`	number	No	Alícuota de impuesto en porcentaje. Entre 0 y 100.
`discount_rate`	number	No	Descuento en porcentaje. Entre 0 y 100.

Endpoints

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

El presupuesto también ofrece el endpoint POST /api/v1/budgets/{id}/convert/ para convertirlo en una venta.

Ejemplo — Petición

POST /api/v1/budgets/
{
  "items": [
    {
      "publication_id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "publication_type": "product",
      "name": "Producto de ejemplo",
      "quantity": 3,
      "price": 7500.00
    }
  ],
  "customer": {
    "customer_id": "66f1a2b3c4d5e6f7a8b9c0a1",
    "name": "Cliente de ejemplo",
    "email": "[email protected]"
  },
  "valid_days": 30,
  "tax_rate": 21
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0a2",
    "items": [
      { "publication_id": "66f1a2b3c4d5e6f7a8b9c0d1", "name": "Producto de ejemplo", "quantity": 3, "price": 7500.00 }
    ],
    "customer": { "customer_id": "66f1a2b3c4d5e6f7a8b9c0a1", "name": "Cliente de ejemplo" },
    "tax_rate": 21,
    "status": "draft"
  }
}

Pedidos

El recurso de pedidos gestiona las órdenes de compra a proveedores: ítems solicitados, costos, fecha de entrega esperada y estado del pedido y de su pago.

Endpoint base: /api/v1/orders

Scopes: orders:read, orders:write

Campos

Campo	Tipo	Requerido	Notas
`supplier_id`	string	Sí	ID del proveedor. Mínimo 1 carácter.
`items`	array	Sí	Líneas del pedido. Mínimo 1 ítem. Cada ítem requiere product_id, product_name, quantity y unit_price.
`tax_amount`	number	No	Importe de impuestos. Mínimo 0.
`shipping_cost`	number	No	Costo de envío. Mínimo 0.
`expected_delivery_date`	string	No	Fecha estimada de entrega.
`notes`	string	No	Notas del pedido. Máximo 1000 caracteres.
`shipping_address`	object	No	Domicilio de entrega.
`payment_terms`	string	No	Condiciones de pago acordadas con el proveedor.
`status`	string	No	Estado del pedido. Valores: draft, pending, confirmed, shipped, delivered, completed, cancelled, refunded.
`payment_status`	string	No	Estado de pago. Valores: pending, paid, partial, overdue, cancelled.

Endpoints

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

Ejemplo — Petición

POST /api/v1/orders/
{
  "supplier_id": "66f1a2b3c4d5e6f7a8b9c0f1",
  "items": [
    {
      "product_id": "66f1a2b3c4d5e6f7a8b9c0f2",
      "product_name": "Insumo de ejemplo",
      "quantity": 50,
      "unit_price": 1200.00
    }
  ],
  "tax_amount": 12600.00,
  "expected_delivery_date": "2026-06-05",
  "status": "pending",
  "payment_status": "pending"
}

Ejemplo — Respuesta

{
  "success": true,
  "data": {
    "_id": "66f1a2b3c4d5e6f7a8b9c0f3",
    "supplier_id": "66f1a2b3c4d5e6f7a8b9c0f1",
    "items": [
      { "product_id": "66f1a2b3c4d5e6f7a8b9c0f2", "product_name": "Insumo de ejemplo", "quantity": 50, "unit_price": 1200.00 }
    ],
    "tax_amount": 12600.00,
    "status": "pending",
    "payment_status": "pending"
  }
}

YoFacturo

Ventas

Ventas

Campos

Endpoints

Ejemplo — Petición

Ejemplo — Respuesta

Punto de venta (POS)

Campos

Endpoints

Ejemplo — Petición

Ejemplo — Respuesta

Caja registradora

Campos

Endpoints

Ejemplo — Petición

Ejemplo — Respuesta

Metas de venta

Campos

Endpoints

Ejemplo — Petición

Ejemplo — Respuesta

Presupuestos

Campos

Endpoints

Ejemplo — Petición

Ejemplo — Respuesta

Pedidos

Campos

Endpoints

Ejemplo — Petición

Ejemplo — Respuesta