Documentation

MonthlyService extends BaseService
in package

Classe responsável por gerar a guia de mensal de todos empregados.

Esta classe recebe os dados, faz as validações necessárias. Captura os dados da empresa ortogada. Captura os dados do empregado. Gera a guia mensal.

Tags
example 
use App\Services\MonthlyService;

$service = MonthlyService();
$service->companyCnpj('12345678901234');
$service->customerCnpj('12345678901234');
$service->competency('MM/YYYY');
$service->generate();

Table of Contents

Properties

$api  : mixed
Este atributo mantém a instância da classe Api, que é utilizada para realizar chamadas à API externa.
$companyCnpj  : string|null
Este atributo armazena o CNPJ da empresa, informado na invocação do serviço.
$competency  : string|null
Este atributo armazena a data de competência.
$customerCnpj  : string|null
Este atributo armazena o CNPJ da cliente, informado na invocação do serviço.
$employer  : array<string|int, mixed>|null
Este atributo armazena os dados relacionados à empresa, como nome, CNPJ e entre outros.
$invoiceId  : string|null
Este atributo armazena o ID da guia.
$paymentInvoicePdfUrl  : string|null
Este atributo armazena a URL do PDF da guia de pagamento.
$uuid  : string|null
Este atributo armazena o UUID para contexto de logs.
$allowMonthly  : bool
Este atributo armazena um booleano que indica se a geração da guia mensal está permitida.
$allowTermination  : bool
Este atributo armazena um booleano que indica se a geração da guia de rescisão está permitida.
$employeesGroupingRecord  : array<string|int, mixed>|null
Este atributo armazena os dados relacionados aos débitos, como valores, datas e entre outros.

Methods

companyCnpj()  : self
Define o CNPJ da empresa.
competency()  : self
Define o mês e ano de competência para a instância da classe.
customerCnpj()  : self
Define o CNPJ do cliente.
generate()  : mixed
Método abstrato para geração da guia
createApiWithCnpj()  : MonthlyApi|TerminationApi
downloadInvoice()  : mixed
Faz o download de uma fatura a partir da URL informada.
getApiClass()  : string
Classe da API específica (deve ser definida nas classes filhas)
getDetailedInvoiceById()  : string|array<string|int, mixed>|null
Busca a guia de detalhamento pelo ID da guia.
getUuid()  : string
Gera um UUID aleatório no formato padrão.
returnError()  : string
sanitizeCompetency()  : string
Sanitiza a competência recebida, ajustando-a para o formato exigido pela API.
setEmployer()  : self
Define os dados do empregador.
validateRequiredFields()  : void
Valida os campos obrigatórios da rescisão.
encodeAndReturnInvoices()  : string
Codifica o conteúdo dos PDFs das faturas detalhada e de pagamento em base64, e retorna uma string JSON contendo o nome, CNPJ, guia detalhada e guia de pagamento.
generateSingleInvoice()  : array<string|int, mixed>
getAndValidateCompetencies()  : array<string|int, mixed>
Recupera e valida as competências disponíveis.
getYearFromCompetency()  : string
Extrai o ano da competência.
isDecember()  : bool
Verifica se a competência é dezembro e se precisa gerar também o 13º.
normalizeCompetency()  : string
Normaliza a competência para o formato MM/YYYY, removendo caracteres inválidos.

Properties

$api

Este atributo mantém a instância da classe Api, que é utilizada para realizar chamadas à API externa.

protected mixed $api = null

$companyCnpj

Este atributo armazena o CNPJ da empresa, informado na invocação do serviço.

protected string|null $companyCnpj = null

$competency

Este atributo armazena a data de competência.

protected string|null $competency = null

$customerCnpj

Este atributo armazena o CNPJ da cliente, informado na invocação do serviço.

protected string|null $customerCnpj = null

$employer

Este atributo armazena os dados relacionados à empresa, como nome, CNPJ e entre outros.

protected array<string|int, mixed>|null $employer = null

$invoiceId

Este atributo armazena o ID da guia.

protected string|null $invoiceId = null

$paymentInvoicePdfUrl

Este atributo armazena a URL do PDF da guia de pagamento.

protected string|null $paymentInvoicePdfUrl = null

$uuid

Este atributo armazena o UUID para contexto de logs.

protected string|null $uuid = null

$allowMonthly

Este atributo armazena um booleano que indica se a geração da guia mensal está permitida.

private bool $allowMonthly = true

$allowTermination

Este atributo armazena um booleano que indica se a geração da guia de rescisão está permitida.

private bool $allowTermination = false

$employeesGroupingRecord

Este atributo armazena os dados relacionados aos débitos, como valores, datas e entre outros.

private array<string|int, mixed>|null $employeesGroupingRecord = null

Methods

companyCnpj()

Define o CNPJ da empresa.

public companyCnpj(string $cnpj) : self

Este método recebe o CNPJ da empresa e o formata, além de criar a instância da classe Api.

Parameters
$cnpj : string

O CNPJ da empresa.

Return values
self —

A própria instância da classe.

competency()

Define o mês e ano de competência para a instância da classe.

public competency(string $competency) : self

O parâmetro deve ser informado no formato "mes/ano", por exemplo "04/2025". O valor informado será sanitizado pelo método sanitizeCompetency para se adequar ao padrão exigido pela API.

Parameters
$competency : string

Mês e ano de competência no formato "mes/ano".

Return values
self —

Retorna a própria instância para permitir encadeamento de métodos.

customerCnpj()

Define o CNPJ do cliente.

public customerCnpj(string $cnpj) : self

Este método recebe o CNPJ do cliente e o formata. Além disso, ao definir o CNPJ do cliente, a instância da classe Api é (re)criada utilizando o CNPJ da empresa e o CNPJ do cliente.

