# Consumindo Web Service

## Visão Geral

Os WebServices são os canais de comunicação que permitem ao Suricato "ouvir" a TOTVS. Através do protocolo SOAP, o sistema recebe arquivos XML contendo atualizações de colaboradores, cargos e escalas, garantindo que a segurança da catraca esteja sempre alinhada com as decisões do RH.

Através dos *ServiceBeans* listados abaixo, é possível realizar o intercâmbio de informações de colaboradores, escalas, locais e eventos administrativos de forma automatizada

## Regras de Negócio

Para que a troca de dados ocorra sem falhas, valide estes pontos:

* [x] **Protocolo de Comunicação:** A integração é realizada via chamadas XML (WSDL).
* [x] **Visibilidade de Rede:** O servidor deve permitir tráfego na porta 5000 (ou a porta configurada para o serviço `suricato-totvs`).
* [x] **Ordem de Integração:** Respeite as dependências. Integre primeiro as bases (Filial, Cargo, Escala) antes de tentar integrar o Colaborador (`UserIntegrationServiceBean`).
* [x] **Máscaras:** Dados como CPF e CNPJ devem seguir exatamente o formato esperado pela TOTVS para evitar rejeições.
* [x] **Tratamento de Resposta:** Toda chamada retorna um status. Em caso de erro, o WebService detalha qual campo ou regra impediu a sincronização.

## Como Consumir o WebService

Para realizar a integração de um tópico específico, siga o procedimento padrão.

{% stepper %}
{% step %}
**Identificação do Tópico:** Escolha o ServiceBean correspondente à informação que deseja integrar (ex: `ScaleIntegrationServiceBean` para Escalas).
{% endstep %}

{% step %}
**Configuração de Endpoint:** Aponte a sua ferramenta de integração ou ERP para a URL WSDL indicada na tabela.
{% endstep %}

{% step %}
**Mapeamento de Máscaras:** Certifique-se de que o XML enviado respeite as máscaras de campo definidas para cada entidade.
{% endstep %}

{% step %}
**Envio de Request:** Execute a chamada do serviço enviando os dados em formato XML.
{% endstep %}

{% step %}
**Análise de Resposta:** Verifique o retorno do WebService. Em caso de erro, a mensagem detalhará o campo ou a regra de negócio que impediu a sincronização.
{% endstep %}
{% endstepper %}

## Lista de WebServices

Os serviços de integração estão centralizados no servidor de aplicação. Utilize a URL base substituindo `servidor` pelo endereço IP ou DNS do seu ambiente.

<table data-header-hidden><thead><tr><th width="172.888916015625"></th><th width="247"></th><th></th></tr></thead><tbody><tr><td><strong>Funcionalidade</strong></td><td><strong>ServiceBean</strong></td><td><strong>URL (WSDL)</strong></td></tr><tr><td>Afastamento e Situação</td><td>AbsenceReasonIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/AbsenceReasonIntegrationServiceBean?wsdl</code></td></tr><tr><td>Local de Organograma</td><td>AllocationUnitIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/AllocationUnitIntegrationServiceBean?wsdl</code></td></tr><tr><td>Centro de Custo</td><td>CostCenterIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/CostCenterIntegrationServiceBean?wsdl</code></td></tr><tr><td>Feriado</td><td>DayNotWorkedIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/DayNotWorkedIntegrationServiceBean?wsdl</code></td></tr><tr><td>Exceção</td><td>ExceptionIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/ExceptionIntegrationServiceBean?wsdl</code></td></tr><tr><td>Pessoa Jurídica</td><td>LegalPersonIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/LegalPersonIntegrationServiceBean?wsdl</code></td></tr><tr><td>Localidade</td><td>LocationIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/LocationIntegrationServiceBean?wsdl</code></td></tr><tr><td>Pessoa Física</td><td>NaturalPersonIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/NaturalPersonIntegrationServiceBean?wsdl</code></td></tr><tr><td>Cargo</td><td>PositionLevelIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/PositionLevelIntegrationServiceBean?wsdl</code></td></tr><tr><td>Escala</td><td>ScaleIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/ScaleIntegrationServiceBean?wsdl</code></td></tr><tr><td>Troca de Turno</td><td>ShiftWorkIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/ShiftWorkIntegrationServiceBean</code></td></tr><tr><td>Filial</td><td>UnitIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/UnitIntegrationServiceBean?wsdl</code></td></tr><tr><td>Colaborador/Usuário</td><td>UserIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/UserIntegrationServiceBean?wsdl</code></td></tr><tr><td>Troca de Turno (Usuário)</td><td>UserShiftWorkIntegrationServiceBean</td><td><code>http://servidor:5000/suricato-totvs/UserShiftWorkIntegrationServiceBean?wsdl</code></td></tr></tbody></table>

