Autenticação

A API fica em https://api.aliquot.cc. Todo endpoint de vendedor está sob /api/v1/crypto e se autentica com uma API key. O gerenciamento de webhooks, sob /api/v1/organizations/{organizationId}/webhooks, também (veja Webhooks). Os endpoints voltados ao comprador sob /api/v1/public (checkout, páginas de payment link, resgates de reembolso) não exigem autenticação: o ID da fatura, o slug do link ou o token de resgate no path é a credencial.

Requisições e respostas são JSON, com nomes de campo em snake_case.

API keys

Crie keys no dashboard em Desenvolvedores → API keys. Dê um nome à key, escolha o ambiente (Sandbox ou Live, veja abaixo) e as permissões e, opcionalmente, uma data de expiração. O segredo é exibido uma única vez, quando a key é criada; o Aliquot guarda apenas um hash dele, então um segredo perdido não pode ser recuperado. Nesse caso, crie uma nova key e revogue a antiga.

Uma key pertence à sua organização e age apenas sobre os dados dela. Você não pode dar a uma key uma permissão que o seu próprio papel na organização não tem.

Revogue uma key na mesma página. Uma key revogada ou expirada é recusada imediatamente.

API keys e ambientes

Cada key fica vinculada a um ambiente, escolhido na criação. O prefixo indica qual:

No dashboard, o formulário da key pede o ambiente (Sandbox por padrão). Pela API, envie "environment": "sandbox" ou "environment": "live" para POST /api/v1/organizations/{organizationId}/api-keys; o padrão é sandbox, ou o ambiente da key que faz a requisição, quando ela é uma key do Sandbox ou do Live. Uma key não pode criar uma key do outro ambiente: isso responde 403 API_KEY_ENVIRONMENT_MISMATCH.

Toda requisição em /api/v1/crypto feita com a key fica no ambiente dela:

• Se você omitir o parâmetro de query mode, ele assume o ambiente da key: uma key do Sandbox lista as faturas do Sandbox sem ?mode=test.
• Uma fatura criada sem network nem mode é criada no ambiente da key.
• Um mode, uma network ou uma rede dos accepted_pairs de um payment link do outro ambiente responde 403 API_KEY_ENVIRONMENT_MISMATCH, e nada é criado.
• Uma fatura, um payment link ou um payout do outro ambiente, lido, anulado ou editado por ID, responde 404 NOT_FOUND, como se não existisse.

Os dados nunca cruzam ambientes: uma fatura do Sandbox nunca é listada no Live, e saldos do Sandbox não podem ter payout para uma mainnet.

Keys legadas. As keys criadas antes da existência dos ambientes começam com fk_live_ e não estão vinculadas a nenhum: funcionam nos dois, e cada requisição escolhe o seu ambiente como descrito em Sandbox e Live nas requisições (as listas têm live como padrão). O dashboard as mostra como "Legada · ambos os ambientes". Substitua-as por uma key do Sandbox ou do Live.

Envio da key

Envie o segredo como bearer token no header Authorization:

curl "https://api.aliquot.cc/api/v1/crypto/invoices?mode=test" \
  -H "Authorization: Bearer $ALIQUOT_API_KEY"

Sem key, a resposta é 401 UNAUTHORIZED. Uma key inválida, revogada ou expirada responde 401 UNAUTHORIZED com a mensagem Invalid or revoked API key. Uma key válida sem a permissão exigida por um endpoint responde 403 FORBIDDEN com Missing permission: <permission>.

As requisições feitas com API keys ficam registradas no log de requisições: Desenvolvedores → Registros no dashboard, ou GET /api/v1/crypto/requests. Cada entrada tem o método, o path, o status, a duração, a Idempotency-Key, se houver, e se a resposta foi um replay.

Permissões

O formulário de key no dashboard oferece todas as permissões desta tabela, agrupadas por recurso, cada uma com uma descrição de uma linha. crypto-invoices:create, crypto-invoices:read, crypto-links:create, crypto-links:read, crypto-accounts:read e crypto-ledger:read vêm pré-selecionadas; crypto-invoices:update, crypto-links:update, crypto-accounts:create, crypto-payouts:read, crypto-payouts:create e webhooks:manage você marca se precisar.

API keys que podem fazer payouts

