README

Pacote responsável por gerar boletos com opção PIX via API do Santander

Índice

🚀 Começando
- 1.1. 📋 Pré-requisitos
- 1.2. 🔧 Instalação
Variáveis de ambiente(Opcional)
Instanciar classe Santander
- 3.1. Usando configuração padrão (do arquivo de configuração)
- 3.2. Usando configuração personalizada(opcional)
Endpoints de API

🚀 Começando

Essas instruções permitirão que você obtenha uma cópia do projeto em operação na sua máquina local para fins de desenvolvimento e teste.

1.1. ### 📋 Pré-requisitos
- PHP ˆ7.2
- Laravel ˆ6.0
- Composer
1.2. ### 🔧 Instalação

Use o gerenciador de pacotes COMPOSER para incluir as dependéncias ao seu projeto.

Comando a executar:
```
composer require flycorp/santander-billet
```
Ou, em seu composer.json adicione:
```
{
    "require": {
        "flycorp/santander-billet": "dev-main"
    }
}
```
Em seguida, execute o comando de instalação do gerenciador de pacotes:
```
composer install
```
Em seguida, publique o arquivo de configuração do pacote em config\santander_billet.php:
```
php artisan vendor:publish --provider="FlyCorp\SantanderBillet\providers\SantanderBilletServiceProvider" --tag=config
```
Lembre-se de realizar a importação das classes quando for utilizar o pacote:
```
#Classe principal para executar chamadas de api
use FlyCorp\SantanderBillet\Santander;
#Classe utilizada exclusivamente na parametrização do boleto
use FlyCorp\SantanderBillet\Billet;
```
Variáveis de ambiente(Opcional)

Adicione ao seu arquivo .env as variáveis de ambiente que possibilitarão a comunicação com o respectivo endpoint de API:
```
SANTANDER_BILLET_ENVIRONMENT="sandbox"
SANTANDER_BILLET_CLIENT_ID=
SANTANDER_BILLET_CLIENT_SECRET=
SANTANDER_BILLET_CERTIFICATE_AUTH=
SANTANDER_BILLET_CERTIFICATE_PATH=
```
Descrição das variáveis:
- SANTANDER_BILLET_ENVIRONMENT: Ambiente da API(sandbox ou production)
- SANTANDER_BILLET_CLIENT_ID: Valor do client_id fornecido pelo Santader
- SANTANDER_BILLET_CLIENT_SECRET: Valor do client_secret fornecido pelo Santander
- SANTANDER_BILLET_CERTIFICATE_AUTH: Senha do certificado
- SANTANDER_BILLET_CERTIFICATE_PATH: Caminho do certificado em formato pfx/pem dentro da pasta Storage

Instanciar classe Santander

3.1. ### Usando configuração padrão (do arquivo de configuração)

use FlyCorp\SantanderBillet\Santander;

$santanderDefault = new Santander();

3.2. ### Usando configuração personalizada(opcional)

3.2.1. Utilizando certificado PFX

use FlyCorp\SantanderBillet\Santander;

$customConfig = [
    'host' => '[https://api-sandbox.santander.com.br](https://api-sandbox.santander.com.br)',
    'certificate_path' => 'santander/certs/arquivo.pfx',
    'certificate_auth' => 'senha123',
    'client_id' => 'meu-client-id',
    'client_secret' => 'meu-client-secret'
];
$santanderCustom = new Santander($customConfig);

3.2.2. Utilizando certificado PEM

use FlyCorp\SantanderBillet\Santander;

$customConfig = [
    'host' => '[https://api-sandbox.santander.com.br](https://api-sandbox.santander.com.br)',
    'certificate_path' => 'santander/certs/arquivo.pem',
    'certificate_auth' => 'santander/certs/keyfile',
    'client_id' => 'meu-client-id',
    'client_secret' => 'meu-client-secret'
];
$santanderCustom = new Santander($customConfig);

Endpoints de API

4.1. ### Workspace:

4.1.1. [POST] Criar workspace /collection_bill_management/v2/workspaces:

$santanderIntegration = new Santander;

