Rex
Entrar Criar conta
Rex API › Referência
Base URL: https://app.rex.com.br/api/v1

Referência da API

A API Rex permite gerenciar programaticamente ofertas, afiliados e links de checkout da sua loja. Você também pode iniciar sessões de pagamento e receber notificações de vendas em tempo real via webhooks.

🏷️

Ofertas

Crie e gerencie as ofertas com desconto da sua loja.

👥

Afiliados

Convide afiliados e acompanhe o desempenho deles.

🔗

Links

Gere links de checkout exclusivos por afiliado.

🚀

Checkout

Inicie uma sessão de pagamento e redirecione o comprador.

🪝

Webhooks

Seja notificado instantaneamente quando uma venda for confirmada.

🎟️

Vouchers

O comprador recebe um voucher para resgatar na loja física.

Autenticação

Todas as requisições à API devem incluir a chave de API da sua loja no cabeçalho Authorization usando o esquema Bearer. Cada loja possui duas chaves independentes — Produção (Live) para uso real e Sandbox para testes sem cobranças. Gerencie as chaves em Painel da Loja → Chaves de API.

Cada chave vale apenas no seu próprio ambiente: a chave de produção autentica no host de produção, e a chave sandbox em staging.rex.app.br. Usar uma no ambiente da outra retorna 401 Unauthorized — então aponte cada chave para o host correspondente.

Cabeçalho HTTP 
Authorization: Bearer <sua_api_key>
exemplo curl — produção 
curl https://app.rex.com.br/api/v1/offers \
  -H "Authorization: Bearer <chave_producao>"
exemplo curl — sandbox 
curl https://staging.rex.app.br/api/v1/offers \
  -H "Authorization: Bearer <chave_sandbox>"
⚠️

Mantenha sua chave de produção privada. Nunca a exponha em código client-side ou repositórios públicos. Se comprometida, regenere-a imediatamente pelo Painel. A chave sandbox não gera cobranças reais, mas só autentica em staging.rex.app.br — ela não funciona contra o host de produção.

Erros

A API usa códigos de status HTTP convencionais. Erros retornam um JSON com o campo error (ou array errors para falhas de validação).

200 OK Requisição bem-sucedida.
201 Created Recurso criado com sucesso.
204 No Content Recurso excluído com sucesso.
401 Unauthorized Chave de API ausente ou inválida.
404 Not Found Recurso não encontrado ou não pertence à sua loja.
422 Unprocessable Entity Validação falhou. Verifique o array errors.
422 — erro de validação 
{
  "errors": ["Title can't be blank", "Commission percent must be greater than 0"]
}

Checkout — Como Funciona

O Rex processa pagamentos via Pagar.me. A integração envolve três passos simples:

1

Crie uma Sessão de Checkout

Chame POST /api/v1/checkout_sessions com o offer_id (e o offer_variant_id, se a oferta tiver variações). Você recebe um checkout_url.

2

Redirecione o Comprador

Redirecione o navegador do comprador para o checkout_url. Ele abre a página PIX hospedada pelo próprio Rex, com o QR Code para pagamento.

3

Receba o Webhook

Após a confirmação do pagamento, o Rex envia um POST para o seu webhook_url configurado com os detalhes da venda.

POST /api/v1/checkout_sessions

Criar Sessão de Checkout

Cria uma sessão de pagamento para uma oferta e retorna um checkout_url para onde você deve redirecionar o comprador.

Parâmetros

