siat

README

go-siat is a professional SDK developed in Go, designed to simplify integration with SIAT (Integrated Tax Administration System) SOAP web services.

💡 Why go-siat?

Integrating with SIAT's SOAP web services for electronic invoicing in Bolivia is often a complex process involving manual XML handling, digital signatures (XMLDSig), and error-prone nested data structures.

go-siat abstracts all this complexity behind a modern, idiomatic, and type-safe SDK. Our goal is to allow Bolivian developers to focus on the business logic of their applications (POS, ERPs), while the SDK handles:

• Building perfect SOAP envelopes.
• Digital signatures required by the tax authority.
• Compression and encoding of invoice packages.
• Structured management of catalogs and operations.

---

🎯 Features

• 🛡️ Type-Safe: Rigorous data structures for ALL requests and responses (goodbye to generic maps and hardcoded strings).
• 🏗️ Builder Pattern: Intuitive construction of complex requests (such as invoices and cancellations) through fluid interfaces.
• 📦 Total SOAP Abstraction: Transparent management of the SOAP layer. The developer interacts with structs, not XML.
• ✍️ Integrated Digital Signature (XMLDSig): Utilities to automatically sign invoices with your digital certificate.
• 🚀 High Performance: Zero unnecessary dependencies, leveraging Go's native speed for byte manipulation and compression.
• 🧩 Modular: Multiple services (Codes, Synchronization, Operations, Sales, Electronic, Computerized) clearly separated.
• 🏢 Multi-Sector: Native and verified support for 35 different sectors (Sales, Hotels, Mining, Hospitals, Hydrocarbons, etc.).

---

📖 Table of Contents

1. Why go-siat?
2. Features
3. Quick Start Guide
4. Advanced Examples
5. Project Architecture
6. Documentation Reference
7. Usage Reference (Tests)
8. Contribution and Support
9. License

---

Implemented Capabilities

The SDK covers the critical services of the SIAT ecosystem:

Services	Key Functionalities
Codes	CUIS/CUFD Request (Individual and Massive), NIT Validation, Communication.
Synchronization	Catalogs for activities, parametric, products, services, and sector documents.
Operations	POS Registration/Closing, Significant Event Management.
Sales	Specific service for sales, bonuses, and fees.
Online Electronic	Full support for invoicing with digital signature.
Online Computerized	Support for modalities without digital signature.
Special Sectors	Verified support for the 35 regulatory sectors of SIAT.

---

Supported Sectors

go-siat includes domain models, builders, and integration tests for the 35 regulatory sectors of SIAT (located in pkg/models/invoices/):

🏢 Standard and Services

• Sales (Sector 1): The standard sector for most businesses.
• Rental of Real Estate: For the real estate and leasing sector.
• Insurance: Issuance of policies and insurance services.
• Basic Services: Electricity, water, gas, and telecommunications.
• Tourism and Lodging / Hotels: For the hotel sector and tour operators.
• Hospitals and Clinics: Health services (National and Free Trade Zone).
• Food Security: Commercialization of basic food basket products.

🏺 Export and Free Trade Zone

• Export of Goods and Services: Commercial Export, Services, and Free Consignment.
• Free Trade Zone: ZF Invoices, ZF Rental, and ZF Hospital Services.
• Duty Free: Invoicing for duty-free shops in airports.

⛽ Hydrocarbons and Energy

• Commercialization of Hydrocarbons: Fuels, Lubricants (with and without IEHD).
• Bottling Plants: LPG distribution sector.
• CNG and GNV: Commercialization of Natural Gas for Vehicles.
• Unsubsidized Fuel: For sale at international price.

⛰️ Mining and Metals

• Sale of Minerals: Internal Sale and Export of Minerals.
• Sale to BCB: Sale of gold and minerals to the Central Bank of Bolivia.

🎓 Education

• Educational Sectors: Schools, Universities, and Institutes (National and Free Trade Zone).

🎲 Other Special Sectors

• Games of Chance: Casinos and entertainment venues.
• Zero Tax (Tasa Cero): Books and international cargo transportation.
• ICE Products: Items covered by the Specific Consumption Tax.
• Prepayments and Shared Invoice: Complex invoicing flows.
• Prevalued: Invoices with fixed price and recurring tax service.
• Foreign Currency Exchange: Exchange houses and financial entities.

