Manual Técnico Servicio Web SAG®

Área Depto. I+D+i Ambiente Producción
Fecha Actualización 29-09-2026 Administrador Camilo Palacio

Objetivo

Integrar diferentes sistemas de información como carritos de compra, sitios web, aplicaciones móviles, páginas web, entre otros, ofreciendo a los clientes la facilidad de tener toda su información sincronizada con el sistema SAG® ERP.

Descripción

El Servicio Web SAG® permite integrar el SAG® ERP con otros aplicativos, en tiempo real y de una manera fácil y segura, por SOAP. El Servicio Web SAG® siempre le entrega al usuario una respuesta a la petición, ya sea positiva o negativa.

URL

La URL del servicio para consumir por SOAP es:

https://wssagpya.azurewebsites.net/ServiceSagWeb.svc?wsdl

El token de prueba para el servicio es: t0k3n1

Probar con SOAP UI

Para probar los servicios SOAP, se recomienda utilizar SoapUI, una herramienta de prueba de servicios web.

Descargar SoapUI

Para descargar SoapUI, visite el sitio oficial: https://www.soapui.org/

Una vez en el sitio, descargue la versión de SoapUI que necesite (SoapUI Open Source o SoapUI Pro).

Descargar SoapUI

Figura 1: Página de descarga de SoapUI

Instalar SoapUI

Después de descargar el instalador, ejecute el archivo y siga los pasos del asistente de instalación:

Instalar SoapUI

Figura 2: Instalación de SoapUI

Una vez instalado SoapUI, para crear un nuevo proyecto:

  1. Abra SoapUI y haga clic en File → New SOAP Project
  2. En el campo Project Name, ingrese cualquier nombre para identificar su proyecto (por ejemplo: "SAGWebService")
  3. En el campo Initial WSDL, pegue la URL del servicio: https://wssagpya.azurewebsites.net/ServiceSagWeb.svc?wsdl
  4. Haga clic en OK y SoapUI cargará automáticamente los métodos disponibles del servicio

Usar SoapUI

Una vez creado el proyecto en SoapUI, para consumir el servicio web siga estos pasos:

  1. Seleccione el método que desea probar (por ejemplo, consultaSagJson o insercionSag)
  2. Ingrese el token de prueba: t0k3n1
  3. Complete los parámetros requeridos según el método seleccionado
  4. Haga clic en el botón de ejecución para enviar la petición

Consumir SoapUI

Figura 3: Consumo del servicio con SoapUI

Nota importante: Cuando necesite enviar XML dentro de otro XML (por ejemplo, en el parámetro a_s_xml), debe escapar el contenido usando CDATA para evitar errores de parsing. El uso de CDATA permite incluir caracteres especiales y estructura XML sin que sean interpretados por el parser XML.

<![CDATA[
  <Movimientos>
    <Movimiento ... />
  </Movimientos>
]]>

Métodos

consultaSagXml() - consultaSagJson() - consultaSagJson2()

Permiten consultar cualquier información almacenada en la base de datos del SAG® ERP...

Descripción

Permiten consultar cualquier información almacenada en la base de datos del SAG® ERP. Con estos métodos se podrá; por ejemplo, consultar la lista de precios y/o existencias de los productos, para cargar en el carrito de compras o también consultar la cartera de los clientes para un aplicativo móvil. La diferencia entre los métodos es la siguiente:

Ejemplos de uso:

Diferencias entre los métodos:

Ejemplo de Entrada / Salida (consultaSagJson)

Entrada:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                        xmlns:tem="http://tempuri.org/">
        <soapenv:Header/>
        <soapenv:Body>
          <tem:consultaSagJson>
            <tem:a_s_token>t0k3n1</tem:a_s_token>
            <tem:a_s_consulta>SELECT TOP 10 n_nit AS Documento, sc_nombre AS Nombre FROM v_clientes</tem:a_s_consulta>
          </tem:consultaSagJson>
        </soapenv:Body>
        </soapenv:Envelope>

Respuesta JSON:

[
        {"Documento":102043531,"Nombre":"CINDY JOHANA ATEHORTUA"},
        {"Documento":1036779941,"Nombre":"LUZ MERCEDES LOPEZ MEJIA"},
        {"Documento":1040740897,"Nombre":"MONICA MARIA MOSQUERA CORDOBA"},
        {"Documento":890900938,"Nombre":"CORPORACION EDUCATIVA COLOMBO BRITANICO"},
        {"Documento":999,"Nombre":"VENTAS DE CONTADO"},
        {"Documento":890900840,"Nombre":"CAJA DE COMPENSACION FAMILIAR CAMACOL"},
        {"Documento":890900842,"Nombre":"CAJA DE COMPENSACION COMFENALCO"},
        {"Documento":890900841,"Nombre":"CAJA DE COMPENSACION COMFAMA"},
        {"Documento":112842385,"Nombre":"PORRAS CASTAÑO LINA MARCELA"},
        {"Documento":15264230,"Nombre":"ANDRES ALBERTO GONZALEZ GUERRA"}
      ]

Respuesta XML (consultaSagXml):

<NewDataSet>
        <Consultas>
          <Documento>102043531</Documento>
          <Nombre>CINDY JOHANA ATEHORTUA</Nombre>
        </Consultas>
        <Consultas>
          <Documento>1036779941</Documento>
          <Nombre>LUZ MERCEDES LOPEZ MEJIA</Nombre>
        </Consultas>
        <Consultas>
          <Documento>1040740897</Documento>
          <Nombre>MONICA MARIA MOSQUERA CORDOBA</Nombre>
        </Consultas>
      </NewDataSet>

Método insercionSag()

Este método se utiliza para grabar o actualizar maestros y documentos en el sistema SAG® ERP. Por ejemplo: crear clientes, pedidos, facturas, artículos, entre otros.

La salida dependerá de cómo se consuma el servicio (XML o JSON).

Entrada / Salida

Entrada Salida
  • a_s_token
  • a_s_tipo
  • a_s_xml
 XML