offer_id obrigatório
integer ID da oferta a ser comprada.
offer_variant_id
integer ID da variação escolhida. <strong>Obrigatório quando a oferta tem variações</strong> — é ela que carrega o preço cobrado. Deve estar ativa e pertencer à oferta. Ignorado em ofertas sem variações.
affiliate_token
string Token do link de afiliado. Se fornecido, a venda será atribuída ao afiliado.
buyer_name
string Nome do comprador, gravado na venda.
buyer_email
string E-mail do comprador, enviado ao Pagar.me.
buyer_document
string CPF do comprador, somente dígitos.
buyer_phone
string Telefone com DDD (ex: <code class='ic'>(11) 99999-9999</code>). Precisa de ao menos 10 dígitos; abaixo disso é ignorado.
Corpo da requisição 
{
  "offer_id": 3,
  "offer_variant_id": 12,
  "affiliate_token": "FuVUcvE_t2A",
  "buyer_name": "João Silva",
  "buyer_email": "joao@exemplo.com",
  "buyer_document": "12345678900",
  "buyer_phone": "(11) 99999-9999"
}
curl 
curl -X POST https://app.rex.com.br/api/v1/checkout_sessions \\
  -H "Authorization: Bearer <sua_api_key>" \\
  -H "Content-Type: application/json" \\
  -d '{"offer_id": 3, "offer_variant_id": 12, "affiliate_token": "FuVUcvE_t2A"}'
Resposta 
HTTP/1.1 201 Created

{
  "checkout_url": "https://app.rex.com.br/purchases/42/pix"
}

Webhooks — Configuração

Configure um endpoint HTTPS público no seu servidor para receber notificações de venda. Defina sua URL em Painel da Loja → Configurações → Webhook URL.

O Rex enviará uma requisição POST para sua URL a cada venda confirmada. Seu endpoint deve responder com 2xx em até 10 segundos.

💡 Dica

Durante o desenvolvimento você pode usar webhook.site ou ngrok para receber webhooks na sua máquina local.

Webhooks — Referência do Payload

O Rex envia um POST com Content-Type: application/json.

POST your_webhook_url 
{
  "event":      "sale.created",
  "sale_id":    42,
  "offer":      "Hambúrguer Artesanal + Fritas",
  "customer":   "João Silva",
  "amount_cents": 3200
}
event string Tipo do evento. Atualmente sempre sale.created.
sale_id integer Identificador único da venda.
offer string Título da oferta comprada.
customer string Nome do comprador.
amount_cents integer Valor total pago em centavos (ex: 3200 = R$ 32,00).
GET /api/v1/offers

Listar Ofertas

Retorna todas as ofertas da loja autenticada, ordenadas por data de criação (mais recente primeiro).

curl 
curl https://app.rex.com.br/api/v1/offers \\
  -H "Authorization: Bearer <sua_api_key>"
Resposta 
HTTP/1.1 200 OK

[
  {
    "id": 1,
    "title": "Hambúrguer Artesanal + Fritas",
    "description": "Pão brioche 200g, batata frita rústica.",
    "original_price_cents": 4500,
    "discounted_price_cents": 3200,
    "commission_percent": 20,
    "valid_days": 30,
    "active": true,
    "created_at": "2026-03-01T10:00:00Z",
    "variants": []
  },
  {
    "id": 2,
    "title": "Camiseta Básica",
    "description": "Algodão penteado.",
    "original_price_cents": null,
    "discounted_price_cents": null,
    "commission_percent": 15,
    "valid_days": 30,
    "active": true,
    "created_at": "2026-03-02T10:00:00Z",
    "variants": [
      { "id": 12, "color": "Preto", "size": "M",
        "original_price_cents": 8990, "discounted_price_cents": 5990, "active": true },
      { "id": 13, "color": "Branco", "size": "G",
        "original_price_cents": 8990, "discounted_price_cents": 6990, "active": false }
    ]
  }
]
POST /api/v1/offers

Criar Oferta

Cria uma nova oferta para a loja.

Parâmetros

