Todos os WebService que referente aos clientes e leads estão estão no caminho “/api/partnes/” ( de agora em diante todo WebService será representado pelo “/api/{serviço}” isso siginificar “http://{servidor}/api/{serviço}” ), abaixo listados estão os tópicos importantes a respeito do WebService.
Para todo e qualquer cadastro que exista existem registros que são uma relação com outro registros, e no cadastro de clientes não eh diferente. O WebSuite possui alguns serviços para caputrar os dados padrões para um novo registros e relacionados através do serviço abaixo :
SalesOneGET api/Partners/New.json?includeReference=true
O serviço dever retornar os dados padrões para campos do cliente e alguns registros que podem ser informados ao adastrar um novo registro, segue o retorno que se espera da chamada apresentada acima. “Os valores podem estar diferentes de acordo com cada configurações realizadas dentro do WebSuite”
//Lista de Cadastros Auxiliares
{
//Valor padrão configurado dentro do WebSuite para Tipo de Frete
"incotermsId" : 0,
//Valor padrão do usuário logado para o campo de vendedor
"SlpCode": -1,
//Campo padrão para o campo Grupo do Cliente
"GroupCode": 100,
//Código da Codição padrão para novos clientes
"GroupNum": -1,
//´Tipo de Cliente padrão para novos clientes
"CardType": 0,
//Código da Transportadora Padrão
"CarrierCode": "T000001",
//Formas de Pagamentos padrão para novos clientes,
"partnerPayMethods": [
{
//Códiog da Condição de Pagamento
"PymCode" : "Boleto"
},
{
//Códiog da Condição de Pagamentop
"PymCode" : "Boleto Banco do Brasil"
},
],
//Lista de Formas de Pagamento Disponiveis
"PayMethods" : [
{
//Código
"id": "Boleto",
//Descrição da Forma de Pagamento
"text": "Pagamento com Boelto"
}
],
//Lista de Municipios Disponiveis,
"counties": [
{
"absId": 0, //Campo que deve preenchido em Partner.PartnerAddress.County
"country": "String",
"ibgeCode": "String",
"name": "String",
"state": "String"
}
],
//Lista de Paises Disponiveis
"countries": [
{
"code": "String", //Campo que deve preenchido em Partner.PartnerAddress.Country
"name": "String"
}
],
//Lista de Grupos de Clientes Disponíveis
"partnerGroups": [
{
}
],
//Lista de Endereços Padrões para um novo cliente ( Quando for realizado consulta na sefaz ) ou pode-se consultar através do serviço /api/address/ByZipCode/{CEP}
"partnerAddresses": [
{
//Tipo de Endereço - 0 Endereço de Cobrança. 1 - Endereço de Faturamento
"addressType": 0,
//Tipo do Logradouro
"addrType": "String",
//Nome do Endereço - Alias para o endereço.: Explo : "Matriz"
"address": "String",
//Bairro
"block": "String",
//Complemento
"building": "String",
//Código do Cliente Caso o cliente já existi
"cardCode": "String",
//Pais
"country": "String",
//Municpio
"county": "String",
//Dedatlhes do Municiio
"countyName": {
"absId": 0,
"country": "String",
"ibgeCode": "String",
"name": "String",
"state": "String"
},
//Geolocalização do Endereçp
"glbLocNum": "String",
//Estado
"state": "String",
//Endereço
"street": "String",
//Número do Endereço
"streetNo": "String",
//CNPJ do Endereço Caso for depósito
"taxId0": "String",
//CEP
"zipCode": "String"
}
],
//Lista de Estados Disponiveis
"states": [
{
"code": "String", //Campo que deve preenchido em Partner.PartnerAddress.State
"country": "String",
"name": "String"
}
],
//Lista de Condições de Pagamento Disponíveis para Condições de Pagamento
"groupNums": [
{
//Código
"id": -1,
//Descrição da Forma de Pagamento
"text": "A vista"
}
],
//Lista de Preços Disponíveis para o campo ListNum
"PriceLists": [
{
//Código da Lista de PReço
"id": 1,
//Description
"text": ""
}
],
//Sugestão de Posição do Contato dentro da empresa
"contactPositions" : [
"Proprietários",
"Comprador"
],
//Caracteristicas disponíveis para o cliente
"PartnerProperties" : [
{
"id": 9,
"text": "Administração Pública"
},
{
"id": 2,
"text": "Armazenagem"
},
//...
],
}4
Há um serviço exclusivo para lista de transportadora disponíveis que pode ser objetida através de :
GET "/api/carriers.json"
E o seu resultado é uma lista de transportadora disponíveis para ser usado no cadastro do parceiros :
//Campo com a lista de Transportadora
data : [
{
//Código da Transportador
"cardCode": "T10001162",
//Razão Social da Transportadora
"cardName": "Exata Cargo Rodoviario F: 2954-0571",
//Nome Fantasia da Transporadora
"cardFName": "Exata Cargo Rodoviario F: 2954-0571",
//Telefone 1 da Transportadora
"phone1": "29540571",
//Telefone 1 da Transportadora que pode se também o DD
"phone2": "11",
}
]
Antes de realizar um procediemnto de novo cliente é possível verificar se o mesmo existe, é sempre uma boa pratica realizar esse procedimento antes de fazer um post para o novo cliente :
“/api/Partners/GetByTaxId/{CNPJ_OR_CPF}” o resultado será o cadastro do cliente descrito na seção do campos do cadastro do cliente ou um registro uma lista em branco.
Para ter um cadastro ‘saudável’ é necessário garantir que as informações presentes no cadastro de clientes estão corretas, para isso existem dois serviços auxiliares para checagem do cadastro.
"/api/Partners/GetByTaxId/{CNPJ_OR_CPF}?sefaz=true&state='{Código_da_UF_Exemplo:SP}'"
O resultado será o mesmo apresentado na seção ‘Obtento os valores padrões para um novo cliente’_
"/address/ByZipCode/{CEP}"
O resultado será um endereço completo do parceiro ou dados em brancos, representado que não foi encontrado valores, segue detalhes :
{
//Tipo de Endereço - 0 Endereço de Cobrança. 1 - Endereço de Faturamento
"addressType": 0,
//Tipo do Logradouro
"addrType": "String",
//Nome do Endereço - Alias para o endereço.: Explo : "Matriz"
"address": "String",
//Bairro
"block": "String",
//Complemento
"building": "String",
//Código do Cliente Caso o cliente já existi
"cardCode": "String",
//Pais
"country": "String",
//Municpio
"county": "String",
//Dedatlhes do Municiio
"countyName": {
"absId": 0,
"country": "String",
"ibgeCode": "String",
"name": "String",
"state": "String"
},
//Geolocalização do Endereçp
"glbLocNum": "String",
//Estado
"state": "String",
//Endereço
"street": "String",
//Número do Endereço
"streetNo": "String",
//CNPJ do Endereço Caso for depósito
"taxId0": "String",
//CEP
"zipCode": "String"
}
Para fazer um cadastro de um novo cliente deve ser usado o serviço a seguir
POST "api/Partnes"
Com os seguintes dados sendo passados para o serviço, (Lembre-se que para alguns campos, pode-se usar o padrão descrito na seção ‘Obtento os valores padrões para um novo cliente’_).
{
//Não eh Obrigátio quando se tratar de Novo Cliente
"cardCode": "String",
//Razão Social
"cardFName": "String",
//Nome Fantasia
"cardName": "String",
//Tipo de Cliente : 0 - Lead , 1 - Cliente ( Novos Sempre serão leads )
"cardType": 0,
//Código da Tranportador - Os códigos possíveis para esses campos devem ser capturados em /api/carriers
"carrierCode": "String",
//Celular
"cellular": "String",
//Tipo de Cliente : 0 - Pessoa Fisica / 1 - Juridica
"cmpPrivate": 0,
//Observações
"comments": "String",
//Desconto Especial - Somente se o usuário logado tiver acesso.
"discCustom": 0,
//Desconto do Paceiro - Somente se o usuário logado tiver acesso.
"discount": 0,
//E-Mail do Cliente é obrigatório
"e_Mail": "String",
//Caso tenha sido feito a consulta na sefaz em
// /api/partner/GetByTaxId/{CNPJ}?sefaz=true&uf={Estado}& deve passar true nesse campo
"fromSefaz": false,
//Grupo do Cliente : Caprutar os grupos disponiveis em /api/partnes/new conforme descrito na seção 1.1
"groupCode": 0,
//Condição de Pagamento : Caputar os grupos disponiveis em /api/partnes/new conforme descrito na seção 1.1
"groupNum": 0,
// 0 para CIF e 1 para FOB, : Existe um valor padrão apra esse campo que pode ser capturado em Caputar os grupos disponiveis em /api/partnes/new conforme descrito na seção 1.1
"incotermsId": 0,
// Site do Cliente
"intrntSite": "String",
// Taxa de Juros
"intrstRate": 0,
// Lista de preço, caso tenha acesso pode ser capturado através de /api/partnes/new ou deixe em branco para o WebSuite preenche-lo com o valor da resposta da query
"listNum": 0,
// Oversações curtas
"notes": "String",
// Lista de endereços do cliente, pode se repetir várias vezes, pode-se capturar o endereço atarvéz de /api/address/ByZipCode/{CEP}
"partnerAddresses": [
{
//Tipo de Endereço - 0 Endereço de Cobrança. 1 - Endereço de Faturamento
"addressType": 0,
//Tipo do Logradouro
"addrType": "String",
//Nome do Endereço - Alias para o endereço.: Explo : "Matriz"
"address": "String",
//Bairro
"block": "String",
//Complemento
"building": "String",
//Código do Cliente Caso o cliente já existi
"cardCode": "String",
//Pais
"country": "String",
//Municpio
"county": "String",
//Dedatlhes do Municiio
"countyName": {
"absId": 0,
"country": "String",
"ibgeCode": "String",
"name": "String",
"state": "String"
},
//Geolocalização do Endereçp
"glbLocNum": "String",
//Estado
"state": "String",
//Endereço
"street": "String",
//Número do Endereço
"streetNo": "String",
//CNPJ do Endereço Caso for depósito
"taxId0": "String",
//CEP
"zipCode": "String"
}
],
//Empresas que o cliente pode fazer pedido
"partnerCompanies": [
{
//Id da Empresa
"companyId": 0
}
],
//Contato dos paceiros
"partnerContacts": [
{
//Endereço
"address": "String",
//Telefone Celular
"cellolar": "String",
//E-mail
"e_Mail": "String",
//Primeiro Nome
"firstName": "String",
//Ultimo Nome
"lastName": "String",
//Nome do Mail
"middleName": "String",
//Nome do Contato
"name": "String",
//Posição ( Pode ser um valor novo ou as sugestão apresentada na seção 2.2 )
"position": "String",
//Telefone
"tel1": "String",
//Telefone
"tel2": "String",
//Titulo ( Sr(a), Dr(a), Pr.. etc )
"title": "String"
}
],
//Forma de Pagamento do Parceiro
"partnerPayMethods": [
{
"cardCode": "String",
"pymCode": "String"
}
],
//Telefone
"phone1": "String",
//Telefone
"phone2": "String",
//Forma de Pagamento Padrão ( Deve ser uma das presentes em partnerPayMethods )
"pymCode": "String",
//Todos os campos que qryGroup são uma referencia ao campo partnerProperties o id é o valor rpesente depois de qryGroup, por exemplo: O id da primeira característica é 1 , então o campo que deve ser preenchido com "Y" é qryGroup1... se caso não desejar habilitar essa característica preencha com "N" em qryGroup1 e assim por diante
"qryGroup1": "Y or N",
"qryGroup10": "Y or N",
"qryGroup11": "Y or N",
"qryGroup12": "Y or N",
"qryGroup13": "Y or N",
"qryGroup14": "Y or N",
"qryGroup15": "Y or N",
"qryGroup16": "Y or N",
"qryGroup17": "Y or N",
"qryGroup18": "Y or N",
"qryGroup19": "Y or N",
"qryGroup2": "Y or N",
"qryGroup20": "Y or N",
"qryGroup21": "Y or N",
"qryGroup22": "Y or N",
"qryGroup23": "Y or N",
"qryGroup24": "Y or N",
"qryGroup25": "Y or N",
"qryGroup26": "Y or N",
"qryGroup27": "Y or N",
"qryGroup28": "Y or N",
"qryGroup29": "Y or N",
"qryGroup3": "Y or N",
"qryGroup30": "Y or N",
"qryGroup4": "Y or N",
"qryGroup5": "Y or N",
"qryGroup6": "Y or N",
"qryGroup7": "Y or N",
"qryGroup8": "Y or N",
"qryGroup9": "Y or N",
//Ednereço Padrão de Entrega, deve ser um valor presente em partnerAddress.address
"shipToDef": "String",
//Código do Vendedor, pode-se capturar o valor padrão presente em
"slpCode": 0,
//Endereço Padrão de Entrega, deve ser um valor presente em partnerAddress.address
"billToDef": "String",
//CNPJ do Parceiro
"taxId0": "String",
//Inscrição Estadual, quando não houver IE deve ser preenchido com o valor "Isento"
"taxId1": "String",
//CPF, quando se tratar de pessoa física
"taxId4": "String",
}
O resultado dessa chamada será o retorno do cadastro completo do cliente caso obtiver sucesso na requisição (Status 201) ou a mensagem de erro que será reportado na propriedade responseStatus (Status 40x) conforme reportado an seção ‘Caminho do WebSuite e status das requisições’_
O serviço para obter o cliente está presente em :
GET /api/Partners
{
//Número da Página (geralemnte usado somente depois da primeira consutla) padrão sempre 1
"pageNumber":1,
//Tamanho da página, quantidade de registro por consulta padrão 30
"pageSize":30,
//Texto do Filtro, pode ser qualquer informação que deseja, por exemplo: "José Silva"
"queryForAnyField":"String",
//Campo de Ordenação, por exemplo: Código do Cliente
"sortBy":"cardCode",
//Ordem da ordenação, asc ou desc
"sortOrder":"asc",
}
o resultado será alog parecido com
{
//Quantidade de Página
"totalPages":0,
//Total de Registros
"totalRows":0,
//Número da Página Consultada
"pageNumber":0,
//Tamanho de Cada Página
"pageSize":0,
//Valor que foi consultado
"queryForAnyField": "String",
//Campo que foi ordenado
"sortBy":"String",
//Tipo de Ordenação que foi realizado
"sortOrder":"String"
//Resultado da Consulta, pode ter 1 ou mais registros
[
{
//Não há necessidade de repetir detalhadamente todos os campos do cliente, haja vista que o mesmos estão representados nas seção acima
//.... Campos do Cliente ....
},
],
}
E para obter um determinado cliente pelo seu código basta realizar um chamada ao WebService :
GET /api/Partners/{"Código_do_Cliente-CardCode"}
E o resultado será um NotFound (Status 404) ou os dados do clientes (Status 200) com os valores do cliente apresentada nas seções anteriores.
O processo de atualização é igual ao processo realizado em ‘Realizando cadastro de um novo cliente ‘ com a seguinte operação diferente, o verbo HTTP, e para fazer uma atualização do cadastro de cliente deve ser usado o serviço a seguir :
PUT "api/Partners"
Os campos a serem enviados para essa chamada são extamente os mesmo presentes em ‘Realizando cadastro de um novo cliente’_ sendo que o campo código é obrigatório.
Somente será possível excluir Leads que não tenham nenhum tipo de pedidos ou qualquer outro tipo de operação, ou seja, um cliente do tipo prospect que não tenha sido realizado qualquer outra operção senão um novo cadastro.
DELETE "/api/Partners/{Códig_do_Cliente-CardCode}"