hyype.com.br/docs/api

Partner API

Integre seu sistema com a Hyype: produtos, ofertas, conteúdos, vendas, leads e checkout — tudo do seu negócio, com um token.

Começar em 4 passos

A Partner API permite que outro sistema (ERP, CRM, automação ou agente de IA) leia e gerencie dados do seu negócio na Hyype, sem usar o painel manualmente.

Entre no painel da Hyype com a conta do produtor (dono do negócio).
Abra Configurações e vá até a seção Chaves de API / Partner API.
Crie uma chave, copie o token e guarde com segurança — ele só aparece na criação.
Cole o token no campo abaixo (ou use no seu sistema) e comece pelas rotas de Produtos → Ofertas → Entregáveis.

Onde obter o token: app.hyype.com.br/settings → Chaves de API

Como produto, oferta e conteúdo se relacionam

Na Hyype, vender algo digital não é um único cadastro. São peças que se ligam. Pense assim:

1. Produto

É o “pacote” que você vende — o nome e a identidade do que o cliente compra (ex.: Curso de Marketing).

2. Oferta

É a forma de vender o produto: preço, recorrência, status. Um produto pode ter várias ofertas (à vista, mensal, promoção).

3. Conteúdo (entregável)

É o que o comprador recebe de fato: curso, ebook, comunidade, etc. O conteúdo se vincula ao produto para liberar o acesso após a compra.

Ordem recomendada

Crie o produto → crie a oferta ligada a esse produto (informando o produto) → crie o conteúdo. A oferta sempre depende de um produto; o conteúdo precisa ficar associado a ele para o comprador receber o acesso (no painel do produto, se ainda não vinculou pela API).

Exemplo: produto “Mentoria VIP” → oferta “R$ 997 à vista” ligada a esse produto → entregável “Área de membros”. Afiliados, checkout e vendas usam essa mesma base.

Contrato da Partner API

Toda listagem usa o mesmo envelope. Status sempre em minúsculas. Paginação vale em todas as rotas GET de lista.

Paginação

Use page (padrão 1) e per_page (padrão 25, máximo 100). A resposta traz meta.current_page, meta.per_page, meta.total e meta.last_page. Sem page você recebe só a primeira página.

Status

Carrinhos da loja e do checkout digital usam o mesmo vocabulário em minúsculas: active, pending_payment, abandoned, expired, converted. A API aceita MAIÚSCULAS na query, mas a resposta sempre volta minúscula.

Vendas, taxa e UTM

Em /sales o valor bruto é total_amount. platform_fee é a taxa da Hyype (não do gateway). net_amount = total_amount − platform_fee. A origem de tráfego vem em tracking.utm_source, tracking.utm_medium, tracking.utm_campaign, tracking.utm_term e tracking.utm_content — não é preciso fatiar metadata.referer.

Rastreio histórico

O rastreio de UTM nas vendas passou a ter cobertura confiável a partir de agosto de 2026 (reliable_from). Comparar junho/julho com agosto/setembro parece queda de tráfego pago, mas o que mudou foi a captura. Esse aviso também vem em meta.tracking de /sales e em /sales/report e /tracking/summary.

Autenticação

Em toda requisição, envie o header Authorization com o token. O negócio (domínio) é identificado automaticamente pelo token — você não precisa informar o domínio na URL.

Formato: Authorization: Bearer SEU_TOKEN
Cada token vale só para o negócio em que foi criado.
Usuários compradores não são criados pela API — eles entram pela compra/checkout. Aqui você consulta e atualiza quem já existe no seu domínio.

URL baseToken de acessoCole o token e clique em Salvar para testar os endpoints nesta página.

Usar com IA (MCP)

O MCP (Model Context Protocol) permite que ferramentas como Cursor ou Claude usem a Partner API por meio de “ferramentas” prontas — listar vendas, criar produto, consultar leads — sem você montar cada chamada HTTP na mão.

Há um servidor MCP oficial da Hyype que espelha esta API. Você configura uma vez o token e o agente passa a operar no seu negócio.

Tenha o token da Partner API (mesmo do painel).
No projeto, use o servidor em apps/mcp-partner-api (Node).
No Cursor (ou cliente MCP), adicione a configuração abaixo com seu token e reinicie o agente.

