YoFacturo
Documentación de la API
API

Documentación para desarrolladores

Recursos y scopes

La API expone 29 recursos del sistema, agrupados por área. Cada recurso se controla con scopes: permisos que definen qué puede leer y escribir cada API token.

Scopes

Un scope es un permiso. Cada API token lleva un conjunto de scopes y solo puede hacer lo que esos scopes habilitan. El formato de un scope es recurso:accion, donde la acción es read (leer) o write (crear, actualizar y eliminar). Por ejemplo: products:read o customers:write.

Al hacer una petición, la API verifica que el token tenga el scope necesario para ese endpoint y método. Si el scope falta, la API responde con 403. Te recomendamos aplicar el principio de mínimo privilegio: otorgá a cada token solo los scopes que su integración realmente usa.

El endpoint GET /api/v1/api-tokens/scopes devuelve la lista actualizada de scopes vigentes con su descripción. Este endpoint se consulta desde el panel web, con la sesión del navegador; no forma parte de la API de integraciones y no se accede con un API token.

Recursos disponibles

La API cubre 29 recursos (57 scopes), agrupados en 7 áreas. Cada recurso tiene un scope de lectura y uno de escritura, salvo Estadísticas, que es el único recurso de solo lectura: solo existe stats:read. Todas las rutas cuelgan de https://api.yo-facturo.com/api/v1/.

Catálogo

Ver detalle →
RecursoEndpoint baseScopes
Productos/api/v1/products
products:read
products:write
Servicios/api/v1/services
services:read
services:write
Alquileres/api/v1/rentals
rentals:read
rentals:write
Categorías/api/v1/categories
categories:read
categories:write
Variantes y opciones/api/v1/products/options
product_options:read
product_options:write
Perfiles de precio/api/v1/products/pricing-profiles
pricing_profiles:read
pricing_profiles:write
Promociones/api/v1/promotions
promotions:read
promotions:write

Ventas

Ver detalle →
RecursoEndpoint baseScopes
Ventas/api/v1/sales
sales:read
sales:write
Punto de venta/api/v1/pos
pos:read
pos:write
Caja registradora/api/v1/cash_register
cash_register:read
cash_register:write
Metas de venta/api/v1/goals
sales_goals:read
sales_goals:write
Presupuestos/api/v1/budgets
budgets:read
budgets:write
Pedidos/api/v1/orders
orders:read
orders:write

Facturación

Ver detalle →
RecursoEndpoint baseScopes
Comprobantes AFIP/ARCA — ver guía completa en Facturación AFIP/api/v1/bill/receipts
invoices:read
invoices:write
Facturas de compra/api/v1/received_invoices
received_invoices:read
received_invoices:write
Remitos/api/v1/delivery_notes
delivery_notes:read
delivery_notes:write

Compras

Ver detalle →
RecursoEndpoint baseScopes
Proveedores/api/v1/suppliers
suppliers:read
suppliers:write
Gastos/api/v1/expenses
expenses:read
expenses:write
Insumos/api/v1/supplies
supplies:read
supplies:write

Clientes

Ver detalle →
RecursoEndpoint baseScopes
Clientes/api/v1/customers
customers:read
customers:write
Cuenta corriente/api/v1/current-accounts
current_accounts:read
current_accounts:write
CRM/api/v1/crm-tasks
crm:read
crm:write
Beneficios/api/v1/rewards
benefits:read
benefits:write

Operaciones

Ver detalle →
RecursoEndpoint baseScopes
Turnos y citas/api/v1/appointments
appointments:read
appointments:write
Contratos/api/v1/contracts
contracts:read
contracts:write
Métodos de pago/api/v1/payment_methods
payment_methods:read
payment_methods:write
Envíos/api/v1/shipping
shipping:read
shipping:write

Contabilidad y reportes

Ver detalle →
RecursoEndpoint baseScopes
Contabilidad/api/v1/accounting
accounting:read
accounting:write
Estadísticas/api/v1/stats
stats:read
Solo lectura

Los recursos de catálogo, ventas, compras y clientes siguen el patrón CRUD estándar (/list/, /{id}/, etc. — ver Convenciones). Los módulos de Facturación, Contabilidad y Estadísticas exponen endpoints específicos de su dominio bajo el endpoint base indicado.

Operaciones — endpoint por endpoint

