Histórico da Página

...

Necessário a instalação do serviço winthor-pedido-venda.
Todos os campos obrigatórios do cadastro de cliente (Rotina 302) serão obrigatórios na API.
O atributo activityId, caso não seja enviado, a API utilizará o valor padrão "1" do parâmetro 4013 - Código do ramo de atividade para cadastro de clientes na Ciashop (CODATVCIASHOP)na rotina 132.
O atributo cnaeId, caso não seja enviado, a API utilizar um valor padrão "4729-6/99" do parâmetro 4585- Código do CNAE para cadastro de clientes e-commerce. (CODCNAEECOMMERCE) na rotina 132.
No Winthor, acessar a rotina 132 - Parâmetros da Presidência, parâmetro 4532 - "Permite alterar o cliente ao receber dados para inserção via ecommerce/API" permite ou não alteração do cadastro de cliente de forma automática ao receber dados do cliente ou pedido via API, por padrão esse campo receberá 'Sim' sendo possível sua configuração por filial. No corpo da requisição o atributo "branchParameterId" é correspondente a filial que permite ou não a alteração.
Obrigatoriamente os cadastro de clientes oriundos da integração deverão informar o atributo "customerOrigin" igual a "VT" (VTEX)
Ao inserir um novo cadastro a API priorizará o CEP informado no atributo "commercialZipCode". Caso o CEP seja inválido e/ou a API (terceira de CEP) esteja indisponível, será considerado a Cidade informada "cityId" e posteriormente os atributos inseridos "businessCity", "businessState".
Ao integrar clientes será considerado o CNPJ/CPF e IE, se tiver um cadastro com o CNPJ/CPF validaremos a Inscrição estadual para cadastrar/alterar, caso seja uma nova Inscrição estadual, será integrado um novo cadastro.
O atributo "sellerId" , caso não seja enviado ou seu valor seja igual a 0, a API utilizará o valor padrão cadastrado no parâmetro "4012 - Código do RCA para cadastro de clientes na Ciashop" na rotina 132.
Ao inserir um novo registro, o valor do código RCA será registrado na coluna CODUSUR1 da tabela PCCLIENT, e em caso de alteração de um registro existente, o valor do código RCA será registrado na coluna CODUSUR3 da mesma tabela, mantendo o registro do código RCA inicial na coluna CODUSUR1.
O atributo documentType, caso não seja enviado, será gravado automaticamente como A, para AMBOS.
O parâmetro withDeliveryAddress dos endpoints de buscar clientes está disponível a partir da versão 1.2.0.1122 do winthor-pedido-venda

Aviso

title	Importante

Quando não houver preenchimento do campo DATA, exemplo (data de cadastro, data de alteração), nossas APIs retornará por padrão a informação "1900-01-01T00:00:00".

Caso necessário, realizar o ajuste nos cadastros para que a API apresente a data desejada.

Possíveis problemas:

Caso o ambiente esteja utilizando o antivírus Kaspersky, o serviço de consultas de cep que é realizado na integração de clientes VIACEP é bloqueado.

Exemplo de consultas do serviço VIACEP:

https://viacep.com.br/ws/35450000/json/

Para que o cadastro de clientes seja integrado com sucesso, é necessário verificar todas restrições referentes ao antivírus ou inativá-lo.

...

Totvs custom tabs box

tabs	Dados integrados com Winthor, Envio Parâmetros/Resposta da Requisição, Listar Dados Cliente
ids	passo1,passo2,passo3

A integração consiste em receber e enviar dados que serão utilizados no E-Commerce.

Totvs custom tabs box items

default	yes
referencia	passo1

Os dados integrados são:

