10.4. Webhook

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://bump.sh/pgw/doc/axepta-api/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
"axepta API MCP server": {
  "url": "https://bump.sh/pgw/doc/axepta-api/mcp"
}
Close

Jeśli podasz callbackUrl w destination, system wyśle webhook po wygenerowaniu raportu.

Webhook Request

Method: POST URL: Twój callbackUrl Headers:

Content-Type: application/json

Body (identyczny jak response GET):

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "plannedReportUuid": "650e8400-e29b-41d4-a716-446655440001",
  "taskName": "report_csv",
  "type": "transaction",
  "status": "generated",
  "settings": {
    "columns": ["transactionInternalId", "transactionAmount"],
    "conditions": {
      "date": {
        "from": 1609459200,
        "to": 1612137599
      },
      "filters": {
        "transactionStatus": ["settled"]
      }
    },
    "destination": {
      "email": ["report@example.com"]
    }
  },
  "generatedAt": 1612137600
}

Uwaga: Pole plannedReportUuid będzie obecne tylko jeśli raport został wygenerowany z zaplanowanego raportu. Dla raportów jednorazowych (utworzonych przez POST /report) pole to będzie null lub nieobecne.

Obsługa webhooka

  1. Webhook jest wysyłany gdy: status osiągnie stan końcowy (generated, error, deleted, cancelled)
  2. Wymagana odpowiedź: Serwer MUSI odpowiedzieć kodem HTTP 200 z body: json { "status": "ok" }
  3. Retry: Jeśli webhook zwróci błąd (kod inny niż 200) lub timeout, system będzie automatycznie ponawiał wysyłkę

Przykład poprawnej obsługi webhooka (Node.js/Express):

app.post('/webhook/report', (req, res) => {
  const report = req.body;

  console.log(`Raport ${report.uuid} ma status: ${report.status}`);

  if (report.status === 'generated') {
    // Raport gotowy - pobierz plik lub wyślij powiadomienie
    console.log(`Raport wygenerowany: ${report.generatedAt}`);
  } else if (report.status === 'error') {
    // Błąd generowania
    console.error(`Błąd generowania raportu ${report.uuid}`);
  }

  // WAŻNE: MUSISZ odpowiedzieć 200 z { status: "ok" }
  res.status(200).json({ status: 'ok' });
});

Przykłady użycia

Prosty raport transakcji

curl -X POST "https://api.example.com/v1/merchant/MERCHANT123/report" \
  -H "Authorization: Basic dXNlcjpwYXNz" \
  -H "Content-Type: application/json" \
  -d '{
    "taskName": "report_csv",
    "type": "transaction",
    "columns": ["transactionInternalId", "transactionAmount", "transactionStatus"],
    "conditions": {
      "date": {
        "from": 1609459200,
        "to": 1612137599,
        "timezone": "Europe/Warsaw"
      }
    }
  }'

Raport z filtrowaniem i webhookiem

curl -X POST "https://api.example.com/v1/merchant/MERCHANT123/report" \
  -H "Authorization: Basic dXNlcjpwYXNz" \
  -H "Content-Type: application/json" \
  -d '{
    "taskName": "report_csv",
    "type": "transaction",
    "columns": ["transactionInternalId", "transactionAmount", "transactionStatus"],
    "conditions": {
      "date": {
        "from": 1609459200,
        "to": 1612137599,
        "timezone": "Europe/Warsaw"
      },
      "language": "PL",
      "filters": {
        "paymentMethodCode": ["card", "blik"],
        "transactionStatus": ["settled"]
      }
    },
    "formatting": {
      "columnSeparator": ";",
      "numberSeparator": ","
    },
    "destination": {
      "email": ["report@example.com"],
      "callbackUrl": "https://your-domain.com/webhook/report"
    }
  }'

Pobranie raportu

curl -X GET "https://api.example.com/v1/merchant/MERCHANT123/report/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Basic <key>"

Pobranie pliku raportu

curl -X GET "https://api.example.com/v1/merchant/MERCHANT123/report/550e8400-e29b-41d4-a716-446655440000/download" \
  -H "Authorization: Basic <key>" \
  -o raport.csv

Tworzenie zaplanowanego raportu

curl -X POST "https://api.example.com/v1/merchant/MERCHANT123/planned-report" \
  -H "Authorization: Basic <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "taskName": "report_csv",
    "type": "transaction",
    "columns": ["transactionInternalId", "transactionAmount", "transactionStatus"],
    "conditions": {
      "date": {
        "timezone": "Europe/Warsaw"
      },
      "language": "PL"
    },
    "formatting": {
      "columnSeparator": ";",
      "numberSeparator": ","
    },
    "destination": {
      "email": ["report@example.com"]
    },
    "frequency": "day",
    "activeFrom": 1609459200,
    "isActive": true,
    "name": "Dzienny raport transakcji"
  }'

Aktualizacja zaplanowanego raportu

curl -X PUT "https://api.example.com/v1/merchant/MERCHANT123/planned-report/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Basic <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false,
    "frequency": "week"
  }'