Pular para o conteúdo principal

Como começar

Instalando​

É necessário ter o PHP com versão superior à 7.4 instalado com o Composer.

Execute o comando abaixo que instala as dependências necessárias com o Composer:

$ composer require open-pix/php-sdk guzzlehttp/guzzle guzzlehttp/psr7

Dessa forma, o SDK, um cliente HTTP (guzzlehttp/guzzle) e uma implementação da PSR-17 (guzzlehttp/psr7) serão instalados.

Criando o cliente​

O ponto de entrada do SDK é um Client:

use OpenPix\PhpSdk\Client;

// Para utilizar OpenPix
$client = Client::create("coloque seu appid aqui");

O método create cria um novo cliente a partir de um ID de aplicativo obtido no site da OpenPix.

Chamando a API​

Um cliente possui recursos (por exemplo: clientes, cobranças, assinaturas, etc.) que podem ser acessados através da execução de métodos no Client.

$client->customers();

Cada recurso irá ter um conjunto de métodos que podem serem executados para realizarem operações:

// Cria um cliente.
$dadosCliente = [
    "name" => "Dan", // Nome
    "taxID" => "31324227036", // CPF
    "email" => "[email protected]", // E-mail
    "phone" => "5511999999999", // Telefone
    "correlationID" => "9134e286-6f71-427a-bf00-241681624586", // ID de correlação
];

$result = $client->customers()->create($dadosCliente);

Operações em recursos​

Em cada recurso, há uma convenção nos nomes das operações, na qual:

  • getOne: Obter apenas um recurso. Associado ao verbo HTTP GET.
  • list: Retornar um paginador, com o resultado da página atual podendo ser obtido executando o método current. Associado ao verbo HTTP GET.
  • create: Criar um recurso. Associado ao verbo HTTP POST.
  • delete: Remover um recurso. Associado ao verbo HTTP DELETE.

Formato das entradas​

No caso de operações de listagem ou de criação, os argumentos de entradas são comumente arrays.

// Cria uma assinatura.
$assinatura = [
    "value" => 100, // Valor
    "customer" => [
        "name" => "Dan", // Nome
        "taxID" => "31324227036", // CPF
        "email" => "[email protected]", // Email
        "phone" => "5511999999999", // Telefone
    ],
    // Dia do mês em que as cobranças serão geradas. Máximo de 27.
    "dayGenerateCharge" => 15,
];

$client->subscriptions()->create($assinatura);

Argumentos simples como strings e inteiros são utilizados no caso de operações de obtenção de apenas um recurso ou remoção.

// Obtém uma cobrança pelo ID. string.
$client->charges()->getOne($correlationID);

// Remove uma cobrança pelo ID. string.
$client->charges()->delete($correlationID);

Formato de saída​

A execução de uma operação irá devolver resultados da API na forma de um array direto ou na forma de um paginador, especialmente em operações de listagem, como na listagem de transações.

/**
 * Criando uma solicitação de pagamento.
 *
 * Retorna um array.
 */
$result = $client->payments()->create([
    "value" => 100,
    "destinationAlias" => "c4249323-b4ca-43f2-8139-8232aab09b93",
    "comment" => "payment comment",
    "correlationID" => "payment1",
    "sourceAccountId" => "my-source-account-id",
]);

/**
 * Resultado:
 *
 * $result = [
 *    "payment" => [
 *        "value" => 100,
 *        "status" => "CREATED",
 *        "destinationAlias" => "c4249323-b4ca-43f2-8139-8232aab09b93",
 *        "comment" => "payment comment",
 *        "correlationID" => "payment1",
 *        "sourceAccountId" => "my-source-account-id",
 *    ],
 *  ],
 * ];
 */

Paginação​

Em recursos em que é possível paginação, há um método list que retorna um objeto Paginator.

Um objeto Paginator possui métodos que auxiliam na paginação dos resultados de operações de listagem de recursos.

Este objeto implementa a interface Iterator, portanto possui métodos como current e next e pode ser utilizado em loops foreach.

// Utilizando foreach para obter 100 clientes.
// Cuidado ao utilizar, pois pode obter todos os clientes disponíveis da API de uma só vez.

$paginator = $client->customers()->list();

$remainingCustomers = 100;

// O foreach chama o método `current`, `next` e `valid` automaticamente.
foreach ($paginator as $result) {
    foreach ($result["customers"] as $customer) {
        // Ativa delay de 200ms.
        usleep(100000);

        echo "Nome do cliente: " . $customer["name"] . "\n";

        $remainingCustomers--;

        if ($remainingCustomers == 0) break 2;
    }
}

// Utilizando loop do/while para obter 100 clientes.
$paginator = $client->customers()->list();

$remainingCustomers = 100;

do {
    // Ativa delay de 200ms.
    usleep(200000);

    // Envia a solicitação HTTP para a API e retorna o resultado como um array.
    $result = $paginator->current();

    foreach ($result["customers"] as $customer) {
        echo "Nome do cliente: " . $customer["name"] . "\n";

        $remainingCustomers--;

        if ($remainingCustomers == 0) break;
    }

    // Avança uma página
    $paginator->next();
} while ($paginator->valid() && $remainingCustomers != 0);

Métodos disponíveis​

Veja os métodos disponíveis em objetos Paginator:

Obs.: as páginas iniciam em zero, como arrays.

// Utilizando como exemplo a listagem de clientes
$paginator = $client->customers()->list();

$paginator->key(); // Obtém o número da página atual. (pg. atual 0)
$paginator->next(); // Avança uma página. (pg. atual 1)
$paginator->previous(); // Retrocede uma página. (pg. atual 0)
$paginator->valid(); // Retorna `true` se há próxima página e `false` caso contrário.
$paginator->perPage(30); // Quantidade de itens por página.
$paginator->skip(30); // Pula 30 clientes. (pg. atual 1)
$paginator->rewind(); // Volta para a página inicial. (pg. atual 0)
$paginator->go(2); // Vai para a página 2 (pg. atual 2)
$paginator->getTotalResourcesCount(); // Obtém a quantidade *total* de clientes disponíveis na API

// Envia uma requisição para a API e retorna o array de resultado
// Aqui, irá obter o array de resultado da página 2.
$page = $paginator->current();

// Retorna o nome do primeiro cliente da página 2.
echo $page["customers"][0]["name"];

PHPDocs​

Em cada operação disponível para um determinado tipo de recurso, existem PHPDocs 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 Intellisense como PhpStorm ou Visual Studio Code com a extensão Intelephense.

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:

  • $client->customers(): Operações em clientes.
  • $client->subscriptions(): Operações em assinaturas.
  • $client->charges(): Operações em cobranças.
  • $client->refunds(): Operações em restituições.
  • $client->payments(): Operações em solicitações de pagamentos.
  • $client->transactions(): Operações em transações.
  • $client->webhooks(): Operações em webhooks.

Dependências​

O SDK depende de implementações das PSRs 17 e 18.

A PSR-17 é usada para fornecer interfaces para mensagens HTTP, tanto requisições quanto respostas. Por outro lado, a PSR-18 é usada para fornecer interfaces para clientes HTTP.

Sendo interfaces, é necessário ter uma implementação instalada, como guzzlehttp/guzzle para a PSR-18 e guzzlehttp/psr7 para a PSR-17.

As PSRs são utilizadas para não depender diretamente de clientes HTTP, deixado a cargo do desenvolvedor.

Exemplos de integração​

Veja exemplos de integração com o SDK de PHP.