TOTVS Varejo PDV Omni

Árvore de páginas

O TOTVS Varejo PDV Omni facilita a consulta e identificação do cadastro de clientes durante as vendas, permitindo acesso rápido aos dados do cliente e direcionando o atendimento com base no histórico de compras. Além disso, oferece funcionalidades para edição e cadastro de novos clientes diretamente no PDV Omni.

Todas as atualizações feitas no PDV Omni são automaticamente integradas ao ERP, garantindo que o cadastro de clientes esteja sempre atualizado e disponível em toda a operação da empresa.


Cliente_endereco

Quando o Fidelidade está desabilitado, o PDV permite que seja cadastrado mais de um endereço para o mesmo cliente. O endereço informado em tela para ser o "endereço padrão" do cliente será gravado na tabela cliente, porém os demais endereços informados será gravado na cliente_endereco

Consulte todos os detalhes do cliente_endereco 



1. Método para integração

Este método é responsável pela criação de novos Clientes

  • Endpoint:
    • /api/retaguarda/v2/clientes
    • /api/retaguarda/v3/clientes
    • /api/retaguarda/v3/dadosdinamicos/down/0/{Versão Dado}
  • Método: Post
  • Autenticação: Bearer token
  • Permissão: Retaguarda

Este endpoint recebe uma lista de Clientes para que possam ser enviados vários na mesma requisição

Para que a baixa do Cliente criado ocorra no PDV Omni é necessário realizar a abertura de um lote do tipo  0 = Cliente

2. Exemplo de requisição

Versão 3.1(V2)

Exemplo de body da requisição - V3.1 (V2) 
[
    {
        "atividade": "string",
        "avatarUrl": "string",
        "bairro": "string",
        "celular": "string",
        "cep": "string",
        "cidade": "string",
        "complemento": "string",
        "cpfCnpj": "string",
        "cracha": "string",
        "dataNascimento": "2024-04-02T18:58:17.727Z",
        "email": "string",
        "endereco": "string",
        "estado": "string",
        "estadoCivil": 0,
        "idInquilino": "string",
        "idProprietario": "string",
        "idRetaguarda": "string",
        "loteOrigem": "string",
        "nome": "string",
        "numero": "string",
        "pessoaFisica": 0,
        "rgInscricao": "string",
        "sexo": 0,
        "situacao": 0,
        "telefone": "string",
        "IdRetaguardaProfissional": "string",
        "IdRetaguardaRamoAtividade": "string",
        "IdRetaguardaRedeCliente": "string",
        "IdRetaguardaClientePrincipal": "string",
        "IdRetaguardaPraca": "string",
        "IdRetaguardaRegiao": "string",
        "UtilizaPrecoAtacado": false
    }
]

Versão 3.2

Este endpoint ainda está em processo de manutenção, as informações estão disponibilizadas apenas para consulta, não sendo possível realizar a requisição.

Exemplo de body da requisição - V3.2 
[
    {
        "atividade": "string",
        "avatarUrl": "string",
        "bairro": "string",
        "celular": "string",
        "cep": "string",
        "cidade": "string",
        "complemento": "string",
        "cpfCnpj": "string",
        "cracha": "string",
        "dataNascimento": "2024-04-02T18:58:17.727Z",
        "email": "string",
        "endereco": "string",
        "estado": "string",
        "estadoCivil": 0,
        "idInquilino": "string",
        "idProprietario": "string",
        "idRetaguarda": "string",
        "loteOrigem": "string",
        "nome": "string",
        "numero": "string",
        "pessoaFisica": 0,
        "rgInscricao": "string",
        "sexo": 0,
        "situacao": 0,
        "telefone": "string",
        "IdRetaguardaProfissional": "string",
        "IdRetaguardaRamoAtividade": "string",
        "IdRetaguardaRedeCliente": "string",
        "IdRetaguardaClientePrincipal": "string",
        "IdRetaguardaPraca": "string",
        "IdRetaguardaRegiao": "string",
        "UtilizaPrecoAtacado": false
    }
]