Ejemplo de petición XML (SOAP)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                        xmlns:tem="http://tempuri.org/">
        <soapenv:Header/>
        <soapenv:Body>
          <tem:insercionSag>
            <tem:a_s_token>t0k3n1</tem:a_s_token>
            <tem:a_s_tipo>1</tem:a_s_tipo>
            <tem:a_s_xml><clientes><cliente ... /></clientes></tem:a_s_xml>
          </tem:insercionSag>
        </soapenv:Body>
      </soapenv:Envelope>

Parámetros de Entrada

Parámetro Descripción Tipo Obligatorio Ejemplo
a_s_token Token de Seguridad asignado por P&A String Sí t0k3n1
a_s_tipo Tipo de acción definida por PYA String Sí 1
a_s_xml Cadena XML con los datos a grabar String Sí <clientes>...</clientes>

Tipos disponibles para a_s_tipo

Tipo Descripción Procedimiento almacenado
1 Crear/Actualizar clientes sp_grabar_cliente_xml
2 Crear documentos (pedidos, facturas, pagos de contado) sp_grabar_documento_xml
3 Crear/Actualizar terceros sp_act_datos_tercero_xml
5 Crear/Actualizar artículos sp_grabar_articulo_basico_xml
6 Recibos de caja, egresos o movimiento contable sp_grabar_movimientos_referencias_xml
28 Crear documentos de cualquier tipo sp_web_grabar_documento

Ejemplo de Respuesta (insercionSag)

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
        <s:Body>
          <insercionSagResponse xmlns="http://tempuri.org/">
            <insercionSagResult 
                xmlns:a="http://schemas.datacontract.org/2004/07/ws.logica.general" 
                xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
              <a:clsGenerales>
                <a:s_estado>OK</a:s_estado>
                <a:s_fuente i:nil="true"/>
                <a:s_identificador i:nil="true"/>
                <a:s_l_movimiento i:nil="true"/>
                <a:s_mensaje>DOCUMENTO CREADO CORRECTAMENTE</a:s_mensaje>
                <a:s_num_documento i:nil="true"/>
              </a:clsGenerales>
            </insercionSagResult>
          </insercionSagResponse>
        </s:Body>
      </s:Envelope>

Parámetros de Respuesta

Parámetro Descripción
s_estado Estado de la operación. Puede ser OK o FALLIDO
s_fuente Código de la fuente asociada al documento
s_identificador Identificador interno del registro
s_l_movimiento Lista o detalle del movimiento
s_mensaje Mensaje descriptivo de la operación (éxito o error)
s_num_documento Número del documento creado

Estructura XML para Crear/Actualizar Clientes (Tipo 1)

Este XML debe enviarse como valor del campo a_s_xml cuando a_s_tipo = 1.

Si se va ACTUALIZAR solo es obligatorio el campo Nit y los campos que se quieran actualizar.

Nodo/Atributo Descripción Tipo Obligatorio Ejemplo
<clientes> Contenedor principal de los clientes Contenedor Sí
<cliente> Contenedor de los datos de un cliente Contenedor Sí
actividadComercial Actividad Comercial según maestro de SAG® String Sí PAPELERÍA
codigoDaneCiudad Código o nombre de ciudad (según DANE) String Sí 05003
Naturaleza J = Jurídica / N = Natural String Sí J
tipoDocumento Tipo de documento (A, C, N, etc.) String Sí A
Documento Número de identificación del cliente Numeric Sí 890900300
digitoVerificacion Dígito de verificación (si aplica) Numeric No 2
direccion Dirección del cliente String Sí Diag. 75c # 32 e 68
tipoTercero Tipo de contribuyente (C, S, G, etc.) String Sí C
telefonoPpal Teléfono principal String Sí +57 4 4486859
telefonoAlterno Teléfono Alterno String No +57 4 3123213323
email Email del cliente String Sí ventas@pya.com.co
activoFijo Debe enviarse siempre como “N” String Sí N
formaPago Forma de pago según maestro String Sí CONTADO
zona Zona comercial del cliente String Sí MEDELLIN Y AREA METROPOLITANA
retenedor ¿Es agente de retención? (S/N) String Sí S
iva ¿Está sujeto a IVA? (S/N) String Sí S
activoComercial ¿Reportado a centrales de riesgo? (S/N) String Sí S
activo Estado del cliente (S/N) String Sí S
tipoCliente Clasificación del cliente String No E-COMMERCE
comisionVentas % de comisión por ventas Numeric No 0
comisionCobros % de Comisión por Recaudo Numeric Si 0
descuento % de Descuento Comercial fijo Numeric Si 0
descuentoPp % de Descuento Pronto Pago fijo Numeric Si 0
precioVenta Lista de precios (0 = ninguna) String Sí 1
reteFuente Código de la Retención en la Fuente por defecto que aplica el Cliente String No V1
otraRetencion Código del ReteCREE por defecto que aplica String No
claseClienteNiff Clasificación del Cliente para NIIF String No RIESGO I
nitVendedor Cédula del Vendedor asignado String No 70100100
cupoMaximo Límite de crédito autorizado Numeric Sí 999999999
Nodo/Atributo Descripción Tipo Obligatorio Ejemplo
Nombre Razón social o nombre completo String Sí ALMACÉN JJ S.A.S.
apellido1 Primer Apellido del Cliente (si es Persona Natural) String No López
apellido2 Segundo Apellido del Cliente (si es Persona Natural) String No Ortiz
nombre1 Primer Nombre del Cliente (si es Persona Natural) String No Juan
nombre2 Segundo Nombre del Cliente (si es Persona Natural) String No José
codigoPostal Código Postal (Zip Code) String No 050030
habeasData Marca que indica si aceptó tratamiento de datos personales (S/N) String No S
centroCosto Código del centro de costo ligado al cliente String No 01
generafacelectronica Marca que indica si maneja factura electrónica (S/N) String No S
emailFacElectronica Email que recibe la factura electrónica String No compras@pya.com.co
responsabilidadFiscal Código de la responsabilidad fiscal del cliente String No R-99-PN
fechaAproboFacElectronica Fecha de aprobación de la factura electrónica Date No 2024-01-15

Validaciones del sistema al crear clientes

Al procesar el XML de creación de clientes, el sistema realiza las siguientes validaciones:

Errores comunes