$workspace = [
    "type" => "BILLING",
    "covenants" => [
        [
            "code" => 0000001
        ]
    ],
    "description" => "Testando",
    "bankSlipBillingWebhookActive" => true,
    "pixBillingWebhookActive" => true,
    "webhookURL" => "https://teste"
];

$data = $santanderIntegration->createWorkspace($workspace);

4.1.2. [GET] Consultar workspace /collection_bill_management/v2/workspaces:

$santanderIntegration = new Santander;

$data = $santanderIntegration->searchWorkspace(); #INFORME O ID DO WORKSPACE PARA PESQUISA ESPECÍFICA

4.1.3. [DELETE] Deletar workspace /collection_bill_management/v2/workspaces/{workspace_id}:

$santanderIntegration = new Santander;

$data = $santanderIntegration->deleteWorkspace("5ca21612-ee50-4626-b2da-e66ca35c605f");

4.1.4. [PATCH] Alterar workspace /collection_bill_management/v2/workspaces/{workspace_id}:

$santanderIntegration = new Santander;

$body = [
    "covenants" => [
        [
            "code" => 0000001
        ]
    ],
    "description" => "Testando"
];

#Forneça o workspace_id e body da requisição
$data = $santanderIntegration->updateWorkspace("5ca21612-ee50-4626-b2da-e66ca35c605f", $body);

4.2. ### Boletos:

4.2.1. [POST] Registrar boleto /collection_bill_management/v2/workspaces/{workspace_id}/bank_slips:

4.2.1.1 Configurando boleto como array:

$billet = new Billet();
$santanderIntegration = new Santander;

$billet = [
    "environment" => "sandbox",
    "workspaceId"=> 201,
    "nsuCode" => 1014,
    "nsuDate" => "2023-05-09",
    "covenantCode" => '0000001',
    "bankNumber" => "1014",
    "clientNumber" => "123",
    "dueDate" => "2023-05-09",
    "issueDate" => "2023-05-09",
    "participantCode" => "teste liq abat",
    "nominalValue" => number_format(1.00, 2, '.', ''),
    "payer" => [
        "name" => "Fulano",
        "documentType" => "CPF",
        "documentNumber" => "94620639079",
        "address" => "rua nove de janeiro",
        "neighborhood" => "bela vista",
        "city" => "sao paulo",
        "state" => "SP",
        "zipCode" => "05134-897"
    ],
    "beneficiary" => [
        "name" => "Ciclano",
        "documentType" => "CNPJ",
        "documentNumber" => "20201210000155",
    ],
    "documentKind" => "DUPLICATA_MERCANTIL",
    "deductionValue" => "0.10",
    "paymentType" => "REGISTRO",
    "key" => [
        "type" => "CNPJ",
        "dictKey" => "00000000000000"
    ],
    "writeOffQuantityDays" => "30",
    "messages" => [
        "mensagem um",
        "mensagem dois"
    ]
];

#Forneça o workspace_id e body da requisição
$data = $santanderIntegration->registerBill('5ca21612-ee50-4626-b2da-e66ca35c605f', $billet);

4.2.1.2 Configurando boleto como objeto:

$billet = new Billet();
$santanderIntegration = new Santander;

$billet->setEnvironment("sandbox")# Valores aceitos(sandbox, PRODUCAO)
    ->setNsuCode(1014)
    ->setNsuDate("2023-05-09")
    ->setCovenantCode("0000001")#INFORME O SEU
    ->setBankNumber("1014")#INFORME O SEU
    ->setClientNumber("123")
    ->setDueDate("2023-05-09")
    ->setIssueDate("2023-05-09")
    ->setParticipantCode("teste liq abat")
    ->setNominalValue(1.00)
    ->payer()
        ->setName("Fulano")
        ->setDocumentType("CPF")
        ->setDocumentNumber("94620639079")
        ->setAddress("rua nove de janeiro")
        ->setNeighborhood("bela vista")
        ->setCity("sao paulo")
        ->setState("SP")
        ->setZipCode("05134-897")
    ->beneficiary()
        ->setName("Ciclano")
        ->setDocumentType("CNPJ")
        ->setDocumentNumber("20201210000155")
    ->setDocumentKind("DUPLICATA_MERCANTIL")
    ->setDeductionValue(0.10)
    ->setPaymentType("REGISTRO")
    ->key()#ESTA CHAVE É NECESSÁRIA PARA GERAR O QR-CODE
        ->setType("CNPJ")#TIPOS ACEITOS (CPF, CNPJ, CELULAR, EMAIL, EVP)
        ->setDictKey("00000000000000")#CNPJ SEM MÁSCARA
    ->setWriteOffQuantityDays("30")
    ->setMessages(["mensagem um", "mensagem dois"]);

