From e0d93df0e015cdcc7544473ff7c31a802076e55e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabrielle=20Guimar=C3=A3es=20de=20Oliveira?= Date: Tue, 1 Aug 2023 10:45:52 -0300 Subject: [PATCH] add java sdk docs (#565) * feat(sdks/java): add base for java sdk docs * feat(sdks/java): add usage apge * feat(sdks/java): add docs for each item in usage.md * feat(sdks/java): add contributing * feat(sdks/java): remame what-is * feat(sdks/java): add resources.md --- docs/sdk/java/_category_.json | 13 ++ docs/sdk/java/contributing.md | 12 ++ docs/sdk/java/resources.md | 216 ++++++++++++++++++++++++++++++++++ docs/sdk/java/usage.md | 214 +++++++++++++++++++++++++++++++++ docs/sdk/java/what-is.md | 23 ++++ 5 files changed, 478 insertions(+) create mode 100644 docs/sdk/java/_category_.json create mode 100644 docs/sdk/java/contributing.md create mode 100644 docs/sdk/java/resources.md create mode 100644 docs/sdk/java/usage.md create mode 100644 docs/sdk/java/what-is.md diff --git a/docs/sdk/java/_category_.json b/docs/sdk/java/_category_.json new file mode 100644 index 00000000..78958687 --- /dev/null +++ b/docs/sdk/java/_category_.json @@ -0,0 +1,13 @@ +{ + "label": "Java", + "collapsible": true, + "collapsed": true, + "className": "orange", + "link": { + "type": "generated-index", + "title": "SDK de Java" + }, + "customProps": { + "description": "Java SDK da OpenPix" + } +} diff --git a/docs/sdk/java/contributing.md b/docs/sdk/java/contributing.md new file mode 100644 index 00000000..945eff5f --- /dev/null +++ b/docs/sdk/java/contributing.md @@ -0,0 +1,12 @@ +--- +id: java-sdk-contributing +title: Como contribuir com o SDK +sidebar_position: 3 +tags: +- api +- ruby +- sdk +--- + +## Contribuindo com o OpenPix Java SDK +O desenvolvimento do nosso Java SDK é opensource e pode ser encontrado em nosso [repositório público](https://github.com/Open-Pix/ruby-sdk). Para contribuir basta ler a sessão de [contributing](https://github.com/Open-Pix/java-sdk#contributing) diff --git a/docs/sdk/java/resources.md b/docs/sdk/java/resources.md new file mode 100644 index 00000000..700c7a40 --- /dev/null +++ b/docs/sdk/java/resources.md @@ -0,0 +1,216 @@ +--- +id: java-sdk-resources +title: Recursos +sidebar_position: 2 +tags: +- api +- ruby +- sdk +--- + +## Lista de recursos disponíveis + +Existem recursos disponíveis para cada tipo de operação. Para cada recurso, existe uma classe que representa o recurso e uma classe que representa uma lista de recursos. Essas classes são as classes de paginação: `Paginator`. + +### Paginação + +A classe `Paginator` é uma classe que representa uma lista de recursos. Ela possui os seguintes métodos: + +- `Future> itemsAsync()`: Obtém os itens da página atual. +- `Future pageInfoAsync()`: Obtém as informações da página atual. +- `void next()`: Vai para a próxima página. +- `void previous()`: Vai para a página anterior. + +As funções `next` e `previous` atualizam uma informação da classe, e os dados só serão lidos +da próxima vez que for chamado o método `itemsAsync` ou `pageInfoAsync`. + +### Charge + +- `Charge`: Representa uma cobrança. + +#### Criar uma cobrança + +```java,no +// Cria uma charge +ChargeBuilder charge = new ChargeBuilder() + .value(100) + .comment("comment") + .correlationID("correlationId") + .destinationAlias("destinationAlias") + .sourceAccountId("sourceAccountId"); + +sdk.createChargeAsync(charge).get(); +``` + +#### Obter uma cobrança + +```java,no +// Obtém uma cobrança pelo ID. string. +sdk.getChargeAsync(correlationID).get(); +``` + +#### Remover uma cobrança + +```java,no +// Remove uma cobrança pelo ID. string. +sdk.deleteChargeAsync(correlationID).get(); +``` + +### PixQrCode + +- `PixQrCode`: Representa um pix qr code. + +#### Criar um pix qr code + +```java,no +// Cria um pix qr code +PixQrCodeBuilder pixQrCode = new PixQrCodeBuilder() + .value(100) + .comment("comment") + .correlationID("correlationId") + .destinationAlias("destinationAlias") + .sourceAccountId("sourceAccountId"); + +sdk.createPixQrCodeAsync(pixQrCode).get(); +``` + +#### Obter um pix qr code + +```java,no +// Obtém um pix qr code pelo ID. string. +sdk.getPixQrCodeAsync(correlationID).get(); +``` + +### Transação + +- `Transaction`: Representa uma transação. + +#### Obter uma transação + +```java,no +// Obtém uma transação pelo ID. string. +sdk.getTransactionAsync(correlationID).get(); +``` + +### Conta + +- `Account`: Representa uma conta. + +#### Obter uma conta + +```java,no +// Obtém uma conta pelo ID. string. +sdk.getAccountAsync(correlationID).get(); +``` + +#### Obter uma lista de contas + +```java,no +// Obtém uma lista de contas. +sdk.getAccountsAsync().get(); +``` + +#### Performar saque + +```java,no +// Performa um saque. +sdk.withdrawAsync(id, value).get(); +``` + +### Reembolso + +- `Refund`: Representa um reembolso. + +#### Criar um reembolso + +```java,no +// Cria um reembolso +RefundBuilder refund = new RefundBuilder() + .value(100) + .comment("comment") + .correlationID("correlationId") + .destinationAccountId("destinationAccountId") + .sourceAccountId("sourceAccountId"); + +sdk.createRefundAsync(refund).get(); +``` + +#### Obter um reembolso + +```java,no +// Obtém um reembolso pelo ID. string. +sdk.getRefundAsync(correlationID).get(); +``` + +### Webhook + +- `Webhook`: Representa um webhook. + +#### Criar um webhook + +```java,no +// Cria um webhook +WebhookBuilder builder = new WebhookBuilder() + .number(100) + .url("https://google.com") + .enableWebhook(); + +sdk.createWebhookAsync(builder).get(); +``` + +#### Deletar um webhook + +```java,no +// Deleta um webhook pelo ID. string. +sdk.deleteWebhookAsync(correlationID).get(); +``` + +### Customer + +- `Customer`: Representa um customer. + +#### Criar um customer + +```java,no +// Cria um customer +CustomerBuilder builder = new CustomerBuilder() + .name("name") + .email("email@gmail.com") + .taxIdNumber("947.761.930-04") + .phoneNumber("4299999-9999") + .address(address); + +sdk.createCustomerAsync(builder).get(); +``` + +#### Obter um customer + +```java,no +// Obtém um customer pelo ID. string. +sdk.getCustomerAsync(correlationID).get(); +``` + +### Pagamento + +- `Payment`: Representa um pagamento. + +#### Criar um pagamento + +```java,no +// Cria um pagamento +PaymentBuilder payment = new PaymentBuilder() + .value(100) + .comment("comment") + .correlationID("correlationId") + .destinationAccountId("destinationAccountId") + .sourceAccountId("sourceAccountId"); + +sdk.createPaymentAsync(payment).get(); +``` + +#### Obter um pagamento + +```java,no +// Obtém um pagamento pelo ID. string. +sdk.getPaymentAsync(correlationID).get(); +``` \ No newline at end of file diff --git a/docs/sdk/java/usage.md b/docs/sdk/java/usage.md new file mode 100644 index 00000000..944586b5 --- /dev/null +++ b/docs/sdk/java/usage.md @@ -0,0 +1,214 @@ +--- +id: java-sdk-usage +title: Como começar +sidebar_position: 0 +tags: + - api + - java + - sdk +--- + +## Instalando + +É necessário ter o PHP com versão superior à 8.0 instalado com o [Gradle](https://gradle.org) ou [Maven](https://maven.apache.org/). + +Use o repositório do "Maven Central" para instalar o SDK: + +```groovy +repositories { + mavenCentral() +} +``` + +E também adicione a dependência do SDK: + +```groovy +dependencies { + implementation 'br.com.openpix:java-sdk:1.0.0' +} +``` + +Dessa forma, o SDK, um cliente HTTP (`ktor`) e uma implementação serão instalados. + +## Criando o cliente + +O ponto de entrada do SDK é um `WooviSDK`: + +```java +package br.com.openpix; + +import br.com.openpix.sdk.WooviSDK; + +import java.util.concurrent.ExecutionException; + +public class Main { + public static void main(String[] args) { + // Para começar a usar o SDK Java + WooviSDK sdk = new WooviSDK(System.getenv("APP_ID")); + } +} + +``` + +O constructor cria um novo cliente a partir de um ID de aplicativo obtido no [site da OpenPix](https://app.openpix.com.br/home/applications/tab/list). Também é possível passar configurações para o SDK, como o executor, para isso você pode observar os "overloads" dessa função, que por definição são os construtores com o mesmo nome, mas com parâmetros diferentes. Você também pode utilizar o método estático `WooviSdk.of` para construir. + +Através dos "overloads" você pode específicar, a "url base", o "executor"(que é o ambiente onde vão ser despachadas as threads), uma instância de json e uma instância de http client. + +Ambas instâncias de json e http client você pode configurar parâmetros internos, como `explicitNulls`, +leniência, e outros, que não vem ao caso, no momento. Todas elas estão documentadas em código, e são fáceis de ler. + +## Chamando a API + +Um SDK possui _métodos_ para acessar a API da OpenPix. Todos eles são assíncronos, e retornam um `Future` que pode ser usado para obter o resultado da chamada. + +```java,no +sdk.allCustomersAsync().get(); +``` + +Cada função retorna um futuro, que pode ser acessado em "single-thread" utilizando o método `get` ou em "multi-thread" utilizando o método `join`. + +## Procurando páginas + +Para procurar páginas, você pode utilizar os métodos, que tem como parâmetro os "start", "end", "charge", e outros, que são os parâmetros de paginação da API. Um exemplo desses métodos, é o método `transactionsAsync`, que retorna uma página de transações. + +```java,no +// Você pode utilizar o método get para obter o resultado da chamada. E não passar nenhum parametro, porque os parametros são opcionais. +sdk.transactionsAsync().get(); + +// Você pode utilizar os seguintes parametros: +sdk.transactionsAsync(start, end, charge, pixQrCode, withdrawal).get(); +``` + +### Formato das entradas + +Cada formato de entrada é uma classe com tipos, geralmente são nomeados como `Builder` no final, por exemplo `ChargeBuilder`. + +```java,no +// Cria uma charge +ChargeBuilder charge = new ChargeBuilder() + .value(100) + .comment("comment") + .correlationID("correlationId") + .destinationAlias("destinationAlias") + .sourceAccountId("sourceAccountId"); + +sdk.createChargeAsync(charge).get(); +``` + +Argumentos simples como strings e inteiros são utilizados no caso de operações de obtenção de apenas um recurso ou remoção. Por exemplo + +```java,no +// Obtém uma cobrança pelo ID. string. +sdk.getChargeAsync(correlationID); + +// Remove uma cobrança pelo ID. string. +sdk.deleteChargeASync(correlationID); +``` + +### Formato de saída + +A execução de uma operação irá devolver resultados da API na forma de um objeto ou na forma de um paginador, especialmente em operações de listagem, como na listagem de transações. + +```java, +/** + * Criando um pix qr code + * + * Retorna um objeto + */ +PixQrCodeBuilder builder = new PixQrCodeBuilder() + .identifier("identificador") + .name("nome"); + +System.out.println(sdk.createPixQrCodeAsync(builder).get()); + +/** + * Resultado: (Identado para fins de leitura) + * + * PixQrCodeResponse( + * pixQrCode=PixQrCode( + * name=nome, + * identifier=identificador, + * correlationID=bad32cd4-123e-49f7-8ca4-f1381c633831, + * paymentLinkID=a42a8a56-ab8e-4fc3-833d-c7dc1ff7473f, + * createdAt=2023-07-28T01:41:58.920Z, + * updatedAt=2023-07-28T01:41:58.920Z, + * brCode=00020126580014br.gov.bcb.pix013600ad360c-92c7-45ab-adb3-188307a6e4d05204000053039865802BR5910Woovi_Demo6009Sao_Paulo62170513identificador63040E64, + * paymentLinkUrl=https://openpix.com.br/pay/a42a8a56-ab8e-4fc3-833d-c7dc1ff7473f, + * qrCodeImage=https://api.openpix.com.br/openpix/charge/brcode/image/a42a8a56-ab8e-4fc3-833d-c7dc1ff7473f.png + * ), + * correlationID=null, + * brCode=null, + * ) + */ +``` + +## JavaDocs + +Em cada operação disponível para um determinado tipo de recurso, existem [Java Docs](https://docs.oracle.com/en/java/) disponíveis informando o formato de entrada e saída da operação com um link para a documentação da API Rest e exemplo de utilização. + +Para utilizar, é sugerido utilizar um editor com como o Eclipse ou o IntelliJ que possuem suporte para Java e bastante tooling para facilitar o desenvolvimento. + +Também é possível consultar a documentação no site da OpenPix caso haja dúvidas. + +## Recursos disponíveis + +Os seguintes recursos estão disponíveis no `Client`: + +- `Future getPixQrCodeAsync(...)`: Obtém um Pix QR Code pelo ID. + +- `Future allPixQrCodesAsync(...)`: Lista todos os Pix QR Codes. + +- `Future createPixQrCodeAsync(...)`: Cria um Pix QR Code. + +- `Future getAccountAsync(...)`: Obtém uma conta pelo ID. + +- `Future allAccountsAsync(...)`: Lista todas as contas. + +- `Future withdrawAsync(...)`: Realiza um saque. + +- `Future getPaymentAsync(...)`: Obtém um pagamento pelo ID. + +- `Future allPaymentsAsync(...)`: Lista todos os pagamentos. + +- `Future createPaymentAsync(...)`: Cria um pagamento. + +- `Future deleteChargeAsync(...)`: Remove uma cobrança pelo ID. + +- `Future getChargeAsync(...)`: Obtém uma cobrança pelo ID. + +- `Future chargesAsync(...)`: Lista todas as cobranças. + +- `Future createChargeAsync(...)`: Cria uma cobrança. + +- `Future chargeQrCodeImageAsync(...)`: Obtém a imagem de um QR Code de uma cobrança. + +- `Future getCustomerAsync(...)`: Obtém um cliente pelo ID. + +- `Future allCustomersAsync(...)`: Lista todos os clientes. + +- `Future createCustomerAsync(...)`: Cria um cliente. + +- `Future getRefundAsync(...)`: Obtém um reembolso pelo ID. + +- `Future allRefundsAsync(...)`: Lista todos os reembolsos. + +- `Future createRefundAsync(...)`: Cria um reembolso. + +- `Future deleteWebhookAsync(...)`: Remove um webhook pelo ID. + +- `Future allWebhooksAsync(...)`: Lista todos os webhooks. + +- `Future createWebhookAsync(...)`: Cria um webhook. + +- `Future getTransactionAsync(...)`: Obtém uma transação pelo ID. + +- `Future transactionsAsync(...)`: Lista todas as transações. + +## Dependências + +O SDK depende de implementações das: +- [Ktor Client](https://ktor.io/docs/create-client.html) (e outras dependências) +- [Kotlinx Coroutines](https://github.com/Kotlin/kotlinx.coroutines) +- [Kotlinx Serialization](https://github.com/Kotlin/kotlinx.serialization) + +O Ktor client é utilizado para realizar as requisições HTTP, e as outras dependências são utilizadas para realizar as requisições de forma assíncrona. diff --git a/docs/sdk/java/what-is.md b/docs/sdk/java/what-is.md new file mode 100644 index 00000000..c5bc2bd1 --- /dev/null +++ b/docs/sdk/java/what-is.md @@ -0,0 +1,23 @@ +--- +id: java-sdk-what-is +title: O que é o SDK de Java? +sidebar_position: 0 +tags: + - api + - java + - sdk +--- + +O SDK de Java é um kit de ferramentas criado com o objetivo de integrar facilmente os serviços da OpenPix em suas aplicações Java. + +Permite criar assinaturas recorrentes, cobranças, solicitações de pagamentos, webhooks, bem como gerenciar outros dados da API. + +É possível enviar requisições customizadas utilizando nosso cliente, que adiciona todas as informações necessárias, como informações de autenticação e realiza a decodificação das respostas em formato JSON. + +Utilizando o nosso paginador integrado, é fácil criar paginações para listagem de dados, com métodos que seguem os padrões do Java. É suportado em todos os endpoints de listagem de dados. + +[JavaDoc](https://www.jetbrains.com/help/idea/working-with-code-documentation.html) estão em todas as classes e métodos para facilitar a utilização de nosso SDK pelo seu editor favorito, como Visual Studio Code por exemplo. + +O SDK é mantido oficialmente pela OpenPix e distribuído pelo [Maven Central](https://search.maven.org/). + +O código está disponível no [repositório do GitHub](https://github.com/Open-Pix/java-sdk).