REST API, OpenAPI, Postman, webhooki

Dokumentacja API fakturyPRO od pierwszego tokena do produkcyjnej integracji.

Praktyczna wiki dla developerów, integratorów i agentów AI. Każdy endpoint ma cel, parametry, odpowiedź i gotowy przykład curl.

Szybki start OpenAPI JSON Kolekcja Postman Manifest API

fakturyPRO / dokumentacja API REST · OpenAPI · Postman

Token i health-check Sprawdź konto, pakiet API i schemat projektu.

Faktura z zamówienia Użyj external_id, aby retry nie tworzył duplikatów.

Webhooki i statusy Synchronizuj płatność, KSeF, link publiczny i historię.

curl -H "Authorization: Bearer {{api_token}}" \
  "https://faktury.pro/api/health.php?id_konta={{account_id}}"

Szybki start

1. Włącz pakiet z APIAPI jest funkcją pakietów PRO/Business albo triala z funkcją API.

2. Wygeneruj tokenWłaściciel konta generuje token w ustawieniach konta. W bazie przechowywany jest tylko hash.

3. Zrób health-checkSprawdź token, konto, schemat tabel i dostępność funkcji.

4. Pobierz słownikiMapuj typy dokumentów, VAT, jednostki i formy płatności z /api/meta.php.

5. Utwórz fakturę z external_idexternal_id chroni przed duplikatami przy ponowieniu requestu.

6. Wyślij do KSeFUżyj ready, xml, send i status, aby zapisać numer KSeF.

curl -X POST "https://faktury.pro/api/faktury/create.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "client": {
        "nazwa": "Klient testowy API",
        "email": "test-api@example.com"
    },
    "items": [
        {
            "nazwa": "Usługa testowa API",
            "ilosc": "1",
            "cena_netto": "100.00",
            "vat": "23"
        }
    ]
}'

Pełny flow: faktura do KSeF

To jest rekomendowana ścieżka dla sklepu, CRM albo własnego systemu sprzedaży. Najpierw tworzysz fakturę z trwałym external_id, potem sprawdzasz gotowość, opcjonalnie generujesz XML, wysyłasz dokument i pobierasz numer KSeF.

1. Create/api/faktury/create.php tworzy fakturę i zabezpiecza retry przez external_id.

2. Ready/api/ksef/ready.php pokazuje braki przed wysyłką, np. NIP, nabywcę, pozycje lub płatność.

3. XML/api/ksef/xml.php generuje FA(3) bez wysyłania do KSeF.

4. Send/api/ksef/send.php wysyła fakturę i zapisuje numery referencyjne.

5. Status/api/ksef/status.php odświeża status i zwraca ksef_number.

Gotowy flow curl

# 1. Utwórz fakturę z identyfikatorem zamówienia
curl -X POST "https://faktury.pro/api/faktury/create.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "client": {
        "nazwa": "Klient testowy API",
        "nip": "5250000000",
        "email": "klient@example.com"
    },
    "items": [
        {
            "nazwa": "Usługa wdrożeniowa",
            "ilosc": "1",
            "cena_netto": "100.00",
            "vat": "23"
        }
    ]
}'

# 2. Sprawdź gotowość faktury do KSeF
curl -X POST "https://faktury.pro/api/ksef/ready.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001"
}'

# 3. Opcjonalnie wygeneruj XML FA(3) bez wysyłki
curl -X POST "https://faktury.pro/api/ksef/xml.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "include_xml": true
}'

# 4. Wyślij fakturę do KSeF
curl -X POST "https://faktury.pro/api/ksef/send.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001"
}'

# 5. Pobierz status i numer KSeF
curl -X POST "https://faktury.pro/api/ksef/status.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "refresh": true
}'

Prompt dla Codex / Claude do wdrożenia flow

Zaimplementuj w projekcie klienta pełny flow fakturyPRO + KSeF:
1. Pobierz FAKTURYPRO_API_TOKEN i FAKTURYPRO_ACCOUNT_ID z env.
2. Wystaw fakturę przez /api/faktury/create.php z external_id równym ID zamówienia.
3. Przed wysyłką do KSeF wywołaj /api/ksef/ready.php i zatrzymaj proces, jeżeli can_send=false.
4. Jeżeli operator chce podgląd, wywołaj /api/ksef/xml.php z include_xml=true.
5. Wyślij dokument przez /api/ksef/send.php.
6. Odświeżaj /api/ksef/status.php aż status będzie accepted, rejected albo duplicate.
7. Zapisz invoice.ksef_number w systemie klienta.
Nie loguj tokenów. Retry rób tylko dla timeoutów i HTTP 5xx. Dla ok=false pokaż message i zachowaj error.

Statusy KSeF w integracji

processingDokument wysłany, KSeF jeszcze przetwarza. Odpytuj /api/ksef/status.php z backoffem.

acceptedDokument przyjęty. Zapisz invoice.ksef_number i pokaż numer w systemie klienta.

duplicateKSeF rozpoznał duplikat. Nie twórz drugiej faktury, pokaż operatorowi istniejący status.

rejectedDokument odrzucony. Pokaż ksef.status_details, popraw dane i ponów kontrolowany proces.

not_sentBrak numerów referencyjnych. Najpierw uruchom ready-check i wysyłkę przez /api/ksef/send.php.

Autoryzacja i bezpieczeństwo

Najlepsza praktyka: wysyłaj token w nagłówku Authorization: Bearer {{api_token}}. Nie przekazuj tokenu w query stringu, bo URL-e trafiają do historii przeglądarki, logów i narzędzi monitoringu.

Obsługiwane metody

Authorization: Bearer {{api_token}}
X-FakturyPro-Token: {{api_token}}
token w body POST jako fallback
id_konta albo account_id w query lub body

Typowe błędy

missing_credentials - brakuje konta albo tokenu
invalid_token - token nie pasuje do konta
api_disabled - API wyłączone dla konta
plan_feature_unavailable - pakiet nie obejmuje API

Postman i OpenAPI

OpenAPI opisuje kontrakt maszynowo, a kolekcja Postman daje gotowe requesty z trzema zmiennymi: base_url, account_id i api_token.

Import do Postmana

Otwórz Postman i wybierz Import.
Wklej adres https://faktury.pro/api/postman.php.
Uzupełnij zmienne kolekcji.
Uruchom request Health, potem Meta, potem Create invoice.
Wbudowane testy Postmana sprawdzą JSON, status HTTP i ok=false.

Import OpenAPI

Użyj https://faktury.pro/api/openapi.php.
Zaimportuj do Swagger UI, Insomnii albo generatora klienta.
Ustaw security scheme bearerAuth.
Generuj klienta dopiero po sprawdzeniu przykładów biznesowych z tej wiki.

Najczęstsze scenariusze

Sklep B2B

Zamówienie tworzy fakturę z external_id, klient dostaje link, a panel sklepu odpytuje status płatności i KSeF.

/api/faktury/create.php
/api/ksef/ready.php
/api/ksef/send.php
/api/ksef/status.php

CRM lub ERP

System utrzymuje klientów, produkty i statusy faktur, a fakturyPRO obsługuje dokument, PDF/XML, historię i link publiczny.

/api/clients/upsert.php
/api/products/upsert.php
/api/faktury/create.php
/api/events/list.php

Biuro rachunkowe

Biuro pobiera sprzedaż i koszty z okresu, oznacza dokumenty jako przekazane i ogranicza ręczne proszenie klienta o pliki.

/api/accounting/summary.php
/api/costs/list.php
/api/accounting/mark.php

Asystent AI

Agent nie zgaduje danych księgowych: pobiera metadane, pokazuje sugestie i wykonuje tylko kontrolowane akcje po decyzji operatora.

/api/health.php
/api/meta.php
/api/assistant/summary.php
/api/assistant/action.php

Diagnostyka błędów API

Każdy błąd zwracaj użytkownikowi przez pole message, a w logice integracji zachowuj maszynowy kod error. Tokenów i pełnych payloadów z danymi wrażliwymi nie zapisuj w logach.

missing_credentialsBrakuje id_konta/account_id albo tokenu. Sprawdź zmienne środowiskowe i nagłówek Authorization.

invalid_tokenToken nie pasuje do konta. Wygeneruj nowy token w panelu i usuń stary z konfiguracji integracji.

api_disabledAPI jest wyłączone dla konta. Włącz API lub sprawdź pakiet/trial.

missing_invoiceRequest nie wskazuje faktury. Przekaż invoice_id, number albo external_id.

invoice_not_foundNie znaleziono faktury na tym koncie. Sprawdź, czy external_id należy do właściwego konta.

ksef_failedOperacja KSeF nie powiodła się. Pokaż message, sprawdź status_details, token KSeF i środowisko.

ready_failedFaktura nie przeszła kontroli. Nie wysyłaj jej do KSeF, dopóki checks.counts.err nie wynosi 0.

HTTP 5xx / timeoutMożna ponowić request z backoffem. Przy tworzeniu faktury retry jest bezpieczne tylko z external_id/idempotency_key.

Minimalny klient API

W projekcie produkcyjnym najlepiej opakować API w mały klient HTTP. Dzięki temu token, account_id, obsługa błędów i retry są w jednym miejscu, a reszta aplikacji wywołuje proste metody biznesowe.

Minimalny klient powinien automatycznie dodawać id_konta, nagłówek Authorization: Bearer, timeout 30 sekund i błąd z polami status, error, message.

JavaScript / Node.js

export class FakturyProClient {
  constructor({ baseUrl = 'https://faktury.pro', accountId, apiToken }) {
    this.baseUrl = baseUrl.replace(/\/$/, '');
    this.accountId = accountId;
    this.apiToken = apiToken;
  }

  async request(path, payload = null) {
    const isGet = payload === null;
    const url = new URL(this.baseUrl + path);
    const options = {
      method: isGet ? 'GET' : 'POST',
      headers: { Authorization: 'Bearer ' + this.apiToken }
    };
    if (isGet) {
      url.searchParams.set('id_konta', this.accountId);
    } else {
      options.headers['Content-Type'] = 'application/json';
      options.body = JSON.stringify({ id_konta: this.accountId, ...payload });
    }
    const res = await fetch(url, options);
    const data = await res.json();
    if (!res.ok || data.ok === false) {
      const err = new Error(data.message || 'fakturyPRO API error');
      err.code = data.error;
      err.status = res.status;
      err.response = data;
      throw err;
    }
    return data;
  }

  createInvoice(invoice) { return this.request('/api/faktury/create.php', invoice); }
  ksefReady(selector) { return this.request('/api/ksef/ready.php', selector); }
  ksefSend(selector) { return this.request('/api/ksef/send.php', selector); }
  ksefStatus(selector) { return this.request('/api/ksef/status.php', { refresh: true, ...selector }); }
}

PHP

<?php
final class FakturyProClient
{
    public function __construct(
        private string $apiToken,
        private int $accountId,
        private string $baseUrl = 'https://faktury.pro'
    ) {}

