Integracja faktur (API / agenci)

Własny portal / ERP łączy się kluczem API (poniżej). Skopiuj instrukcję Markdown i wklej agentowi w jego aplikacji — albo podaj publiczny URL.

• Portal / ERP → klucz API → POST /v1/invoices (nie webhook sklepu).
• emailBuyer + buyer.email → my mailujemy nabywcę (HTML FV); albo mail po Waszej stronie.
• callbackUrl → webhook invoice.created z X-KS-Signature (HMAC kluczem API).
• Każda FV liczy się do limitu dokumentów pakietu.

POST https://api.ksiegujesam.pl/v1/invoices
X-Api-Key: ks_…
Content-Type: application/json

{
  "organizationId": "ORG_ID",
  "kind": "VAT",
  "issueDate": "2026-09-22",
  "buyer": {
    "name": "Jan Kowalski",
    "nip": "5250000000",
    "email": "[email protected]",
    "addressLine1": "ul. Przykładowa 1",
    "city": "Warszawa",
    "postalCode": "00-001",
    "countryCode": "PL"
  },
  "lines": [
    {
      "name": "Opłata za ogłoszenie #12345",
      "quantity": 1,
      "unit": "szt.",
      "unitNetPrice": 81.3,
      "vatRate": "23"
    }
  ],
  "notes": "portal:listing:12345",
  "sendToKsef": false,
  "emailBuyer": true,
  "callbackUrl": "https://twoj-portal.example/webhooks/ksiegujesam"
}

# Integracja faktur z KsięgujęSam — instrukcja dla agenta / developera

