EIDA API – Dokumentacja integracyjna

🔐 Autoryzacja

Każdy użytkownik generuje własny klucz API w sekcji Konto → Integracja API.

Wysyłaj go jako:

Authorization: Bearer <TWÓJ_KLUCZ_API>

lub alternatywnie:

x-api-key: <TWÓJ_KLUCZ_API>

📤 1. Upload pojedynczego pliku

Endpoint: POST /api/v1/attachments

Parametry (multipart/form-data):

• file – plik do przesłania (max 20 MB)
• recipient_nip – NIP odbiorcy (10 cyfr)
• doc_id – identyfikator dokumentu w ERP (wymagany)
• invoice_no – numer faktury (opcjonalny)

Przykład odpowiedzi:

{
  "status": "ok",
  "message": "File uploaded",
  "attachment": {
    "eida_code": "vDfYn3B",
    "filename": "FV_001.pdf",
    "filesize": 46289,
    "recipient_nip": "7791002618",
    "doc_id": 10,
    "timestamp": "2025-10-23T19:42:15Z"
  }
}

📦 2. Upload paczki plików (batch)

Endpoint: POST /api/v1/attachments

Wysyła wiele plików w jednym żądaniu z opisem w manifeście JSON.

Przykład pola manifest:

{
  "items": [
    {"filename": "FV_001.pdf", "recipient_nip": "7791002618", "doc_id": 101, "invoice_no": "FV/10/2025/001"},
    {"filename": "FV_002.pdf", "recipient_nip": "7791002618", "doc_id": 102}
  ]
}

Przykład odpowiedzi:

{
  "ok": true,
  "errors": 0,
  "items": [
    {"filename": "FV_001.pdf", "eida_code": "AbC123d", "doc_id": 101, "status": "created"},
    {"filename": "FV_002.pdf", "eida_code": "EfG456h", "doc_id": 102, "status": "created"}
  ]
}

Limity:

• Maks. rozmiar jednego pliku: 20 MB
• Maks. rozmiar całej paczki: 100 MB
• Maks. liczba plików: 50

🔍 3. Metadane pliku (GET /meta)

Endpoint: GET /api/v1/attachments/<EIDA_CODE>/meta?recipient_nip=XXXXXXXXXX

Przykład odpowiedzi:

{
  "eida_code": "AbC123",
  "filename": "FV_001.pdf",
  "filesize": 46289,
  "doc_id": 101,
  "invoice_no": "FV/10/2025/001",
  "timestamp": "2025-10-23T19:42:15Z"
}

📥 4. Pobieranie pliku (GET)

Endpoint: GET /api/v1/attachments/<EIDA_CODE>?recipient_nip=XXXXXXXXXX

Zwraca plik binarny (PDF, JPG, ZIP...).

⚠️ 5. Błędy i kody odpowiedzi

• 400 bad_request – brak wymaganych pól
• 400 invalid_nip – błędny NIP odbiorcy
• 400 missing_or_invalid_doc_id – brak doc_id
• 401 unauthorized – błędny klucz API
• 403 invalid_nip – NIP nie pasuje do pliku
• 404 not_found – plik nie istnieje
• 413 file_too_large – przekroczony limit 20 MB
• 413 total_batch_size_exceeded – przekroczony łączny limit 100 MB

⚙️ 6. Limity techniczne

• MAX_CONTENT_LENGTH: 100 MB
• MAX_FILE_SIZE: 20 MB
• MAX_FILES_AT_ONCE: 50
• Kodowanie: UTF-8
• Format czasu: ISO 8601 UTC
• Baza danych: SQLAlchemy (SQLite / PostgreSQL)