    public function request(string $path, ?array $payload = null): array
    {
        $isGet = $payload === null;
        $url = rtrim($this->baseUrl, '/') . $path;
        if ($isGet) {
            $url .= '?id_konta=' . urlencode((string)$this->accountId);
        } else {
            $payload = ['id_konta' => $this->accountId] + $payload;
        }

        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => $isGet ? 'GET' : 'POST',
            CURLOPT_HTTPHEADER => array_filter([
                'Authorization: Bearer ' . $this->apiToken,
                $isGet ? null : 'Content-Type: application/json',
            ]),
            CURLOPT_POSTFIELDS => $isGet ? null : json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
            CURLOPT_TIMEOUT => 30,
        ]);
        $raw = curl_exec($ch);
        if ($raw === false) throw new RuntimeException(curl_error($ch));
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        curl_close($ch);
        $data = json_decode((string)$raw, true) ?: [];
        if ($status >= 400 || (isset($data['ok']) && $data['ok'] === false)) {
            throw new RuntimeException(($data['message'] ?? 'fakturyPRO API error') . ' [' . ($data['error'] ?? $status) . ']');
        }
        return $data;
    }
}

Checklista przed produkcją

Token API jest w sekrecie środowiskowym, nie w kodzie ani w logach. Każda faktura ze sklepu ma stabilne external_id albo idempotency_key. Integracja zaczyna od /api/health.php i zapisuje wersję API w diagnostyce. Mapowanie VAT, jednostek i płatności bierze dane z /api/meta.php. KSeF zawsze przechodzi przez ready przed send. Retry działa tylko dla timeoutów i HTTP 5xx, z backoffem. Webhook albo polling /api/events/list.php synchronizuje statusy po stronie klienta. Alerty monitorują wzrost invalid_token, ksef_failed i timeoutów.

Start i diagnostyka

Pierwsze requesty po wygenerowaniu tokena. Te endpointy nie zmieniają danych i są dobre do smoke testu integracji.

GET /api/health.php

Health-check konta API

Użyj po zapisaniu tokena w sklepie, CRM albo scenariuszu Make/n8n.

Parametry

id_konta lub account_id - identyfikator konta
Authorization: Bearer {{api_token}} albo X-FakturyPro-Token

Odpowiedź

ok
api_version
account.api_enabled
project.schema
features

Przykład curl

curl -H "Authorization: Bearer {{api_token}}" \
  "https://faktury.pro/api/health.php?id_konta={{account_id}}"

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "api_version": "2026-06-04",
    "account": {
        "api_enabled": true
    },
    "features": [
        "invoices",
        "ksef",
        "webhooks"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$accountId = getenv('FAKTURYPRO_ACCOUNT_ID');
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$ch = curl_init($baseUrl . '/api/health.php?id_konta=' . urlencode($accountId));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiToken],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const accountId = process.env.FAKTURYPRO_ACCOUNT_ID;
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const url = baseUrl + '/api/health.php?id_konta=' + encodeURIComponent(accountId);
const res = await fetch(url, {
  headers: { Authorization: 'Bearer ' + apiToken }
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
account_id = os.environ['FAKTURYPRO_ACCOUNT_ID']
api_token = os.environ['FAKTURYPRO_API_TOKEN']

response = requests.get(
    f'{base_url}/api/health.php',
    params={'id_konta': account_id},
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

C# / .NET

using System.Net.Http.Headers;

var baseUrl = "https://faktury.pro";
var accountId = Environment.GetEnvironmentVariable("FAKTURYPRO_ACCOUNT_ID");
var apiToken = Environment.GetEnvironmentVariable("FAKTURYPRO_API_TOKEN");

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiToken);

var url = baseUrl + "/api/health.php?id_konta=" + Uri.EscapeDataString(accountId ?? "");
var json = await http.GetStringAsync(url);
Console.WriteLine(json);

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

String baseUrl = "https://faktury.pro";
String accountId = System.getenv("FAKTURYPRO_ACCOUNT_ID");
String apiToken = System.getenv("FAKTURYPRO_API_TOKEN");
String url = baseUrl + "/api/health.php?id_konta=" + URLEncoder.encode(accountId, StandardCharsets.UTF_8);

HttpRequest request = HttpRequest.newBuilder(URI.create(url))
    .header("Authorization", "Bearer " + apiToken)
    .GET()
    .build();

HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) throw new RuntimeException(response.body());
System.out.println(response.body());

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
  "os"
)

func main() {
  baseURL := "https://faktury.pro"
  accountID := os.Getenv("FAKTURYPRO_ACCOUNT_ID")
  apiToken := os.Getenv("FAKTURYPRO_API_TOKEN")

  req, _ := http.NewRequest("GET", baseURL+"/api/health.php?id_konta="+url.QueryEscape(accountID), nil)
  req.Header.Set("Authorization", "Bearer "+apiToken)

  res, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  if res.StatusCode >= 400 { panic(string(body)) }
  fmt.Println(string(body))
}

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/health.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}"
}

GET /api/meta.php

Słowniki integracyjne

Pobierz typy dokumentów, jednostki, VAT i formy płatności przed mapowaniem danych.

Parametry

id_konta lub account_id

Odpowiedź

invoice_types
numbering_schemes
payment_methods
units
sale_types
vat_rates

Przykład curl

curl -H "Authorization: Bearer {{api_token}}" \
  "https://faktury.pro/api/meta.php?id_konta={{account_id}}"

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/meta.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "invoice_types",
        "numbering_schemes",
        "payment_methods",
        "units",
        "sale_types",
        "vat_rates"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$accountId = getenv('FAKTURYPRO_ACCOUNT_ID');
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$ch = curl_init($baseUrl . '/api/meta.php?id_konta=' . urlencode($accountId));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiToken],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const accountId = process.env.FAKTURYPRO_ACCOUNT_ID;
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const url = baseUrl + '/api/meta.php?id_konta=' + encodeURIComponent(accountId);
const res = await fetch(url, {
  headers: { Authorization: 'Bearer ' + apiToken }
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
account_id = os.environ['FAKTURYPRO_ACCOUNT_ID']
api_token = os.environ['FAKTURYPRO_API_TOKEN']

response = requests.get(
    f'{base_url}/api/meta.php',
    params={'id_konta': account_id},
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/meta.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}"
}

GET /api/events/list.php

Feed zdarzen do pollingu

Gdy integracja nie moze odebrac webhooka albo potrzebuje kontrolnego odczytu po kursorze.

Parametry

after_id
since lub created_from
source
type
object_type
object_id
limit 1..100

Odpowiedź

events
meta.last_id
meta.has_more
filters

Przykład curl

curl -H "Authorization: Bearer {{api_token}}" \
  "https://faktury.pro/api/events/list.php?id_konta={{account_id}}"

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/events/list.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "events",
        "meta.last_id",
        "meta.has_more",
        "filters"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$accountId = getenv('FAKTURYPRO_ACCOUNT_ID');
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$ch = curl_init($baseUrl . '/api/events/list.php?id_konta=' . urlencode($accountId));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiToken],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const accountId = process.env.FAKTURYPRO_ACCOUNT_ID;
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const url = baseUrl + '/api/events/list.php?id_konta=' + encodeURIComponent(accountId);
const res = await fetch(url, {
  headers: { Authorization: 'Bearer ' + apiToken }
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
account_id = os.environ['FAKTURYPRO_ACCOUNT_ID']
api_token = os.environ['FAKTURYPRO_API_TOKEN']

response = requests.get(
    f'{base_url}/api/events/list.php',
    params={'id_konta': account_id},
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/events/list.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}"
}

Faktury

Tworzenie, odczyt, statusy, publiczne linki, wysyłka maili i płatności na dokumencie.

POST /api/faktury/create.php

Utworzenie faktury

Najczęstszy endpoint dla sklepu internetowego, CRM albo formularza zamówienia.

Parametry

external_id / order_id / idempotency_key
client lub klient
items lub pozycje
typ_faktury: faktura, proforma, oferta
data_wystawienia / issue_date
termin_platnosci / due_date

Odpowiedź

HTTP 201
invoice.id
invoice.numer
client_id
links.status
links.preview
links.pdf

Przykład curl

curl -X POST "https://faktury.pro/api/faktury/create.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "client": {
        "nazwa": "Testowy klient",
        "nip": "5250000000",
        "email": "klient@example.com"
    },
    "items": [
        {
            "nazwa": "Usługa wdrożeniowa",
            "ilosc": "1",
            "cena_netto": "100.00",
            "vat": "23"
        }
    ]
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "invoice": {
        "id": 123,
        "numer": "FV/6/2026/1",
        "external_id": "order-1001",
        "payment_status": "unpaid",
        "ksef_status": "draft"
    },
    "links": {
        "status": "https://faktury.pro/api/faktury/status.php",
        "preview": "https://faktury.pro/faktura/..."
    }
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
  'client' => 
  array (
    'nazwa' => 'Testowy klient',
    'nip' => '5250000000',
    'email' => 'klient@example.com',
  ),
  'items' => 
  array (
    0 => 
    array (
      'nazwa' => 'Usługa wdrożeniowa',
      'ilosc' => '1',
      'cena_netto' => '100.00',
      'vat' => '23',
    ),
  ),
);

$ch = curl_init($baseUrl . '/api/faktury/create.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "client": {
        "nazwa": "Testowy klient",
        "nip": "5250000000",
        "email": "klient@example.com"
    },
    "items": [
        {
            "nazwa": "Usługa wdrożeniowa",
            "ilosc": "1",
            "cena_netto": "100.00",
            "vat": "23"
        }
    ]
};

const res = await fetch(baseUrl + '/api/faktury/create.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
  'client' => 
  array (
    'nazwa' => 'Testowy klient',
    'nip' => '5250000000',
    'email' => 'klient@example.com',
  ),
  'items' => 
  array (
    0 => 
    array (
      'nazwa' => 'Usługa wdrożeniowa',
      'ilosc' => '1',
      'cena_netto' => '100.00',
      'vat' => '23',
    ),
  ),
)

response = requests.post(
    f'{base_url}/api/faktury/create.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

C# / .NET

using System.Net.Http.Headers;
using System.Text;

var baseUrl = "https://faktury.pro";
var apiToken = Environment.GetEnvironmentVariable("FAKTURYPRO_API_TOKEN");

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiToken);

