Grupo Polgo - Logo
API docs by Redocly

🐙 Polgo | Documentação (1.94.027)

Download OpenAPI specification:Download

Introdução 🧑‍💻

Seja bem-vindo a nossa documentação. Aqui vocẽ poderá navegar por todos os endpoints disponibilizados por nossa equipe.

Para mais informações em como integrar sua solução conosco, acesse nosso site.

Login 🔑

O serviço de Login é utilizado para cadastrar, trocar senha e gerar códigos de autenticação de um usuário

Autenticação de usuários

Esse endpoint serve para autenticar um usuário.

Request Body schema: application/json

Campos para autenticação
Informações de acesso fornecidas pela equipe de Onboarding

usuario
required
string

Nome do usuário.

senha
required
string

Senha do usuário.

Responses

Request samples

Content type
application/json
{
  • "usuario": "polgo",
  • "senha": "123456789"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "mensagem": "Usuário autenticado com sucesso!",
  • "retorno": {
    }
}

Criação de usuário

Esse endpoint serve para criar um login.

Request Body schema: application/json

Campos para a criação de um login.

usuario
required
string

CPF/CNPJ do novo usuário.

nome
required
string

Nome do novo usuário.

tipo
required
string
Enum: "consumidor" "lojista"

Tipo de permissão para novo usuário.

senha
required
string

Senha do novo usuário.

email
string

E-mail do novo usuário.

object

Estrutura com informações sobre módulo de indicação.

Responses

Request samples

Content type
application/json
{
  • "usuario": "51525032984",
  • "nome": "Teste consumidor",
  • "tipo": "consumidor",
  • "senha": "123456",
  • "email": "teste@mail.com.br",
  • "consumidor": {
    }
}

Response samples

Content type
application/json
{
  • "status": 201,
  • "mensagem": "Login inserido com sucesso.",
  • "retorno": {
    }
}

Consumidor 🙋‍♂️

O serviço de Consumidor permite o cadastro e consulta de consumidores dentro de nossa plataforma.

Listar consumidores

Endpoint para listar os consumidores cadastrados em nossa base.

path Parameters
totalPorPagina
required
integer [ 1 .. 100 ]
Example: 10

Indicador da quantidade total de itens por página.

paginaAtual
required
integer >= 1
Example: 1

Indicador da pagina atual.

query Parameters
filtroNome
string
Example: filtroNome=POLGO

Parâmetro de filtragem pelo nome do consumidor.

filtroBairros
string
Example: filtroBairros=Jardim, Recanto

Parâmetro de filtragem pelos bairros do consumidor, separados por vírgula.

filtroCpf
string
Example: filtroCpf=16286538576

Parâmetro de filtragem pelo CPF do consumidor.

filtroRg
string
Example: filtroRg=637627637

Parâmetro de filtragem pelo RG do consumidor.

filtroTelefone
string
Example: filtroTelefone=19972638765

Parâmetro de filtragem pelo telefone do consumidor.

filtroIdadeMaxima
string
Example: filtroIdadeMaxima=78

Parâmetro de filtragem pela idade máxima do consumidor.

filtroIdadeMinima
string
Example: filtroIdadeMinima=18

Parâmetro de filtragem pela idade mínima do consumidor.

filtroEmail
string
Example: filtroEmail=grupo@polgo.com.br

Parâmetro de filtragem pelo e-mail do consumidor.

filtroDataHoraInicial
string
Example: filtroDataHoraInicial=2022-08-19 00:00:00

Data-hora inicial de cadastro de usuários, no formato YYYY-MM-DD HH:mm:ss.

filtroDataHoraAtualizacaoInicial
string
Example: filtroDataHoraAtualizacaoInicial=2022-08-15 00:00:00

Data-hora inicial de atualização de usuários, no formato YYYY-MM-DD HH:mm:ss.

filtroDataHoraAtualizacaoFinal
string
Example: filtroDataHoraAtualizacaoFinal=2022-08-17 00:00:00