Los recursos CRUD comparten estas operaciones; reemplazá products por el recurso que quieras (customers, sales, etc.). Las respuestas exitosas siempre incluyen success: true y los datos bajo la clave data.

Listar — GET /api/v1/products/list/?per_page=20&page=1

Devuelve una página de recursos con metadatos de paginación.

Petición:

GET /api/v1/products/list/?per_page=20&page=1
Headers: X-API-Key: TU_TOKEN

Respuesta:

{
  "success": true,
  "data": {
    "items": [ { "_id": "...", "name": "Remera blanca" } ],
    "total": 134,
    "page": 1,
    "per_page": 20,
    "total_pages": 7,
    "has_next": true,
    "has_prev": false
  }
}

Obtener uno — GET /api/v1/products/{id}/

Devuelve un único recurso identificado por su id.

Petición:

GET /api/v1/products/6a0f0967cdefb0d115b45b3c/
Headers: X-API-Key: TU_TOKEN

Respuesta:

{
  "success": true,
  "data": {
    "_id": "6a0f0967cdefb0d115b45b3c",
    "name": "Remera blanca",
    "base_price": 8500.0,
    "status": "active"
  }
}

Crear — POST /api/v1/products/

Crea un recurso nuevo con los datos enviados en el cuerpo.

Petición:

POST /api/v1/products/
Headers: X-API-Key: TU_TOKEN, Content-Type: application/json
Body:
{
  "name": "Remera blanca talle M",
  "base_price": 8500,
  "description": "Algodón 100%"
}

Respuesta:

{
  "success": true,
  "data": {
    "_id": "6a0f0967cdefb0d115b45b3c",
    "name": "Remera blanca talle M",
    "base_price": 8500.0,
    "status": "draft",
    "created_at": "2026-05-21T13:32:23Z"
  }
}

Actualizar — PUT /api/v1/products/{id}/

Actualiza los campos enviados de un recurso existente.

Petición:

PUT /api/v1/products/6a0f0967cdefb0d115b45b3c/
Headers: X-API-Key: TU_TOKEN, Content-Type: application/json
Body:
{
  "base_price": 9200
}

Respuesta:

{
  "success": true,
  "data": {
    "_id": "6a0f0967cdefb0d115b45b3c",
    "base_price": 9200.0
  }
}

Eliminar — DELETE /api/v1/products/{id}/

Elimina el recurso identificado por su id.

Petición:

DELETE /api/v1/products/6a0f0967cdefb0d115b45b3c/
Headers: X-API-Key: TU_TOKEN

Respuesta:

{
  "success": true,
  "data": {
    "deleted": true,
    "id": "6a0f0967cdefb0d115b45b3c"
  }
}

Crear en lote — POST /api/v1/products/bulk/create/

Crea varios recursos en una sola petición y reporta el resultado de cada uno.

Petición:

POST /api/v1/products/bulk/create/
Headers: X-API-Key: TU_TOKEN, Content-Type: application/json
Body:
{
  "items": [
    { "name": "Producto A", "base_price": 100 },
    { "name": "Producto B", "base_price": 200 }
  ]
}

Respuesta:

{
  "success": true,
  "data": {
    "created": [
      { "index": 0, "success": true, "id": "..." },
      { "index": 1, "success": true, "id": "..." }
    ],
    "total": 2,
    "success_count": 2,
    "error_count": 0
  }
}

Actualizar en lote — PUT /api/v1/products/bulk/update/

Actualiza varios recursos en una sola petición y reporta el resultado de cada uno.

Petición:

PUT /api/v1/products/bulk/update/
Headers: X-API-Key: TU_TOKEN, Content-Type: application/json
Body:
{
  "updates": [
    { "id": "...", "base_price": 150 },
    { "id": "...", "base_price": 250 }
  ]
}

Respuesta:

{
  "success": true,
  "data": {
    "updated": [ ... ],
    "total": 2,
    "success_count": 2,
    "error_count": 0
  }
}

Eliminar en lote — POST /api/v1/products/bulk/delete/

Elimina varios recursos en una sola petición y reporta el resultado de cada uno.

Petición:

POST /api/v1/products/bulk/delete/
Headers: X-API-Key: TU_TOKEN, Content-Type: application/json
Body:
{
  "ids": [ "...", "..." ]
}

Respuesta:

{
  "success": true,
  "data": {
    "deleted": [ ... ],
    "total": 2,
    "success_count": 2,
    "error_count": 0
  }
}