Objetivo
Este documento tem como objetivo explicar o funcionamento da integração do Cadastro de Endereço de entrega.
Pré-Requisitos e Restrições
- Necessário a instalação do serviço winthor-pedido-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 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". O padrão do parâmetro é "Sim";
Integração
A integração consiste em receber e enviar dados que serão utilizados no E-Commerce.
Os dados integrados são:
DELIVERY ADDRESS | PCCLIENTENTEND | Referência rotina 3324 | |||
API | Referência Winthor | Descrição | Tipo(Tamanho) | Obrigatório | Observações |
---|---|---|---|---|---|
receiverName | PCCLIENTENTEND.RAZAORECEBEDOR | Nome/Razão Social do Recebedor da mercadoria | VARCHAR2(60,0) | Não | |
receiverEmail | PCCLIENTENTEND.EMAILRECEBEDOR | E-mail do Recebedor da mercadoria | VARCHAR2(60,0) | Não | |
customerId | PCCLIENTENTEND.CODCLI | Código do cliente ao qual o endereço de entrega está vinculado | NUMBER(9,0) | Sim | |
squareId | PCCLIENTENTEND.CODPRACAENT | Código da praça | NUMBER(6,0) | Não | |
date | PCCLIENTENTEND.DTCADASTRO | Data de cadastro do registro | DATE | Não | Se não enviado, será assumida a data no instante em que a requisição foi realizada; |
lastChangeDate | PCCLIENTENTEND.DTULTALTER | Identifica quando foi feita a última alteração | DATE | Não | Se não enviado, será assumida a data no instante em que a requisição foi realizada; |
zipCode | PCCLIENTENTEND.CEPENT | CEP de entrega | VARCHAR2(9,0) | Sim | Necessário para a consulta das outras informações na API de terceiros VIACEP |
state | PCCLIENTENTEND.ESTENT | Estado de entrega | VARCHAR2(2,0) | Não | Caso o 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. |
city | PCCLIENTENTEND.MUNICENT | Cidade de entrega | VARCHAR2(15,0) | Não | Caso 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. |
district | PCCLIENTENTEND.BAIRROENT | Bairro de entrega | VARCHAR2(40,0) | Não | Caso 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. |
address | PCCLIENTENTEND.ENDERENT | Endereço de entrega | NUMBER(40,0) | Não | |
complement | PCCLIENTENTEND.COMPLEMENTOENT | Complemento de entrega | VARCHAR2(60,0) | Não | |
cityId | PCCLIENTENTEND.CODCIDADE | Código da cidade de entrega | NUMBER(6,0) | Não | |
number | PCCLIENTENTEND.NUMEROENT | Número do endereço de entrega | VARCHAR2(6,0) | Não | |
regionNumber | PCCLIENTENTEND.NUMREGIAO | Caso 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,0) | Não | |
observation | PCCLIENTENTEND.OBSERVACAO | Observações do cadastro de endereço de entrega | VARCHAR2(4000,0) | Não | |
tradeName | PCCLIENTENTEND.FANTASIA | Nome Fantasia para identificação do estabelecimento de entrega | VARCHAR2(100,0) | Não | |
receiverZipCode | PCCLIENTENTEND.CEPRECEBEDOR | CEP do Recebedor da mercadoria | VARCHAR2(9,0) | Não | |
receiverCountryId | PCCLIENTENTEND.CODPAISRECEBEDOR | Código do pais do Recebedor da mercadoria | NUMBER(6,0) | Não | |
receiverPhone | PCCLIENTENTEND.FONERECEBEDOR | Telefone do Recebedor da mercadoria | NUMBER(14,0) | Não | |
receiverStateInscription | PCCLIENTENTEND.IERECEBEDOR | Inscrição estadual do Recebedor da mercadoria | NUMBER(14,0) | Não | |
latitude | PCCLIENTENTEND.LATITUDE | Indica a Latitude | VARCHAR2(20,0) | Não | |
longitude | PCCLIENTENTEND.LONGITUDE | Indica a Longitude | VARCHAR2(20,0) | Não | |
referencePoint | PCCLIENTENTEND.PONTOREFER | Indica o Ponto de Referência | VARCHAR2(80,0) | Não | |
customerOrigin | - | Origem do cliente | VARCHAR2(3,0) | Sim | ("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;
method: 'POST', url: '/api/wholesale/v1/customer/deliveryAddress'
{
"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,
"receiverStateInscription":0,
"observation":""
}
Exemplo JSON da resposta:
{ "Id": 0 }
Para que seja realizada uma nova integração atualizando um registro já integrado, o sistema verifica o CPF/CNPJ. Portanto, ao realizar alguma alteração no registro, ele será encaminhado novamente para a view para manter a integridade dos dados do ERP com o E-commerce.