API-SIRE 🇵🇪

API REST en Go para integración con el Sistema Integrado de Registros Electrónicos (SIRE) de SUNAT - Perú.

Permite gestionar los Registros de Ventas (RVIE) y Compras electrónicos mediante los servicios web oficiales de SUNAT.

📋 Requisitos Previos

• Go 1.20 o superior
• Credenciales SUNAT: CLIENT_ID y CLIENT_SECRET del Portal de Desarrolladores SUNAT
• Usuario SOL con permisos para facturación electrónica

🚀 Instalación

# Clonar el repositorio
git clone https://github.com/SwodLore/API-SIRE.git
cd API-SIRE

# Instalar dependencias
go mod download

# Configurar variables de entorno
cp .env.example .env
# Editar .env con tus credenciales reales

⚙️ Configuración

Crea un archivo .env en la raíz del proyecto con las siguientes variables:

Variable	Descripción
CLIENT_ID	ID de cliente de la API SUNAT
CLIENT_SECRET	Secreto del cliente API SUNAT
RUC	Número de RUC del contribuyente (11 dígitos)
USUARIO	Usuario SOL
CLAVE_SOL	Clave SOL

🏃 Ejecución

# Modo desarrollo (con hot-reload usando Air)
air

# Modo estándar
go run main.go

El servidor se iniciará en http://localhost:8080

📚 Endpoints Disponibles

🔐 Autenticación

Método	Endpoint	Descripción
GET	/api/sunat/auth/obtener-token	Obtener token usando variables de entorno
POST	/api/sunat/auth/login	Obtener token con credenciales en body

Login (Recomendado)

POST /api/sunat/auth/login
Content-Type: application/json

{
  "ruc": "20123456789",
  "usuarioSol": "USUARIO",
  "claveSol": "clave123"
}

Respuesta:

{
  "access_token": "eyJraWQ..."
}

⚠️ El token expira en 1 hora. Debes obtener uno nuevo cuando expire.

---

📊 Registro de Ventas (RVIE)

Todos los endpoints de ventas requieren el header Authorization: Bearer <token>

Consultas y Descargas

Método	Endpoint	Descripción
GET	/api/sunat/ventas/periodos/:codLibro	Consultar periodos disponibles
GET	/api/sunat/ventas/descargar-propuesta/:perTributario	Descargar propuesta SUNAT
GET	/api/sunat/ventas/resumen-comprobantes/:perTributario	Resumen de comprobantes RVIE
GET	/api/sunat/ventas/descargar-no-incluidos/:perTributario	Descargar no incluidos
GET	/api/sunat/ventas/descargar-resumen/:perTributario/:codTipoResumen/:codTipoArchivo	Descargar resumen
GET	/api/sunat/ventas/exportar-preliminar-ventas/:perTributario	Exportar preliminar
GET	/api/sunat/ventas/consultar-estado-ticket	Consultar estado de ticket
GET	/api/sunat/ventas/descargar-archivo	Descargar archivo por ticket
GET	/api/sunat/ventas/constancia-recepcion	Constancia de recepción
GET	/api/sunat/ventas/rvie-periodo/:perTributario	RVIE por período
GET	/api/sunat/ventas/reporte-consolidado-periodo/:perTributario	Reporte consolidado
GET	/api/sunat/ventas/ajustes-posteriores/:perTributario	Ajustes posteriores
GET	/api/sunat/ventas/reporte-car/:perTributario	Reporte CAR
GET	/api/sunat/ventas/reporte-estadistico/:perTributario	Reporte estadístico
GET	/api/sunat/ventas/reporte-cumplimiento/:perTributario/:codLibro	Reporte cumplimiento
GET	/api/sunat/ventas/reporte-exportadores/:perTributario	Reporte exportadores

Importaciones y Registros

Método	Endpoint	Descripción
POST	/api/sunat/ventas/importar-reemplazo-propuesta/:perTributario	Importar reemplazo de propuesta
POST	/api/sunat/ventas/importar-nuevos-comprobantes/:perTributario	Importar nuevos comprobantes
POST	/api/sunat/ventas/importar-comprobantes-preliminar/:perTributario	Importar a preliminar
POST	/api/sunat/ventas/importar-ajustes-posteriores/:perTributario	Importar ajustes
POST	/api/sunat/ventas/aceptar-propuesta/:perTributario	Aceptar propuesta RVIE
POST	/api/sunat/ventas/registrar-preliminar/:perTributario	Registrar preliminar
POST	/api/sunat/ventas/exclusion-definitiva/:perTributario	Exclusión definitiva NC y facturas
POST	/api/sunat/ventas/tipo-cambio-masivo/:perTributario	Tipo de cambio masivo

Modificaciones y Eliminaciones

Método	Endpoint	Descripción
PUT	/api/sunat/ventas/editar-tipo-cambio/:perTributario	Editar tipo de cambio
PUT	/api/sunat/ventas/eliminar-comprobante-preliminar/:perTributario	Eliminar de preliminar
PUT	/api/sunat/ventas/eliminar-reemplazo/:perTributario	Eliminar reemplazo
PUT	/api/sunat/ventas/eliminapreliminar/:perTributario	Eliminar preliminar registrado
DELETE	/api/sunat/ventas/eliminar-comprobante/:perTributario	Eliminar comprobante propuesta

---

🛒 Registro de Compras (RCE)

Gestión de Propuesta

