TOTVS Distribuição e Varejo - linha Winthor

Páginas filhas
  • APIs Integrações - Endereço de entrega

Versões comparadas

Versão antiga 2

changes.mady.by.user Beatriz Menezes de Oliveira

Gravado em

comparado com

Nova versão Atual

changes.mady.by.user Beatriz Menezes de Oliveira

Gravado em

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

...

  • Necessário a instalação do  serviço winthor-pedido-venda. venda   ( Versão >= 1.2.0.1126)
  • Todos os campos obrigatórios do cadastro de endereço de entrega (Rotina 3324) serão obrigatórios na API.
  • Formato aceito para os campos de data: "AAAA-MM-DDTHH:MM:SS";
  • No WinThor, o parâmetro  4672 - Aceita validar CEP online nas APIs do WinThor da rotina 132 permite validar se o CEP informado está valido em API terceiros (ViaCEP e ByJG). Se o parâmetro estiver como "Sim" a Ao inserir um novo cadastro a API, caso seja permitido a validação online do cep (atributo "acceptValidateZipCodeOnline" igual a true), a aplicação consultará na api de terceiros VIACEP (https://viacep.com.br/) o CEP informado no atributo "zipCode", e priorizará as informações de cidade, estado, e bairro retornada por ela. Do contrário, se não permitida a validação online serão mantidas as informações enviadas nos atributos "state","city" e "district".Formato aceito para os campos de data: "AAAA-MM-DDTHH:MM:SS"  O padrão do parâmetro é "Sim";
  • Para que seja realizada a busca automática da praça do cliente, o parâmetro 4680 - Permite busca automática do código da praça no cadastro do cliente via API Winthor da rotina 132 deve estar habilitado. Para esse parâmetro existe a seguinte regra:
    • Caso o parâmetro 4680 da rotina 132 esteja habilitado (sim), a API irá consultar o código da praça no cadastrado na rotina 572 do Winthor através do CEP do endereço de entrega (a API irá buscar o código cujo CEP está entre CEP inicial e CEP final cadastrado na rotina 572);
      • Caso não encontrado pelo intervalo de CEP, a API pegará o código do parâmetro 4011 - Código da praca para cadastro de clientes na Ciashop  da rotina 132, e caso o mesmo esteja nulo irá setar o valor padrão 1;
    • Caso o parâmetro 4680 da rotina 132 esteja desabilitado (não), a API irá considerar o que foi enviado na requisição (atributo squareId), e caso o mesmo seja nulo ou zero, irá setar o valor padrão 1;

Integração


VARCHAR2(6
Totvs custom tabs box
tabsDados integrados com Winthor, Envio Parâmetros/Resposta da Requisição
idspasso1,passo2

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

Totvs custom tabs box items
defaultyes
referenciapasso1

Os dados integrados são: 

DELIVERY ADDRESS              PCCLIENTENTENDReferência rotina 3324


APIReferência Winthor DescriçãoTipo(Tamanho)ObrigatórioObservações
activityIdpcclient.codatv1

Código da atividade do Cliente - aba dados cadastrais

NUMBER(6,0)Sim
branchParameterIdFilial de referência para considerar o parâmetro CODPRACACIASHOP



receiverNamePCCLIENTENTEND.RAZAORECEBEDOR

Nome/Razão Social do Recebedor da mercadoria

VARCHAR2(60
addressInfopcclient.enderent

Não

Esse parâmetro só é retornado no GET da requisição. Não é utilizado para gravar informações;billingAddresspcclient.endercobEndereço Cobrança - aba endereço cobrançaVARCHAR2(40,0)SimbillingAddressNumberpcclient.numerocobNumero do endereço de cobrança - aba endereço cobrança
,0)Não
billingDistrict

receiverEmail
pcclient
PCCLIENTENTEND.
bairrocob
EMAILRECEBEDOR
Bairro - aba endereço cobrança
E-mail do Recebedor da mercadoriaVARCHAR2(
40
60,0)

Não

billingId

customerId
pcclient
PCCLIENTENTEND.
codcob
CODCLICódigo
de cobrança - aba posição financeira - valor padrão "D"
do cliente ao qual o endereço de entrega está vinculadoNUMBER(9
VARCHAR2(4
,0)
Não
Sim
billingState

squareId
pcclient
PCCLIENTENTEND.
estcob
CODPRACAENTCódigo da praçaNUMBER(6
Estado - aba endereço cobrançaVARCHAR2(2
,0)Não
billingZipCode

date
pcclient
PCCLIENTENTEND.
cepcobCEP - aba endereço cobrançaVARCHAR2(9,0)SimbranchParameterIdFilial de referência para considerar o parâmetro ALTERACLIAUTOECOMMERCENãobusinessCitypcclient.municentCampo município - aba endereço comercialVARCHAR2(15,0)Não
DTCADASTROData de cadastro do registroDATENãoSe não enviado, será assumida a data no instante em que a requisição foi realizada;
lastChangeDatePCCLIENTENTEND.DTULTALTERIdentifica quando foi feita a última alteraçãoDATE

Não

Se não enviado, será assumida a data no instante em que a requisição foi realizada;
zipCodePCCLIENTENTEND.CEPENTCEP de entregaVARCHAR2(9,0)

Sim

Necessário para a consulta das outras informações na API de terceiros VIACEP
statePCCLIENTENTEND.ESTENTEstado de
businessCityIdpcclient.codcidadecomCidade - aba endereço entregaNUMBER(6,0)NãoRelaciona o ID da cidade cadastrado no banco de dados.businessDistrictpcclient.bairroentBairro - aba endereço comercialVARCHAR2(40,0)SimbusinessStatepcclient.estentEstado - aba endereço
entregaVARCHAR2(2,0)
NãocityIdpcclient.codcidadeCidadeNUMBER(10,0)

Sim

Relaciona
Caso o
ID da cidade cadastrado no banco de dados.cnaeIdpcclient.codcnaeCNAE - aba capaVARCHAR2(60,0)NãocommercialAddresspcclient.enderentEndereço comercial - aba endereço comercialVARCHAR2(40,0)SimcommercialAddressNumberpcclient.numeroentNumero do endereço comercial - aba endereço entregaVARCHAR2(6,0)NãocommercialZipCodepcclient.cepcomCEP - aba endereço entregaVARCHAR2(9,0)Sim
parâmetro 4672 da rotina 132 esteja marcado como sim, o campo não precisa ser enviado pois será gravado o estado retornado na API de terceiros VIACEP. Do contrário, o campo deve ser enviado na requisição.
cityPCCLIENTENTEND.MUNICENTCidade de entregaVARCHAR2(15,0)SimCaso o parâmetro 4672 da rotina 132 esteja marcado como sim, o campo não precisa ser enviado pois será gravada a cidade retornada na API de terceiros VIACEP. Do contrário, o campo deve ser enviado na requisição.
districtPCCLIENTENTEND.BAIRROENTBairro de entregaVARCHAR2(40,0)SimCaso o parâmetro 4672 da rotina 132 esteja marcado como sim,  o campo não precisa ser enviado pois será gravado o bairro retornado na API de terceiros VIACEP. Do contrário, o campo deve ser enviado na requisição.
addressPCCLIENTENTEND.ENDERENTEndereço de entregaNUMBER(40,0)Sim
complementPCCLIENTENTEND.COMPLEMENTOENTComplemento de entregaVARCHAR2(60,0)Não
cityIdPCCLIENTENTEND.CODCIDADECódigo da cidade de entrega
complementBillingAddresspcclient.complementocobComplemento endereço de cobrança - aba endereço cobrançaVARCHAR2(80,0)NãocomplementBusinessAddresspcclient.complementoentComplemento endereço de cobrança - aba endereço comercialVARCHAR2(80,0)NãocomplementDeliveryAddresspcclient.complementocomComplemento endereço de cobrança - aba endereço entregaVARCHAR2(80,0)Nãocorporatepcclient.tipofjTipo de Pessoa - aba capaVARCHAR2(1,0)SimCampo 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").corporatePhonepcclient.telentTelefone - aba endereço comercialVARCHAR2(13,0)NãoO valor é criado na tabela 'pcclient.telent'.deliveryPhonepcclient.telcomTelefone comercial - aba endereço de entregaVARCHAR2(13,0)NãoO valor é criado na tabela 'pcclient.telcom'.billingPhonepcclient.telcobTelefone comercial - aba endereço de cobrançaVARCHAR2(13,0)NãoO valor é criado na tabela 'pcclient.telcob'.countryIdpcclient.codpaisCódigo do pais - aba endereço comercial
NUMBER(6,0)Sim
createDatepcclient.dtcadastroData e Hora de cadastro - aba dados cadastraisDATE(7,0)SimO 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.customerOriginSimOs valores aceitos para esse campo são: "VT" - VTEX; "WB" - WEB; "WTN" - Winthor não Web; "WTW" - WTA - Winthor Web; "N" - Nenhum;deliveryAddresspcclient.endercomEndereço - aba endereço entrega
Caso não enviado é realizada uma busca pelo código do IBGE (retornado na validação online do CEP, no caso do parâmetro 4672 estar marcado como sim) e se não encontrado é feita a busca pelo nome da cidade e estado;
numberPCCLIENTENTEND.NUMEROENTNúmero do endereço de entregaVARCHAR2(6
VARCHAR2(40
,0)Não
deliveryAddressNumber

regionNumber
pcclient
PCCLIENTENTEND.
numerocomNumero do endereço de entrega - aba endereço entrega
NUMREGIAOCaso sistema trabalhe com tributação por endereço de entrega, e não utilize tributação por UF, no momento do cálculo dos impostos, será utilizada a região do endereço de entrega para impostos.NUMBER(4
VARCHAR2(6
,0)Não
deliveryDistrict

observation
pcclient
PCCLIENTENTEND.
bairrocom
OBSERVACAOObservações do cadastro de endereço de
Bairro - aba endereço
entregaVARCHAR2(
40
4000,0)Não
deliveryState

tradeName
pcclient
PCCLIENTENTEND.
estcom
FANTASIANome Fantasia para identificação do estabelecimento de
Estado - aba endereço
entregaVARCHAR2(
2
100,0)Não
deliveryZipCode

receiverZipCode
pcclient
PCCLIENTENTEND.
CEPENT
CEPRECEBEDORCEP
- aba endereço COMERCIAL
do Recebedor da mercadoriaVARCHAR2(9,0)Não
documentNãodocumentType*pcclient.tipodocumentoTipo de documento - aba condições comerciais - opções

receiverCountryIdPCCLIENTENTEND.CODPAISRECEBEDORCódigo do pais do Recebedor da mercadoriaNUMBER(6
VARCHAR2(1
,0)Não
Os valores aceitos são 'A' para Ambos, 'C' para Cupom ou 'N' para Nota Fiscal.emailpcclient.emailE-mail - aba endereço comercial

receiverPhonePCCLIENTENTEND.FONERECEBEDORTelefone do Recebedor da mercadoriaNUMBER(14
VARCHAR2(100
,0)
Sim
Não
emailNfe

receiverStateInscription
pcclient
PCCLIENTENTEND.
emailnfeE-mail NF-e - aba endereço comercial
IERECEBEDORInscrição estadual do Recebedor da mercadoriaNUMBER(14
VARCHAR2(3500
,0)Não
Caso esse parâmetro não seja enviado, será replicado o valor do campo 'email' para o 'emailNfe'.finalCostumerpcclient.consumidorfinalConsumidor Final  - aba condições comerciais - opções

latitudePCCLIENTENTEND.LATITUDEIndica a LatitudeVARCHAR2(20
VARCHAR2(1
,0)Não
Campo booleano. true para 'S', false para 'N'.

longitudePCCLIENTENTEND.LONGITUDEIndica a LongitudeVARCHAR2(20
ibgeIdpccidade.codibgeNUMBER(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.

referencePointPCCLIENTENTEND.PONTOREFERIndica o Ponto de ReferênciaVARCHAR2(80
id*pcclient.codcliCódigo - aba capaVARCHAR2(9
,0)Não
lastChangepcclient.dtultalterData e Hora da última alteração - aba dados cadastraisDATE(7,0)SimO 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". namepcclient.clienteCampo cliente - Nome do cliente - aba capa

customerOrigin-Origem do clienteVARCHAR2(3
VARCHAR2(60
,0)Sim
paymentPlanIdpcclient.codplpagPlano de pagamento - aba condições comerciais  - parâmetrosNUMBER(4,0)NãopersonIdentificationNumberpcclient.cgcentCNPJ/CPF - aba capaVARCHAR2(18,0)Simphone*Não é gravado em tabela nenhumaTelefone comercial - aba endereço comercialVARCHAR2(13,0)NãosellerIdpcclient.codusur1RCA 1 - Código do RCANUMBER(4,0)SimsquareIdpcclient.codpracaCampo praça - endereço comercialNUMBER(6,0)SimstateInscriptionpcclient.ieentIns. Est./ Produtor - aba dados cadastrais: Informar Inscrição Estadual. Caso não tenha, informar ISENTO. VARCHAR2(15,0)SimtradeNamepcclient.fantasiaFantasia - aba capaVARCHAR2(40,0)Nãopermissions.acceptValidateZipCodeOnlinebooleanNã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
("VT", "Vtex"), ("WB", "Web"), ("WTN", "Winthor não Web"), ("WTW", "WTA - Winthor Web"), ("N", "Nenhum"); Só haverá consulta de informações complementares na API de terceiros VIACEP (cidade, estado e bairro) se a origem for igual a "VT";



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.  Caso os dados da API de consulta falhem, serão utilizados valores informados na requisição do corpo;
  • Código Pais será 1058 que representa o Brasil;


Exemplo JSON do envio da requisição e dados do retorno:
Totvs custom tabs box items
defaultno
referenciapasso2
{
Bloco de código
languagejs
titleURI - Cadastrar ClienteEndereço 
method:  'POST',
url:  '/api/wholesale/v1/customer/deliveryAddress'
Bloco de código
languagejs
titleBody


{
    "receiverName":"",


    "receiverEmail":"",


    "customerId":0,


    "squareId":

0,


    "date":

"2022-10-04T20:05:12",


    "lastChangeDate":

"2022-10-04T20:05:12",


    "zipCode":

0000000,


    "state":

"",


    "city":"",


    "district":"",


    "address":"",


    "complement":"",


    "cityId":0,


    "number":"",


    "regionNumber":0,


    "customerOrigin":"VT",


    "tradeName":"",


    "receiverZipCode":"",


    "receiverCountryId":0,


    "receiverPhone":0,


    "latitude":"",


    "longitude":"",


    "referencePoint":"0",


    "ibgeId":0,

"permissions": { "acceptValidateZipCodeOnline":true }


    "receiverStateInscription":0,
    "observation":""
}

Exemplo JSON da resposta:  

Bloco de código
languagejs
titleBody Response 
{
    "Id": 0
}

...