var payload = @"{
    ""id_konta"": ""{{account_id}}"",
    ""external_id"": ""order-1001"",
    ""client"": {
        ""nazwa"": ""Testowy klient"",
        ""nip"": ""5250000000"",
        ""email"": ""klient@example.com""
    },
    ""items"": [
        {
            ""nazwa"": ""Usługa wdrożeniowa"",
            ""ilosc"": ""1"",
            ""cena_netto"": ""100.00"",
            ""vat"": ""23""
        }
    ]
}";
var body = new StringContent(payload, Encoding.UTF8, "application/json");
var res = await http.PostAsync(baseUrl + "/api/faktury/create.php", body);
var json = await res.Content.ReadAsStringAsync();
if (!res.IsSuccessStatusCode) throw new Exception("fakturyPRO API HTTP " + (int)res.StatusCode + ": " + json);
Console.WriteLine(json);

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String baseUrl = "https://faktury.pro";
String apiToken = System.getenv("FAKTURYPRO_API_TOKEN");
String payload = """
{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "client": {
        "nazwa": "Testowy klient",
        "nip": "5250000000",
        "email": "klient@example.com"
    },
    "items": [
        {
            "nazwa": "Usługa wdrożeniowa",
            "ilosc": "1",
            "cena_netto": "100.00",
            "vat": "23"
        }
    ]
}
""";

HttpRequest request = HttpRequest.newBuilder(URI.create(baseUrl + "/api/faktury/create.php"))
    .header("Authorization", "Bearer " + apiToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) throw new RuntimeException(response.body());
System.out.println(response.body());

Go

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  baseURL := "https://faktury.pro"
  apiToken := os.Getenv("FAKTURYPRO_API_TOKEN")
  payload := []byte(`{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "client": {
        "nazwa": "Testowy klient",
        "nip": "5250000000",
        "email": "klient@example.com"
    },
    "items": [
        {
            "nazwa": "Usługa wdrożeniowa",
            "ilosc": "1",
            "cena_netto": "100.00",
            "vat": "23"
        }
    ]
}`)

  req, _ := http.NewRequest("POST", baseURL+"/api/faktury/create.php", bytes.NewReader(payload))
  req.Header.Set("Authorization", "Bearer "+apiToken)
  req.Header.Set("Content-Type", "application/json")

  res, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  if res.StatusCode >= 400 { panic(string(body)) }
  fmt.Println(string(body))
}

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/faktury/create.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "client": {
        "nazwa": "Testowy klient",
        "nip": "5250000000",
        "email": "klient@example.com"
    },
    "items": [
        {
            "nazwa": "Usługa wdrożeniowa",
            "ilosc": "1",
            "cena_netto": "100.00",
            "vat": "23"
        }
    ]
}

GET /api/faktury/list.php

Lista faktur

Synchronizacja dokumentów do ERP, panelu klienta albo narzędzia BI.

Parametry

page
limit 1..100
date_from / date_to
client_id
nip
external_id
payment_status
q
sort

Odpowiedź

meta
filters
invoices[]

Przykład curl

curl -H "Authorization: Bearer {{api_token}}" \
  "https://faktury.pro/api/faktury/list.php?id_konta={{account_id}}"

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/faktury/list.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "meta",
        "filters",
        "invoices[]"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$accountId = getenv('FAKTURYPRO_ACCOUNT_ID');
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$ch = curl_init($baseUrl . '/api/faktury/list.php?id_konta=' . urlencode($accountId));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiToken],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const accountId = process.env.FAKTURYPRO_ACCOUNT_ID;
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const url = baseUrl + '/api/faktury/list.php?id_konta=' + encodeURIComponent(accountId);
const res = await fetch(url, {
  headers: { Authorization: 'Bearer ' + apiToken }
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
account_id = os.environ['FAKTURYPRO_ACCOUNT_ID']
api_token = os.environ['FAKTURYPRO_API_TOKEN']

response = requests.get(
    f'{base_url}/api/faktury/list.php',
    params={'id_konta': account_id},
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/faktury/list.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}"
}

POST /api/faktury/detail.php

Szczegóły faktury

Pobranie pełnego dokumentu razem z pozycjami i linkami publicznymi.

Parametry

id / invoice_id
numer / number
external_id / order_id / idempotency_key

Odpowiedź

invoice
invoice.items
invoice.links.public
invoice.links.public_pdf

Przykład curl

curl -X POST "https://faktury.pro/api/faktury/detail.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001"
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/faktury/detail.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "invoice",
        "invoice.items",
        "invoice.links.public",
        "invoice.links.public_pdf"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
);

$ch = curl_init($baseUrl . '/api/faktury/detail.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "external_id": "order-1001"
};

const res = await fetch(baseUrl + '/api/faktury/detail.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
)

response = requests.post(
    f'{base_url}/api/faktury/detail.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/faktury/detail.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001"
}

POST /api/faktury/status.php

Status faktury

Lekki odczyt statusu płatności i KSeF bez pobierania całego dokumentu.

Parametry

id / invoice_id
numer / number
external_id / order_id

Odpowiedź

payment_status
kwota_oplacona
pozostalo_do_zaplaty
ksef_status
ksef_number

Przykład curl

curl -X POST "https://faktury.pro/api/faktury/status.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001"
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/faktury/status.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "payment_status",
        "kwota_oplacona",
        "pozostalo_do_zaplaty",
        "ksef_status",
        "ksef_number"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
);

$ch = curl_init($baseUrl . '/api/faktury/status.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "external_id": "order-1001"
};

const res = await fetch(baseUrl + '/api/faktury/status.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
)

response = requests.post(
    f'{base_url}/api/faktury/status.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/faktury/status.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001"
}

POST /api/faktury/history.php

Historia faktury

Audyt zmian i synchronizacja wpisow historii faktury po kursorze.

Parametry

id / numer / external_id
after_id
since
type
limit 1..100

Odpowiedź

invoice
events[]
meta.last_id
meta.has_more

Przykład curl

curl -X POST "https://faktury.pro/api/faktury/history.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "limit": 20
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/faktury/history.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "invoice",
        "events[]",
        "meta.last_id",
        "meta.has_more"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
  'limit' => 20,
);

$ch = curl_init($baseUrl . '/api/faktury/history.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "limit": 20
};

const res = await fetch(baseUrl + '/api/faktury/history.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
  'limit' => 20,
)

response = requests.post(
    f'{base_url}/api/faktury/history.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/faktury/history.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "limit": 20
}

POST /api/faktury/public-link.php

Publiczny link faktury

Gdy sklep albo CRM chce zapisać link do podglądu/PDF bez wysyłania maila.

Parametry

id / invoice_id
numer / invoice_number
external_id / idempotency_key

Odpowiedź

public_token
links.public
links.public_pdf
links.public_xml

Przykład curl

curl -X POST "https://faktury.pro/api/faktury/public-link.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001"
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/faktury/public-link.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "public_token",
        "links.public",
        "links.public_pdf",
        "links.public_xml"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
);

$ch = curl_init($baseUrl . '/api/faktury/public-link.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "external_id": "order-1001"
};

const res = await fetch(baseUrl + '/api/faktury/public-link.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
)

response = requests.post(
    f'{base_url}/api/faktury/public-link.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/faktury/public-link.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001"
}

POST /api/faktury/send.php

Wysyłka faktury albo przypomnienia

Wyślij klientowi dokument lub przypomnienie z PDF-em po stronie fakturyPRO.

Parametry

id / numer / external_id
mode: invoice albo reminder
email / email_to
attach_pdf
allow_paid

Odpowiedź

sent
recipient_email
links
notification

Przykład curl

curl -X POST "https://faktury.pro/api/faktury/send.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "mode": "invoice",
    "attach_pdf": true
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/faktury/send.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "sent",
        "recipient_email",
        "links",
        "notification"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
  'mode' => 'invoice',
  'attach_pdf' => true,
);

$ch = curl_init($baseUrl . '/api/faktury/send.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "mode": "invoice",
    "attach_pdf": true
};

const res = await fetch(baseUrl + '/api/faktury/send.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
  'mode' => 'invoice',
  'attach_pdf' => true,
)

response = requests.post(
    f'{base_url}/api/faktury/send.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/faktury/send.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "mode": "invoice",
    "attach_pdf": true
}

POST /api/faktury/payment.php

Aktualizacja płatności faktury

CRM, sklep albo operator płatności zna status wpłaty i ma zaktualizować fakturę.

Parametry

id / numer / external_id
status: paid, partial, unpaid
amount
payment_date
transaction_id
provider

Odpowiedź

invoice
payment
duplicate

Przykład curl

curl -X POST "https://faktury.pro/api/faktury/payment.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "status": "paid",
    "amount": "123.00",
    "transaction_id": "pay-1001",
    "provider": "shop"
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/faktury/payment.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "invoice",
        "payment",
        "duplicate"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
  'status' => 'paid',
  'amount' => '123.00',
  'transaction_id' => 'pay-1001',
  'provider' => 'shop',
);

$ch = curl_init($baseUrl . '/api/faktury/payment.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "status": "paid",
    "amount": "123.00",
    "transaction_id": "pay-1001",
    "provider": "shop"
};

const res = await fetch(baseUrl + '/api/faktury/payment.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'external_id' => 'order-1001',
  'status' => 'paid',
  'amount' => '123.00',
  'transaction_id' => 'pay-1001',
  'provider' => 'shop',
)

response = requests.post(
    f'{base_url}/api/faktury/payment.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/faktury/payment.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "external_id": "order-1001",
    "status": "paid",
    "amount": "123.00",
    "transaction_id": "pay-1001",
    "provider": "shop"
}

Operacje zbiorcze

Bezpieczne endpointy dla migracji, sklepów z dużym ruchem i retry po timeoutach.

POST /api/faktury/bulk-create.php

Bulk create faktur

Import paczki zamówień albo cykliczna synchronizacja managera zamówień.

Parametry

invoices / faktury max 50
continue_on_error
każdy element jak create.php

Odpowiedź

HTTP 201 albo 207
summary
results[]
duplicate=true dla powtórek external_id

Przykład curl

curl -X POST "https://faktury.pro/api/faktury/bulk-create.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "continue_on_error": true,
    "invoices": [
        {
            "external_id": "order-1001",
            "client": {
                "nazwa": "Klient A"
            },
            "items": [
                {
                    "nazwa": "Towar",
                    "ilosc": "1",
                    "cena_netto": "50.00",
                    "vat": "23"
                }
            ]
        }
    ]
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/faktury/bulk-create.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "HTTP 201 albo 207",
        "summary",
        "results[]",
        "duplicate=true dla powtórek external_id"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'continue_on_error' => true,
  'invoices' => 
  array (
    0 => 
    array (
      'external_id' => 'order-1001',
      'client' => 
      array (
        'nazwa' => 'Klient A',
      ),
      'items' => 
      array (
        0 => 
        array (
          'nazwa' => 'Towar',
          'ilosc' => '1',
          'cena_netto' => '50.00',
          'vat' => '23',
        ),
      ),
    ),
  ),
);

$ch = curl_init($baseUrl . '/api/faktury/bulk-create.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "continue_on_error": true,
    "invoices": [
        {
            "external_id": "order-1001",
            "client": {
                "nazwa": "Klient A"
            },
            "items": [
                {
                    "nazwa": "Towar",
                    "ilosc": "1",
                    "cena_netto": "50.00",
                    "vat": "23"
                }
            ]
        }
    ]
};

