API do Crownbot | Documentação

Visão geral

A API deixa o seu sistema, site ou automação falar com a sua conta do Crownbot: ver todas as vendas, gerar Pix, cuidar dos produtos e cupons, acompanhar a carteira, mandar mensagens pelos seus bots do Telegram e receber um aviso na hora em que uma venda acontece.

Endereço base

https://www.crownbot.com.br/api/v1

Pedidos e respostas em JSON (UTF-8). Nomes dos campos em português, sem acento.
Dinheiro sempre em centavos, como número inteiro: 1990 é R$ 19,90.
Datas das respostas em ISO 8601, no fuso UTC. Nos filtros, uma data sem hora (2026-09-24) é contada no horário de Brasília.
Listas vêm como { "dados": [...], "proximo": ... } (veja Paginação).
A v1 só cresce: campos e rotas novos podem aparecer. Ignore campos que o seu código não conhece.

Primeiro teste

Terminal

curl https://www.crownbot.com.br/api/v1/conta \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Cobrar pelo seu sistema

Gere o Pix com a referencia do seu pedido e libere o acesso quando chegar o aviso venda.paga com essa mesma referencia.

Node.js

const CHAVE = process.env.CROWNBOT_CHAVE; // cbk_...

async function cobrar(pedidoId, centavos) {
  const resposta = await fetch("https://www.crownbot.com.br/api/v1/pix", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${CHAVE}`,
      "Content-Type": "application/json",
      // Repetir com a mesma chave devolve o mesmo Pix: sem cobrança em dobro.
      "Idempotency-Key": `pedido-${pedidoId}`,
    },
    body: JSON.stringify({ valor_centavos: centavos, descricao: "Pedido " + pedidoId, referencia: pedidoId }),
  });
  const dados = await resposta.json();
  if (!resposta.ok) throw new Error(`${dados.error}: ${dados.mensagem}`);
  return dados.pix; // mostre dados.pix.qr_code e dados.pix.copia_e_cola
}

Autenticação

Crie a chave em Painel > Sistemas externos. Ela aparece uma vez só, na criação: copie e guarde. Mande em todo pedido no cabeçalho Authorization:

Authorization: Bearer cbk_...

Permissão	O que faz
Total	Consulta tudo e altera: gera Pix, cria e edita produtos e cupons, manda mensagem pelo bot.
Só leitura	Só consulta. Boa para planilhas, painéis e ferramentas de relatório. Rota que altera responde 403 sem_permissao.

A chave age como você. Use no servidor, nunca em site, app ou bot que roda no aparelho de outra pessoa.
Até 10 chaves por conta. Uma por sistema: se uma vazar, revogue só ela no painel e ela para no pedido seguinte.
Nenhuma rota move dinheiro para fora: saque só pelo painel, para a chave Pix que você cadastrou.

Erros

Todo erro volta com o status HTTP, um error fixo (compare o seu código com ele) e uma mensagem para quem lê o log. Parâmetro inválido diz qual em campo.

Resposta 400

{
  "error": "parametro_invalido",
  "mensagem": "Parâmetro com valor fora do permitido. O campo \"campo\" diz qual.",
  "campo": "situacao"
}

error	Status	Quando
`chave_ausente`	401	Mande a chave no cabeçalho Authorization: Bearer cbk_...
`chave_invalida`	401	Chave inexistente, revogada ou com formato errado.
`sem_permissao`	403	Esta chave é só de leitura. Crie uma chave com permissão total para alterar dados.
`muitas_tentativas`	429	Muitos pedidos seguidos. Espere os segundos do cabeçalho Retry-After.
`corpo_invalido`	400	Mande um objeto JSON com Content-Type: application/json, de até 16 KB.
`parametro_invalido`	400	Parâmetro com valor fora do permitido. O campo "campo" diz qual.
`nao_encontrado`	404	Não existe nesta conta.
`indisponivel`	503	Falha temporária do nosso lado. Tente de novo em instantes.
`idempotencia_invalida`	400	Idempotency-Key precisa ter de 1 a 100 caracteres visíveis, sem espaço.
`idempotencia_conflito`	422	Esta Idempotency-Key já foi usada com outro pedido. Use uma chave nova para cada operação.
`idempotencia_em_andamento`	409	O primeiro pedido com esta Idempotency-Key ainda está rodando. Tente de novo em instantes.
`valor_invalido`	400	valor_centavos precisa ser inteiro, de 200 (R$ 2,00) a 10000000 (R$ 100.000,00).
`validade_invalida`	400	Validade fora do permitido. Pix: 15, 30, 60, 180, 720 ou 1440 minutos. Cupom: data e hora futuras.
`carteira_inativa`	409	A conta não tem a carteira do Crownbot ativa (Painel > Gateways).
`gateway_indisponivel`	502	O gateway recusou ou não respondeu. Tente de novo em instantes.
`nome_invalido`	400	Nome obrigatório, de uma linha, com até 80 caracteres.
`preco_invalido`	400	preco_centavos precisa ser inteiro, de 200 (R$ 2,00) a 10000000 (R$ 100.000,00).
`descricao_longa`	400	Descrição de até 500 caracteres.
`mensagem_longa`	400	Mensagem de entrega de até 2000 caracteres.
`link_invalido`	400	Cada link precisa de titulo (até 60) e url https:// (até 500).
`links_demais`	400	No máximo 10 links de entrega.
`bio_link_invalido`	400	bio_links só aceita ids de bio links desta conta.
`oferta_invalida`	400	Oferta extra: outro produto da conta, não arquivado, por 50 centavos até o preço cheio dele.
`arquivado`	409	Produto arquivado não entra em bio link.
`limite`	409	A conta chegou ao limite de 100 produtos à venda.
`dados_invalidos`	400	Algum campo veio com o tipo errado. Confira a documentação da rota.
`codigo_invalido`	400	Código de 3 a 32 letras, números, hífen ou sublinhado.
`codigo_em_uso`	409	A conta já tem um cupom com esse código.
`desconto_invalido`	400	Desconto: tipo "valor" (centavos, até 10000000) ou "percentual" (inteiro de 1 a 99).
`limite_invalido`	400	max_usos precisa ser inteiro positivo e não menor que os usos já feitos.
`produtos_invalidos`	400	produtos: de 1 a 100 ids de produtos seus, não arquivados, que continuam acima de R$ 2,00 com o desconto.
`cupons_limite`	409	A conta chegou ao limite de 100 cupons.
`sem_carteira`	404	A conta nunca ativou a carteira do Crownbot.
`contato_nao_encontrado`	404	Esse chat nunca conversou com este bot. O Telegram só deixa o bot escrever para quem já falou com ele.
`texto_invalido`	400	texto obrigatório, de 1 a 4096 caracteres.
`botoes_invalidos`	400	botoes: até 8, cada um com texto (até 40) e url https://.
`contato_bloqueou`	409	A pessoa bloqueou o bot.
`telegram_recusou`	502	O Telegram recusou a mensagem.

Erro 5xx ou falta de resposta: tente de novo com espera crescente (1 s, 2 s, 4 s). Nos POST, use a mesma Idempotency-Key para não criar nada em dobro.

Limites

Pedidos por chave	120 por minuto
Pix gerados pela API	300 por conta a cada 10 minutos
Mensagens pelo bot	1000 por bot por hora
Corpo do pedido	16 KB
Itens por página	100

Passou do limite: status 429 com muitas_tentativas e o cabeçalho Retry-After em segundos. Espere esse tempo e repita.

Paginação

As listas trazem até limite itens (padrão 50, máximo 100), mais novos primeiro. Se houver mais, proximo traz um cursor: mande ele em cursor para pegar a página seguinte. Quando proximo vem null, acabou. Venda nova que chega no meio não faz a lista pular nem repetir.

Node.js

let cursor = null;
do {
  const url = new URL("https://www.crownbot.com.br/api/v1/vendas");
  url.searchParams.set("situacao", "pago");
  if (cursor) url.searchParams.set("cursor", cursor);
  const pagina = await (await fetch(url, { headers: { Authorization: `Bearer ${CHAVE}` } })).json();
  for (const venda of pagina.dados) console.log(venda.ref, venda.valor_centavos);
  cursor = pagina.proximo;
} while (cursor);

Idempotência

Nos POST (gerar Pix, criar produto ou cupom, mandar mensagem), mande o cabeçalho Idempotency-Key com um valor único da operação, como o id do pedido no seu sistema. Se a rede cair e você repetir o pedido com a mesma chave, o Crownbot devolve a primeira resposta em vez de fazer tudo de novo.

Idempotency-Key: pedido-1234

Vale por 24 horas, por conta. De 1 a 100 caracteres visíveis, sem espaço.
Mesma chave e mesmo corpo: volta a resposta guardada, com o cabeçalho Idempotent-Replayed: true.
Mesma chave com outro corpo: 422 idempotencia_conflito. Chave nova para cada operação.
Primeiro pedido ainda rodando: 409 idempotencia_em_andamento. Espere um instante e repita.
Só resposta de sucesso fica guardada: depois de um erro, a mesma chave tenta de verdade outra vez.

Conta

Confere se a chave funciona e o que ela pode fazer. É a primeira chamada de qualquer integração.

Testar a chave

GET/api/v1/conta

Responde 200 com a chave certa. pix_ativo diz se a conta já gera Pix (carteira do Crownbot ativa em Gateways).

Pedido

curl "https://www.crownbot.com.br/api/v1/conta" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "ok": true,
  "chave": {
    "nome": "Meu sistema",
    "permissao": "total"
  },
  "conta": {
    "pix_ativo": true
  }
}

Erros próprios:chave_ausentechave_invalidamuitas_tentativas

Vendas

Todas as vendas da conta num lugar só, de qualquer origem: checkout do bio link, Pix avulso do painel, Pix pela API, Pix do bot do Telegram e doações. Cada venda traz o que a origem dela sabe (os itens do pedido, a conversa do bot, a mensagem da doação).

Campos

`id`	uuid	Id da venda no Crownbot.
`ref`	texto	Referência do Pix no gateway (cb_...). É a mesma do Pix avulso e dos avisos.
`origem`	texto	checkout, cobranca (Pix avulso do painel), api, bot, doacao ou outro.
`situacao`	texto	pendente, pago, expirado, cancelado, falhou ou estornado. Pix vencido sem pagamento já aparece expirado.
`valor_centavos`	inteiro	Valor cobrado, em centavos (1990 = R$ 19,90).
`valor_pago_centavos`	inteiro ou null	O que o gateway confirmou que entrou. Só depois de pago.
`descricao`	texto	Nome do produto ou descrição do Pix, como ficou na hora da venda.
`gateway`	texto	Gateway que processou o Pix (crownbot é a carteira do Crownbot).
`cliente`	objeto	nome, email (checkout) e telegram (bot). O que a origem não sabe vem null.
`referencia`	texto ou null	O texto que a sua integração mandou ao criar o Pix pela API.
`criado_em, expira_em, pago_em, estornado_em, atualizado_em`	data	Datas em ISO 8601, no fuso UTC.
`pedido`	objeto ou null	Só no checkout: id, itens, cupom, desconto_centavos, link_acesso (depois de pago) e bio_link.
`bot`	objeto ou null	Só no bot: id e username do bot e o chat_id de quem comprou.
`doacao`	objeto ou null	Só na doação: a mensagem de quem doou.

Listar vendas

GET/api/v1/vendas

Mais novas primeiro. Para manter um sistema em dia, peça de tempos em tempos com atualizado_desde igual à hora da última sincronização.

Filtros (query string)

`situacao`	texto	pendente, pago, expirado, cancelado, falhou ou estornado.
`origem`	texto	checkout, cobranca, api, bot, doacao ou outro.
`desde`	data	Vendas geradas a partir desta data.
`ate`	data	Vendas geradas antes desta data. Só a data (AAAA-MM-DD) inclui o dia inteiro.
`atualizado_desde`	data	Só as vendas que mudaram desde esta data (pagas, estornadas, expiradas).
`email`	texto	E-mail do comprador no checkout. Maiúsculas não importam.
`referencia`	texto	A referencia de um Pix criado pela API.
`limite`	inteiro	Itens por página, de 1 a 100. Padrão: 50.
`cursor`	texto	O valor de "proximo" da página anterior. Sem ele, vem a primeira página.

Pedido

curl "https://www.crownbot.com.br/api/v1/vendas" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "dados": [
    {
      "id": "6b1f0c2e-7a3d-4b8e-a5c9-2d4f6e8a0b13",
      "ref": "cb_91c3e5a7-2b4d-4f6e-8a0c-1e3f5a7b9c2d",
      "origem": "checkout",
      "situacao": "pago",
      "valor_centavos": 2990,
      "valor_pago_centavos": 2990,
      "descricao": "Curso completo + 1 item",
      "gateway": "crownbot",
      "cliente": {
        "nome": null,
        "email": "maria@exemplo.com",
        "telegram": null
      },
      "referencia": null,
      "criado_em": "2026-09-24T14:58:10.000Z",
      "expira_em": "2026-09-24T15:28:10.000Z",
      "pago_em": "2026-09-24T15:01:42.000Z",
      "estornado_em": null,
      "atualizado_em": "2026-09-24T15:01:43.000Z",
      "pedido": {
        "id": "8e2d4c1a-5b7f-4e3a-9c10-2f6b8d4e1a73",
        "itens": [
          {
            "produto_id": "3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4",
            "nome": "Curso completo",
            "valor_centavos": 2490
          },
          {
            "produto_id": "c41e8b72-6d3a-4f09-8e15-7a2b9c0d5e68",
            "nome": "Planilhas bônus",
            "valor_centavos": 500
          }
        ],
        "cupom": null,
        "desconto_centavos": 0,
        "link_acesso": "https://www.crownbot.com.br/pedido/8e2d4c1a-5b7f-4e3a-9c10-2f6b8d4e1a73/Xk29aQ...",
        "bio_link": "mariafit"
      },
      "bot": null,
      "doacao": null
    },
    {
      "id": "0d8f6b4a-2c1e-4a9b-8d7f-5e3c1a9b7d20",
      "ref": "cb_7e5c3a1f-9d8b-4c6a-b4e2-0f8d6c4a2e19",
      "origem": "bot",
      "situacao": "pago",
      "valor_centavos": 1990,
      "valor_pago_centavos": 1990,
      "descricao": "Cobrança Pix · Plano 30 dias",
      "gateway": "crownbot",
      "cliente": {
        "nome": "Ana",
        "email": null,
        "telegram": "@ana_exemplo"
      },
      "referencia": null,
      "criado_em": "2026-09-24T14:58:10.000Z",
      "expira_em": "2026-09-24T15:28:10.000Z",
      "pago_em": "2026-09-24T15:01:42.000Z",
      "estornado_em": null,
      "atualizado_em": "2026-09-24T15:01:43.000Z",
      "pedido": null,
      "bot": {
        "id": "5f0d2b8e-1c4a-4e7b-9d36-a8e2c7b1f940",
        "username": "@MinhaLojaBot",
        "chat_id": 7952019701
      },
      "doacao": null
    }
  ],
  "proximo": "WyIyMDI2LTA5LTI0IDE0OjU4OjEwLjEyMyswMCIsIjZiMWYwYzJlIl0"
}

Erros próprios:parametro_invalido

Consultar uma venda

GET/api/v1/vendas/{id}

Aceita o id da venda, o id do pedido do checkout ou a ref do Pix. Venda de outra conta responde 404, igual a uma que não existe.

No caminho

idobrigatório texto Id da venda, id do pedido ou ref do Pix.

Pedido

curl "https://www.crownbot.com.br/api/v1/vendas/6b1f0c2e-7a3d-4b8e-a5c9-2d4f6e8a0b13" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "venda": {
    "id": "6b1f0c2e-7a3d-4b8e-a5c9-2d4f6e8a0b13",
    "ref": "cb_91c3e5a7-2b4d-4f6e-8a0c-1e3f5a7b9c2d",
    "origem": "checkout",
    "situacao": "pago",
    "valor_centavos": 2990,
    "valor_pago_centavos": 2990,
    "descricao": "Curso completo + 1 item",
    "gateway": "crownbot",
    "cliente": {
      "nome": null,
      "email": "maria@exemplo.com",
      "telegram": null
    },
    "referencia": null,
    "criado_em": "2026-09-24T14:58:10.000Z",
    "expira_em": "2026-09-24T15:28:10.000Z",
    "pago_em": "2026-09-24T15:01:42.000Z",
    "estornado_em": null,
    "atualizado_em": "2026-09-24T15:01:43.000Z",
    "pedido": {
      "id": "8e2d4c1a-5b7f-4e3a-9c10-2f6b8d4e1a73",
      "itens": [
        {
          "produto_id": "3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4",
          "nome": "Curso completo",
          "valor_centavos": 2490
        },
        {
          "produto_id": "c41e8b72-6d3a-4f09-8e15-7a2b9c0d5e68",
          "nome": "Planilhas bônus",
          "valor_centavos": 500
        }
      ],
      "cupom": null,
      "desconto_centavos": 0,
      "link_acesso": "https://www.crownbot.com.br/pedido/8e2d4c1a-5b7f-4e3a-9c10-2f6b8d4e1a73/Xk29aQ...",
      "bio_link": "mariafit"
    },
    "bot": null,
    "doacao": null
  }
}

Erros próprios:nao_encontrado

Pix

Pix avulso pela carteira do Crownbot: o mesmo das Cobranças do painel, com a mesma tarifa das vendas, e o dinheiro cai na sua subconta. Serve para cobrar de dentro do seu site, bot ou sistema. Precisa da carteira do Crownbot ativa em Painel > Gateways.

Campos

`ref`	texto	Referência do Pix. Use para consultar e para casar com os avisos.
`situacao`	texto	pendente, pago, expirado, cancelado, falhou ou estornado.
`valor_centavos`	inteiro	Valor do Pix em centavos.
`copia_e_cola`	texto	O código Pix copia e cola.
`qr_code`	texto	Imagem PNG do QR em data URI. Só na criação: depois, gere o QR a partir do copia_e_cola.
`descricao`	texto ou null	Aparece no app do banco de quem paga.
`cliente`	texto ou null	Para quem é o Pix. Fica só no Crownbot.
`referencia`	texto ou null	Texto livre da sua integração (o id do pedido, o chat). Não vai para o gateway.
`criado_em, expira_em, pago_em`	data	Datas em ISO 8601, no fuso UTC.

Gerar um Pix

POST/api/v1/pix

Gera o Pix na hora e devolve o copia e cola e o QR. Mande Idempotency-Key: se a rede cair e você repetir o pedido, recebe o mesmo Pix em vez de um segundo.

Chave com permissão totalAceita Idempotency-Key

Corpo (JSON)

`valor_centavos`obrigatório	inteiro	De 200 (R$ 2,00) a 10000000 (R$ 100.000,00).
`descricao`	texto	Até 60 caracteres. Aparece no app do banco. Sem ela, vai "Cobrança Pix".
`cliente`	texto	Até 60 caracteres. Fica só no Crownbot.
`referencia`	texto	Até 200 caracteres. Devolvida na consulta, na lista de vendas e nos avisos.
`validade_minutos`	inteiro	15, 30 (padrão), 60, 180, 720 ou 1440.

Pedido

curl -X POST "https://www.crownbot.com.br/api/v1/pix" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{"valor_centavos":1990,"descricao":"VIP mensal","cliente":"Maria","referencia":"pedido_1234","validade_minutos":30}'

Resposta 201

{
  "pix": {
    "ref": "cb_3f9a2c7e-8d1b-4c1e-9a55-0b6d2f1e7a10",
    "situacao": "pendente",
    "valor_centavos": 1990,
    "copia_e_cola": "00020101021226890014br.gov.bcb.pix2567pix.exemplo.com/qr/v2/cobv/3f9a2c7e5204000053039865406019.905802BR6304A1B2",
    "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "descricao": "VIP mensal",
    "cliente": "Maria",
    "referencia": "pedido_1234",
    "criado_em": "2026-09-24T15:04:05.000Z",
    "expira_em": "2026-09-24T15:34:05.000Z",
    "pago_em": null
  }
}

Erros próprios:valor_invalidovalidade_invalidacarteira_inativamuitas_tentativasgateway_indisponivel

Listar Pix

GET/api/v1/pix

Pix avulsos da conta (painel, API e bot), mais novos primeiro. A lista não pergunta ao gateway: para acompanhar um Pix aberto, consulte ele sozinho.

Filtros (query string)

`situacao`	texto	pendente, pago, expirado, cancelado, falhou ou estornado.
`referencia`	texto	Só os Pix com esta referencia.
`desde`	data	Criados a partir desta data.
`ate`	data	Criados antes desta data. Só a data inclui o dia inteiro.
`limite`	inteiro	Itens por página, de 1 a 100. Padrão: 50.
`cursor`	texto	O valor de "proximo" da página anterior. Sem ele, vem a primeira página.

Pedido

curl "https://www.crownbot.com.br/api/v1/pix" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "dados": [
    {
      "ref": "cb_3f9a2c7e-8d1b-4c1e-9a55-0b6d2f1e7a10",
      "situacao": "pendente",
      "valor_centavos": 1990,
      "copia_e_cola": "00020101021226890014br.gov.bcb.pix2567pix.exemplo.com/qr/v2/cobv/3f9a2c7e5204000053039865406019.905802BR6304A1B2",
      "descricao": "VIP mensal",
      "cliente": "Maria",
      "referencia": "pedido_1234",
      "criado_em": "2026-09-24T15:04:05.000Z",
      "expira_em": "2026-09-24T15:34:05.000Z",
      "pago_em": null
    }
  ],
  "proximo": null
}

Erros próprios:parametro_invalido

Consultar um Pix

GET/api/v1/pix/{ref}

Enquanto o Pix está aberto, a consulta confere no gateway no máximo a cada 10 segundos, então dá para perguntar em intervalos curtos. Melhor ainda: receba o aviso venda.paga e não pergunte.

No caminho

refobrigatório texto A ref devolvida na criação.

Pedido

curl "https://www.crownbot.com.br/api/v1/pix/cb_3f9a2c7e-8d1b-4c1e-9a55-0b6d2f1e7a10" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "pix": {
    "ref": "cb_3f9a2c7e-8d1b-4c1e-9a55-0b6d2f1e7a10",
    "situacao": "pago",
    "valor_centavos": 1990,
    "copia_e_cola": "00020101021226890014br.gov.bcb.pix2567pix.exemplo.com/qr/v2/cobv/3f9a2c7e5204000053039865406019.905802BR6304A1B2",
    "descricao": "VIP mensal",
    "cliente": "Maria",
    "referencia": "pedido_1234",
    "criado_em": "2026-09-24T15:04:05.000Z",
    "expira_em": "2026-09-24T15:34:05.000Z",
    "pago_em": "2026-09-24T15:06:12.000Z"
  }
}

Erros próprios:nao_encontrado

Produtos

Os produtos do checkout: preço, o que cada um entrega (mensagem, links e arquivos) e em quais bio links aparece. Imagem e arquivos de entrega se enviam pelo painel; a API lê e altera o resto.

Campos

`preco_centavos`	inteiro	Preço em centavos, de 200 a 10000000.
`ativo`	booleano	false pausa a venda sem tirar dos bio links.
`arquivado`	booleano	Produto com pedido que foi removido: some dos bio links e quem comprou continua recebendo.
`mensagem_entrega`	texto	O que o comprador lê depois de pagar. Até 2000 caracteres.
`links_entrega`	lista	Até 10 links { titulo, url }, só https.
`bio_links`	lista	Bio links em que o produto aparece, com o endereço de cada um.
`oferta_extra`	objeto ou null	Order bump: outro produto seu (produto_id) por um preço especial (preco_centavos).

Listar produtos

GET/api/v1/produtos

Todos os produtos (à venda, pausados e arquivados) na ordem do painel. Vem tudo numa página: a conta tem no máximo 100 à venda.

Pedido

curl "https://www.crownbot.com.br/api/v1/produtos" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "dados": [
    {
      "id": "3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4",
      "nome": "Curso completo",
      "descricao": "12 aulas em vídeo e material de apoio.",
      "preco_centavos": 2490,
      "ativo": true,
      "arquivado": false,
      "imagem": "https://arquivos.crownbot.com.br/produtos/3a9c7e21/capa.webp",
      "imagem_borrada": false,
      "mensagem_entrega": "Obrigado pela compra! O acesso está nos links abaixo.",
      "links_entrega": [
        {
          "titulo": "Área de membros",
          "url": "https://membros.exemplo.com/curso"
        }
      ],
      "arquivos": [
        {
          "id": "f2a4c6e8-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
          "nome": "apostila.pdf",
          "tamanho_bytes": 2483120,
          "tipo": "application/pdf"
        }
      ],
      "bio_links": [
        {
          "id": "a7c9e1b3-5d2f-4a8c-b0e6-3f1d5b7a9c24",
          "url": "https://www.crownbot.com.br/mariafit"
        }
      ],
      "oferta_extra": {
        "produto_id": "c41e8b72-6d3a-4f09-8e15-7a2b9c0d5e68",
        "preco_centavos": 500
      },
      "criado_em": "2026-09-01T12:00:00.000Z",
      "atualizado_em": "2026-09-20T18:30:00.000Z"
    }
  ],
  "proximo": null
}

Consultar um produto

GET/api/v1/produtos/{id}

Um produto da conta pelo id.

No caminho

idobrigatório uuid Id do produto.

Pedido

curl "https://www.crownbot.com.br/api/v1/produtos/3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "produto": {
    "id": "3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4",
    "nome": "Curso completo",
    "descricao": "12 aulas em vídeo e material de apoio.",
    "preco_centavos": 2490,
    "ativo": true,
    "arquivado": false,
    "imagem": "https://arquivos.crownbot.com.br/produtos/3a9c7e21/capa.webp",
    "imagem_borrada": false,
    "mensagem_entrega": "Obrigado pela compra! O acesso está nos links abaixo.",
    "links_entrega": [
      {
        "titulo": "Área de membros",
        "url": "https://membros.exemplo.com/curso"
      }
    ],
    "arquivos": [
      {
        "id": "f2a4c6e8-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
        "nome": "apostila.pdf",
        "tamanho_bytes": 2483120,
        "tipo": "application/pdf"
      }
    ],
    "bio_links": [
      {
        "id": "a7c9e1b3-5d2f-4a8c-b0e6-3f1d5b7a9c24",
        "url": "https://www.crownbot.com.br/mariafit"
      }
    ],
    "oferta_extra": {
      "produto_id": "c41e8b72-6d3a-4f09-8e15-7a2b9c0d5e68",
      "preco_centavos": 500
    },
    "criado_em": "2026-09-01T12:00:00.000Z",
    "atualizado_em": "2026-09-20T18:30:00.000Z"
  }
}

Erros próprios:nao_encontrado

Criar um produto

POST/api/v1/produtos

nome e preco_centavos são obrigatórios; o resto é opcional. Se algum campo for recusado, nada fica criado.

Chave com permissão totalAceita Idempotency-Key

Corpo (JSON)

`nome`obrigatório	texto	Até 80 caracteres, uma linha.
`preco_centavos`obrigatório	inteiro	De 200 a 10000000.
`descricao`	texto	Até 500 caracteres.
`ativo`	booleano	Padrão: true.
`mensagem_entrega`	texto	Até 2000 caracteres.
`links_entrega`	lista	Até 10 { titulo, url }. url só https.
`bio_links`	lista de uuid	Ids dos seus bio links em que o produto aparece.
`oferta_extra`	objeto ou null	{ produto_id, preco_centavos }: outro produto seu, de 50 centavos até o preço cheio dele.
`imagem_borrada`	booleano	Mostra a imagem borrada no bio link.

Pedido

curl -X POST "https://www.crownbot.com.br/api/v1/produtos" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{"nome":"Curso completo","preco_centavos":2490,"descricao":"12 aulas em vídeo e material de apoio.","mensagem_entrega":"Obrigado pela compra! O acesso está nos links abaixo.","links_entrega":[{"titulo":"Área de membros","url":"https://membros.exemplo.com/curso"}]}'

Resposta 201

{
  "produto": {
    "id": "3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4",
    "nome": "Curso completo",
    "descricao": "12 aulas em vídeo e material de apoio.",
    "preco_centavos": 2490,
    "ativo": true,
    "arquivado": false,
    "imagem": null,
    "imagem_borrada": false,
    "mensagem_entrega": "Obrigado pela compra! O acesso está nos links abaixo.",
    "links_entrega": [
      {
        "titulo": "Área de membros",
        "url": "https://membros.exemplo.com/curso"
      }
    ],
    "arquivos": [],
    "bio_links": [],
    "oferta_extra": null,
    "criado_em": "2026-09-01T12:00:00.000Z",
    "atualizado_em": "2026-09-20T18:30:00.000Z"
  }
}

Erros próprios:nome_invalidopreco_invalidodescricao_longamensagem_longalink_invalidolinks_demaisbio_link_invalidooferta_invalidalimite

Editar um produto

PATCH/api/v1/produtos/{id}

Mande só os campos que mudam (os mesmos da criação). { "arquivado": false } tira do arquivo: o produto volta pausado e sem bio links, para você revisar.

Chave com permissão total

No caminho

idobrigatório uuid Id do produto.

Pedido

curl -X PATCH "https://www.crownbot.com.br/api/v1/produtos/3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"preco_centavos":1990,"ativo":true}'

Resposta 200

{
  "produto": {
    "id": "3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4",
    "nome": "Curso completo",
    "descricao": "12 aulas em vídeo e material de apoio.",
    "preco_centavos": 1990,
    "ativo": true,
    "arquivado": false,
    "imagem": "https://arquivos.crownbot.com.br/produtos/3a9c7e21/capa.webp",
    "imagem_borrada": false,
    "mensagem_entrega": "Obrigado pela compra! O acesso está nos links abaixo.",
    "links_entrega": [
      {
        "titulo": "Área de membros",
        "url": "https://membros.exemplo.com/curso"
      }
    ],
    "arquivos": [
      {
        "id": "f2a4c6e8-1b3d-4f5a-9c7e-0d2b4f6a8c1e",
        "nome": "apostila.pdf",
        "tamanho_bytes": 2483120,
        "tipo": "application/pdf"
      }
    ],
    "bio_links": [
      {
        "id": "a7c9e1b3-5d2f-4a8c-b0e6-3f1d5b7a9c24",
        "url": "https://www.crownbot.com.br/mariafit"
      }
    ],
    "oferta_extra": {
      "produto_id": "c41e8b72-6d3a-4f09-8e15-7a2b9c0d5e68",
      "preco_centavos": 500
    },
    "criado_em": "2026-09-01T12:00:00.000Z",
    "atualizado_em": "2026-09-20T18:30:00.000Z"
  }
}

Erros próprios:nao_encontradonome_invalidopreco_invalidolink_invalidooferta_invalidaarquivadodados_invalidos

Remover um produto

DELETE/api/v1/produtos/{id}

Produto com pedido é arquivado (sai dos bio links e quem comprou continua recebendo). Sem nenhum pedido, é excluído de vez, com os arquivos.

Chave com permissão total

No caminho

idobrigatório uuid Id do produto.

Pedido

curl -X DELETE "https://www.crownbot.com.br/api/v1/produtos/3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "resultado": "arquivado"
}

Erros próprios:nao_encontrado

Cupons

Cupons de desconto do checkout. Um cupom vale para os produtos escolhidos e nunca deixa o total abaixo de R$ 2,00.

Campos

`codigo`	texto	O que o comprador digita. Guardado em maiúsculas.
`tipo`	texto	valor (desconto fixo em centavos) ou percentual.
`valor`	inteiro	Centavos no tipo valor; de 1 a 99 no percentual.
`validade`	data ou null	Até quando vale. null: sem prazo.
`max_usos, usos`	inteiro	Limite de usos (null: sem limite) e quantos já foram usados.
`produtos`	lista de uuid	Produtos em que o cupom vale.

Listar cupons

GET/api/v1/cupons

Todos os cupons da conta, mais novos primeiro, numa página só (a conta tem no máximo 100).

Pedido

curl "https://www.crownbot.com.br/api/v1/cupons" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "dados": [
    {
      "id": "e9b1d3f5-7a2c-4e6b-8d0f-4c6e8a0b2d57",
      "codigo": "BEMVINDO",
      "tipo": "percentual",
      "valor": 10,
      "ativo": true,
      "validade": "2027-01-01T02:59:00.000Z",
      "max_usos": 100,
      "usos": 12,
      "produtos": [
        "3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4"
      ]
    }
  ],
  "proximo": null
}

Consultar um cupom

GET/api/v1/cupons/{id}

Um cupom da conta pelo id.

No caminho

idobrigatório uuid Id do cupom.

Pedido

curl "https://www.crownbot.com.br/api/v1/cupons/e9b1d3f5-7a2c-4e6b-8d0f-4c6e8a0b2d57" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "cupom": {
    "id": "e9b1d3f5-7a2c-4e6b-8d0f-4c6e8a0b2d57",
    "codigo": "BEMVINDO",
    "tipo": "percentual",
    "valor": 10,
    "ativo": true,
    "validade": "2027-01-01T02:59:00.000Z",
    "max_usos": 100,
    "usos": 12,
    "produtos": [
      "3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4"
    ]
  }
}

Erros próprios:nao_encontrado

Criar um cupom

POST/api/v1/cupons

Bom para gerar um cupom por cliente a partir do seu sistema (recuperação de carrinho, indicação).

Chave com permissão totalAceita Idempotency-Key

Corpo (JSON)

`codigo`obrigatório	texto	De 3 a 32 letras, números, hífen ou sublinhado.
`tipo`obrigatório	texto	valor ou percentual.
`valor`obrigatório	inteiro	Centavos (até 10000000) ou percentual de 1 a 99.
`produtos`obrigatório	lista de uuid	De 1 a 100 produtos seus, não arquivados.
`ativo`	booleano	Padrão: true.
`validade`	data	Data e hora futuras com fuso, ex.: 2026-12-31T23:59:00-03:00. Padrão: sem prazo.
`max_usos`	inteiro	De 1 a 1000000. Padrão: sem limite.

Pedido

curl -X POST "https://www.crownbot.com.br/api/v1/cupons" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{"codigo":"BEMVINDO","tipo":"percentual","valor":10,"produtos":["3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4"],"validade":"2026-12-31T23:59:00-03:00","max_usos":100}'

Resposta 201

{
  "cupom": {
    "id": "e9b1d3f5-7a2c-4e6b-8d0f-4c6e8a0b2d57",
    "codigo": "BEMVINDO",
    "tipo": "percentual",
    "valor": 10,
    "ativo": true,
    "validade": "2027-01-01T02:59:00.000Z",
    "max_usos": 100,
    "usos": 0,
    "produtos": [
      "3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4"
    ]
  }
}

Erros próprios:codigo_invalidocodigo_em_usodesconto_invalidovalidade_invalidalimite_invalidoprodutos_invalidoscupons_limite

Editar ou pausar um cupom

PATCH/api/v1/cupons/{id}

Mande só o que muda. Só { "ativo": false } pausa sem conferir o resto (vale até para cupom vencido).

Chave com permissão total

No caminho

idobrigatório uuid Id do cupom.

Pedido

curl -X PATCH "https://www.crownbot.com.br/api/v1/cupons/e9b1d3f5-7a2c-4e6b-8d0f-4c6e8a0b2d57" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"ativo":false}'

Resposta 200

{
  "cupom": {
    "id": "e9b1d3f5-7a2c-4e6b-8d0f-4c6e8a0b2d57",
    "codigo": "BEMVINDO",
    "tipo": "percentual",
    "valor": 10,
    "ativo": false,
    "validade": "2027-01-01T02:59:00.000Z",
    "max_usos": 100,
    "usos": 12,
    "produtos": [
      "3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4"
    ]
  }
}

Erros próprios:nao_encontradocodigo_em_usodesconto_invalidovalidade_invalidalimite_invalidoprodutos_invalidos

Carteira

Saldo e extrato da carteira do Crownbot. Só leitura: saque se pede pelo painel, com a sua chave Pix cadastrada.

Saldo e saques

GET/api/v1/carteira

O saldo é conferido no gateway na hora. saldo vem null se o gateway não responder.

Pedido

curl "https://www.crownbot.com.br/api/v1/carteira" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "carteira": {
    "gateway": "crownbot",
    "ativa": true,
    "saldo": {
      "disponivel_centavos": 184250,
      "bloqueado_centavos": 0,
      "recebido_liquido_centavos": 529870,
      "sacado_centavos": 345620
    },
    "chave_pix": {
      "tipo": "email",
      "final": "ma***@exemplo.com",
      "cadastrada_em": "2026-08-02T10:00:00.000Z"
    },
    "saque_minimo_centavos": 1000,
    "taxa_saque_centavos": 300,
    "saques": [
      {
        "id": "4c2e0a8f-6b4d-4f2a-9e8c-7a5b3d1f9e06",
        "valor_centavos": 50000,
        "taxa_centavos": 300,
        "situacao": "concluido",
        "chave_pix": "ma***@exemplo.com",
        "motivo_falha": null,
        "criado_em": "2026-09-20T13:00:00.000Z"
      }
    ]
  }
}

Erros próprios:sem_carteira

Extrato

GET/api/v1/carteira/extrato

Cada venda, estorno e saque com a tarifa do Crownbot, a taxa do gateway e o saldo linha a linha, mais novo primeiro. tipo: venda, estorno, saque ou saque_recusado.

Filtros (query string)

`desde`	data	Linhas a partir desta data.
`ate`	data	Linhas antes desta data. Só a data inclui o dia inteiro.
`limite`	inteiro	Itens por página, de 1 a 100. Padrão: 50.
`cursor`	texto	O valor de "proximo" da página anterior. Sem ele, vem a primeira página.

Pedido

curl "https://www.crownbot.com.br/api/v1/carteira/extrato" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "saldo_centavos": 184250,
  "dados": [
    {
      "em": "2026-09-24T15:01:42.000Z",
      "tipo": "venda",
      "descricao": "Curso completo + 1 item",
      "bruto_centavos": 2990,
      "tarifa_centavos": 45,
      "taxa_gateway_centavos": 75,
      "liquido_centavos": 2870,
      "saldo_centavos": 184250
    }
  ],
  "proximo": null
}

Erros próprios:sem_carteiraparametro_invalido

Bots do Telegram

Os bots conectados, quem já conversou com cada um e mensagens do bot a partir do seu sistema (avisar um cliente, mandar um acesso comprado fora do Crownbot).

Listar bots

GET/api/v1/bots

Os bots da conta com o fluxo que cada um roda.

Pedido

curl "https://www.crownbot.com.br/api/v1/bots" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "dados": [
    {
      "id": "5f0d2b8e-1c4a-4e7b-9d36-a8e2c7b1f940",
      "username": "@MinhaLojaBot",
      "nome": "Minha Loja",
      "link": "https://t.me/MinhaLojaBot",
      "fluxo": {
        "id": "b3d5f7a9-1c2e-4a6b-8d0f-2e4a6c8e0a13",
        "nome": "Funil principal"
      },
      "criado_em": "2026-09-01T12:00:00.000Z"
    }
  ],
  "proximo": null
}

Listar contatos

GET/api/v1/bots/{id}/contatos

Quem já conversou com o bot, mais novos primeiro. Conversas de grupo ficam fora. cliente: já pagou um Pix no bot. origem: o que veio no link /start (t.me/bot?start=insta).

No caminho

idobrigatório uuid Id do bot.

Filtros (query string)

`cliente`	texto	sim (só quem comprou) ou nao (só quem ainda não comprou).
`desde`	data	Contatos que chegaram a partir desta data.
`limite`	inteiro	Itens por página, de 1 a 100. Padrão: 50.
`cursor`	texto	O valor de "proximo" da página anterior. Sem ele, vem a primeira página.

Pedido

curl "https://www.crownbot.com.br/api/v1/bots/5f0d2b8e-1c4a-4e7b-9d36-a8e2c7b1f940/contatos" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE"

Resposta 200

{
  "dados": [
    {
      "chat_id": 7952019701,
      "nome": "Ana",
      "username": "@ana_exemplo",
      "origem": "insta",
      "cliente": true,
      "bloqueou": false,
      "criado_em": "2026-09-20T21:14:00.000Z",
      "atualizado_em": "2026-09-24T15:01:43.000Z"
    }
  ],
  "proximo": "WyIyMDI2LTA5LTI0IDE0OjU4OjEwLjEyMyswMCIsIjZiMWYwYzJlIl0"
}

Erros próprios:nao_encontradoparametro_invalido

Mandar mensagem

POST/api/v1/bots/{id}/mensagens

O bot escreve para quem já conversou com ele (o Telegram não deixa bot iniciar conversa). O texto aceita a formatação dos fluxos: *negrito*, _itálico_, ~riscado~ e ||spoiler||. Até 1000 mensagens por hora por bot.

Chave com permissão totalAceita Idempotency-Key

No caminho

idobrigatório uuid Id do bot.

Corpo (JSON)

`chat_id`obrigatório	inteiro	O chat_id do contato (vem na lista de contatos e nas vendas do bot).
`texto`obrigatório	texto	De 1 a 4096 caracteres.
`botoes`	lista	Até 8 botões de link { texto, url }, um por linha. texto até 40, url só https.

Pedido

curl -X POST "https://www.crownbot.com.br/api/v1/bots/5f0d2b8e-1c4a-4e7b-9d36-a8e2c7b1f940/mensagens" \
  -H "Authorization: Bearer $CROWNBOT_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234" \
  -d '{"chat_id":7952019701,"texto":"Oi, Ana! Seu acesso ao *Plano 30 dias* foi liberado.","botoes":[{"texto":"Entrar no grupo","url":"https://t.me/+AbCdEfGh123"}]}'

Resposta 201

{
  "enviada": true,
  "message_id": 4812
}

Erros próprios:nao_encontradocontato_nao_encontradotexto_invalidobotoes_invalidoscontato_bloqueoumuitas_tentativastelegram_recusou

Avisos de venda (webhooks)

Em vez de perguntar de tempos em tempos, receba um POST na hora em que algo acontece. Em Painel > Sistemas externos > Avisos de venda, cadastre a URL (só https://público) e marque os eventos. O segredo da assinatura aparece uma vez, ao ativar.

Evento	Quando
`venda.paga`	Qualquer venda aprovada: checkout, Pix avulso, API, bot ou doação.
`venda.gerada`	Alguém gerou o Pix e ainda não pagou. Bom para recuperar venda.
`venda.expirada`	Venceu sem pagamento. Pode chegar alguns minutos depois da hora.
`venda.cancelada`	O gateway cancelou ou recusou a cobrança.
`venda.estornada`	O dinheiro de uma venda paga voltou para quem pagou.
`pix.pago`	Só Pix avulso (Cobranças e API), com o corpo { pix }.

O que chega

Cabeçalhos

POST <sua URL>
Content-Type: application/json
User-Agent: Crownbot-Webhook/1
X-Crownbot-Evento: venda.paga
X-Crownbot-Entrega: d7f9b1c3-5e2a-4c8f-a6b0-9e1d3f5a7c24
X-Crownbot-Assinatura: sha256=<HMAC-SHA256 do corpo com o seu segredo, em hex>

Corpo

{
  "evento": "venda.paga",
  "id": "d7f9b1c3-5e2a-4c8f-a6b0-9e1d3f5a7c24",
  "criado_em": "2026-09-24T15:01:43.000Z",
  "venda": {
    "id": "6b1f0c2e-7a3d-4b8e-a5c9-2d4f6e8a0b13",
    "ref": "cb_91c3e5a7-2b4d-4f6e-8a0c-1e3f5a7b9c2d",
    "origem": "checkout",
    "situacao": "pago",
    "valor_centavos": 2990,
    "valor_pago_centavos": 2990,
    "descricao": "Curso completo + 1 item",
    "gateway": "crownbot",
    "cliente": {
      "nome": null,
      "email": "maria@exemplo.com",
      "telegram": null
    },
    "referencia": null,
    "criado_em": "2026-09-24T14:58:10.000Z",
    "expira_em": "2026-09-24T15:28:10.000Z",
    "pago_em": "2026-09-24T15:01:42.000Z",
    "estornado_em": null,
    "atualizado_em": "2026-09-24T15:01:43.000Z",
    "pedido": {
      "id": "8e2d4c1a-5b7f-4e3a-9c10-2f6b8d4e1a73",
      "itens": [
        {
          "produto_id": "3a9c7e21-0f4b-4d8e-b6a2-91c5d7e3f0b4",
          "nome": "Curso completo",
          "valor_centavos": 2490
        },
        {
          "produto_id": "c41e8b72-6d3a-4f09-8e15-7a2b9c0d5e68",
          "nome": "Planilhas bônus",
          "valor_centavos": 500
        }
      ],
      "cupom": null,
      "desconto_centavos": 0,
      "link_acesso": "https://www.crownbot.com.br/pedido/8e2d4c1a-5b7f-4e3a-9c10-2f6b8d4e1a73/Xk29aQ...",
      "bio_link": "mariafit"
    },
    "bot": null,
    "doacao": null
  }
}

venda vem no mesmo formato de Vendas, com o estado da hora do envio. O evento pix.pago é o formato antigo, só de Pix avulso, com o corpo { evento, id, criado_em, pix } no formato de Pix. Integração nova: use venda.paga.

Conferir a assinatura

Confira antes de liberar qualquer coisa: sem isso, quem descobrir a sua URL forja uma venda paga. A assinatura é sobre o corpo cru, byte a byte: leia antes de transformar em JSON.

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();
const SEGREDO = process.env.CROWNBOT_SEGREDO; // whsec_...

// O corpo precisa chegar cru: a assinatura é sobre os bytes exatos.
app.post("/crownbot", express.raw({ type: "application/json" }), (req, res) => {
  const esperado = "sha256=" + crypto.createHmac("sha256", SEGREDO).update(req.body).digest("hex");
  const recebido = req.get("X-Crownbot-Assinatura") ?? "";
  const ok = recebido.length === esperado.length &&
    crypto.timingSafeEqual(Buffer.from(recebido), Buffer.from(esperado));
  if (!ok) return res.status(401).end();

  const aviso = JSON.parse(req.body.toString("utf8"));
  if (aviso.evento === "venda.paga") {
    // Libere o acesso. Guarde aviso.id: se ele chegar de novo, ignore.
  }
  res.status(200).end();
});

Python (Flask)

import hashlib, hmac, os
from flask import Flask, request, abort

app = Flask(__name__)
SEGREDO = os.environ["CROWNBOT_SEGREDO"].encode()

@app.post("/crownbot")
def crownbot():
    esperado = "sha256=" + hmac.new(SEGREDO, request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(esperado, request.headers.get("X-Crownbot-Assinatura", "")):
        abort(401)
    aviso = request.get_json()
    if aviso["evento"] == "venda.paga":
        pass  # libere o acesso; ignore aviso["id"] repetido
    return "", 200

PHP

<?php
$segredo = getenv('CROWNBOT_SEGREDO');
$corpo = file_get_contents('php://input');
$esperado = 'sha256=' . hash_hmac('sha256', $corpo, $segredo);
if (!hash_equals($esperado, $_SERVER['HTTP_X_CROWNBOT_ASSINATURA'] ?? '')) {
    http_response_code(401);
    exit;
}
$aviso = json_decode($corpo, true);
if ($aviso['evento'] === 'venda.paga') {
    // libere o acesso; ignore $aviso['id'] repetido
}
http_response_code(200);

Entrega e novas tentativas

Qualquer resposta 2xx em até 5 segundos conta como entregue. O corpo da resposta não é lido e redirecionamento não é seguido.
Falhou: tenta de novo depois de 1 min, 5 min, 30 min, 2 h, 12 h (6 tentativas no total). Depois, fica como falhou e dá para reenviar pelo painel.
Um aviso por evento e venda. O reenvio usa o mesmo id (X-Crownbot-Entrega): guarde os ids já processados e ignore repetidos.
A ordem de chegada não é garantida. Use o campo evento e a situacao da venda, não a ordem.
Responda rápido e processe depois (uma fila, por exemplo). Trabalho lento dentro da resposta vira nova tentativa.
O botão Enviar teste do painel manda { "evento": "teste" } assinado, para conferir a sua URL.