adaptech/finapi-access

<strong>账户信息服务(AIS)和支付启动服务(PIS)的RESTful API</strong> 以下页面为您提供有关如何使用我们API的一些基本信息。实际的API服务文档随后进一步说明。您可以使用菜单在API部分之间跳转。

1.143.1 2022-01-11 13:48 UTC

This package is auto-updated.

Last update: 2024-09-11 19:41:08 UTC


README

账户信息服务(AIS)和支付启动服务(PIS)的RESTful API

以下页面为您提供有关如何使用我们API的一些基本信息。
实际的API服务文档随后进一步说明。您可以使用菜单在API部分之间跳转。

此页面内置了HTTP(S)客户端,因此您可以直接在此页面测试服务,通过在相应的服务中填写请求参数和/或正文,然后点击TRY按钮。请注意,您需要授权才能成功进行API调用。要授权,请参阅API的“授权”部分,或直接使用TRY按钮附近的OAUTH按钮。

一般信息

错误响应

当API调用返回错误时,通常具有以下示例中的结构
{
  \"errors\": [
    {
      \"message\": \"Interface 'FINTS_SERVER' is not supported for this operation.\",
      \"code\": \"BAD_REQUEST\",
      \"type\": \"TECHNICAL\"
    }
  ],
  \"date\": \"2020-11-19 16:54:06.854\",
  \"requestId\": \"selfgen-312042e7-df55-47e4-bffd-956a68ef37b5\",
  \"endpoint\": \"POST /api/v1/bankConnections/import\",
  \"authContext\": \"1/21\",
  \"bank\": \"DEMO0002 - finAPI Test Redirect Bank\"
}

如果API调用需要用户进行额外的身份验证,则返回HTTP代码510,并且错误响应包含额外的"multiStepAuthentication"对象,如下例所示

{
  \"errors\": [
    {
      \"message\": \"Es ist eine zusätzliche Authentifizierung erforderlich. Bitte geben Sie folgenden Code an: 123456\",
      \"code\": \"ADDITIONAL_AUTHENTICATION_REQUIRED\",
      \"type\": \"BUSINESS\",
      \"multiStepAuthentication\": {
        \"hash\": \"678b13f4be9ed7d981a840af8131223a\",
        \"status\": \"CHALLENGE_RESPONSE_REQUIRED\",
        \"challengeMessage\": \"Es ist eine zusätzliche Authentifizierung erforderlich. Bitte geben Sie folgenden Code an: 123456\",
        \"answerFieldLabel\": \"TAN\",
        \"redirectUrl\": null,
        \"redirectContext\": null,
        \"redirectContextField\": null,
        \"twoStepProcedures\": null,
        \"photoTanMimeType\": null,
        \"photoTanData\": null,
        \"opticalData\": null
      }
    }
  ],
  \"date\": \"2019-11-29 09:51:55.931\",
  \"requestId\": \"selfgen-45059c99-1b14-4df7-9bd3-9d5f126df294\",
  \"endpoint\": \"POST /api/v1/bankConnections/import\",
  \"authContext\": \"1/18\",
  \"bank\": \"DEMO0001 - finAPI Test Bank\"
}

此错误格式的例外是API身份验证错误,返回以下结构

{
  \"error\": \"invalid_token\",
  \"error_description\": \"Invalid access token: cccbce46-xxxx-xxxx-xxxx-xxxxxxxxxx\"
}

分页

可能返回大量数据的API服务实现分页。它们在每个“页面”中返回一定数量的条目。进一步的条目必须通过后续调用获取。

任何实现分页的API服务都提供以下输入参数
• "page":要检索的页码(从1开始)。
• "perPage":页面中的条目数。默认值和最大值在各自服务的文档中说明。

分页响应包含一个额外的"paging"对象,其结构如下

{
  ...
  ,
  \"paging\": {
    \"page\": 1,
    \"perPage\": 20,
    \"pageCount\": 234,
    \"totalCount\": 4662
  }
}

国际化

finAPI服务支持国际化,这意味着您可以为API服务响应定义您首选的语言。

以下语言可用:德语、英语、捷克语、斯洛伐克语。

首选语言可以通过提供官方HTTP Accept-Language标题来定义。

finAPI对以下语言的官方iso语言代码"de"、"en"、"cs"和"sk"做出反应。Accept-Language标题支持的附加子标签可以提供,例如"en-US",但会被忽略。
如果没有提供Accept-Language标题,则默认使用德语。

例外情况
• 银行登录提示和登录字段仅以银行的语种提供,且不会被翻译。
• 通常作为BUSINESS错误返回的银行系统直接消息不会翻译。
• finAPI直接创建的BUSINESS错误以德语和英语提供。
• 旨在开发者的TECHNICAL错误消息大多数为英语,但也可能翻译。

请求ID

在任何API调用中,您可以通过名为“X-Request-Id”的头部传递一个请求ID。请求ID可以是一个最多255个字符的任意字符串。传递较长的字符串会导致错误。

如果您为调用未传递请求ID,finAPI将内部生成一个随机ID。

请求ID始终以名为“X-Request-Id”的头部返回到服务的响应中。