Uma key com crypto-payouts:create tira dinheiro dos seus saldos sem um código por payout. Por isso, criá-la exige step-up: você precisa ter a autenticação de dois fatores ativada no seu usuário (Configurações → Segurança) e um código atual do seu app autenticador no momento em que cria a key: no dashboard, ao marcar crypto-payouts:create aparece um campo para ele; pela API, envie-o como totp_code. Sem 2FA, a requisição responde 422 TWO_FACTOR_NOT_ENABLED; sem um código válido, 403 STEP_UP_REQUIRED. Uma key que não foi criada dessa forma responde 403 STEP_UP_REQUIRED em POST /api/v1/crypto/payouts. Veja Payouts.

Só crypto-payouts:create torna uma key capaz de fazer payouts. As permissões são comparadas de forma exata, então crypto-payouts:manage não inclui crypto-payouts:create nem crypto-payouts:read e não dá acesso a nenhum endpoint de payouts.

Sandbox e Live nas requisições

O Sandbox (mode: "test" na API) e o Live são separados pela rede, não pelo endpoint:

• Ao criar uma fatura: a network que você envia decide o ambiente (BASE_SEPOLIA é Sandbox, BASE_MAINNET é Live). Se você deixar o comprador escolher a rede, a fatura assume o ambiente da sua key; com uma key legada, envie "mode": "test" ou "mode": "live". Uma rede e um mode que não coincidem resultam em 422 (com uma key do Sandbox ou do Live, o que não corresponde à key resulta em 403 antes).
• Os payment links recebem o ambiente dos seus accepted_pairs, e os payouts, da sua network.
• Ao ler: os endpoints de listagem aceitam um parâmetro de query mode, cujo padrão é o ambiente da sua key (live com uma key legada fk_live_). Com uma key legada, adicione mode=test para ver faturas, payouts, reembolsos, payment links, saldos e lançamentos do ledger do Sandbox.

Toda fatura, todo payout e todo payment link traz livemode: false no Sandbox, true no Live.

Idempotência

POST /api/v1/crypto/invoices e POST /api/v1/crypto/payouts exigem um header Idempotency-Key (1–255 caracteres). Use um valor que identifique a operação no seu sistema, como o ID de um pedido ou de um saque, e reutilize-o quando repetir a requisição.

As keys têm escopo na sua organização. Duas requisições contam como a mesma quando o método, o path e o corpo JSON coincidem; a ordem das chaves dentro do corpo não importa. Apenas respostas bem-sucedidas (2xx) são armazenadas: se a primeira requisição falhar, a key é liberada e você pode corrigir a requisição e enviá-la de novo com a mesma key.

Erros

Os erros compartilham um único formato:

{
  "code": "VALIDATION_FAILED",
  "message": "mode (test | live) is required when no network is given",
  "issues": [{ "path": "mode", "message": "mode (test | live) is required when no network is given" }]
}

code é estável e feito para o seu código; message é para pessoas. issues aparece em erros de validação e aponta para o campo (path usa pontos para aninhamento, como splits.0.percent).

Trate os códigos que você não reconhece pelo status HTTP.

Limites de taxa

As requisições são contadas por minuto, separadamente para leituras (GET) e escritas (POST, PATCH, DELETE). Os padrões são 300 leituras e 60 escritas por minuto. As requisições feitas com uma API key contam para o usuário que criou a key; os endpoints públicos do checkout contam por endereço IP.

As respostas trazem os headers padrão RateLimit e RateLimit-Policy com o limite, o que resta e quando a janela é reiniciada. Acima do limite, a API responde 429 com:

{ "code": "RATE_LIMITED", "message": "Too many requests. Try again later." }

Paginação

GET em faturas, payouts, reembolsos, transações do ledger e no log de requisições devolve uma página:

{ "items": [], "next_cursor": "inv_01JB7Q8M3X4K9TPZ2R6WVN5HDC" }

Envie next_cursor de volta como cursor para obter a próxima página; ele é null na última página. limit vai de 1 a 100 (padrão 25; 50 para o log de requisições). Os itens vêm dos mais recentes para os mais antigos. Os demais endpoints de listagem (redes, contas, payment links, saldos, contas do ledger) devolvem { "items": [...] } em uma única resposta.

Valores e IDs

• Os valores são strings decimais, nunca números. Preços em USD têm no máximo duas casas decimais ("100", "100.5", "100.00"); valores em tokens são exatos, com pelo menos duas casas decimais ("102.50", "76.875").
• As porcentagens (markup_percent, splits[].percent) são números JSON com no máximo duas casas decimais (2.5 é 2,5 %).
• Os IDs de objeto têm um prefixo: inv_ faturas, acct_ contas, po_ payouts, rfd_ reembolsos, plink_ payment links, ltx_ transações do ledger. Eles são ordenáveis pela data de criação.
• Os timestamps estão em ISO 8601, em UTC.