Comparação de Páginas

...

e
View file
name entidade.json

...

Objetivo

Detalhar o uso de API de Inclusão de Clientes

Uso Geral

Obter token autenticação

Introdução

Qualquer webservice do projeto SispetroWeb exigirá um token de autenticação. Este token é gerado a partir deste webservice e será válido por 24 horas. Assim, recomendamos que o sistema consumidor dos webservices aqui descritos salvem o token armazenando também a data e hora em que ele foi gerado para que, quando chegar próximo de sua validade, seja obtido novo token.

Para mais informações, ver Documentação - API Obtenção de Token

Métodos de Cadastros

1. Inclusão ou edição de clientes

Introdução

Este webservice tem por finalidade a inclusão ou alteração de UM cliente. Como alguns campos são preenchidos conforme o perfil de empresas, é necessário informar a empresa ao obter o token.

Nota

Para utilizar esta API, o usuário deve ter permissão para incluir clientes. Para verificar esta permissão, ele deve acessar a manutenção de usuários, localizar o usuário que está utilizando na API e ver na aba SispetroApp como está a configuração para inclusão de clientes (não pode, ver sistema ou pode). Para mais informações, ver Painel SispetroApp

Caso o valor seja “Ver Sistema” Ver Sistema, ir na manutenção de empresas, aba SispetroApp e ver qual valor está configurado para a permissão de inclusão de clientes (pode ou não pode). Para mais informações, ver SispetroApp (Usuários)

Endereços

Inclusão: <endereço do SispetroWeb>/entidade
Alteração: <endereço do SispetroWeb>/entidade/<campo CodEnt da entidade>

Parâmetros

Será necessário enviar um header com o token e no corpo do webservice (body) os dados relativos ao cliente que se deseja incluir ou alterar.

...

Chave	Conteudo	Pai	Obrigatório
entidade	fixo	-	Sim
CGC	CNPJ ou CPF com máscara	entidade	Sim se dentro País
NomeUsual	Nome Usual do Cliente	entidade
RzSocial	Razão Social	entidade	Sim
IE	Inscrição Estadual	entidade	Sim
ConsumidorFinal	0 - Não, 1 - Sim (se não informado será preenchido com 0)	entidade
InscricaoMunicipal	Inscrição Municipal	entidade
Endereco	Endereço	entidade	Sim
Numero	Número com até 8 caracteres	entidade	Sim
Complemento	Complemento do Endereço	entidade
Bairro	Bairro	entidade	Sim
CodigoDNC	Código IBGE do Município (formato 999.999-9)	entidade	Sim
Municipio	Descrição do Município	entidade	Sim
UF	UF	entidade	Sim
CEP	Formato 99999-999	entidade	Sim
Latitude	Latitude do endereço	entidade
Longitude	Longitude do endereço	entidade
CodPais	Código do País (se não informado será 1058 - Brasil)	entidade
Fone	Telefone (com DDD)	entidade
OutrosFones	Campo texto contendo os demais telefones	entidade
EMail	E-mail de uso geral	entidade	Sim
Bloqueado	0 - Não, 1 - Sim	entidade
SeqBloqueio	Código do bloqueio para uso na inclusão via API	entidade	Sim se Bloqueado for 1
DtCad	Data do Cadastro	entidade
DataAlteracaoCad	Data de Alteração do Cadastro	entidade
DPMP_CodigoInstalacao	Código Instalação na ANP	entidade
HorarioEntregaInicial	Horário Inicial para Entrega	entidade
HorarioEntregaFinal	Horário Final para Entrega	entidade
LimCred	Limite de Crédito	entidade	Este campo só será alterado ou preenchido caso o usuário tenha permissão conforme perfil `'ckbAlteraLimiteCredito'`
CodPg	Código da Condição de Pagamento	entidade
CodTpCobr	Código do Tipo de Cobrança	entidade
Vendedor	Código do Vendedor	entidade
AtividadeEconomica	Uma letra que representa a Atividade econômica de uso exclusivo do Sispetro (P - Posto, G - Consumidor Final, T - TRR, C - Congênere e O - Órgão Público)	entidade
SubstitutoTributario	Código da Categoria do Estabelecimento (uso no Scanc)	entidade
SeqTipo	Código do Tipo de Cliente	entidade
BloqueiaEntregaRetira	0 - Não bloqueia, 1 - Bloqueia Entrega, 2 - Bloqueia Retira	entidade
IDRegiaoVendas	Código da Região de Vendas	entidade
PermiteEntregaCarreta	Permite entrega de carreta ( 0 - Não, 1 - Sim)	entidade
CdPrefFat	Sequencial do Endereço de faturamento (conforme lista Enderecos)	entidade
CdPrefEnt	Sequencial do Endereço de faturamento (conforme lista Enderecos)	entidade
CdPrefCob	Sequencial do Endereço de faturamento (conforme lista Enderecos)	entidade
Enderecos	list	entidade
Seq	Id do endereço	Enderecos	Sim no caso de edição. Na inclusão, não enviar.
Endereco	Endereço	Enderecos
Numero	Número com até 8 caracteres	Enderecos
Complemento	Complemento do Endereço	Enderecos
Bairro	Bairro	Enderecos
CodigoDNC	Código IBGE do Município (formato 999.999-9)	Enderecos
Municipio	Descrição do Município	Enderecos
UF	UF	Enderecos
CEP	Formato 99999-999	Enderecos
CodPais	Latitude do endereço	Enderecos
Latitude	Longitude do endereço	Enderecos
Longitude	Código do País (se não informado será 1058 - Brasil)	Enderecos
Fone	Telefone (com DDD)	Enderecos
CNPJ	CNPJ do endereço	Enderecos
documento	IE do endereço	Enderecos
RzSocial	Razão Social para o endereço	Enderecos
galonagens	list	entidade
Sequencial	ID da Galonagem (chave primária)	galonagens	Sim no caso de edição. Na inclusão, não enviar.
Produto	Código do Produto no Sispetro	galonagens
Qtde	Qtde em Litros	galonagens
M3	Qtde em M3	galonagens
comprador	Código do Cliente que é o responsável pelo Grupo Econômico. Se não informado será o próprio cliente.	entidade
layout_estendido	0 = retorna somente dados do registro (padrão), 1 = retorna dados adicionais do cliente (layout descrito abaixo)	entidade

