Idioma e moeda
Entrar
Cases Planos
Buscar no site
Idioma e moeda
API Pública Smartbis v1.9.0

Integre vendas, clientes, dependentes, benefícios e elegibilidade ao motor de fidelidade.

API REST v2 para integrações server-to-server com autenticação Bearer Token, escopos explícitos, escritas idempotentes e controle do acesso de titulares e dependentes aos planos.

Fluxo básico

Da autenticação até a recompensa automática.

O uso principal da API é registrar vendas externas para que a Smartbis processe cashback, pontos, vouchers e comunicações conforme as regras da conta.

01 Gerar token

Obtenha as credenciais na área Desenvolvedores do painel. Envie a API Key da identidade autorizada e uma Secret Key válida; o token expira em 24 horas.

02 Criar ou localizar cliente

Use documento, telefone ou ID para localizar e manter o cliente sincronizado.

03 Registrar venda

Envie `sale_amount` por documento, telefone ou `customer_id` para acionar o motor de fidelidade.

04 Validar benefícios

Consulte cupons, vouchers, categorias e estoque quando a operação precisar.

Referência rápida dos principais endpoints.

Esta parte funciona como uma porta de entrada antes da documentação Swagger completa.

POST /auth/token

Gera o token Bearer para autenticar as próximas chamadas.

Auth
GET /customers

Lista clientes ou filtra por documento, telefone ou ID, com paginação opcional.

Customers
POST /customers

Cria cliente com nome, telefone, senha e dados complementares.

Customers
PATCH /customers/{customer_id}

Atualiza os dados cadastrais suportados e permite ativar ou desativar o cliente pelo campo `active`.

Customers
GET /customers/{customer_id}/referrals

Lista apenas os clientes indicados diretamente pelo cliente informado, respeitando as permissões de visualização. A consulta não gera créditos; eventuais recompensas seguem o processo existente e aparecem no extrato de transações.

Referrals
GET /partners

Lista parceiros próprios e permite consultar os detalhes de cada cadastro.

Partners
POST /partners

Cadastra um parceiro respeitando as regras e os limites do plano.

Partners
PATCH /partners/{partner_id}

Atualiza, ativa ou desativa um parceiro próprio.

Partners
POST /sales

O administrador registra na operação principal. Para registrar em uma loja específica, use a API Key de um operador autorizado nela.

Sales
GET /customers/{customer_id}/transactions

Consulta o extrato paginado, o saldo atual e, quando aplicável, a composição do saldo por parceiro.

Transactions
POST /transactions/{transaction_id}/refund

Estorna integralmente o valor gerado pela transação elegível, uma única vez. Consulte refundable no extrato; o operador só estorna suas próprias vendas autorizadas.

Transactions
GET /coupons

Lista cupons/recompensas disponíveis para a operação.

Coupons
POST /coupons

Cadastra uma recompensa usando as regras e os limites existentes da operação.

Coupons
PATCH /coupons/{coupon_id}

Atualiza, ativa ou desativa uma recompensa existente.

Coupons
PATCH /coupons/{coupon_id}/stock

Atualiza estoque de uma recompensa específica.

Coupons
GET /vouchers

Lista vouchers com paginação opcional.

Vouchers
POST /vouchers/{voucher_code}/validate

Valida voucher pelo código informado.

Vouchers
POST /vouchers/manual-redemptions

Executa o resgate manual existente, verificando saldo e registrando o voucher e a movimentação de forma atômica.

Vouchers
GET /plans

Lista os planos para participantes configurados no clube.

Plans
GET /subscriptions

Lista assinaturas e permite filtrar acessos ativos, inadimplentes, vencidos ou cancelados.

Subscriptions
GET /customers/{customer_id}/dependents

Consulta dependentes vinculados ao titular e sua elegibilidade herdada.

Dependents
POST /customers/{customer_id}/dependents

Cadastra dependente respeitando empresa, titular e limite do plano.

Dependents
PATCH /dependents/{dependent_id}

Atualiza os dados suportados do dependente; sua elegibilidade continua herdada do titular.

Dependents
PATCH /categories/{category_id}

Atualiza, ativa ou desativa uma categoria sem remover seus vínculos existentes.

Categories
GET /eligibility/reconciliation

Concilia vidas ativas por plano e período, com paginação.

Eligibility
POST /webhooks

Cadastra destinos HTTPS para eventos assinados de ativação, inadimplência, expiração e cancelamento de assinaturas.

