O que é API

Interface de Programação de Aplicações (pt-BR) ou Interface de Programação de Aplicação (pt-BR), cuja sigla API provém do Inglês Application Programming Interface, é um conjunto de rotinas e padrões estabelecidos por um software para a utilização das suas funcionalidades por aplicativos que não pretendem envolver-se em detalhes da implementação do software, mas apenas usar seus serviços.

De modo geral, a API é composta por uma série de funções acessíveis somente por programação, e que permitem utilizar características do software menos evidentes ao utilizador tradicional.

Por exemplo, um sistema operacional possui uma grande quantidade de funções na API, que permitem ao programador criar janelas, acessar arquivos, cifrar dados etc. Mas as APIs dos sistemas operacionais costumam ser dissociadas de tarefas mais essenciais, como a manipulação de blocos de memória e acesso a dispositivos. Essas tarefas são atributos do núcleo de sistema e raramente são programáveis. Outro exemplo são programas de desenho geométrico que possuem uma API específica para criar automaticamente entidades de acordo com padrões definidos pelo utilizador.

Chave de API

Para iniciar é preciso conhecer a chave de API. No menu principal do acesso empresa tem um item do menu chamado Chave de API. Essa chave será necessária no envio da requisição de cada endpoint da API.

Não informe a chave para terceiros não autorizados. Ela deve ser mantida em sigilo como uma senha é tratada.

Cabeçalho de requisição

É obrigatório o envio de dois parâmetros no cabeçalho (header) da requisição. Chave Apikey e Content-Type. Veja o exemplo abaixo:

Apikey: chave_de_api @string
Content-Type: application/json @string

Erros

As mensagens de erro serão apresentadas em formato texto pela chave message, e são identificadas sempre que a chave de retorno error tem o valor true (verdadeiro). Veja um exemplo:

        {
            "error": true,
            "data": [],
            "datetime": "2020-01-01 12:35:56",
            "message": "O CPF do cliente está inválido."
        }
    

Cashback

Integre com o Cashback e automatize o processo de registro. Antes de integrar certifique-se que você tem o contrato com a ferramenta ativa.

Os endpoints disponíveis são:

Configurações

https://sempremais.me/api/cashback-configuracoes

Registrar

https://sempremais.me/api/cashback-registrar

Consultar

https://sempremais.me/api/cashback-consultar

Resgatar

https://sempremais.me/api/cashback-resgatar

Cashback - configurações

Se necessário saber as configurações definidas do seu cashback basta realizar a seguinte chamada.

Endpoint

https://sempremais.me/api/cashback-configuracoes

Método

POST

Parâmetros de envio (JSON)

        {
            Cnpj: '' @string (com ou sem pontuação - máscara)
        }
    

Retorno (formato JSON)

        {
            error: false, @boolean
            message: '', @string
            datetime: '', @string (Y-m-d H:i:s)
            data: {
                "QualquerDia": "Sim",
                "DiasSelecionados": {
                    "Segunda-feira": "Não",
                    "Terça-feira": "Não",
                    "Quarta-feira": "Não"
                    "Quinta-feira": "Não",
                    "Sexta-feira": "Não",
                    "Sábado": "Não",
                    "Domingo": "Não",
                },
                "Expira": "Sim",
                "ExpiraEm": "9 meses",
                "Porcentagem": 5,
                "Ativo": "Sim"
            },
        }
    

Cashback - registrando

Para registrar um cashback para um determinado cliente, basta realizar a seguinte chamada.

Endpoint

https://sempremais.me/api/cashback-registrar

Método

POST

Parâmetros de envio (JSON)

        {
            Cnpj: '', @string (com ou sem pontuação - máscara)
            CpfCliente: '', @string (com ou sem pontuação - máscara)
            ValorCompra: 0.00, @float (com duas casas decimais de centavos)
        }
    

Retorno (formato JSON)

        {
            error: false, @boolean
            message: '', @string
            datetime: '', @string (Y-m-d H:i:s)
            data: {
                Resumo: "Saldo atual do cliente: R$ 3,05",
                ValorCompra: "R$ 1,00",
                Cashback: "R$ 0,05",
                SaldoAtual: "R$ 3,05"
            }
        }
    

Cashback - consultando

Endpoint

https://sempremais.me/api/cashback-consultar

Método

POST

Parâmetros de envio (JSON)

        {
            Cnpj: '', @string (com ou sem pontuação - máscara)
            CpfCliente: '', @string (com ou sem pontuação - máscara)
        }
    

Retorno (formato JSON)

        {
            error: false, @boolean
            message: '', @string
            datetime: '', @string (Y-m-d H:i:s)
            data: "R$ 0,00", @string
        }
    

Cashback - sacando

Endpoint

https://sempremais.me/api/cashback-resgatar

Método

POST

Parâmetros de envio (JSON)

        {
            Cnpj: '', @string (com ou sem pontuação - máscara)
            CpfCliente: '', @string (com ou sem pontuação - máscara)
            ValorSaque: 0.00, @float (com duas casas decimais de centavos)
        }
    

Retorno (formato JSON)

        {
            error: false, @boolean
            message: '', @string
            datetime: '', @string (Y-m-d H:i:s)
            data: {
                Resumo: "Saldo atual do cliente: R$ 4,05",
                SaldoAtual: "R$ 4,05",
                SaqueRealizado: "R$ 1,00"
            }
        }