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: | CUSTOMER | PCCLIENT | Referência rotina 302 |
|
|
| | API | Referência Winthor | Descrição | Tipo(Tamanho) | Obrigatório | Observações |
|---|
| 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 os parâmetro ALTERACLIAUTOECOMMERCE e CODPRACACIASHOP |
|
| Não |
| | businessCity | pccidade.nomecidade | Campo município - aba endereço comercial | VARCHAR2(80,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.00302T00:00". | | 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 |
|
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 do país será 10581 1058 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 |
|---|
| {
"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
withDeliveryAddressbranchId : false - Informe para : 1,2 - Informar o(s) código(s) de filial(is) do cliente
withDeliveryAddress : false - Informe para retornar os endereços de entregas do cliente cliente |
| Bloco de código |
|---|
| language | js |
|---|
| title | URI Parameters - Listar todos cadastros |
|---|
| method: 'GET',
url: '/api/wholesale/v1/customer/list'
*PARAMS:*
withDeliveryAddress : false : false - Informe para retornar os endereços de entregas do cliente
branchId : 1,2 - Informe para retornar os endereços de entregasInformar o(s) código(s) de filial(is) 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) |
Observações da requisição ao consultar: - Em caso de não encontrar registro pelo CPF/CNPJ retornará o http status 404 com a descrição do erro: "Não foi possível encontrar os clientes com os dados informados: personIdentificationNumber: XPTO. Verifique se informou corretamente os dados e realize nova consulta."
- Caso o parâmetro finalCostumer ou personalType não seja enviado a lista de clientes não será filtrada, sendo assim trazendo todos os registro pois são parâmetros não obrigatórios.
- Caso o Cliente consultado esteja excluidio, o campo active será apresentado com valor 0 (zero). Indicativo de cliente inativo.
| 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",
"active": true,
"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
}
} |
|
|