{
  "mcpServers": {
    "hyype-partner-api": {
      "command": "node",
      "args": ["./apps/mcp-partner-api/server.js"],
      "env": {
        "HYYPE_PARTNER_API_URL": "https://api.hyype.com.br/api/v1",
        "HYYPE_PARTNER_API_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Com o MCP ativo, o agente usa as mesmas rotas e o mesmo contrato desta API: paginação page/per_page, taxa Hyype (platform_fee), UTMs em tracking.utm_* e carrinhos com source=all e status em minúsculas.

Contexto

GET/me

Contexto do token

Retorna o domínio/negócio vinculado ao token, o usuário técnico da API e metadados do token atual.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/me' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "message": "OK",
  "data": {
    "tenant": {
      "id": 1,
      "name": "Minha Escola",
      "alias": "minha-escola",
      "domain": "minha-escola.hyype.com.br"
    },
    "api_user": {
      "id": 99,
      "name": "API",
      "email": "[email protected]"
    },
    "token": {
      "name": "partner-api-default",
      "abilities": [
        "partner-api"
      ],
      "last_used_at": null,
      "expires_at": null
    }
  }
}

Usuários

GET/users

Listar usuários

Lista usuários do seu domínio. Filtros: search, role e paginação.

Parâmetros

searchquery · stringBusca livre por nome, e-mail, código etc.rolequery · enumValores permitidos: member, producer, affiliate, affiliate_manager, coproducer, operator — Papel do usuário no negócio.per_pagequery · integerItens por página (1–100).pagequery · integerNúmero da página.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/users?role=member&per_page=25&page=1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "data": [
    {
      "id": 12,
      "name": "Aluno",
      "email": "[email protected]",
      "phone": "11999990000",
      "roles": [
        "member"
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

GET/users/{id}

Obter usuário

Detalhe de um usuário do seu domínio.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/users/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 12,
    "name": "Aluno",
    "email": "[email protected]",
    "phone": "11999990000",
    "roles": [
      "member"
    ],
    "notify_by_email": true
  }
}

PATCH/users/{id}

Atualizar usuário

Edita nome, e-mail, telefone e preferências de notificação. Não altera o usuário técnico da API.

Parâmetros

idpath · integerobrigatório

Body (JSON)

Campo	Tipo	Valores permitidos
name	string	texto livre
email	string	texto livre
phone	string	texto livre
notify_by_email	boolean	true, false
notify_by_whatsapp	boolean	true, false
notify_by_push	boolean	true, false

Exemplos de código

curl -X PATCH 'https://api.hyype.com.br/api/v1/users/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Nome Atualizado",
  "phone": "11999999999",
  "notify_by_email": true
}'

Exemplo de resposta

{
  "success": true,
  "message": "Usuário atualizado.",
  "data": {
    "id": 12,
    "name": "Nome Atualizado",
    "email": "[email protected]",
    "phone": "11999999999",
    "notify_by_email": true
  }
}

DELETE/users/{id}

Arquivar usuário

Arquiva o usuário. Administradores do negócio e o usuário técnico da API não podem ser removidos.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X DELETE 'https://api.hyype.com.br/api/v1/users/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "message": "Usuário arquivado.",
  "data": null
}

Produtos

GET/products

Listar produtos

Lista produtos do seu domínio.

Parâmetros

searchquery · stringBusca livre por nome, e-mail, código etc.statusquery · enumValores permitidos: draft, active, inactive, archived — Status do produto.typequery · enumValores permitidos: digital, course, bundle, subscription, ebook, masterclass, consulting, membership, physical, digital_download, live_series — Tipo do produto.per_pagequery · integerItens por página (1–100).pagequery · integerNúmero da página.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/products?status=active&type=course&per_page=25&page=1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Curso de Marketing",
      "slug": "curso-marketing",
      "status": "active",
      "type": "course",
      "base_price": 197,
      "currency_code": "BRL"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

POST/products

Criar produto

Cria um produto no domínio autenticado pelo token.

Body (JSON)

Campo	Tipo	Valores permitidos
nameobrigatório	string	texto livre
description	string	texto livre
long_description	string	texto livre
type	string	digital, course, bundle, subscription, ebook, masterclass, consulting, membership, physical, digital_download, live_series
status	string	draft, active, inactive, archived
base_price	number	texto livre
currency_code	string	BRL, USD, EUR
is_featured	boolean	true, false
metadata	object	texto livre

Exemplos de código

curl -X POST 'https://api.hyype.com.br/api/v1/products' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Meu Produto",
  "description": "Descrição curta",
  "type": "course",
  "status": "draft",
  "base_price": 97,
  "currency_code": "BRL"
}'

Exemplo de resposta

{
  "success": true,
  "message": "Produto criado.",
  "data": {
    "id": 1,
    "name": "Meu Produto",
    "type": "course",
    "status": "draft",
    "base_price": 97,
    "currency_code": "BRL"
  }
}

GET/products/{id}

Obter produto

Detalhe com ofertas e entregáveis vinculados.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/products/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 1,
    "name": "Curso de Marketing",
    "status": "active",
    "type": "course",
    "variants": [
      {
        "id": 10,
        "name": "À vista",
        "price": 197
      }
    ]
  }
}

