[Melhoria] DP: API de Funcionários – Campo Matriz de Rateio

Agora no Bluesoft ERP, é possível consultar e atualizar a Matriz de Rateio vinculada aos funcionários diretamente pelas rotas públicas da API de integração.

Objetivo

O objetivo desta melhoria é igualar as funcionalidades entre o cadastro realizado diretamente no sistema e as operações de API, permitindo que sistemas externos consigam manter os dados de rateio dos funcionários completamente atualizados e equivalentes ao ERP.

O Que Mudou?

Como Era o Processo Antes?

Antes, o cadastro de funcionários pela interface visual do ERP já permitia vincular uma Matriz de Rateio. No entanto, essa informação não estava disponível no contrato atual da API (/api/dp/funcionarios).

Como Irá Funcionar a Partir de Agora?

Agora, a API foi expandida e o atributo correspondente foi incluído nos payloads. O benefício direto é a autonomia total para gerenciar o rateio dos funcionários via integração, eliminando processos manuais no ERP.

A operação foi disponibilizada nos três fluxos principais da API de funcionários (/api/dp/funcionarios):

1. Consulta (GET): Ao consultar funcionários, a resposta passará a exibir o campo matrizRateioKey com o identificador da Matriz de Rateio efetivamente vinculada. Caso o funcionário não possua matriz, o campo retornará null.
2. Inclusão e Alteração (POST e PUT): As rotas de escrita passam a receber o atributo opcional matrizRateioKey (como número inteiro ou nulo) para vincular, substituir ou remover a matriz. O sistema aceitará como novo vínculo apenas matrizes que já existam, que estejam ativas e que sejam do tipo “Funcionário”.
3. Preservação de Dados: Se a requisição de alteração for enviada com o atributo matrizRateioKey ausente (não incluído no payload), o sistema preservará a Matriz de Rateio atual que já está salva no funcionário.
4. Remoção de Vínculo: Para remover uma Matriz de Rateio existente do funcionário através da integração, basta enviar o campo matrizRateioKey com o valor null no payload.

Observações / Validações

• Exclusividade Sistêmica: O sistema mantém a regra rígida de que o funcionário pode possuir um Centro de Resultado OU uma Matriz de Rateio, mas não os dois simultaneamente.
• Bloqueio de Simultaneidade: O sistema recusará automaticamente qualquer operação de escrita (POST ou PUT) em que uma Matriz de Rateio e um Centro de Resultado sejam informados no mesmo envio.
• Troca de Vínculos: Se o funcionário já possui uma Matriz de Rateio e a integração precisa alterá-lo para um Centro de Resultado, é obrigatório enviar o campo matrizRateioKey como null junto com os dados do novo centro, sinalizando a troca explícita.
• Controle de Acesso: Não há novas permissões. Foram mantidas as mesmas permissões atuais (36 para Consultar, 47 para Incluir e 58 para Alterar).

Exemplo de JSON da Requisição POST:

{
    "nomeRazao": "FUNCIONARIO EXEMPLO",
    "nomeFantasia": "FUNCIONARIO EXEMPLO",
    "cpfCnpj": "52*******25",
    "nomeAbreviado": "FUNCIONARIO EXEMPLO",
    "dataCadastro": "03/09/2026 10:00",
    "ultimaAlteracao": "03/09/2026 10:00",
    "contatos": [
        {
            "tipoContato": "EMAIL_COMERCIAL",
            "valor": "funcionario.exemplo@example.com"
        }
    ],
    "enderecos": [
        {
            "rua": "Rua Exemplo",
            "numero": "100",
            "cep": "04089-010",
            "cidade": "São Paulo",
            "uf": "SP",
            "bairro": "Centro",
            "complemento": "Conjunto 10",
            "tipoDeEndereco": "FATURAMENTO",
            "pais": "BRASIL",
            "codigoDoMunicipioNoIBGE": "3550308"
        }
    ],
    "inscricaoEstadual": "ISENTA",
    "tipo": "FISICA",
    "sexo": "F",
    "estadoCivil": "SOLTEIRO",
    "dataNascimento": "15/06/1990",
    "rg": "123456789",
    "ufEmissorRg": "SP",
    "tipoDomicilio": {
        "tipoDomicilioKey": 1,
        "descricao": "Nacional"
    },
    "ativa": true,
    "lojaRegistroKey": 1,
    "lojaEfetivaKey": 1,
    "funcaoEfetivaKey": 110,
    "dataAdmissao": "01/09/2026",
    "salarioAtual": 3500.00,
    "numeroCtps": 123456,
    "serieCtps": 10,
    "ufCtps": "SP",
    "dataEmissaoCtps": "10/01/2015",
    "nacionalidade": "Brasileira",
    "ufNaturalidade": "SP",
    "nomePai": "PAI EXEMPLO",
    "nomeMae": "MAE EXEMPLO",
    "status": true,
    "codigoIntegracaoFolha": 100001,
    "codigoIntegracaoFuncao": "110",
    "convenioMedico": false,
    "valeTransporte": true,
    "operador": false,
    "fiscal": false,
    "estadoTituloEleitoral": "SP",
    "usaValeCompra": false,
    "limiteValeCompra": 0.00,
    "contasBancarias": [],
    "vinculosEmpregaticios": [
        {
            "codigoIntegracaoFolha": 100001,
            "lojaRegistro": 1,
            "lojaEfetiva": 1,
            "dataAdmissao": "01/09/2026"
        }
    ],
    "centroDeCustoKey": null,
    "matrizRateioKey": 456,
    "uf": "SP",
    "rua": "Rua Exemplo",
    "numero": "100",
    "bairro": "Centro",
    "cidade": "São Paulo",
    "cep": "04089-010"
}

Para conhecer mais sobre como é a utilização dessa ferramenta, clique aqui.

Para saber mais sobre a utilização das APIs do ERP, clique aqui.