FAQ Técnico

Sim. A plataforma disponibiliza um ambiente de sandbox com endpoints equivalentes prefixados por /sandbox (por exemplo, /sandbox/api-docs para a especificação e endpoints correspondentes na API), que permite simular diferentes status de pagamento (pago, pendente, expirado, entre outros) sem gerar cobranças reais nem movimentar fundos de verdade. É o ambiente recomendado para validar toda a integração — geração de cobrança, consulta de status e recebimento de webhook — antes de apontar sua aplicação para produção.

A referência em /api-docs é gerada a partir de uma especificação OpenAPI 3.0 (Swagger), que descreve parâmetros, exemplos de requisição e resposta em formato HTTP/JSON, independente de linguagem. Não publicamos SDKs oficiais para linguagens específicas, mas como o arquivo YAML da especificação é um documento OpenAPI padrão, ele pode ser importado diretamente em ferramentas como Postman, Insomnia ou geradores de cliente (OpenAPI Generator) para produzir automaticamente um cliente na linguagem da sua escolha.

A maioria dos endpoints tem limite de 60 requisições por minuto por IP. Os endpoints de webhook (/webhooks/*) têm um limite maior, de 100 requisições por minuto, por receberem chamadas automatizadas do provedor de pagamento. Ao exceder o limite, a API responde com o código 429 e a mensagem "Too Many Attempts.". Recomendamos implementar espera com backoff progressivo em vez de tentar novamente imediatamente, e evitar polling agressivo de status — prefira usar webhooks para ser notificado dos eventos.

O canal principal de suporte técnico é o bot de atendimento no Telegram, acessível pela página de Suporte, que varia conforme o domínio/whitelabel utilizado. Para relatar um bug, inclua o endpoint chamado, o horário aproximado da requisição, o código de status HTTP recebido, o corpo da resposta (campo message) e, se disponível, o identificador da transação — isso acelera bastante o diagnóstico. Para assuntos comerciais ou parcerias, use a página de Contato.

Sim. A plataforma segue uma política de low-KYC: não são exigidos documentos adicionais no cadastro inicial, mas toda conta passa por uma revisão da equipe de compliance antes de poder movimentar valores. Enquanto a conta não for aprovada, chamadas à API que envolvam movimentação financeira real não devem ser usadas — utilize o ambiente de sandbox para testar sua integração nesse período.

A especificação OpenAPI publicada em /api-docs tem um número de versão global. Além disso, alguns endpoints mantêm versões paralelas durante uma transição — por exemplo, existe um endpoint de webhook em formato legado e uma versão v2 recomendada para novas integrações, mantidas simultaneamente por um período para não quebrar integrações existentes. Sempre que uma nova versão de endpoint for recomendada, ela é sinalizada como tal na descrição da referência Swagger.

Erros são retornados como um objeto JSON com pelo menos dois campos: success (booleano, false em caso de erro) e message (texto legível descrevendo o problema). O código de status HTTP (401, 403, 422, 429 ou 500) deve ser usado para decidir a lógica de tratamento no seu código; o campo message serve principalmente para logging e depuração humana. Detalhes completos estão na página de Erros e Códigos de Status.

A plataforma não consegue enviar notificações para endereços localhost ou endpoints que exigem autenticação prévia, já que precisa alcançar sua URL publicamente pela internet. Durante o desenvolvimento, use uma ferramenta de túnel (por exemplo, ngrok ou similar) para expor temporariamente seu servidor local com uma URL pública e HTTPS, e configure essa URL como response_url/callback. Use o ambiente de sandbox para dar o disparo dos eventos sem gerar cobranças reais, e só depois substitua pela URL definitiva de produção.

Falhas de rede podem levar a plataforma a reenviar a mesma notificação mais de uma vez. Seu endpoint deve ser idempotente: antes de executar uma ação (como liberar um produto ou atualizar um pedido), verifique se o identificador daquela transação já foi processado anteriormente e, em caso positivo, apenas responda com sucesso sem repetir a ação. O artigo sobre webhooks no blog detalha esse padrão com um checklist completo.

Praticamente todos os endpoints de negócio (geração de cobrança, consulta de status, saque) exigem o parâmetro code, que identifica sua conta e carteira. Os endpoints de webhook exigem o cabeçalho Authorization: Basic <TOKEN>. Não há endpoints públicos de escrita (criação de cobrança, saque) sem alguma forma de autenticação. Detalhes completos na página de Autenticação.

Sim, alguns endpoints de geração de cobrança aceitam um parâmetro opcional de carteira personalizada (endereço Liquid Network customizado), direcionando aquele pagamento específico para um endereço diferente do padrão configurado na conta. Como transações na Liquid Network são irreversíveis, valide esse endereço cuidadosamente antes de enviar a requisição — erros de digitação não podem ser corrigidos após a confirmação da transação.