Data-hora final de atualização de usuários, no formato YYYY-MM-DD HH:mm:ss.

filtroCadastroInicial
string
Example: filtroCadastroInicial=true

Caso verdadeiro, retorna consumidores com o campo cadastroInicial true, se não false.

header Parameters
Authorization
required
string

Token de autorização
Fornecido pelo endpoint de autenticação de usuários.

Responses

Request samples 

curl --request GET \
--url https://testews.polgo.com.br/polgo/consumidor/v1/consumidores/100/1 \
--header 'Content-Type: application/json' \
--header 'authorization: 000aaa999zzz'

Response samples

Content type
application/json
{
  • "status": 200,
  • "mensagem": "Lista de consumidores recuperadas.",
  • "retorno": {
    }
}

Documento Fiscal 📄

O Serviço de Documentos Fiscais é responsável pela geração, processamento e listagem de vendas. Ele se comunica com serviços de Cashback, Cupom e Raspadinha Alternativa

Inserir nova venda

Endpoint responsável em gravar novas vendas.

header Parameters
Authorization
required
string

Token de autorização
Fornecido pelo endpoint de autenticação de usuários.

Request Body schema: application/json
usuario
required
string

CPF/CNPJ do usuário da venda

numeroDocumento
required
string

Identificador único da venda.
Exemplo: Chave de acesso ou código de controle interno'

dataHoraEmissao
required
string

Data e hora da emissão no formato YYYY-MM-DD HH:mm:ss

valorTotal
required
number <double>

Valor total da venda

cnpjEmitente
required
string

CNPJ do emitente.
Informar campo cnpjEmitente ou codigoEmitente

codigoEmitente
required
string

Código interno do emitente.
Informar campo cnpjEmitente ou codigoEmitente

object

Estrutura com informações da campanha.
Informação fornecida pela equipe de Onboarding

object

Grupo de produtos utilizados na venda

formaPagamento
string

Formas de pagamentos utilizadas na venda.
Agrupar informações por vírgula. Exemplo: DINHEIRO,CARTAO'

extra
string

Campo livre para informações complementares da venda

object

Estrutura para informações do vendedor

object

Estrutura para informações complementares do consumidor

urlImagem
string

Link com o comprovante da venda

Responses

Request samples

Content type
application/json
{
  • "campanha": {
    },
  • "usuario": "11122233399",
  • "urlImagem": "",
  • "extra": "Documento de origem em São Paulo - SP",
  • "cnpjEmitente": "111222333000199",
  • "codigoEmitente": "12345",
  • "dataHoraEmissao": "2021-01-01 00:00:00",
  • "valorTotal": "123.45,",
  • "cnpjCpf": "11122233399",
  • "numeroDocumento": "35542315348534897845315458945643154687456341",
  • "formaPagamento": "DINHEIRO",
  • "produtosServicos": [
    ],
  • "vendedor": {
    },
  • "consumidor": {
    }
}

Response samples

Content type
application/json
{
  • "status": 201,
  • "mensagem": "Documento processado com sucesso.",
  • "retorno": {
    }
}

Cancelar venda

Endpoint serve para cancelar uma venda.

header Parameters
Authorization
required
string

Token de autorização
Fornecido pelo endpoint de autenticação de usuários.

Request Body schema: application/json

Dados para cancelar uma venda.

idDocumentoFiscal
required
string

Identificador único da venda
Fornecido pelo endpoint de inserir uma nova venda

Responses

Request samples

Content type
application/json
{
  • "idDocumentoFiscal": "31b83745-3d5b-4a1a-b533-dd670ca9079a"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "mensagem": "Documento Fiscal cancelado.",
  • "retorno": {
    }
}

Listagem de vendas

Endpoint serve para obter a listagem de vendas.

path Parameters
totalPorPagina
required
integer [ -1 .. 100 ]
Example: 100

Indicador da quantidade total de itens por página
Ao utilizar o valor -1, todos os registros serão listados