PUT/products/{id}

Atualizar produto

Atualiza campos do produto.

Parâmetros

idpath · integerobrigatório

Body (JSON)

Campo	Tipo	Valores permitidos
name	string	texto livre
description	string	texto livre
type	string	digital, course, bundle, subscription, ebook, masterclass, consulting, membership, physical, digital_download, live_series
status	string	draft, active, inactive, archived
base_price	number	texto livre
currency_code	string	BRL, USD, EUR
is_featured	boolean	true, false
slug	string	texto livre
metadata	object	texto livre

Exemplos de código

curl -X PUT 'https://api.hyype.com.br/api/v1/products/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Produto Atualizado",
  "status": "active"
}'

DELETE/products/{id}

Remover produto

Remove o produto do catálogo ativo.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X DELETE 'https://api.hyype.com.br/api/v1/products/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Ofertas

GET/offers

Listar ofertas

Ofertas de venda vinculadas a produtos do domínio.

Parâmetros

product_idquery · integerID do produto no seu domínio.statusquery · enumValores permitidos: active, inactive, sold_out — Status da oferta.searchquery · stringBusca livre por nome, e-mail, código etc.per_pagequery · integerItens por página (1–100).pagequery · integerNúmero da página.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/offers?product_id=1&status=active&per_page=25&page=1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "data": [
    {
      "id": 10,
      "name": "À vista",
      "price": 197,
      "status": "active",
      "product_id": 1
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

POST/offers

Criar oferta

Cria oferta vinculada a um product_id do seu domínio.

Body (JSON)

Campo	Tipo	Valores permitidos
product_idobrigatório	integer	texto livre
nameobrigatório	string	texto livre
description	string	texto livre
priceobrigatório	number	texto livre
compare_at_price	number	texto livre
currency_code	string	BRL, USD, EUR
billing_type	string	one_time, recurring
billing_period	string	monthly, quarterly, yearly
status	string	active, inactive, sold_out
sku	string	texto livre
is_default	boolean	true, false
metadata	object	texto livre

Exemplos de código

curl -X POST 'https://api.hyype.com.br/api/v1/offers' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "product_id": 1,
  "name": "Oferta principal",
  "price": 197,
  "currency_code": "BRL",
  "billing_type": "one_time",
  "status": "active"
}'

GET/offers/{id}

Obter oferta

Detalhe da oferta.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/offers/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

PUT/offers/{id}

Atualizar oferta

Atualiza preço, status, cobrança e metadados.

Parâmetros

idpath · integerobrigatório

Body (JSON)

Campo	Tipo	Valores permitidos
name	string	texto livre
description	string	texto livre
price	number	texto livre
compare_at_price	number	texto livre
currency_code	string	BRL, USD, EUR
billing_type	string	one_time, recurring
billing_period	string	monthly, quarterly, yearly
status	string	active, inactive, sold_out
sku	string	texto livre
is_default	boolean	true, false
sales_page_url	string	texto livre
metadata	object	texto livre

Exemplos de código

curl -X PUT 'https://api.hyype.com.br/api/v1/offers/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "price": 247,
  "status": "active"
}'

DELETE/offers/{id}

Remover oferta

Remove a oferta do catálogo ativo.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X DELETE 'https://api.hyype.com.br/api/v1/offers/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Afiliados

