Ir al contenido

API Transacciones

De LAZARVS
Revisión del 16:12 5 nov 2026 de Pablo (Hablar | contribs.) (Se actualiza luego de cambios)

API Transacciones de Lazarvs

La API permite consultar y crear oportunidades, notas de venta y órdenes de compra. Las operaciones GET y POST comparten la ruta de cada recurso.

Información general

  • Objeto: API_Transacciones.
  • URL base: {{URL de Lazarvs}}/transacciones.
  • Formato: JSON.
  • Contrato local de desarrollo: Plantilla:URL de Lazarvs/API_Transacciones.yaml.

La URL de Lazarvs incluye el protocolo, servidor y contexto de la aplicación. Debe utilizarse la URL correspondiente al ambiente de destino. Los códigos de maestros deben existir en la compañía y el ambiente utilizados.

Autenticación y encabezados

Todas las operaciones requieren el token JWT autorizado para la integración. La compañía y el usuario se obtienen del token; no se seleccionan enviando esos datos en el cuerpo de la orden.

Authorization: Bearer <token_jwt>
Accept: application/json
Content-Type: application/json

Accept indica el formato esperado de respuesta. Content-Type debe enviarse en los POST con cuerpo JSON. Los GET no requieren cuerpo. Los datos adicionales del payload JWT que una operación no utiliza se ignoran; no deben confundirse con el cuerpo JSON del POST.

Convenciones

  • Respetar exactamente las mayúsculas y minúsculas de los parámetros y miembros JSON documentados. En particular, el GET de órdenes de compra recibe Ordennumero, mientras que el POST devuelve OrdenNumero.
  • Las fechas se envían como cadenas YYYY-MM-DD.
  • Los booleanos se envían como true o false, sin comillas.
  • Los números se envían sin separadores de miles y con punto decimal, sin comillas. Los códigos se envían como cadenas para conservar ceros iniciales.
  • En respuestas observadas, el generador serializa algunos importes y números como cadenas, aunque el YAML los declara numéricos. Los clientes deben contemplar esa representación.
  • Que el YAML no declare un campo obligatorio no elimina las validaciones funcionales de las transacciones. Los ejemplos deben adaptarse a los maestros y configuración de cada compañía.

Endpoints

Método Ruta relativa Operación
GET /Oportunidad Consulta por número externo de oportunidad.
POST /Oportunidad Crea una oportunidad.
GET /NotaVenta Consulta una nota de venta asociada a una oportunidad externa.
POST /NotaVenta Crea una nota de venta.
GET /OrdenDeCompra Consulta por número de orden y/o oportunidad externa.
POST /OrdenDeCompra Crea cabecera y líneas de una orden de compra.

GET /Oportunidad

Consulta una oportunidad por su número externo.

Parámetro query Tipo Descripción
Oportunidad string Número externo de oportunidad. El YAML lo declara opcional; debe informarse para identificar la oportunidad buscada.
GET {{URL de Lazarvs}}/transacciones/Oportunidad?Oportunidad=2024-0101

La respuesta contiene SDTOportunidad y los Mensajes que correspondan. Si no se encuentra el registro, se devuelve HTTP 404.

POST /Oportunidad

Crea una oportunidad. El cuerpo contiene un objeto raíz SDTOportunidad. Su estructura completa figura en la sección de esquemas.

{
  "SDTOportunidad": {
    "Nombre": "Oportunidad de prueba",
    "NumeroExterno": "API-PRUEBA-001",
    "CuentaIdTributaria": "ID_TRIBUTARIA_CLIENTE",
    "FechaApertura": "2026-11-04",
    "Moneda": "USD",
    "IngresoEsperadoMoneda": 20000,
    "Probabilidad": 0,
    "DeclaradoAlProveedor": false,
    "Importante": false
  }
}

Ejemplo orientativo: completar los códigos y demás datos exigidos por la configuración. La respuesta contiene la colección de mensajes de la operación.

GET /NotaVenta

Consulta una nota de venta asociada a una oportunidad identificada por su número externo.

