Este documento visa facilitar a integração de sistemas externos que pretendem realizar consultas sobre posições de estoque e preços de produtos, bem como efetuar registros de pedidos de venda, nas empresas clientes que utilizam o sistema da Vetor Soluções. A integração é realizada através de APIs RESTful, proporcionando um método padronizado e eficiente para o intercâmbio de informações.

Requisito Geral

  1. Para utilizar deste recurso, a aplicação deve ser previamente homologada para integração com as APIs da Vetor Soluções. Em caso de dúvidas entre em contato com a equipe  de atendimento da Zetti Tech para credenciamento/solicitação do token de acesso as APIs.

Requisitos de produtos

As consultas da posição de estoque e valores de produtos devem ser realizadas com os seguintes parâmetros:

  1. As consultas da posição de estoque e valores de produtos devem ser realizadas com os seguintes parâmetros: 
  2. URL: https://integracao.zetti.dev/api/ecommerce/produtos/consulta
  3. Headers: Authorization: ApiKey xxxxxxxxxxxx (onde “xxxxxxxxxxxx” corresponde ao token de acesso repassado pela Vetor Soluções para acesso à base da empresa).
  4. Método: GET
  5. Retorno: A API irá retornar um JSON com o seguinte formato:

campos com “?” podem retornar o valor nulo (“null”).

{

    "status": int32,

    "data": [

        {

            "cdFilial": int32,

            "cdProduto": int32,

            "descricao": string,

            "descricaoUsual": string,

            "codigoBarras": string,

            "inativo": bool,

            "cdMarca": int32?,

            "nomeMarca" : string?,

            "cdFabricante" : int32?,

            "nomeFabricante" : string?,

            "cdLinha" : int32?,

            "nomeLinha" : string?,

            "cdCategoria" : int32?,

            "nomeCategoria" : string?,

            "qtdEstoque" : double,

            "vlrTabela": double,

            "percDesconto": double,

            "vlrOferta": double,

            "dtUltimaAlteracao": dateTime,

            "nsuRegistro": int32

        }

    ],

    "msg": string,

    "total": int32

}

Onde:

  • “status”: indicará o resultado do processamento: 200 para sucesso, 500 para erros e advertências; 

  • “data”: retornará uma lista de no máximo 500 registros de acordo com os critérios informados;

  • “msg”: retornará uma mensagem descrevendo o resultado do processamento da consulta (sucesso, erro ou advertência caso ocorra);

  • “total”: indicará a quantidade total de registros encontrados para os critérios informados. Esta propriedade irá retornar algum valor somente se for informado o parâmetro $count=true na URL de consulta. O uso deste parâmetro é opcional pois pode influenciar na performance da consulta; 

Critérios de consulta

Pode-se efetuar critérios avançados na consulta utilizando o protocolo de consulta OData através dos seguintes parâmetros na URL:

  • $filter: utilizado para efetuar filtros dinâmicos de acordo com a estrutura de retorno dos registros, no formato $filter={função | propriedade operador valor}. Exemplos: 

Filtrando somente produtos que contenham a palavra “azul” na descrição:   

...produtos/consulta?$filter=contains(descricao, ‘azul’) 

Filtrando somente produtos ativos e com quantidade em estoque superior a zero:

...produtos/consulta?$filter=inativo eq false and qtdEstoque gt 0 

Alguns operadores disponíveis:

eq: igual a; 

ne: diferente de; 

gt: maior que; 

ge: maior ou igual a; 

lt: menor que; 

le: menor ou igual a; 

and: “e” lógico; 

or: “ou” lógico; 

$select: utilizado para especificar os campos de retorno da API, dando a possibilidade de selecionar somente as propriedades desejadas a fim de diminuir o tráfego de dados. Exemplo:    

Para a API retornar somente o código e a descrição dos produtos:    

...produtos/consulta?$select=codigo,descricao 

$orderby: utilizado para especificar a ordem de retorno dos resultados: Exemplo: 

Para ordenar os resultados da consulta por preço do maior para o menor:    

...produtos/consulta?$orderby=vlrTabela asc 

$top: utilizado para especificar a quantidade de registros a serem retornados pela API. Exemplo: 

Para retornar somente os 100 primeiros resultados: 

...produtos/consulta?$top=100

$skip: utilizado para especificar a quantidade de registros a serem ignorados no retorno da API. Em conjunto com o parâmetro $top pode-se paginar os resultados para otimizar as consultas: Exemplo: 

Para retornar somente 100 registros ignorando os primeiros 200:    

...produtos/consulta?$skip=200&$top=100

$count: utilizado para indicar se a API deve ou não contabilizar a quantidade total de registros encontrados para os critérios informados na propriedade “total” do retorno. Exemplo:    

...produtos/consulta?$count=true 

Para mais informações sobre o protocolo OData consultar documentação disponível em https://www.odata.org/documentation/odata-version-2-0/uri-conventions/