GET/affiliates

Listar afiliados

Afiliados vinculados às ofertas do seu domínio.

Parâmetros

offer_idquery · integerID da oferta.statusquery · enumValores permitidos: pending, accepted, rejected, expired — Status do vínculo de afiliado.is_activequery · enumValores permitidos: true, falsesearchquery · stringBusca livre por nome, e-mail, código etc.per_pagequery · integerItens por página (1–100).pagequery · integerNúmero da página.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/affiliates?status=accepted&is_active=true&per_page=25&page=1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "data": [
    {
      "id": 3,
      "email": "[email protected]",
      "commission_percentage": 30,
      "status": "accepted",
      "is_active": true
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

POST/affiliates

Criar afiliado

Convida ou cadastra afiliado em uma oferta.

Body (JSON)

Campo	Tipo	Valores permitidos
offer_idobrigatório	integer	ID da oferta.
emailobrigatório	string	texto livre
user_id	integer	texto livre
commission_percentage	number	texto livre
commission_fixed	number	texto livre
status	string	pending, accepted, rejected, expired
is_active	boolean	true, false
attribution_model	string	last_click, first_click
cookie_duration_days	integer	texto livre

Exemplos de código

curl -X POST 'https://api.hyype.com.br/api/v1/affiliates' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "offer_id": 1,
  "email": "[email protected]",
  "commission_percentage": 30,
  "status": "pending",
  "attribution_model": "last_click"
}'

GET/affiliates/{id}

Obter afiliado

Detalhe do vínculo de afiliado.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/affiliates/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

PUT/affiliates/{id}

Atualizar afiliado

Comissão, status e ativação.

Parâmetros

idpath · integerobrigatório

Body (JSON)

Campo	Tipo	Valores permitidos
email	string	texto livre
commission_percentage	number	texto livre
commission_fixed	number	texto livre
status	string	pending, accepted, rejected, expired
is_active	boolean	true, false
attribution_model	string	last_click, first_click
cookie_duration_days	integer	texto livre

Exemplos de código

curl -X PUT 'https://api.hyype.com.br/api/v1/affiliates/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "commission_percentage": 40,
  "is_active": true,
  "status": "accepted"
}'

DELETE/affiliates/{id}

Remover afiliado

Remove o vínculo de afiliado.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X DELETE 'https://api.hyype.com.br/api/v1/affiliates/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Entregáveis

GET/deliverables

Listar entregáveis

Conteúdos do domínio (cursos, ebooks, etc.).

Parâmetros

typequery · enumValores permitidos: course, ebook, document, masterclass, live_series, consulting, community, app, members_area — Tipo de conteúdo/entregável.statusquery · enumValores permitidos: draft, published, active, inactive — Status do entregável.searchquery · stringBusca livre por nome, e-mail, código etc.per_pagequery · integerItens por página (1–100).pagequery · integerNúmero da página.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/deliverables?type=course&status=published&per_page=25&page=1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "data": [
    {
      "id": 8,
      "name": "Curso Completo",
      "type": "course",
      "status": "published"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

POST/deliverables

Criar entregável

Cria entregável base. Use um dos tipos permitidos.

Body (JSON)

Campo	Tipo	Valores permitidos
nameobrigatório	string	texto livre
typeobrigatório	string	course, ebook, document, masterclass, live_series, consulting, community, app, members_area
description	string	texto livre
status	string	draft, published, active, inactive
thumbnail_url	string	texto livre
sort_order	integer	texto livre
metadata	object	texto livre

Exemplos de código

curl -X POST 'https://api.hyype.com.br/api/v1/deliverables' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Curso Completo",
  "type": "course",
  "status": "draft",
  "description": "Conteúdo principal"
}'

GET/deliverables/{id}

Obter entregável

Detalhe com tipo e produtos vinculados.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/deliverables/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

PUT/deliverables/{id}

Atualizar entregável

Atualiza metadados e status.

Parâmetros

idpath · integerobrigatório

Body (JSON)

Campo	Tipo	Valores permitidos
name	string	texto livre
type	string	course, ebook, document, masterclass, live_series, consulting, community, app, members_area
description	string	texto livre
status	string	draft, published, active, inactive
thumbnail_url	string	texto livre
sort_order	integer	texto livre
metadata	object	texto livre

Exemplos de código

curl -X PUT 'https://api.hyype.com.br/api/v1/deliverables/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "published"
}'

