Skip to content

README.md

Latest commit

 

History

History
251 lines (196 loc) · 14 KB

README.md

File metadata and controls

251 lines (196 loc) · 14 KB
Raw

eConnect PSB PHP SDK

PHP SDK for the eConnect Procurement Service Bus (PSB) API (https://psb.econnect.eu/?urls.primaryName=V1)

Installation & Usage

Requirements

  • PHP 8.2 or later
  • A PSR-18 HTTP client with an HTTPlug async implementation, such as Symfony HttpClient or Guzzle
  • Compatible with Symfony 6.4, 7.x and 8.x (Symfony 8 itself requires PHP 8.4 or later)

Composer

To install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/QbilSoftware/econnect-psb-php.git"
    }
  ],
  "require": {
    "qbil-software/econnect-psb-php": "dev-main"
  }
}

Then run composer install.

Your project is free to choose the HTTP client of your choice. In a Symfony application, use Symfony HttpClient:

composer require symfony/http-client guzzlehttp/promises

Or use Guzzle 7 with its HTTPlug adapter:

composer require guzzlehttp/guzzle php-http/guzzle7-adapter

Manual Installation

Download the files and include autoload.php:

<?php
require_once('/path/to/econnect-psb-php/vendor/autoload.php');

Getting Started

Please follow the installation procedure and then run the following:

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = (new EConnect\Psb\Configuration())
    ->setHost('https://psb.econnect.eu')
    ->setUsername('{username}')
    ->setPassword('{password}')
    ->setApiKey('Subscription-Key', '{subscription key}');

$authenticator = new EConnect\Psb\OidcAuthenticator(
    Http\Discovery\Psr18ClientDiscovery::find(),
    Http\Discovery\Psr17FactoryDiscovery::findRequestFactory(),
    Http\Discovery\Psr17FactoryDiscovery::findStreamFactory(),
    new Symfony\Component\Clock\NativeClock(),
    $config,
);

// Fetches an access token and stores it in $config. The token is cached and renewed
// shortly before it expires, so it is cheap to call this before every batch of API calls.
$authenticator->authenticate('{clientId}', '{clientSecret}');

// The HTTP client is optional: when omitted, it is discovered with `Psr18ClientDiscovery`.
$apiInstance = new EConnect\Psb\Api\HookApi(null, $config);

try {
    $result = $apiInstance->getHookConfigs();
    print_r($result);
} catch (EConnect\Psb\ApiException $e) {
    echo 'Exception when calling HookApi->getHookConfigs: ', $e->getMessage(), PHP_EOL;
}

Symfony

With symfony/framework-bundle and symfony/http-client installed, register the SDK as services, for example in config/services.yaml:

services:
    EConnect\Psb\Configuration:
        calls:
            - setHost: ['%env(PSB_HOST)%']
            - setUsername: ['%env(PSB_USERNAME)%']
            - setPassword: ['%env(PSB_PASSWORD)%']
            - setApiKey: ['Subscription-Key', '%env(PSB_SUBSCRIPTION_KEY)%']

    EConnect\Psb\OidcAuthenticator:
        arguments:
            $httpClient: '@psr18.http_client'
            $requestFactory: '@psr18.http_client'
            $streamFactory: '@psr18.http_client'
            $clock: '@clock'
            $config: '@EConnect\Psb\Configuration'

    EConnect\Psb\Api\:
        resource: '%kernel.project_dir%/vendor/qbil-software/econnect-psb-php/lib/Api/'
        autowire: true

The API classes then use Symfony HttpClient for both synchronous and asynchronous requests. Inject OidcAuthenticator and the API classes you need into your own services, and call authenticate() before using the APIs.

API Endpoints

All URIs are relative to the configured host, e.g. https://psb.econnect.eu