Método	Endpoint	Descripción
GET	/api/sunat/compras/libros/rce/periodos/:codLibro	Consultar períodos RCE
GET	/api/sunat/compras/libros/rce/propuesta/:perTributario/descargar	Descargar propuesta
POST	/api/sunat/compras/aceptarpropuesta/:perTributario	Aceptar propuesta
POST	/api/sunat/compras/reemplazo-propuesta/:perTributario	Importar reemplazo propuesta
POST	/api/sunat/compras/importar-comprobantes-propuesta/:perTributario	Importar nuevos comprobantes
POST	/api/sunat/compras/importar-complemento-propuesta/:perTributario	Importar datos complementarios
POST	/api/sunat/compras/incluir-excluir-propuesta/:perTributario	Incluir/excluir comprobantes
DELETE	/api/sunat/compras/eliminar-comprobante-propuesta/:perTributario	Eliminar comprobante de propuesta
POST	/api/sunat/compras/comparar-documentos/:perTributario	Comparar registro con propuesta

Datos FV621 (Formulario Virtual 621)

Método	Endpoint	Descripción
PUT	/api/sunat/compras/actualizar-coeficiente-prorrata/:perTributario	Actualizar coeficiente de prorrata
PUT	/api/sunat/compras/actualizar-reintegro-credito/:perTributario	Actualizar reintegro del crédito fiscal
PUT	/api/sunat/compras/actualizar-credito-fiscal-especial/:perTributario	Actualizar crédito fiscal especial
GET	/api/sunat/compras/consultar-fv0621	Consultar datos FV621

Tipo de Cambio

Método	Endpoint	Descripción
POST	/api/sunat/compras/importar-tipo-cambio-masivo/:perTributario/:codLibro	Importar tipo de cambio masivo (archivo)

Preliminares

Método	Endpoint	Descripción
POST	/api/sunat/compras/registrar-preliminar/:perTributario	Registrar preliminar
POST	/api/sunat/compras/importar-comprobantes-preliminar/:perTributario	Importar comprobantes a preliminar
POST	/api/sunat/compras/eliminar-comprobante-preliminar/:perTributario	Eliminar comprobante del preliminar
PUT	/api/sunat/compras/eliminar-preliminar/:perTributario/:indEliminar	Eliminar preliminar

Generación de Registros

Método	Endpoint	Descripción
POST	/api/sunat/compras/generar-registro-correlativo/:perTributario	Generar RVIE y RCE de manera correlativa

Nota: perTributario tiene formato YYYYMM (ej: 202501 para enero 2025)

---

🔄 Flujo de Uso Recomendado

1. POST /api/sunat/auth/login         → Obtener token
2. GET /api/sunat/ventas/periodos/14  → Consultar periodos disponibles
3. GET /api/sunat/ventas/resumen-comprobantes/202501?codTipoResumen=1  → Ver resumen
4. GET /api/sunat/ventas/descargar-propuesta/202501?codTipoArchivo=0   → Descargar propuesta
5. POST /api/sunat/ventas/aceptar-propuesta/202501  → Aceptar propuesta

Ejemplo con cURL

# 1. Obtener token
TOKEN=$(curl -s -X POST http://localhost:8080/api/sunat/auth/login \
  -H "Content-Type: application/json" \
  -d '{"ruc":"20123456789","usuarioSol":"USUARIO","claveSol":"clave123"}' \
  | jq -r '.access_token')

# 2. Consultar resumen de comprobantes
curl -X GET "http://localhost:8080/api/sunat/ventas/resumen-comprobantes/202501?codTipoResumen=1" \
  -H "Authorization: Bearer $TOKEN"

# 3. Descargar propuesta
curl -X GET "http://localhost:8080/api/sunat/ventas/descargar-propuesta/202501?codTipoArchivo=0" \
  -H "Authorization: Bearer $TOKEN"

---

📁 Estructura del Proyecto

API-SIRE/
├── main.go              # Punto de entrada
├── AUTH/                # Módulo de autenticación OAuth2
│   ├── controller.go    # LoginController, ObtenerTokenController
│   ├── routes.go        # /api/sunat/auth/*
│   └── service.go       # ObtenerTokenService
├── VENTAS/              # Módulo Registro de Ventas (RVIE)
│   ├── controllers/
│   │   ├── controllers.go
│   │   └── resumen_controller.go
│   ├── models/
│   ├── routes/
│   └── services/
│       ├── services.go
│       └── resumen_service.go
├── COMPRAS/             # Módulo Registro de Compras (RCE)
│   ├── controllers/
│   ├── models/
│   ├── routes/
│   └── services/
├── .air.toml            # Configuración hot-reload
├── .env.example         # Ejemplo de variables de entorno
├── go.mod               
└── go.sum               

🛠️ Tecnologías

• Gin - Framework web
• Resty - Cliente HTTP
• godotenv - Carga de variables de entorno
• Air - Hot-reload para desarrollo

📖 Documentación SUNAT

• API SIRE - Documentación Oficial
• Manual de Desarrolladores SIRE

⚠️ Notas Importantes

• El token expira en 1 hora, usa /api/sunat/auth/login para renovarlo
• Los errores 401 indican token expirado o inválido
• Los errores 422 son normales al probar con datos no reales
• El formato de perTributario es YYYYMM (ej: 202501)
• codTipoArchivo: 0 = JSON, 1 = TXT

📄 Licencia

MIT License - Ver LICENSE para más detalles.

---

Desarrollado con ❤️ para la comunidad de desarrolladores peruanos.