Teste a API da Liquix sem risco, em minutos.

1. Visão geral

O Liquix Sandbox é um ambiente de teste da API de parceiros da Liquix (LiquixPay API). Ele roda inteiro no seu navegador: nenhum dado sai desta página, o dinheiro é fictício e o botão Reiniciar apaga tudo.

• 100% via API. Todos os serviços são usados por chamadas HTTP. Não há tela obrigatória.
• Referência completa. Todas as rotas, campos e exemplos estão na Documentação da API.
• Low KYC/KYB. Seus clientes finais entram por um vínculo com cadastro simplificado. Níveis de verificação e limites de cada um: definidos na contratação.
• Base de endereço (ilustrativa): https://sandbox.liquix.tech/parceiro/v1. Todas as rotas começam com /parceiro/v1.
• Produto simulado: dolar (Pix em reais vira USDC, o dólar digital, na carteira do cliente final).

O que é fiel à API real e o que é ilustrativo

2. Comece em 5 minutos

1. Clique em Gerar chave de teste (passo 1 do guia).
2. Cadastre um webhook (passo 3), cote (passo 4) e crie a operação (passo 5).
3. No passo 6, marque o Pix como pago e veja os eventos assinados chegarem.

Prefere o terminal? Estas quatro chamadas fazem o mesmo fora do sandbox (troque a base pela real quando tiver a sua chave):

export LIQUIX_API_KEY="lqxp_test_..."        # a chave que o sandbox gerou
BASE="https://sandbox.liquix.tech/parceiro/v1"

# 1) quem sou eu
curl -s "$BASE/eu" -H "Authorization: Bearer $LIQUIX_API_KEY"

# 2) cotar R$ 1.000,00 para um cliente vinculado
curl -s -X POST "$BASE/cotacoes" \
  -H "Authorization: Bearer $LIQUIX_API_KEY" -H "Content-Type: application/json" \
  -d '{"produto":"dolar","cliente_ref":"cliente-001","valor_brl":"1000.00"}'

# 3) criar a operacao com o cotacao_id devolvido (Idempotency-Key e obrigatoria)
curl -s -X POST "$BASE/operacoes" \
  -H "Authorization: Bearer $LIQUIX_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-0001-abc" \
  -d '{"cotacao_id":"<id da cotacao>"}'

# 4) acompanhar
curl -s "$BASE/operacoes/<id da operacao>" -H "Authorization: Bearer $LIQUIX_API_KEY"

Dica: clique duas vezes em qualquer bloco de código para copiá-lo.

3. Autenticação, chaves e escopos

Toda chamada leva Authorization: Bearer lqxp_…. Chave ausente, errada, expirada ou revogada devolve sempre o mesmo 401 (a API não diz qual dos casos), com WWW-Authenticate: Bearer.

• O parceiro vem sempre da chave, nunca do corpo nem do caminho. Recurso de outro parceiro responde 404, igual a um que não existe.
• Cada chave tem um teto por operação, um teto por dia (em dólares) e um limite por minuto. Veja tudo em GET /eu.
• Parceiro suspenso só lê: as escritas devolvem 403 parceiro_suspenso.
• Guarde a chave em variável de ambiente. Nunca no código, nunca no navegador do seu cliente.

4. Cotar e operar

Cotar não move dinheiro e não cria operação. Operar executa uma cotação, e só por cotacao_id: valor e destino nunca vêm no pedido.

• valor_brl é texto ("1000.00" ou "1000,00"). Mínimo de R$ 10,00 no sandbox.
• Todos os valores na resposta são inteiros em centavos: valor_brl_centavos (centavos de real), usdc_estimado_centavos (centavos de dólar), comissao_prevista_centavos (centavos de real).
• tarifa.all_in é o percentual total que o cliente final paga: tarifa da Liquix mais o markup da sua chave. markup_bps é o seu markup em pontos-base (50 = 0,50%).
• A comissão prevista é o valor vezes o markup. Ela só é paga quando a operação chega a concluida.
• A cotação tem validade curta (5 minutos no sandbox) e uso único.