const res = await fetch(baseUrl + '/api/faktury/bulk-create.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'continue_on_error' => true,
  'invoices' => 
  array (
    0 => 
    array (
      'external_id' => 'order-1001',
      'client' => 
      array (
        'nazwa' => 'Klient A',
      ),
      'items' => 
      array (
        0 => 
        array (
          'nazwa' => 'Towar',
          'ilosc' => '1',
          'cena_netto' => '50.00',
          'vat' => '23',
        ),
      ),
    ),
  ),
)

response = requests.post(
    f'{base_url}/api/faktury/bulk-create.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/faktury/bulk-create.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "continue_on_error": true,
    "invoices": [
        {
            "external_id": "order-1001",
            "client": {
                "nazwa": "Klient A"
            },
            "items": [
                {
                    "nazwa": "Towar",
                    "ilosc": "1",
                    "cena_netto": "50.00",
                    "vat": "23"
                }
            ]
        }
    ]
}

POST /api/faktury/bulk-status.php

Bulk status faktur

Jednym requestem sprawdź statusy wielu dokumentów po identyfikatorach sklepu.

Parametry

invoices / faktury / items max 100
id / invoice_id
numer / number
external_id / order_id

Odpowiedź

summary.requested
summary.found
summary.missing
results[]

Przykład curl

curl -X POST "https://faktury.pro/api/faktury/bulk-status.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "invoices": [
        {
            "external_id": "order-1001"
        },
        {
            "external_id": "order-1002"
        }
    ]
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/faktury/bulk-status.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "summary.requested",
        "summary.found",
        "summary.missing",
        "results[]"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'invoices' => 
  array (
    0 => 
    array (
      'external_id' => 'order-1001',
    ),
    1 => 
    array (
      'external_id' => 'order-1002',
    ),
  ),
);

$ch = curl_init($baseUrl . '/api/faktury/bulk-status.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "invoices": [
        {
            "external_id": "order-1001"
        },
        {
            "external_id": "order-1002"
        }
    ]
};

const res = await fetch(baseUrl + '/api/faktury/bulk-status.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'invoices' => 
  array (
    0 => 
    array (
      'external_id' => 'order-1001',
    ),
    1 => 
    array (
      'external_id' => 'order-1002',
    ),
  ),
)

response = requests.post(
    f'{base_url}/api/faktury/bulk-status.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/faktury/bulk-status.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "invoices": [
        {
            "external_id": "order-1001"
        },
        {
            "external_id": "order-1002"
        }
    ]
}

POST /api/faktury/bulk-payment.php

Bulk payment

Masowe oznaczenie płatności po eksporcie z bramki albo banku.

Parametry

payments / platnosci / items max 100
status globalnie lub per element
transaction_id
continue_on_error

Odpowiedź

summary.updated
summary.duplicates
summary.failed
results[]

Przykład curl

curl -X POST "https://faktury.pro/api/faktury/bulk-payment.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "continue_on_error": true,
    "payments": [
        {
            "external_id": "order-1001",
            "status": "paid",
            "amount": "123.00",
            "transaction_id": "tx-1001"
        }
    ]
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/faktury/bulk-payment.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "summary.updated",
        "summary.duplicates",
        "summary.failed",
        "results[]"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'continue_on_error' => true,
  'payments' => 
  array (
    0 => 
    array (
      'external_id' => 'order-1001',
      'status' => 'paid',
      'amount' => '123.00',
      'transaction_id' => 'tx-1001',
    ),
  ),
);

$ch = curl_init($baseUrl . '/api/faktury/bulk-payment.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "continue_on_error": true,
    "payments": [
        {
            "external_id": "order-1001",
            "status": "paid",
            "amount": "123.00",
            "transaction_id": "tx-1001"
        }
    ]
};

const res = await fetch(baseUrl + '/api/faktury/bulk-payment.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'continue_on_error' => true,
  'payments' => 
  array (
    0 => 
    array (
      'external_id' => 'order-1001',
      'status' => 'paid',
      'amount' => '123.00',
      'transaction_id' => 'tx-1001',
    ),
  ),
)

response = requests.post(
    f'{base_url}/api/faktury/bulk-payment.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/faktury/bulk-payment.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "continue_on_error": true,
    "payments": [
        {
            "external_id": "order-1001",
            "status": "paid",
            "amount": "123.00",
            "transaction_id": "tx-1001"
        }
    ]
}

POST /api/faktury/bulk-send.php

Bulk send

Wysyłka wielu faktur albo przypomnień po stronie fakturyPRO.

Parametry

invoices / faktury / items max 50
mode
attach_pdf
email per element
continue_on_error

Odpowiedź

summary.sent
summary.failed
results[]

Przykład curl

curl -X POST "https://faktury.pro/api/faktury/bulk-send.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "mode": "invoice",
    "invoices": [
        {
            "external_id": "order-1001"
        }
    ]
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/faktury/bulk-send.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "summary.sent",
        "summary.failed",
        "results[]"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'mode' => 'invoice',
  'invoices' => 
  array (
    0 => 
    array (
      'external_id' => 'order-1001',
    ),
  ),
);

$ch = curl_init($baseUrl . '/api/faktury/bulk-send.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "mode": "invoice",
    "invoices": [
        {
            "external_id": "order-1001"
        }
    ]
};

const res = await fetch(baseUrl + '/api/faktury/bulk-send.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'mode' => 'invoice',
  'invoices' => 
  array (
    0 => 
    array (
      'external_id' => 'order-1001',
    ),
  ),
)

response = requests.post(
    f'{base_url}/api/faktury/bulk-send.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/faktury/bulk-send.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "mode": "invoice",
    "invoices": [
        {
            "external_id": "order-1001"
        }
    ]
}

KSeF

Publiczne API do sprawdzenia gotowości, wygenerowania XML, wysłania faktury do KSeF i odświeżenia statusu.

GET/POST /api/ksef/ready.php

Gotowość faktury do KSeF

Sprawdź braki przed wysyłką: sprzedawca, nabywca, pozycje, płatność i typ dokumentu.

Parametry

id / invoice_id
numer / number
external_id / order_id

Odpowiedź

ready
can_send
checks.counts
checks.rows[]
environment

Przykład curl

curl -X POST "https://faktury.pro/api/ksef/ready.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "invoice_id": 1
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "ready": true,
    "can_send": true,
    "environment": "test",
    "checks": {
        "counts": {
            "ok": 7,
            "warn": 1,
            "err": 0
        },
        "rows": [
            {
                "area": "Sprzedawca",
                "status": "ok",
                "message": "NIP: 5250000000"
            }
        ]
    }
}

Błąd

{
    "ok": false,
    "error": "ksef_failed",
    "message": "Operacja KSeF nie powiodła się.",
    "details": [
        "Sprawdź token KSeF, środowisko i gotowość faktury."
    ]
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'invoice_id' => 1,
);

$ch = curl_init($baseUrl . '/api/ksef/ready.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "invoice_id": 1
};

const res = await fetch(baseUrl + '/api/ksef/ready.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'invoice_id' => 1,
)

response = requests.post(
    f'{base_url}/api/ksef/ready.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/ksef/ready.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "invoice_id": 1
}

POST /api/ksef/xml.php

XML KSeF bez wysyłki

Wygeneruj i zapisz XML FA(3) przy fakturze, zanim wyślesz dokument do KSeF.

Parametry

id / invoice_id
include_xml
force tylko świadomie przy ostrzeżeniach

Odpowiedź

xml_saved
xml
invoice

Przykład curl

curl -X POST "https://faktury.pro/api/ksef/xml.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "include_xml": true
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "xml_saved": true,
    "invoice": {
        "id": 123,
        "ksef_status": "xml_ready"
    },
    "xml": "<Faktura xmlns=\"http://crd.gov.pl/wzor/2025/06/25/13775/\">...</Faktura>"
}

Błąd

{
    "ok": false,
    "error": "ksef_failed",
    "message": "Operacja KSeF nie powiodła się.",
    "details": [
        "Sprawdź token KSeF, środowisko i gotowość faktury."
    ]
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'invoice_id' => 1,
  'include_xml' => true,
);

$ch = curl_init($baseUrl . '/api/ksef/xml.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "include_xml": true
};

const res = await fetch(baseUrl + '/api/ksef/xml.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'invoice_id' => 1,
  'include_xml' => true,
)

response = requests.post(
    f'{base_url}/api/ksef/xml.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/ksef/xml.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "include_xml": true
}

POST /api/ksef/send.php

Wysyłka faktury do KSeF

Wyślij fakturę utworzoną przez API lub panel do KSeF i zapisz numery referencyjne.

Parametry

id / invoice_id
numer / number
external_id / order_id
force opcjonalnie

Odpowiedź

status=processing
ksef.session_reference_number
ksef.invoice_reference_number
links.status

Przykład curl

curl -X POST "https://faktury.pro/api/ksef/send.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "invoice_id": 1
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "status": "processing",
    "invoice": {
        "id": 123,
        "ksef_status": "processing"
    },
    "ksef": {
        "session_reference_number": "20260614-SE-...",
        "invoice_reference_number": "20260614-INV-..."
    },
    "links": {
        "status": "https://faktury.pro/api/ksef/status.php?id_konta=123&id=123"
    }
}

Błąd

{
    "ok": false,
    "error": "ksef_failed",
    "message": "Operacja KSeF nie powiodła się.",
    "details": [
        "Sprawdź token KSeF, środowisko i gotowość faktury."
    ]
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'invoice_id' => 1,
);

$ch = curl_init($baseUrl . '/api/ksef/send.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "invoice_id": 1
};

const res = await fetch(baseUrl + '/api/ksef/send.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'invoice_id' => 1,
)

response = requests.post(
    f'{base_url}/api/ksef/send.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

C# / .NET

using System.Net.Http.Headers;
using System.Text;

var baseUrl = "https://faktury.pro";
var apiToken = Environment.GetEnvironmentVariable("FAKTURYPRO_API_TOKEN");

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiToken);

var payload = @"{
    ""id_konta"": ""{{account_id}}"",
    ""invoice_id"": 1
}";
var body = new StringContent(payload, Encoding.UTF8, "application/json");
var res = await http.PostAsync(baseUrl + "/api/ksef/send.php", body);
var json = await res.Content.ReadAsStringAsync();
if (!res.IsSuccessStatusCode) throw new Exception("fakturyPRO API HTTP " + (int)res.StatusCode + ": " + json);
Console.WriteLine(json);

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String baseUrl = "https://faktury.pro";
String apiToken = System.getenv("FAKTURYPRO_API_TOKEN");
String payload = """
{
    "id_konta": "{{account_id}}",
    "invoice_id": 1
}
""";