API	Referência Winthor	Descrição	Tipo(Tamanho)	Obrigatório	Observações
CUSTOMER	PCCLIENT	Referência rotina 302
activityId	pcclient.codatv1	Código da atividade do Cliente - aba dados cadastrais	NUMBER(6,0)	Sim
addressInfo	pcclient.enderent			Não	Esse parâmetro só é retornado no GET da requisição. Não é utilizado para gravar informações;
billingAddress	pcclient.endercob	Endereço Cobrança - aba endereço cobrança	VARCHAR2(40,0)	Sim
billingAddressNumber	pcclient.numerocob	Numero do endereço de cobrança - aba endereço cobrança	VARCHAR2(6,0)	Não
billingDistrict	pcclient.bairrocob	Bairro - aba endereço cobrança	VARCHAR2(40,0)	Não
billingId	pcclient.codcob	Código de cobrança - aba posição financeira - valor padrão "D"	VARCHAR2(4,0)	Não
billingState	pcclient.estcob	Estado - aba endereço cobrança	VARCHAR2(2,0)	Não
billingZipCode	pcclient.cepcob	CEP - aba endereço cobrança	VARCHAR2(9,0)	Sim
branchParameterId	Filial de referência para considerar o parâmetro ALTERACLIAUTOECOMMERCE			Não
businessCity	pcclient.municent	Campo município - aba endereço comercial	VARCHAR2(15,0)	Não
businessCityId	pcclient.codcidadecom	Cidade - aba endereço entrega	NUMBER(6,0)	Não	Relaciona o ID da cidade cadastrado no banco de dados.
businessDistrict	pcclient.bairroent	Bairro - aba endereço comercial	VARCHAR2(40,0)	Sim
businessState	pcclient.estent	Estado - aba endereço entrega	VARCHAR2(2,0)	Não
cityId	pcclient.codcidade	Cidade	NUMBER(10,0)	Sim	Relaciona o ID da cidade cadastrado no banco de dados.
cnaeId	pcclient.codcnae	CNAE - aba capa	VARCHAR2(60,0)	Não
commercialAddress	pcclient.enderent	Endereço comercial - aba endereço comercial	VARCHAR2(40,0)	Sim
commercialAddressNumber	pcclient.numeroent	Numero do endereço comercial - aba endereço entrega	VARCHAR2(6,0)	Não
commercialZipCode	pcclient.cepcom	CEP - aba endereço entrega	VARCHAR2(9,0)	Sim
complementBillingAddress	pcclient.complementocob	Complemento endereço de cobrança - aba endereço cobrança	VARCHAR2(80,0)	Não
complementBusinessAddress	pcclient.complementoent	Complemento endereço de cobrança - aba endereço comercial	VARCHAR2(80,0)	Não
complementDeliveryAddress	pcclient.complementocom	Complemento endereço de cobrança - aba endereço entrega	VARCHAR2(80,0)	Não
corporate	pcclient.tipofj	Tipo de Pessoa - aba capa	VARCHAR2(1,0)	Sim	Campo Booleano. true é para pessoa jurídica("J") e false para pessoa física ("F"); Como padrão, caso parâmetro não seja enviado, será definido de acordo com o CGC informado, caso seja enviado um CPF será pessoa física ("F"), caso seja CNPJ será pessoa jurídica("J").
corporatePhone	pcclient.telent	Telefone - aba endereço comercial	VARCHAR2(13,0)	Não	O valor é criado na tabela 'pcclient.telent'.
deliveryPhone	pcclient.telcom	Telefone comercial - aba endereço de entrega	VARCHAR2(13,0)	Não	O valor é criado na tabela 'pcclient.telcom'.
billingPhone	pcclient.telcob	Telefone comercial - aba endereço de cobrança	VARCHAR2(13,0)	Não	O valor é criado na tabela 'pcclient.telcob'.
countryId	pcclient.codpais	Código do pais - aba endereço comercial	NUMBER(6,0)	Sim
createDate	pcclient.dtcadastro	Data e Hora de cadastro - aba dados cadastrais	DATE(7,0)	Sim	O formato correto de envio é: "yyyy-MM-dd'T'HH:mm:ss.SSS". Sendo: yyyy para ano com quatro dígitos, MM para mês com dois dígitos, dd para dia com dois dígitos, HH para hora com dois dígitos, mm para minutos com dois dígitos, ss para segundos com dois dígitos, e SSS para milésimos com três dígitos. Exemplo de input válido: "2021-12-02T15:35:20.003". Para 'CustomerOrigin' sendo 'VT', o campo não é obrigatório e pega os dados do de data e horário da requisição.
customerOrigin				Sim	Os valores aceitos para esse campo são: "VT" - VTEX; "WB" - WEB; "WTN" - Winthor não Web; "WTW" - WTA - Winthor Web; "N" - Nenhum;
deliveryAddress	pcclient.endercom	Endereço - aba endereço entrega	VARCHAR2(40,0)	Não
deliveryAddressNumber	pcclient.numerocom	Numero do endereço de entrega - aba endereço entrega	VARCHAR2(6,0)	Não
deliveryDistrict	pcclient.bairrocom	Bairro - aba endereço entrega	VARCHAR2(40,0)	Não
deliveryState	pcclient.estcom	Estado - aba endereço entrega	VARCHAR2(2,0)	Não
deliveryZipCode	pcclient.CEPENT	CEP - aba endereço COMERCIAL	VARCHAR2(9,0)	Não
document				Não
documentType*	pcclient.tipodocumento	Tipo de documento - aba condições comerciais - opções	VARCHAR2(1,0)	Não	Os valores aceitos são 'A' para Ambos, 'C' para Cupom ou 'N' para Nota Fiscal.
email	pcclient.email	E-mail - aba endereço comercial	VARCHAR2(100,0)	Sim
emailNfe	pcclient.emailnfe	E-mail NF-e - aba endereço comercial	VARCHAR2(3500,0)	Não	Caso esse parâmetro não seja enviado, será replicado o valor do campo 'email' para o 'emailNfe'.
finalCostumer	pcclient.consumidorfinal	Consumidor Final - aba condições comerciais - opções	VARCHAR2(1,0)	Não	Campo booleano. true para 'S', false para 'N'.
ibgeId	pccidade.codibge		NUMBER(10,0)	Não	Não é um campo obrigatório porém por redundância, o cliente pode envia-lo para verificar se o ID do IBGE existe no banco de dados. Campo utilizado no POST somente para validação de dados - e o envio deve ser feito pelo body como String.
id*	pcclient.codcli	Código - aba capa	VARCHAR2(9,0)	Não
lastChange	pcclient.dtultalter	Data e Hora da última alteração - aba dados cadastrais	DATE(7,0)	Sim	O formato correto de envio é: "yyyy-MM-dd'T'HH:mm:ss.SSS". Sendo: yyyy para ano com quatro dígitos, MM para mês com dois dígitos, dd para dia com dois dígitos, HH para hora com dois dígitos, mm para minutos com dois dígitos, ss para segundos com dois dígitos, e SSS para milésimos com três dígitos. Exemplo de input válido: "2021-12-02T15:35:20.003".
name	pcclient.cliente	Campo cliente - Nome do cliente - aba capa	VARCHAR2(60,0)	Sim
paymentPlanId	pcclient.codplpag	Plano de pagamento - aba condições comerciais - parâmetros	NUMBER(4,0)	Não
personIdentificationNumber	pcclient.cgcent	CNPJ/CPF - aba capa	VARCHAR2(18,0)	Sim
phone	*Não é gravado em tabela nenhuma	Telefone comercial - aba endereço comercial	VARCHAR2(13,0)	Não
sellerId	pcclient.codusur1	RCA 1 - Código do RCA	NUMBER(4,0)	Sim
squareId	pcclient.codpraca	Campo praça - endereço comercial	NUMBER(6,0)	Sim
stateInscription	pcclient.ieent	Ins. Est./ Produtor - aba dados cadastrais: Informar Inscrição Estadual. Caso não tenha, informar ISENTO.	VARCHAR2(15,0)	Sim
tradeName	pcclient.fantasia	Fantasia - aba capa	VARCHAR2(40,0)	Não
permissions.acceptValidateZipCodeOnline			boolean	Não	Default: true Em caso de 'false' a aplicação não irá validar se o CEP está valido em API terceiros (ViaCEP e ByJG) Obs: opção disponível a partir da versão: 1.2.0.1087