Webhooks
GET /webhooks/deliveries

Consulta o histórico de entregas para investigar tentativas e falhas dos eventos de assinatura.

Webhooks
POST /access-links

Emite acesso assinado, curto e de uso único para fornecedores vinculados.

Access
PATCH /subscriptions/{customer_id}

Ativa, suspende ou encerra o acesso do participante a um plano sem alterar cobranças no gateway.

Subscriptions
Objetos principais

Recursos da API organizados pelo uso da operação.

A página apresenta os domínios da API em linguagem de produto, enquanto a documentação Swagger mantém os detalhes de schema, parâmetros e respostas.

Clientes

Cadastro, busca, atualização, ativação e desativação por documento, telefone ou ID, respeitando a visibilidade do operador.

Vendas

Registro de compras externas para gerar cashback, pontos ou vouchers.

Cupons

Cadastro, atualização, ativação, desativação e controle de estoque das recompensas.

Vouchers

Consulta, validação e resgate manual pelo processo oficial, com verificação de saldo.

Categorias

Criação, atualização, ativação e desativação das categorias da operação.

Parceiros e indicações

Mantém parceiros próprios e consulta indicações diretas sem criar uma rede multinível ou alterar recompensas.

Planos e assinaturas

Consulta planos e sincroniza o status de acesso dos participantes com sistemas e fornecedores externos.

Dependentes e elegibilidade

Mantém vínculos familiares e concilia titulares e dependentes ativos sem transportar dados clínicos.

Webhooks e acesso federado

Entrega os eventos de assinatura suportados com assinatura e retentativas. Para fornecedores vinculados, emite acesso temporário de uso único.

Autenticação

A API Key identifica quem registra a operação. O administrador registra vendas na operação principal; para uma loja específica, utilize a API Key de um operador autorizado nela.

Escolha o percurso da sua integração.

Os exemplos abaixo organizam recursos existentes. Consulte no OpenAPI os campos, permissões e respostas de cada etapa.

ERP e pós-venda

Localize ou cadastre o cliente, registre a venda em POST /sales e consulte GET /customers/{customer_id}/transactions. Se for necessário estornar, use o transaction_id de uma movimentação com refundable: true; a integração não escolhe um valor parcial.

Operação com várias lojas

Gere um token para o operador autorizado na loja de cada operação. A API Key administrativa registra na operação principal; POST /sales não recebe store_id para distribuir vendas. Vínculos ambíguos retornam 409 para correção do contexto.

Clube e fornecedor externo

Consulte planos e assinaturas, mantenha titulares e dependentes e concilie a elegibilidade. Cadastre o vínculo do beneficiário com o fornecedor antes de emitir acesso temporário. Atualizar o acesso na Smartbis não cria cobranças nem cancela assinaturas no gateway.

Trate autenticação, reenvios e eventos desde o início.

Mantenha credenciais no backend e respeite os escopos retornados pela autenticação. A documentação interativa contém os contratos para implementar e validar cada fluxo.

Token e permissões

Renove o token de 24 horas quando necessário e trate respostas 401. A autorização segue a API Key do usuário: usar a Secret Key administrativa com a API Key de um operador não amplia suas permissões.

Reenvio sem duplicidade

As escritas exigem Idempotency-Key. Reenvie a mesma requisição com a mesma chave para obter a resposta armazenada dentro da janela de 24 horas. Outra carga com a mesma chave retorna 409; uma operação em processamento também pode retornar 409 e orientar nova tentativa.

Eventos de assinatura

O catálogo atual inclui subscription.activated, subscription.past_due, subscription.expired e subscription.cancelled. Use GET /webhooks/deliveries para acompanhar entregas; o catálogo não representa eventos de todas as alterações da plataforma.

Assinatura e retentativas

Valide a assinatura HMAC sobre o corpo bruto e o timestamp, com tolerância de cinco minutos. O mecanismo de entrega prevê até oito tentativas; respostas HTTP 2xx concluem a entrega. Consulte a documentação para implementar a validação e tratar falhas.

Acesso de uso único

Os links para fornecedores vinculados usam tokens com validade de 60 a 900 segundos. A troca por POST /access-links/consume consome o token uma única vez; solicite novo acesso quando ele expirar ou já tiver sido utilizado.

Precisa conectar um sistema próprio?

Use a documentação interativa para testar endpoints, validar payloads e implementar o fluxo adequado para sua integração.

Abrir Swagger