Ventas - Sistema de Facturación Electrónica SUNAT

GET /api/ventas

Lista todas las ventas de la empresa activa.

Autenticación

Requiere autenticación con token Bearer y permiso ventas.view.

Parámetros de Consulta

No requiere parámetros.

Respuesta

success

boolean

Indica si la operación fue exitosa

ventas

array

Lista de ventas

Show Estructura

id_venta

integer

ID único de la venta

id_tido

integer

Tipo de documento (1: Boleta, 2: Factura, 6: Nota de Venta)

serie

string

Serie del comprobante (ej: F001, B001)

numero

integer

Número correlativo del comprobante

fecha_emision

string

Fecha de emisión (formato: YYYY-MM-DD)

cliente

object

Datos del cliente

Show Propiedades

documento

string

DNI o RUC del cliente

datos

string

Nombre o razón social del cliente

tipo_documento

object

abreviatura

string

Abreviatura del tipo de documento

subtotal

number

Base imponible (sin IGV)

igv

number

Monto del IGV

total

number

Total de la venta

tipo_moneda

string

Moneda (PEN o USD)

estado

string

Estado de la venta (1: Activa, 2: Anulada, 3: Vendida)

estado_sunat

string

Estado en SUNAT (0: Pendiente, 1: Enviado)

nombre_xml

string

Nombre del archivo XML generado

cdr_url

string

Ruta del CDR (Constancia de Recepción de SUNAT)

afecta_stock

boolean

Indica si afectó el stock

stock_real_descontado

boolean

Indica si se descontó del almacén real

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/ventas" \
  -H "Authorization: Bearer {token}"

POST /api/ventas

Crea una nueva venta, factura o boleta.

Autenticación

Requiere autenticación con token Bearer y permiso ventas.create.

Parámetros del Body

id_tido

integer

required

Tipo de documento:

1: Boleta (requiere DNI de 8 dígitos)
2: Factura (requiere RUC de 11 dígitos)
6: Nota de venta

id_cliente

integer

ID del cliente existente (opcional si se envía cliente_documento)

cliente_documento

string

required

Documento del cliente (DNI o RUC). Obligatorio si no se envía id_cliente.

cliente_datos

string

required

Nombre o razón social del cliente. Obligatorio si no se envía id_cliente.

cliente_direccion

string

Dirección del cliente

fecha_emision

string

required

Fecha de emisión (formato: YYYY-MM-DD)

serie

string

required

Serie del comprobante (ej: F001, B001)

numero

integer

required

Número correlativo del comprobante

subtotal

number

required

Base imponible (sin IGV)

igv

number

required

Monto del IGV

total

number

required

Total de la venta

tipo_moneda

string

required

Moneda: PEN o USD

afecta_stock

boolean

Indica si debe descontar stock. Por defecto true (excepto para notas de venta).

productos

array

required

Lista de productos de la venta (mínimo 1)

Show Estructura

id_producto

integer

required

ID del producto

cantidad

integer

required

Cantidad vendida (mínimo 1)

precio_unitario

number

required

Precio unitario

subtotal

number

required

Subtotal del item

igv

number

required

IGV del item

total

number

required

Total del item

unidad_medida

string

Código SUNAT de unidad (default: NIU)

tipo_afectacion_igv

string

Tipo de afectación IGV (default: 10 - Gravado)

pago_id_tipo_pago

integer

ID del método de pago

pago_numero_operacion

string

Número de operación del pago

pago_banco

string

Banco del pago

pago_voucher

file

Imagen del voucher (formatos: jpeg, png, jpg, webp. Máximo: 2MB)

cotizacion_id

integer

ID de cotización relacionada (cambiará su estado a ‘aprobada’)

nota_venta_id

integer

ID de nota de venta relacionada (cambiará su estado a ‘vendida’)

Validaciones Importantes

Factura (id_tido=2): Requiere RUC de 11 dígitos. No acepta DNI.
Boleta (id_tido=1): Requiere DNI de 8 dígitos. No acepta RUC.
Si afecta_stock es true, se descuenta el stock automáticamente al crear la venta.

Respuesta

success

boolean

Indica si la venta fue creada exitosamente

message

string

Mensaje descriptivo de la operación

venta

object

id_venta

integer

ID de la venta creada

numero_completo

string

Número completo del comprobante (ej: F001-000001)

Ejemplo de Uso

curl -X POST "https://api.ejemplo.com/api/ventas" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_tido": 2,
    "cliente_documento": "20612706702",
    "cliente_datos": "EMPRESA EJEMPLO SAC",
    "cliente_direccion": "AV. EJEMPLO 123",
    "fecha_emision": "2024-01-15",
    "serie": "F001",
    "numero": 1,
    "subtotal": 100.00,
    "igv": 18.00,
    "total": 118.00,
    "tipo_moneda": "PEN",
    "afecta_stock": true,
    "productos": [
      {
        "id_producto": 1,
        "cantidad": 2,
        "precio_unitario": 50.00,
        "subtotal": 100.00,
        "igv": 18.00,
        "total": 118.00,
        "unidad_medida": "NIU",
        "tipo_afectacion_igv": "10"
      }
    ]
  }'

GET /api/ventas/

