| name | jpk-submit |
| description | Wysyła wygenerowany plik JPK_V7M lub JPK_EWP do bramki Ministerstwa Finansów (REST API e-dokumenty.mf.gov.pl) z autoryzacją "danymi autoryzującymi" (bez podpisu kwalifikowanego). Zwraca numer referencyjny i UPO (Urzędowe Poświadczenie Odbioru). Użyj gdy user mówi "wyślij JPK do MF", "złóż deklarację VAT", "wyślij JPK_V7M", "wyślij ewidencję ryczałtu", "submituj JPK", lub bezpośrednio po wygenerowaniu pliku JPK. |
Wysyłka JPK do bramki MF
Pełny flow: szyfrowanie XML (AES-256-CBC + RSA klucz publiczny MF) → init upload → PUT na Azure Blob → finish → polling status → pobranie UPO.
Wymagane dane
- xml-path — ścieżka do pliku JPK (zwykle z
data/jpk/JPK_V7M_*.xml lub data/jpk/JPK_EWP_*.xml)
W .env muszą być:
MF_PESEL — PESEL podatnikaMF_PRIOR_INCOME — kwota przychodu z PIT za rok N-2 (dla wysyłki w 2026 → PIT za 2024). Pozycje zgodnie z formularzem PIT-37/28/36/36L. Brak zeznania → 0.MF_CERT_PATH — ścieżka do klucza publicznego MF (PEM/DER) — pobierz z podatki.gov.pl, sekcja klucze publiczneMF_ENV=test (domyślnie) lub prodSELLER_FIRST_NAME, SELLER_LAST_NAME, SELLER_BIRTH_DATE, SELLER_NIP
Wywołanie — DRY-RUN (zalecane przed pierwszą wysyłką)
python3 skills/jpk-submit/scripts/submit.py --xml-path data/jpk/JPK_V7M_2026_04.xml --dry-run
Pokazuje co byłoby wysłane (rozmiar, env, fingerprint danych autoryzujących) bez dotykania bramki.
Wywołanie — wysyłka
python3 skills/jpk-submit/scripts/submit.py --xml-path data/jpk/JPK_V7M_2026_04.xml
Zwraca JSON:
{
"success": true,
"reference_number": "20260417-...",
"status_code": 200,
"upo_path": "data/upo/UPO_20260417-...bin",
"mf_env": "test"
}
Polling statusu trwa do 10 minut (interwał 15s). Status 200 = sukces + UPO; 401-420 = błędy MF (zła XSD, certyfikat, autoryzacja).
⚠️ KRYTYCZNE — przed wysyłką na PROD
- Najpierw przetestuj na bramce TEST (
MF_ENV=test). Bramka prod = e-dokumenty.mf.gov.pl, test = test-e-dokumenty.mf.gov.pl.
- Zweryfikuj kwotę przychodu z PIT za rok N-2 — błąd → odrzucenie autoryzacji. Konkretne pozycje: PIT-37 poz. 50/83, PIT-28 poz. 20/22/24/62/73, PIT-36 poz. 67-75/131, PIT-36L poz. 23/25/27/28/33. Brak zeznania = 0. Nie wolno sumować z różnych zeznań.
- Sprawdź certyfikat MF — aktualizowany okresowo (ostatnio 18.07.2025). Nieaktualny → init zwróci błąd
404.
- Zachowaj UPO —
data/upo/UPO_*.bin to dowód złożenia. Bez UPO uznaje się że JPK nie został złożony.
- Termin — JPK_V7M do 25-go następnego miesiąca; JPK_EWP do 30.04 następnego roku.
Po sukcesie
Pokaż userowi: reference_number, mf_env, ścieżkę UPO (jako klikalny link).
Jeśli mf_env=test — wyraźnie zaznacz że to wysyłka TESTOWA, nie produkcyjna.
Implementacja MVP — disclaimer
Klient został napisany od zera (brak oficjalnego SDK MF dla Pythona). Jeśli MF zmieni format InitUploadSigned (do potwierdzenia: nazwa endpointu dla danych autoryzujących vs. podpis kwalifikowany) — wymaga to aktualizacji src/jdg_ksiegowy/mf_gateway/client.py.
