# Sifende Docs

- [Introducción](/docs): Documentación oficial de la API de Sifende — facturación electrónica para Paraguay vía SIFEN.
- La Plataforma
  - [La Plataforma](/docs/plataforma): Sifende es la plataforma SaaS que conecta tu negocio con e-kuatia de la DNIT — emisión, firma, transmisión y seguimiento de documentos electrónicos vía una API REST simple.
  - [Cómo Funciona](/docs/plataforma/como-funciona): De cero a un CDC aprobado por la DNIT en tres pasos — registrate y configurá, enviá un JSON a la API y recibí el documento aprobado.
  - [Características](/docs/plataforma/caracteristicas): Todo lo que incluye Sifende — conexión automatizada con e-kuatia, todos los tipos de DE, procesamiento por lotes, panel web, API keys, multi-usuario y notificaciones por email.
  - [Planes y Precios](/docs/plataforma/planes): Cuatro planes de Sifende — Starter (gratis), Professional, Business y Enterprise. Precios por contribuyente (RUC) por mes, en guaraníes y sin contratos a largo plazo.
- Inicio Rápido
  - [Inicio Rápido](/docs/inicio-rapido): Emití tu primera Factura Electrónica con Sifende en aproximadamente 15 minutos.
  - [Requisitos Previos](/docs/inicio-rapido/requisitos-previos): Qué necesitás tener antes de integrar Sifende — certificado digital, CSC, timbrado electrónico y ambiente de pruebas.
  - [Paso 1: Configurar Credenciales](/docs/inicio-rapido/paso-1-credenciales): Subí tu certificado digital, configurá el timbrado y obtené tu API key para empezar a emitir documentos.
  - [Paso 2: Tu Primera Factura Electrónica](/docs/inicio-rapido/paso-2-primera-factura): Emití tu primera Factura Electrónica
  - [Paso 3: Verificar el Estado](/docs/inicio-rapido/paso-3-verificar-estado): Consultá el estado de procesamiento de tu documento en SIFEN usando el CDC.
  - [Paso 4: Ir a Producción](/docs/inicio-rapido/paso-4-produccion): Checklist para pasar tu integración de Sifende al ambiente de producción.
- Herramientas
  - [Herramientas](/docs/herramientas): Herramientas oficiales para integrarte con la API de Sifende sin escribir código de bajo nivel.
  - [Sifende CLI](/docs/herramientas/sifende-cli): CLI en Python para emitir documentos electrónicos, consultar estado, descargar KuDE, cancelar e inutilizar contra la API de Sifende desde la terminal.
- Conceptos
  - [Conceptos](/docs/conceptos): Los modelos mentales que necesitás entender para integrar Sifende correctamente.
  - [Cómo Funciona Sifende](/docs/conceptos/como-funciona): Arquitectura general de Sifende — tu sistema, la API, SIFEN y el flujo completo de un documento electrónico.
  - [Autenticación](/docs/conceptos/autenticacion): Los dos modos de autenticación en Sifende — API key para integraciones ERP y Keycloak JWT para frontends personalizados.
  - [Contribuyente](/docs/conceptos/contribuyente): Qué es un contribuyente en Sifende — la entidad jurídica que emite documentos electrónicos.
  - [Documentos Electrónicos](/docs/conceptos/documentos-electronicos): Los tipos de documentos electrónicos que podés emitir con Sifende y su estado de disponibilidad.
  - [Timbrado y Numeración](/docs/conceptos/timbrado-numeracion): Qué es el timbrado electrónico, cómo se relaciona con los establecimientos y cómo se forma el número de documento.
  - [Receptor](/docs/conceptos/receptor): Quién recibe el documento — diferencias entre B2B (contribuyente con RUC) y B2C (persona física o innominado).
  - [Ítems e IVA](/docs/conceptos/items-iva): Cómo estructurar los ítems de un documento — descripción, cantidad, precio, afectación tributaria y tasas de IVA en Paraguay.
  - [Ciclo de Vida de un Documento](/docs/conceptos/ciclo-de-vida): Qué pasa después de emitir un documento — los estados por los que pasa hasta su aprobación o rechazo por SIFEN.
  - [CDC (Código de Control)](/docs/conceptos/cdc): Qué es el CDC, cómo se estructura y por qué es el identificador más importante de tus documentos electrónicos.
  - [Lotes](/docs/conceptos/lotes): Cómo agrupa Sifende los documentos en lotes para enviarlos a SIFEN y qué estados tiene un lote.
  - [Eventos SIFEN](/docs/conceptos/eventos-sifen): Los eventos que podés enviar a SIFEN sobre un documento ya aprobado — cancelación e inutilización de numeración.
  - [Ambientes](/docs/conceptos/ambientes): Ambiente de pruebas (QA) y producción en Sifende — URLs, credenciales y diferencias de comportamiento.