Considerações

As informações dos produtos são atualizadas a cada 30 minutos. No caso de acompanhamento em tempo real, para evitar o consumo indevido da API, armazenar o maior valor da propriedade “nsuRegistro” dentre os resultados retornados, e na próxima consulta efetuada, informar o parâmetro $filter=nsuRegistro gt xxxx (onde xxxx é o número do nsu armazenado anteriormente) para que se retorne somente os produtos com novas alterações, repetindo o processo para cada ciclo de consumo.

Requisições de pedidos

Os pedidos deverão ser registrados por meio da API com os seguintes parâmetros:

  1. URL: https://integracao.zetti.dev/api/ecommerce/pedidos
  2. Headers: Authorization: ApiKey xxxxxxxxxxxx (onde “xxxxxxxxxxxx” corresponde ao token de acesso repassado pela Vetor Soluções para acesso a base da empresa).
  3. Método: POST
  4. Payload:



    {

        "cdFilial": 0,

        "cgcFilial": "string",
        //Obrigatório informar uma das duas propriedades cgcFilial ou cdFilial

        "dtEmissao": "2022-11-07T18:34:26.076Z",

        "cliente": {

            "nome": "string",

            "cpfCgc": "string",

            "telefone": "string", //opcional

            "sexo": "string", //M, F ou em branco

            "dtNascimento": "2022-11-07T18:34:26.076Z", //opcional

            "endereco": "string",

            "numero": "string",

            "complemento": "string",

            "cep": "string",

            "bairro": "string",

            "cidade": "string",

            "uf": "string",

            "cidadeIBGE": 0, //opcional

            "referencia": "string",

            "email": "string",

            "inscEstadual": "string", //opcional

            "inscMunicipal": "string" //opcional

        },

        "vlrProdutos": 0,

        "vlrDescontos": 0,

        "vlrFrete": 0,

        "vlrOutros": 0,

        "vlrTotal": 0,

        "vlrTroco": 0,

        "observacao": "string",

        "nrPedido": "string", //obrigatório

        "retirar": true,

        "itens": [

            {

                "cdProduto": 0, //obrigatório

                "cdBarrasProduto": "string",

                "quantidade": 0,

                "vlrUnitario": 0,

                "vlrDesconto": 0,

                "vlrTotal": 0

            }

        ]

    }

  5. Retorno:

    {

        "status": 200,

        "data": {

            "situacao": 0,

            "cdOrcamento": 123,

            "mensagem": "Orçamento registrado com sucesso",

        },

        "msg": "Orçamento registrado com sucesso"

    }

Onde:

A propriedade “situação” poderá ter os seguintes valores:

0. Não encontrado

1. Pendente

2. Em separação

3. Conferência

4. Faturado

5. Despachado

6. Entregue

7. Entrega não realizada

8. Cancelado

9. Devolvido

E na propriedade “cdOrcamento” o código do orçamento gerado para o pedido.

  1. Para consultar a stuação de um pedido, deve-se realizar a seguinte requisição:
    1. URL: https://integracao.zetti.dev/api/Ecommerce/pedidos/status?numeroPedido=xxxxxxx&cdOrcamento=9999

      Onde:

      “xxxxxxx” corresponde ao número do pedido da plataforma enviado na propriedade “nrPedido” ao registrar o pedido, e “9999” o “cdOrcamento” retornado pela API ao registrar o pedido.

  2. Headers: Authorization: ApiKey xxxxxxxxxxxx (onde “xxxxxxxxxxxx” corresponde ao token de acesso repassado pela Zetti Tech para acesso a base da empresa).
  3. Método: GET
    1. Esta requisição irá retornar o mesmo objeto retornado na API de registro de pedido, sendo atualizado a propriedade “situacao” no decorrer do processo do pedido na loja.

WebHook de notificação de alteração de status de pedidos

O cliente é responsável pelo desenvolvimento, publicação e integração do serviço conforme a documentação abaixo para o uso do WebHook da Vetor. As atualizações de status dos pedidos serão transmitidas por meio da API, incluindo os seguintes parâmetros:

  1. URL: https://seuservico.com/api/pedidos/notificar
  2. Headers:
    1. X-AppToken: token único de identificação para acesso a api.
  3. Método: POST
  4. Payload:



    {

        "pedidoId": "13951",

        "dataStatus": "2023-05-15T16:07:58",

        "status": "Faturado",

        "notaFiscal": {

            "dataEmissao": "2023-12-22T16:25:12",

            "serie": 15,

            "numero": 45685,

            "chaveAcesso": "52231216010431000250650010000015991664015477",

            "valor": 5.99

        }

    }

  5. Response: retorne statuscode : 201-created
  6. OpenApi – A documentação pode ser baixada ao clicar aqui e pode utilizada no OpenAPI Generator para auxiliar na criação do serviço.

Explore outros conteúdos e descubra o passo a passo da operação.