Manual da API de Semelhantes

Manual contendo as últimas atualizações efetuadas em 08/03/2024.

Introdução

A API  tem a função de realizar a consulta de semelhantes ativos e semelhantes que já foram excluídos, além de vincular novos materiais semelhantes e desvincular aqueles que já estão cadastrados.

Acesso

Comunicação: REST/JSON

Para acessar a coleção de chamadas: Clique aqui

Listage dos Endpoint's que contemplam a API de semelhantes:

Descrição

Método

URL Endpoint

API Semelhantes

Post

https://wscockpit.systax.com.br/api/api/material_Semelhante/auth

API Semelhantes - Vincular

Post

https://wscockpit.systax.com.br/api/api/material_Semelhante/vincular

API Semelhantes - Descinvular

Post

https://wscockpit.systax.com.br/api//api/material_Semelhante/desvincular

Swagger: https://wscockpit.systax.com.br/Api/swagger/index.html

Autenticação

A autenticação na API mencionada nesse documento, é feita via Bearer Token. A obtenção do Token é via autenticação pelo tipo Basic Auth (via usuário e senha, disponibilizados pela Systax). Para mais informações Clique aqui.

URL para obtenção do Token: https://app.systax.com.br/auth/access-token

Descrição dos campos de chamada e retorno

Chamada

Campo

Descrição

Tipo

mas_cod_prod

Código do semelhante. Iniciar a sequência de requisições pelo menor código de semelhante, por exemplo, 0.

String

mas_origem

Origem do semelhante. Iniciar a sequência de requisições pelo menor código de origem, por exemplo, 0.

String

retornar_excluidos

Caso "false" será retornado apenas os semelhantes ativos. Caso "true" será retornado apenas os semelhantes excluídos.

Boolean

paginacao

Quantidade de registros retornados por requisição com um limite de 100. 

Numerico

ponteiro_atualizacao

Controle do envio de registros novos, modificados e excluídos.

String

Paginação: Quando a quantidade de registros a serem exibidos excede o valor informado no parâmetro "paginação", é necessário fazer uma nova requisição para listar os registros restantes. Para isso, é preciso combinar os campos "mas_cod_prod" e "mas_origem" informando-os com os últimos valores da requisição anterior.      

Ponteiro_atualização: Esse parâmetro garante o retorno somente dos registros novos, alterados ou excluídos a partir de uma determinada data e hora. A máscara utilizada é: aaaammddhhmmss. O valor desse campo deve ser armazenado para requisições de atualizações, evitando assim, o envio do cadastro todo.

 

Retorno

Campo

Descrição

Tipo

total_registro

Quantidade de registros retornados

Numeric

cod_prod

Código do produto original

String

mat_origem

Origem do produto original

String

mas_cod_prod

Código do semelhante

String

mas_origem

Origem do semelhante

String

mas_desc

Descrição do semelhante

String

mas_dt_incl

Data de criação do semelhante

String

usu_nome

Usuário responsável pela criação do semelhante

String

excluido

Caso "true" o semelhante está excluído. Caso "false" o semelhante encontra-se ativo.

Boolean

cod_status

Código de retorno da requisição

String

msg_status

Mensagem de retorno da requisição

String

ponteiro_atualizacao

Armazena a data e hora da requisição com a máscara: aaaammddhhmmss  

String

 

Tabela de código  (campos "cód_status" e "msg_status" )

cod_status

msg_status

0

Retorno com sucesso

10

Ocorreu uma falha na aplicação

401

Token inválido ou expirado

Exemplos de chamada e retorno

Exemplos de chamada e retorno

Chamadas

Retornar semelhantes ativos

{    
    "mas_cod_prod": "1234",
    "mas_origem": "0",
    "retornar_excluidos": false,
    "paginacao": 100,
    "ponteiro_atualizacao": "0"
}

Retornar semelhantes excluídos

{    
    "mas_cod_prod": "1234",
    "mas_origem": "0",
    "retornar_excluidos": true,
    "paginacao": 100,
    "ponteiro_atualizacao": "0"
}

Retornar os semelhantes ativos ou excluídos a partir de uma data específica. Ex: 01/01/2024 00:00:00

    "mas_cod_prod": "1234",
    "mas_origem": "0",
    "retornar_excluidos": false,
    "paginacao": 100,
    "ponteiro_atualizacao": "20240101000000"
}

Exemplos de chamada e retorno

Retornos

Retorno de semelhantes ativos:

{
   "total_registro": 2,
   "material_Semelhantes":    [
            {
         "cod_prod": "1234",
         "mat_origem": "0",
         "mas_cod_prod": "0202020202",
         "mas_origem": "0",
         "mas_desc": "Descrição",
         "mas_dt_incl": "2024-01-01T14:38:13.857",
         "usu_nome": "",
         "excluido": false
      },
            {
         "cod_prod": "12345",
         "mat_origem": "0",
         "mas_cod_prod": "101010",
         "mas_origem": "0",
         "mas_desc": "Descrição",
         "mas_dt_incl": "2024-01-01T13:57:52.047",
         "usu_nome": "",        
         "excluido": false
      }
   ],
   "origem": "Systax",
   "sistema": "Cockpit",
   "status":    {
      "cod_status": 0,
      "msg_status": "Retorno com sucesso. "
   },
    "ponteiro_atualizacao":"11111111111111"
}

