@payping/api
v4.7.0-beta.11
Published
payping public api
Downloads
167
Keywords
Readme
Attention
Please do not use any code linting tool (eslint, prettier, ...) in api/* files, because they are auto generated, and they might be replaced again, so manual changes in the code should be minimal.
How to use
1. first config sdk behavior in apiConfigs.ts
file:
// root/apiConfigs.ts
import { StatusHandlersTypes, apiConfigs } from "@payping/api";
import { Modal } from "@payping/desktop-components";
import { logout } from "./actions";
import { environment } from "./env";
import { store } from "./index";
const generalHandler = (error): void => {
// eslint-disable-next-line no-console
console.error(error);
Modal.error({
content: error.message,
title: "خطا",
});
};
const unAuthorizedHandler = (): void => {
store.dispatch(logout());
};
const statusHandlers: StatusHandlersTypes = {
"401": unAuthorizedHandler,
default: generalHandler,
};
const networkChecker = new Promise<void>((resolve) => resolve());
apiConfigs.updateConfig({
environment,
networkChecker,
statusHandlers,
});
2. then import apiConfigs.ts
file in your root component to intiate configs like this:
import "./apiConfigs";
3. after that, set accessToken in your root component ASAP:
import { apiConfigs } from "@payping/api";
const token = this.props.organizationToken || this.props.token;
if (token) {
apiConfigs.updateConfig({ accessToken: token });
}
4. call updateConfig
wherever accessToken changes:
- on login personal token
- on logout personal token
- on login organization token
- on logout organization token
5. import APIs and use them:
import { invoiceV2Apis } from "@payping/api";
const { invoiceV2List } = invoiceV2Apis;
async function getInvoices() {
const res = await invoiceV2List();
return res;
}
6. you can change baseurl by updateConfig
method:
import { EnvironmentType, apiConfigs } from "@payping/api";
const environment: EnvironmentType = "Development"; // manatadbir.ir
apiConfigs.updateConfig({ environment });
Other usefull methods:
- getCurrentPath:
const { oauthPath, basePath } = getCurrentPath();
- sdkFetch: use it just like
fetch
but you can ignore base path and it doesn't need accessToken and error handlers
How to Add a method:
Short way
Run following script with the url of openapi schema:
NOTE: you need java & node on your system to be able to run this script
yarn run generate-api:ts --input cash-out --version v1,v2,PublicApi --replace true
- input:
serviceName
orurl
orfile
address, e.g.:oauth
https://oauth.payping.dev/swagger/openApi/v1/swagger.json
./schema.json
- version: Comma-separated list of needed versions. e.g.:
v1,v2,PublicApi
v1
- replace: Whether to replace current api files inside src/<admin|app>/api folder. Default value is
true
,false
should be passed if not wanted.
Input & Versions
If required Input
field in not in this list please add it to the switch case in generate-api.ts and update the list
| Input | Example Versions | | ----------------------------------------- | ---------------------------------------- | | admin | v1 | | category | v1 | | permalink | v1 | | product | v1 | | coupon | v1 | | customer | v1 | | invoice | v1 | | timeline | v1 | | oauth | v1 | | pay | v1 | | payment | v1 | | report | v1 | | request | v1 | | withdraw | v1 | | service | v1 | | user | v1 | | digitalAccount | BankAgreements,Banks,Khavarmiyaneh,Saman | | cashout - cashOut - cash-out - settlement | v1,v2,PublicApi | | bnplConsumer | v1 | | bnplMerchant | v1 |
Long way
1. Get the (json|yaml) schema file:
- Go to the swagger ui (for example https://swagger.payping.ir/)
- At the top of the page, there is a path for the schema (json or yaml), in this case: https://cdn.payping.ir/statics/openapi.json
- Copy the content of this file to the https://editor.swagger.io/
2. Generate api code:
- The result of the previous step generates the same swagger ui that you saw in the https://swagger.payping.ir
NOTE: You might be asked to convert your file to
yaml
, it's okay if you acceptNOTE: If you see errors at the top of the generated swagger ui, you need to fix them to be able to generate your code. Otherwise no error will be shown and only your request will receive 400 response.
- Now you can generate your desired
Server
orClient
side code (we usetypescript-fetch
).
3. Merge codes:
- Inside the generated code you need the
api.ts
file, inside which you will find the type and the methods. - There are 4 main functions (each function contains functions for each of the methods) for calling methods with name similar to following:
- ProductApiFetchParamCreator: this function generates the options for the request, so its output is a
json object
. - ProductApiFp: this function calls the
ProductApiFetchParamCreator
to get the request options, then performs the request, and then return the response to us. - ProductApiFactory: this function is how we can use these apis in different places in our code (they are exported in /src/apis.ts).
- ProductApi: this function is the same as
ProductApiFactory
, the only difference is that this one is based on class but last one was based on function.WARNING: Do not replace the whole code with the generated one (there are some methods that we have added ourselves).
- ProductApiFetchParamCreator: this function generates the options for the request, so its output is a
- Find the 4 functions of the methods that you want to add and add them to the existing ones.
- The missing types, request body type (input of all 4 functions) or output viewModel (output of 2nd function), should be added to the
types.ts
file next to the functions file.NOTE: Check the apisTypes to ensure your new types are all exported
NOTE: Replace all Date types with string, since we will have problems with Date types.
Checking changes before Publish:
- Run script for building package on local (
customPrepublishOnly:app
orcustomPrepublishOnly:admin
). - Output will be in a
dist|distAdmin
folder at the root of the project. - Go to the project that you want to install this package in and install it locally:
yarn add ../apisdk/dist/ or yarn add ../apisdk/distAdmin/
NOTE: If your project has submodules you need to use the
-W
option inyarn add
command and replace the version of the package in all package.json files with this route../apisdk/dist/
.
How to Publish:
Admin:
Create a release branch for this new version (its name should be the new version that you want to publish plus admin for example
1.0.4-admin
):Edit
build_config/admin/package.json
version (pay attention to Semver)Run script for publishing package on registry:
NOTE: In your terminal you should be logged in at our registry at https://npmregistry.payping.dev If you aren't, run:
npm logout npm login --registry=https://npmregistry.payping.dev
yarn customPublish:admin
- Finish your release branch
Dashboard:
Create a release branch for this new version (its name should be the new version that you want to publish plus app for example
1.0.4-app
):Edit
build_config/app/package.json
version (pay attention to Semver)Run script for publishing package on registry:
NOTE: In your terminal you should be logged in at npm registry at https://registry.npmjs.org. If you aren't, run:
npm logout npm login
yarn customPublish:app
- Finish your release branch