README

Vamos transformar o Brasil em uma API?

Introdução

Esse SDK foi construído com o intuito de ser flexível, de forma que todos possam utilizar todas as features e versões da BrasilAPI.

Você pode acessar a documentação oficial da BrasilAPI acessando esse link.

Índice

Introdução
- Índice
- Requisitos
- Instalação
- Utilização
- Endpoints
  - Bancos
  - CEP
  - CEP V2
  - CNPJ
  - CPTEC
  - DDD
  - Feriados
  - FIPE
  - IBGE
  - ISBN
  - NCM
  - Pix
  - Registro BR
  - Taxas
- Criando endpoints
- Tratando exceções
- Licença

Requisitos

PHP versão 7.4 ou maior;
Guzzle Http versão 7.4 ou maior.

Instalação

Para instalar o SDK, você deve utilizar o Composer com o seguinte comando:

composer require kseven/brasilapi-php

Utilização

O uso mais simples da biblioteca seria o seguinte:

<?php

require __DIR__ . '/vendor/autoload.php';

use BrasilApi\Client;

$brasilApi = new Client();

$address = $brasilApi->cep()->get('01001000');

Endpoints

Abaixo você pode ver todos os endpoints disponíveis, por padrão, na biblioteca:

Bancos

Buscando todos os bancos disponíveis na API.

$brasilApi->banks()->getList();

Buscando um banco específico pelo seu código.

$brasilApi->banks()->get(1);

CEP

Buscando um CEP específico.

$brasilApi->cep()->get('01001000');

CEP V2

Buscando um CEP específico.

$brasilApi->cepV2()->get('01001000');

CNPJ

Buscando um CNPJ específico.

$brasilApi->cnpj()->get('00000000000191');

CPTEC

Buscando uma cidade pelo nome.

$brasilApi->cptec()->cities('São Paulo');

Buscando todas as cidades disponíveis.

$brasilApi->cptec()->cities();

Buscando as informações meteorológicas em todas as capitais dos estados brasileiros.

$brasilApi->cptec()->weatherInCapitals();

Buscando as informações meteorológicas em um aeroporto específico através do seu código ICAO.

$brasilApi->cptec()->weatherInAirport('SBGR');

Buscando as informações meteorológicas de uma cidade específica pelo seu código.

$brasilApi->cptec()->weatherInCity(999);

Buscando as informações meteorológicas de uma cidade específica no período de X dias.

Obs.: O primeiro parâmetro se refere ao código da cidade e o segundo parâmetro refere-se a quantidade de dias. Lembrando que só é possível buscar informações entre 1 a 6 dias.

$brasilApi->cptec()->weatherInCityInXDays(999, 6);

Buscando a previsão oceânica em uma cidade específica.

$brasilApi->cptec()->oceanForecastInCity(999);

Buscando a previsão oceânica em uma cidade específica no período de X dias.

Obs.: O primeiro parâmetro se refere ao código da cidade e o segundo parâmetro refere-se a quantidade de dias. Lembrando que só é possível buscar informações entre 1 a 6 dias.

$brasilApi->cptec()->oceanForecastInCityInXDays(999, 6);

DDD

Buscando o estado e cidades que possuem determinado DDD.

$brasilApi->ddd()->get(77);

Feriados

Buscando todos os feriados nacionais em determinado ano.

$brasilApi->holidays()->fromYear(2022);

FIPE

Buscando todas as marcas de veículos referente a um tipo de veículo.

$brasilApi->fipe()->brandsByTypeVehicle('caminhoes');

Buscando o preço de um veículo específico pelo seu código FIPE.

$brasilApi->fipe()->price('001004-9');

Buscando as tabelas de referência existentes.

$brasilApi->fipe()->referenceTables();

IBGE

Buscando todos os municípios de um estado específico pela sua sigla.

$brasilApi->ibge()->stateCities('BA');

Buscando informações de todos os estados brasileiros.

$brasilApi->ibge()->states();

Buscando informações de um estado específico pela sua sigla.

$brasilApi->ibge()->state('BA');

ISBN

Buscando informações sobre um livro específico pelo seu código ISBN.

$brasilApi->isbn()->book('9788545702870');

NCM

Buscando informações sobre todos os NCMs.

$brasilApi->ncm()->getList();

Buscando informações sobre um NCM específico.

$brasilApi->ncm()->get('01012100');

Buscando informações de um NCM a partir de um código ou descrição.

$brasilApi->ncm()->search('01012100');

Pix

Buscando informações de todos os participantes do PIX no dia atual ou anterior.

$brasilApi->pix()->participants();

Registro BR

Buscando informações de um domínio específico.

$brasilApi->registerBr()->domain('google.com');

Taxas

Buscando as taxas de juros e alguns índices oficiais do Brasil.

$brasilApi->taxes()->getList();

Buscando informações de uma taxa a partir do seu nome/sigla.

$brasilApi->taxes()->get('Selic');

Criando endpoints

Para adicionar novos ou sobreescrever os já existentes endpoints, você deve seguir os seguintes passos:

Crie uma classe que extenda a classe BrasilApi\Endpoints\Abstracts\Endpoint;
Nesta classe, você pode implementar todos os métodos que desejar e utilizar o método $this->client->request() para enviar as requisições para a API. Lembre-se que a base URL da API já está embutido no 'Client', portanto na uri do método você precisa adicionar apenas o complemento da rota.

Exemplo:

URL: https://brasilapi.com.br/api/cep/v2/01001000
BASE_URI: https://brasilapi.com.br/api
URI: /cep/v2/01001000

Para incorporá-lo ao SDK, você deve possuir uma instância de BrasilApi\Client e utilizar o método addEndpoint, passando como parâmetro o nome do endpoint e a classe criada no passo 1.

Exemplo:

<?php

require __DIR__ . '/vendor/autoload.php';

use BrasilApi\Client;
use BrasilApi\Endpoints\Abstracts\Endpoint;

class Hope extends Endpoint
{
    public function getList(): array
    {
        return $this->client->request("/hopes/list");
    }
}

$brasilApi = new Client();

$brasilApi->addEndpoint("hope", Hope::class);

Para utilizar este novo endpoint, você deve chamá-lo da seguinte forma:

$address = $brasilApi->hope()->getList();

Obs.: A chamada do método do endpoint deve ser feito com o mesmo nome que foi definido no método addEndpoint, pois ele será utilizado na busca dinâmica do endpoint através do método mágico __call.

Obs.2: Além de criar, você pode sobrescrever endpoints existentes e atualizar os seus métodos. Isso pode ser útil caso seja lançada uma nova versão de algum endpoint e você queira utilizá-lo imediatamente. Dessa forma, você pode sobrescrever o endpoint existente e alterar a sua URI.

Tratando exceções

Caso a API retorne um erro, a biblioteca irá lançar uma exceção do tipo BrasilApi\Exceptions\BrasilApiException. Para capturar esta exceção, você deve utilizar o bloco try/catch e tratar o erro da forma que desejar.