Parámetro query Tipo Descripción
Oportunidad string Número externo de oportunidad. El YAML lo declara opcional; debe informarse para realizar esta búsqueda.
GET {{URL de Lazarvs}}/transacciones/NotaVenta?Oportunidad=2024-0101

La respuesta contiene SDTNotaVenta y los Mensajes que correspondan. Si no se encuentra, se devuelve HTTP 404.

POST /NotaVenta

Crea una nota de venta mediante el objeto raíz SDTNotaVenta. Debe indicarse al menos una referencia: OportunidadExterna, OportunidadNumero u OrdenDeCompraCliente. La implementación controla duplicados con las referencias informadas.

{
  "SDTNotaVenta": {
    "Fecha": "2026-11-04",
    "Descripcion": "Nota de venta de prueba",
    "Moneda": "USD",
    "Cliente": "CODIGO_CLIENTE",
    "OrdenDeCompraCliente": "OC-CLI-PRUEBA-001",
    "UsaIdentificacion": false,
    "CongelaPrecios": false,
    "Articulos": [
      {
        "ArticuloCodigo": "CODIGO_ARTICULO",
        "ArticuloCantidad": 2,
        "ArticuloPrecio": 100,
        "ArticuloPrecioImpuestoIncluido": false
      }
    ],
    "Enlaces": []
  }
}

Ejemplo orientativo: sustituir los códigos y completar las condiciones, ubicación y demás campos requeridos. La respuesta contiene la colección de mensajes. Los campos de identificación, entrega, artículos y enlaces se detallan en los esquemas.

GET /OrdenDeCompra

Devuelve la cabecera y las líneas de una orden de compra dentro de la compañía del token.

Parámetro query exacto Tipo Descripción
Ordennumero integer (int64) Número interno de orden de compra. Opcional individualmente.
Oportunidad string Número externo de oportunidad (OpoNroExt), no su número interno. Opcional individualmente.

Debe informarse al menos uno de los dos parámetros. Si se informan ambos, la orden debe cumplir ambos filtros. Si no se informa ninguno, la validación devuelve HTTP 400. Si no hay coincidencias, devuelve HTTP 404.

La respuesta es un único objeto: cuando una oportunidad tiene varias órdenes, la consulta implementada selecciona la de menor número.

GET {{URL de Lazarvs}}/transacciones/OrdenDeCompra?Ordennumero=845
GET {{URL de Lazarvs}}/transacciones/OrdenDeCompra?Oportunidad=OP-EXTERNA-001
GET {{URL de Lazarvs}}/transacciones/OrdenDeCompra?Ordennumero=845&Oportunidad=OP-EXTERNA-001

La respuesta contiene SDTOrdenDeCompra y los mensajes que correspondan. El contrato actual devuelve principalmente códigos: la ampliación con nombres y un SDT exclusivo de consulta todavía no forma parte de esta versión.

POST /OrdenDeCompra

Crea una orden de compra con cabecera y una o más líneas. El cuerpo debe estar contenido en SDTOrdenDeCompra. No se utilizan los filtros query del GET.

{
  "SDTOrdenDeCompra": {
    "Fecha": "2026-11-04",
    "FechaEntrega": "2026-11-04",
    "Descripcion": "PRUEBA API - Alta de orden de compra",
    "Proveedor": "0291",
    "CentroCostos": "GV01",
    "Almacen": "02",
    "Moneda": "USD",
    "EsImportacion": false,
    "FormaPago": "45 Días, Cheque",
    "Lineas": [
      {
        "Destino": "C",
        "Descripcion": "Prueba API - Línea 1",
        "Articulo": "020-000182-002",
        "CentroCostos": "GV01",
        "Mercancia": "W01",
        "Cantidad": 2,
        "Precio": 100,
        "ImpuestoCodigo": "BD"
      },
      {
        "Destino": "C",
        "Descripcion": "Prueba API - Línea 2",
        "Articulo": "020-160001-001",
        "CentroCostos": "GV01",
        "Mercancia": "W01",
        "Cantidad": 1,
        "Precio": 50,
        "ImpuestoCodigo": "BD"
      }
    ]
  }
}