我们强烈建议始终传递一个(最好是唯一的)请求ID,并在您发起请求或收到响应(尤其是错误响应)时将其包含到您的客户端应用程序日志中。finAPI也会在其端记录请求ID。拥有请求ID可以帮助finAPI支持团队更有效地工作并更快地解决工单。

覆盖HTTP方法

一些HTTP客户端不支持HTTP方法PATCH或DELETE。如果您正在使用此类客户端在您的应用程序中,您可以使用带有特殊HTTP头部以指示原始HTTP方法的POST请求。

该头部的名称是X-HTTP-Method-Override。将其值设置为PATCHDELETE。设置此头部的POST请求将由finAPI服务器处理为PATCH或DELETE。

示例

X-HTTP-Method-Override: PATCH
POST /api/v1/label/51
{\"name\": \"changed label\"}

将由finAPI解释为

PATCH /api/v1/label/51
{\"name\": \"changed label\"}

用户元数据

随着PSD2 API的迁移,API中引入了一个新的术语“用户元数据”(也称为“PSU元数据”)。这些用户元数据旨在告知银行API是否有真实的最终用户在HTTP请求之后,或者请求是由系统(例如自动批量更新)触发的。在后一种情况下,银行可能会对HTTP请求的数量进行一些限制,例如对单个同意的限制。此外,某些操作可能完全被银行API禁止。例如,一些银行不允许在没有最终用户参与的情况下颁发新的同意。因此,对于此类操作,客户提供PSU元数据是绝对必要且强制性的。

由于finAPI与最终用户没有直接交互,提供关于最终用户的所有必要信息是客户端应用程序的责任。这必须通过在代表最终用户触发的每个请求中发送额外的头部来完成。

目前,API支持以下头部
• \"PSU-IP-Address\" - 用户设备的IP地址。
• \"PSU-Device-OS\" - 用户设备及/或操作系统标识。
• \"PSU-User-Agent\" - 用户浏览器或其他客户端设备标识。

常见问题解答

是否有finAPI SDK?
目前我们不提供原生SDK,但可以通过OpenAPI生成几乎任何目标语言的SDK。使用此页面的“下载SDK”按钮生成SDK。

我如何启用finAPI的自动批量更新?
目前无法通过API设置批量更新。请联系support@finapi.io进行此操作。

为什么在调用此页面的服务时需要不断授权?
此页面是一个“单页应用”。重新加载页面会重置OAuth授权上下文。通常不需要重新加载页面,所以请不要这样做,您的授权将保持。

如需更多信息,请访问https://www.finapi.io/impressumrechtlicher-hinweis

安装与使用

要求

PHP 7.3 及以上版本。应也能与 PHP 8.0 兼容,但尚未测试。

Composer

要通过Composer安装绑定,请将以下内容添加到composer.json

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https:////.git"
    }
  ],
  "require": {
    "/": "*@dev"
  }
}

然后运行composer install

手动安装

下载文件并包含autoload.php

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

入门指南

请遵循安装过程,然后运行以下命令

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



// Configure OAuth2 access token for authorization: finapi_auth
$config = OpenAPIAccess\Client\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');

// Configure OAuth2 access token for authorization: finapi_auth
$config = OpenAPIAccess\Client\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new OpenAPIAccess\Client\Api\AccountsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$id = 56; // int | Identifier of the account to delete
$x_http_method_override = 'x_http_method_override_example'; // string | Some HTTP clients do not support the HTTP methods PATCH or DELETE. If you are using such a client in your application, you can use a POST request instead with this header indicating the originally intended HTTP method. POST Requests having this  header set will be treated either as PATCH or DELETE by the finAPI servers.
$x_request_id = 'x_request_id_example'; // string | With any API call, you can pass a request ID. The request ID can be an arbitrary string with up to 255 characters. Passing a longer string will result in an error. If you don't pass a request ID for a call, finAPI will generate a random ID internally. The request ID is always returned back in the response of a service, as a header with name 'X-Request-Id'. We highly recommend to always pass a (preferably unique) request ID, and include it into your client application logs whenever you make a request or receive a response (especially in the case of an error response). finAPI is also logging request IDs on its end. Having a request ID can help the finAPI support team to work more efficiently and solve tickets faster.

try {
    $apiInstance->deleteAccount($id, $x_http_method_override, $x_request_id);
} catch (Exception $e) {
    echo 'Exception when calling AccountsApi->deleteAccount: ', $e->getMessage(), PHP_EOL;
}

API 端点

所有 URI 都是相对于https://sandbox.finapi.io

模型

授权

finapi_auth

  • 类型: OAuth
  • 流程: password
  • 授权URL: ``
  • 作用域:
    • all: 无限制

finapi_auth

  • 类型: OAuth
  • 流程: application
  • 授权URL: ``
  • 作用域:
    • all: 无限制

测试

运行测试,使用

composer install
vendor/bin/phpunit

作者

kontakt@finapi.io

关于此包

此PHP包由OpenAPI Generator项目自动生成

  • API版本: 1.143.1
  • 构建包: org.openapitools.codegen.languages.PhpClientCodegen