---

🚀 Quick Start Guide

1. Requirements

• Go 1.25 or higher.
• Valid digital certificate (p12/pfx) and private key (for Electronic modality).

2. Installation

go get github.com/ron86i/go-siat

3. Usage Example: Verifying NIT

package main

import (
	"context"
	"fmt"
	"github.com/ron86i/go-siat"
	"github.com/ron86i/go-siat/pkg/models"
)

func main() {
	// 1. Initialize the client
	s, _ := siat.New("YOUR_SIAT_URL", nil)

	// 2. Prepare the request using builders
	req := models.Codigos().NewVerificarNitBuilder().
		WithNit(123456789).
		Build()

	// 3. Execute call
	resp, err := s.Codigos().VerificarNit(context.Background(), req)
	if err != nil {
		panic(err)
	}

	fmt.Printf("NIT Transaction status: %v\n", resp.Body.Content.RespuestaVerificarNit.Transaccion)
}

---

🏗️ Project Architecture

The project follows a modular architecture based on Ports and Adapters (Hexagonal) to ensure maintainability and testability:

• internal/core/domain/: Pure business logic and SIAT data structures.
• internal/core/port/: Definition of interfaces (contracts).
• internal/adapter/services/: Implementation of SOAP clients and communication.
• pkg/models/invoices/: Domain models and fluent builders for the 35 SIAT sectors.
• pkg/utils/: Utilities for signatures, compression, and formatting.

---

📂 Documentation Reference

For detailed guides and implementation details, see:

Document	Description
ARCHITECTURE.md	Architectural design, patterns, and design decisions of the SDK.
CONTRIBUTING.md	Contributor guide: how to report bugs and send pull requests.
CONTEXT_BEST_PRACTICES.md	Best practices for using context.Context in applications calling the SDK.
SUPPORT.md	Technical and commercial support for electronic invoicing.

---

The best way to learn how to use each service is by reviewing the integration tests:

Category	Test File
Codes	siat_codigos_service_test.go
Synchronization	siat_sincronizacion_service_test.go
Operations	siat_operaciones_service_test.go
Sales	siat_compra_venta_service_test.go
Electronic	siat_electronica_service_test.go
Computerized	siat_computarizada_service_test.go
Invoicing (Sectors)	pkg/models/invoices/
End-to-End	siat_test.go

---

Contributions are welcome! If you find a bug or have a suggestion, please open an Issue or a Pull Request (please review the CONTRIBUTING.md).

If you need technical help or commercial support for integrating electronic invoicing in your company, please check our SUPPORT.md.

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Documentation

Index

• Constants
• func GetMensaje(code int) string
• func IsConfigCode(code int) bool
• func IsNetworkError(err error) bool
• func IsRetryable(err error) bool
• func IsRetryableCode(code int) bool
• func IsValidationCode(code int) bool
• func IsWarningCode(code int) bool
• func NewHTTPClient(cfg HTTPConfig) *http.Client
• func Verify(resp interface{}) error
• type Config
• type HTTPConfig
  • func DefaultHTTPConfig() HTTPConfig
• type HTTPMiddleware
• type Map
  • func (m Map) Sum() float64
  • func (m Map) ToJSON() (string, error)
  • func (m Map) ToStruct(v interface{}) error
• type SiatError
  • func NewAuthError(msg string) *SiatError
  • func NewNetworkError(msg string, err error) *SiatError
  • func NewSiatError(code int, msg string) *SiatError
  • func NewTimeoutError(msg string) *SiatError
• type SiatServices
  • func New(baseUrl string, httpClient *http.Client) (*SiatServices, error)
  • func NewWithMiddleware(baseUrl string, httpClient *http.Client, middlewares ...HTTPMiddleware) (*SiatServices, error)
  • func (s *SiatServices) Codigos() ports.SiatCodigosService
  • func (s *SiatServices) CompraVenta() ports.SiatCompraVentaService
  • func (s *SiatServices) Computarizada() ports.SiatComputarizadaService
  • func (s *SiatServices) Electronica() ports.SiatElectronicaService
  • func (s *SiatServices) Operaciones() ports.SiatOperacionesPort
  • func (s *SiatServices) Sincronizacion() ports.SiatSincronizacionService
  • func (s *SiatServices) WithConfig(token string) ports.Config
  • func (s *SiatServices) WithTraceID(id string) *SiatServices