3. Descrição de campos e regras


Informação

Coluna

Obrigatório

Tipo

Tamanho

Descrição
Nome do cliente nome Sim Texto 250 Nome completo do cliente
Identificação no retaguarda id_retaguarda Não Texto 100
Endereço do cliente endereco Não Texto 150

Endereço do cliente. Corresponde ao campo de logradouro.

Na tabela cliente ficará a informação do endereço padrão do cliente.

Em tela, normalmente, esse campo fica indisponível para alteração após a consulta automática do CEP.
Descrição descricao Não Texto 100
Número da residência do endereço numero Não Texto 15

Número da residência do endereço do cliente. Corresponde ao campo número na tela de cadastro.

Na tabela cliente ficará a informação do número do endereço padrão do cliente.
Complemento do endereço complemento Não Texto 50

Completo do endereço do cliente. Corresponde ao campo complemento.

Na tabela cliente ficará a informação do complemento do endereço padrão do cliente.
Bairro do endereço bairro Não Texto 100

Bairro do endereço do cliente. Corresponde ao campo bairro na tela de cadastro.

Na tabela cliente ficará a informação do bairro do endereço padrão do cliente.

Em tela, normalmente, esse campo fica indisponível para alteração após a consulta automática do CEP.
Cidade do endereço cidade Não Texto 100

Cidade do endereço do cliente. Corresponde ao campo cidade na tela de cadastro.

Na tabela cliente ficará a informação do cidade do endereço padrão do cliente.

Em tela, normalmente, esse campo fica indisponível para alteração após a consulta automática do CEP.
UF do endereço estado Não Texto 30

Estado do endereço do cliente, somente a sigla. Corresponde ao campo estado na tela de cadastro.

Na tabela cliente ficará a informação do estado do endereço padrão do cliente.

Em tela, normalmente, esse campo fica indisponível para alteração após a consulta automática do CEP.
CEP do endereço cep Não Texto 10

CEP do endereço do cliente. Corresponde ao campo CEP na tela de cadastro.

Na tabela cliente ficará a informação do CEP do endereço padrão do cliente.
Telefone residencial telefone Não Texto 20

Telefone do cliente. Corresponde ao campo telefone na tela de cadastro.

O campo possui a máscara de DDD + telefone (XX) XXXX-XXXX. O campo não aceita números com 9 dígitos (como celular) nem telefones iniciados com o digito 9.
Telefone celular celular Não Texto 20

Telefone celular do cliente. Corresponde ao campo celular na tela de cadastro.

O campo possui a máscara de DDD + celular (XX) XXXXX-XXXX. O campo não aceita números com 8 dígitos (como telefone residencial).
E-mail email Não Texto 80

E-mail de contato do cliente. Corresponde ao campo e-mail na tela de cadastro.

O campo possui validação se o valor digitado é válido (possua o servidor de e-mail @xpto.com.br)
Data de nascimento data_nascimento Não Data
Exemplo "1991-03-20 00:00:00.00000". Corresponde a data de nascimento do cliente.
Situação situacao Sim Inteiro

Define se o cliente em questão está ativo ou inativo.

  • 0 - Inativo
  • 1 - Ativo
Data de cadastro data_cadastro Sim Data
Exemplo "2024-03-20 20:56:43.15725". Corresponde a data em que o dado foi cadastrado localmente.
Data de atualização data_atualizacao Sim Data
Exemplo "2024-03-20 20:56:43.15725". Corresponde a data em que o dado foi atualizado localmente.
Identificação de pessoa física ou jurídica pessoa_fisica Sim Inteiro

Campo preenchido automaticamente dependendo do dado CPF/CNPJ.

Caso o campo seja preenchido com um CPF, o campo pessoa_fisica será igual a 1.

Caso o campo seja preenchido com um CNPJ, o campo pessoa_fisica será igual a 0.