Código Mensaje Descripción
FALLIDO EL CLIENTE YA EXISTE Se está intentando insertar un cliente con NIT ya registrado.
FALLIDO CIUDAD NO EXISTE El código de ciudad enviado no se encuentra en el maestro de ciudades.
FALLIDO CAMPOS OBLIGATORIOS VACÍOS Uno o más campos requeridos están vacíos o mal formateados.
FALLIDO TIPO DE CLIENTE INVÁLIDO El tipo de cliente enviado no existe en la configuración.
FALLIDO TIPO DE DOCUMENTO INVÁLIDO El tipo de documento no está configurado o es incorrecto.

Ejemplo de respuesta con error

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
        <s:Body>
          <insercionSagResponse xmlns="http://tempuri.org/">
            <insercionSagResult xmlns:a="http://schemas.datacontract.org/2004/07/ws.logica.general"
                                xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
              <a:clsGenerales>
                <a:s_estado>FALLIDO</a:s_estado>
                <a:s_mensaje>EL CLIENTE YA EXISTE</a:s_mensaje>
                <a:s_identificador i:nil="true"/>
                <a:s_num_documento i:nil="true"/>
              </a:clsGenerales>
            </insercionSagResult>
          </insercionSagResponse>
        </s:Body>
      </s:Envelope>

Ejemplo XML - Crear/Actualizar Cliente

<clientes>
        <cliente
          actividadComercial="SECTOR PUBLICO"
          codigoDaneCiudad="MEDELLIN"
          naturaleza="J"
          tipoDocumento="A"
          documento="811040859"
          digitoVerificacion="2"
          nombre="PyA Soluciones Integradas SAS"
          direccion="Diag. 75c # 32 e 68"
          tipoTercero="J"
          telefonoPpal="4486859"
          telefonoAlterno="3001234567"
          email="info@pya.com.co"
          codigo_alterno="CLI-001"
          activoFijo="N"
          formaPago="CONTADO"
          zona="MEDELLIN Y AREA METROPOLITANA"
          retenedor="S"
          iva="S"
          activoComercial="S"
          activo="S"
          tipoCliente="E-COMMERCE"
          comisionVentas="0.00"
          comisionCobros="0.00"
          descuento="0.00"
          descuentoPp="0.00"
          precioVenta="1"
          otraRetencion=""
          reteFuente=""
          claseClienteNiff=""
          nitVendedor="800123456"
          cupoMaximo="999999999"
          direccionAlterna="Calle 10 # 5-20"
          preferenciaCliente="N"
          recibirNuevamentePah="N"
          tallaBrasier=""
          tallaPanty=""
          tallaPijama=""
          tipoBrasierPreferido=""
          tipoPantyPreferido=""
          coloresPreferidos=""
          fechaPahAniversario=""
          fechaPahCumpleanios=""
          fechaPahCumpleaniosOtro=""
          nombrePahOtro=""
          fechaPahDespedidaSoltera=""
          nombrePahOtro2=""
          diaCumpleAnios="15"
          anioCumpleanios="1990"
          mesCumpleAnios="06"
          nombre1="Juan"
          nombre2="Carlos"
          apellido1="Pérez"
          apellido2="López"
          generafacelectronica="N"
          fechaAproboFacElectronica=""
          usuarioAproboFacElectronica=""
          emailFacElectronica=""
          codigoEstablecimientoDest=""
          codigoPostal="050021"
          habeasData="S"
          centroCosto="CC-VENTAS"
          responsabilidadFiscal="R-01"
          rut="14051451"
          reteIvaVentas="N"
          porcentajeReteivaVentas="0.00"
          cuentaReteIvaVentas=""/>
      </clientes>

Estructura XML para Crear/Actualizar Terceros (tipo 3)

Si se va ACTUALIZAR solo es obligatorio el campo Nit y los campos que se quieran actualizar.

Nodo Descripción Tipo Oblig Ejemplo
<Terceros> Contiene todos los Terceros a crear.
<tercero> Contiene los datos de un Tercero en particular.
tipoDocumento Tipo de Documento de Identificación del Tercero.
A = Nit
B = Certificado Cabildo
C = Cédula de Ciudadanía
E = Cédula de Extranjería
F = Tarjeta Profesional
L = Servicio Nacional de Pruebas
M = Menor sin identificación
N = Número por Secretaría de Educación
O = Número de Identificación Personal
P = Pasaporte
R = Registro Civil
S = Adulto sin Identificación
T = Cédula del Tutor
U = Número Único de Identificación
V = Visa
X = Tercero del Exterior sin ID (43)
Z = Tercero del Exterior con ID (42) 		String Sí A
documentoActual Número de la Cédula o NIT del Tercero (o su número de identificación) Numeric Sí 890900300
documentoActualizar Número de la Cédula o NIT a actualizar (si cambió) Numeric No 890900300
digitoVerificacion Dígito de Verificación Numeric No 2
codigoAlterno Código Alterno o Alias String No JJ
nombre Nombre Completo o Razón Social del Tercero
Si el tercero es para actualizar, el campo NO es obligatorio.		 String Sí ALMACÉN JJ S.A.S.
representanteLegal Nombre del Representante Legal String No Juan José Peláez
naturaleza Indica si es Persona Natural o Jurídica.
N = Natural
J = Jurídica
Si el tercero es para actualizar, el campo NO es obligatorio.		 String Sí J
direccion Dirección del Tercero String No Diag. 75c # 32 e 68
direccion2 Segunda dirección String No Vereda Quirama
codigoDaneCiudad Código de la Ciudad asignado por el DANE. También, se puede enviar el nombre de la ciudad. Debe ser igual al Maestro de Ciudades del SAG®.
Si el tercero es para actualizar, el campo NO es obligatorio. 		String Sí 05360
tipoTercero Tipo de Contribuyente.
C = Régimen Común
S = Régimen Simplificado
G = Gran Contribuyente
O = Empresa Oficial
N = Clientes Natural
L = Entidad sin Ánimo de Lucro
J = Sociedad Extranjera
R = No Responsable de IVA
E = Empresa del Estado 		String No C
telefonoPpal Teléfono Principal String No +57 4 4486859
telefonoAlterno Teléfono Alterno String No
telefonoFax Fax o Tercer Teléfono String No
email Email String No ventas@pya.com.co
email2 Segundo Email String No ventas@pya.com.co
paginaWeb Sitio Web del Tercero String No www.pya.com.co
idExterior Número de Identificación del Tercero del Exterior String No R-120222-1
codActividadEconomica Actividad Económica según la DIAN String No 6120