Criar a operação devolve 201 e a operação em aguardando_pagamento, com o Pix copia e cola em pagamento. Repetir a mesma Idempotency-Key devolve 200 e a mesma operação.

5. Estados da operação e eventos

A operação tem versao: sobe a cada mudança e vira o seq do evento. O GET decide, o webhook só aponta: ao receber um evento, consulte GET /operacoes/{id} para saber o estado de verdade.

6. Idempotência

É o que torna seguro repetir uma chamada depois de um erro de rede.

• Cabeçalho Idempotency-Key: 8 a 128 caracteres entre letras, números e _ . : -.
• Obrigatório em POST /operacoes, POST /vinculos/…/revogar e nas escritas de webhooks. Opcional em POST /cotacoes.
• Mesma chave + mesmo corpo → a mesma resposta (em POST /operacoes, status 200).
• Mesma chave + corpo diferente → 422 idempotencia_pedido_diferente.
• Se der timeout ao criar uma operação, repita com a mesma chave: nunca nasce duas vezes.
• Respostas 5xx não ficam guardadas: repetir tenta de novo.

7. Webhooks e assinatura

Cadastre até 5 endpoints (ativos e pausados contam). A URL precisa ser https, porta 443, sem usuário e senha, em endereço público; senão: 422 url_proibida (a URL não volta na resposta). Para testar no seu computador, use um túnel https.

O segredo (whsec_…) aparece uma única vez, na criação. Quem perde remove e recria o endpoint.

Cabeçalhos e corpo

• webhook-id: msg_ + 32 hex. Igual em todas as tentativas do mesmo evento (use para não processar duas vezes).
• webhook-timestamp: segundos. Muda a cada tentativa.
• webhook-signature: v1,<base64>.
• Corpo (JSON compacto, nesta ordem): id, type, timestamp, seq, data.

Como verificar

Assinatura = base64( HMAC-SHA256( chave, "<webhook-id>.<webhook-timestamp>." + corpo ) ), com a chave sendo o segredo sem whsec_ decodificado de base64. Use os bytes exatos recebidos, não o JSON reserializado.

import base64, hashlib, hmac, time

def verificar(segredo: str, msg_id: str, timestamp: str, corpo: bytes, assinatura: str) -> bool:
    """Standard Webhooks v1. `corpo` sao os bytes EXATOS recebidos (antes de qualquer json.loads)."""
    if abs(time.time() - int(timestamp)) > 300:          # recusa mensagens com mais de 5 minutos
        return False
    chave = base64.b64decode(segredo.removeprefix("whsec_"))
    esperado = base64.b64encode(
        hmac.new(chave, f"{msg_id}.{timestamp}.".encode() + corpo, hashlib.sha256).digest()
    ).decode()
    # o cabecalho pode ter varias assinaturas separadas por espaco: "v1,xxx v1,yyy"
    return any(hmac.compare_digest(esperado, s[3:]) for s in assinatura.split() if s.startswith("v1,"))

import { createHmac, timingSafeEqual } from "node:crypto";

export function verificar(segredo: string, msgId: string, timestamp: string, corpo: Buffer, assinatura: string): boolean {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;        // 5 minutos
  const chave = Buffer.from(segredo.replace(/^whsec_/, ""), "base64");
  const esperado = createHmac("sha256", chave).update(`${msgId}.${timestamp}.`).update(corpo).digest();
  return assinatura.split(" ").filter((s) => s.startsWith("v1,")).some((s) => {
    const recebido = Buffer.from(s.slice(3), "base64");
    return recebido.length === esperado.length && timingSafeEqual(recebido, esperado);
  });
}

Tentativas e pausa

Responda 2xx rápido. Qualquer outra resposta ou timeout é falha, e a Liquix tenta de novo com esta espera antes de cada tentativa: 0, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 14 h, 20 h, 24 h (10 tentativas). Depois disso a entrega fica esgotada. Seguidas entregas esgotadas pausam o endpoint [no sandbox: 3 seguidas, valor ilustrativo]: os eventos novos esperam, não se perdem, e voltam em ordem com POST /webhooks/endpoints/{id}/retomar. Para reenviar um evento já entregue: POST /webhooks/eventos/{id}/reenviar (mesmo webhook-id).