Constants

const (
	CodeCufdFueraDeTolerancia                        = 123
	CodeRecepcionPendiente                           = 901
	CodeRecepcionRechazada                           = 902
	CodeRecepcionProcesada                           = 903
	CodeRecepcionObservada                           = 904
	CodeAnulacionConfirmada                          = 905
	CodeAnulacionRechazada                           = 906
	CodeReversionAnulacionConfirmada                 = 907
	CodeRecepcionValidada                            = 908
	CodeReversionAnulacionRechazada                  = 909
	CodeAmbienteInvalido                             = 910
	CodeCodigoSistemaInvalido                        = 911
	CodeSistemaNoAsociadoAlContribuyente             = 912
	CodeCuisInvalido                                 = 913
	CodeCufdInvalido                                 = 914
	CodeTipoFacturaDocumentoInvalido                 = 915
	CodeTipoEmisionInvalido                          = 916
	CodeModalidadInvalida                            = 917
	CodeSucursalInvalida                             = 918
	CodeNitInvalido                                  = 919
	CodeArchivoInvalido                              = 920
	CodeFirmadoXmlIncorrecto                         = 921
	CodeFirmaXmlNoCorrespondeAlContribuyente         = 922
	CodeCodigoRecepcionInvalido                      = 923
	CodeFacturaNoExisteEnSin                         = 924
	CodeMotivoAnulacionInvalido                      = 925
	CodeComunicacionExitosa                          = 926
	CodeCertificadoFirmaInvalido                     = 927
	CodeCertificadoRevocado                          = 928
	CodeCuisNoVigente                                = 929
	CodeCuisNoCorrespondeASucursalPuntoVenta         = 930
	CodeCodigoDocumentoSectorInvalido                = 931
	CodeCodigoDocumentoSectorNoCorrespondeAlServicio = 932
	CodePuntoVentaInexistenteOInvalido               = 933
	CodeAnulacionFueraDePlazo                        = 934
	CodeFechaEnvioInvalida                           = 935
	CodeFacturaYaAnulada                             = 936
	CodeNitNoAsociadoAModalidad                      = 937
	CodeNitPresentaMarcasDeControl                   = 938
	CodeFacturaNoCumpleXsd                           = 939
	CodeNitNoHabilitadoDocumentoSector               = 940
	CodeFacturaNoDisponibleParaAnular                = 941
	CodeEventoSignificativoNoExisteEnSin             = 942
	CodeFormatoFechaEnvioIncorrecto                  = 943
	CodeCodigoRecepcionNoExisteEnSin                 = 944
	CodeEstadoRecepcionAnulacionIncorrecta           = 945
	CodeCufNoExisteEnSin                             = 946
	CodeTipoPuntoVentaInvalido                       = 947
	CodeNombrePuntoVentaVacio                        = 948
	CodeDescripcionPuntoVentaVacio                   = 949
	CodeEventoSignificativoVacio                     = 950
	CodeDescripcionEventoSignificativoVacio          = 951
	CodeCufYaRegistradoEnSin                         = 952
	CodeCufdNoVigente                                = 953
	CodePaqueteContingenciaExcedido                  = 954
	CodeNoExisteRegistroMasivo                       = 955
	CodePaqueteMasivoExcedido                        = 956
	CodeNoExisteEventoSignificativo                  = 957
	CodeUsuarioNoAutorizado                          = 958
	CodeCuisNoAsociadoAlSistema                      = 959
	CodeFinDeEventoRequerido                         = 960
	CodeMarcaDomicilioInexistente                    = 961
	CodeBloqueoDosificacionFiscalizacion             = 962
	CodeBloqueoDosificacionJuridica                  = 963
	CodeNoCumpleObligatoriedadDDJJ                   = 964
	CodeContribuyenteSinFirmaVigente                 = 965
	CodeNoSePuedeRecuperarDatosContribuyente         = 966
	CodeTiempoEsperaAgotadoDB                        = 967
	CodeAnulacionYaRevertida                         = 968
	CodeHashInvalido                                 = 969
	CodeCuisVigenteNoPuedeSolicitarOtro              = 970
	CodeArchivoExcedeTamano                          = 971
	CodeCantidadFacturasExcedeNormativa              = 972
	CodeRangoFechasEventoInvalido                    = 974
	CodeSistemaNoAutorizadoOObservado                = 975
	CodeCodigoEventoIncorrecto                       = 976
	CodeNoExistenActividadesNIT                      = 977
	CodeReversionFacturaConfirmada                   = 978
	CodeCuisNoAsociadoASistemaOSucursal              = 979
	CodeExisteCuisVigente                            = 980
	CodeRangoFechasEventoSignificativoInvalido       = 981
	CodeNoExistePuntosDeVenta                        = 982
	CodeFechaEnvioPaqueteFueraDePlazo                = 983
	CodeEventoNoCorrespondeCufd                      = 984
	CodeCantidadFacturasDiferenteADeclarada          = 985
	CodeNitActivo                                    = 986
	CodeNitInactivo                                  = 987
	CodeCuisFueraDeTolerancia                        = 988
	CodeTokenInvalido                                = 989
	CodeClienteSinActividadesSector                  = 990
	CodeErrorBaseDeDatos                             = 991
	CodeErrorServicioPadron                          = 992
	CodeFechaEnvioFueraDePlazo                       = 993
	CodeNitInexistente                               = 994
	CodeServicioNoDisponible                         = 995
	CodeRangoFechasInvalido                          = 996
	CodeNombreExcedeLimite                           = 997
	CodeDescripcionExcedeLimite                      = 998
	CodeErrorEjecucionServicio                       = 999
	CodeCufYaExisteEnSin                             = 1000
	CodeNitNoCorrespondeACufd                        = 1001
	CodeCufInvalido                                  = 1002
	CodeCufdEnXmlInvalido                            = 1003
	CodeSucursalNoCorrespondeACufd                   = 1004
	CodeFacturaNoPuedeSerEmitidaAlMismoEmisor        = 1005
	CodeCufdNoCorrespondeAEvento                     = 1006
	CodeDireccionNoCorrespondeAPadron                = 1007
	CodePuntoVentaEnXmlInexistente                   = 1008
	CodeFechaEmisionNoValidaLinea                    = 1009
	CodeFacturaMontoExcedidoSinDatos                 = 1010
	CodeComplementoSoloCarnet                        = 1011
	CodeNumeroTarjetaSoloConTarjeta                  = 1012
	CodeCalculoMontoTotalErroneo                     = 1013
	CodeCalculoMontoTotalMonedaErroneo               = 1014
	CodeCalculoImporteBaseErroneo                    = 1015
	CodeActividadNoHabilitada                        = 1016
	CodeProductoNoRelacionadoAActividad              = 1017
	CodeCalculoSubtotalErroneo                       = 1018
	CodeCalculoIceEspecificoErroneo                  = 1019
	CodeCalculoIcePorcentualErroneo                  = 1020
	CodeMontoIceEspecificoErroneo                    = 1021
	CodeMontoIcePorcentualErroneo                    = 1022
	CodeCodigoNandinaErroneo                         = 1023
	CodeSumatoriaDetallesErronea                     = 1024
	CodeMontoSujetoCreditoLey317Erroneo              = 1025
	CodeMontoTotalSujetoIJErroneo                    = 1026
	CodeMontoDiferenciaCambioErroneo                 = 1027
	CodeMontoIvaErroneo                              = 1028
	CodeMontoTotalDevueltoErroneo                    = 1029
	CodeMontoTotalOriginalErroneo                    = 1030
	CodeMontoEfectivoDevueltoErroneo                 = 1031
	CodeMontoTotalIPJErroneo                         = 1032
	CodeMontoDevueltoMayorAOriginal                  = 1033
	CodeFechaEmisionMenorPeriodoAnterior             = 1034
	CodeFormatoFechaIncorrecto                       = 1035
	CodeNominatividadIncorrecta                      = 1036
	CodeNitNoValido                                  = 1037
	CodeNitConjuntoNoValido                          = 1038
	CodeFechaEmisionMasivaIncorrecta                 = 1039
	CodeFechaEmisionFueraRangoContingencia           = 1040
	CodeFechaEmisionFueraPlazoNorma                  = 1041
	CodeNitMedicoNoValido                            = 1042
	CodeMontoConciliadoErroneo                       = 1043
	CodeMontoTotalConciliadoErroneo                  = 1044
	CodeCafcNoValido                                 = 1045
	CodeFechaEmisionCafcIncorrecta                   = 1046
	CodeNumeroFacturaCafcIncorrecto                  = 1047
	CodeNotaCreditoFacturaNoEncontrada               = 1048
	CodeNotaDetalleDiferenteAFactura                 = 1049
	CodeMontoGiftCardNoCorresponde                   = 1050
	CodeFechaFacturaIncorrecta                       = 1051
	CodeCalculoMontoIehdErroneo                      = 1052
	CodeActividadNotaAutorizadaPlazo                 = 1053
	CodeMontoDescuentoCreditoDebitoErroneo           = 1054
	CodeMontoTarifaErroneo                           = 1055
	CodeTipoCambioErroneo                            = 1056
	CodeMontoTotalMonedaComputarizadaErroneo         = 1057
	CodeMontoTotalSujetoIvaErroneo                   = 1058
	CodeRazonSocialErronea                           = 1059
	CodeMontoDetalleErroneo                          = 1060
	CodeNotaNoValidaParaDevolucion                   = 1061
	CodeWarnCorrelatividadFactura                    = 2000
	CodeWarnFechaRangoContingencia                   = 2001
	CodeWarnFechaEmisionMasiva                       = 2002
	CodeWarnFacturaMontoSinDatos                     = 2003
	CodeWarnComplementoSoloCarnet                    = 2004
	CodeWarnNitClienteNoValido                       = 2005
	CodeWarnNumeroTarjetaSoloConTarjeta              = 2006
	CodeWarnCalculoMontoTotal                        = 2007
	CodeWarnCalculoMontoTotalMoneda                  = 2008
	CodeWarnCalculoImporteBase                       = 2009
	CodeWarnActividadNoHabilitada                    = 2010
	CodeWarnProductoNoRelacionado                    = 2011
	CodeWarnCalculoSubtotal                          = 2012
	CodeWarnEmisionAMismoEmisor                      = 2013
	CodeWarnDireccionNoCorrespondePadron             = 2014
	CodeWarnCalculoIceEspecifico                     = 2015
	CodeWarnCalculoIcePorcentual                     = 2016
	CodeWarnMontoIceEspecifico                       = 2017
	CodeWarnMontoIcePorcentual                       = 2018
	CodeWarnCodigoNandinaErroneo                     = 2019
	CodeNitNoContratoVigente                         = 3000
	CodeCategoriaContratoNoSector                    = 3001
	CodeExcedeLimiteCufdMasivo                       = 3002
	CodeMarcaNoFormulariosVigentes                   = 3003
	CodeMarcaDomicilioInexistenteMarca               = 3004
	CodeMarcaBloqueoFiscalizacion                    = 3005
	CodeMarcaBloqueoJuridica                         = 3006
	CodeMarcaNoObligatoriedadDDJJ                    = 3007
	CodeWarnCuisExpira                               = 3008
	CodeTamanoArchivoMayorNorma                      = 3009
	CodeFacturaYaUtilizadaOConsolidada               = 3010
)