Observações da requisição POST:

Se a origem do pedido for "VT":

Será utilizado o CEP para preencher os dados do nome da cidade, nome do estado, e o bairro (tanto comercial, de cobrança e entrega). Caso os dados da API de consulta falhem, serão utilizados valores informados na requisição do corpo;
O parâmetro: "CommercialZipCode" irá definir os campos: 'CepComercial', 'CepEntrega' e 'CepCobranca'. Sendo assim, esses valores serão iguais;
O parâmetro: "ComplementBusinessAddress" irá definir os campos: 'ComplementoEnderecoComercial', 'ComplementoEnderecoEntrega' e 'ComplementoEndereçoCobranca'. Sendo assim, esses valores serão iguais;
O parâmetro: "CommercialAddressNumber" irá definir os campos: 'NumeroEnderecoComercial', 'NumeroEnderecoEntrega' e 'NumeroEnderecoCobrança'. Sendo assim, esses valores serão iguais;
O parâmetro: "CommercialAddress" irá definir os campos: 'EnderecoComercial', 'EnderecoEntrega' e 'EnderecoCobrança'. Sendo assim, esses valores serão iguais;
O parâmetro: "corporatePhone" irá definir os campos: 'Telefone comercial', 'TelefoneEntrega' e 'TelefoneCobranca'. Sendo assim, esses valores serão iguais;
O CNAE padrão será 4729-6/99;
Código Pais será 10581 que representa o Brasil;