HttpRequest request = HttpRequest.newBuilder(URI.create(baseUrl + "/api/ksef/send.php"))
    .header("Authorization", "Bearer " + apiToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) throw new RuntimeException(response.body());
System.out.println(response.body());

Go

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  baseURL := "https://faktury.pro"
  apiToken := os.Getenv("FAKTURYPRO_API_TOKEN")
  payload := []byte(`{
    "id_konta": "{{account_id}}",
    "invoice_id": 1
}`)

  req, _ := http.NewRequest("POST", baseURL+"/api/ksef/send.php", bytes.NewReader(payload))
  req.Header.Set("Authorization", "Bearer "+apiToken)
  req.Header.Set("Content-Type", "application/json")

  res, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  if res.StatusCode >= 400 { panic(string(body)) }
  fmt.Println(string(body))
}

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/ksef/send.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "invoice_id": 1
}

GET/POST /api/ksef/status.php

Status faktury w KSeF

Odśwież status po wysyłce: accepted, duplicate, rejected albo processing.

Parametry

id / invoice_id
refresh domyślnie true

Odpowiedź

invoice.ksef_status
invoice.ksef_number
ksef.status_code
ksef.status_details
ksef.qr_url

Przykład curl

curl -X POST "https://faktury.pro/api/ksef/status.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "refresh": true
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "status": "accepted",
    "invoice": {
        "id": 123,
        "ksef_status": "accepted",
        "ksef_number": "1234567890-20260614-ABCDEF"
    },
    "ksef": {
        "status_code": 200,
        "status_description": "Dokument przyjęty",
        "ksef_number": "1234567890-20260614-ABCDEF"
    }
}

Błąd

{
    "ok": false,
    "error": "ksef_failed",
    "message": "Operacja KSeF nie powiodła się.",
    "details": [
        "Sprawdź token KSeF, środowisko i gotowość faktury."
    ]
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'invoice_id' => 1,
  'refresh' => true,
);

$ch = curl_init($baseUrl . '/api/ksef/status.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "refresh": true
};

const res = await fetch(baseUrl + '/api/ksef/status.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'invoice_id' => 1,
  'refresh' => true,
)

response = requests.post(
    f'{base_url}/api/ksef/status.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

C# / .NET

using System.Net.Http.Headers;
using System.Text;

var baseUrl = "https://faktury.pro";
var apiToken = Environment.GetEnvironmentVariable("FAKTURYPRO_API_TOKEN");

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiToken);

var payload = @"{
    ""id_konta"": ""{{account_id}}"",
    ""invoice_id"": 1,
    ""refresh"": true
}";
var body = new StringContent(payload, Encoding.UTF8, "application/json");
var res = await http.PostAsync(baseUrl + "/api/ksef/status.php", body);
var json = await res.Content.ReadAsStringAsync();
if (!res.IsSuccessStatusCode) throw new Exception("fakturyPRO API HTTP " + (int)res.StatusCode + ": " + json);
Console.WriteLine(json);

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String baseUrl = "https://faktury.pro";
String apiToken = System.getenv("FAKTURYPRO_API_TOKEN");
String payload = """
{
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "refresh": true
}
""";

HttpRequest request = HttpRequest.newBuilder(URI.create(baseUrl + "/api/ksef/status.php"))
    .header("Authorization", "Bearer " + apiToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) throw new RuntimeException(response.body());
System.out.println(response.body());

Go

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  baseURL := "https://faktury.pro"
  apiToken := os.Getenv("FAKTURYPRO_API_TOKEN")
  payload := []byte(`{
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "refresh": true
}`)

  req, _ := http.NewRequest("POST", baseURL+"/api/ksef/status.php", bytes.NewReader(payload))
  req.Header.Set("Authorization", "Bearer "+apiToken)
  req.Header.Set("Content-Type", "application/json")

  res, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  if res.StatusCode >= 400 { panic(string(body)) }
  fmt.Println(string(body))
}

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/ksef/status.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "refresh": true
}

Klienci i produkty

Katalog kontrahentów oraz produktów/usług z aliasami polskimi i angielskimi.

GET /api/clients/list.php

Lista klientów

CRM albo sklep chce wyszukać istniejącego kontrahenta.

Parametry

page
limit
id / client_id
q
nip / tax_id
email
sort

Odpowiedź

meta
filters
clients[]

Przykład curl

curl -H "Authorization: Bearer {{api_token}}" \
  "https://faktury.pro/api/clients/list.php?id_konta={{account_id}}"

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/clients/list.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "meta",
        "filters",
        "clients[]"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$accountId = getenv('FAKTURYPRO_ACCOUNT_ID');
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$ch = curl_init($baseUrl . '/api/clients/list.php?id_konta=' . urlencode($accountId));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiToken],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const accountId = process.env.FAKTURYPRO_ACCOUNT_ID;
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const url = baseUrl + '/api/clients/list.php?id_konta=' + encodeURIComponent(accountId);
const res = await fetch(url, {
  headers: { Authorization: 'Bearer ' + apiToken }
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
account_id = os.environ['FAKTURYPRO_ACCOUNT_ID']
api_token = os.environ['FAKTURYPRO_API_TOKEN']

response = requests.get(
    f'{base_url}/api/clients/list.php',
    params={'id_konta': account_id},
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/clients/list.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}"
}

POST /api/clients/detail.php

Szczegóły klienta

Pełna karta klienta, statystyki, ostatnie faktury i rachunki płatnika.

Parametry

id / client_id
nip / tax_id
customer_number
email
invoice_limit
transfer_limit

Odpowiedź

client
stats
recent_invoices
payer_accounts

Przykład curl

curl -X POST "https://faktury.pro/api/clients/detail.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "nip": "5250000000",
    "invoice_limit": 10
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/clients/detail.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "client",
        "stats",
        "recent_invoices",
        "payer_accounts"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'nip' => '5250000000',
  'invoice_limit' => 10,
);

$ch = curl_init($baseUrl . '/api/clients/detail.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "nip": "5250000000",
    "invoice_limit": 10
};

const res = await fetch(baseUrl + '/api/clients/detail.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'nip' => '5250000000',
  'invoice_limit' => 10,
)

response = requests.post(
    f'{base_url}/api/clients/detail.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/clients/detail.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "nip": "5250000000",
    "invoice_limit": 10
}

POST /api/clients/upsert.php

Dodanie lub aktualizacja klienta

Upsert kontrahenta przed wystawieniem faktury albo synchronizacja CRM.

Parametry

client / klient
name / nazwa
tax_id / nip
email
customer_number
default_due_days
pola KSeF/VAT UE

Odpowiedź

created
client.id
client

Przykład curl

curl -X POST "https://faktury.pro/api/clients/upsert.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "client": {
        "name": "ACME Sp. z o.o.",
        "tax_id": "5250000000",
        "email": "finanse@example.com",
        "customer_number": "CRM-42"
    }
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/clients/upsert.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "created",
        "client.id",
        "client"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'client' => 
  array (
    'name' => 'ACME Sp. z o.o.',
    'tax_id' => '5250000000',
    'email' => 'finanse@example.com',
    'customer_number' => 'CRM-42',
  ),
);

$ch = curl_init($baseUrl . '/api/clients/upsert.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "client": {
        "name": "ACME Sp. z o.o.",
        "tax_id": "5250000000",
        "email": "finanse@example.com",
        "customer_number": "CRM-42"
    }
};

const res = await fetch(baseUrl + '/api/clients/upsert.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'client' => 
  array (
    'name' => 'ACME Sp. z o.o.',
    'tax_id' => '5250000000',
    'email' => 'finanse@example.com',
    'customer_number' => 'CRM-42',
  ),
)

response = requests.post(
    f'{base_url}/api/clients/upsert.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/clients/upsert.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "client": {
        "name": "ACME Sp. z o.o.",
        "tax_id": "5250000000",
        "email": "finanse@example.com",
        "customer_number": "CRM-42"
    }
}

POST /api/clients/bulk-upsert.php

Bulk upsert klientów

Migracja albo okresowa synchronizacja bazy kontrahentów.

Parametry

clients / klienci / items max 100
mode: upsert, create, update
continue_on_error

Odpowiedź

HTTP 200 albo 207
summary
results[]

Przykład curl

curl -X POST "https://faktury.pro/api/clients/bulk-upsert.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "continue_on_error": true,
    "clients": [
        {
            "name": "ACME Sp. z o.o.",
            "tax_id": "5250000000"
        }
    ]
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/clients/bulk-upsert.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "HTTP 200 albo 207",
        "summary",
        "results[]"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'continue_on_error' => true,
  'clients' => 
  array (
    0 => 
    array (
      'name' => 'ACME Sp. z o.o.',
      'tax_id' => '5250000000',
    ),
  ),
);

$ch = curl_init($baseUrl . '/api/clients/bulk-upsert.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "continue_on_error": true,
    "clients": [
        {
            "name": "ACME Sp. z o.o.",
            "tax_id": "5250000000"
        }
    ]
};

const res = await fetch(baseUrl + '/api/clients/bulk-upsert.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'continue_on_error' => true,
  'clients' => 
  array (
    0 => 
    array (
      'name' => 'ACME Sp. z o.o.',
      'tax_id' => '5250000000',
    ),
  ),
)

response = requests.post(
    f'{base_url}/api/clients/bulk-upsert.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/clients/bulk-upsert.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "continue_on_error": true,
    "clients": [
        {
            "name": "ACME Sp. z o.o.",
            "tax_id": "5250000000"
        }
    ]
}

GET /api/products/list.php

Lista produktów i usług

Pobranie katalogu pozycji do sklepu, CRM lub formularza zamówień.

Parametry

page
limit
id / product_id
q
active
sort

Odpowiedź

meta
filters
products[]

Przykład curl

curl -H "Authorization: Bearer {{api_token}}" \
  "https://faktury.pro/api/products/list.php?id_konta={{account_id}}"

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/products/list.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "meta",
        "filters",
        "products[]"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$accountId = getenv('FAKTURYPRO_ACCOUNT_ID');
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$ch = curl_init($baseUrl . '/api/products/list.php?id_konta=' . urlencode($accountId));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiToken],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const accountId = process.env.FAKTURYPRO_ACCOUNT_ID;
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const url = baseUrl + '/api/products/list.php?id_konta=' + encodeURIComponent(accountId);
const res = await fetch(url, {
  headers: { Authorization: 'Bearer ' + apiToken }
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
account_id = os.environ['FAKTURYPRO_ACCOUNT_ID']
api_token = os.environ['FAKTURYPRO_API_TOKEN']

response = requests.get(
    f'{base_url}/api/products/list.php',
    params={'id_konta': account_id},
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/products/list.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}"
}

POST /api/products/upsert.php

Dodanie lub aktualizacja produktu

Utrzymanie katalogu usług i towarów z zewnętrznego systemu.

Parametry

product / produkt
name / nazwa
unit
net_unit_price
vat_rate
sale_type
active
order

Odpowiedź

created
product.id
product

Przykład curl

curl -X POST "https://faktury.pro/api/products/upsert.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "product": {
        "name": "Abonament PRO",
        "unit": "szt.",
        "net_unit_price": "99.00",
        "vat_rate": "23"
    }
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/products/upsert.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "created",
        "product.id",
        "product"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'product' => 
  array (
    'name' => 'Abonament PRO',
    'unit' => 'szt.',
    'net_unit_price' => '99.00',
    'vat_rate' => '23',
  ),
);