NOTA: Cuando se usa el método de insercionSagXml() para actualizar un tercero, no es necesario mandar toda la estructura. Solo se requieren las etiquetas <terceros>, <tercero>, nitActual y las etiquetas de los campos que se vayan a actualizar, por ejemplo <email>, <dirección>, etc.

Estructura XML para Crear/Actualizar Artículos (Tipo 5)

Si se va ACTUALIZAR solo es obligatorio el campo Código del Artículo y los campos que se quieran actualizar.

Nodo Descripción Tipo Oblig Ejemplo
<articulos> Contiene todos los Artículos a crear.
<articulo> Contiene los datos de un Artículo en particular.
codigo Código del Artículo String Sí 1001
descripcion Nombre o descripción del Artículo String Sí CHAQUETA STAR
descripcion2 Descripción adicional String No JACKET STAR
referencia Referencia del Artículo String No ST01
codBarras Código de Barras String No 7704040123456
grupo Grupo del Artículo String Sí VESTUARIO
subGrupo Subgrupo String No DAMA
linea Línea o Marca String No BON JOVI
unidad Unidad de manejo String Sí UNIDAD
manejaKardex Inventariable (S/N) Char Sí S
manejaLote Manejo de lote o serial
N / V / E / S		 Char Sí N
manejaTallaColor Manejo de Talla/Color
S / N / I		 Char Sí N
talla Código de la Talla String No 36
color Código del Color String No NG
codBarrasSKU Código de Barras SKU String No 7704040145456
activo Activo (S/N) Char Sí S
bloqueado Bloqueado (S/N) Char Sí N
clase Clasificación: A/S/G/O Char Sí A
tarifaIVA Código de la tarifa de IVA String Sí IVA19
porcentajeIVA % de IVA Numeric Sí 19
incluidoIVA IVA incluido (S/N) Char Sí N
PV1 Precio de Venta 1 hasta PV8 Numeric No 50000
PV1TC Precio de Venta Talla Color 1 hasta PV8TC Numeric No 50000
costoSTD Composición Numeric No 0
cantMaxima Cantidad Máxima permitida Numeric No 0
cantMinima Cantidad Minima permitida Numeric No 0
tiendaVirtual Indica si el Artículo está habilitado para la venta por eCommerce (S/N) Char No N
composicion Composición String No Pol/Alg
adquisicion Adquisición String No Importado
otroDato1 Otros Datos 1 hasta Otro dato 10 String No Rayas

Ejemplo Artículos

<articulos>
        <articulo 
          codigo="1001"
          descripcion="CHAQUETA STAR"
          descripcion2="STAR JACKET"
          referencia="ST01"
          codBarras="7704040123456"
          grupo="VESTUARIO DAMA"
          subgrupo="BON JOVI"
          unidad="UNIDAD"
          manejaKardex="S"
          manejaLote="N"
          manejaTallaColor="S"
          talla="36"
          color="NG"
          codBarrasSKU="7704567123401"
          activo="S"
          bloqueado="N"
          clase="A"
          tarifaIVA="IVA19"
          porcentajeIVA="19"
          incluidoIVA="N"
          PV1="50000"
          PV2="40000"
          composicion="Pol/Alg"
          adquisicion="Importado"
          otroDato1="Rayas" />
      </articulos>

Ejemplo XML para crear articulos con componentes

Para crear artículos con componentes, debe incluir los campos obligatorios en el nodo articulo y agregar los componentes dentro del nodo Componentes. El atributo ManejaComponentes debe estar en "S" para indicar que el artículo maneja componentes.

<articulos>
        <articulo articuloId="1"
                  Codigo="si"
                  ka_nl_articulo="1"
                  ManejaComponentes="S">
            <Componentes ArticuloComponenteId="1"
                         articuloId="1"
                         CodigoArticuloComponente="FLORV2"
                         Cantidad="10"
                         Orden="1"
                         DetalleAdicional="Descripcion de prueba de compo1" />
            <Componentes ArticuloComponenteId="2"
                         articuloId="1"
                         CodigoArticuloComponente="FLORV1"
                         Cantidad="12"
                         Orden="1"
                         DetalleAdicional="Descripcion de prueba de compo2" />
        </articulo>
    </articulos>

Estructura Archivo XML Documentos (Todos los Tipos de Documentos) (Tipo 28)