Totvs custom tabs box items

default	no
referencia	passo2

Exemplo JSON do envio da requisição e dados do retorno:

Bloco de código

language	js
title	URI - Cadastrar Cliente

method: 'POST',
url: '/api/wholesale/v1/customer/'

Bloco de código

language	js
title	Body

{
    "corporate": true,
    "name": "string",
    "personIdentificationNumber": "string",
    "stateInscription": "string",
    "commercialAddress": "string",
    "businessDistrict": "string ",
    "commercialZipCode": "string",
    "email": "string",
	"emailNfe": "string",
    "customerOrigin": "VT",
    "finalCostumer": "false",
    "billingId": "string",
    "paymentPlanId":0,
    "commercialAddressNumber": "string",
    "billingAddressNumber": "string",
    "deliveryAddressNumber": "string",
    "squareId": 0,
    "activityId": 0,
    "complementBillingAddress": "string",
    "complementBusinessAddress": "string",
    "complementDeliveryAddress": "string",
    "BusinessCity": "string",
    "sellerId": 0,
    "businessCity": "string",
    "cityId": 0,
    "countryId": 0,
	"documentType": "A"
}

Exemplo JSON da resposta:

Bloco de código

language	js
title	Body Response

{
    "Id": 0
}

Bloco de código

language	js
title	Body Response - Error

{
    "code": "WT-PV-000000",
    "message": "Erro ao validar itens",
    "detailedMessage": "Lista de validações em details",
    "details": [
        {
            "code": "WT-PV-0000XX",
            "message": "Campo obrigatório",
            "detailedMessage": "Detalhes do campo obrigatório. ",
            "details": []
        }
    ]
}

Totvs custom tabs box items

default	no
referencia	passo3

Enviar as requisições conforme indicação abaixo para listar os cadastros existentes:

Bloco de código

language	js
title	URI Parameters - Listar um único cadastro

method: 'GET',
url: '/api/wholesale/v1/customer/'

*PARAMS:*
customerId  : 0      -    Informar o código do cliente withDeliveryAddresscliente 
withDeliveryAddress  : false - Informe para retornar os endereços de entregas do cliente

Bloco de código

language	js
title	URI Parameters - Listar todos cadastros

method: 'GET',
url: '/api/wholesale/v1/customer/list'

*PARAMS:*
withDeliveryAddress  : false     -    Informe para retornar os endereços de entregas do cliente

Bloco de código

language	js
title	Body Response - Exemplo para todos os casos

{
    "corporate": true,
    "name": "string",
    "personIdentificationNumber": "string",
    "stateInscription": "string",
    "commercialAddress": "string",
    "businessDistrict": "string ",
    "commercialZipCode": "string",
    "email": "string",
	"emailNfe": "string",
    "customerOrigin": "VT",
    "finalCostumer": "false",
    "billingId": "string",
    "paymentPlanId":0,
    "commercialAddressNumber": "string",
    "billingAddressNumber": "string",
    "deliveryAddressNumber": "string",
    "squareId": 0,
    "activityId": 0,
    "complementBillingAddress": "string",
    "complementBusinessAddress": "string",
    "complementDeliveryAddress": "string",
    "BusinessCity": "string",
    "sellerId": 0,
    "businessCity": "string",
    "cityId": 0,
    "countryId": 0,
	"documentType": "A",
	"phone": "string",
	"corporatePhone": "string",
	"billingPhone": "string",
	"deliveryPhone": "string",
    "deliveryAddresses": [
            "id": "number",
            "receiverName": "string",
            "receiverEmail": "string",
            "customerId": "number",
            "squareId": "number",
            "zipCode": "string",
            "state": "string",
            "city": "string",
            "district": "string",
            "address": "string",
            "complement": "string",
            "cityId": "number",
            "number": "number",
            "tradeName": "string",
            "lastChangeDate": "string",
            "receiverCountryId": "number",
            "receiverPhone": "number",
            "referencePoint": "string"
     ]
	"permissions":{
        "acceptValidateZipCodeOnline": false
    } 
}

...

Páginas filhas

Versões comparadas

Versão antiga 50

Nova versão 51

Chave

Possíveis problemas: