Pular para o conteúdo principal

Como começar

Instalando​

É necessário ter o Java com versão superior à 8.0 instalado com o Gradle ou Maven.

Use o repositório do "Maven Central" para instalar o SDK:

repositories {
    mavenCentral()
}

E também adicione a dependência do SDK:

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:

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. 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.

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.

// 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.

// 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

// 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.

/**
 * 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 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<PixQrCodeResponse> getPixQrCodeAsync(...): Obtém um Pix QR Code pelo ID.

  • Future<PixQrCodeList> allPixQrCodesAsync(...): Lista todos os Pix QR Codes.

  • Future<PixQrCodeResponse> createPixQrCodeAsync(...): Cria um Pix QR Code.

  • Future<Account> getAccountAsync(...): Obtém uma conta pelo ID.

  • Future<AccountListResponse> allAccountsAsync(...): Lista todas as contas.

  • Future<WithdrawResponse> withdrawAsync(...): Realiza um saque.

  • Future<PaymentResponseObject> getPaymentAsync(...): Obtém um pagamento pelo ID.

  • Future<PaymentListResponse> allPaymentsAsync(...): Lista todos os pagamentos.

  • Future<PaymentResponseObject> createPaymentAsync(...): Cria um pagamento.

  • Future<ChargeDeleteResponse> deleteChargeAsync(...): Remove uma cobrança pelo ID.

  • Future<ChargeResponse> getChargeAsync(...): Obtém uma cobrança pelo ID.

  • Future<ChargeListResponse> chargesAsync(...): Lista todas as cobranças.

  • Future<ChargeResponse> createChargeAsync(...): Cria uma cobrança.

  • Future<File> chargeQrCodeImageAsync(...): Obtém a imagem de um QR Code de uma cobrança.

  • Future<Customer> getCustomerAsync(...): Obtém um cliente pelo ID.

  • Future<CustomerListResponse> allCustomersAsync(...): Lista todos os clientes.

  • Future<CustomerResponse> createCustomerAsync(...): Cria um cliente.

  • Future<RefundResponse> getRefundAsync(...): Obtém um reembolso pelo ID.

  • Future<RefundListResponse> allRefundsAsync(...): Lista todos os reembolsos.

  • Future<RefundResponse> createRefundAsync(...): Cria um reembolso.

  • Future<WebhookDeleteResponse> deleteWebhookAsync(...): Remove um webhook pelo ID.

  • Future<WebhookListResponse> allWebhooksAsync(...): Lista todos os webhooks.

  • Future<WebhookResponse> createWebhookAsync(...): Cria um webhook.

  • Future<TransactionResponse> getTransactionAsync(...): Obtém uma transação pelo ID.

  • Future<TransactionListResponse> transactionsAsync(...): Lista todas as transações.

Dependências​

O SDK depende de implementações das:

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.