paginaAtual
required
integer >= 1
Example: 1

Indicador da pagina atual

query Parameters
anoCampanha
integer
Example: anoCampanha=2022

Ano da campanha

identificacaoCampanha
string
Example: identificacaoCampanha=GRUPOPOLGO

Identificação da campanha

numeroDocumento
string
Example: numeroDocumento=5555

Número de identificação da venda

cnpjEmitente
string
Example: cnpjEmitente=11122233000199

CNPJ do emitente da venda

codigoInternoEmitente
string
Example: codigoInternoEmitente=182b1456-7562-11ec-b8e2-43291dcfc479

Código interno do emitente

usuario
string
Example: usuario=11122233399

CPF/CNPJ do usuário da venda

header Parameters
Authorization
required
string

Token de autorização
Fornecido pelo endpoint de autenticação de usuários.

Responses

Request samples 

curl --request GET \
--url https://testews.polgo.com.br/polgo/documentoFiscal/v1/documentos/1/1 \
--header 'Content-Type: application/json' \
--header 'authorization: 000aaa999zzz'

Response samples

Content type
application/json
{
  • "status": 200,
  • "mensagem": "lista recuperada",
  • "retorno": {
    }
}

Cupom 🎟️

O serviço de Cupom é utilizado para a premiação dos usuários, permitindo que cupons sejam gerados, listados e premiados. Ele se comunica com o serviço de Documento Fiscal

Listar cupons por campanha

Esse endpoint serve para listar os cupons gerados com base em uma campanha.

path Parameters
anoCampanha
required
integer
Example: 2024

Ano da campanha.
Informação fornecedida pela equipe de Onboarding

identificacaoCampanha
required
string
Example: CAMPANHAPOLGO

Identificação da campanha. Informação fornecedida pela equipe de Onboarding

totalPorPagina
required
integer [ -1 .. 100 ]
Example: 10

Indicador da quantidade total de itens por página.
Ao passar -1, todos os registros serão retornados

paginaAtual
required
integer >= 1
Example: 1

Indicador da pagina atual.

header Parameters
Authorization
required
string

Token de autorização
Fornecido pelo endpoint de autenticação de usuários.

Request Body schema: application/json
object

Estrutura com parâmetros de filtragem.

Responses

Request samples

Content type
application/json
{
  • "filtro": {
    }
}

Response samples

Content type
application/json
{
  • "status": "200,",
  • "mensagem": "Lista dos cupons recuperada.",
  • "retorno": {
    }
}

Listar cupons de um consumidor

Esse endpoint serve para listar os cupons de um determinado usuário em uma campanha.

path Parameters
anoCampanha
required
integer
Example: 2022

Ano da campanha.
Informação fornecedida pela equipe de Onboarding

identificacaoCampanha
required
string
Example: CAMPANHAPOLGO

Identificação da campanha. Informação fornecedida pela equipe de Onboarding

usuario
required
string
Example: 99059662008

CPF do consumidor.

totalPorPagina
required
integer [ 1 .. 100 ]
Example: 10

Total de cupons por página.

paginaAtual
required
integer >= 1
Example: 1

Página atual.

header Parameters
Authorization
required
string

Token de autorização
Fornecido pelo endpoint de autenticação de usuários.

Responses

Request samples 

curl --request GET \
--url https://testews.polgo.com.br/polgo/cupom/v2/cupons/consumidor/2024/CAMPANHAPOLGO/12312312300/10/1 \
--header 'Content-Type: application/json' \
--header 'authorization: 000aaa999zzz' \

Response samples

Content type
application/json
{
  • "status": 200,
  • "mensagem": "Quantidade de cupons obtida.",
  • "retorno": {
    }
}

Raspadinha Alternativa 🍀

O serviço de Raspadinha Alternativa é outra modalidade de premiação oferecida pela plataforma Polgo, sendo possível que Raspadinhas sejam geradas, listadas, raspadas e entregues via PicPay ou Cashback Polgo. Ele se comunicando com o serviço de Documento Fiscal

