Agora no Bluesoft ERP, é possível incluir um ou mais contatos diretamente em uma pessoa cadastrada através do seu identificador único (pessoaKey) via API pública, sem a necessidade de informar chaves de contatos preexistentes e de forma independente do papel da pessoa no sistema (seja cliente, fornecedor ou funcionário).

O objetivo desta melhoria é centralizar e otimizar a integração de dados no ERP, permitindo que sistemas externos acrescentem novos telefones, e-mails e referências ao cadastro da pessoa através de uma rota dedicada exclusivamente à inclusão, garantindo a integridade dos dados e eliminando manutenções manuais ou o uso de rotas descontinuadas.

Como Era o Processo Antes?

Antes, a rota centralizada de contatos de pessoa (PUT /api/pessoas/{pessoaKey}/contatos) operava unicamente para alteração de dados e exigia obrigatoriamente a identificação de um contato preexistente (contatoKey).

Com isso, integrações que conheciam a pessoaKey, mas precisavam incluir um novo telefone ou e-mail, não conseguiam realizar a operação por essa via central. O processo dependia do uso de APIs específicas de cada módulo (como cliente, fornecedor ou funcionário) ou da inclusão manual diretamente pelas telas do ERP.

Benefícios:

  • Centralização Integrada: Permite cadastrar novos contatos utilizando apenas a pessoaKey, unificando a manutenção independentemente da classificação da pessoa.
  • Operação em Lote: Inclusão de múltiplos contatos em uma única chamada de API.
  • Integridade de Dados: Validação integral antes do salvamento, prevenindo gravações parciais em caso de falha.

Como Irá Funcionar a Partir de Agora?

A partir desta atualização, foi disponibilizada uma nova rota de escrita dedicada exclusivamente à inclusão de contatos:

  1. Acesso e Permissão: A operação é realizada através do endpoint POST /api/pessoas/{pessoaKey}/contatos e requer a permissão 4733 – API Contatos (Incluir).
  2. Dados da Requisição: A integração deve enviar uma lista no corpo da requisição contendo um ou mais contatos com a seguinte estrutura:
    • tipoContato: Classificação do contato reconhecida pelo ERP (obrigatório).
    • valor: Conteúdo do contato, aceitando de 1 a 100 caracteres (obrigatório).
    • nomeContatoReferencia: Nome de apoio com até 30 caracteres (opcional).
    • referencia: Complemento de referência com até 200 caracteres (opcional).
  3. Validações Aplicadas:
    • Existência da Pessoa: Se a pessoaKey informada não for encontrada no ERP, o sistema rejeita a chamada com status 404 Not Found.
    • Contrato e Formato: Rejeita requisições com corpo ausente, nulo ou listas vazias, além de validar o formato de e-mail para os tipos aplicáveis.
    • Exclusividade para Centro de Distribuição: Os tipos EMAIL_RASTREAMENTE_CARGA e EMAIL_EMISSAO_CT_E continuam restritos e só podem ser incluídos se a pessoa corresponder a um Centro de Distribuição (CD).
    • Duplicidade Literal: O ERP compara o tipo e o valor de forma literal. Se a pessoa já possuir um contato exatamente igual ou se o lote contiver itens duplicados entre si, toda a requisição é rejeitada com status 400 Bad Request.
    • Múltiplos Contatos do Mesmo Tipo: É permitido cadastrar mais de um contato do mesmo tipo para a mesma pessoa, desde que seus valores sejam diferentes.
  4. Atomicidade e Confirmabilidade: O lote é validado por completo antes da gravação. Caso ocorra erro em qualquer item, nenhum contato é criado e a data de alteração da pessoa não é atualizada. Havendo sucesso integral, o sistema retorna o status 201 Created apresentando a contatoKey gerada, o tipoContato e o valor de cada contato criado.

Observações Importantes!

  • Escopo Exclusivo de Inclusão: A nova rota executa apenas a criação de novos contatos; não realiza alterações, substituições ou exclusões de registros existentes.
  • Gestão de Acesso: É necessário conceder a permissão 4733 – API Contatos (Incluir) para os usuários ou credenciais de integração que utilizarão o endpoint.
  • Manutenção do Legado: As rotas públicas preexistentes mantêm seus contratos e comportamentos originais, sendo a nova rota a solução padrão e centralizada para inclusões via API.

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

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