Nodo Descripción Tipo Oblig Ejemplo
<Movimientos> Contiene todos los Documentos a crear.
<Movimiento> Contiene los datos de un Documento en particular.
MovimientoId Número Interno del Documento Numeric Sí 213012
FechaDocumento Fecha del Documento. Formato YYYY/MM/DD Date Sí 2020/04/30
NumeroDocumento Número del Documento. Si llega en 0 el SAG® asigna el consecutivo siguiente Numeric Sí 0
NumeroDocumento2 Número2 String No OC-400
CodigoFuente Código de la Fuente String Sí PD
ClaseComprobante Clase de Comprobante, si aplica String No PED
Nit Nit del cliente / proveedor al que se le realiza el documento Numeric Sí 10202455
NitVendedor Cédula del Vendedor Numeric No 70100200
CentroCosto Centro de Costos String No 04
Prefijo Prefijo del Documento, si aplica String No 02
CiudadEntrega Ciudad de Entrega del Pedido String No Cali
DireccionEntrega Dirección de Entrega del Pedido String No Calle 25 # 12-29
Observaciones Observaciones del Documento String No Dejar en Portería
Moneda Moneda de Negociación String No PESOS
Trm TRM Numeric No 1
Pedido Número del Pedido/OC del Cliente o Proveedor. Informativo. Ej: FV-1122 String No OC-201
Remision Número de Remisión String No RM-112
LoginUsuario Login del Usuario logueado en la aplicación origen. String Si WTORO
Otros Código Sucursal del Cliente. Debe iniciar por ! String No !1
Impreso Indicador de si el documento fue impreso (S/N) Char No N
Generado Indicador de si el documento fue generado automáticamente (S/N) Char No N
EsRemision Indicador de si el documento es una Remisión (S/N) Char No N
Facturado Indicador de si el documento (remisión) fue facturado (S/N) Char No N
VistoBueno Indicador de si el documento fue modificado manualmente por contabilidad (S/N) Char No N
Autorizado Indicador de si el documento está autorizado (S/N) Char No N
Incoterm El código del Incoterm debe existir en la base de datos Varchar No CFR, CIF
RealizarCommit Indica si se realiza el Commit en la BD al grabar el Documento (S/N) Char Sí S
Accion Indica la acción a realizar en el sistema Char No I = Insertar
FechaOriginal La fecha con la que se graba el documento Date No 2025-05-28
Beneficiario Nombre del Beneficiario String No Juan Pérez
CodigoCuentaBanco Es el código de la cuenta del banco, solo se utiliza para los recibos y egresos. Es obligatorio para los documentos tipos recibos de caja y/o egresos String No 110505
TrmMe Es la TRM de la moneda extranjera Decimal No 0
PagoContado Indica si el documento va a realizar un pago de contado Char No S = Sí / N = No
PorcentajeComisionVentas Indica el % de comisiones de un vendedor sobre esa venta Decimal No 0 por defecto hasta el 99%
FechaVencimiento Indica la fecha de vencimiento del documento Date No 2025-05-28
DiasPp1 Días para el cálculo del pronto pago (Hasta DiasPp3) Decimal No 0
FechaPp1 Fecha del primer pronto pago (Hasta FechaPp3) Date No 2025-06-08
DescripcionFormaPago Descripción de la forma de pago String No 30 días, debe estar en el maestro de formas de pago del SAG (formas_pagos)
ManejaCuota Indica si el documento maneja cuotas Char No S = Sí, N = No
PorcentajeRefteManual Indica el % de la retención para retenciones manuales (personas naturales) Decimal No 0 hasta el 99.9%
ValorRetefteManual Valor de la retención manual Decimal No 10000
SistemaOrigen Indica el sistema del que llega el documento String No SagWeb
AsignarImpuestosPorDefecto Indica si se van a asignar los impuestos teniendo en cuenta el maestro de terceros Char No S = Sí, N = No
AsignarVendedorPorDefecto Indica si se va a asignar el vendedor teniendo en cuenta el maestro de terceros Char No S = Sí, N = No
AsignarMonedaPorDefecto Indica si se asigna la moneda de la empresa por defecto Char No S = Sí, N = No
NitPaciente Graba en el documento el número de documento del paciente (Empresas de salud) Int No 1053854678
DocumentoCerrado Indica si se va a dejar cerrado el documento o no Char No S = Sí, N = No
CausalDevolucion El código de la causal de devolución solo aplica para notas de devolución. Debe existir en el maestro de causales de devolución del SAG (causal_devolucion) String No 01

Estructura XML <MovimientoDetalle>

Nodo Descripción Tipo Oblig Ejemplo
<MovimientoDetalle> El detalle del Item a enviar dentro del Movimiento. <Movimientos> <Movimiento
…