Retorno de semelhantes excluídos:

{
   "total_registro": 2,
   "material_Semelhantes":    [
            {
         "cod_prod": "1234",
         "mat_origem": "0",
         "mas_cod_prod": "000001",
         "mas_origem": "0",
         "mas_desc": "Descrição",
         "mas_dt_incl": "2024-01-01T09:52:14",
         "usu_nome": "",
         "excluido": true
      },
            {
         "cod_prod": "12345",
         "mat_origem": "0",
         "mas_cod_prod": "000001",
         "mas_origem": "0",
         "mas_desc": "Descrição",
         "mas_dt_incl": "2024-01-01T20:48:57",
         "usu_nome": "",
         "excluido": true
      }
   ],
   "origem": "Systax",
   "sistema": "Cockpit",
   "status":    {
      "cod_status": 0,
      "msg_status": "Retorno com sucesso. "
   },

   "ponteiro_atualizacao":"11111111111111"
}

Retorno dos semelhantes cadastrados a partir de data específica Ex: 01/01/2024 00:00:00

{
   "total_registro": 6,
   "material_Semelhantes":    [
            {
         "cod_prod": "123",
         "mat_origem": "0",
         "mas_cod_prod": "S01",
         "mas_origem": "0",
         "mas_desc": "Descrição",
         "mas_dt_incl": "2024-01-01T10:32:16.887",
         "usu_nome": "",
         "excluido": false
      },
            {
         "cod_prod": "1234",
         "mat_origem": "0",
         "mas_cod_prod": "S01",
         "mas_origem": "1",
         "mas_desc": "Descrição",
         "mas_dt_incl": "2021-01-26T11:12:34.997",
         "usu_nome": "",
         "excluido": false
      },
            {
         "cod_prod": "12345",
         "mat_origem": "0",
         "mas_cod_prod": "S01",
         "mas_origem": "2",
         "mas_desc": "Descrição",
         "mas_dt_incl": "2024-01-01T11:24:14.637",
         "usu_nome": "",
         "excluido": false
      },
            {
         "cod_prod": "123456",
         "mat_origem": "0",
         "mas_cod_prod": "S01",
         "mas_origem": "3",
         "mas_desc": "Descrição",
         "mas_dt_incl": "2024-01-01T11:41:53.34",
         "usu_nome": "",
         "excluido": false
      },
            {
         "cod_prod": "1234567",
         "mat_origem": "0",
         "mas_cod_prod": "S01",
         "mas_origem": "4",
         "mas_desc": "Descrição",
         "mas_dt_incl": "2024-01-01T08:34:09",
         "usu_nome": "",
         "excluido": false
      },
            {
         "cod_prod": "12345678",
         "mat_origem": "0",
         "mas_cod_prod": "S02",
         "mas_origem": "0",
         "mas_desc": "Descrição",
         "mas_dt_incl": "2024-01-01T10:33:33.373",
         "usu_nome": "",
         "excluido": false
      }
   ],
   "origem": "Systax",
   "sistema": "Cockpit",
   "status":    {
      "cod_status": 0,
      "msg_status": "Retorno com sucesso. "
   },
   "ponteiro_atualizacao": "11111111111111"
}

Descrição dos campos de chamada e retorno - Opção Vincular/ Desvincular

Chamada

Importante: o que diferencia se o sistema irá vincular ou desvincular o produto são os endpoint's, indicados na guia "Acesso" do manual.

Campo

Descrição

Tipo

id

Id de registro

Numerico

codProdutoOriginal

Código do produto pai

String

origemProdutoOriginal

Origem do produto pai
(Código da Tabela de Origens: 0 a 8)

Numerico

codProdutoSemelhante

Código do produto semelhante

String

origemProdutoSemelhante

Origem do produto semelhante
(Código da Tabela de Origens: 0 a 8)

Numerico

descricaoSemelhante

Descrição do produto semelhante

String

cean

Cean do produto semelhante
(Apenas números e até 15 dígitos)

String

 

Retorno

Campo

Descrição

Tipo

id

Id de registro

Numerico

protocolo

Código de rastreamento da ação realizada

String

data

Data em que foi feita a vincução/desvinculação

String

cod

Código de retorno

Numerico

(Descrições na tabela de códigos abaixo)

message

Mensagem de retorno da requisição

String

 

Tabela de código  (campos "cód_status" e "msg_status" )

cod_status

msg_status

0

Retorno com sucesso

10

Ocorreu uma falha na aplicação

401

Token inválido ou expirado

Exemplo de chamada e retorno - Opção Vincular/ Desvincular

Chamada

Importante: o que diferencia se o sistema irá vincular ou desvincular o produto são os endpoint's, indicados na guia "Acesso" do manual

{
  "itens": [
    {
      "id": 0,
      "codProdutoOriginal": "1234",
      "origemProdutoOriginal": 0,
      "codProdutoSemelhante": "Semelhante1",
      "origemProdutoSemelhante": 0,
      "descricaoSemelhante": "Semelhante1",
      "cean": "7896411800346"            
    }
  ]
}

 

Retorno

{
    "itens": [
        {
            "id": 0,
            "protocolo": 12345,
            "data": "01/01/2024 15:41:13",
            "cod": 0,
            "message": "Solicitação realizada com sucesso"
        }
    ]
}