# Factura Electrónica (/docs/guias/factura-electronica)



Una Factura Electrónica (FE) se emite con un `POST /api/v1/documento-electronico` y `tipoDocumento: "FACTURA_ELECTRONICA"`. Esta guía va desde la solicitud hasta el seguimiento del estado en SIFEN.

## Antes de empezar [#antes-de-empezar]

Verificá que tenés los tres elementos imprescindibles configurados:

* **Timbrado activo** y vigente, cargado en el panel de Sifende para tu contribuyente.
* **Certificado digital** subido: `.p12` válido y en vigencia.
* **API key** generada desde el panel y disponible como variable de entorno.

Si te falta alguno, volvé a [Inicio Rápido: Requisitos previos](/docs/inicio-rapido/requisitos-previos).

## Paso 1: Prepará la solicitud [#paso-1-prepará-la-solicitud]

La FE usa el endpoint polimórfico `POST /api/v1/documento-electronico` con `tipoDocumento: "FACTURA_ELECTRONICA"`. Los datos del **emisor** los completa Sifende automáticamente desde el contribuyente y el timbrado configurados. Vos solo pasás los datos del receptor, los ítems y la condición de pago.

Ejemplo de FE B2C **innominada** (consumo final menos de Gs. 7.000.000) con un solo ítem gravado al 10%. El caso innominado se indica con `tipoContribuyente: "NO_CONTRIBUYENTE"` + `tipoDocumento: "INNOMINADO"`, y con los valores literales `"0"` en `numeroDocumento` y `"Sin Nombre"` en `nombreRazonSocial`:

```json
{
  "tipoDocumento": "FACTURA_ELECTRONICA",
  "fechaEmision": "2026-04-27T10:30:00",
  "tipoEmision": "NORMAL",
  "numeroEstablecimiento": 1,
  "puntoExpedicion": 1,
  "tipoTransaccion": "VENTA_MERCADERIA",
  "monedaOperacion": "PYG",
  "receptor": {
    "tipoContribuyente": "NO_CONTRIBUYENTE",
    "tipoOperacion": "B2C",
    "tipoDocumento": "INNOMINADO",
    "numeroDocumento": "0",
    "nombreRazonSocial": "Sin Nombre"
  },
  "condicionOperacion": "CONTADO",
  "condicionPago": {
    "tipo": "CONTADO",
    "tipoPago": "EFECTIVO",
    "monedaPago": "PYG",
    "montoPago": 150000
  },
  "items": [
    {
      "codigo": "PROD-A4-75",
      "descripcion": "Resma de papel A4 75g",
      "cantidad": 10,
      "unidadMedida": "UNI",
      "precioUnitario": 15000,
      "afectacionTributaria": "GRAVADO",
      "tasaIVA": 10
    }
  ]
}
```

<Callout type="info">
  Los montos en guaraníes son **enteros sin decimales**. `15000` representa Gs. 15.000. Ver [Convenciones](/docs/referencia/convenciones).
</Callout>

## Paso 2: Enviá la solicitud [#paso-2-enviá-la-solicitud]

<Tabs>
  <Tab value="curl" label="cURL">
    ```bash
    curl -X POST https://api.sifende.com.py/api/v1/documento-electronico \
      -H "Authorization: Bearer $SIFENDE_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
      -d @factura.json
    ```
  </Tab>

  <Tab value="typescript" label="TypeScript">
    ```typescript
    const idempotencyKey = await obtenerOCrearClaveDeEmision(ventaId);

    const response = await fetch(
      'https://api.sifende.com.py/api/v1/documento-electronico',
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.SIFENDE_API_KEY}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey,
        },
        body: JSON.stringify(facturaPayload),
      }
    );

    if (!response.ok) {
      const problem = await response.json();
      throw new Error(`${problem.title}: ${problem.detail}`);
    }

    const { id, cdc, estado, statusUrl, kudeUrl } = await response.json();
    console.log('CDC emitido:', cdc, ', estado inicial:', estado);
    ```
  </Tab>
</Tabs>

<Callout type="warn">
  No generes una clave dentro de cada intento: otra clave representa una emisión nueva y puede reservar otro correlativo. Para recuperar una respuesta perdida, reutilizá la clave y el body persistidos.
</Callout>

## Paso 3: Guardá la respuesta [#paso-3-guardá-la-respuesta]

