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:

  • URL: https://integracao.zetti.dev/api/ecommerce/produtos/consulta
  • Headers: Authorization: ApiKey xxxxxxxxxxxx (onde “xxxxxxxxxxxx” corresponde ao token de acesso repassado pela Vetor Soluções para acesso à base da empresa)
  • Método: GET
  • 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
}
CODE

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:

Parâmetro $filter

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

Deve ser utilizado seguindo o padrão:

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

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

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

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

A seguir estão alguns operadores disponíveis para utilização:

  • 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

Parâmetro $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.

Deve ser utilizado seguindo o padrão:    

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

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

Parâmetro $orderby

Utilizado para especificar a ordem de retorno dos resultados.

Deve ser utilizado seguindo o padrão:

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

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

Parâmetro $top

Utilizado para especificar a quantidade de registros a serem retornados pela API.

Deve ser utilizado seguindo o padrão:

Para retornar somente os 100 primeiros resultados.

...produtos/consulta?$top=100
CODE

Parâmetro $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.

Deve ser utilizado seguindo o padrão:

Para retornar somente 100 registros ignorando os primeiros 200.

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

Parâmetro $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.

Deve ser utilizado seguindo o padrão:

...produtos/consulta?$count=true 
CODE

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:

{
	"cdOrigem": 0,
	"cdFilial": 0,
	"cgcFilial": "string", //Obrigatório informar uma das duas propriedades cgcFilial ou cdFilial
	"cdVendedor": 0,
	"dtEmissao": "2025-08-20T19:18:03.548Z",
	"cliente": {
	   	 "codigo": 0,
	   	"nome": "string",
	 		 "cpfCgc": "string",	
	"telefone": "string", //opcional
	        	"sexo": "string", //M, F ou em branco
	 "dtNascimento": "2025-08-20T19:18:03.548Z", //opcional
	    "endereco": "string",
	"numero": "string",
	"complemento": "string",
	    "cep": "string",
	    "bairro": "string",
	    "cdCidade": 0,
	    "cidade": "string",
	    "uf": "string",
	    "cidadeIBGE": 0, //opcional
	    "referencia": "string",
	    "email": "string",
	    "inscEstadual": "string", //opcional
	    "inscMunicipal": "string" //opcional
	    "cdConvenio": 0,
	    "clienteFidelidade": true,
	    "nrCartaoFidelidade": "string",
	    "cadastroSimplificado": true
	},
	"cdConvenio": 0,
	"vlrProdutos": 0,
	"vlrDescontos": 0,
	"vlrFrete": 0,
	"vlrOutros": 0,
	"vlrTotal": 0,
	"vlrTrocoPara": 0,
	"observacao": "string",
	"nrPedido": "string", //obrigatório
	"dadosPedido": "string",
	"retirar": true,
	"isTransportadora": true,
	"transportadora": "string",
	"itens": [
	    {
	     "id": "string",
	     "cdProduto": 0, //obrigatório
	     "cdProdutoEcommerce": "string",
	     "cdBarrasProduto": "string",
	     "nomeProduto": "string",
	     "quantidade": 0,
	     "vlrUnitario": 0,
	     "vlrDesconto": 0,
	     "vlrDescontoRateio": 0,
	     "vlrTotal": 0,
	     "cdTblDesc": 0,
	     "cdTpDesc": 0,
	     "cdVendedor": 0,
	     "infoDiversas": "string",
	     "receita": {
	        "cdMedico": 0,
	        "tpDocMedico": "string",
	        "nrDocMedico": "string",
	        "ufDocMedico": "string",
	        "nmMedico": "string",
	        "especialidadeMedico": "string",
	        "dtReceita": "2025-08-20T19:18:03.548Z",
	        "cdReceita": 0
	     },
	     "infoExtra": {
	        "tipoInfo": "ManipulacaoItem",
	        "info": "string"
	     }
	    }
	],
	"statusPedido": "Desconhecido",
	"pagamentos": [
	    {
	     "formaPagamento": "Dinheiro",
	     "descricao": "string",
	     "valor": 0,
	     "nrAutorizacao": "string",
	     "nsu": "string",
	     "bandeiraCartao": "string",
	     "adquirente": "string",
	     "dataCaptura": "2025-08-20T19:18:03.548Z",
	     "qtdParcelas": 0,
	     "cdConvenio": 0,
	     "pagamentoNaEntrega": true,
	     "cdAdmCartao": 0,
	     "valeId": "string",
	     "valeCodigo": "string",
	     "identificador": "string"
	    }
	],
	"marketPlace": "Amazon"
}
CODE
  • Retorno:
{
    "status": 200,
    "data": {
        "situacao": 0,
        "cdOrcamento": 123,
        "mensagem": "Orçamento registrado com sucesso",
    },
    "msg": "Orçamento registrado com sucesso"
}
CODE

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” será o código do orçamento gerado para o pedido.

  • Para consultar a stuação de um pedido, deve-se realizar a seguinte requisição:
  • Headers: Authorization: ApiKey xxxxxxxxxxxx (onde “xxxxxxxxxxxx” corresponde ao token de acesso repassado pela Zetti Tech para acesso a base da empresa).
  • Método GET:
    • 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:

  • URL: https://seuservico.com/api/pedidos/notificar
  • Headers:
    • X-AppToken: token único de identificação para acesso a api.
  • Método: POST
  • 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
    }
}
    CODE
  • Response:
retorne statuscode: 201-created
CODE
  • 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.