Cadastro de Unidades Organizacionais no SoftExpert Administração: Criação, Atualização e Exclusão com Web Services SOAP
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.
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.