SIAT Error Codes

const (
	// AmbienteProduccion (1): Operaciones reales con validez tributaria.
	AmbienteProduccion = iota + 1
	// AmbientePruebas (2): Entorno de desarrollo, pruebas y certificación.
	AmbientePruebas
)

const (
	// ModalidadElectronica (1): Requiere firma digital de los documentos XML.
	ModalidadElectronica = iota + 1
	// ModalidadComputarizada (2): No requiere firma digital, usa código de control.
	ModalidadComputarizada
)

const (
	// EmisionOnline (1): La emisión se realizó con conexión al SIAT.
	EmisionOnline = iota + 1
	// EmisionOffline (2): La emisión se realizó fuera de línea (Contingencia).
	EmisionOffline
	// EmisionMasiva (3): Para procesos de alta demanda de facturación.
	EmisionMasiva
)

Functions

func GetMensaje

func GetMensaje(code int) string

GetMensaje retorna la descripción del código de error del SIAT. Si el código no existe, retorna una descripción genérica con el código.

func IsConfigCode

func IsConfigCode(code int) bool

IsConfigCode retorna true si el código indica un error de configuración del sistema o credenciales.

func IsNetworkError

func IsNetworkError(err error) bool

IsNetworkError indica si un error fue de red. Útil para distinguir entre problemas de conectividad y errores del servidor.

