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.

• Introdu��o
  • �ndice
  • Requisitos
  • Instala��o
  • Utiliza��o
  • Endpoints
    • Bancos
    • CEP
    • CEP V2
    • CNPJ
    • Corretoras
    • CPTEC
    • DDD
    • Feriados
    • FIPE
    • IBGE
    • ISBN
    • NCM
    • Pix
    • Registro BR
    • Taxas
  • Criando endpoints
  • Tratando exce��es
  • Testes
  • Contribuindo
  • Licen�a

• PHP vers�o 8.1 ou maior;
• Guzzle Http vers�o 7.4 ou maior.

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

composer require andreoneres/brasilapi-php

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');

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

Buscando todos os bancos dispon�veis na API.

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

Buscando um banco espec�fico pelo seu c�digo.

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

Buscando um CEP espec�fico.

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

Buscando um CEP espec�fico.

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

Buscando um CNPJ espec�fico.

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

Buscando uma corretora espec�fica pelo CNPJ.

$brasilApi->realtors()->get('76621457000185');

Buscando todas as corretoras listadas pela CVM.

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

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);

Buscando o estado e cidades que possuem determinado DDD.

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

Buscando todos os feriados nacionais em determinado ano.

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

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();

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');

Buscando informa��es sobre um livro espec�fico pelo seu c�digo ISBN.

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

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');

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

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

Buscando informa��es de um dom�nio espec�fico.

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

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');

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

1. Crie uma classe que extenda a classe BrasilApi\Endpoints\Abstracts\Endpoint;

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

3. 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);

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

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.

Exemplo:

try {
    $address = $brasilApi->cep()->get('01001000');
} catch (BrasilApiException $e) {
    echo $e->getMessage(); // Retorna a mensagem de erro da API
    echo $e->getCode(); // Retorna o c�digo HTTP da API
    echo $e->getErrors(); // Retorna os erros retornados pela API
    echo $e->getRawResponse(); // Retorna a resposta bruta da API
}

Neste projeto � utilizado o Pest para a implementa��o de testes automatizados. Para execut�-los, instale as depend�ncias de desenvolvimento, caso n�o tenha instalado, e execute o seguinte comando:

composer test

Para contribuir com o projeto, voc� deve seguir os seguintes passos:

1. Fa�a um fork do projeto;
2. Crie uma branch para sua altera��o: git checkout -b feat-fix-refactor/my-changes;
3. Fa�a commit das suas altera��es: git commit -m 'feat-fix-refactor: My changes';
4. Fa�a push para a sua branch: git push origin feat-fix-refactor/my-changes;
5. Abra um pull request.
6. Aguarde a an�lise do seu pull request.
7. Se seu pull request for aceito, ele ser� mesclado com a branch main.

Obs.: N�o se esque�a de criar testes para o seu c�digo.

Veja em LICENSE.md.