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.
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.
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.
Use documento, telefone ou ID para localizar e manter o cliente sincronizado.
Envie `sale_amount` por documento, telefone ou `customer_id` para acionar o motor de fidelidade.
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.
Gera o token Bearer para autenticar as próximas chamadas.
AuthLista clientes ou filtra por documento, telefone ou ID, com paginação opcional.
CustomersCria cliente com nome, telefone, senha e dados complementares.
CustomersAtualiza os dados cadastrais suportados e permite ativar ou desativar o cliente pelo campo `active`.
CustomersLista 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.
ReferralsLista parceiros próprios e permite consultar os detalhes de cada cadastro.
PartnersCadastra um parceiro respeitando as regras e os limites do plano.
PartnersAtualiza, ativa ou desativa um parceiro próprio.
PartnersO administrador registra na operação principal. Para registrar em uma loja específica, use a API Key de um operador autorizado nela.
SalesConsulta o extrato paginado, o saldo atual e, quando aplicável, a composição do saldo por parceiro.
TransactionsEstorna 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.
TransactionsLista cupons/recompensas disponíveis para a operação.
CouponsCadastra uma recompensa usando as regras e os limites existentes da operação.
CouponsAtualiza, ativa ou desativa uma recompensa existente.
CouponsAtualiza estoque de uma recompensa específica.
CouponsLista vouchers com paginação opcional.
VouchersValida voucher pelo código informado.
VouchersExecuta o resgate manual existente, verificando saldo e registrando o voucher e a movimentação de forma atômica.
VouchersLista os planos para participantes configurados no clube.
PlansLista assinaturas e permite filtrar acessos ativos, inadimplentes, vencidos ou cancelados.
SubscriptionsConsulta dependentes vinculados ao titular e sua elegibilidade herdada.
DependentsCadastra dependente respeitando empresa, titular e limite do plano.
DependentsAtualiza os dados suportados do dependente; sua elegibilidade continua herdada do titular.
DependentsAtualiza, ativa ou desativa uma categoria sem remover seus vínculos existentes.
CategoriesConcilia vidas ativas por plano e período, com paginação.
EligibilityCadastra destinos HTTPS para eventos assinados de ativação, inadimplência, expiração e cancelamento de assinaturas.
WebhooksConsulta o histórico de entregas para investigar tentativas e falhas dos eventos de assinatura.
WebhooksEmite acesso assinado, curto e de uso único para fornecedores vinculados.
AccessAtiva, suspende ou encerra o acesso do participante a um plano sem alterar cobranças no gateway.
SubscriptionsRecursos 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.
Cadastro, busca, atualização, ativação e desativação por documento, telefone ou ID, respeitando a visibilidade do operador.
Registro de compras externas para gerar cashback, pontos ou vouchers.
Cadastro, atualização, ativação, desativação e controle de estoque das recompensas.
Consulta, validação e resgate manual pelo processo oficial, com verificação de saldo.
Criação, atualização, ativação e desativação das categorias da operação.
Mantém parceiros próprios e consulta indicações diretas sem criar uma rede multinível ou alterar recompensas.
Consulta planos e sincroniza o status de acesso dos participantes com sistemas e fornecedores externos.
Mantém vínculos familiares e concilia titulares e dependentes ativos sem transportar dados clínicos.
Entrega os eventos de assinatura suportados com assinatura e retentativas. Para fornecedores vinculados, emite acesso temporário de uso único.
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.
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.
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.
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.
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.
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.
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.
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.
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.