Métodos

Inclusão: POST
Alteração: PUT

Exemplo de arquivo json para envio em

View file

name	entidade.json

.

Exemplo de chamada de WebService

Bloco de código

# alteração do cliente código 6426
curl -H "Content-Type: application/json" -H "Accept: application/json" -H 
"Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZF91c3VhcmlvIjozMiwiY25waiI6IjAzLjk4MC43NTQvMDAwMy0wNSIsImRlcG9zaXRvX3BhZHJhbyI6IjEiLCJleHAiOjE3MjMxMjc2MzF9.-lJY1DvvjMPd9W1zc2j1ZPBIZHfIT4j_r881t8BibPI" 
-X PUT http://localhost/entidade/6426 -d@entidade.json

#inclusão de um cliente novo
curl -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZF91c3VhcmlvIjozMiwiY25waiI6IjAzLjk4MC43NTQvMDAwMy0wNSIsImRlcG9zaXRvX3BhZHJhbyI6IjEiLCJleHAiOjE3MjMxMjc2MzF9.-lJY1DvvjMPd9W1zc2j1ZPBIZHfIT4j_r881t8BibPI" 
-X POST http://localhost/entidade -d@entidade.json

Retorno Bem Sucedido

Serão retornados os dados do cliente se ele for incluído com sucesso. O status da resposta sempre será 200.

...