$ch = curl_init($baseUrl . '/api/products/upsert.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "product": {
        "name": "Abonament PRO",
        "unit": "szt.",
        "net_unit_price": "99.00",
        "vat_rate": "23"
    }
};

const res = await fetch(baseUrl + '/api/products/upsert.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'product' => 
  array (
    'name' => 'Abonament PRO',
    'unit' => 'szt.',
    'net_unit_price' => '99.00',
    'vat_rate' => '23',
  ),
)

response = requests.post(
    f'{base_url}/api/products/upsert.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/products/upsert.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "product": {
        "name": "Abonament PRO",
        "unit": "szt.",
        "net_unit_price": "99.00",
        "vat_rate": "23"
    }
}

POST /api/products/bulk-upsert.php

Bulk upsert produktów

Masowe założenie lub odświeżenie katalogu pozycji.

Parametry

products / produkty / items max 100
mode
continue_on_error

Odpowiedź

summary
results[]

Przykład curl

curl -X POST "https://faktury.pro/api/products/bulk-upsert.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "products": [
        {
            "name": "Usługa testowa",
            "net_unit_price": "100.00",
            "vat_rate": "23"
        }
    ]
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/products/bulk-upsert.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "summary",
        "results[]"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'products' => 
  array (
    0 => 
    array (
      'name' => 'Usługa testowa',
      'net_unit_price' => '100.00',
      'vat_rate' => '23',
    ),
  ),
);

$ch = curl_init($baseUrl . '/api/products/bulk-upsert.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "products": [
        {
            "name": "Usługa testowa",
            "net_unit_price": "100.00",
            "vat_rate": "23"
        }
    ]
};

const res = await fetch(baseUrl + '/api/products/bulk-upsert.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'products' => 
  array (
    0 => 
    array (
      'name' => 'Usługa testowa',
      'net_unit_price' => '100.00',
      'vat_rate' => '23',
    ),
  ),
)

response = requests.post(
    f'{base_url}/api/products/bulk-upsert.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/products/bulk-upsert.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "products": [
        {
            "name": "Usługa testowa",
            "net_unit_price": "100.00",
            "vat_rate": "23"
        }
    ]
}

Księgowość, koszty i bank

Endpointy dla biur rachunkowych, importów bankowych, kosztów i uzgadniania płatności.

POST /api/accounting/summary.php

Podsumowanie księgowe

Biuro rachunkowe albo ERP pobiera dokumenty z okresu i status przekazania.

Parametry

date_from / date_to
scope: all, sales, costs
accounting_status

Odpowiedź

sales
costs
links.csv
links.zip

Przykład curl

curl -X POST "https://faktury.pro/api/accounting/summary.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "date_from": "2026-06-01",
    "date_to": "2026-06-30",
    "scope": "all"
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/accounting/summary.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "sales",
        "costs",
        "links.csv",
        "links.zip"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'date_from' => '2026-06-01',
  'date_to' => '2026-06-30',
  'scope' => 'all',
);

$ch = curl_init($baseUrl . '/api/accounting/summary.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "date_from": "2026-06-01",
    "date_to": "2026-06-30",
    "scope": "all"
};

const res = await fetch(baseUrl + '/api/accounting/summary.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'date_from' => '2026-06-01',
  'date_to' => '2026-06-30',
  'scope' => 'all',
)

response = requests.post(
    f'{base_url}/api/accounting/summary.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/accounting/summary.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "date_from": "2026-06-01",
    "date_to": "2026-06-30",
    "scope": "all"
}

POST /api/accounting/mark.php

Oznaczenie jako przekazane księgowości

Po eksporcie dokumentów ustaw status przekazania lub cofnij oznaczenie.

Parametry

scope
sent / accounting_sent
sales_ids / invoice_ids
cost_ids
date_from / date_to

Odpowiedź

updated
sales
costs

Przykład curl

curl -X POST "https://faktury.pro/api/accounting/mark.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "scope": "sales",
    "sent": true,
    "date_from": "2026-06-01",
    "date_to": "2026-06-30"
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/accounting/mark.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "updated",
        "sales",
        "costs"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'scope' => 'sales',
  'sent' => true,
  'date_from' => '2026-06-01',
  'date_to' => '2026-06-30',
);

$ch = curl_init($baseUrl . '/api/accounting/mark.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "scope": "sales",
    "sent": true,
    "date_from": "2026-06-01",
    "date_to": "2026-06-30"
};

const res = await fetch(baseUrl + '/api/accounting/mark.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'scope' => 'sales',
  'sent' => true,
  'date_from' => '2026-06-01',
  'date_to' => '2026-06-30',
)

response = requests.post(
    f'{base_url}/api/accounting/mark.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/accounting/mark.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "scope": "sales",
    "sent": true,
    "date_from": "2026-06-01",
    "date_to": "2026-06-30"
}

GET /api/costs/list.php

Lista kosztów

Pobranie kosztów/KSeF zakupowych do księgowości albo asystenta.

Parametry

page
limit
date_from
date_to
status
q

Odpowiedź

costs
meta
filters

Przykład curl

curl -H "Authorization: Bearer {{api_token}}" \
  "https://faktury.pro/api/costs/list.php?id_konta={{account_id}}"

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/costs/list.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "costs",
        "meta",
        "filters"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$accountId = getenv('FAKTURYPRO_ACCOUNT_ID');
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$ch = curl_init($baseUrl . '/api/costs/list.php?id_konta=' . urlencode($accountId));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiToken],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const accountId = process.env.FAKTURYPRO_ACCOUNT_ID;
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const url = baseUrl + '/api/costs/list.php?id_konta=' + encodeURIComponent(accountId);
const res = await fetch(url, {
  headers: { Authorization: 'Bearer ' + apiToken }
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
account_id = os.environ['FAKTURYPRO_ACCOUNT_ID']
api_token = os.environ['FAKTURYPRO_API_TOKEN']

response = requests.get(
    f'{base_url}/api/costs/list.php',
    params={'id_konta': account_id},
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/costs/list.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}"
}

POST /api/costs/detail.php

Szczegóły kosztu

Pełny odczyt pojedynczego kosztu z załącznikami i statusem.

Parametry

id / cost_id

Odpowiedź

cost
files
history

Przykład curl

curl -X POST "https://faktury.pro/api/costs/detail.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "cost_id": 1
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/costs/detail.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "cost",
        "files",
        "history"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'cost_id' => 1,
);

$ch = curl_init($baseUrl . '/api/costs/detail.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "cost_id": 1
};

const res = await fetch(baseUrl + '/api/costs/detail.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'cost_id' => 1,
)

response = requests.post(
    f'{base_url}/api/costs/detail.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/costs/detail.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "cost_id": 1
}

POST /api/costs/status.php

Zmiana statusu kosztu

Workflow akceptacji kosztów albo oznaczenie jako przekazane.

Parametry

id / cost_id
status
category
note

Odpowiedź

cost
history

Przykład curl

curl -X POST "https://faktury.pro/api/costs/status.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "cost_id": 1,
    "status": "accepted"
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/costs/status.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "cost",
        "history"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'cost_id' => 1,
  'status' => 'accepted',
);

$ch = curl_init($baseUrl . '/api/costs/status.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "cost_id": 1,
    "status": "accepted"
};

const res = await fetch(baseUrl + '/api/costs/status.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'cost_id' => 1,
  'status' => 'accepted',
)

response = requests.post(
    f'{base_url}/api/costs/status.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/costs/status.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "cost_id": 1,
    "status": "accepted"
}

GET /api/bank/transfers.php

Lista przelewów bankowych

Narzędzie uzgadnia przelewy z fakturami.

Parametry

page
limit
date_from
date_to
status
q

Odpowiedź

transfers
summary
meta

Przykład curl

curl -H "Authorization: Bearer {{api_token}}" \
  "https://faktury.pro/api/bank/transfers.php?id_konta={{account_id}}"

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/bank/transfers.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "transfers",
        "summary",
        "meta"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$accountId = getenv('FAKTURYPRO_ACCOUNT_ID');
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$ch = curl_init($baseUrl . '/api/bank/transfers.php?id_konta=' . urlencode($accountId));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiToken],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const accountId = process.env.FAKTURYPRO_ACCOUNT_ID;
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const url = baseUrl + '/api/bank/transfers.php?id_konta=' + encodeURIComponent(accountId);
const res = await fetch(url, {
  headers: { Authorization: 'Bearer ' + apiToken }
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
account_id = os.environ['FAKTURYPRO_ACCOUNT_ID']
api_token = os.environ['FAKTURYPRO_API_TOKEN']

response = requests.get(
    f'{base_url}/api/bank/transfers.php',
    params={'id_konta': account_id},
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/bank/transfers.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}"
}

POST /api/bank/import.php

Import operacji bankowych

Zewnętrzny parser bankowy wysyła transakcje do fakturyPRO.

Parametry

transfers max 500
transaction_id
amount
booking_date
payer_account

Odpowiedź

summary.imported
summary.duplicates
results[]

Przykład curl

curl -X POST "https://faktury.pro/api/bank/import.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "transfers": [
        {
            "transaction_id": "bank-1001",
            "amount": "123.00",
            "booking_date": "2026-06-14",
            "title": "FV 1/06/2026"
        }
    ]
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/bank/import.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "summary.imported",
        "summary.duplicates",
        "results[]"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'transfers' => 
  array (
    0 => 
    array (
      'transaction_id' => 'bank-1001',
      'amount' => '123.00',
      'booking_date' => '2026-06-14',
      'title' => 'FV 1/06/2026',
    ),
  ),
);

$ch = curl_init($baseUrl . '/api/bank/import.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "transfers": [
        {
            "transaction_id": "bank-1001",
            "amount": "123.00",
            "booking_date": "2026-06-14",
            "title": "FV 1/06/2026"
        }
    ]
};

const res = await fetch(baseUrl + '/api/bank/import.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'transfers' => 
  array (
    0 => 
    array (
      'transaction_id' => 'bank-1001',
      'amount' => '123.00',
      'booking_date' => '2026-06-14',
      'title' => 'FV 1/06/2026',
    ),
  ),
)

response = requests.post(
    f'{base_url}/api/bank/import.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/bank/import.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "transfers": [
        {
            "transaction_id": "bank-1001",
            "amount": "123.00",
            "booking_date": "2026-06-14",
            "title": "FV 1/06/2026"
        }
    ]
}

POST /api/bank/match.php