#Forneça o workspace_id e body da requisição
$data = $santanderIntegration->registerBill('5ca21612-ee50-4626-b2da-e66ca35c605f', $billet->toArray());

4.2.2. [PATCH] Atualizar instruções /collection_bill_management/v2/workspaces/{workspace_id}/bank_slips:

$santanderIntegration = new Santander;

$body = [
    "covenantCode" => "0000001",
    "bankNumber" => "123",
    "operation" => "BAIXAR"
];

#Forneça o workspace_id e body da requisição
$data = $santanderIntegration->updateBillInstructions("5ca21612-ee50-4626-b2da-e66ca35c605f", $body);

4.2.3. [POST] Obter dados para acessar boleto(PDF/QR-code) /collection_bill_management/v2/bills/{$billId}/bank_slips:

$santanderIntegration = new Santander;

$billId = "0000001.1005";

$body = [
    "payerDocumentNumber" => "94620639079",
];

#Forneça o bill_id e body da requisição
$data = $santanderIntegration->getPdfBill($billId, $body);

4.3. ### Consulta simples:

4.3.1. [GET] Consulta sonda /collection_bill_management/v2/workspaces/{workspace_id}/bank_slips/{bank_slips}:

$santanderIntegration = new Santander;

$data = $santanderIntegration->simpleSearchBySonda();

4.3.2. [GET] Consulta nn /collection_bill_management/v2/bills:

$santanderIntegration = new Santander;

$beneficiaryCode = "356720"; #CÓDIGO DO BENEFICIÁRIO
$bankNumber = "10054325"; #CÓDIGO DO BANCO

$data = $santanderIntegration->detailedSearchByNn($beneficiaryCode, $bankNumber);

4.3.3. [GET] Consulta sn /collection_bill_management/v2/bills:

$santanderIntegration = new Santander;

$beneficiaryCode = "356720"; #CÓDIGO DO BENEFICIÁRIO
$bankNumber = "10054325"; #CÓDIGO DO BANCO
$dueDate = "2023-04-25";
$nominalValue = "100.00";

$data = $santanderIntegration->detailedSearchBySn($beneficiaryCode, $bankNumber, $dueDate, $nominalValue);

4.3.4. [GET] Consulta sn /collection_bill_management/v2/bills:

$santanderIntegration = new Santander;

$beneficiaryCode = "356720"; #CÓDIGO DO BENEFICIÁRIO
$bankNumber = "10054325"; #CÓDIGO DO BANCO
$dueDate = "2023-04-25"; #DATA DE VENCIMENTO
$nominalValue = "100.00";#VALOR NOMINAL

$data = $santanderIntegration->detailedSearchBySn($beneficiaryCode, $bankNumber, $dueDate, $nominalValue);

4.3.5. [GET] Pesquisa por tipo /collection_bill_management/v2/bills:

$santanderIntegration = new Santander;

$billId = "0000001.1005";

#Valores para type (bankslips, default, duplicate, registry, settlement)
#A. default: Pesquisa padrão, trazendo somente dados básicos do boleto
#B. duplicate: Pesquisa de dados para emissão de segunda via de boleto
#C. bankslip: Pesquisa para dados completos do boleto
#D. setlement: Pesquisa para informações de baixas/liquidações do boleto
#E. registry: Pesquisa de informações de cartório no boleto
$data = $santanderIntegration->detailedSearchBySearchType($billId, $type);

flycorp / santander-billet

Maintainers

Details

README

Índice

🚀 Começando

Variáveis de ambiente(Opcional)

Instanciar classe Santander

Endpoints de API