## WebServices: Guia de Sincronização

Utilize os links abaixo para acessar os detalhes de configuração de cada serviço. Os nomes listados correspondem exatamente aos ServiceBeans homologados para a integração TOTVS.

#### Cadastro e Estrutura Base

Configurações essenciais de pessoas e unidades organizacionais.

* NaturalPersonIntegrationServiceBean | Dados Pessoais
  * \[Configurar Pessoa Física →]
* UserIntegrationServiceBean | Dados do Colaborador/Usuário
  * \[Sincronizar Colaboradores →]
* LegalPersonIntegrationServiceBean | Cadastro de Pessoa Jurídica
  * \[Validar Pessoas Jurídicas →]
* UnitIntegrationServiceBean | Cadastro de Filiais
  * \[Configurar Unidades →]
* PositionLevelIntegrationServiceBean | Níveis de Cargo
  * \[Ajustar Tabela de Cargos →]

#### Alocação e Custos

Mapeamento de onde o colaborador está inserido na empresa.

* LocationIntegrationServiceBean | Localidades de Atuação
  * \[Mapear Localidades →]
* AllocationUnitIntegrationServiceBean | Unidades de Organograma
  * \[Configurar Alocação →]
* CostCenterIntegrationServiceBean | Centros de Custo
  * \[Sincronizar Custos →]

#### Jornada, Escalas e Ausências

Serviços que regem o tempo e a presença no controle de acesso.

* ScaleIntegrationServiceBean | Configuração de Escalas
  * \[Sincronizar Escalas →]
* ShiftWorkIntegrationServiceBean | Trocas de Turno Gerais
  * \[Gerenciar Turnos →]
* UserShiftWorkIntegrationServiceBean | Trocas de Turno por Usuário
  * \[Ajustar Turnos de Usuários →]
* AbsenceReasonIntegrationServiceBean | Motivos de Afastamento
  * \[Configurar Afastamentos →]
* DayNotWorkedIntegrationServiceBean | Feriados e Dias não Trabalhados
  * \[Sincronizar Calendário →]
* ExceptionIntegrationServiceBean | Exceções de Acesso
  * \[Validar Exceções →]

#### Padrões de Comunicação (Obrigatórios)

Antes de qualquer integração, valide as regras de formatação de dados.

* Máscaras de Campo: Regras para CPF, CNPJ e IDs.
  * \[Ver Guia de Máscaras →]
* Resposta do Sistema: Como interpretar os retornos de sucesso ou erro.
  * \[Entender Status de Resposta →]

## FAQ - Perguntas Frequentes

<details>

<summary>O que fazer se a URL WSDL não carregar no navegador?</summary>

Verifique se o serviço `suricato-totvs` está ativo no servidor e se a porta `5000` não está sendo bloqueada por um firewall.

</details>

<details>

<summary>As trocas de turno devem ser enviadas por qual serviço?</summary>

Depende do contexto: use `ShiftWorkIntegrationServiceBean` para a definição geral do turno ou `UserShiftWorkIntegrationServiceBean` para vincular a troca a um colaborador específico.

</details>

<details>

<summary>O WebService aceita integração parcial (apenas alguns campos)?</summary>

Sim, desde que todos os campos marcados como obrigatórios no contrato do WSDL sejam enviados na requisição XML.

</details>

<details>

<summary>Como interpretar as mensagens de erro na Resposta?</summary>

As respostas seguem um padrão técnico; erros de validação de dados (como CPF inválido) ou erros de banco de dados serão descritos na tag de mensagem do retorno.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://software-telematica-com.gitbook.io/suricato-docs/central-tecnica/instalacao-e-configuracao-do-suricato/instalacao-do-suricato/integracao-suricato-totvs/webservice-suricato-totvs/consumindo-web-service.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.