Listar raspadinhas

Esse endpoint serve para listar raspadinhas digitais.

path Parameters
anoCampanha
required
integer
Example: 2024

Ano da campanha. Informação fornecedida pela equipe de Onboarding

identificacaoCampanha
required
string
Example: CAMPANHATESTE

Identificação da campanha. Informação fornecedida pela equipe de Onboarding

totalPorPagina
required
integer [ 1 .. 100 ]
Example: 10

Indicador da quantidade total de itens por página.

paginaAtual
required
integer >= 1
Example: 1

Indicador da pagina atual.

query Parameters
dataInicial
string
Example: dataInicial=2024-01-31

Data inicial da raspadinha, no formato YYYY-MM-DD

dataFinal
string
Example: dataFinal=2024-12-31

Data final da raspadinha, no formato YYYY-MM-DD.

tipoFiltro
string
Enum: "dataRaspada" "dataCriada"

Tipo de filtro para data inicial e final

usuario
string
Example: usuario=73699266488

Consumidor

nomeUsuario
string
Example: nomeUsuario=Eugênio

Nome do consumidor

raspadas
boolean
Example: raspadas=true

Filtrar apenas raspadinhas já raspadas

premiadas
boolean
Example: premiadas=false

Filtrar apenas raspadinhas premiadas

canceladas
boolean
Example: canceladas=false

Filtrar apenas raspadinhas canceladas

entregues
boolean
Example: entregues=true

Filtrar apenas raspadinhas entregues

numeroDocumentoFiscal
string
Example: numeroDocumentoFiscal=d42d9545-bfe6-4bd6-b58e-b3452236b894

Filtro por número de identificação do documento fiscal

id
string
Example: id=d42d9545-bfe6-4bd6-b58e-b3452236b894

Filtro por identificador único da raspadinha

loja
string
Example: loja=79743543000159

Filtro pelo CNPJ que originou a raspadinha, sem caracteres especiais ou pontuação

ordemPor
string
Enum: "dataCriada" "dataRaspada" "dataEntregue"
Example: ordemPor=dataCriada

Campo para ordenação das raspadinhas a serem retornadas na listagem

ordemSentido
string
Enum: "ASC" "DESC"
Example: ordemSentido=DESC

Sentido para ordenação das raspadinhas a serem retornadas na listagem

header Parameters
Authorization
required
string

Token de autorização
Fornecido pelo endpoint de autenticação de usuários.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "mensagem": "Lista de raspadinhas obtidas com sucesso!",
  • "retorno": {
    }
}

Raspar raspadinha digital

Esse endpoint serve para raspar uma raspadinha digital.

path Parameters
idRaspadinha
required
string
Example: a1b83025-8816-4a49-9c58-6c02a63a8a2c

Identificador único da raspadinha digital.

header Parameters
Authorization
required
string

Token de autorização
Fornecido pelo endpoint de autenticação de usuários.

Responses

Request samples 

curl --request GET \
--url https://testews.polgo.com.br/polgo/raspadinhaAlternativa/v1/raspadinhas/raspar/123456789 \
--header 'Content-Type: application/json' \
--header 'authorization: 000aaa999zzz' \

Response samples

Content type
application/json
{
  • "status": 200,
  • "mensagem": "Raspadinha raspada com sucesso",
  • "retorno": {
    }
}

Marcar prêmio da raspadinha como entregue

Esse endpoint serve para marcar como entregue o prêmio de uma raspadinha digital.

path Parameters
idRaspadinha
required
string
Example: a3fa0918-de19-4616-a417-ddfa4bf76490

Identificador único da raspadinha digital.

header Parameters
Authorization
required
string

Token de autorização
Fornecido pelo endpoint de autenticação de usuários.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "mensagem": "Prêmio de raspadinha entregue com sucesso!",
  • "retorno": {
    }
}