**Produkt:** KsięgujęSam (https://app.ksiegujesam.pl)
**API:** `https://api.ksiegujesam.pl`
**Ta instrukcja (live):** https://app.ksiegujesam.pl/integracja · raw MD: https://app.ksiegujesam.pl/integracja/raw
**Cel:** wystawianie faktur VAT z zewnętrznej aplikacji (portal, sklep, ERP) przez publiczne API `/v1`.

---

## Zasady (obowiązkowe)

1. Nie wymyślaj endpointów spoza tej instrukcji.
2. Klucz API tylko w env / secrets — nigdy w git / logach.
3. Po `POST /v1/invoices` zapisz u siebie `id` i `number` (idempotencja).
4. Mail do nabywcy: ustaw `buyer.email` + `emailBuyer: true` **albo** wyślij mail sam z odpowiedzi API.
5. Opcjonalny webhook: `callbackUrl` (https) → `invoice.created` z podpisem HMAC.
6. Każda FV liczy się do limitu dokumentów pakietu KsięgujęSam.
7. To nie jest doradztwo podatkowe — VAT ustala Twój produkt / użytkownik.
8. Domyślnie `sendToKsef: false`. `true` tylko przy skonfigurowanym KSeF i świadomej decyzji.

Portal / własny system = **REST `/v1`**. Webhooki Woo/Shoper/… to osobny kanał sklepów.

---

## Setup (właściciel konta, raz)

1. Pakiet PRO+ (feature `api_access`).
2. Zaplecze → Publiczne API → utwórz klucz (`ks_…`, widoczny raz).
3. Env w Twojej aplikacji:

```bash
KSIEGUJESAM_API_BASE=https://api.ksiegujesam.pl
KSIEGUJESAM_API_KEY=ks_xxxxxxxx
KSIEGUJESAM_ORGANIZATION_ID=ORG_ID_Z_GET_/v1/me
```

---

## Auth

```http
X-Api-Key: ks_…
Content-Type: application/json
```

Albo: `Authorization: Bearer ks_…`

Scope’y: `invoices:write`, `invoices:read`, opcjonalnie `contractors:read`.

---

## Sanity check

```http
GET https://api.ksiegujesam.pl/v1/me
X-Api-Key: {KEY}
```

Zwraca `organizations[].id` — użyj jako `organizationId`.

---

## Wystawienie FV (pełny flow portalu)

```http
POST https://api.ksiegujesam.pl/v1/invoices
X-Api-Key: {KEY}
Content-Type: application/json
```

```json
{
  "organizationId": "ORG_ID_Z_GET_/v1/me",
  "kind": "VAT",
  "issueDate": "2026-08-13",
  "buyer": {
    "name": "Jan Kowalski",
    "nip": "5250000000",
    "email": "[email protected]",
    "addressLine1": "ul. Przykładowa 1",
    "city": "Warszawa",
    "postalCode": "00-001",
    "countryCode": "PL"
  },
  "lines": [
    {
      "name": "Opłata za ogłoszenie #12345",
      "quantity": 1,
      "unit": "szt.",
      "unitNetPrice": 81.3,
      "vatRate": "23"
    }
  ],
  "notes": "portal:listing:12345",
  "sendToKsef": false,
  "emailBuyer": true,
  "callbackUrl": "https://twoj-portal.example/webhooks/ksiegujesam"
}
```

### Pola kluczowe

| Pole | Wymagane | Uwagi |
|---|---|---|
| organizationId | tak | z /v1/me |
| kind | tak | zwykle VAT |
| issueDate | tak | YYYY-MM-DD |
| buyer.name | tak | |
| buyer.email | nie* | *wymagany gdy emailBuyer=true |
| lines[] | tak | unitNetPrice = netto; vatRate: "23" / "8" / "5" / "0" / "0_wdt" / "0_ex" / "zw" / "np" |
| notes | nie | Twój ID (listing/order) |
| sendToKsef | nie | false = bezpieczny default |
| emailBuyer | nie | true = my wysyłamy mail z HTML FV do nabywcy |
| callbackUrl | nie | https POST invoice.created (dev: http://localhost) |

### Odpowiedź (sukces) — zapisz

- `id`, `number`, kwoty
- `paymentUrl` — strona płatności/podglądu
- `htmlUrl` — publiczny HTML FV
- `email`: `{ sent, to?, error? }` (błąd maila **nie** cofa FV)
- `callback`: `{ delivered, status?, error? }`

API **nie** deduplikuje po notes — idempotencję zrób u siebie.

---

## Webhook zwrotny (callbackUrl)

```http
POST https://twoj-portal.example/webhooks/ksiegujesam
Content-Type: application/json
X-KS-Event: invoice.created
X-KS-Signature: sha256=<hmac_hex>
```

Podpis: HMAC-SHA256 **surowego body** kluczem API (`ks_…`).

```js
const crypto = require("crypto");
const expected = "sha256=" + crypto.createHmac("sha256", API_KEY).update(rawBody).digest("hex");
```

Timeout po naszej stronie: 8 s. Nieudany callback nie kasuje FV.

---

## Odczyt / ponowny mail / HTML

- `GET https://api.ksiegujesam.pl/v1/invoices?organizationId=ORG_ID_Z_GET_/v1/me`
- `GET https://api.ksiegujesam.pl/v1/invoices/{id}?organizationId=ORG_ID_Z_GET_/v1/me`
- `GET https://api.ksiegujesam.pl/v1/invoices/{id}/html?organizationId=ORG_ID_Z_GET_/v1/me`
- `POST https://api.ksiegujesam.pl/v1/invoices/{id}/email` body: `{ "organizationId": "ORG_ID_Z_GET_/v1/me", "to": "opcjonalnie@…" }`
- `GET https://api.ksiegujesam.pl/v1/contractors?organizationId=ORG_ID_Z_GET_/v1/me&q=`

---

## Flow (portal ogłoszeń)

1. Zdarzenie biznesowe (płatność / publikacja).
2. Jeśli masz już `ksiegujesamInvoiceId` → stop.
3. `POST /v1/invoices` z `emailBuyer` i/lub `callbackUrl`.
4. Zapisz id/number; obsłuż webhook albo odpowiedź synchroniczną.
5. KSeF: ręcznie w Faktury albo `sendToKsef: true`.

---

## Błędy

| HTTP | Znaczenie |
|---|---|
| 400 | Walidacja body / emailBuyer bez email / zły callbackUrl |
| 401 | Zły klucz |
| 403 | Plan / scope / zła firma |
| 404 | organizationId nie z konta klucza |
| 503 | KSeF/kolejka (gdy sendToKsef) — FV mogła powstać |

---

## DoD

- [ ] Env ustawione
- [ ] GET /v1/me OK
- [ ] POST tworzy FV; id/number zapisane
- [ ] emailBuyer lub własny mail do klienta
- [ ] (opcja) callbackUrl weryfikuje X-KS-Signature
- [ ] sendToKsef domyślnie false
- [ ] Brak sekretów w logach / git