Parameters
$cnpj : string

O CNPJ do cliente.

Return values
self —

A própria instância da classe.

generate()

Método abstrato para geração da guia

public generate() : mixed

createApiWithCnpj()

protected createApiWithCnpj(string $companyCnpj, string $customerCnpj) : MonthlyApi|TerminationApi
Parameters
$companyCnpj : string

O CNPJ da empresa.

$customerCnpj : string

O CNPJ do cliente utilizado em conjunto com o CNPJ da empresa.

Return values
MonthlyApi|TerminationApi —

A instância da classe Api configurada com o cookie de sessão.

downloadInvoice()

Faz o download de uma fatura a partir da URL informada.

protected downloadInvoice(string $invoiceUrl) : mixed
Parameters
$invoiceUrl : string

URL da fatura a ser baixada.

Return values
mixed —

Conteúdo da fatura detalhada obtida pelo download.

getApiClass()

Classe da API específica (deve ser definida nas classes filhas)

protected getApiClass() : string
Return values
string

getDetailedInvoiceById()

Busca a guia de detalhamento pelo ID da guia.

protected getDetailedInvoiceById(mixed $invoiceId) : string|array<string|int, mixed>|null

Caso a guia detalhada seja encontrada, retorna o conteúdo do arquivo através da URL. Se não for possível gerar ou encontrar a guia detalhada, lança uma exceção.

Parameters
$invoiceId : mixed

ID da guia para busca do detalhamento.

Tags
throws
DataNotFoundException

Caso não seja possível gerar ou encontrar a guia detalhada.

Return values
string|array<string|int, mixed>|null —

Conteúdo do arquivo detalhado ou nulo.

getUuid()

Gera um UUID aleatório no formato padrão.

protected getUuid() : string

Este método é utilizado apenas para cumprir um requisito da API, que exige o envio de uma string UUID em algumas requisições. O UUID gerado não possui relação com outros dados do sistema.

Return values
string —

UUID gerado aleatoriamente.

returnError()

protected returnError(int $code, string $message) : string
Parameters
$code : int
$message : string
Return values
string

sanitizeCompetency()

Sanitiza a competência recebida, ajustando-a para o formato exigido pela API.

protected sanitizeCompetency(string $competency) : string

Este método recebe uma string representando a competência no formato 'mes/ano', valida e converte para o formato 'ano + mes' utilizado pela API. Trata casos especiais como 13º salário (décimo terceiro).

Parameters
$competency : string

Data de competência no formato 'MM/YYYY'.

Tags
throws
InvalidArgumentException

Se a competência estiver em formato inválido.

Return values
string —

Competência ajustada no formato 'YYYYMM' ou '13YYYY' para décimo terceiro.

setEmployer()

Define os dados do empregador.

protected setEmployer(array<string|int, mixed> $employer) : self

Recebe um array com os dados do empregador e atribui ao atributo da classe.

Parameters
$employer : array<string|int, mixed>

Array contendo os dados do empregador.

Return values
self

validateRequiredFields()

Valida os campos obrigatórios da rescisão.

protected validateRequiredFields() : void

Esta função verifica se os parâmetros essenciais para o processamento da rescisão estão preenchidos. Caso algum dos campos obrigatórios esteja ausente, uma exceção InvalidArgumentException será lançada informando qual parâmetro está faltando e, quando aplicável, o formato esperado.

Campos validados:

  • tag: Gera o valor caso esteja ausente.
  • cpf: Obrigatório, não pode estar vazio.
  • amount: Valor total obrigatório, não pode estar vazio.
  • competency: Competência obrigatória, formato esperado MM/YYYY.
  • payment: Data de pagamento obrigatória, formatos aceitos d/m/Y, d-m-Y ou Y-m-d.
Tags
throws
InvalidArgumentException

Se algum campo obrigatório não for informado ou estiver vazio.

encodeAndReturnInvoices()

Codifica o conteúdo dos PDFs das faturas detalhada e de pagamento em base64, e retorna uma string JSON contendo o nome, CNPJ, guia detalhada e guia de pagamento.

private encodeAndReturnInvoices(string $detailedInvoicePdfContent, string $paymentInvoicePdfContent) : string
Parameters
$detailedInvoicePdfContent : string

Conteúdo do PDF da fatura detalhada.

$paymentInvoicePdfContent : string

Conteúdo do PDF da fatura de pagamento.

Return values
string —

JSON com os dados codificados das faturas.

generateSingleInvoice()

private generateSingleInvoice(string $competency) : array<string|int, mixed>
Parameters
$competency : string
Return values
array<string|int, mixed>

getAndValidateCompetencies()

Recupera e valida as competências disponíveis.

private getAndValidateCompetencies() : array<string|int, mixed>
Tags
throws
DataNotFoundException

Se não houver débitos de interesse ou se a competência não for encontrada.

Return values
array<string|int, mixed> —

As competências disponíveis.

getYearFromCompetency()

Extrai o ano da competência.

private getYearFromCompetency(string $competency) : string
Parameters
$competency : string

Competência no formato YYYYMM

Return values
string —

O ano extraído

isDecember()

Verifica se a competência é dezembro e se precisa gerar também o 13º.

private isDecember(string $competency) : bool
Parameters
$competency : string

Competência no formato YYYYMM

Return values
bool —

True se for dezembro

normalizeCompetency()

Normaliza a competência para o formato MM/YYYY, removendo caracteres inválidos.

private normalizeCompetency(string $competency) : string
Parameters
$competency : string

A competência a ser normalizada.

Return values
string —

A competência normalizada no formato MM/YYYY.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results