Confido Docs

Autenticação

A chave de API no cabeçalho X-API-Key, os escopos, os IPs autorizados, as subcontas e os limites.

A chave de API

Toda chamada leva a chave no cabeçalho X-API-Key:

curl https://api.confidoscm.com/api/v1/charges -H "X-API-Key: ch_live_…"

As chaves são criadas no painel, em Configurações › Integrações › Chaves de API. A chave aparece uma vez só, na criação: a Confido guarda apenas um resumo dela (hash) e não consegue mostrá-la de novo. Perdeu? Revogue e crie outra.

Prefixo Ambiente Detalhes
ch_live_ Produção Dinheiro de verdade. Só sai para conta aprovada; se você usa 2FA, o painel pede o código.
ch_test_ Teste Criada dentro de um ambiente de teste (sandbox) do painel. Veja Ambientes.

Nunca coloque a chave no navegador, num aplicativo ou num repositório. Ela é do seu servidor.

Escopos

Cada chave só faz o que os escopos dela permitem. Sem o escopo, a chamada responde 403.

Escopo Libera
payments:create, payments:read Vendas (/payments) e cobranças (/charges). Vêm marcados por padrão.
payment_links:read, payment_links:write Links de pagamento (/payment-links).
webhooks:read, webhooks:write Endpoints de webhook (/webhook-endpoints).
accounts:read, accounts:write Subcontas (/accounts), o Connect.

IPs autorizados

A chave só funciona a partir dos IPs cadastrados nela. É obrigatório: uma chave sem IP responde "API key sem IP autorizado", e uma chamada de outro IP responde 403 "IP não autorizado para esta API key".

  • Cadastre o IP público de saída do seu servidor, um por linha (IPv4 ou IPv6).
  • Faixas (CIDR), curingas, nomes, IPs de rede privada (10.x, 192.168.x, 172.16–31.x), loopback e CGNAT não são aceitos: eles nunca são o endereço que chega à Confido.
  • O número máximo de IPs por conta é ajustado pela Confido. Precisa de mais? Fale com o suporte.

Se o seu servidor sai por vários IPs (nuvem com IP dinâmico), fixe a saída com um NAT de IP estático e cadastre esse IP.

Testar pelo navegador

O botão Testar da Referência da API manda a requisição do seu navegador. Para funcionar:

  1. Cadastre o IP público do seu computador na chave (procure "qual é o meu IP" num buscador). Sem isso, a resposta será 403 IP não autorizado, o que já prova que a chamada chegou à Confido.
  2. Cole a chave no campo de autenticação da página. Ela fica só na memória da aba: não é salva no navegador nem enviada a ninguém além de api.confidoscm.com.
  3. Cuidado com ch_live_: o Testar cria vendas e cobranças reais. Prefira uma chave de teste e as rotas que só leem. Depois de testar, tire o IP do computador da chave.

Agir por uma subconta (Connect)

Com o cabeçalho Confido-Account: acct_…, a chave da conta-mãe age em nome de uma subconta filha direta: a venda, a cobrança e o saldo passam a ser dela. A subconta precisa estar aprovada e ativa; neta, conta de outra árvore ou conta suspensa respondem 403. Veja Subcontas (Connect).

Limites de requisição

Quem chama Limite
Com chave válida 600 por minuto por conta (todas as chaves somadas). A Confido pode ajustar o da sua conta.
Sem chave, ou com chave recusada 100 por minuto por IP

Passou do limite, a resposta é 429. Espere alguns segundos (respeite o Retry-After quando vier) e tente de novo, sempre com a mesma chave de idempotência.

Revogar e trocar

Em Chaves de API, use Revogar: a chave deixa de valer na hora, em todos os serviços. Para trocar sem parar, crie a nova, ponha no servidor e só então revogue a antiga.