title obrigatório
string Nome da oferta.
description
string Descrição completa exibida para os compradores.
original_price_cents
integer Preço original em centavos (ex: 4500 = R$45,00). Obrigatório <strong>apenas</strong> se a oferta não tiver variações.
discounted_price_cents
integer Preço com desconto em centavos. Valor cobrado do comprador. Obrigatório <strong>apenas</strong> se a oferta não tiver variações.
commission_percent obrigatório
integer Percentual da venda creditado ao afiliado (1–100).
valid_days
integer Quantos dias o voucher é válido após a compra.
active
boolean Se a oferta está ativa. Padrão: <code class='ic'>true</code>.
variants_attributes
array Variações (cor e/ou tamanho), cada uma com seu próprio preço. Veja a seção <a href='#offers-variants' style='color:#60a5fa;text-decoration:underline;'>Variações</a>.
Corpo da requisição 
{
  "offer": {
    "title": "Camiseta Básica",
    "description": "Algodão penteado.",
    "commission_percent": 15,
    "valid_days": 30,
    "variants_attributes": [
      { "color": "Preto",  "size": "M",
        "original_price_cents": 8990, "discounted_price_cents": 5990 },
      { "color": "Branco", "size": "G",
        "original_price_cents": 8990, "discounted_price_cents": 6990 }
    ]
  }
}
curl 
curl -X POST https://app.rex.com.br/api/v1/offers \\
  -H "Authorization: Bearer <sua_api_key>" \\
  -H "Content-Type: application/json" \\
  -d '{"offer": {"title": "Hambúrguer + Fritas", "commission_percent": 20, "discounted_price_cents": 3200}}'
Resposta 
201 Created  +  objeto da oferta (veja Listar Ofertas para o schema)
PATCH /api/v1/offers/:id

Atualizar Oferta

Atualiza um ou mais campos de uma oferta existente.

Parâmetros

title
string Novo título.
commission_percent
integer Novo percentual de comissão.
discounted_price_cents
integer Novo preço com desconto em centavos.
active
boolean Ativar (<code class='ic'>true</code>) ou desativar (<code class='ic'>false</code>) a oferta.
variants_attributes
array Cria, atualiza (com <code class='ic'>id</code>) ou remove (com <code class='ic'>_destroy</code>) variações. Veja <a href='#offers-variants' style='color:#60a5fa;text-decoration:underline;'>Variações</a>.
Corpo da requisição 
{
  "offer": {
    "commission_percent": 25,
    "discounted_price_cents": 2900
  }
}
curl 
curl -X PATCH https://app.rex.com.br/api/v1/offers/1 \\
  -H "Authorization: Bearer <sua_api_key>" \\
  -H "Content-Type: application/json" \\
  -d '{"offer": {"commission_percent": 25}}'
Resposta 
200 OK  +  objeto da oferta atualizada
DELETE /api/v1/offers/:id

Excluir Oferta

Exclui permanentemente uma oferta e todos os links de afiliado associados.

curl 
curl -X DELETE https://app.rex.com.br/api/v1/offers/1 \\
  -H "Authorization: Bearer <sua_api_key>"
Resposta 
HTTP/1.1 204 No Content

Variações de Produto

Uma oferta pode ter variações por cor e/ou tamanho. Cada variação carrega o seu próprio preço completo — não é um acréscimo sobre o preço da oferta. Quando existem variações, o preço padrão da oferta (discounted_price_cents) pode ficar em branco, e as listagens passam a exibir o valor da variação ativa mais barata.

id integer Só no update — identifica a variação existente. Omita para criar uma nova.
color string Cor da variação (ex: Preto). Opcional se size for informado.
size string Tamanho da variação (ex: M). Opcional se color for informado.
original_price_cents integer Preço cheio da variação em centavos. Mínimo 100 (R$ 1,00).
discounted_price_cents integer Preço cobrado desta variação em centavos. Mínimo 100 e não pode ser maior que o original.
active boolean Variações inativas não podem ser compradas, mas continuam aparecendo nesta API.
_destroy boolean Envie true junto com o id para excluir a variação.

⚠️ Regras que costumam pegar

  • Informe cor ou tamanho — uma variação sem os dois é rejeitada.
  • A combinação cor + tamanho é única por oferta, sem diferenciar maiúsculas (Preto/M colide com preto/m).
  • Para criar uma oferta sem preço padrão, envie as variações na mesma requisição. Criar a oferta primeiro e adicionar variações depois falha, porque na primeira gravação ela ainda não tem variação alguma e o preço padrão passa a ser obrigatório.
  • No checkout, oferta com variações exige offer_variant_id; sem ele a resposta é 422.