Class Method HTTP request Description
HookApi getHookConfigs GET /api/v1/hook Get registered environment hooks.
HookApi getHooks GET /api/v1/{partyId}/hook Get registered hooks.
HookApi removeHookConfig DELETE /api/v1/hook/{hookId} Delete default hook.
HookApi sendHookPing GET /api/v1/{partyId}/hook/ping Send ping to hook(s).
HookApi setHookConfig PUT /api/v1/hook Add or update environment hook.
HookApi subscribe PUT /api/v1/{partyId}/hook Add or update hook.
HookApi unSubscribe DELETE /api/v1/{partyId}/hook/{hookId} Delete hook.
MeApi getUser GET /api/v1/me Get user.
MeApi getUserParty GET /api/v1/me/party Get parties.
PeppolApi getDeliveryOptions GET /api/v1/peppol/deliveryOption Advanced recipient party lookup in Peppol.
PeppolApi getPeppolConfig GET /api/v1/peppol/config Get default Peppol configuration
PeppolApi getPeppolParties GET /api/v1/peppol/config/party Get your Peppol participants
PeppolApi getPeppolPartyConfig GET /api/v1/peppol/config/party/{partyId} Get participant Peppol configuration
PeppolApi removePeppolPartyConfig DELETE /api/v1/peppol/config/party/{partyId} Un register (Remove) participant in Peppol
PeppolApi requestPartyPrepareToMigrate GET /api/v1/peppol/{partyId}/prepareToMigrate Generates a migration key and registers it with the SML to enable participant transfer between SMPs
PeppolApi setPeppolConfig PUT /api/v1/peppol/config Add or update default Peppol configuration
PeppolApi setPeppolPartyConfig PUT /api/v1/peppol/config/party/{partyId} Register or update participant in Peppol
PurchaseInvoiceApi deletePurchaseInvoice DELETE /api/v1/{partyId}/purchaseInvoice/{documentId} Delete purchase invoice.
PurchaseInvoiceApi downloadPurchaseInvoice GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download Download purchase invoice.
PurchaseInvoiceApi getPurchaseInvoiceStatuses GET /api/v1/{partyId}/purchaseInvoice/{documentId}/status Get purchase invoice statuses (FOR DEBUGGING ONLY).
PurchaseInvoiceApi queryRecipientPartyForInvoiceResponse POST /api/v1/{partyId}/purchaseInvoice/queryRecipientParty Lookup the recipient party (seller/supplier) for possible delivery.
PurchaseInvoiceApi recognizePurchaseInvoice POST /api/v1/{partyId}/purchaseInvoice/recognize Recognize purchase invoice.
PurchaseInvoiceApi sendInvoiceResponse POST /api/v1/{partyId}/purchaseInvoice/{documentId}/response Send invoice response to let the seller know the status of the received invoice.
PurchaseOrderApi apiV1PartyIdPurchaseOrderDocumentIdStatusGet GET /api/v1/{partyId}/purchaseOrder/{documentId}/status Get purchase order statuses (FOR DEBUGGING ONLY).
PurchaseOrderApi apiV1PartyIdPurchaseOrderQueryRecipientPartyPost POST /api/v1/{partyId}/purchaseOrder/queryRecipientParty Lookup the recipient party (seller) for possible delivery.
PurchaseOrderApi sendOrderCancellation POST /api/v1/{partyId}/purchaseOrder/{documentId}/cancel Send order cancellation to let the seller know the order is cancelled.
PurchaseOrderApi sendPurchaseOrder POST /api/v1/{partyId}/purchaseOrder/send Send a purchase order.
SalesInvoiceApi getSalesInvoiceStatuses GET /api/v1/{partyId}/salesInvoice/{documentId}/status Get sales invoice statuses (FOR DEBUGGING ONLY).
SalesInvoiceApi queryRecipientPartyForSalesInvoice POST /api/v1/{partyId}/salesInvoice/queryRecipientParty Lookup the recipient party (buyer/customer) for possible delivery.
SalesInvoiceApi recognizeSalesInvoice POST /api/v1/{partyId}/salesInvoice/recognize Recognize sales invoice.
SalesInvoiceApi sendSalesInvoice POST /api/v1/{partyId}/salesInvoice/send Send an invoice.
SalesOrderApi deleteSalesOrder DELETE /api/v1/{partyId}/salesOrder/{documentId} Delete sales order.
SalesOrderApi downloadSalesOrder GET /api/v1/{partyId}/salesOrder/{documentId}/download Download sales order.
SalesOrderApi getSalesOrderStatuses GET /api/v1/{partyId}/salesOrder/{documentId}/status Get sales order statuses (FOR DEBUGGING ONLY).
SalesOrderApi queryRecipientPartyForOrderResponse POST /api/v1/{partyId}/salesOrder/queryRecipientParty Lookup the recipient party (buyer/customer) for possible delivery.
SalesOrderApi sendOrderResponse POST /api/v1/{partyId}/salesOrder/{documentId}/response Send order response to let the buyer know the status of the received order.
UserApi addOrUpdateUser PUT /api/v1/user Add or update users.
UserApi addOrUpdateUserParty PUT /api/v1/user/{name}/party Add or update user's party.
UserApi deleteUser DELETE /api/v1/user/{name} Delete user.
UserApi deleteUserParty DELETE /api/v1/user/{name}/party/{partyId} Removes user's party.
UserApi getUserParties GET /api/v1/user/{name}/party Get user's parties.
UserApi getUsers GET /api/v1/user List users.

Models

Authorization

Bearer

  • Type: OAuth
  • Flow: implicit
  • Authorization URL: https://identity.econnect.eu/connect/authorize
  • Scopes:
    • ap: Procurement Service Bus API
    • vpd: Validated Party Service API

Subscription-Key

  • Type: API key
  • API key parameter name: Subscription-Key
  • Location: HTTP header

Tests

To run the tests, use:

composer install
composer test

The unit test suite in test/Unit covers authentication, (de)serialization and request building, including a run on top of Symfony HttpClient. The generated suite in test/Api and test/Model contains the placeholders created by OpenAPI Generator.

Regenerating the SDK

Hand-maintained files are listed in .openapi-generator-ignore and are kept when regenerating. The generated code also carries the following patches, which have to be re-applied after regenerating:

  • lib/Api/*.php: createRequest() always builds the request through the PSR-17 factories, and multipart requests set Content-Type: multipart/form-data; boundary=... from the MultipartStream.
  • lib/ObjectSerializer.php: dates are detected with \DateTimeInterface, so \DateTimeImmutable values are serialized as well.
  • lib/DebugPlugin.php: failed requests are logged as <METHOD path HTTP/version> code message.

lib/functions.php provides GuzzleHttp\Psr7\try_fopen(), which the generated file uploads call but guzzlehttp/psr7 2.0 and later no longer ship.

Author

techsupport@econnect.eu

About this package

This PHP package is automatically generated by the OpenAPI Generator project:

  • API version: 1.0
    • Generator version: 7.12.0
  • Build package: org.openapitools.codegen.languages.PhpClientCodegen