Dopasowanie przelewu

Operator albo automat potwierdza, że przelew dotyczy konkretnej faktury.

Parametry

transfer_id
invoice_id / external_id
action

Odpowiedź

transfer
invoice
payment

Przykład curl

curl -X POST "https://faktury.pro/api/bank/match.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "transfer_id": 1,
    "invoice_id": 1,
    "action": "confirm"
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/bank/match.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "transfer",
        "invoice",
        "payment"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'transfer_id' => 1,
  'invoice_id' => 1,
  'action' => 'confirm',
);

$ch = curl_init($baseUrl . '/api/bank/match.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "transfer_id": 1,
    "invoice_id": 1,
    "action": "confirm"
};

const res = await fetch(baseUrl + '/api/bank/match.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'transfer_id' => 1,
  'invoice_id' => 1,
  'action' => 'confirm',
)

response = requests.post(
    f'{base_url}/api/bank/match.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/bank/match.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "transfer_id": 1,
    "invoice_id": 1,
    "action": "confirm"
}

POST /api/bank/bulk.php

Bulk bank actions

Masowe potwierdzenie, cofnięcie albo pominięcie dopasowań bankowych.

Parametry

action: match, confirm, unmatch, undo, skip
items[]

Odpowiedź

HTTP 200 albo 207
summary
results[]

Przykład curl

curl -X POST "https://faktury.pro/api/bank/bulk.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "action": "confirm",
    "items": [
        {
            "transfer_id": 1,
            "invoice_id": 1
        }
    ]
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/bank/bulk.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "HTTP 200 albo 207",
        "summary",
        "results[]"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'action' => 'confirm',
  'items' => 
  array (
    0 => 
    array (
      'transfer_id' => 1,
      'invoice_id' => 1,
    ),
  ),
);

$ch = curl_init($baseUrl . '/api/bank/bulk.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "action": "confirm",
    "items": [
        {
            "transfer_id": 1,
            "invoice_id": 1
        }
    ]
};

const res = await fetch(baseUrl + '/api/bank/bulk.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'action' => 'confirm',
  'items' => 
  array (
    0 => 
    array (
      'transfer_id' => 1,
      'invoice_id' => 1,
    ),
  ),
)

response = requests.post(
    f'{base_url}/api/bank/bulk.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/bank/bulk.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "action": "confirm",
    "items": [
        {
            "transfer_id": 1,
            "invoice_id": 1
        }
    ]
}

Automatyzacje, webhooki i asystent

Integracje dwukierunkowe, ustawienia webhooków, asystenci AI i faktury cykliczne.

GET/POST /api/webhooks/settings.php

Ustawienia webhooka wychodzącego

Panel integratora włącza URL webhooka i odczytuje obsługiwane zdarzenia.

Parametry

GET: odczyt konfiguracji
POST: url / webhook_url
enabled / webhook_enabled
clear_url

Odpowiedź

webhook.enabled
webhook.url
events
signature

Przykład curl

curl -X POST "https://faktury.pro/api/webhooks/settings.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "enabled": true,
    "url": "https://example.com/fakturypro/webhook"
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/webhooks/settings.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "webhook.enabled",
        "webhook.url",
        "events",
        "signature"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'enabled' => true,
  'url' => 'https://example.com/fakturypro/webhook',
);

$ch = curl_init($baseUrl . '/api/webhooks/settings.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "enabled": true,
    "url": "https://example.com/fakturypro/webhook"
};

const res = await fetch(baseUrl + '/api/webhooks/settings.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'enabled' => true,
  'url' => 'https://example.com/fakturypro/webhook',
)

response = requests.post(
    f'{base_url}/api/webhooks/settings.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/webhooks/settings.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "enabled": true,
    "url": "https://example.com/fakturypro/webhook"
}

POST /api/webhooks/test.php

Test webhooka

Sprawdzenie odbiornika przed produkcyjnym włączeniem synchronizacji.

Parametry

event opcjonalnie
external_id opcjonalnie

Odpowiedź

sent
status_code
event=webhook.test

Przykład curl

curl -X POST "https://faktury.pro/api/webhooks/test.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "event": "webhook.test",
    "external_id": "test-1001"
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/webhooks/test.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "sent",
        "status_code",
        "event=webhook.test"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'event' => 'webhook.test',
  'external_id' => 'test-1001',
);

$ch = curl_init($baseUrl . '/api/webhooks/test.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "event": "webhook.test",
    "external_id": "test-1001"
};

const res = await fetch(baseUrl + '/api/webhooks/test.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'event' => 'webhook.test',
  'external_id' => 'test-1001',
)

response = requests.post(
    f'{base_url}/api/webhooks/test.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/webhooks/test.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "event": "webhook.test",
    "external_id": "test-1001"
}

GET /api/assistant/summary.php

Podsumowanie dla asystenta

AI agent albo dashboard zewnętrzny potrzebuje kontekstu zaległości, dokumentów i sugestii.

Parametry

id_konta
date_from / date_to opcjonalnie

Odpowiedź

summary
suggestions
invoices
costs

Przykład curl

curl -H "Authorization: Bearer {{api_token}}" \
  "https://faktury.pro/api/assistant/summary.php?id_konta={{account_id}}"

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/assistant/summary.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "summary",
        "suggestions",
        "invoices",
        "costs"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$accountId = getenv('FAKTURYPRO_ACCOUNT_ID');
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$ch = curl_init($baseUrl . '/api/assistant/summary.php?id_konta=' . urlencode($accountId));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiToken],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const accountId = process.env.FAKTURYPRO_ACCOUNT_ID;
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const url = baseUrl + '/api/assistant/summary.php?id_konta=' + encodeURIComponent(accountId);
const res = await fetch(url, {
  headers: { Authorization: 'Bearer ' + apiToken }
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
account_id = os.environ['FAKTURYPRO_ACCOUNT_ID']
api_token = os.environ['FAKTURYPRO_API_TOKEN']

response = requests.get(
    f'{base_url}/api/assistant/summary.php',
    params={'id_konta': account_id},
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/assistant/summary.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}"
}

POST /api/assistant/action.php

Akcja asystenta

Zewnętrzny asystent wykonuje kontrolowaną akcję po decyzji operatora.

Parametry

action: snooze, hide, done
fingerprint
type

Odpowiedź

ok
suggestion

Przykład curl

curl -X POST "https://faktury.pro/api/assistant/action.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "action": "snooze",
    "type": "overdue_invoice",
    "fingerprint": "sha256..."
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/assistant/action.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "ok",
        "suggestion"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'action' => 'snooze',
  'type' => 'overdue_invoice',
  'fingerprint' => 'sha256...',
);

$ch = curl_init($baseUrl . '/api/assistant/action.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "action": "snooze",
    "type": "overdue_invoice",
    "fingerprint": "sha256..."
};

const res = await fetch(baseUrl + '/api/assistant/action.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'action' => 'snooze',
  'type' => 'overdue_invoice',
  'fingerprint' => 'sha256...',
)

response = requests.post(
    f'{base_url}/api/assistant/action.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/assistant/action.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "action": "snooze",
    "type": "overdue_invoice",
    "fingerprint": "sha256..."
}

GET /api/recurring/list.php

Lista szablonów cyklicznych

Panel abonamentów albo CRM pokazuje cykliczne faktury klienta.

Parametry

status
cycle
client_id
due
auto
q
include_items

Odpowiedź

templates
recurring_templates
meta
filters

Przykład curl

curl -H "Authorization: Bearer {{api_token}}" \
  "https://faktury.pro/api/recurring/list.php?id_konta={{account_id}}"

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/recurring/list.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "templates",
        "recurring_templates",
        "meta",
        "filters"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$accountId = getenv('FAKTURYPRO_ACCOUNT_ID');
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$ch = curl_init($baseUrl . '/api/recurring/list.php?id_konta=' . urlencode($accountId));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiToken],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const accountId = process.env.FAKTURYPRO_ACCOUNT_ID;
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const url = baseUrl + '/api/recurring/list.php?id_konta=' + encodeURIComponent(accountId);
const res = await fetch(url, {
  headers: { Authorization: 'Bearer ' + apiToken }
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
account_id = os.environ['FAKTURYPRO_ACCOUNT_ID']
api_token = os.environ['FAKTURYPRO_API_TOKEN']

response = requests.get(
    f'{base_url}/api/recurring/list.php',
    params={'id_konta': account_id},
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/recurring/list.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}"
}

POST /api/recurring/detail.php

Szczegóły szablonu cyklicznego

Odczyt pozycji, sum i ostatnich faktur z danego szablonu.

Parametry

id / template_id / recurring_id
history_limit

Odpowiedź

template
template.items
template.totals
template.recent_invoices

Przykład curl

curl -X POST "https://faktury.pro/api/recurring/detail.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "template_id": 1
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/recurring/detail.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "template",
        "template.items",
        "template.totals",
        "template.recent_invoices"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'template_id' => 1,
);

$ch = curl_init($baseUrl . '/api/recurring/detail.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "template_id": 1
};

const res = await fetch(baseUrl + '/api/recurring/detail.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'template_id' => 1,
)

response = requests.post(
    f'{base_url}/api/recurring/detail.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/recurring/detail.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "template_id": 1
}

POST /api/recurring/upsert.php

Dodanie lub aktualizacja szablonu cyklicznego

CRM tworzy abonament, który ma być fakturowany okresowo.

Parametry

template.client_id albo template.client
cycle
next_issue_date
end_date
items[]

Odpowiedź

created
client_created
template
links

Przykład curl

curl -X POST "https://faktury.pro/api/recurring/upsert.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "template": {
        "client": {
            "name": "Klient abonamentowy"
        },
        "cycle": "miesieczny",
        "next_issue_date": "2026-07-01",
        "items": [
            {
                "name": "Abonament",
                "qty": "1",
                "net_unit_price": "99.00",
                "vat_rate": "23"
            }
        ]
    }
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/recurring/upsert.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "created",
        "client_created",
        "template",
        "links"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'template' => 
  array (
    'client' => 
    array (
      'name' => 'Klient abonamentowy',
    ),
    'cycle' => 'miesieczny',
    'next_issue_date' => '2026-07-01',
    'items' => 
    array (
      0 => 
      array (
        'name' => 'Abonament',
        'qty' => '1',
        'net_unit_price' => '99.00',
        'vat_rate' => '23',
      ),
    ),
  ),
);

$ch = curl_init($baseUrl . '/api/recurring/upsert.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "template": {
        "client": {
            "name": "Klient abonamentowy"
        },
        "cycle": "miesieczny",
        "next_issue_date": "2026-07-01",
        "items": [
            {
                "name": "Abonament",
                "qty": "1",
                "net_unit_price": "99.00",
                "vat_rate": "23"
            }
        ]
    }
};

