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 agrupados en 7 áreas; la tabla «Todos los permisos (scopes)» de más abajo lista los 73 scopes vigentes. 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.

Todos los permisos (scopes)

Esta es la lista completa de scopes que podés asignar a un API token. Cada fila indica el grupo, el scope y qué permite. Los scopes :read son de solo lectura y los :write permiten crear, modificar y eliminar; scim:provision y shipping:fulfill tienen su propia acción. Asigná a cada token solo los que su integración necesita.

GrupoScopeQué permite
Productosproducts:readLeer productos
Productosproducts:writeCrear, actualizar y eliminar productos
Serviciosservices:readLeer servicios
Serviciosservices:writeCrear, actualizar y eliminar servicios
Alquileresrentals:readLeer alquileres
Alquileresrentals:writeCrear, actualizar y eliminar alquileres
Categoríascategories:readLeer categorías
Categoríascategories:writeCrear, actualizar y eliminar categorías
Variantes y opcionesproduct_options:readLeer variantes y opciones de producto
Variantes y opcionesproduct_options:writeCrear, actualizar y eliminar variantes y opciones
Perfiles de preciopricing_profiles:readLeer perfiles de precio
Perfiles de preciopricing_profiles:writeCrear, actualizar y eliminar perfiles de precio
Promocionespromotions:readLeer promociones
Promocionespromotions:writeCrear, actualizar y eliminar promociones
Ventassales:readLeer ventas
Ventassales:writeCrear, actualizar y eliminar ventas
Punto de ventapos:readLeer terminales y sesiones de punto de venta
Punto de ventapos:writeOperar el punto de venta
Caja registradoracash_register:readLeer cajas y movimientos
Caja registradoracash_register:writeOperar la caja registradora
Metas de ventasales_goals:readLeer metas de venta
Metas de ventasales_goals:writeCrear, actualizar y eliminar metas de venta
Presupuestosbudgets:readLeer presupuestos
Presupuestosbudgets:writeCrear, actualizar y eliminar presupuestos
Pedidosorders:readLeer pedidos
Pedidosorders:writeCrear, actualizar y eliminar pedidos
Facturación AFIPinvoices:readLeer comprobantes AFIP
Facturación AFIPinvoices:writeEmitir y anular comprobantes AFIP
Facturas de comprareceived_invoices:readLeer facturas de compra
Facturas de comprareceived_invoices:writeCrear, actualizar y eliminar facturas de compra
Remitosdelivery_notes:readLeer remitos
Remitosdelivery_notes:writeCrear, actualizar y eliminar remitos
Proveedoressuppliers:readLeer proveedores
Proveedoressuppliers:writeCrear, actualizar y eliminar proveedores
Gastosexpenses:readLeer gastos
Gastosexpenses:writeCrear, actualizar y eliminar gastos
Insumossupplies:readLeer insumos y consumos
Insumossupplies:writeCrear, actualizar y eliminar insumos y consumos
Clientescustomers:readLeer clientes
Clientescustomers:writeCrear, actualizar y eliminar clientes
Cuenta corrientecurrent_accounts:readLeer cuentas corrientes y movimientos
Cuenta corrientecurrent_accounts:writeRegistrar pagos y movimientos de cuenta corriente
CRMcrm:readLeer CRM (pipeline, tareas, segmentos, mensajería)
CRMcrm:writeGestionar CRM (pipeline, tareas, segmentos, mensajería)
Beneficiosbenefits:readLeer programa de beneficios y recompensas
Beneficiosbenefits:writeGestionar beneficios y recompensas
Cuentas mayoristasbuyer_orgs:readLeer cuentas mayoristas/compradoras
Cuentas mayoristasbuyer_orgs:writeCrear, actualizar y eliminar cuentas mayoristas/compradoras
Listas de precioprice_lists:readLeer listas de precio por cliente o grupo
Listas de precioprice_lists:writeCrear, actualizar y eliminar listas de precio
Turnos y citasappointments:readLeer turnos y citas
Turnos y citasappointments:writeCrear, actualizar y eliminar turnos y citas
Contratoscontracts:readLeer contratos
Contratoscontracts:writeCrear, actualizar y eliminar contratos
Métodos de pagopayment_methods:readLeer métodos de pago
Métodos de pagopayment_methods:writeCrear, actualizar y eliminar métodos de pago
Envíosshipping:readLeer envíos, repartidores y flota
Envíosshipping:writeGestionar envíos, repartidores y flota
Envíosshipping:fulfillPreparar envíos (picking, bultos, listo para despacho)
Servicio en campofield_service:readLeer órdenes de trabajo y formularios de campo
Servicio en campofield_service:writeGestionar órdenes de trabajo y formularios de campo
Mesasmesas:readLeer salón, mesas, pedidos y comandas de Mesas
Mesasmesas:writeGestionar salón, mesas, pedidos, comandas y cierre de Mesas
Contabilidadaccounting:readLeer contabilidad, IVA, retenciones y reportes fiscales
Contabilidadaccounting:writeGestionar contabilidad, IVA, retenciones y datos fiscales
Estadísticasstats:readLeer estadísticas y métricas del negocio
Aprovisionamiento SCIMscim:provisionAprovisionar y desaprovisionar usuarios vía SCIM 2.0 (Okta, Azure AD)
Webhooks salienteswebhooks:readLeer endpoints de webhooks salientes y su historial de entregas
Webhooks salienteswebhooks:writeCrear y eliminar endpoints de webhooks salientes
Contribuyentes (cuenta API partner)taxpayers:readLeer los contribuyentes (CUITs) de una cuenta API partner
Contribuyentes (cuenta API partner)taxpayers:writeRegistrar, actualizar y dar de baja contribuyentes (CUITs) de una cuenta API partner
Miembros del equipomembers:readLeer los miembros del equipo de la cuenta
Miembros del equipomembers:writeCrear, editar y eliminar miembros del equipo (no puede otorgar permisos que el titular no tenga)

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