DELETE/deliverables/{id}

Remover entregável

Remove o entregável do catálogo ativo.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X DELETE 'https://api.hyype.com.br/api/v1/deliverables/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Vendas

GET/sales

Listar vendas

Vendas do domínio. Inclui platform_fee (taxa Hyype), net_amount e tracking.utm_*. Paginação: page e per_page.

Parâmetros

statusquery · enumValores permitidos: pending, paid, failed, refunded, cancelled, overdue — Status do pagamento da venda.payment_methodquery · enumValores permitidos: pix, credit_card, boleto — Meio de pagamento.fromquery · dateData inicial (YYYY-MM-DD).toquery · dateData final (YYYY-MM-DD).searchquery · stringBusca por nome, e-mail do cliente ou número da venda.per_pagequery · integerItens por página (1–100).pagequery · integerNúmero da página.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/sales?status=paid&payment_method=pix&from=2026-01-01&to=2026-12-31&per_page=25&page=1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Campos da resposta

Campo	Tipo	Descrição
id	integer	ID da venda (invoice).
invoice_number	string	Número exibido da venda.
status	string	Status em minúsculas: pending, paid, failed, refunded, cancelled, overdue.
amount	number	Subtotal da venda, sem frete/juros extras.
total_amount	number	Valor total cobrado do cliente.
tax_amount	number	Imposto da nota — não é taxa da Hyype nem do gateway. Em geral 0.
platform_fee	number	Taxa da plataforma Hyype nesta venda (R$).
platform_fee_percentage	number	Percentual da taxa Hyype aplicado.
platform_fee_fixed	number	Parcela fixa da taxa Hyype (R$).
platform_fee_source	string	applied = valor creditado na carteira; estimated = calculado pela regra atual do tenant.
net_amount	number	total_amount menos a taxa da Hyype.
tracking.utm_source	string	utm_source já separado.
tracking.utm_medium	string	utm_medium já separado.
tracking.utm_campaign	string	utm_campaign já separado.
tracking.utm_term	string	utm_term já separado.
tracking.utm_content	string	utm_content já separado.
tracking_captured	boolean	true se algum UTM foi encontrado (campo próprio, carrinho ou query string).

Exemplo de resposta

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "invoice_number": "INV-ABC123",
      "status": "paid",
      "amount": 197,
      "total_amount": 197,
      "discount_amount": 0,
      "tax_amount": 0,
      "currency": "BRL",
      "payment_method": "pix",
      "payment_gateway": "asaas",
      "platform_fee": 15.74,
      "platform_fee_percentage": 7.99,
      "platform_fee_fixed": 0,
      "platform_fee_source": "applied",
      "net_amount": 181.26,
      "customer_name": "Maria Silva",
      "customer_email": "[email protected]",
      "tracking": {
        "utm_source": "facebook",
        "utm_medium": "cpc",
        "utm_campaign": "lancamento",
        "utm_term": null,
        "utm_content": "anuncio-a",
        "referrer": "https://facebook.com",
        "landing_url": null
      },
      "tracking_captured": true,
      "product": {
        "id": 1,
        "name": "Curso de Marketing",
        "slug": "curso-marketing"
      },
      "product_variant": {
        "id": 10,
        "name": "À vista",
        "sale_uuid": "sale_abc"
      },
      "paid_at": "2026-09-01T12:00:00-03:00",
      "created_at": "2026-09-01T12:00:00-03:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1,
    "tracking": {
      "reliable_from": "2026-08-01",
      "message": "O rastreio de UTM nas vendas passou a ter cobertura confiável a partir de agosto de 2026. Meses anteriores não devem ser comparados com os atuais para avaliar tráfego pago."
    }
  }
}

GET/sales/report

Relatório de vendas

Agregados: totais pagos, por método, por dia e cobertura de UTM (tracking.reliable_from).

Parâmetros

