Loja

A documentação deste serviço está em construção. Fique de olho nas nossas atualizações!

A API Loja faz parte do Agenda Lojista e permite o gerenciamento de estabelecimentos comerciais, incluindo a configuração de formas de pagamento, tarifas e consultas de parcelas.

Com essa API, é possível:

Cadastrar e gerenciar lojas.

Definir e associar tarifas às lojas.

Configurar formas de pagamento.

Consultar parcelas e acordos de pagamento.

Para utilizar os recursos da API, é necessário seguir uma jornada específica de cadastro e associação de dados, garantindo que todas as informações estejam devidamente registradas antes de realizar determinadas operações.

Exemplo de jornada

Figura 1. Fluxo da API Loja

O fluxo básico de uso da API pode seguir esta sequência:

Cadastrar uma loja: o primeiro passo é criar uma loja no sistema.

Criar uma tarifa (opcional): caso a loja utilize tarifas, elas podem ser cadastradas separadamente.

Associar a tarifa à loja: se houver tarifas cadastradas, elas podem ser vinculadas à loja.

Gerenciar formas de pagamento: com a loja configurada, podem ser definidas as formas de pagamento aceitas.

Consultar parcelas e acordos: a API permite acessar detalhes sobre parcelas e acordos de pagamento vinculados às lojas.

Esse fluxo garante que todas as operações sejam realizadas de maneira estruturada e eficiente, evitando inconsistências nos dados.

Endpoints

Formas de pagamento

Tipo	Endpoint	Descrição
GET	/api/v1/lojas/{id}/acordos-formas-pagamentos	Listar formas de pagamento
POST	/api/v1/lojas/{id}/acordos-formas-pagamentos	Cadastrar forma de pagamento de uma loja
PATCH	/api/v1/lojas/{id}/acordos-formas-pagamentos	Atualizar forma de pagamento de uma loja
GET	/api/v1/lojas/{id}/acordos-formas-pagamentos/quantidade-parcelas/{quantidadeParcelas}	Consultar parcelas de uma loja

Lojas

Tipo	Endpoint	Descrição
POST	/api/v1/lojas	Cadastrar uma loja
GET	/api/v1/lojas/{id}	Consultar uma loja cadastrada
GET	/api/v1/lojas/externo/{idExterno}	Consultar loja por ID externo
GET	/api/v1/lojas/cnpj	Listar loja pelo CNPJ
GET	/api/v1/lojas/cards	Listar lojas
PATCH	/api/v1/lojas/{idLoja}	Alterar uma loja

Tarifas

Tipo	Endpoint	Descrição
GET	/api/v1/lojas/{idLoja}/tarifas	Listar tarifas por loja
POST	/api/v1/lojas/{idLoja}/tarifas	Associar tarifa a uma loja
DELETE	/api/v1/lojas/{idLoja}/tarifas	Cancelar tarifas com a loja
GET	/api/v1/lojas/tarifas	Listar tarifas
POST	/api/v1/lojas/tarifas	Cadastrar tarifa
GET	/api/v1/lojas/tarifas/{id}	Consultar uma tarifa
PATCH	/api/v1/lojas/tarifas/{id}	Alterar cadastro de uma tarifa

Casos de uso

A seguir, detalhamos os principais casos de uso na jornada do Loja, explicando como cada operação é realizada através dos endpoints disponíveis.

Cadastrar uma loja

Serviço exclusivo para processadora Dock.

Use este o endpoint para cadastrar uma loja

Para cada nova requisição no Tote, é necessário alterar o idExterno, cnpj e inscricaoEstadual.

Exemplo de request body :

{
  "idExterno": "a1b2c3d4e5f6",
  "nomeFantasia": "RPE",
  "razaoSocial": "RETAIL PAYMENT ECOSSYSTEM",
  "cnpj": "44168283000150",
  "inscricaoEstadual": "123.456.789-1112",
  "endereco": {
    "rua": "Rua Rodrigo Mayume Chaves Piscina Júnior",
    "bairro": "Bessa",
    "localidade": "João Pessoa",
    "uf": "PB",
    "complemento": "CORE",
    "numero": "123",
    "cep": "99999999"
  },
  "telefone": {
    "area": "83",
    "numero": "999999999"
  },
  "telefoneAdicional": {
    "area": "83",
    "numero": "999999999"
  },
  "email": "rpe@rpe.tech",
  "observacao": "Modelo de response: cadastro de lojas.",
  "numeroEstabelecimento": 123456,
  "naturezaEstabelecimento": "PROPRIO"
}

Exemplo de response:

