08. Conexão com APIs

Essa documentação ainda não está na fase final. Recomendamos a leitura e estudo do código para compreensão maior do funcionamento.

O Banco Central do Brasil já lançou as especificações padrões da API Pix e elas estão disponíveis em bacen/pix-api. Entretanto, cada Banco Emissor ou PSP tem suas próprias especificações que podem, ou não, serem compatíveis com as especificações oficiais. Por essa razão determinamos que nossa biblioteca apenas provê as interfaces necessárias para realizar as conexões com as APIs Pix de forma organizada e padronizada.

A classe BaseApi é responsável por esse tratamento. O objetivo dela é prover os principais endpoints para criação/obtenção das cobranças Pix, para que esses dados sejam convertidos no código Pix apropriado.

Essa classe ainda permite que todos os endpoint sejam personalizados, assim, você poderá configurar conforme a API que estará utilizando. Alguns bancos e provedores de serviços de pagamentos já liberaram as documentações das suas APIs, basta seguir de acordo. Os endpoints que a BaseApi suporta são:

Constante	Valor	Descrição
BaseApi::ENDPOINT_CREATE_COB	1	Endpoint para a criação de cobranças.
BaseApi::ENDPOINT_UPDATE_COB	2	Endpoint para a atualização de cobranças.
BaseApi::ENDPOINT_GET_COB	3	Endpoint para a obtenção de uma cobrança.
BaseApi::ENDPOINT_CREATE_DEVO	4	Endpoint para a solicitação de devolução.
BaseApi::ENDPOINT_GET_DEVO	5	Endpoint para a obtenção da solicitação de devolução.
BaseApi::ENDPOINT_OAUTH	99	Endpoint para a autenticação OAuth.

A classe BaseApi é um singleton e abstrata. Você deve criar a sua própria classe para estender esta. Para exemplo, vamos criar a classe BradescoApi e estender a classe BaseApi. O primeiro passo é configurar e adicionar todos os endpoints.

// Crie uma classe para o Banco/SPI e extenda BaseApi
// Configura a classe BaseApi
$bradesco = BradescoApi::use(
	'https://qrpix-h.bradesco.com.br',
	SSL_CERT_ABSPATH,
	SSL_CERT_PASS
)->addEndpoint(
	BaseApi::ENDPOINT_CREATE_COB,
	BaseApi::REQUEST_METHOD_POST,
	'/cob/{tid}'
)->addEndpoint(
	BaseApi::ENDPOINT_UPDATE_COB,
	BaseApi::REQUEST_METHOD_PATCH,
	'/cob/{tid}'
)->addEndpoint(
	BaseApi::ENDPOINT_GET_COB,
	BaseApi::REQUEST_METHOD_GET,
	'/cob/{tid}'
);

Após a configuração dos endpoints, chame o método oAuth() para obter o token de acesso. O token de acesso será salvo na memória e, quando expirado será atualizado automaticamente. Veja abaixo:

// Obtem o token de acesso
$bradesco->oAuth(
	BaseApi::REQUEST_METHOD_POST,
	'/auth/server/oauth/token',
	CLIENT_ID,
	CLIENT_SECRET
);

Por fim, realize as chamadas aos endpoints para receber as respostas do SPI:

// Crie um payload para a cobrança implementando CobPayloadInterface
$cob = new BradescoCobPayload();
// Crie os dados do $cob
// Envie o $cob e receba os novos dados
$cob = $bradesco->createCob($cob);

Para padronizar a comunicação com a API foram criadas duas interfaces, são elas:

• CobPayloadInterface utilizado para payloads de cobranças, que registra os métodos que um CobPayload deve ter;
• DevoPayloadInterface utilizado para payloads de devoluções, que registra os métodos que um DevoPayload deve ter;

A classe BradescoCobPayload, por exemplo, implementa CobPayloadInterface.

Classe CobPayload

Fizemos uma classe de exemplo que segue todos os padrões da API Pix definida pelo Banco Central do Brasil. O objetivo desta classe é auxiliar as padronizações dos corpos (payloads) enviados e recebidos pela API Pix. A nossa estrutura de exemplo é apenas uma sugestão, você pode utilizar a lógica que você quiser para criar o CobPayload compatível com sua API Pix, entretanto é obrigatório que a classe implemente CobPayloadInterface, assim a classe BaseApi lidará com os envios e as respostas de acordo.

Além dos métodos para obter/setar dados do CobPayload, haverão dois métodos disponíveis sendo eles:

• export(): exporta todos os dados da classe CobPayload para o array compatível com a API Pix;
• import(): importa todos os dados de resposta da API Pix para os objetos relacionados criando um CobPayload organizado.

O CobPayload e as classes derivadas disponíveis em Entities/Cob/* são bem flexíveis e fazem a importação/exportação de todos os dados disponíveis conforme os modelos padrões da API Pix, não há muito com o que se preocupar. Mas recomendamos que você crie o CobPayload compatível com a API na qual está realizando a conexão.

Exemplo

// Não implementamos ainda uma classe $api
$cobResponse = $api->getCob($tid);

// Cria o cob para normalizar os dados
$cob = (new CobPayload())->import($cobResponse);

// Nome do recebedor do Pix
$cob->getSender()->getName();
// Nome do devedor do Pix
$cob->getRecipient()->getName();
// Valor original do Pix
$cob->getAmount()->getOriginalAmount();
// Status da cobrança do Pix
$cob->getStatus();
// -> exemplos de dados

// Você também pode criar o seu cob e enviar via $api
$devedor = (new Entities\Cob\Person())->setDocument('12345678930');
$recebedor = (new Entities\Cob\Person())->setDocument('11222333000100');
$valor = (new Entities\Cob\Amount())->setOriginalAmount('1.00');
$calendario = (new Entities\Cob\Calendar())->setDueDate(DateTime::now()->add(new DateInterval('P10D')));

$cob = (new CobPayload())
	->setSender($recebedor)
	->setRecipient($devedor)
	->setAmount($valor)
	->setCalendar($calendario);

// Não implementamos ainda uma classe $api
// Envie o payload do cob
$cobResponse = $api->createCob($cob->export());

// Capture a resposta
$cob = (new CobPayload())->import($cobResponse);