Versão: 2.2.0

Cadastro de Unidades Organizacionais no SoftExpert Administração: Criação, Atualização e Exclusão com Web Services SOAP

info

Este tutorial tem como objetivo fornecer uma breve demonstração de como pode ser construído um aplicativo para cadastro de estrutura organizacional de forma hierárquica no SoftExpert Administração. Não é um guia abrangente sobre integrações, mas sim uma ilustração prática para a criação de uma requisição.

Apresentação

Para criar ou atualizar as unidades organizacionais no SoftExpert Administração, é necessário utilizar nossos web services SOAP. Existem três métodos disponíveis para inserir, editar ou excluir dados de uma área ou unidade de negócio: newDepartment, editDepartment e deleteDepartment.

O método newDepartment possibilita inserir os dados de uma área ou unidade de negócio, enquanto o método editDepartment possibilita editar os dados de uma área ou unidade de negócios já existente. Já o método deleteDepartment possibilita excluir uma área ou unidade de negócios.

Cadastro de Áreas ou Unidade de Negócio

Neste artigo vamos criar as áreas e unidades de negócios de forma hierarquizada, então é necessário realizar o cadastro por níveis. Por exemplo, para criar uma unidade de negócio pai e uma área filha desta unidade de negócio, é necessário realizar o cadastro em duas etapas. Primeiro, é necessário cadastrar a unidade de negócio pai utilizando o método newDepartment e, em seguida, cadastrar a área filha utilizando o mesmo método e informando o ID da unidade de negócio pai como parâmetro.

dica

Antes de criar uma área ou unidade de negócio, é importante verificar se a mesma já foi cadastrada no SoftExpert Suite. Uma sugestão é enviar uma requisição para o método editDepartment para tentar editar o registro existente. Se a resposta for negativa, a próxima ação do aplicativo pode ser criar a área ou unidade de negócio utilizando o método newDepartment.

O SoftExpert Administração não irá cadastrar registros duplicados dentro de áreas ou unidades negócios no sistema. Caso uma área ou unidade de negócio já exista, é possível atualizar suas informações através do método editDepartment, enquanto a criação de novas áreas ou unidades deve ser realizada através do método newDepartment.

URL de recurso

POST /apigateway/se/ws/adm_ws.php

Exemplo

Cadastro de uma Unidade de Negócio

Neste exemplo, estamos enviando uma solicitação ao endpoint do SoftExpert Administração com o objetivo de criar uma unidade de negócio. Os parâmetros utilizados nesta requisição incluem:

Atributos utilizados neste exemplo:

Parâmetro	Tipo	Requerido	Descrição
`ID`	String	Sim	Identificador da unidade de negócio
`DESC`	String	Sim	Nome para a unidade de negócio
`FGDEPTTYPE`	Integer	Sim	Tipo da área: 2 - Unidade de Negócio.

Exemplo de solicitação:

curl 'https://my-domain.softexpert.com/apigateway/se/ws/adm_ws.php' \
-H 'Content-Type: text/xml; charset=utf-8' \
-H 'SOAPAction: urn:admin#newDepartment' \
-H 'Authorization: <your_api_token>' \
-d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:admin">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:newDepartment>
         <urn:ID>BU001</urn:ID>
         <urn:DESC>Global Electronics Corporation</urn:DESC>
         <urn:FGDEPTTYPE>2</urn:FGDEPTTYPE>
      </urn:newDepartment>
   </soapenv:Body>
</soapenv:Envelope>' -X POST

Exemplo de resposta do cadastro da Unidade de Negócio:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
        <newDepartmentResponse xmlns="urn:admin">
            <return>65</return>
            <Status>SUCCESS</Status>
            <Detail>Registro(s) inserido(s)</Detail>
            <Code>1</Code>
        </newDepartmentResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Cadastro de uma Área

Após o cadastro bem-sucedido da unidade de negócio, utilize o identificador passado no exemplo da requisição anterior para vincular a área que será criada neste passo à unidade de negócio anteriormente cadastrada.

Atributos utilizados neste exemplo:

Parâmetro	Tipo	Requerido	Descrição
`ID`	String	Sim	Identificador da unidade de negócio
`DESC`	String	Sim	Nome para a unidade de negócio
`FGDEPTTYPE`	Integer	Sim	Tipo da área: 2 - Unidade de Negócio.

Exemplo de solicitação:

curl 'https://my-domain.softexpert.com/apigateway/se/ws/adm_ws.php' \
-H 'Content-Type: text/xml; charset=utf-8' \
-H 'SOAPAction: urn:admin#newDepartment' \
-H 'Authorization: <your_api_token>' \
-d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:admin">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:newDepartment>
         <!--You may enter the following 6 items in any order-->
         <urn:ID>CA101</urn:ID>
         <urn:DESC>Mobile Devices Division</urn:DESC>
         <urn:IDUPPER>BU001</urn:IDUPPER>
         <urn:FGDEPTTYPE>1</urn:FGDEPTTYPE>
      </urn:newDepartment>
   </soapenv:Body>
</soapenv:Envelope>' -X POST

Resposta do cadastro de Área:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
        <newDepartmentResponse xmlns="urn:admin">
            <return>66</return>
            <Status>SUCCESS</Status>
            <Detail>Registro(s) inserido(s)</Detail>
            <Code>1</Code>
        </newDepartmentResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Tratamento de Erros e Exceções

Ao trabalhar com os métodos newDepartment, editDepartment e deleteDepartment, é crucial implementar um tratamento de erros e exceções adequado. Isso garantirá que qualquer erro que ocorra durante a execução das solicitações SOAP seja identificado e tratado de maneira apropriada. Erros comuns incluem parâmetros incorretos, problemas de autenticação ou indisponibilidade do serviço.

Ao receber uma resposta do servidor, verifique o campo <Status> na resposta. Se o valor for SUCCESS, a operação foi bem-sucedida. No entanto, se o valor for ERROR, analise os campos <Detail> e <Code> para obter mais informações sobre a causa do erro e tomar as medidas adequadas.

Apresentação​

Cadastro de Áreas ou Unidade de Negócio​

URL de recurso​

Exemplo​

Cadastro de uma Unidade de Negócio​

Cadastro de uma Área​

Tratamento de Erros e Exceções​

Artigos relacionados​