<MovimientoDetalle
…
> </Movimiento>
</Movimientos>
MovimientoId Número Interno del Documento Numeric Sí 213012
MovimientoDetalleId Consecutivo del Ítem Numeric Sí 1
CualPrecio Lista de Precios a Tomar. 1..8 String No 1
CodigoArticulo Código del Artículo. Si maneja T/C, puede enviarse separado o como Código de Barras Ref-Talla-Color String Sí 2002
Talla Talla String No L
Color Color String No NG
Cantidad Cantidad Pedida Numeric Sí 6
ValorUnitario Valor Unitario antes de IVA (usar -9999999 para costo promedio) Numeric Sí 15000
Iva % de IVA Numeric Sí 19
Descuento % de Descuento Comercial Numeric Sí 5
Descuento2 % de 2° Descuento Comercial Numeric Sí 5
PorcentajeIva % de Iva al producto Numeric No 5
CantidadUnidadCompraMayor Cantidad Unidad de Compra x Mayor. Ej: Docena Numeric No 5
FechaEntrega Fecha de entrega estimada Date No 2024-01-05
FuenteFactura Fecha de la factura a relacionar (Obligatorio si es un Recibo de Caja) String No 2024-01-05
NumeroFactura Numero de documento a relacionar (Obligatorio si es un Recibo de Caja) Int No 2024-01-05
FechaFactura Fecha de la factura a relacionar (Obligatorio si es un Recibo de Caja) Date No 2024-01-05
CodigoBin Código Bin del artículo String No
ValorUnitarioCompraMayor Valor Unitario Unidad de Compra x Mayor Numeric No 200000
DetalleAdicional Detalle adicional por ítem String No ASESORÍA PRESENCIAL
BodegaOrigen Código de la Bodega Origen (requerido para traslados) String No 01
BodegaDestino Código de la Bodega Destino (requerido para traslados) String No 02
Bodega Es obligatoria para documentos tipo factura o inventario, indica cual es el codigo de la bodega (Debe existir en el maestro de bodegas) String No 02
Lote Número de Lote o Serial String No AB3545R
Campo01Detalle Detalle opcional (Hasta Campo04Detalle) String No Detalle del item personal
PorcentajeBase 0 hasta 99.9 Numeric No 10
ValorBase Valor base de la cuenta contable (Necesaria para un asiento contable) Numeric No Ejemplo valor base de la retención en la fuente o el iva
CodigoCuentaContable El numero de la cuenta contable que esta en el maestro de cuentas contables String No ADM
CodigoValorPosible Codigo del valor posible String No Ejemplo 99 para indicar que es el total
90 IVA
70 ReteFUENTE
80 ReteIVA
CodigoFlujoCaja Codigo flujo caja que esta en el maestro de flujo de caja String No 01 Que hace referencia a ingresos
FuentePedido Fuente del documento de pedido String No OG
NumeroPedido Número del documento del pedido String No 33670
FechaPedido Fecha del documento relacionado Date No 2025-05-21
CodigoCentroCostoItem Código del centro de costo del maestro centro costo String No ADM
ObservacionesItem Permite agregar una observación sobre el item String No Escribir observación
Campo01Detalle Se puede usar hasta el detalle 08 String No Escribir observación
Impuesto01 Impuesto al consumo en Valor Decimal No 12000
Impuesto02 Impuesto al consumo en POrcentaje Decimal No 19
ImpuestoSaludableNominal Impuesto saludable en valor Decimal No 10000
ImpuestoSaludablePorcentual Impuesto saludable en porcenatje Decimal No 10
FuenteRemision Indica la fuente de la remisión asociar el item, queda como el documento relacionado String No OC
NumeroRemision Indica el número de documento de la remisión asociar el item, queda como el documento relacionado Int No 14574
TipoComponente Indica si el artículo o item es un componente Char No S
NitTercero Cédula o nit del tercero String No 9001458793
NitVendedorAnticipo Relaciona el Vendedor que realiza el anticipo Int No 9001458793
CodigoCuentaMas Código de la cuenta más que aplica solo para Recibos de Caja y Egresos String No Debe existir en el maestro de plan de cuentas del SAG
CodigoCuentaMenos Código de la cuenta menos que aplica solo para Recibos de Caja y Egresos String No Debe existir en el maestro de plan de cuentas del SAG
CodigoCuentaDifCambio Código de la cuenta diferencia en cambio que aplica solo para Recibos de Caja y Egresos String No Debe existir en el maestro de plan de cuentas del SAG
ValorDiferenciaCambio Es el valor de la diferencia en cambio Decimal No 10000
CodigoCuentaDifCambioMe Es el valor de la diferencia en cambio para moneda extranjera String No Debe existir en el maestro de plan de cuentas del SAG
CodigoCuentaReteiva Código de la cuenta reteiva, aplica solo para Recibos de Caja y Egresos String No Debe existir en el maestro de plan de cuentas del SAG
CodigoCuentaReteFte Indica cuál es el código de la retención en la fuente para el Item String No C10
CodigoRetencionFteItem Código en Sag que identifica la retención en la fuente String No R01
CodigoCuentaDifCambioniif Código de la cuenta de cambio para Nif, aplica solo para Recibos de Caja y Egresos String No Debe existir en el maestro de SAG
ValorDifCambioNiif Indica el valor de diferencia de cambio para el Niff Decimal No 5000
ValorMe Indica el valor de cambio en Moneda extranjera Decimal No 5200
CodigoBinOrigen Código de localización cuando maneja Bin (Solo aplica para traslados entre bodegas) String No Debe existir en el maestro de bodegas bines de SAG
CodigoBinDestino Código de localización cuando maneja Bin (Solo aplica para traslados entre bodegas) String No Debe existir en el maestro de bodegas bines de SAG
CualPrecio Indica cuál lista de precio se utiliza Char No 1 = Precio 1
CodigoCausal Indica el codigo de la causal de devolución para el item, para las Notas String No Debe existir en el maestro de SAG (causal_devolucion)
NumeroCheque Indica cuál lista de precio se utiliza String No 12345678

<MovimientoOtrosDatos>

Nodo Descripción Tipo Oblig Ejemplo
<MovimientoOtrosDatos> Otros Datos del documento. <Movimientos> <Movimiento
…

<MovimientoOtrosDatos
…
> </Movimiento>
</Movimientos>
MovimientoId Número Interno del Documento Numeric Sí 213012
Dato1 Más Datos 1 - 30 String No Dato1, Dato8 … Dato30

EJEMPLO XML PARA TRASLADOS:

<Movimientos>
        <Movimiento MovimientoId="1"
                    CodigoFuente="TR"
                    NumeroDocumento="0"
                    FechaDocumento="2023/06/30"
                    Nit="72257656"
                    CentroCosto="8000"
                    Observaciones="Pruebas"
                    Moneda="PESOS"
                    LoginUsuario="ADMON"
                    SistemaOrigen="SQL">
      
          <MovimientoOtrosDatos MovimientoId="1"
            Dato1="Dato1"
            Dato2="Dato2"
            Dato3="Dato3"
            Dato4="Dato4"
            Dato5="Dato5"
            Dato15="Dato15" />
      
          <MovimientoDetalle MovimientoDetalleId="1"
            MovimientoId="1"
            CodigoArticulo="CAMISA01"
            BodegaOrigen="A"
            BodegaDestino="B"
            Cantidad="1"
            Descuento="0"
            Iva="1"
            ValorUnitario="0"
            ValorPrecioVenta="300"
            Talla="S"
            Color="RJ"
            PorcentajeIva="19"
            PorcentajeDescuento="0"
            DetalleAdicional="Detalle"/>
      
        </Movimiento>
      </Movimientos>

EJEMPLO XML PARA ASIENTO CONTABLE:

<Movimientos>
        <Movimiento MovimientoId="1"
                    CodigoFuente="FV"
                    Prefijo="FE"
                    NumeroDocumento="0"
                    FechaDocumento="2024/10/31"
                    CentroCosto="8000"
                    Generado="N"
                    Beneficiario="90000"
                    ClaseComprobante=""
                    Observaciones="Pruebas Observaciones"
                    RealizarCommit="N"
                    Moneda="PESOS"
                    LoginUsuario="ADMON"
                    SistemaOrigen="NOMBRE EMPRESA QUE GEENRA EL DOCUMENTO">
      
          <MovimientoOtrosDatos MovimientoId="1" Dato01="Dato1" />
      
          <MovimientoDetalle MovimientoDetalleId="1"
            MovimientoId="1"
            CodigoCuentaContable="41201401"
            NitTercero="123456789"
            CodigoCentroCosto="8000"
            Valor="1000"
            PorcentajeBase="0"
            ValorBase="0"/>
      
          <MovimientoDetalle MovimientoDetalleId="2"
            MovimientoId="1"
            CodigoCuentaContable="24080105"
            NitTercero="123456789"
            Valor="-1000"
            PorcentajeBase="1"
            ValorBase="1000000"
            DetalleAdicional="Detalle"/>
      
        </Movimiento>
      </Movimientos>