Esse campo é utilizado posteriormente para tratar a máscara do dado de CPF/CNPJ nas telas de identificação de consumidor.
CPF ou CNPJ do cliente cadastrado cpf_cnpj Não Texto 25
RG do cliente cadastrado rg_inscricao Não Texto 25
Sexo do cliente sexo Não Inteiro

Sexo

  • 0 - Não informado
  • 1 - Masculino
  • 2 - Feminino
Estado civil do cliente estado_civil Não Inteiro

Estado civil

  • 0 - Não informado
  • 1 - Casado
  • 2 - Solteiro
  • 3 - Viúvo
  • 4 - Separado
  • 5 - Divorciado
  • 6 - Outros
Avatar do cliente avatar_url Não Texto 300 Defasado
Enviar para o retaguarda/ERP enviarpnet Não Inteiro

Campo de controle se o cliente já foi integrado com o retaguarda/ERP.

  • 0 - Integrado
  • 1 - Pendente de integração

Quando cadastrado um novo cliente e o Fidelidade estiver habilitado, esse campo será sempre gravado como 0. Pois com o Fidelidade ativo, não há integração do cliente.

Quando o fidelidade estiver desabilitado, esse campo será gravado como 1 para que quando executado a rotina de integração de cliente ele seja retornado.
Atividade/Convenio atividade Não Texto 500

Campo utilizado para verificar se o cliente possui promoções ativas para o mesmo no Motor TOTVS.

Esse campo é preenchido na tela do Live, no cadastro do cliente, na aba de classificação.

Quando há no Motor TOTVS uma promoção vinculada ao convênio do cliente a promoção será aplicada.
Crachá cracha Não Texto 20 Defasado
Vinculo com a carta de consentimento id_termo_consentimento Não Texto 100 ID retaguarda da tabela termo_consentimento, para vincular qual a carta aceitada pelo cliente
Data de aceite do termo de consentimento data_aceite_termo_consentimento Não Data
Data em que o cliente aceitou/concordou com o termo de consentimento
Tipo de endereço tipo_endereco Não Numérico

Tipo endereço

  • 0 - Entrega
  • 1 - Comercial
  • 2 - Cobrança
Id profissional id_profissional Não Texto 100

Id Profissional vinculado ao cliente
Id ramo atividade id_ramo_atividade Não  Numerico

Id Ramo Atividade vinculado a tabela ramo_atividade
Id retaguarda rede cliente  id_retaguarda_rede_cliente Não Texto 100

Id Retaguarda da rede do cliente
Id cliente principal id_cliente_principal Não Numerico

Id do cliente principal, caso seja o principal será nulo.
Id retaguarda praca id_retaguarda_praca Não  Texto 100

Id Retaguarda praça do cliente
Id regiao id_regiao Não  Numerico

Id regiao vinculado a tabela regiao
Utlizada preco atacado utiliza_preco_atacado Não  Boleano

