APIs Integrações - Clientes

Objetivo

Este documento tem como objetivo explicar o funcionamento da integração do Cadastro de Cliente.

Pré-Requisitos e Restrições

• Necessário a instalação do serviço winthor-pedido-venda. Para realizar a instalação desse serviço, segue link com as devidas explicações:

Comece por aqui -> Parametrizações WTA

• Para realizar o cadastro de clientes no WinThor, acesse o link abaixo:

Como cadastrar cliente na rotina 302?

• 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) da 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) da 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
• 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). Caso falso, essa validação não ocorrerá. 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 cliente (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

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

{
    "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"
}

{
    "Id": 0
}

{
    "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": []
        }
    ]
}

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

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

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

*PARAMS:*
withDeliveryAddress : false  - Informe para retornar os endereços de entregas do cliente  
finalCostumer       : String - Informe 'S' para retornar somente consumidor final e 'N' para não consumidor final (Não obrigatório) 
personalType        : String - Informe 'J' para retornar somente cliente pessoa jurídica e 'F' para somente pessoa física (Não obrigatório)

personIdentificationNumber   -  CPF ou CNPJ do cliente - * Disponível a partir da versão 1.3.0.1 (Versão de homologação)

{
    "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
    } 
}

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.