EJEMPLO PARA UNA ENTRADA DE MERCANCIA CON ORDEN DE COMPRA ASOCIADA:

<Movimientos>
        <Movimiento MovimientoId="1"
                    FechaDocumento="2025-05-22"
                    NumeroDocumento="0"
                    NumeroDocumento2="HRN"
                    CentroCosto="A"
                    LoginUsuario="WMS"
                    FechaVencimiento="2025-06-21"
                    FechaPp1="2025-05-22"
                    RealizarCommit="S"
                    CodigoFuente="EA"
                    Nit="890911700"
                    Moneda="PESOS"
                    Pedido="OG-33670"
                    Observaciones="Prueba Integración WMS">
      
          <MovimientoDetalle MovimientoId="1"
            MovimientoDetalleId="1"
            Cantidad="1"
            ValorUnitario="6700"
            Iva="0"
            Descuento="0"
            CodigoArticulo="CR506H"
            Bodega="AG01"
            FuentePedido="OG"
            NumeroPedido="33670"
            FechaPedido="2025-05-21"
            DetalleAdicional="Nota item"/>
      
          <MovimientoDetalle MovimientoId="1"
            MovimientoDetalleId="2"
            Cantidad="1"
            ValorUnitario="140"
            Iva="0"
            Descuento="0"
            CodigoArticulo="CR804GB"
            Bodega="AG01"
            FuentePedido="OG"
            NumeroPedido="33670"
            FechaPedido="2025-05-21"
            DetalleAdicional="Nota item"/>
      
        </Movimiento>
      </Movimientos>

ESTRUCTURA COMPLEMENTARIA DE UNA FACTURA CON MEDIOS DE PAGO

Nodo Descripción Tipo Oblig Ejemplo
<Movimientos> Contenedor general de todos los movimientos del documento. <Movimientos>
  <Movimiento ... >
    <MovimientoDetalle ... />
    <MovimientoMediosPagos ... />
  </Movimiento>
</Movimientos>
MovimientoMediosPagos Información de los medios de pago asociados al movimiento. Nodo interno del Movimiento con los medios de Pago
MovimientoId Identifica el consecutivo del medio de pago dentro del Movimiento. String Si 1
CodigoMedioPago Codigo del Medio de Pago a enviar, que debe existir en el maestro de Medios de pago String Si 01
Valor Valor cancelado con el medio de pago Numeric Si 10000
CodigoTransaccion Código de la transacción en caso de que se haya realizado una transaccion string Si 10000

EJEMPLO XML CON MEDIOS DE PAGO (Factura POS):

<Movimientos>
            <Movimiento MovimientoId="1" 
            FechaDocumento="2025-06-25" 
            NumeroDocumento="14516" 
            Prefijo="PR" 
            LoginUsuario="ADMON" 
            RealizarCommit="S" 
            CodigoFuente="FV" 
            NitTercero="900011412" >
                <MovimientoDetalle MovimientoId="1" 
                MovimientoDetalleId="1" 
                CualPrecio="1" 
                Cantidad="21" 
                ValorUnitario="5000" 
                Iva="0" 
                Descuento="0" 
                CodigoArticulo="1" 
                Bodega="01"  />
                <MovimientoMediosPagos 
                    Movimientold="1"                     
                    CodigoMedioPago="01" 
                    EsFacturaPos="S" 
                    Valor="90000" />
                <MovimientoMediosPagos 
                    Movimientold="1"
                    CodigoMedioPago="03" 
                    CodigoTransaccion="12"
                    NumeroTransaccion="1313"
                    EsFacturaPos="S" 
                    Valor="15000" />
        </Movimiento>
    </Movimientos>

EJEMPLO XML DE UNA FACTURA DE VENTA:

<Movimientos>
  <Movimiento MovimientoId="1" 
              FechaDocumento="2025-06-25" 
              NumeroDocumento="14516" 
              CentroCosto="6" 
              Prefijo="PR" 
              NitVendedor="472" 
              LoginUsuario="ADMON" 
              FechaVencimiento="2025-09-08" 
              DiasPp1="12" 
              FechaPp1="2025-07-07" 
              PorcentajeDescuentoPp1="12" 
              FormaPago="28" 
              Zona="19" 
              RealizarCommit="S" 
              CodigoFuente="FV" 
              NitTercero="416" 
              Moneda="PESOS">

    <MovimientoDetalle MovimientoId="1" 
                       MovimientoDetalleId="1" 
                       CualPrecio="1" 
                       Cantidad="20" 
                       ValorUnitario="12000" 
                       Iva="19" 
                       Descuento="20" 
                       CodigoCentroCostoItem="0" 
                       CodigoArticulo="40077" 
                       Bodega="1"/>

  </Movimiento>
</Movimientos>

Eventos sobre Factura Recibida - Operador Saphety (Acuse de Recibo, Aceptación, Rechazo y Recibo de Mercancía)

Sección dirigida a usuarios/integradores que consumen el servicio web para realizar eventos de acuse de recibo, aceptación, rechazo y recibo de mercancía sobre facturas recibidas a través del operador Saphety.

Servicio y operación

Propiedad Valor
URL del servicio https://apifesag.azurewebsites.net/ServiceFE.svc
WSDL (para agregar referencia) https://apifesag.azurewebsites.net/ServiceFE.svc?wsdl
Operación a invocar facturaElectronicaPyA

La operación recibe un objeto invoiceContractRequest y devuelve un objeto facturaElectronicaPyAResult.

Consumo vía SOAP

Agregue una referencia de servicio apuntando al WSDL y llame la operación facturaElectronicaPyA. En el WSDL el puerto se publica como httpEndpoint con dirección http://apifesag.azurewebsites.net/ServiceFE.svc/soap (también responde por https://). Si consume el servicio manualmente (SoapUI, Postman, etc.), envíe el sobre SOAP a esa dirección:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:tem="http://tempuri.org/"
                  xmlns:bas="http://schemas.datacontract.org/2004/07/Ws.Contracts.Base">
  <soapenv:Header/>
  <soapenv:Body>
    <tem:facturaElectronicaPyA>
      <tem:invoiceContractRequest>
        <bas:Environment>P</bas:Environment>
        <bas:Version>v2</bas:Version>
        <bas:User>usuario_saphety</bas:User>
        <bas:Password>password_saphety</bas:Password>
        <bas:Operator>1</bas:Operator>
        <bas:DocumentType>acu</bas:DocumentType>
        <bas:Resource>{"Identification":{"CompanyIds":"900123456","InvoiceNumber":"FE-1001"}}</bas:Resource>
        <bas:VirtualOperator>pya</bas:VirtualOperator>
      </tem:invoiceContractRequest>
    </tem:facturaElectronicaPyA>
  </soapenv:Body>