fromquery · dateData inicial (YYYY-MM-DD).toquery · dateData final (YYYY-MM-DD).

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/sales/report?from=2026-01-01&to=2026-12-31' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "message": "OK",
  "data": {
    "total_invoices": 40,
    "paid_count": 32,
    "paid_amount": 6304,
    "pending_count": 6,
    "refunded_count": 2,
    "by_payment_method": [
      {
        "payment_method": "pix",
        "count": 20,
        "amount": 3940
      }
    ],
    "by_day": [
      {
        "day": "2026-09-01",
        "count": 4,
        "amount": 788
      }
    ],
    "tracking": {
      "reliable_from": "2026-08-01",
      "message": "O rastreio de UTM nas vendas passou a ter cobertura confiável a partir de agosto de 2026. Meses anteriores não devem ser comparados com os atuais para avaliar tráfego pago.",
      "sales_with_utm": 27,
      "sales_total": 32,
      "coverage_percent": 84.4
    }
  }
}

GET/sales/{id}

Obter venda

Detalhe da venda com itens, taxa da Hyype e UTMs já separados.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/sales/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Campos da resposta

Campo	Tipo	Descrição
id	integer	ID da venda (invoice).
invoice_number	string	Número exibido da venda.
status	string	Status em minúsculas: pending, paid, failed, refunded, cancelled, overdue.
amount	number	Subtotal da venda, sem frete/juros extras.
total_amount	number	Valor total cobrado do cliente.
tax_amount	number	Imposto da nota — não é taxa da Hyype nem do gateway. Em geral 0.
platform_fee	number	Taxa da plataforma Hyype nesta venda (R$).
platform_fee_percentage	number	Percentual da taxa Hyype aplicado.
platform_fee_fixed	number	Parcela fixa da taxa Hyype (R$).
platform_fee_source	string	applied = valor creditado na carteira; estimated = calculado pela regra atual do tenant.
net_amount	number	total_amount menos a taxa da Hyype.
tracking.utm_source	string	utm_source já separado.
tracking.utm_medium	string	utm_medium já separado.
tracking.utm_campaign	string	utm_campaign já separado.
tracking.utm_term	string	utm_term já separado.
tracking.utm_content	string	utm_content já separado.
tracking_captured	boolean	true se algum UTM foi encontrado (campo próprio, carrinho ou query string).

Exemplo de resposta

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 1001,
    "invoice_number": "INV-ABC123",
    "status": "paid",
    "amount": 197,
    "total_amount": 197,
    "discount_amount": 0,
    "tax_amount": 0,
    "currency": "BRL",
    "payment_method": "pix",
    "payment_gateway": "asaas",
    "platform_fee": 15.74,
    "platform_fee_percentage": 7.99,
    "platform_fee_fixed": 0,
    "platform_fee_source": "applied",
    "net_amount": 181.26,
    "customer_name": "Maria Silva",
    "customer_email": "[email protected]",
    "tracking": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "lancamento",
      "utm_term": null,
      "utm_content": "anuncio-a",
      "referrer": "https://facebook.com",
      "landing_url": null
    },
    "tracking_captured": true,
    "product": {
      "id": 1,
      "name": "Curso de Marketing",
      "slug": "curso-marketing"
    },
    "product_variant": {
      "id": 10,
      "name": "À vista",
      "sale_uuid": "sale_abc"
    },
    "paid_at": "2026-09-01T12:00:00-03:00",
    "created_at": "2026-09-01T12:00:00-03:00"
  }
}

Checkout / Carrinhos

GET/checkout-sessions

Listar sessões

Carrinhos da loja e/ou do checkout digital. source=all une as duas origens. Status sempre em minúsculas.

Parâmetros

sourcequery · enumValores permitidos: all, store, digital — Origem dos carrinhos. all une loja e checkout digital na mesma lista.statusquery · enumValores permitidos: active, pending_payment, abandoned, expired, converted — Status do carrinho. Sempre minúsculas na resposta (abandoned, converted, …). A query aceita os dois formatos.fromquery · dateData inicial (YYYY-MM-DD).toquery · dateData final (YYYY-MM-DD).searchquery · stringBusca livre por nome, e-mail, código etc.per_pagequery · integerItens por página (1–100).pagequery · integerNúmero da página.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/checkout-sessions?source=all&status=abandoned&per_page=25&page=1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Campos da resposta