Obtiene el detalle completo de una venta específica.

Autenticación

Requiere autenticación con token Bearer y permiso ventas.view.

Parámetros de Ruta

integer

required

ID de la venta

Respuesta

success

boolean

Indica si la operación fue exitosa

venta

object

Objeto completo de la venta con todas sus relaciones (cliente, productos, servicios, cuotas, pagos)

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/ventas/123" \
  -H "Authorization: Bearer {token}"

POST /api/ventas//anular

Anula una venta y retorna el stock al almacén si corresponde.

Autenticación

Requiere autenticación con token Bearer y permiso ventas.delete.

Parámetros de Ruta

integer

required

ID de la venta a anular

Parámetros del Body

motivo_anulacion

string

required

Motivo de la anulación (máximo 500 caracteres)

Respuesta

success

boolean

Indica si la venta fue anulada exitosamente

message

string

Mensaje confirmando la anulación. Indica si el stock fue retornado.

Ejemplo de Uso

curl -X POST "https://api.ejemplo.com/api/ventas/123/anular" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "motivo_anulacion": "Error en el monto facturado"
  }'

GET /api/ventas/proximo-numero

Obtiene el próximo número correlativo disponible para una serie.

Autenticación

Requiere autenticación con token Bearer.

Parámetros de Consulta

serie

string

Serie del comprobante (default: F001)

Respuesta

success

boolean

Indica si la operación fue exitosa

numero

integer

Próximo número correlativo

numero_completo

string

Número completo con formato (ej: F001-000042)

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/ventas/proximo-numero?serie=F001" \
  -H "Authorization: Bearer {token}"

GET /api/ventas//preview-descontar-stock

Previsualiza qué productos existen en el almacén real (almacén 2) antes de descontar stock.

Autenticación

Requiere autenticación con token Bearer y permiso ventas.edit.

Parámetros de Ruta

integer

required

ID de la venta

Respuesta

success

boolean

Indica si la operación fue exitosa

data

array

Lista de productos con su disponibilidad en almacén 2

stock_real_descontado

boolean

Indica si ya se descontó el stock real

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/ventas/123/preview-descontar-stock" \
  -H "Authorization: Bearer {token}"

POST /api/ventas//descontar-stock

Descuenta el stock del almacén real (almacén 2) para una venta.

Autenticación

Requiere autenticación con token Bearer y permiso ventas.edit.

Parámetros de Ruta

integer

required

ID de la venta

Respuesta

success

boolean

Indica si la operación fue exitosa

message

string

Mensaje confirmando el descuento de stock

Ejemplo de Uso

curl -X POST "https://api.ejemplo.com/api/ventas/123/descontar-stock" \
  -H "Authorization: Bearer {token}"

Códigos de Error

422 Unprocessable Entity: Error de validación. La respuesta incluye el campo errors con los detalles.
404 Not Found: Venta no encontrada.
500 Internal Server Error: Error en el servidor.

Notas Importantes

Todas las ventas están asociadas a la empresa del usuario autenticado.
El stock se descuenta automáticamente al crear la venta si afecta_stock es true.
Las facturas requieren RUC de 11 dígitos. Las boletas requieren DNI.
El sistema sincroniza automáticamente el número correlativo en documentos_empresas.

Autenticación

Endpoints

Recursos

​GET /api/ventas

​Autenticación

​Parámetros de Consulta

​Respuesta

​Ejemplo de Uso

​POST /api/ventas

​Autenticación

​Parámetros del Body

​Validaciones Importantes

​Respuesta

​Ejemplo de Uso

​GET /api/ventas/

​Autenticación

​Parámetros de Ruta

​Respuesta

​Ejemplo de Uso

​POST /api/ventas//anular

​Autenticación

​Parámetros de Ruta

​Parámetros del Body

​Respuesta

​Ejemplo de Uso

​GET /api/ventas/proximo-numero

​Autenticación

​Parámetros de Consulta

​Respuesta

​Ejemplo de Uso

​GET /api/ventas//preview-descontar-stock

​Autenticación

​Parámetros de Ruta

​Respuesta

​Ejemplo de Uso

​POST /api/ventas//descontar-stock

​Autenticación

​Parámetros de Ruta

​Respuesta

​Ejemplo de Uso

​Códigos de Error

​Notas Importantes

Build docs developers (and LLMs) love

GET /api/ventas

Autenticación

Parámetros de Consulta

Respuesta

Ejemplo de Uso

POST /api/ventas

Autenticación

Parámetros del Body

Validaciones Importantes

Respuesta

Ejemplo de Uso

GET /api/ventas/

Autenticación

Parámetros de Ruta

Respuesta

Ejemplo de Uso

POST /api/ventas//anular

Autenticación

Parámetros de Ruta

Parámetros del Body

Respuesta

Ejemplo de Uso

GET /api/ventas/proximo-numero

Autenticación

Parámetros de Consulta

Respuesta

Ejemplo de Uso

GET /api/ventas//preview-descontar-stock

Autenticación

Parámetros de Ruta

Respuesta

Ejemplo de Uso

POST /api/ventas//descontar-stock

Autenticación

Parámetros de Ruta

Respuesta

Ejemplo de Uso

Códigos de Error

Notas Importantes