</soapenv:Envelope>

Consumo vía REST / JSON

Propiedad Valor
Método HTTP POST
URL https://apifesag.azurewebsites.net/ServiceFE.svc/web/facturaElectronicaPyA
Content-Type application/json
Body JSON envuelto en el nodo invoiceContractRequest

Nota: estos eventos (acu, sif, nof, sib) solo están disponibles en la operación facturaElectronicaPyA.

Contrato de entrada (invoiceContractRequest)

{
  "invoiceContractRequest": {
    "Environment": "P",
    "Version": "v2",
    "User": "usuario_saphety",
    "Password": "password_saphety",
    "Operator": "1",
    "DocumentType": "acu",
    "Resource": "{ ... JSON del evento en formato string ... }",
    "VirtualOperator": "pya",
    "FileName": "",
    "FormatStandard": "",
    "Token": ""
  }
}

Parámetros de Entrada

Parámetro Obligatorio Descripción
Environment Sí Ambiente destino en Saphety. R = Pruebas (QA), H = Habilitación (QA), P = Producción.
Version Sí Versión del API del operador. Use v2.
User Sí Usuario asignado por Saphety. Con él el servicio se autentica ante el operador.
Password Sí Contraseña del usuario Saphety.
Operator Sí Operador de facturación. Para Saphety usar 1 o 4.
DocumentType Sí Define el evento a ejecutar. Ver tabla de opciones más abajo.
Resource Sí String que contiene un JSON con los datos del evento. Su estructura depende del DocumentType.
VirtualOperator No Operador virtual dentro de Saphety. Si no se envía, se usa pya por defecto.
FileName No No se utiliza en este flujo.
FormatStandard No No se utiliza en este flujo.
Token No No se utiliza en este flujo (la autenticación se hace con User/Password).

Opciones de DocumentType

Valor Evento
acu Acuse de recibo de la factura
sif Aceptación expresa de la factura
nof Rechazo de la factura
sib Recibo de bienes / mercancía

No es necesario enviar el identificador interno de la factura en Saphety: el servicio la localiza automáticamente usando el NIT de la empresa (CompanyIds) y el número de factura (InvoiceNumber) que se incluyen en el Resource.

Estructura del campo Resource

Resource es una cadena de texto que contiene JSON. Los campos CompanyIds (NIT de la empresa receptora) e InvoiceNumber (número de la factura) son obligatorios porque el servicio los usa para localizar el documento en Saphety.

Acuse de recibo (acu) y Recibo de bienes (sib)

CompanyIds e InvoiceNumber van dentro del nodo Identification.

{
  "invoiceContractRequest": {
    "Environment": "P",
    "Version": "v2",
    "User": "usuario_saphety",
    "Password": "password_saphety",
    "Operator": "1",
    "DocumentType": "acu",
    "Resource": "{\"Identification\":{\"CompanyIds\":\"900123456\",\"InvoiceNumber\":\"FE-1001\",\"DocumentDate\":\"2026-09-29\"}}"
  }
}

Equivalente para sib cambiando solo "DocumentType": "sib".

Aceptación (sif) y Rechazo (nof)

CompanyIds e InvoiceNumber van en el nivel raíz del JSON del Resource. En el rechazo puede incluir el motivo en RejectionReason.

{
  "invoiceContractRequest": {
    "Environment": "P",
    "Version": "v2",
    "User": "usuario_saphety",
    "Password": "password_saphety",
    "Operator": "1",
    "DocumentType": "nof",
    "Resource": "{\"CompanyIds\":\"900123456\",\"InvoiceNumber\":\"FE-1001\",\"RejectionReason\":\"Datos incorrectos en la factura\"}"
  }
}

Equivalente para sif cambiando solo "DocumentType": "sif".

Importante: el Resource se envía como string, por eso las comillas internas del JSON deben ir escapadas (\") cuando se arme el body de la petición.

Respuesta

La operación devuelve el objeto facturaElectronicaPyAResult con estos campos:

Campo Descripción
Success true si el evento se registró correctamente en Saphety.
Id "1" cuando el evento fue exitoso (estos eventos no devuelven un id de transacción propio).
s_estado "OK" si fue exitoso, "FALLIDO" en caso contrario.
Messages Lista de mensajes. En error incluye el detalle devuelto por Saphety y, cuando existe, una solución sugerida para corregirlo.
s_fuente, s_identificador, s_l_movimiento, s_num_documento, s_qr_base64 Campos del contrato de respuesta; no se diligencian en este flujo.

Respuesta exitosa (JSON)

{
  "facturaElectronicaPyAResult": {
    "Success": true,
    "Id": "1",
    "s_estado": "OK",
    "Messages": []
  }
}

Respuesta con error (JSON)

{
  "facturaElectronicaPyAResult": {
    "Success": false,
    "Id": null,
    "s_estado": "FALLIDO",
    "Messages": [
      "S - Ocurrio un error en el proceso y no se completo correctamente",
      "<detalle del error devuelto por Saphety>"
    ]
  }
}

En consumo SOAP, el mismo objeto llega dentro del sobre SOAP en el nodo facturaElectronicaPyAResponse/facturaElectronicaPyAResult.

Errores de validación (datos de entrada)

Cuando falla la validación de la petición, Success es false y Messages contiene uno o varios de estos mensajes:

Resumen rápido

Evento DocumentType ¿Dónde van CompanyIds e InvoiceNumber?
Acuse de recibo acu Dentro de Identification
Aceptar factura sif Nivel raíz del Resource
Rechazar factura nof Nivel raíz del Resource
Recibo de bienes sib Dentro de Identification
↑