Guía API KSeF 2.0

1. Entornos

KSeF proporciona tres entornos distintos. Utilice siempre TEST o DEMO para el desarrollo.

2. Autenticación

Cada sesión API requiere autenticación por token. El flujo completo utiliza cifrado RSA-OAEP del token con la clave pública del KSeF.

Flujo completo (token API)

1. GET  /security/public-key-certificates     → RSA keys
2. POST /auth/challenge                        → challenge + timestampMs
3. RSA-OAEP(token|timestampMs)                 → encrypt with "KsefTokenEncryption" key
4. POST /auth/ksef-token                       → challenge + encryptedToken
   → authenticationToken + referenceNumber (HTTP 202)
5. GET  /auth/{referenceNumber}                → poll until code=200
6. POST /auth/token/redeem                     → exchange → accessToken

Headers requeridos para llamadas autenticadas

Authorization: Bearer {accessToken}
Accept: application/json
Content-Type: application/json

Claves públicas

GET /security/public-key-certificates devuelve 2 certificados:

No hay campo fingerprint en la respuesta (contrario a la documentación).

3. Sesión Online (interactiva)

Para enviar facturas sin adjuntos, una a una.

1. POST /sessions/online                           → open session
2. POST /sessions/online/{ref}/invoices             → send invoice
3. GET  /sessions/{ref}/invoices/{invoiceRef}        → check status
4. POST /sessions/online/{ref}/close                → close session

Apertura de sesión

{
  "formCode": {"systemCode": "FA (3)", "schemaVersion": "1-0E", "value": "FA"},
  "encryption": {
    "encryptedSymmetricKey": "RSA-OAEP(aes_key, cert_SymmetricKeyEncryption)",
    "initializationVector": "base64(iv_16_bytes)"
  }
}

El cliente genera la clave AES-256 y el IV, cifra la clave con RSA y envía ambos.

Envío de una factura

{
  "invoiceHash": "base64(SHA256(xml_raw))",
  "invoiceSize": 2048,
  "encryptedInvoiceHash": "base64(SHA256(xml_encrypted))",
  "encryptedInvoiceSize": 2064,
  "encryptedInvoiceContent": "base64(AES-256-CBC(xml_raw))"
}

Cifrado AES-256-CBC con padding PKCS#7. Misma clave/IV que la sesión.

4. Sesión Batch (wsadowa)

Para enviar facturas con o sin adjuntos, en lote (ZIP).

1. Create ZIP containing XML invoices (faktura_1.xml, faktura_2.xml, ...)
2. Encrypt ZIP with AES-256-CBC + PKCS#7 (NO IV prepend)
3. POST /sessions/batch           → open session, receive upload URL
4. PUT  {uploadUrl}               → upload encrypted ZIP (raw bytes)
5. POST /sessions/batch/{ref}/close  → close and start processing
6. GET  /sessions/{ref}           → poll session status
7. GET  /sessions/{ref}/invoices  → accepted invoices
8. GET  /sessions/{ref}/invoices/failed → rejected invoices

Apertura de sesión batch

{
  "formCode": {"systemCode": "FA (3)", "schemaVersion": "1-0E", "value": "FA"},
  "batchFile": {
    "fileSize": 1078,
    "fileHash": "base64(SHA256(zip_raw))",
    "fileParts": [{
      "ordinalNumber": 1,
      "fileSize": 1088,
      "fileHash": "base64(SHA256(zip_encrypted))"
    }]
  },
  "encryption": {
    "encryptedSymmetricKey": "...",
    "initializationVector": "..."
  }
}

Resultados por factura

Tras cerrar la sesión batch, cada factura se procesa de forma independiente. Consulte los resultados a través de dos endpoints separados.

GET /sessions/{ref}/invoices          → accepted invoices (with ksefNumber)
GET /sessions/{ref}/invoices/failed   → rejected invoices (with processingCode + error)

El procesamiento es paralelo: las facturas aceptadas y rechazadas pueden aparecer en un orden diferente al del ZIP.

5. Códigos de procesamiento

Las respuestas API utilizan códigos de procesamiento (processingCode) para indicar el estado de la solicitud. El mismo código puede tener significados ligeramente diferentes según el endpoint (auth, sesión, factura, exportación).

Progresión (100-299)

Errores (400-550)

Source : Issue #526, OpenAPI spec, api-changelog.md

6. Límites

Verificable vía GET /limits/context.

7. Adjuntos (Zalacznik)

Prerrequisitos

• 1.Activación : POST /testdata/attachment con {"nip": "..."} (entorno TEST). En PROD: declaración vía e-Urząd Skarbowy.
• 2.Sesión batch obligatoria : el modo online rechaza los adjuntos (código 415).

Verificación

GET /permissions/attachments/status (authenticated)

{"isAttachmentAllowed": true}
// or with revocation date:
{"isAttachmentAllowed": true, "revokedDate": "2026-12-31T23:59:59+00:00"}

Estructura XML

'<Zalacznik>' es hijo directo de '<Faktura>' (no de '<Fa>'), con contenido estructurado:

<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <Naglowek>...</Naglowek>
  <Podmiot1>...</Podmiot1>
  <Podmiot2>...</Podmiot2>
  <Fa>...</Fa>
  <Zalacznik>
    <BlokDanych>
      <MetaDane>
        <ZKlucz>Key</ZKlucz>
        <ZWartosc>Value</ZWartosc>
      </MetaDane>
      <Tabela>
        <Opis>Table description</Opis>
        <TNaglowek>
          <Kol Typ="txt"><NKom>Column 1</NKom></Kol>
          <Kol Typ="int"><NKom>Column 2</NKom></Kol>
        </TNaglowek>
        <Wiersz>
          <WKom>Value 1</WKom>
          <WKom>42</WKom>
        </Wiersz>
      </Tabela>
    </BlokDanych>
  </Zalacznik>
</Faktura>

Tipos de columna: txt, int, dec, date.

Códigos de error de adjuntos

8. Endpoints testdata (entorno TEST)

No requiere autenticación. Estos endpoints permiten configurar el entorno de prueba.

9. Endpoints de información

Endpoints autenticados para consultar el estado de su cuenta y facturas.

10. Problemas conocidos

Puntos de atención al integrar con la API KSeF, basados en nuestras pruebas reales:

Enlaces útiles

• 🔗 Documentación KSeF (GitHub CIRFMF)
• 🔗 Especificación OpenAPI KSeF
• 🔗 Portal oficial KSeF (podatki.gov.pl)