func IsRetryable

func IsRetryable(err error) bool

IsRetryable indica si un error puede/debe ser reintentado. Útil para implementar lógica de retry en la aplicación.

func IsRetryableCode

func IsRetryableCode(code int) bool

IsRetryableCode retorna true si el código de error del SIAT sugiere que la operación puede ser reintentada después de un tiempo (ej: saturación o timeout de base de datos).

func IsValidationCode

func IsValidationCode(code int) bool

IsValidationCode retorna true si el código indica un error de validación de datos (ej: NIT inexistente, formato XSD inválido).

func IsWarningCode

func IsWarningCode(code int) bool

IsWarningCode retorna true si el código es informativo o una advertencia que no impide el proceso.

func NewHTTPClient

func NewHTTPClient(cfg HTTPConfig) *http.Client

NewHTTPClient crea un cliente HTTP optimizado basado en HTTPConfig. Es útil para customizar la configuración sin reescribir todo el Transport.

Ejemplo:

cfg := siat.DefaultHTTPConfig()
cfg.Timeout = 60 * time.Second
client := siat.NewHTTPClient(cfg)
s, err := siat.New(baseUrl, client)

func Verify

func Verify(resp interface{}) error

Verify analiza una respuesta del SIAT y determina si la operación fue exitosa. Si la respuesta contiene errores del SIAT (Transaccion=false o mensajes de error), construye y retorna un *SiatError detallado.