Campo	Tipo	Descrição
id	string\|integer	ID do carrinho (número na loja, UUID no digital).
source	string	store ou digital.
status	string	Status em minúsculas.
customer_email	string	E-mail capturado no carrinho.
total	number	Valor do carrinho.
utm_source	string	utm_source já separado.
utm_content	string	utm_content já separado.

Exemplo de resposta

{
  "success": true,
  "data": [
    {
      "id": 55,
      "source": "store",
      "status": "abandoned",
      "token": "2f8c1e2a-7c1a-4b0e-9f11-0c3d8a1b2c3d",
      "customer_name": "João",
      "customer_email": "[email protected]",
      "total": 197,
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": null,
      "utm_term": null,
      "utm_content": "ad-1",
      "referrer": "https://google.com",
      "landing_url": null,
      "created_at": "2026-09-01T11:00:00-03:00",
      "updated_at": "2026-09-01T11:20:00-03:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1,
    "source": "all",
    "store": {
      "current_page": 1,
      "per_page": 25,
      "total": 1,
      "last_page": 1
    },
    "digital": {
      "current_page": 1,
      "per_page": 25,
      "total": 0,
      "last_page": 1
    }
  }
}

GET/checkout-sessions/abandoned

Carrinhos abandonados

Atalho para recuperação de carrinho abandonado.

Parâmetros

sourcequery · enumValores permitidos: all, store, digital — Origem dos carrinhos. all une loja e checkout digital na mesma lista.fromquery · dateData inicial (YYYY-MM-DD).toquery · dateData final (YYYY-MM-DD).per_pagequery · integerItens por página (1–100).pagequery · integerNúmero da página.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/checkout-sessions/abandoned?source=digital&per_page=25&page=1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Campos da resposta

Campo	Tipo	Descrição
id	string\|integer	ID do carrinho (número na loja, UUID no digital).
source	string	store ou digital.
status	string	Status em minúsculas.
customer_email	string	E-mail capturado no carrinho.
total	number	Valor do carrinho.
utm_source	string	utm_source já separado.
utm_content	string	utm_content já separado.

Exemplo de resposta

{
  "success": true,
  "data": [
    {
      "id": 55,
      "source": "store",
      "status": "abandoned",
      "token": "2f8c1e2a-7c1a-4b0e-9f11-0c3d8a1b2c3d",
      "customer_name": "João",
      "customer_email": "[email protected]",
      "total": 197,
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": null,
      "utm_term": null,
      "utm_content": "ad-1",
      "referrer": "https://google.com",
      "landing_url": null,
      "created_at": "2026-09-01T11:00:00-03:00",
      "updated_at": "2026-09-01T11:20:00-03:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1,
    "source": "all"
  }
}

GET/checkout-sessions/{id}

Obter sessão

Detalhe por id numérico ou token do carrinho da loja.

Parâmetros

idpath · stringobrigatórioID numérico ou token do carrinho da loja.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/checkout-sessions/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Campos da resposta

Campo	Tipo	Descrição
id	string\|integer	ID do carrinho (número na loja, UUID no digital).
source	string	store ou digital.
status	string	Status em minúsculas.
customer_email	string	E-mail capturado no carrinho.
total	number	Valor do carrinho.
utm_source	string	utm_source já separado.
utm_content	string	utm_content já separado.

Exemplo de resposta

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 55,
    "source": "store",
    "status": "abandoned",
    "token": "2f8c1e2a-7c1a-4b0e-9f11-0c3d8a1b2c3d",
    "customer_name": "João",
    "customer_email": "[email protected]",
    "total": 197,
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": null,
    "utm_term": null,
    "utm_content": "ad-1",
    "referrer": "https://google.com",
    "landing_url": null,
    "created_at": "2026-09-01T11:00:00-03:00",
    "updated_at": "2026-09-01T11:20:00-03:00"
  }
}

Leads

GET/leads

Listar leads

Leads capturados no seu domínio.

Parâmetros