const res = await fetch(baseUrl + '/api/recurring/upsert.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'template' => 
  array (
    'client' => 
    array (
      'name' => 'Klient abonamentowy',
    ),
    'cycle' => 'miesieczny',
    'next_issue_date' => '2026-07-01',
    'items' => 
    array (
      0 => 
      array (
        'name' => 'Abonament',
        'qty' => '1',
        'net_unit_price' => '99.00',
        'vat_rate' => '23',
      ),
    ),
  ),
)

response = requests.post(
    f'{base_url}/api/recurring/upsert.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/recurring/upsert.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "template": {
        "client": {
            "name": "Klient abonamentowy"
        },
        "cycle": "miesieczny",
        "next_issue_date": "2026-07-01",
        "items": [
            {
                "name": "Abonament",
                "qty": "1",
                "net_unit_price": "99.00",
                "vat_rate": "23"
            }
        ]
    }
}

POST /api/recurring/issue.php

Wystawienie faktury cyklicznej

Zewnętrzny harmonogram uruchamia wystawienie z gotowego szablonu.

Parametry

id / template_id / recurring_id
force=true tylko świadomie

Odpowiedź

template
invoice
links
can_force przy duplikacie

Przykład curl

curl -X POST "https://faktury.pro/api/recurring/issue.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "template_id": 1
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/recurring/issue.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "template",
        "invoice",
        "links",
        "can_force przy duplikacie"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'template_id' => 1,
);

$ch = curl_init($baseUrl . '/api/recurring/issue.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "template_id": 1
};

const res = await fetch(baseUrl + '/api/recurring/issue.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'template_id' => 1,
)

response = requests.post(
    f'{base_url}/api/recurring/issue.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/recurring/issue.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "template_id": 1
}

POST /api/recurring/status.php

Zmiana statusu szablonu cyklicznego

Pauza, wznowienie, włączenie auto albo zmiana dat bez pełnego upsertu.

Parametry

action
next_issue_date
end_date

Odpowiedź

template

Przykład curl

curl -X POST "https://faktury.pro/api/recurring/status.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "template_id": 1,
    "action": "pause"
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "endpoint": "/api/recurring/status.php",
    "result": "Przykładowa odpowiedź. Szczegółowe pola zależą od endpointu.",
    "returns": [
        "template"
    ]
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'template_id' => 1,
  'action' => 'pause',
);

$ch = curl_init($baseUrl . '/api/recurring/status.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "template_id": 1,
    "action": "pause"
};

const res = await fetch(baseUrl + '/api/recurring/status.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'template_id' => 1,
  'action' => 'pause',
)

response = requests.post(
    f'{base_url}/api/recurring/status.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/recurring/status.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "template_id": 1,
    "action": "pause"
}

Webhook płatności

Neutralny endpoint dla zewnętrznych operatorów płatności i checkoutów.

POST /api/platnosci/webhook.php

Potwierdzenie płatności online

Operator płatności potwierdza wpłatę i faktura ma zostać oznaczona jako opłacona.

Parametry

token API albo sekret płatności
X-FakturyPro-Signature opcjonalnie
id / invoice_id albo numer
status
amount
transaction_id
provider

Odpowiedź

invoice
payment
duplicate

Przykład curl

curl -X POST "https://faktury.pro/api/platnosci/webhook.php" \
  -H "Authorization: Bearer {{api_token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "status": "paid",
    "amount": "123.00",
    "transaction_id": "provider-1001",
    "provider": "external-checkout"
}'

Przykładowe odpowiedzi JSON

Sukces

{
    "ok": true,
    "invoice": {
        "id": 123,
        "payment_status": "paid"
    },
    "payment": {
        "amount": "123.00",
        "provider": "external-checkout"
    },
    "duplicate": false
}

Błąd

{
    "ok": false,
    "error": "invalid_token",
    "message": "Token API jest nieprawidłowy albo konto nie ma aktywnego API."
}

Przykłady w popularnych językach i dla AI

PHP

<?php
$baseUrl = 'https://faktury.pro';
$apiToken = getenv('FAKTURYPRO_API_TOKEN');

$payload = array (
  'id_konta' => '{{account_id}}',
  'invoice_id' => 1,
  'status' => 'paid',
  'amount' => '123.00',
  'transaction_id' => 'provider-1001',
  'provider' => 'external-checkout',
);

$ch = curl_init($baseUrl . '/api/platnosci/webhook.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$raw = curl_exec($ch);
if ($raw === false) throw new RuntimeException(curl_error($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status >= 400) throw new RuntimeException('fakturyPRO API HTTP ' . $status . ': ' . $raw);

print_r(json_decode($raw, true));

JavaScript / Node.js

const baseUrl = 'https://faktury.pro';
const apiToken = process.env.FAKTURYPRO_API_TOKEN;

const payload = {
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "status": "paid",
    "amount": "123.00",
    "transaction_id": "provider-1001",
    "provider": "external-checkout"
};

const res = await fetch(baseUrl + '/api/platnosci/webhook.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + apiToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

if (!res.ok) throw new Error('fakturyPRO API HTTP ' + res.status);
const data = await res.json();
console.log(data);

Python

import os
import requests

base_url = 'https://faktury.pro'
api_token = os.environ['FAKTURYPRO_API_TOKEN']

payload = array (
  'id_konta' => '{{account_id}}',
  'invoice_id' => 1,
  'status' => 'paid',
  'amount' => '123.00',
  'transaction_id' => 'provider-1001',
  'provider' => 'external-checkout',
)

response = requests.post(
    f'{base_url}/api/platnosci/webhook.php',
    json=payload,
    headers={'Authorization': f'Bearer {api_token}'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

C# / .NET

using System.Net.Http.Headers;
using System.Text;

var baseUrl = "https://faktury.pro";
var apiToken = Environment.GetEnvironmentVariable("FAKTURYPRO_API_TOKEN");

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiToken);

var payload = @"{
    ""id_konta"": ""{{account_id}}"",
    ""invoice_id"": 1,
    ""status"": ""paid"",
    ""amount"": ""123.00"",
    ""transaction_id"": ""provider-1001"",
    ""provider"": ""external-checkout""
}";
var body = new StringContent(payload, Encoding.UTF8, "application/json");
var res = await http.PostAsync(baseUrl + "/api/platnosci/webhook.php", body);
var json = await res.Content.ReadAsStringAsync();
if (!res.IsSuccessStatusCode) throw new Exception("fakturyPRO API HTTP " + (int)res.StatusCode + ": " + json);
Console.WriteLine(json);

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String baseUrl = "https://faktury.pro";
String apiToken = System.getenv("FAKTURYPRO_API_TOKEN");
String payload = """
{
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "status": "paid",
    "amount": "123.00",
    "transaction_id": "provider-1001",
    "provider": "external-checkout"
}
""";

HttpRequest request = HttpRequest.newBuilder(URI.create(baseUrl + "/api/platnosci/webhook.php"))
    .header("Authorization", "Bearer " + apiToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) throw new RuntimeException(response.body());
System.out.println(response.body());

Go

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  baseURL := "https://faktury.pro"
  apiToken := os.Getenv("FAKTURYPRO_API_TOKEN")
  payload := []byte(`{
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "status": "paid",
    "amount": "123.00",
    "transaction_id": "provider-1001",
    "provider": "external-checkout"
}`)

  req, _ := http.NewRequest("POST", baseURL+"/api/platnosci/webhook.php", bytes.NewReader(payload))
  req.Header.Set("Authorization", "Bearer "+apiToken)
  req.Header.Set("Content-Type", "application/json")

  res, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)
  if res.StatusCode >= 400 { panic(string(body)) }
  fmt.Println(string(body))
}

Prompt dla Codex / Claude

Zaimplementuj integrację z fakturyPRO dla endpointu /api/platnosci/webhook.php.
Użyj tokenu z env FAKTURYPRO_API_TOKEN i account_id z env FAKTURYPRO_ACCOUNT_ID.
Nie zapisuj tokenu w logach ani w URL. Obsłuż JSON: ok=false, error, message.
Dodaj retry tylko dla timeoutów/5xx, a dla faktur używaj external_id/idempotency_key.
Przykładowy payload:
{
    "id_konta": "{{account_id}}",
    "invoice_id": 1,
    "status": "paid",
    "amount": "123.00",
    "transaction_id": "provider-1001",
    "provider": "external-checkout"
}

Dla botów AI i wdrożeń AEO

Ta dokumentacja celowo używa stabilnych nazw endpointów, aliasów pól po polsku i angielsku, przykładów curl oraz maszynowych kodów błędów. Dzięki temu Codex, Claude i inne agenty mogą szybciej dobrać właściwy endpoint do projektu klienta.

Dla agentów: zacznij od /api/health.php, pobierz /api/meta.php, twórz faktury przez /api/faktury/create.php z external_id, a KSeF prowadź przez ready → xml → send → status. Token trzymaj wyłącznie w nagłówku Authorization: Bearer.

Nie zapisuj tokenu API ani tokenu KSeF w logach, URL-ach, promptach ani publicznych webhookach.
Retry wykonuj tylko dla timeoutów i HTTP 5xx; dla faktur używaj external_id albo idempotency_key.
Gdy odpowiedź ma ok=false, pokaż użytkownikowi message i zachowaj maszynowy kod error do diagnostyki.

Maszynowe punkty wejścia: llms.txt, llms-full.txt, OpenAPI, Postman, manifest API.

FAQ

Gdzie wygenerować token API?

Token API generuje właściciel konta w panelu fakturyPRO, w ustawieniach konta. W dokumentacji i logach zapisuj tylko placeholder, np. {{api_token}}.

Czy token można wysłać w adresie URL?

Nie. Zalecany jest nagłówek Authorization: Bearer. Alternatywnie można użyć X-FakturyPro-Token albo pola token w body POST.

Jak uniknąć duplikatów faktur?

Wysyłaj stabilne external_id, order_id albo idempotency_key. Ponowienie requestu z tym samym identyfikatorem zwraca istniejącą fakturę zamiast tworzyć drugą.

Czy przez API wystawię fakturę poprawną do KSeF?

Tak: utwórz fakturę przez create.php, sprawdź ready.php, opcjonalnie wygeneruj xml.php, wyślij send.php i pobierz numer przez status.php. Ready-check pokazuje braki przed wysyłką.

Jaka jest różnica między XML preview i send?

xml.php generuje i zapisuje XML FA(3) bez wysyłki do KSeF. send.php wykonuje wysyłkę i zapisuje numery referencyjne, a status.php odświeża numer KSeF.

Kiedy robić retry?

Retry stosuj tylko dla timeoutów i błędów 5xx. Dla tworzenia faktur zawsze przekazuj external_id lub idempotency_key, żeby ponowienie nie utworzyło duplikatu.

Co importować do Postmana?

Użyj /api/postman.php jako kolekcji Postman oraz /api/openapi.php jako specyfikacji OpenAPI 3.0 dla Swaggera, Insomnii i generatorów klientów.