Es compatible con cualquier objeto de respuesta del SDK (RespuestaCuis, RespuestaRecepcion, etc.) utilizando reflexión para extraer los campos 'Transaccion' y 'MensajesList'.

Ejemplo:

resp, err := s.Codigos().VerificarNit(ctx, cfg, req)
if err != nil { return err } // Error de red
if err := siat.Verify(resp.Body.Content.RespuestaCuis); err != nil {
    return err // Error del SIAT (ej: NIT inválido)
}

Types

type Config

type Config = ports.Config

Config agrupa la configuración necesaria para realizar solicitudes autenticadas al SIAT. Es un alias a ports.Config y debe ser instanciada cuando se realicen llamadas a los servicios.

Campos:

• Token: Token de autenticación proporcionado por el SIAT (obligatorio)
• UserAgent: Identificador del cliente HTTP (opcional, pero recomendado para registro)

Ejemplo:

cfg := siat.Config{
	Token: "tu_token_api",
	UserAgent: "MyApp/1.0 (Bolivia)",
}

type HTTPConfig

type HTTPConfig = services.HTTPConfig

HTTPConfig es la configuración pública para personalizar el cliente HTTP del SDK. Permite que los usuarios customicen timeouts, connection pooling y TLS sin pasar su propio http.Client.

Campos principales:

• Timeout: Timeout total para solicitudes (default: 45s)
• MaxIdleConns: Pool global de conexiones ociosas (default: 100)
• MaxConnsPerHost: Conexiones simultáneas por host (default: 10)
• TLSMinVersion: Versión mínima de TLS (default: TLS 1.2)

Ejemplo:

cfg := siat.HTTPConfig{
	Timeout:         60 * time.Second,
	MaxConnsPerHost: 5,
}
client := siat.NewHTTPClient(cfg)
s, _ := siat.New(baseUrl, client)

func DefaultHTTPConfig

func DefaultHTTPConfig() HTTPConfig

DefaultHTTPConfig retorna la configuración HTTP recomendada para producción.

Valores:

• Timeout: 45 segundos
• MaxIdleConns: 100
• MaxConnsPerHost: 10
• MaxIdleConnsPerHost: 5
• TLSMinVersion: TLS 1.2

Esta es la configuración usada por defecto si no pasas un http.Client a New().

type HTTPMiddleware

type HTTPMiddleware = middleware.HTTPMiddleware

HTTPMiddleware es la interfaz pública que permite agregar comportamiento HTTP personalizado. Los usuarios pueden implementarla para agregar logging, métricas, retry, etc. sin necesidad de modificar el SDK.

Ejemplo: Implementar retry con exponential backoff:

type RetryMiddleware struct {
    maxAttempts int
}

func (m *RetryMiddleware) WrapTransport(base http.RoundTripper) http.RoundTripper {
    return &retryRoundTripper{
        base: base,
        maxAttempts: m.maxAttempts,
    }
}