- Guías
  - [Guías](/docs/guias): Guías prácticas paso a paso para los flujos más comunes de integración con Sifende.
  - [Factura Electrónica](/docs/guias/factura-electronica): Guía completa para emitir una Factura Electrónica con datos del receptor B2C o B2B, ítems, condición de pago y ejemplos de request completo.
  - [Receptor B2B y B2C](/docs/guias/receptor-b2b-b2c): Cómo estructurar el receptor para facturas a otros contribuyentes (B2B con RUC) vs. consumidores finales (B2C) y documentos innominados.
  - [Consultar Estado de un Documento](/docs/guias/consultar-estado): Cómo verificar si un documento fue aprobado o rechazado por SIFEN usando el CDC, con la estrategia de polling recomendada.
  - [Manejar Errores](/docs/guias/manejar-errores): Cómo interpretar y manejar errores de la API de Sifende y rechazos de SIFEN en tu integración.
  - [Nota de Crédito Electrónica](/docs/guias/nota-credito): Cómo emitir una Nota de Crédito (NCE) para anular total o parcialmente una factura aprobada.
  - [Nota de Débito Electrónica](/docs/guias/nota-debito): Cómo emitir una Nota de Débito (NDE) para incrementar el monto de una factura aprobada.
  - [Descargar KuDE](/docs/guias/descargar-kude): Cómo obtener el KuDE (comprobante PDF) de un documento aprobado para entregarlo al cliente.
  - [Cancelar un Documento](/docs/guias/cancelar-documento): Cómo cancelar una Factura Electrónica o Nota de Crédito ya aprobada enviando el evento de cancelación a SIFEN.
  - [Inutilizar Numeración](/docs/guias/inutilizar-numeracion): Cómo inutilizar rangos de números de documento no utilizados para cumplir con la normativa de la SET.
  - [Polling de Resultados SIFEN](/docs/guias/polling-resultados): Estrategia de polling para monitorear el estado de procesamiento de documentos en SIFEN, con intervalos, backoff y manejo de timeouts.
  - [Facturar en Moneda Extranjera](/docs/guias/moneda-extranjera): Cómo emitir facturas en dólares (USD) u otras monedas, con tipo de cambio, monedaOperacion y totales en PYG.
  - [Múltiples Establecimientos](/docs/guias/multiples-establecimientos): Cómo gestionar varias sucursales con diferentes números de establecimiento y puntos de expedición.
  - [Reintentar Documentos Rechazados](/docs/guias/reintentar-rechazados): Flujo completo para corregir un documento rechazado por SIFEN y reemitirlo con un nuevo CDC.
  - [Ir a Producción](/docs/guias/ir-a-produccion): Checklist completo para pasar tu integración de Sifende al ambiente de producción — credenciales, manejo de errores y pruebas finales.