Bloco de código
{"CodEnt":1,"CNPJ":01.000.000/0001-99,"RzSocial":FULANO DE TAL,...

Retorno Sem Sucesso

Será retornado um objeto JSON com o motivo da não inclusão (poderá ser um erro de autenticação caso o token tenha expirado ou seja inválido ou alguma regra de negócio não atendida. O status da resposta sempre será diferente de 200.

Bloco de código
{"error":"Cliente... e valido","status":422}

2. Dados Gerais de Cliente

Introdução

Este webservice tem por finalidade retornar dados de UM cliente. Não é necessário informar a empresa ao obter o token.

Nota
Para acessar este método, o usuário deverá ter a permissão de usuário conforme perfil `ckb_permite_visualizar_clientes`

Endereço

<endereço do SispetroWeb>/entidade/get_entidade_api?id=<id da entidade>

Parâmetros

Será necessário enviar um header com o token. Como parâmetro enviar:

...

Nome	Descritivo	Exemplo
Authorization	Conteúdo do token obtido no passo de autenticação do usuário	eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZF91c3VhcmlvIjozMiwiY25waiI6IjAxLjgwNC4zNDUvMDAwMS02MCIsImV4cCI6MTUwMDA1MzYxN30.-ZvhWFYI8fyx66b3kZY1UVUrfaWUTioV3_M6K2wiPGM
Content-Type	tipo do formato de envio	application/json
Accept	tipo do formato de envio	application/json

Método

GET

Exemplo de chamada de WebService

Bloco de código

curl -H "Content-Type: application/json" -H "Accept: application/json" 
     -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZF91c3VhcmlvIjozMiwiY25waiI6IjAzLjk4MC43NTQvMDAwMy0wNSIsImRlcG9zaXRvX3BhZHJhbyI6IjEiLCJleHAiOjE3MjM1NTAwMTN9.IeVJImGIv4_Ko__pYQMQgmC0ehTcyNnGlCUMZoR75M8" 
     -X GET http://localhost/entidade/get_entidade_api\?id\=6426

Retorno Bem Sucedido

Serão retornados todos os dados relativos ao cliente consultado se encontrado. O status da resposta sempre será 200.

Layout conforme retorno de https://futura.atlassian.net/wiki/spaces/ESP/pages/4691329025/API+para+Vendas#1.-Inclus%C3%A3o-Cliente

Retorno Sem Sucesso

Será retornado um objeto JSON com o motivo da não inclusão (poderá ser um erro de autenticação caso o token tenha expirado ou seja inválido ou alguma regra de negócio não atendida. O status da resposta sempre será diferente de 200.

Bloco de código
{"error":"Cliente... nao e valido","status":422}

3. Clientes alterados

Introdução

Este webservice tem por finalidade retornar dados de clientes que sofreram alguma alteração a partir da data/hora informada.

Nota
Para acessar este método, o usuário deverá ter a permissão de usuário conforme perfil `ckb_permite_visualizar_clientes`

Endereço

<endereço do SispetroWeb>/entidade/clientes_alterados?data_hora_inicial=<data hora inicio alteracao>

Parâmetros

Será necessário enviar um header com o token. Como parâmetro enviar:

...

Nome	Descritivo	Exemplo
Authorization	Conteúdo do token obtido no passo de autenticação do usuário	eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZF91c3VhcmlvIjozMiwiY25waiI6IjAxLjgwNC4zNDUvMDAwMS02MCIsImV4cCI6MTUwMDA1MzYxN30.-ZvhWFYI8fyx66b3kZY1UVUrfaWUTioV3_M6K2wiPGM
Content-Type	tipo do formato de envio	application/json
Accept	tipo do formato de envio	application/json

Método

GET

Exemplo de chamada de WebService

Bloco de código

curl -H "Content-Type: application/json" -H "Accept: application/json" -X GET -H 
"Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZF91c3VhcmlvIjozMiwiY25waiI6IjAzLjk4MC43NTQvMDAwMy0wNSIsImRlcG9zaXRvX3BhZHJhbyI6IjEiLCJleHAiOjE3MjM2NjA2Mjl9.Jrx6JRm4i6C18MillNsbnSEnx47i4ae7rnF_vKmn86o" 
http://localhost/entidade/clientes_alterados\?data_hora_inicial=2024-08-10%2012:00

Retorno Bem Sucedido

Serão retornados todos os dados relativos aos clientes alterados a partir da data/hora informada. O status da resposta sempre será 200.

...

Item

Chave

Conteudo

1

CodEnt

Código da entidade alterada ou excluída

2

FlagOperacao

I = inclusão, U = alteração ou E = exclusão

3

entidade

mesmo layout de retorno de um cliente https://futura.atlassian.net/wiki/spaces/ESP/pages/4691329025/API+para+Vendas#1.-Inclus%C3%A3o-Cliente

Nota
Se o flagOperação for igual a 'E' (exclusão), não retorna a estrutura entidade.

Retorno Sem Sucesso

Será retornado um objeto JSON com o motivo da não aceitação (poderá ser um erro de autenticação caso o token tenha expirado ou seja inválido ou alguma regra de negócio não atendida. O status da resposta sempre será diferente de 200.

...

Versões comparadas

Versão antiga 1

Nova versão 2

Chave

e
View file
name entidade.json

Objetivo

Uso Geral

Obter token autenticação

Introdução

Métodos de Cadastros

1. Inclusão ou edição de clientes

Introdução

Endereços

Parâmetros

Métodos

Exemplo de chamada de WebService

Retorno Bem Sucedido

Retorno Sem Sucesso

2. Dados Gerais de Cliente

Introdução

Endereço

Parâmetros

Método

Exemplo de chamada de WebService

Retorno Bem Sucedido

Retorno Sem Sucesso

3. Clientes alterados

Introdução

Endereço

Parâmetros

Método

Exemplo de chamada de WebService

Retorno Bem Sucedido

Retorno Sem Sucesso

Comparação de Páginas

Versões comparadas

Versão antiga 1

Nova versão 2

Chave

<span class="diff-html-changed" data-a11y-before="Start of changed content" data-a11y-after="End of changed content" id="changed-diff-0">[data-colorid=</span>

Objetivo

Uso Geral

Obter token autenticação

Introdução

Métodos de Cadastros

1. Inclusão ou edição de clientes

Introdução

Endereços

Parâmetros

Métodos

Exemplo de chamada de WebService

Retorno Bem Sucedido

Retorno Sem Sucesso

2. Dados Gerais de Cliente

Introdução

Endereço

Parâmetros

Método

Exemplo de chamada de WebService

Retorno Bem Sucedido

Retorno Sem Sucesso

3. Clientes alterados

Introdução

Endereço

Parâmetros

Método

Exemplo de chamada de WebService

Retorno Bem Sucedido

Retorno Sem Sucesso