Como criar credenciais de API e testar a integração

A API da Quibly Pay permite que o seu sistema gere cobranças PIX, consulte transações e peça saques. Este artigo mostra como criar as credenciais no painel. Os detalhes técnicos (rotas, exemplos de código, erros) estão na documentação de integração: https://app.quiblypay.com/docs (versão para IA em https://app.quiblypay.com/llms-full.txt).

O que a API faz hoje

• Gerar cobrança PIX (QR Code copia e cola).
• Consultar o status de uma transação.
• Pedir saque PIX para a conta do titular.
• Simular pagamentos no modo teste.

A API não cria cobranças de cartão. Para vender no cartão, use o checkout de produto ou o link de pagamento.

Antes de começar

• A conta precisa estar verificada.
• A verificação em duas etapas precisa estar ativa: criar, regenerar ou excluir credenciais pede o código do seu app autenticador.

Passo a passo

1. Vá em Desenvolvedor > Credenciais de API.
2. Para começar pelos testes, ligue o Modo teste (Sandbox) no rodapé do menu. As chaves de teste começam com qp_test_ e as de produção com qp_live_.
3. Clique em Nova credencial.
4. Preencha Nome (ex.: Loja virtual), Descrição e Domínio (opcional, só para você identificar).
5. Escolha as permissões: - Recebimentos (Pix In): gerar cobranças PIX. - Consulta: consultar transações. - Saques (Pix Out): pedir saques pela API. Só marque se a sua integração faz saques: essa chave poderá tirar dinheiro da conta.
6. Clique em Criar credencial e confirme com o código do app autenticador.
7. Na tela Credencial pronta, copie e guarde num lugar seguro o Client ID, o client secret e o secret de webhook. Os segredos aparecem só nesse momento.

Testar antes de ir para produção

1. Use a credencial qp_test_ e as rotas de sandbox descritas na documentação.
2. O PIX de teste não pode ser pago em banco. Simule o pagamento pela API ou pelo botão Marcar como pago na transação.
3. Confira se o seu sistema recebeu e validou o webhook.
4. Quando estiver tudo certo, desligue o modo teste, crie uma credencial de produção e troque para as rotas de produção.

Gerenciar credenciais

No card de cada credencial:

• Regenerar segredo: o segredo atual para de funcionar na hora (e o secret de webhook também é trocado). Atualize suas integrações.
• Gerar novo secret de webhook: só o secret dos webhooks muda. O client secret continua valendo.
• Excluir: as integrações que usam essa credencial param na hora. Não dá para desfazer.

Cuidados

• Nunca coloque o client secret em código de site, aplicativo ou URL. Use só no servidor.
• Se suspeitar de vazamento, regenere o segredo imediatamente.