Este ejemplo fue probado en test con esos maestros. Los códigos no son universales: deben sustituirse por los existentes en el ambiente y la compañía de destino.

Reglas del alta

  • Se requiere al menos una línea.
  • El servidor asigna el número de orden, las secuencias, la ruta y estación inicial y los datos de auditoría.
  • Si se omite la fecha de orden, se utiliza la fecha del servidor. Si se omite la fecha de entrega, se utiliza la fecha de orden.
  • Para compras locales corresponde informar el almacén de entrega. Para importaciones corresponde la condición de importación; se aplican las validaciones de la transacción.
  • Para destino Bienes de Cambio, la unidad se obtiene del artículo. La mercancía también se toma del artículo cuando tiene una definida.
  • La tasa del impuesto se obtiene del modelo a partir del código de impuesto; no se asigna desde ImpuestoTasa.
  • Los subtotales, impuestos y totales se calculan mediante las reglas de los Business Components.
  • Cabecera, líneas y actualización de totales se confirman con un único Commit. Si falla alguna etapa, se ejecuta Rollback de toda la operación.
  • Cada POST exitoso crea una nueva orden. No debe repetirse una solicitud de alta sin verificar antes el resultado de la anterior.

Campos calculados

Aunque el SDT compartido los incluye, no deben enviarse como datos de alta: Numero, los importes de cabecera SubTotal, Impuestos y Total, y los miembros de línea Secuencia, ImpuestoTasa, SubTotal, Impuestos y Total. Sus valores se asignan o calculan en el servidor.

Respuesta exitosa

{
  "Mensajes": [
    {
      "Description": "Se creó la orden de compra 845",
      "Id": "INFOOC01",
      "Type": 2
    }
  ],
  "OrdenNumero": "845"
}

El número del ejemplo corresponde a una ejecución de test. El número generado permite consultar la orden por GET. Los mensajes automáticos de guardados intermedios se filtran para no confundirlos con la confirmación final.

Respuesta de error

{
  "Mensajes": [
    {
      "Description": "Línea 2: No existe 'Artículo'.",
      "Id": "ForeignKeyNotFound",
      "Type": 1
    },
    {
      "Description": "Línea 2: No existe 'Unidad'.",
      "Id": "ForeignKeyNotFound",
      "Type": 1
    }
  ],
  "OrdenNumero": "0"
}

Con la implementación actual, los errores funcionales del POST devuelven HTTP 409. OrdenNumero = 0 indica que no se devuelve una orden creada. El error de unidad puede ser consecuencia de un artículo inexistente, porque la unidad se resuelve a partir de ese artículo. Se verificó en test que un error en la segunda línea revierte también la cabecera y la primera línea.

Respuestas y códigos HTTP

HTTP Significado en la implementación
200 Operación exitosa. El POST de orden de compra devuelve el número generado; no utiliza 201 en esta versión.
400 GET de orden de compra sin número de orden ni oportunidad externa.
401 Token inválido o permisos insuficientes, según los eventos actuales.
404 Consulta GET sin resultados.
405 Operación no habilitada o uso de entidad no permitido por las validaciones actuales.
409 POST con errores funcionales o de validación.

El YAML generado enumera 200 y 404 por operación, pero no refleja todos los códigos asignados en los eventos del API. La tabla anterior incluye el comportamiento implementado. No se utiliza 422 en la implementación actual.

Estructura de mensajes

Cada mensaje incluye Id, Type y Description. En las respuestas observadas se presenta como un arreglo Mensajes. Los nombres de esquemas internos del YAML no deben confundirse con los nombres de propiedades JSON.

Type Significado
0 Advertencia (Warning)
1 Error (Error)
2 Información (Info)
3 Depuración (Debug)

El YAML tiene una inconsistencia en los esquemas de mensajes: algunos GET referencian un ítem individual para Mensajes, y el esquema genérico de los POST de oportunidad y nota de venta usa Messages. Para integrar esos POST, comprobar la envoltura JSON efectiva en el ambiente de destino. Para órdenes de compra se verificó el arreglo Mensajes mostrado en los ejemplos. El esquema anterior API_Transacciones_Respuesta con Existe y Datos no es la respuesta declarada por el contrato actual.

