Emitir Documento Electrónico

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.

POST /api/v1/documento-electronico

Emite un documento electrónico y lo encola para envío a SIFEN. La respuesta es asíncrona: la API retorna inmediatamente con estado: PENDIENTE y un CDC ya calculado. El procesamiento real ocurre en segundo plano (lote → firma → envío SIFEN → resultado). Usá GET /status/:cdc o el statusUrl retornado para hacer polling del estado final.

Autenticación

Authorization: Bearer {api-key} — requerido

Request body

El campo tipoDocumento determina el schema completo del request. Ver los modelos:

Campos comunes a todos los tipos

Campo	Tipo	Req.	Descripción
`tipoDocumento`	`enum`	Sí	Tipo de documento — ver tabla arriba
`fechaEmision`	`datetime`	Sí	Fecha y hora de emisión (`YYYY-MM-DDTHH:mm:ss`)
`tipoEmision`	`enum`	Sí	`NORMAL` o `CONTINGENCIA`
`numeroEstablecimiento`	`integer`	Sí	Número de establecimiento (1-999)
`puntoExpedicion`	`integer`	Sí	Punto de expedición (1-999)
`tipoTransaccion`	`enum`	Sí	Naturaleza de la operación
`monedaOperacion`	`enum`	Sí	Moneda (ej: `PYG`, `USD`)
`receptor`	`object`	Sí	Datos del receptor — ver Modelo Receptor
`condicionOperacion`	`enum`	Sí	`CONTADO` o `CREDITO`
`condicionPago`	`object`	Sí*	Requerido para `CONTADO`
`items`	`array`	Sí	Lista de ítems — ver Modelo Ítem

Respuesta exitosa

Status: 202 Accepted

La respuesta es un objeto JSON con el CDC, el estado inicial (PENDIENTE) y URLs auxiliares para seguimiento.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cdc": "01800123451001001000000122026042710000000006",
  "estado": "PENDIENTE",
  "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"
}

Headers de respuesta

Header	Valor	Descripción
`Location`	`{statusUrl}`	URL absoluta para consultar el estado del documento

Campos del DTO

Campo	Tipo	Descripción
`id`	`uuid`	ID interno del documento en Sifende
`cdc`	`string(44)`	Código de Control del Documento Electrónico — identificador único en SIFEN
`estado`	`enum`	Estado inicial: siempre `PENDIENTE` en la respuesta de emisión
`tipoDocumento`	`enum`	Tipo del documento creado (eco del request)
`iTiDe`	`integer`	Código numérico SIFEN del tipo (1=FE, 5=NCE, 6=NDE)
`numeroDocumento`	`integer`	Número correlativo asignado dentro del punto de expedición
`numeroFormateado`	`string`	Número en formato `establecimiento-puntoExpedicion-secuencia` (ej: `001-001-0000001`)
`fechaCreacion`	`datetime`	Timestamp de creación del registro
`qrUrl`	`string`	URL del QR oficial de SIFEN para el KuDE
`statusUrl`	`string`	URL absoluta para consultar el estado
`kudeUrl`	`string`	URL absoluta para descargar el KuDE en PDF (disponible solo cuando `estado = APROBADO`)

El estado inicial es siempre PENDIENTE. Hacé polling a statusUrl o GET /status/:cdc cada 5–10 segundos hasta obtener APROBADO, RECHAZADO o APROBADO_OBSERVACION. Ver Polling de resultados.

Errores comunes

Status	Tipo	Cuándo ocurre
400	`validation-error`	Campos inválidos o faltantes
400	`invalid-enum-value`	Valor de enumeración no reconocido
404	`timbrado-not-found`	No hay timbrado configurado
404	`certificate-not-found`	No hay certificado digital subido
422	`documento-electronico-generation-error`	Error de compliance SIFEN en la generación

Ejemplos