La respuesta exitosa es &#x2A;*`202 Accepted`** con un body que incluye los identificadores del DE creado:

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cdc": "01800123451001001000000122026042710000000006",
  "estado": "PENDIENTE",
  "ambiente": "DEV",
  "tipoDocumento": "FACTURA_ELECTRONICA",
  "iTiDe": 1,
  "numeroDocumento": 1,
  "numeroFormateado": "001-001-0000001",
  "fechaCreacion": "2026-04-27T10:30:00",
  "qrUrl": "https://ekuatia.set.gov.py/consultas-test/qr?...",
  "statusUrl": "https://api.sifende.com.py/api/v1/documento-electronico/status/01800123451001001000000122026042710000000006",
  "kudeUrl": "https://api.sifende.com.py/api/v1/documento-electronico/01800123451001001000000122026042710000000006/kude"
}
```

<Callout type="info">
  **`estado: "PENDIENTE"` es lo esperado.** SIFEN procesa el documento de forma asíncrona: el CDC ya es válido, pero la aprobación llega en segundos a minutos. Pasá al Paso 4 para verificar.
</Callout>

Guardá `id`, `cdc`, `numeroFormateado` y la `Idempotency-Key` asociados a tu venta.

* Consultar el estado de procesamiento en SIFEN (usá `statusUrl` o el `cdc`).
* Descargar el KuDE (PDF) cuando esté aprobado (usá `kudeUrl`).
* Cancelar el documento si fuera necesario.

## Paso 4: Esperá el resultado de SIFEN [#paso-4-esperá-el-resultado-de-sifen]

SIFEN procesa los documentos de forma **asíncrona**. Apenas recibís el CDC, el estado es `PENDIENTE` o `EN_LOTE`. El procesamiento tarda habitualmente entre 15 y 60 segundos, pero puede superar los 2 minutos en el ambiente de QA. Implementá polling con timeout de al menos 5 minutos.

Los detalles de la estrategia de polling están en [Consultar Estado de un Documento](/docs/guias/consultar-estado).

## Más allá de la factura simple [#más-allá-de-la-factura-simple]

La solicitud de este ejemplo cubre una venta al contado con un solo medio de pago. La misma factura admite, sin cambiar de endpoint:

* **Varios medios de pago**, datos de tarjeta o cheque y medios `OTRO` descritos: usá [`pagos`](/docs/referencia/modelos/condicion-pago#forma-completa-pagos-y-credito). Al contado, los pagos deben cubrir exactamente el total.
* **Crédito con cuotas o plazo**, en cualquier moneda, con entrega inicial. Las cuotas deben sumar el saldo financiado.
* **Notas de remisión y facturas de anticipo asociadas**, con el anticipo aplicado global o por ítem: ver [Documentos asociados y anticipos](/docs/referencia/modelos/factura-electronica#documentos-asociados-y-anticipos).
* **Datos del ítem** como GTIN, NCM, lote o vencimiento, ítems gravados parcialmente y vehículos nuevos: ver [Ítem](/docs/referencia/modelos/item).
* **Presencia del comprador, datos comerciales, sectores** (energía, seguros, supermercado), **transporte y carga**: ver [Factura Electrónica](/docs/referencia/modelos/factura-electronica#campos-específicos-de-fe).

Todo campo opcional que no aplica a tu operación se omite.

## Errores frecuentes en este flujo [#errores-frecuentes-en-este-flujo]

| Status | Tipo                       | Causa más común                                                  | Cómo resolverlo                                    |
| ------ | -------------------------- | ---------------------------------------------------------------- | -------------------------------------------------- |
| 400    | `validation-error`         | Falta un campo obligatorio o un valor está mal formateado        | Revisá `errores` en la respuesta                   |
| 400    | `invalid-enum-value`       | Valor de enum no reconocido (ej: `"INVOICE"` en `tipoDocumento`) | Revisá `valoresAceptados` en la respuesta          |
| 401    | JSON de autenticación      | API key inválida o revocada                                      | Rotá la credencial desde el panel, en **API Keys** |
| 422    | `configuracion-incompleta` | No hay timbrado configurado para este contribuyente              | Cargá el timbrado en el panel                      |

Para recuperar un timeout o interpretar errores de idempotencia, ver [Idempotencia y Reintentos Seguros](/docs/guias/idempotencia).

Para el listado completo, ver [Manejar Errores](/docs/guias/manejar-errores) y [Rechazos SIFEN](/docs/solucion-problemas/rechazos-sifen).

## Próximos pasos [#próximos-pasos]

* Si facturás a una empresa con RUC → [Receptor B2B y B2C](/docs/guias/receptor-b2b-b2c).
* Si necesitás anular o ajustar una FE aprobada → [Nota de Crédito](/docs/guias/nota-credito).
* Si querés entregar el comprobante al cliente → [Descargar KuDE](/docs/guias/descargar-kude).
