API de loja direta

01Arquitetura

O fluxo tem duas comunicações obrigatórias da loja para a Cashbanx, sempre nesta ordem: a notificação do pedido e, depois, a atualização do status para concluído ou cancelado.

1. Dentro de uma página da Cashbanx específica do parceiro é disponibilizado um link para o site da loja. Esse link carrega o identificador do clique — um valor no formato hub_<número>, entregue num parâmetro de URL cujo nome é combinado com cada loja no momento do cadastro.
2. Ao clicar, uma nova aba abre o site da loja. Ex.: https://www.paginadolojaxpto.com.br/?token=hub_1234567
3. No site da loja o cliente seleciona os produtos e fecha o pedido. A loja deve guardar o identificador do clique recebido na URL e associá-lo ao pedido.
4. Após a confirmação do pedido, a loja notifica a Cashbanx (purchase-made), devolvendo o identificador do clique no campo click_id. Nesse momento a Cashbanx comunica a Esfera, que informa o cliente por e-mail sobre a compra. O pedido nasce pendente: nenhuma pontuação é liberada ainda.
5. Após o prazo legal de cancelamento e a negociação com o time comercial da Cashbanx, a loja atualiza o status do pedido (confirm-purchase) — concluído ou cancelado.

Quem calcula a pontuação

A loja informa o valor do pedido; quem apura a pontuação é a Cashbanx, a partir da comissão registrada no cadastro da loja e da regra do programa. O campo points da notificação é informativo: ele é armazenado junto ao pedido, mas não determina o que o cliente recebe.

02Ambientes

Todos os endpoints deste documento são publicados sob o prefixo /api. Substitua {cashbanx_url} pelo host do ambiente:

03Credenciais e identificação

A Cashbanx entrega à loja, por ambiente:

• client_id e client_secret — usados apenas para obter o token de acesso. O client_secret é exibido uma única vez no momento da criação; perdido, ele é substituído por um novo, não recuperado.
• partner_id — o identificador da loja no cadastro da Cashbanx, enviado no corpo das duas chamadas.

A credencial é o que determina a loja e o programa em que o pedido será lançado. O partner_id enviado no corpo precisa ser exatamente o da credencial usada; qualquer outro valor é recusado com partner not found. Nenhum campo do corpo altera o destino do lançamento.

04Autenticação

OAuth 2.0, fluxo client_credentials. O token tem validade de 30 minutos (expires_in: 1800) e deve ser reutilizado enquanto for válido — obtenha um novo apenas quando o anterior expirar.

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

Retorno 200 · sucesso

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 1800,
  "token_type": "bearer"
}

O fluxo client_credentials não emite refresh_token nem refresh_expires_in (RFC 6749, §4.4.3): a loja já possui as credenciais e solicita um novo token quando precisar. O parâmetro encrypted não é aceito.

Retorno 4xx · erro — o corpo de erro é sempre o mesmo formato:

{ "errorCode": "invalid_client", "errorMessage": "client_id or client_secret is incorrect" }

05API · Notificação de Pedido

Informa que um pedido foi realizado. O pedido é registrado como pendente e aguarda a atualização de status descrita na seção 6.

Authorization: Bearer {access_token}
Content-Type: application/json

Exemplo de requisição

{
  "customer_id": "01245678901",
  "customer_id_type": "CPF",
  "customer_name": "João da Silva",
  "customer_mail": "joaodasilva@hotmail.com",
  "customer_phone": "11999999999",
  "click_id": "hub_1234567",
  "partner_id": "ABC",
  "campaign_id": "DEFG1234",
  "order_id": "1234567891",
  "order_date": "2026-01-01",
  "points": 100,
  "order_total": 100.50,
  "order_item_quantity": 1,
  "order_item_sku": "0987654321",
  "address_street": "Rua XPTO",
  "address_number": "200",
  "address_complement": "AP 100",
  "address_city": "São Paulo",
  "address_uf": "SP",
  "address_country": "Brasil"
}

Retorno 200 · sucesso

{ "message": "Purchase received." }

06API · Atualização de Pedido

Conclui ou cancela um pedido notificado anteriormente. É esta chamada que libera ou cancela a pontuação do cliente.

Authorization: Bearer {access_token}
Content-Type: application/json

Pedido concluído · libera a pontuação

{
  "partner_id": "ABC",
  "order_id": "1234567891",
  "order_status": "COMPLETED",
  "order_date": "2026-01-01",
  "order_update_date": "2026-02-15",
  "status_description": "Pedido entregue"
}

{ "message": "Confirmed order." }

Pedido cancelado · não libera a pontuação

{
  "partner_id": "ABC",
  "order_id": "1234567891",
  "order_status": "CANCELED",
  "order_update_date": "2026-02-15",
  "status_description": "Cancelado por motivo específico"
}

{ "message": "Order canceled." }

07E-mails transacionais

Quando a loja notifica que o pedido foi realizado, a Cashbanx informa a Esfera para que ela faça a comunicação ao cliente por e-mail. Quem dispara o e-mail é a Esfera, não a Cashbanx.

Assunto: "Você vai ganhar pontos na Esfera!"

08Notas de integração

• Reenvio após timeout é seguro. O order_id é a chave de idempotência: um reenvio da notificação responde order_id duplicated e uma segunda atualização responde Order already processed. Em nenhum dos casos há crédito em duplicidade.
• Não existe valor negativo. Estorno e devolução não são representados por order_total negativo — o caminho publicado é o CANCELED, e apenas enquanto o pedido não tiver sido atualizado.
• Guarde o click_id por pedido. Reaproveitar o identificador de um clique antigo em um pedido novo faz a pontuação ser apurada pela taxa errada, sem que nada acuse o problema.
• Reutilize o token durante os 30 minutos de validade. Solicitações de token são limitadas a 20 por minuto por client_id.
• Campo não previsto neste documento é recusado com Bad Request. Envie apenas os campos publicados.