Atualizar preço de uma variação e excluir outra 

curl -X PATCH https://app.rex.com.br/api/v1/offers/2 \
  -H "Authorization: Bearer <sua_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "offer": {
      "variants_attributes": [
        { "id": 12, "discounted_price_cents": 4990 },
        { "id": 13, "_destroy": true },
        { "color": "Azul", "size": "P",
          "original_price_cents": 8990, "discounted_price_cents": 6490 }
      ]
    }
  }'
GET /api/v1/affiliates

Listar Afiliados

Sem filtro, retorna os afiliados que possuem links para as ofertas da sua loja. Com <code class='ic'>?doc=</code>, a busca é global à plataforma — serve para localizar um afiliado que já existe antes de convidá-lo.

Parâmetros

doc
string Busca pelo CPF ou CNPJ do afiliado (query parameter). Aceita com ou sem pontuação. <strong>Esta busca não se limita à sua loja</strong>: encontra qualquer afiliado da plataforma.
curl 
curl "https://app.rex.com.br/api/v1/affiliates?doc=123.456.789-00" \\
  -H "Authorization: Bearer <sua_api_key>"
Resposta 
HTTP/1.1 200 OK

[
  {
    "id": 5,
    "name": "Maria Afiliada",
    "email": "maria@email.com",
    "document": "123.456.789-00",
    "phone_ddd": "11",
    "phone_number": "999990000",
    "created_at": "2026-01-15T12:00:00Z"
  }
]
GET /api/v1/affiliates/:id

Buscar Afiliado

Retorna um afiliado específico incluindo seus links para as ofertas da sua loja.

curl 
curl https://app.rex.com.br/api/v1/affiliates/5 \\
  -H "Authorization: Bearer <sua_api_key>"
Resposta 
HTTP/1.1 200 OK

{
  "id": 5,
  "name": "Maria Afiliada",
  "email": "maria@email.com",
  "document": "123.456.789-00",
  "phone_ddd": "11",
  "phone_number": "999990000",
  "created_at": "2026-01-15T12:00:00Z",
  "affiliate_links": [
    {
      "id": 12,
      "offer_id": 3,
      "token": "FuVUcvE_t2A",
      "checkout_url": "https://app.rex.com.br/checkout/3?token=FuVUcvE_t2A",
      "click_count": 47
    }
  ]
}
POST /api/v1/affiliates

Convidar Afiliado

Cria uma nova conta de afiliado com senha aleatória gerada automaticamente. O afiliado precisa redefinir a senha para acessar o painel.

Parâmetros

name obrigatório
string Nome completo do afiliado.
email obrigatório
string E-mail (será usado para login).
document obrigatório
string CPF ou CNPJ. Deve ser único entre todos os afiliados. Aceita com ou sem pontuação — é gravado só com dígitos.
phone_ddd
string DDD, somente dígitos (ex: <code class='ic'>11</code>). Envie junto com <code class='ic'>phone_number</code>.
phone_number
string Número sem o DDD, somente dígitos (ex: <code class='ic'>999990000</code>). O telefone precisa vir <strong>separado em DDD e número</strong> — um campo único <code class='ic'>phone</code> é descartado sem erro, e sem ele o afiliado não recebe repasses do Pagar.me.
Corpo da requisição 
{
  "affiliate": {
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "987.654.321-00",
    "phone_ddd": "21",
    "phone_number": "988881234"
  }
}
curl 
curl -X POST https://app.rex.com.br/api/v1/affiliates \\
  -H "Authorization: Bearer <sua_api_key>" \\
  -H "Content-Type: application/json" \\
  -d '{"affiliate": {"name": "João Silva", "email": "joao@email.com", "document": "98765432100"}}'
Resposta 
201 Created  +  objeto do afiliado (veja Listar Afiliados para o schema)
Rex API v1
© 2026 Rex