Emitir Documento Electrónico

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

Idempotencia

Idempotency-Key es un header opcional de 1 a 255 caracteres ASCII visibles, sin espacios al inicio ni al final. El flujo compartido está definido en Idempotencia y Reintentos Seguros.

Idempotency-Key: 7d444840-9dc0-11d1-b245-5ffdce74fad2

En emisión, el replay devuelve el mismo 202, documento, CDC, correlativo y Location; nunca reserva otro número. Si el contrato no está disponible, 503 idempotency-unavailable no crea el documento ni consume el correlativo.

Request body

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

• Factura Electrónica
• Nota de Crédito Electrónica
• Nota de Débito Electrónica

Campos comunes a todos los tipos

Campos condicionales según el tipo de documento

Estos campos no aplican a todos los tipos de documento. Omitir el que corresponde a tu tipoDocumento devuelve 400 validation-error.

Campos del receptor

El bloque receptor usa los mismos nombres de campo en toda operación, pero cuáles son obligatorios depende de tipoContribuyente. Schema completo en Modelo Receptor.

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

Campos del DTO

Errores comunes

Ejemplos

Los dos casos de receptor que cubren la mayoría de las integraciones. Copiá el que corresponda a tu operación — lo que los diferencia es el bloque receptor.

Factura B2C — consumidor final identificado

Factura a crédito por cuotas

El siguiente body coincide con el fixture válido publicado por OpenAPI:

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-09-18T10:30:00",
  "tipoEmision": "NORMAL",
  "numeroEstablecimiento": 1,
  "puntoExpedicion": 1,
  "tipoTransaccion": "VENTA_MERCADERIA",
  "monedaOperacion": "PYG",
  "receptor": {
    "tipoContribuyente": "CONTRIBUYENTE",
    "tipoOperacion": "B2B",
    "tipoContribuyenteReceptor": "PERSONA_JURIDICA",
    "numeroDocumento": "80012345",
    "digitoVerificador": "7",
    "nombreRazonSocial": "Comercial San Roque S.A."
  },
  "condicionOperacion": "CREDITO",
  "condicionPago": {
    "tipo": "CREDITO",
    "condicionCredito": "CUOTA",
    "cuotas": 3,
    "detalleCuotas": [
      {
        "monto": 40000,
        "fechaVencimiento": "2026-09-18"
      },
      {
        "monto": 40000,
        "fechaVencimiento": "2026-10-18"
      },
      {
        "monto": 40000,
        "fechaVencimiento": "2026-11-18"
      }
    ]
  },
  "items": [
    {
      "codigo": "PROD-001",
      "descripcion": "Resma de papel A4 75g",
      "cantidad": 10,
      "unidadMedida": "UNI",
      "precioUnitario": 12000,
      "afectacionTributaria": "GRAVADO",
      "tasaIVA": 10
    }
  ]
}'

Para crédito a plazo, reemplazá la rama por condicionCredito: "PLAZO" y plazoCredito; no envíes cuotas ni detalleCuotas. La API sólo admite crédito en PYG por ahora.

Factura B2B — receptor contribuyente con RUC

Respecto del ejemplo anterior, en el bloque receptor: tipoContribuyente pasa a CONTRIBUYENTE y tipoOperacion a B2B, se agregan tipoContribuyenteReceptor y digitoVerificador, y se saca tipoDocumento. El numeroDocumento es el RUC sin el dígito verificador.

Próximos pasos

• Receptor B2B y B2C: cada caso de receptor con su ejemplo y los rechazos asociados.
• Consultar el estado del documento
• Modelo Receptor: schema completo del bloque receptor.