searchquery · stringBusca livre por nome, e-mail, código etc.is_clientquery · enumValores permitidos: true, false — Se o lead já é cliente.checkout_initiatedquery · enumValores permitidos: true, false — Se o lead iniciou checkout.sourcequery · stringOrigem do lead (texto livre, ex.: partner_api, ads, organic).fromquery · dateData inicial (YYYY-MM-DD).toquery · dateData final (YYYY-MM-DD).per_pagequery · integerItens por página (1–100).pagequery · integerNúmero da página.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/leads?per_page=25&page=1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "data": [
    {
      "id": 44,
      "email": "[email protected]",
      "name": "Lead Exemplo",
      "phone": "11988887777",
      "source": "partner_api",
      "is_client": false
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

POST/leads

Criar/atualizar lead

Cria lead ou atualiza se o e-mail já existir.

Body (JSON)

Campo	Tipo	Valores permitidos
emailobrigatório	string	texto livre
name	string	texto livre
phone	string	texto livre
notes	string	texto livre
source	string	Origem do lead (texto livre, ex.: partner_api, ads, organic).

Exemplos de código

curl -X POST 'https://api.hyype.com.br/api/v1/leads' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "[email protected]",
  "name": "Lead Exemplo",
  "phone": "11988887777",
  "source": "partner_api"
}'

GET/leads/{id}

Obter lead

Detalhe do lead.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/leads/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

PUT/leads/{id}

Atualizar lead

Notas, telefone e flags.

Parâmetros

idpath · integerobrigatório

Body (JSON)

Campo	Tipo	Valores permitidos
name	string	texto livre
phone	string	texto livre
notes	string	texto livre
source	string	texto livre
is_client	boolean	true, false

Exemplos de código

curl -X PUT 'https://api.hyype.com.br/api/v1/leads/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "notes": "Contatado via WhatsApp",
  "is_client": false
}'

DELETE/leads/{id}

Remover lead

Exclui o lead.

Parâmetros

idpath · integerobrigatório

Exemplos de código

curl -X DELETE 'https://api.hyype.com.br/api/v1/leads/1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Tracking

GET/tracking/pixels

Listar pixels

Pixels de conversão nos produtos (sem expor segredos).

Parâmetros

platformquery · enumValores permitidos: meta_ads, google_ads, analytics, tag_manager, tiktok — Plataforma de pixel/ads.product_idquery · integerID do produto no seu domínio.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/tracking/pixels?platform=meta_ads' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "id": 1,
      "product_id": 1,
      "platform": "meta_ads",
      "pixel_id": "123456789",
      "enabled_events": [
        "Purchase"
      ],
      "has_access_token": true
    }
  ]
}

GET/tracking/summary

Resumo de tracking

Totais por plataforma e aviso de cobertura histórica de UTM nas vendas.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/tracking/summary' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "message": "OK",
  "data": {
    "products_with_pixels": 2,
    "total_pixels": 3,
    "by_platform": {
      "meta_ads": 2,
      "google_ads": 1
    },
    "sales_utm": {
      "reliable_from": "2026-08-01",
      "message": "O rastreio de UTM nas vendas passou a ter cobertura confiável a partir de agosto de 2026. Meses anteriores não devem ser comparados com os atuais para avaliar tráfego pago."
    }
  }
}

Logs de mensageria

GET/messaging-logs

Listar logs

Fila de mensagens enviadas apenas deste domínio (e-mail, WhatsApp, push).

Parâmetros

channelquery · enumValores permitidos: email, whatsapp, push, internal — Canal da mensagem.statusquery · enumValores permitidos: pending, processing, sent, failed, cancelled, bounced — Status na fila de envio.searchquery · stringBusca por destinatário, nome ou assunto.fromquery · dateData inicial (YYYY-MM-DD).toquery · dateData final (YYYY-MM-DD).per_pagequery · integerItens por página (1–100).pagequery · integerNúmero da página.

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/messaging-logs?channel=email&status=sent&per_page=25&page=1' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "data": [
    {
      "id": 77,
      "channel": "email",
      "status": "sent",
      "recipient_address": "[email protected]",
      "subject": "Seu acesso"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

GET/messaging-logs/{id}

Obter log

Detalhe de uma mensagem na fila.

Parâmetros

idpath · stringobrigatório

Exemplos de código

curl -X GET 'https://api.hyype.com.br/api/v1/messaging-logs/%7Bid%7D' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI' \
  -H 'Accept: application/json' \

Exemplo de resposta

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 77,
    "channel": "email",
    "status": "sent",
    "recipient_address": "[email protected]",
    "subject": "Seu acesso",
    "body": "Olá, seu acesso foi liberado."
  }
}