Integração com APIs Vetor Soluções (E-commmerce/Tele-vendas)

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

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,
            "dtCadastro": dateTime,
            "dtUltimaAlteracao": dateTime,
            "nsuRegistro": int32,
            "controleSngpc": bool,
            "cdDepartamento": int32,
            "nomeDepartamento": string,
            "controlado": bool,
            "antimicrobiano": bool,
            "etico": bool,
            "generico": bool,
            "similar": bool,
            "tipoReceituario": string,
            "tipoReceita": string,
            "corReceita": string
        }
    ],
    "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:

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

{
	"cdOrigem": 0, //Código opcional de uso interno
	"cdFilial": 1, //Filial responsável pela entrega
	"cgcFilial": "12.123.123/0001-01", //Obrigatório, informar ao menos uma das duas propriedades: cgcFilial ou cdFilial
	"nrPedido": "123456789", //Obrigatório: identificador único do pedido
	"cdVendedor": 0, //Opcional
	"dtEmissao": "2025-08-20T19:18:03.548Z",
	"cliente": {
	    "codigo": 0, //Código interno do cliente (opcional)
	    "nome": "Nome cliente", //Obrigatório
	    "cpfCgc": "123.123.123-12",	//Opcional: se não for informado o pedido será registrado em um cadastro de cliente genérico
            "telefone": "(62) 98765-4321", //Opcional
	    "sexo": "M", //M, F ou em branco
	    "dtNascimento": "2025-08-20", //Opcional
	    "endereco": "RUA 1",
	    "numero": "SN",
	    "complemento": "AP 1001",
	    "cep": "75123-123",
	    "bairro": "Centro",
	    "cidade": "Goiânia",
	    "uf": "GO",
	    "cidadeIBGE": 0, //Opcional
	    "referencia": "Portão azul", //Opcional
	    "email": "email@email.com", //Opcional
	    "inscEstadual": "123456", //Opcional
	    "inscMunicipal": "123456" //Opcional
	},
	"vlrProdutos": 0, //Obrigatório: valor líquido dos produtos
	"vlrDescontos": 0, //Soma do valor de desconto dos produtos
	"vlrFrete": 0, //Opcional
	"vlrOutros": 0, //Opcional
	"vlrTotal": 0, //Obrigatório: valor total líquido do pedido
	"vlrTrocoPara": 0, //Opcional
	"observacao": "",
	"retirar": true,
	"transportadora": "CORREIOS", //Opcional
	"marketPlace": "Amazon", //Opcional
	"itens": [
	    {
	     "cdProduto": 1234, //Obrigatório
	     "cdProdutoEcommerce": "1234", //Opcional
	     "cdBarrasProduto": "78945612345", //Opcional
	     "nomeProduto": "string",
	     "quantidade": 0, //Obrigatório
	     "vlrUnitario": 0, //Obrigatório
	     "vlrDesconto": 0, //Valor de desconto total do item
	     "vlrTotal": 0, //Obrigatório
	     "cdVendedor": 0, //Opcional
	     "infoDiversas": "string",
	     "receita": {
	        "cdMedico": 0,
	        "tpDocMedico": "string",
	        "nrDocMedico": "string",
	        "ufDocMedico": "string",
	        "nmMedico": "string",
	        "especialidadeMedico": "string",
	        "dtReceita": "2025-08-20T19:18:03.548Z",
	        "cdReceita": 0
	     }
	    }
	],
	"statusPedido": "Pago", //Opções: Pago, PagamentoNaEntrega
	"pagamentos": [
	    {
	     "formaPagamento": "CartaoCredito", //Obrigatório. Opções: Dinheiro, CartaoCredito, CartaoDebito, Pix, Convenio, CarteiraDigital, BoletoBancario
	     "valor": 0, //Obrigatório
	     "nrAutorizacao": "123456789",
	     "nsu": "987654321",
	     "bandeiraCartao": "MASTERCARD",
	     "adquirente": "REDE",
	     "dataCaptura": "2025-08-20T19:18:03.548Z",
	     "qtdParcelas": 1,
	     "cdConvenio": 0,
	     "identificador": ""
	    }
	]
}

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:
- 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.
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.

Consulta de clientes

As consultas clientes devem ser realizadas com os seguintes parâmetros:

URL: https://integracao.zetti.dev/api/Ecommerce/cliente/consulta?cpfCnpj="cpfCnpj", onde "cpfCnpj" deve ser substituído pelo número do documento a ser pesquisado sem aspas.
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:

{
  "status": 0,
  "data": {
    "codigo": 0,
    "nome": "string",
    "razaoSocial": "string",
    "cpfCgc": "string",
    "telefone": "string",
    "sexo": "string",
    "dtNascimento": "2026-04-09T12:34:14.977Z",
    "nrRg": "string",
    "endereco": "string",
    "numero": "string",
    "complemento": "string",
    "cep": "string",
    "bairro": "string",
    "cdCidade": 0,
    "cidade": "string",
    "uf": "string",
    "cidadeIBGE": 0,
    "referencia": "string",
    "email": "string",
    "inscEstadual": "string",
    "inscMunicipal": "string",
    "cdConvenio": 0,
    "clienteFidelidade": true,
    "nrCartaoFidelidade": "string"
  },
  "msg": "string",
  "total": 0
}

CODE

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.

Histórico de Atualizações

A seguir, apresentamos o histórico de atualizações deste documento, garantindo a rastreabilidade das alterações e o alinhamento com as evoluções do sistema. As revisões seguem o versionamento da aplicação. Para mais detalhes, consulte as Notas de Versão.

Versão	Publicado	Alterado Por	Comentar
ATUAL (v. 33)	27/04/2026 17:49	Dammyla Araujo	Atualização [DOC-1348]
v. 32	27/04/2026 17:47	Dammyla Araujo	Revertida da versão 29
v. 31	27/04/2026 17:43	Dammyla Araujo
v. 30	27/04/2026 17:40	Dammyla Araujo
v. 29	09/04/2026 10:09	Dammyla Araujo	ajustes finos

Ir para o histórico da página

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