Falso ou Verdadeiro



      Requisição



      Definições dos campos do body

      Campo

      Tipo

      Descrição

      Obrigatório

      Observações
      atividade String Atividade

      Não

      Tamanho máximo: 500 caracteres
      avatarUrl String Avatar do cliente Não Tamanho máximo: 300caracteres
      bairro String Bairro principal do cliente

      Não

      Tamanho máximo: 100 caracteres
      celular String Celular do cliente

      Não

      Tamanho máximo:  20 caracteres
      cep String CEP do endereço principal do cliente

      Não

      Tamanho máximo: 10 caracteres
      cidade String Cidade principal do cliente

      Não

      Tamanho máximo: 100 caracteres
      complemento String Complemente do endereço principal do cliente

      Não

      Tamanho máximo: 50 caracteres
      cpfCnpj String CPF ou CNPJ do cliente

      Sim

      Tamanho máximo: 14 caracteres
      cracha String Crachá

      Não

      Tamanho máximo: 20 caracteres
      dataNascimento Datetime

      Data de nascimento do cliente

      		 Não
      email String Email do cliente

      Não

      Tamanho máximo: 80 caracteres
      endereco String Endereço principal do cliente

      Não

      Tamanho máximo: 150 caracteres
      estado String Estado principal do cliente

      Não

      Tamanho máximo: 30 caracteres
      estadoCivil Int Indica o estado civil do cliente (Descritivo abaixo)

      Não

      Código

      Descrição
      0 Não informado
      1 Casado
      2 Solteiro
      3 Viúvo
      4 Separado
      5 Divorciado
      6 Outros
      idInquilino String

      Identificador do inquilino 

      		 Sim
      idProprietario String Identificador do proprietário Sim
      idRetaguarda String Identificador do cliente na retaguarda Sim Tamanho máximo: 100 caracteres
      loteOrigem String Identificador do lote em que serão enviados os dados Sim
      nome String Nome do cliente

      Sim

      Tamanho máximo: 200 caracteres
      numero String Número do endereço principal do cliente

      Não

      Tamanho máximo: 15 caracteres
      pessoaFisica Int Indica se o cliente é uma pessoa física ou jurídica Sim
      rgInscricao String RG do cliente

      Não

      Tamanho máximo: 25 caracteres
      sexo Int Indica o genero do cliente (Descritivo abaixo)

      Não
      Código Definição
      0 Não Definido
      1 Masculino
      2 Feminino
      situacao Int Situação do cliente 

      Sim

      		 0 - Inativo, 1 - Ativo
      telefone String Telefone do cliente

      Não

      Tamanho máximo: 20 caracteres
      IdRetaguardaProfissional String Id Retaguarda do Profissional 

      Não

      Tamanho máximo: 100 caracteres
      IdRetaguardaRamoAtividade String

      Id Retaguarda Ramo Atividade vinculado a tabela ramo_atividade

      Não

      Tamanho máximo: 100 caracteres
      IdRetaguardaRedeCliente  String

      Id Retaguarda da rede do cliente

      Não 

      Tamanho máximo: 100 caracteres
      IdRetaguardaClientePrincipal String

      Id Retaguarda do cliente principal, caso seja o principal será nulo.

      Não

      Tamanho máximo: 100 caracteres
      IdRetaguardaPraca String

      Id Retaguarda praça do cliente

      Não

      Tamanho máximo: 100 caracteres
      IdRetaguardaRegiao String

      Id Retaguarda regiao vinculado a tabela regiao

      Não

      Tamanho máximo: 100 caracteres
      UtlizadaPrecoAtacado bool

      Falso ou Verdadeiro

      		 Não False - Falso, True - Verdadeiro
      Valor default = False

      Retorno

        Exemplo de body de retorno

        {
            "success": true,
            "message": "Requisição inserida com sucesso!",
            "data": null,
            "errors": null,
            "totalTime": 0,
            "numberOfRecords": 0
        }

        Definições dos campos do retorno

        Campo

        Tipo

        Descrição
        Success bool Indica se a criação do compartilhamento foi feita com sucesso
        Message string Caso ocorra erros durante a criação do compartilhamento eles serão enviados nesse campo
        Data objeto Objeto compartilhamento criado
        Errors Lista Listas com os erros encontrados no processo
        TotalTime int tempo da requisição
        NumberOfRecords int número de dados inseridos

        Devido a arquitetura implentada temos dois retornos de erros que foram padronizados na versão três deste endpoint

          Este retorno ocorre quando um campo enviado não passa pela validação, por exemplo, não enviar um dado obrigatório

          {
              "code": "string",
              "message": "string",
              "detailedMessage": "string",
              "helpUrl": "string",
              "details": [
                  {
                      "guid": "string",
                      "code": "string",
                      "message": "string",
                      "detailedMessage": "string"
                  }
              ]
          }

          Campo

          Tipo

          Descrição
          code string Código de erro
          message string Mensagem do erro
          detailedMessage string Detalhamento do erro
          helpUrl string url de ajuda
          TotalTime string Tempo total de busca
          details lista de objeto Lista de objeto de erros
          details.guid string Identificador do erro
          details.code string Código do erro
          details.message string Mensagem do erro 
          details.detailedMessage string Detalhamento do erro

          Este retorno ocorre quando algo na aplicação não ocorreu da forma esperada, por exemplo, quando uma exceção é lançada pela aplicação

          {
              "success": false,
              "message": "",
              "data": null,
              "errors": null,
              "totalTime": 0,
              "numberOfRecords": 0
          }

          Campo

          Tipo

          Descrição
          Success bool Indica se a criação do cliente foi feita com sucesso
          Message string Messagem com os erros
          Data objeto Objeto cliente
          Errors Lista Listas com os erros encontrados no processo
          TotalTime int tempo da requisição
          NumberOfRecords int número de dados inseridos

          Este endpoint ainda está em processo de manutenção, as informações estão disponibilizadas apenas para consulta, não sendo possível realizar a requisição.

          Requisição


          Definições dos campos do body

          Campo

          Tipo

          Descrição

          Obrigatório

          Observações
          nome String Nome do cliente

          Sim

          Tamanho máximo: 250 caracteres
          endereco String Endereço principal do cliente

          Não

          Tamanho máximo: 150 caracteres
          numero String Número do endereço principal do cliente

          Não

          Tamanho máximo: 15 caracteres
          complemento String Complemente do endereço principal do cliente

          Não

          Tamanho máximo: 50 caracteres
          bairro String Bairro principal do cliente

          Não

          Tamanho máximo: 100 caracteres
          cidade String Cidade principal do cliente

          Não

          Tamanho máximo: 100 caracteres
          estado String Estado principal do cliente

          Não

          Tamanho máximo: 30 caracteres
          cep String CEP do endereço principal do cliente

          Não

          Tamanho máximo: 10 caracteres
          telefone String Telefone do cliente

          Não

          Tamanho máximo: 20 caracteres
          celular String Celular do cliente

          Não

          Tamanho máximo:  20 caracteres
          email String Email do cliente

          Não

          Tamanho máximo: 80 caracteres
          dataNascimento Datetime

          Data de nascimento do cliente

          		 Não
          situacao Int Situação do cliente 

          Sim

          0 - Inativo, 1 - Ativo
          pessoaFisica Int Indica se o cliente é uma pessoa física ou jurídica Sim 0 - Pessoa Física, 1 - Pessoa Jurídica
          cpfCnpj String CPF ou CNPJ do cliente

          Não

          Tamanho máximo: 25 caracteres
          rgInscricao String RG do cliente

          Não

          Tamanho máximo: 25 caracteres
          sexo Int Indica o genero do cliente 

          Não
          Descrição Código
          Não informado 0
          Masculino 1
          Feminino 2
          estadoCivil Int Indica o estado civil do cliente

          Não
          Descrição Código
          Não informado 0
          Casado 1
          Solteiro 2
          Viúvo 3
          Separado 4
          Divorciado 5
          Outros 6
          avatarUrl String DEFASADO Não DEFASADO
          atividade String Atividade

          Não

          Tamanho máximo: 500 caracteres
          cracha String DEFASADO

          Não

          DEFASADO
          idInquilino String

          Identificador do inquilino 

          		 Sim
          idRetaguarda String Identificador do cliente na retaguarda Sim Tamanho máximo: 100 caracteres
          idProprietario String Identificador do proprietário Sim
          loteOrigem String Identificador do lote em que serão enviados os dados Sim
          tipoEndereco Int Tipo Endereço Não
          Descrição Código
          Entrega 0
          Comercial 1
          Cobrança 2
          descricao String Descrição Não

          Tamanho máximo: 100 caracteres
          IdRetaguardaProfissional String Id Retaguarda do Profissional 

          Não

          Tamanho máximo: 100 caracteres
          IdRetaguardaRamoAtividade String

          Id Retaguarda Ramo Atividade vinculado a tabela ramo_atividade

          Não

          Tamanho máximo: 100 caracteres
          IdRetaguardaRedeCliente  String

          Id Retaguarda da rede do cliente

          Não 

          Tamanho máximo: 100 caracteres
          IdRetaguardaClientePrincipal String

          Id Retaguarda do cliente principal, caso seja o principal será nulo.

          Não

          Tamanho máximo: 100 caracteres
          IdRetaguardaPraca String

          Id Retaguarda praça do cliente

          Não

          Tamanho máximo: 100 caracteres
          IdRetaguardaRegiao String

          Id Retaguarda regiao vinculado a tabela regiao

          Não

          Tamanho máximo: 100 caracteres
          UtlizadaPrecoAtacado bool

          Falso ou Verdadeiro

          		 Não False - Falso, True - Verdadeiro
          Valor default = False

          Retornos

            Exemplo de body de retorno

            {
                "success": true,
                "message": "Requisição inserida com sucesso!",
                "data": null,
                "errors": null,
                "totalTime": 0,
                "numberOfRecords": 0
            }

            Definições dos campos do retorno

            Campo

            Tipo

            Descrição
            Success bool Indica se a criação do compartilhamento foi feita com sucesso
            Message string Caso ocorra erros durante a criação do compartilhamento eles serão enviados nesse campo
            Data objeto Objeto compartilhamento criado
            Errors Lista Listas com os erros encontrados no processo
            TotalTime int tempo da requisição
            NumberOfRecords int número de dados inseridos

            Exemplo de body de retorno

            {
                "code": "string",
                "message": "string",
                "detailedMessage": "string",
                "helpUrl": "string",
                "details": [
                    {
                        "guid": "string",
                        "code": "string",
                        "message": "string",
                        "detailedMessage": "string"
                    }
                ]
            }

            Definições dos campos do retorno

            Campo

            Tipo

            Descrição
            code string Código de erro
            message string Mensagem do erro
            detailedMessage string Detalhamento do erro
            helpUrl string url de ajuda
            TotalTime string Tempo total de busca
            details lista de objeto Lista de objeto de erros
            details.guid string Identificador do erro
            details.code string Código do erro
            details.message string Mensagem do erro 
            details.detailedMessage string Detalhamento do erro

            Campo

            Tipo

            Descrição
            Success bool Indica se a criação do cliente foi feita com sucesso
            Message string Caso ocorra erros durante a criação do cliente eles serão enviados nesse campo
            Data objeto Objeto cliente criado
            Errors Lista Listas com os erros encontrados no processo
            TotalTime int tempo da requisição
            NumberOfRecords int número de dados inseridos

            {
                "success": true,
                "message": "",
                "data": null,
                "errors": null,
                "totalTime": 0,
                "numberOfRecords": 0
            }

            Devido a arquitetura implentada temos dois retornos de erros que foram padronizados na versão três deste endpoint

              Este retorno ocorre quando um campo enviado não passa pela validação, por exemplo, não enviar um dado obrigatório

              Campo

              Tipo

              Descrição
              code string Código de erro
              message string Mensagem do erro
              detailedMessage string Detalhamento do erro
              helpUrl string url de ajuda
              TotalTime string Tempo total de busca
              details lista de objeto Lista de objeto de erros
              details.guid string Identificador do erro
              details.code string Código do erro
              details.message string Mensagem do erro 
              details.detailedMessage string Detalhamento do erro

              Este retorno ocorre quando algo na aplicação não ocorreu da forma esperada, por exemplo, quando uma excessão é lançada pela aplicação

              Campo

              Tipo

              Descrição
              Success bool Indica se a criação do cliente foi feita com sucesso
              Message string Messagem com os erros
              Data objeto Objeto cliente
              Errors Lista Listas com os erros encontrados no processo
              TotalTime int tempo da requisição
              NumberOfRecords int número de dados inseridos

              {
                  "success": false,
                  "message": "",
                  "data": null,
                  "errors": null,
                  "totalTime": 0,
                  "numberOfRecords": 0
              }

              • Sem rótulos