8. Erros

Todo erro vem neste formato, e toda resposta traz X-Request-Id (guarde-o ao falar com o suporte):

{"error": {"code": "corpo_invalido", "message": "corpo da requisição inválido", "request_id": "9f2c…", "details": [{"field": "valor_brl", "code": "formato_invalido"}]}}

Os códigos são os da API real. O gatilho de cada um (valores, clientes de teste) é do sandbox. Clique em Provocar para gerar o erro de verdade e ver a resposta no console.

Regra de ouro: 4xx = corrija o pedido (não adianta repetir igual). 429 e 5xx = repita com a mesma Idempotency-Key, respeitando Retry-After.

9. Valores mágicos e controles do sandbox

Na API real o estado vem do pagamento do cliente. Aqui você faz esse papel, pelos botões da seção Operações. Os centavos do valor decidem o desfecho quando você marca o Pix como pago:

• Clientes de teste: cliente-001 e cliente-002 (ativos); cliente-sem-carteira (dá 409 cliente_sem_carteira); cliente-novo (carteira em espera de segurança: 409 carteira_em_resfriamento); cliente-revogado (dá 404 vinculo_nao_encontrado, igual a um cliente que não existe).
• Um Pix por vez: enquanto uma operação de um cliente está aguardando_pagamento, cotar ou operar para o mesmo cliente dá 409 operacao_em_andamento. Pague ou expire a operação (seção Operações) para liberar.
• Limites: mínimo R$ 10,00; acima de ~R$ 10.000 passa do teto da chave de teste.
• Preset "só leitura" mostra o 403 escopo_insuficiente. "Parceiro suspenso" mostra o 403 parceiro_suspenso.
• Rajada: o botão Provocar do erro muitas_requisicoes dispara 61 chamadas seguidas.
• Para desenvolvedores: abra o console do navegador (F12) e use LiquixSandbox.api("GET", "/eu", { headers: ... }).

10. Outros serviços (também via API)

Este sandbox simula o produto Dólar (Pix ↔ USDC). Os demais serviços da proposta comercial entram na mesma API, no mesmo modelo de chave, cotação, operação e webhook:

Condições: definidas na contratação. Peça o seu acesso pelos contatos da proposta.

11. Agentes de IA: x402 e MCP

x402 usa o código HTTP 402 Payment Required. O agente chama a API, recebe o preço da chamada, paga em USDC e repete a chamada já com o comprovante. Sem cartão, sem fatura, sem cadastro manual. Para que serve:

• Tesouraria automática: um agente cota e converte USDC em reais (e o contrário) dentro de um teto.
• Pagar contas e boletos sozinho, pedindo aprovação humana acima do teto.
• Cobrar por uso: a sua empresa cobra de outros agentes pelo seu serviço, chamada a chamada, sem contrato mensal.

MCP (Model Context Protocol) é o jeito padrão de dar ferramentas a um agente de IA. O kit para agentes da Liquix traz as ferramentas cotar, criar_operacao, obter_operacao e outras, com teto por chave aplicado no servidor: acima dele a chamada fica pending_approval e só executa com a aprovação de uma pessoa.

12. Perguntas frequentes

Posso usar uma chave real aqui? Não, e não precisa: a chave do sandbox é gerada na sua tela e nada sai do navegador.

Por que recebo 404 em vez de 403 quando o recurso é de outro parceiro? Para não revelar que o recurso existe. É a mesma resposta de "não existe".

Quanto vale a cotação? Pouco tempo (5 minutos no sandbox) e uso único. Venceu? Cote de novo.

Recebo operacao_em_andamento ao cotar de novo. Cada cliente final tem um Pix por vez. Conclua ou deixe expirar a operação anterior (botões da seção Operações no sandbox).

O que fazer com 429? Espere o tempo do cabeçalho Retry-After e repita com a mesma Idempotency-Key.

O webhook chegou duas vezes. Normal: a entrega é "pelo menos uma vez". Use o webhook-id para ignorar repetidos e consulte o GET antes de agir.

Como vou para produção? Peça o contrato e a chave pelos contatos da proposta. Prazo e passos: definidos na contratação.

13. Glossário