- Referencia API
  - [Referencia API](/docs/referencia): Documentación completa de todos los endpoints de la API de Sifende — schemas, ejemplos de código y referencia de errores.
  - [Autenticación](/docs/referencia/autenticacion): Cómo autenticarte con la API de Sifende — API key para integraciones ERP y Keycloak JWT para frontends personalizados.
  - [Convenciones](/docs/referencia/convenciones): Convenciones específicas de Paraguay en la API de Sifende — formato de RUC, montos en guaraníes, fechas, CDC y numeración de documentos.
  - [Errores](/docs/referencia/errores): Referencia completa de errores de la API de Sifende — formato Problem Details, tipos de error y códigos de rechazo de SIFEN.
  - [Enumeraciones](/docs/referencia/enumeraciones): Todos los valores válidos de las enumeraciones SIFEN usadas en la API de Sifende — tipoDocumento, afectacionTributaria, condicionPago y más.
  - [Versionado](/docs/referencia/versionado): Política de versionado de la API de Sifende — versiones, breaking changes y deprecaciones.
  - [Changelog](/docs/referencia/changelog): Historial de cambios de la API de Sifende — nuevas funcionalidades, correcciones y breaking changes.
  - Documentos Electrónicos
    - [Documentos Electrónicos](/docs/referencia/documentos-electronicos): API de emisión, consulta y gestión de documentos electrónicos — el núcleo de la integración con Sifende.
    - [Emitir Documento Electrónico](/docs/referencia/documentos-electronicos/emitir): POST /api/v1/documento-electronico — emite cualquier tipo de documento electrónico (FE, NCE, NDE) y retorna un DTO con el CDC y URLs de seguimiento.
    - [Consultar Estado](/docs/referencia/documentos-electronicos/consultar-estado): GET /api/v1/documento-electronico/status/:cdc — consultá el estado de procesamiento de un documento electrónico por CDC.
    - [Descargar KuDE](/docs/referencia/documentos-electronicos/descargar-kude): GET /api/v1/documento-electronico/:cdc/kude — descargá el KuDE (comprobante) en formato PDF de un documento aprobado.
    - [Cancelar Documento](/docs/referencia/documentos-electronicos/cancelar): POST /api/v1/documento-electronico/:cdc/cancelar — enviá el evento de cancelación a SIFEN para un documento aprobado.
    - [Inutilizar Numeración](/docs/referencia/documentos-electronicos/inutilizar): POST /api/v1/documento-electronico/inutilizar — inutilizá rangos de números de documento no utilizados.
  - Modelos de Datos
    - [Modelos de Datos](/docs/referencia/modelos): Schemas completos de los modelos de request para cada tipo de documento electrónico y sus entidades relacionadas.
    - [Factura Electrónica](/docs/referencia/modelos/factura-electronica): Schema completo del request para emitir una Factura Electrónica (FE) con Sifende.
    - [Nota de Crédito Electrónica](/docs/referencia/modelos/nota-credito): Schema del request para emitir una Nota de Crédito Electrónica (NCE) que hace referencia a una Factura Electrónica aprobada.
    - [Nota de Débito Electrónica](/docs/referencia/modelos/nota-debito): Schema del request para emitir una Nota de Débito Electrónica (NDE) que incrementa el monto de una factura aprobada.
    - [Autofactura Electrónica](/docs/referencia/modelos/autofactura): Schema del request para emitir una Autofactura Electrónica (AFE).
    - [Nota de Remisión Electrónica](/docs/referencia/modelos/nota-remision): Schema del request para emitir una Nota de Remisión Electrónica (NRE).
    - [Receptor](/docs/referencia/modelos/receptor): Schema del objeto receptor — datos del destinatario del documento para operaciones B2B y B2C.
    - [Ítem](/docs/referencia/modelos/item): Schema de un ítem de línea — producto o servicio incluido en el documento electrónico con su afectación tributaria.
    - [Condición de Pago](/docs/referencia/modelos/condicion-pago): Schema de la condición de pago — contado con medio de pago o crédito con cuotas.
    - [Documento Asociado](/docs/referencia/modelos/documento-asociado): Schema del documento asociado — referencia a la factura original para notas de crédito y débito.
  - Eventos SIFEN
    - [Eventos SIFEN](/docs/referencia/eventos): Consulta de eventos SIFEN — cancelaciones e inutilizaciones enviadas a través de la API.
    - [Listar Eventos](/docs/referencia/eventos/listar): GET /eventos — paginá los eventos SIFEN (cancelaciones e inutilizaciones) de un contribuyente.
    - [Detalle de Evento](/docs/referencia/eventos/detalle): GET /eventos/:eventoId — obtené el detalle completo de un evento SIFEN.
  - API Keys
    - [API Keys](/docs/referencia/api-keys): Gestión del ciclo de vida de los API keys — creación, rotación y revocación de claves de integración.
    - [Crear API Key](/docs/referencia/api-keys/crear): POST /api/v1/contribuyentes/:contribuyenteId/api-keys — creá un nuevo API key para autenticar llamadas de integración.
    - [Listar API Keys](/docs/referencia/api-keys/listar): GET /api/v1/contribuyentes/:contribuyenteId/api-keys — obtené todos los API keys de un contribuyente.
    - [Rotar API Key](/docs/referencia/api-keys/rotar): POST /api/v1/contribuyentes/:contribuyenteId/api-keys/:id/rotar — generá un nuevo secreto y revocá el anterior.
    - [Eliminar API Key](/docs/referencia/api-keys/eliminar): DELETE /api/v1/contribuyentes/:contribuyenteId/api-keys/:id — revocá permanentemente un API key.
  - Catálogos
    - [Enumeraciones SIFEN (Endpoint)](/docs/referencia/catalogos/enumeraciones): GET /api/v1/public/enums — lista todos los valores válidos de las enumeraciones SIFEN en tiempo real.
    - [Geografía](/docs/referencia/catalogos/geografia): GET /api/v1/geografia — departamentos, distritos y ciudades de Paraguay para autocompletar direcciones.
    - [Actividades Económicas](/docs/referencia/catalogos/actividades-economicas): GET /api/v1/actividades-economicas — árbol de códigos CIIU para asociar a un contribuyente.
  - API de Sesión
    - [API de Sesión](/docs/referencia/sesion): Endpoints de sesión Keycloak para el panel web y frontends personalizados sobre Sifende.
    - [Contribuyentes](/docs/referencia/sesion/contribuyentes): Endpoints de sesión para gestión de contribuyentes (entidades emisoras) via autenticación Keycloak JWT.
    - [Certificado Digital](/docs/referencia/sesion/certificado): Subida del certificado digital PKCS12 y Código de Seguridad del Contribuyente (CSC) por sesión Keycloak.
    - [Timbrado](/docs/referencia/sesion/timbrado): Endpoints de sesión para gestión del timbrado electrónico (autorización SET) por contribuyente.
    - [Lotes](/docs/referencia/sesion/lotes): Endpoints de sesión para consulta de lotes y transmisiones SIFEN del contribuyente.
    - [Documentos Electrónicos (Sesión)](/docs/referencia/sesion/documentos): Endpoints de sesión para listar, consultar, descargar XML/KuDE y revisar el historial de lotes de cada documento.
    - [Usuarios](/docs/referencia/sesion/usuarios): Endpoints de sesión para perfil del usuario autenticado y gestión de miembros del equipo por contribuyente.
    - [Métricas](/docs/referencia/sesion/metricas): Endpoint de sesión que devuelve KPIs agregados del contribuyente para alimentar dashboards.
- Solución de Problemas
  - [Solución de Problemas](/docs/solucion-problemas): Guía de diagnóstico para los errores más comunes en integraciones con Sifende y SIFEN.
  - [Rechazos SIFEN](/docs/solucion-problemas/rechazos-sifen): Códigos de rechazo de SIFEN — causa de cada error y cómo corregirlo en tu solicitud, organizados por categoría.
  - [Errores Comunes](/docs/solucion-problemas/errores-comunes): Los errores más frecuentes al integrar con la API de Sifende — causa y solución para cada uno.
  - [Certificado Digital](/docs/solucion-problemas/certificado-digital): Problemas comunes con el certificado digital — vencimiento, contraseña incorrecta y formato inválido.
  - [Preguntas Frecuentes](/docs/solucion-problemas/faq): Respuestas a las preguntas más frecuentes sobre Sifende, su integración con SIFEN y los planes de la plataforma.
  - [Soporte](/docs/solucion-problemas/soporte): Cómo contactar al equipo de soporte de Sifende.