Esquemas de datos

Los siguientes campos reproducen el contrato adjunto. Los tipos corresponden a OpenAPI; las reglas de obligatoriedad funcional dependen de la operación y de la configuración. No se incluyen campos descriptivos propuestos para una versión futura.

SDTOportunidad

Campo Tipo Descripción
Nombre string Nombre
Tipo string Tipo de Oportunidad
NumeroExterno string Número Externo
Territorio string Territorio
AsignadoA string Asignado a
Cuenta string Cuenta
CuentaIdTributaria string Número de Documento
Prospecto integer (int64) Prospecto
Origen string Origen
FechaApertura string (date) Fecha Apertura
FechaInicio string (date) Fecha Inicio de Validez
FechaEntregaOferta string (date) Fecha Entrega Oferta
FechaCierreEsperado string (date) Fecha Cierre Esperado
FechaCierreEfectivo string (date) Fecha Cierre Efectivo
Etapa string Etapa
Probabilidad number (double) Probabilidad
Solucion string Solución Ofrecida
ProximoPaso string Próximo paso
DeclaradoAlProveedor boolean Declarado al Proveedor
OportunidadProveedor string Oportunidad en Proveedor
Importante boolean Importante
Competencia string Competencia
Descripcion string Descripción
ActividadPlanificada string Pasos Planificados
Moneda string Moneda
IngresoEsperadoMoneda number (double) Ingreso Esperado

SDTNotaVenta

Campo Tipo Descripción
Fecha string (date) Fecha
Tipo string Código
Descripcion string Descripción
Comentarios string Comentarios
Local string Local
Almacen string Almacén
Moneda string Moneda
OportunidadExterna string Número Externo
OportunidadNumero integer (int64) Oportunidad
UsaIdentificacion boolean Ingresa Identificación
Cliente string Cliente
ClienteIdTributaria string Id Tributaria de Cliente (cuando no se envía cliente)
DireccionEntregaNumero integer (int64) Dirección Entrega
Condicion string Condición
CongelaPrecios boolean Congela Precios
FechaPrecios string (date) Fecha para Precios
OrdenDeCompraCliente string Orden de Compra de Cliente
Territorio string Territorio
Jurisdiccion string Jurisdicción
PorcentajeDescuentoGlobal number (double) Porcentaje de Descuento
FechaInicialEntrega string (date) Fecha Inicial de Entrega
FechaFinalEntrega string (date) Fecha Final de Entrega
Identificacion object Véase SDTNotaVenta.Identificacion.
Entrega object Véase SDTNotaVenta.Entrega.
Articulos array Colección de SDTNotaVenta.Articulos_Articulo.
Enlaces array Colección de SDTNotaVenta.Enlaces_Enlace.

SDTNotaVenta.Identificacion

Campo Tipo Descripción
ClienteNombre string Nombre de Cliente
ClienteTipo string Tipo Valores: F = Fisico, J = Juridico.
ClienteDireccion string Dirección de Cliente
ClienteCiudad string Ciudad
ClientePais string País
ClientePersonaFisicaTipoDocumento string Documento Valores: C = CI, D = DNI, P = Pasaporte, N = NIE, O = Otros.
ClientePersonaFisicaNumeroDocumento string Número
ClientePersonaJuridicaTipoDocumento string Localización Valores: N = Nacional, E = Exterior.
ClientePersonaJuridicaNumeroDocumento string Id Tributaria

SDTNotaVenta.Entrega

Campo Tipo Descripción
EntregaDireccion string Dirección de Entrega
EntregaCiudad string Ciudad
EntregaCodigoPostal string Código Postal
EntregaEstadoProvincia string Estado / Provincia
EntregaPais string País
EntregaTelefono string Teléfono
EntregaContacto string Contacto

SDTNotaVenta.Articulos_Articulo