curl -X POST https://api.sifende.com.py/api/v1/documento-electronico \
  -H "Authorization: Bearer $SIFENDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tipoDocumento": "FACTURA_ELECTRONICA",
    "fechaEmision": "2026-04-15T10:30:00",
    "tipoEmision": "NORMAL",
    "numeroEstablecimiento": 1,
    "puntoExpedicion": 1,
    "tipoTransaccion": "VENTA_MERCADERIA",
    "monedaOperacion": "PYG",
    "receptor": {
      "tipoContribuyente": "NO_CONTRIBUYENTE",
      "tipoOperacion": "B2C",
      "tipoDocumento": "CEDULA_PARAGUAYA",
      "numeroDocumento": "1234567",
      "nombreRazonSocial": "Juan Pérez"
    },
    "condicionOperacion": "CONTADO",
    "condicionPago": {
      "tipo": "CONTADO",
      "tipoPago": "EFECTIVO",
      "monedaPago": "PYG",
      "montoPago": 110000
    },
    "items": [
      {
        "codigo": "PROD-001",
        "descripcion": "Resma de papel A4 75g",
        "cantidad": 10,
        "unidadMedida": "UNI",
        "precioUnitario": 10000,
        "afectacionTributaria": "GRAVADO",
        "tasaIVA": 10
      }
    ]
  }'

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',
    },
    body: JSON.stringify({
      tipoDocumento: 'FACTURA_ELECTRONICA',
      fechaEmision: '2026-04-15T10:30:00',
      tipoEmision: 'NORMAL',
      numeroEstablecimiento: 1,
      puntoExpedicion: 1,
      tipoTransaccion: 'VENTA_MERCADERIA',
      monedaOperacion: 'PYG',
      receptor: {
        tipoContribuyente: 'NO_CONTRIBUYENTE',
        tipoOperacion: 'B2C',
        tipoDocumento: 'CEDULA_PARAGUAYA',
        numeroDocumento: '1234567',
        nombreRazonSocial: 'Juan Pérez',
      },
      condicionOperacion: 'CONTADO',
      condicionPago: {
        tipo: 'CONTADO',
        tipoPago: 'EFECTIVO',
        monedaPago: 'PYG',
        montoPago: 110000,
      },
      items: [
        {
          codigo: 'PROD-001',
          descripcion: 'Resma de papel A4 75g',
          cantidad: 10,
          unidadMedida: 'UNI',
          precioUnitario: 10000,
          afectacionTributaria: 'GRAVADO',
          tasaIVA: 10,
        },
      ],
    }),
  }
);

const data = await response.json();
// data.cdc      → "01800123451001001000000122026042710000000006"
// data.estado   → "PENDIENTE"
// data.statusUrl → "https://api.sifende.com.py/api/v1/documento-electronico/status/..."

import requests, os

response = requests.post(
    'https://api.sifende.com.py/api/v1/documento-electronico',
    headers={
        'Authorization': f'Bearer {os.environ["SIFENDE_API_KEY"]}',
        'Content-Type': 'application/json',
    },
    json={
        'tipoDocumento': 'FACTURA_ELECTRONICA',
        'fechaEmision': '2026-04-15T10:30:00',
        'tipoEmision': 'NORMAL',
        'numeroEstablecimiento': 1,
        'puntoExpedicion': 1,
        'tipoTransaccion': 'VENTA_MERCADERIA',
        'monedaOperacion': 'PYG',
        'receptor': {
            'tipoContribuyente': 'NO_CONTRIBUYENTE',
            'tipoOperacion': 'B2C',
            'tipoDocumento': 'CEDULA_PARAGUAYA',
            'numeroDocumento': '1234567',
            'nombreRazonSocial': 'Juan Pérez',
        },
        'condicionOperacion': 'CONTADO',
        'condicionPago': {
            'tipo': 'CONTADO',
            'tipoPago': 'EFECTIVO',
            'monedaPago': 'PYG',
            'montoPago': 110000,
        },
        'items': [{
            'codigo': 'PROD-001',
            'descripcion': 'Resma de papel A4 75g',
            'cantidad': 10,
            'unidadMedida': 'UNI',
            'precioUnitario': 10000,
            'afectacionTributaria': 'GRAVADO',
            'tasaIVA': 10,
        }],
    }
)

data = response.json()
# data['cdc']        → "01800123451001001000000122026042710000000006"
# data['estado']     → "PENDIENTE"
# data['statusUrl']  → "https://api.sifende.com.py/api/v1/documento-electronico/status/..."

Emitir Documento Electrónico

On this page