// Uso
s, err := siat.NewWithMiddleware(
    baseUrl,
    nil, // usa defaults
    &RetryMiddleware{maxAttempts: 3},
)

type Map

type Map map[string]interface{}

Map es un alias para map[string]interface{} que proporciona métodos de utilidad para trabajar con datos JSON de forma más cómda. Es especialmente útil al trabajar con respuestas heterogéneas del SIAT.

func (Map) Sum

func (m Map) Sum() float64

Sum retorna la suma de todos los valores numéricos en el Map. Soporta tipos float64, float32, int, int64 e int32. Los valores no numéricos se ignoran.

func (Map) ToJSON

func (m Map) ToJSON() (string, error)

ToJSON convierte el Map a su representación en string JSON. Retorna un error si la codificación falla.

func (Map) ToStruct

func (m Map) ToStruct(v interface{}) error

ToStruct convierte el Map en la estructura Go especificada. Utiliza encoding/json internamente, por lo que se requiere que v sea un puntero a una estructura con etiquetas json apropiadas.

type SiatError

type SiatError = errors.SiatError

SiatError es el tipo de error que retorna el SDK. Permite al usuario distinguir entre diferentes tipos de errores: - Errores de red (timeout, conexión rechazada) - Errores del servidor SIAT (validaciones rechazadas) - Errores de autenticación (token inválido) - Y saber cuáles pueden/deben ser reintentados

Ejemplo:

resp, err := s.Codigos().SolicitudCuis(ctx, cfg, req)
if err != nil {
    var siatErr *siat.SiatError
    if errors.As(err, &siatErr) {
        if siat.IsRetryable(err) {
            // Reintentar después
        } else if siat.IsNetworkError(err) {
            // Error temporal de conexión
        } else {
            // Error del servidor o autenticación
        }
    }
}

func NewAuthError

func NewAuthError(msg string) *SiatError

NewAuthError crea un error de autenticación. No tiene sentido reintentar sin credentials válidas.

func NewNetworkError

func NewNetworkError(msg string, err error) *SiatError

NewNetworkError crea un error de red (timeout, connection refused, etc). Estos errores son reintentables.

func NewSiatError

func NewSiatError(code int, msg string) *SiatError

NewSiatError crea un error del servidor SIAT. Indica que el servidor rechazó la solicitud por alguna razón específica.

func NewTimeoutError

func NewTimeoutError(msg string) *SiatError

NewTimeoutError crea un error de timeout. Es reintentable porque es un problema temporal.

type SiatServices

type SiatServices struct {
	// contains filtered or unexported fields
}

SiatServices es el punto de entrada principal del SDK. Agrupa todas las implementaciones de los servicios del SIAT (Códigos, Sincronización, Operaciones, Compra-Venta, Computarizada, Electrónica) y proporciona acceso a ellos a través de métodos orientados a objetivos. Los usuarios deben crear una instancia usando New().

func New

func New(baseUrl string, httpClient *http.Client) (*SiatServices, error)

New crea e inicializa una nueva instancia de SiatServices.

Parámetros:

• baseUrl: URL base de los servicios SIAT (ej: https://pilotosiatservicios.impuestos.gob.bo/v2)
• httpClient: Cliente HTTP personalizado (opcional). Si es nil, se crea uno con configuración segura.

La función configura automáticamente:

• Timeouts apropiados (15s handshake, 45s total)
• TLS 1.2+ para seguridad
• Pools de conexión para alto rendimiento
• Proxy desde variables de entorno si están configuradas

Retorna un error si baseUrl está vacía o si alguno de los servicios falla al inicializarse.

Ejemplo:

s, err := siat.New("https://pilotosiatservicios.impuestos.gob.bo/v2", nil)
if err != nil {
	log.Fatal(err)
}

func NewWithMiddleware

func NewWithMiddleware(baseUrl string, httpClient *http.Client, middlewares ...HTTPMiddleware) (*SiatServices, error)

NewWithMiddleware crea una instancia de SiatServices con middlewares HTTP personalizados. Es útil para agregar logging, métricas, retry, circuit breaker, etc.

Parámetros:

• baseUrl: URL base del SIAT
• httpClient: Cliente HTTP (opcional, usa defaults si es nil)
• middlewares: Middlewares a aplicar en orden (primero = más externo)

Los middlewares se aplican al Transport del cliente, permitiendo interceptar todas las solicitudes.

Ejemplo completo con logging:

type LoggingMiddleware struct{}
func (LoggingMiddleware) WrapTransport(base http.RoundTripper) http.RoundTripper {
    return &loggingRoundTripper{base: base}
}
type loggingRoundTripper struct { base http.RoundTripper }
func (rt *loggingRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
    log.Printf("-> %s %s", req.Method, req.URL.Path)
    resp, err := rt.base.RoundTrip(req)
    if err == nil {
        log.Printf("<- %d", resp.StatusCode)
    }
    return resp, err
}

// Uso
s, err := siat.NewWithMiddleware(baseUrl, nil, &LoggingMiddleware{})

func (*SiatServices) Codigos

func (s *SiatServices) Codigos() ports.SiatCodigosService

Codigos retorna el servicio para: - Solicitud de códigos CUIS (Código Único de Identificación de Sistemas) - Solicitud de códigos CUFD (Código Único de Facturación por Dirección) - Validación de números NIT (Rol Tributario) Los códigos CUIS y CUFD son obligatorios para emitir invoices.

func (*SiatServices) CompraVenta

func (s *SiatServices) CompraVenta() ports.SiatCompraVentaService

CompraVenta retorna el servicio para el sector de compra-venta (Sector 1). Permite enviar, recibir y anular facturas comerciales estándar. Este es el sector más común para comercios generales.

func (*SiatServices) Computarizada

func (s *SiatServices) Computarizada() ports.SiatComputarizadaService

Computarizada retorna el servicio para facturación computarizada (sin firma digital, basada en máquinas registradoras fiscales). Permite enviar, recibir y anular facturas de este tipo.

func (*SiatServices) Electronica

func (s *SiatServices) Electronica() ports.SiatElectronicaService

Electronica retorna el servicio para facturación electrónica (con firma digital). Permite enviar, recibir y anular facturas electrónicas de todos los sectores. Este es el tipo de facturación más moderno y flexible del SIAT.

func (*SiatServices) Operaciones

func (s *SiatServices) Operaciones() ports.SiatOperacionesPort

Operaciones retorna el servicio para la gestión de puntos de venta (PV), cierre de períodos de facturación y eventos significativos (cambios de modalidad, etc.).

func (*SiatServices) Sincronizacion

func (s *SiatServices) Sincronizacion() ports.SiatSincronizacionService

Sincronizacion retorna el servicio que proporciona acceso a catálogos maestros: actividades económicas, documentos fiscales, monedas, tipos de cambio, etc. Estos catálogos son esenciales para validar datos antes de emitir invoices.

func (*SiatServices) WithConfig

func (s *SiatServices) WithConfig(token string) ports.Config

WithConfig retorna una nueva instancia de ports.Config con el traceID actual. Esto permite que el usuario establezca el traceID una sola vez con WithTraceID() y que automáticamente se inyecte en todas las solicitudes posteriores.

El usuario debe proporcionar el Token de autenticación del SIAT. El UserAgent se establece en una cadena vacía y puede ser personalizado.

Parámetros:

• token: El token de autenticación del SIAT (obligatorio)

Retorna:

• ports.Config con TraceID pre-establecido

Ejemplo:

s.WithTraceID("trace-12345")
config := s.WithConfig("myToken123")
// config.TraceID es "trace-12345" automáticamente

func (*SiatServices) WithTraceID

func (s *SiatServices) WithTraceID(id string) *SiatServices

WithTraceID establece un ID de seguimiento (trace ID) para correlacionar solicitudes en sistemas distribuidos. El trace ID se inyecta en el encabezado HTTP "X-Trace-ID" en todas las solicitudes posteriores.

El trace ID es completamente opcional y no afecta la funcionalidad del SDK si no se proporciona. Es útil para:

• Correlacionar logs entre múltiples servicios
• Rastrear solicitudes a través de sistemas distribuidos
• Debugging de problemas en producción

Parámetros:

• id: El ID de seguimiento (puede estar vacío para limpiar el trace ID anterior)

Retorna el receptor (SiatServices) para permitir encadenamiento de métodos.

Ejemplo:

s.WithTraceID("trace-12345-dev").Operaciones()...
// El trace-12345-dev se incluirá en el encabezado X-Trace-ID de todas las solicitudes