Campo Tipo Descripción
ArticuloCodigo string Artículo
ArticuloLote string Lote
ArticuloCantidad number (double) Cantidad
ArticuloTipoDeVenta string Tipo de Venta
ArticuloSerie string Serie
ArticuloPorcentajeImpuesto number (double) Porcentaje de Impuesto
ArticuloPrecio number (double) Precio
ArticuloPrecioImpuestoIncluido boolean Impuesto de Venta incluido en el precio
ArticuloDescuento number (double) Descuento
ArticuloProveedor string Proveedor
ArticuloCostoUnitario number (double) Costo Unitario
ArticuloGastosImportacion number (double) Gastos Importación

SDTNotaVenta.Enlaces_Enlace

Campo Tipo Descripción
EnlaceDescripcion string Descripción
EnlaceURL string URL

SDTOrdenDeCompra

Campo Tipo Descripción
Numero integer (int64) Número de Orden de Compra Calculado/asignado por el servidor; no enviar en el POST.
Fecha string (date) Fecha de Orden de Compra
Descripcion string Descripción
Proveedor string Proveedor
Comprador string Comprador
CentroCostos string Centro de Costos
Comentarios string Comentarios al Proveedor
EsImportacion boolean Importación
FechaEntrega string (date) Fecha de Entrega Esperada
CondicionImportacion string Condición Valores: EXW = EXW, FCA = FCA, FOB = FOB, FAS = FAS, CFR = CFR, CIF = CIF, CPT = CPT, CIP = CIP, DAF = DAF, DES = DES, DEQ = DEQ, DDU = DDU, DAT = DAT, DAP = DAP, DDP = DDP, N/A = NoAplica.
CondicionImportacionAsociada string Asociado a Condición
NotaVentaNumero integer (int64) Nota de Venta
OportunidadNumero integer (int64) Oportunidad
Almacen string Almacén Entrega
Segmento string Segmento
Moneda string Moneda
FormaPago string Forma de Pago
SubTotal number (double) SubTotal Calculado/asignado por el servidor; no enviar en el POST.
Impuestos number (double) Impuesto Calculado/asignado por el servidor; no enviar en el POST.
Total number (double) Total Calculado/asignado por el servidor; no enviar en el POST.
Lineas array Colección de SDTOrdenDeCompra.Lineas_LineasItem.

SDTOrdenDeCompra.Lineas_LineasItem

Campo Tipo Descripción
Secuencia integer (int64) Secuencia OC Calculado/asignado por el servidor; no enviar en el POST.
Destino string Destino Valores: U = BienesDeUso, C = BienesDeCambio, G = Gastos, P = Especifico.
Descripcion string Descripción
Articulo string Artículo
CentroCostos string Centro de Costos
Mercancia string Mercancía
Cuenta string Cuenta
Proyecto string Proyecto
TipoTransaccion string Tipo de Transacción
Unidad string Unidad
Cantidad number (double) Cantidad
Precio number (double) Precio Unitario
ImpuestoCodigo string Impuesto
ImpuestoTasa number (double) Tasa de Impuesto Vigente Calculado/asignado por el servidor; no enviar en el POST.
SubTotal number (double) SubTotal Calculado/asignado por el servidor; no enviar en el POST.
Impuestos number (double) Impuesto Calculado/asignado por el servidor; no enviar en el POST.
Total number (double) Total Calculado/asignado por el servidor; no enviar en el POST.

Verificación de una integración

  1. Consultar por GET una orden conocida y comprobar que corresponde a la compañía del token.
  2. Crear en test una orden con dos líneas válidas.
  3. Consultar el número devuelto y comparar cabecera, líneas e importes con Lazarvs.
  4. Repetir con una primera línea válida y una segunda inválida, usando una descripción distinta.
  5. Comprobar HTTP 409, mensajes de error y número de salida 0; verificar en Lazarvs que no quedó una orden con la descripción de la prueba fallida.
  6. Probar el GET con cada filtro, con ambos filtros y sin filtros.

Las pruebas de alta deben ejecutarse en test antes de habilitar una integración en producción.