Agora no Bluesoft ERP, é possível cadastrar e atualizar os dados complementares de contato nas APIs de Clientes, Fornecedores e Funcionários, além de realizar a atualização centralizada dos contatos de uma pessoa através de uma rota única.

O objetivo desta melhoria é centralizar e padronizar a manutenção dos dados de contato no ERP via integração, garantindo que o cadastro mantido por sistemas externos fique equivalente ao mantido no Bluesoft ERP, sem a necessidade de complementação manual.

O Que Mudou?

Como Era o Processo Antes?

Antes, as APIs de clientes, fornecedores e funcionários permitiam manipular contatos apenas com o tipo e valor. Não havia cobertura para os campos de referência do contato (Nome do contato de referência e Referência) no cadastro via integração, nem uma estrutura centralizada para atualização. Isso gerava divergências entre os dados do ERP e das integrações, exigindo digitação manual e gerando retrabalhos.

Como Funciona Agora?

Agora, as APIs de cadastro e atualização de Clientes, Fornecedores e Funcionários passam a aceitar e retornar os campos complementares de contato. Além disso, foi disponibilizado um novo endpoint centralizado na API de Pessoa que permite atualizar os contatos de qualquer entidade vinculada a uma pessoa por meio da chave única (pessoaKey).

Benefícios:

  • Padronização: Rota única para manutenção de contatos, independente do papel da pessoa no sistema (Cliente, Fornecedor ou Funcionário).
  • Integridade dos Dados: Alinhamento completo entre as informações mantidas nos sistemas integrados e no ERP.
  • Redução de Retrabalho: Elimina a necessidade de ajustes manuais no cadastro do ERP após a importação via API.

Como Irá Funcionar?

1. Inclusão dos Campos Complementares nas APIs Existentes

Nas requisições de cadastro e atualização (POST e PUT) das APIs de Clientes, Fornecedores e Funcionários, o objeto do array contatos foi estendido com os seguintes campos opcionais:

  • nomeContatoReferencia: Texto opcional com limite de até 30 caracteres (grava o Nome do contato de referência).
  • referencia: Texto opcional com limite de até 200 caracteres (grava a Referência).

Nas consultas (GET) dessas APIs, o retorno do array contatos passa a incluir também os campos contatoKey, nomeContato (ou nomeContatoReferencia) e referencia.

2. Atualização Centralizada via API de Pessoa

Foi criado o novo endpoint de atualização centralizada de contatos:

  • Endpoint: PUT /api/pessoas/{pessoaKey}/contatos

Para utilizá-lo:

  1. Informe a pessoaKey na URL (chaves contextuais como clienteKey, fornecedorKey ou funcionarioKey que representem a chave da pessoa podem ser utilizadas).
  2. No corpo da requisição (Body), envie a lista de objetos contendo obrigatoriamente o contatoKey de cada contato a ser alterado.
  3. É possível atualizar apenas os campos enviados no JSON (atualização parcial). Os campos omitidos na requisição manterão seus valores atuais no banco de dados.
  4. Para limpar o conteúdo dos campos nomeContatoReferencia ou referencia, basta enviá-los como string vazia ("").

Exemplo de JSON:

[
  {
    "contatoKey": "282",
    "tipoContato": "WHATSAPP",
    "valor": "11999998888",
    "nomeContatoReferencia": "Contato API",
    "referencia": "Referencia atualizada pela API"
  }
]

Observações Importantes!

  • Permissões de Acesso: Para utilizar a nova rota centralizada PUT /api/pessoas/{pessoaKey}/contatos, é necessário possuir a nova permissão global API – Contatos (Atualizar) (4685-API-Contatos).
  • Validações de Limite: As operações serão bloqueadas com mensagem de erro caso o campo nomeContatoReferencia ultrapasse 30 caracteres ou o campo referencia ultrapasse 200 caracteres.
  • Validações de Vínculo: O sistema retornará erro se a pessoaKey não for encontrada ou se o contatoKey informado não pertencer à pessoa informada.
  • Aviso de Descontinuação (Deprecated): A rota antiga de atualização de contatos específica de fornecedores (PUT /api/fornecedores/contatos/{fornecedorKey}) foi marcada como Deprecated. Recomenda-se utilizar o novo endpoint centralizado PUT /api/pessoas/{pessoaKey}/contatos.

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.

Disponível a partir da versão r372.01