[
  {
    "id": 1,
    "dataCadastro": "2023-06-06T13:29:19.203407",
    "idExterno": "a2b2c3t4e5f6",
    "nomeFantasia": "RPE",
    "razaoSocial": "RETAIL PAYMENT ECOSSYSTEM",
    "cnpj": "22023603000141",
    "inscricaoEstadual": "129864802855",
    "endereco": {
      "id": 1,
      "rua": "Rua das Matas",
      "bairro": "Bessa",
      "localidade": "João Pessoa",
      "uf": "PB",
      "complemento": "CORE",
      "numero": "123",
      "cep": "99999999"
    },
    "telefone": {
      "id": 26,
      "area": "83",
      "numero": "999999999"
    },
    "telefoneAdicional": {
      "id": 26,
      "area": "83",
      "numero": "999999999"
    },
    "email": "rpe@rpe.tech",
    "naturezaEstabelecimento": "PROPRIO",
    "numeroEstabelecimento": 123456,
    "observacao": "Modelo de response: cadastro de lojas."
  }
]

Criar uma tarifa

Serviço exclusivo para processadora Dock.

Use este endpoint para cadastrar uma nova tarifa.

Para criar uma nova tarifa, é necessário alterar o campo valor para fins de teste.

Exemplo de request body :

{
  "descricao": "Cadastro de teste para tarifa.",
  "valor": 30.59,
  "status": "ATIVO",
  "tipoCobranca": "DIA",
  "diaCobranca": 2,
  "utilizaValorIntervalado": true,
  "valorMinimo": 49.99,
  "valorMaximo": 200.99
}

Exemplo de response:

{
  "id": 1,
  "descricao": "Cadastro de teste para tarifa.",
  "valor": 0,
  "status": "ATIVO",
  "tipoCobranca": "DIA",
  "diaCobranca": 2,
  "utilizaValorIntervalado": true,
  "valorMinimo": 49.99,
  "valorMaximo": 200.99
}

Associar tarifa a uma loja

Serviço exclusivo para processadora Dock.

Use este endpoint para associar tarifa a uma loja.

Para cada nova requisição no Tote, é necessário alterar o idExterno, cnpj e inscricaoEstadual.

Exemplo de requisição:

Use Path parameter idLoja: 32 associar uma tarifa nesta loja.

Use o Query parameter idTarifa: para cada nova requisição, cadastre uma nova tarifa e insira aqui o idTarifa gerado no endpoint anterior.

Exemplo de response:

{
  "mensagem": "Operação realizada com sucesso."
}

Consultar uma loja

Use este endpoint para consultar uma loja.

Exemplo de requisição:

Use Path parameter id para listar uma loja.

Exemplo de response:

{
  "id": 1,
  "razaoSocial": "REDE NUMERO 1 LTDA",
  "nomeFantasia": "REDE NUMERO 1",
  "tipoContrato": {
    "id": 1,
    "descricao": "TIPO CONTRATO PADRAO",
    "status": "A",
    "idBin": 177,
    "formaLimite": "L",
    "cartaoGerado": "A",
    "tipoSenhaCartao": "3",
    "utilizaDigitoFixo": "N",
    "digitoFixo": 0,
    "cadastroClientesComCargaELote": "S",
    "permitirPagamentoAvulsoClienteConvenio": "S",
    "utilizaCartaoMulticash": "N",
    "utilizaCartaoPresente": "N",
    "utilizaFaturamentoMinimoConvenio": "N",
    "valorFaturamentoMinimoConvenio": 53.1,
    "tipoCartao": "F",
    "tipoExibicaoFatFodCliente": "D",
    "habPagLoteModuloConvenio": "N",
    "validaJurosSaque": "N",
    "habilitarConsultaSemEncargos": "N",
    "validarVendaRotativaSaldoMensal": "N",
    "idBinSegundaVia": 144,
    "liberacaoLimitePosCorte": "N",
    "habLimiteExtra": "N",
    "tipoSenha": "JA_INDICADA_POR_CARTAO",
    "tipoLimite": 1
  },
  "unidadeNegocio": {
    "id": 1,
    "descricao": "ADMINISTRADORA"
  },
  "limiteParcelamento": 200.33,
  "logradouro": "LOGRADOURO",
  "numero": "1",
  "complemento": "COMPLEMENTO",
  "cep": "58000000",
  "bairro": "CENTRO",
  "cidade": "JOÃO PESSOA",
  "estado": "PB",
  "cnpj": "00000000000001",
  "sigla": "SGL"
}

Os endpoints irão retornar os dados que podem ser acessados de acordo com suas credenciais de autenticação. Para mais informações, visite a página de autenticação.