Documentação de Integração: Z-Sync

Objetivo Principal do Z-Sync: O Z-Sync atua como um middleware robusto e eficiente, facilitando a integração entre ERPs diversos. Sua principal função é otimizar a troca de dados entre plataformas, proporcionando agilidade e consistência nas operações. O Z-Sync oferece endpoints RESTful que permitem a consulta e manipulação de dados no ERP, como centros de custos, ocorrências, parâmetros de configuração, e muito mais. A solução visa simplificar o dia a dia das empresas, oferecendo uma interface padronizada e eficiente para integrar diferentes sistemas.

---

1. Introdução

Esta documentação descreve os endpoints da API do Z-Sync, que permite a integração de diferentes sistemas com um ERP. Através dessa API, é possível consultar e manipular diversos dados do ERP, como centros de custos, parâmetros de configuração, execuções de métodos e ocorrências.

Objetivo:
Facilitar a comunicação entre o ERP e outros sistemas, permitindo a integração de dados em tempo real e garantindo maior eficiência nas operações.

Pré-requisitos:

• Ambiente ERP configurado com o serviço REST habilitado.
• Parâmetros de acesso e configurações de rede adequadas.

---

2. Autenticação

A API do Z-Sync requer autenticação via token para garantir o acesso aos endpoints. Para obter o token, é necessário realizar uma requisição POST para o endpoint /api/auth com as credenciais de usuário. O token gerado deve ser incluído no cabeçalho Authorization de todas as requisições subsequentes.

Fluxo de Autenticação:

1. Requisição de Autenticação:

   • O cliente envia uma requisição POST para o endpoint /api/auth, fornecendo o nome de usuário e a senha no corpo da requisição.

2. Recebimento do Token:

   • Se as credenciais forem válidas, o servidor retornará um token de autenticação que deve ser usado para acessar os demais endpoints da API.

3. Uso do Token:

   • O token gerado deve ser enviado no cabeçalho Authorization das requisições subsequentes, no formato Bearer {token}.

Exemplo de Requisição POST /api/auth:

{
  "username": "usuario_exemplo",
  "password": "senha_exemplo"
}

Exemplo de Resposta de Sucesso (200 OK):

{
  "token": "abcd1234token"
}

Exemplo de Resposta de Erro (400 Bad Request):

{
  "erro": "Credenciais inválidas."
}

---

3. Endpoints e Métodos

3.1. Endpoint: GET /api/management/executions/sum/initial-date/{initialDate}/final-date/{finalDate}

Descrição:
Retorna o número de execuções realizadas por intervalo de hora.

Parâmetros de URL:

• initialDate (obrigatório): Data inicial no formato yyyy-MM-dd HH:mm:ss.
• finalDate (obrigatório): Data final no formato yyyy-MM-dd HH:mm:ss.

Respostas:

• 200 - OK

{
  "totalExecutions": 150
}

• 400 - Bad Request:
  Erro de parâmetros inválidos.

---

3.2. Endpoint: GET /api/occurrence

Descrição:
Retorna todos os registros de ocorrência, com possibilidade de filtro por parâmetros como nome do aplicativo, nome da integração, status de erro, entre outros.

Parâmetros de URL:

• nameApplication (opcional): Nome do aplicativo.
• integrationName (opcional): Nome da integração.
• statusError (opcional): Status do erro (ex: "FAILED").
• page (opcional): Número da página de resultados.
• pageSize (opcional): Número de registros por página.

Respostas:

• 200 - OK

{
  "data": [
    {
      "id": "12345",
      "nameApplication": "App1",
      "statusError": "FAILED",
      "description": "Erro na execução",
      "creationDate": "2024-12-04T15:30:00"
    }
  ],
  "pagination": {
    "totalElements": 1,
    "page": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

---

3.3. Endpoint: POST /api/auth

Descrição:
Realiza a autenticação para acesso a outros endpoints do Z-Sync. Este endpoint deve ser utilizado para obter o token de autenticação.

Parâmetros de Body:

• username (obrigatório): Nome de usuário.
• password (obrigatório): Senha de acesso.

Respostas:

• 200 - OK

{
  "token": "abcd1234token"
}

• 400 - Bad Request:
  Erro de parâmetros inválidos.

---

3.4. Endpoint: GET /api/method

Descrição:
Retorna uma lista de métodos configurados no ERP, com a possibilidade de filtragem por nome do método e outros parâmetros.

Parâmetros de URL:

• nameMethod (opcional): Nome do método.
• integrationName (opcional): Nome da integração.

Respostas:

• 200 - OK

{
  "methods": [
    {
      "name": "Method1",
      "status": "ACTIVE",
      "lastExecution": "2024-12-04T15:30:00"
    }
  ]
}

---

4. Processo de Integração

Fluxo Geral

1. Requisição para Endpoints RESTful: O cliente envia uma requisição GET, POST, PUT ou DELETE para o Z-Sync, com os parâmetros necessários na URL ou corpo da requisição.

2. Validação dos Parâmetros: O sistema valida todos os parâmetros fornecidos e, caso algum parâmetro esteja incorreto, retorna um erro adequado.

3. Consulta ao ERP: Após a validação, o Z-Sync consulta o banco de dados ou sistema ERP, executando a lógica necessária (como retornar listas de centros de custos ou ocorrências).

4. Retorno da Resposta: Os dados solicitados são formatados em JSON e enviados como resposta, com os códigos HTTP apropriados.

---

5. Tratamento de Erros

Possíveis Respostas de Erro

1. 400 - Bad Request:
   Parâmetros inválidos ou ausentes.

   {
     "erro": "O parâmetro Page deve ser um número válido."
   }
   

2. 404 - Not Found:
   Endpoint ou dados não encontrados.

   {
     "erro": "Recurso não encontrado."
   }
   

3. 500 - Internal Server Error:
   Erro interno durante o processamento.

   {
     "erro": "Erro interno no servidor."
   }
   

---

6. Conclusão

O Z-Sync oferece uma solução robusta para a integração entre sistemas ERP e outras plataformas. Com endpoints RESTful fáceis de usar, validação de parâmetros e respostas consistentes, ele melhora a comunicação e a agilidade nos processos empresariais. Esta documentação visa fornecer todos os detalhes necessários para a integração, garantindo uma experiência simples e eficiente para os desenvolvedores.