# Documentação da API

> Mapa da API do Throne: Pix, cartão em várias moedas, internacional, saldo, saques e webhooks.

Fonte: https://app.thronecorporate.com/docs

## O que dá para fazer com a API

| Você quer | Use | Guia |
|---|---|---|
| Receber por Pix (QR Code e copia e cola) | `POST /transactions` com `payment_method: "pix"` | [Cobrar com Pix](/docs/pix) |
| Receber cartão dentro da sua página, na moeda do comprador | `POST /elements/checkout` + Throne Elements | [Cartão: como funciona](/docs/cartao) |
| Receber cartão do comprador brasileiro, com a página em português, o CPF pedido na tela e o botão e a moldura ajustados pela API | `POST /elements/checkout/br` + Throne Elements | [Checkout Brasil](/docs/cartao/brasil) |
| Cobrar um segundo produto sem pedir o cartão de novo | `POST /elements/checkout` com `one_click_from` | [Upsell em um clique](/docs/cartao/oneclick) |
| Cobrar no cartão a cada ciclo, sozinho | `POST /elements/checkout` com `recurrence` | [Recorrência](/docs/cartao/recorrencias) |
| Receber pagamento internacional por botão embutido | `POST /global/checkout` + iframe | [Internacional (Paycore)](/docs/internacional) |
| Ver o saldo da conta | `GET /balance` | [Saldo e saques](/docs/saques) |
| Sacar por Pix ou cripto | `POST /withdrawals` | [Saldo e saques](/docs/saques) |
| Saber na hora que uma venda foi paga | Webhook `transaction.paid` | [Webhooks](/docs/webhooks) |

URL base de todas as chamadas:

```text
https://app.thronecorporate.com/api/v1
```

## Por onde começar

1. Gere uma chave de API no painel, em [Chaves de API](https://app.thronecorporate.com/painel/api-keys).
2. Leia [Comece aqui](/docs/comecar): autenticação, `Idempotency-Key`, tempo de resposta e formato dos erros. São cinco minutos e evitam a maior parte dos problemas.
3. Veja [Limites e tempos](/docs/limites) e [Como testar](/docs/testar). Não existe ambiente de testes separado.
4. Siga o guia do meio de pagamento que você vai usar.
5. Cadastre a URL do seu webhook no painel e valide a assinatura, como em [Webhooks](/docs/webhooks).
6. Antes de abrir as vendas, passe pelo [Checklist de verificação](/docs/checklist).

## Cartão: qual guia é o seu

O cartão é sempre o mesmo Throne Elements, criado pelo `POST /elements/checkout` ou, para o comprador brasileiro, pelo [Checkout Brasil](/docs/cartao/brasil). No checkout comum, o que muda é o comportamento do checkout, conforme a adquirente. Com mais de uma adquirente habilitada na conta, cada site escolhe a dela pelo campo `acquirer` ([como escolher](/docs/cartao/escolher)). As habilitadas aparecem no painel, em **Documentação da API**, e em `GET /elements/acquirers`.

| Adquirente | Verificação do banco | Navegador de app (Instagram, Facebook) | Tentativas por checkout | Guia |
|---|---|---|---|---|
| Sterling | Não tem: aprova ou recusa na hora | Tudo dentro do elemento | 5 | [Sterling](/docs/cartao/sterling) |
| Imperium | Não tem: o resultado sai na própria tentativa (uma recusa pode levar até 25 segundos) | Tudo dentro do elemento | 5 | [Imperium](/docs/cartao/imperium) |
| NovaCorp | Abre uma janela de verificação; a tela do banco aparece nela quando ele pede | A própria aba vai para a página segura de pagamento, sem evento na sua página | 6 | [NovaCorp](/docs/cartao/novacorp) |
| Eminence | Pode pedir; a tela do banco aparece dentro do próprio elemento | Tudo dentro do elemento | 5 | [Eminence](/docs/cartao/eminence) |
| Apex | Não tem: aprova ou recusa na hora | Tudo dentro do elemento | 5 | [Apex](/docs/cartao/apex) |
| ShadowBank | Não tem: aprova ou recusa na hora | Tudo dentro do elemento | 5 | [ShadowBank](/docs/cartao/shadowbank) |
| Vortex | Não tem: aprova ou recusa na hora | Tudo dentro do elemento | 5 | [Vortex](/docs/cartao/vortex) |

A validade do checkout é de 24 horas nas seis. O valor máximo por venda depende da adquirente e varia com a moeda e com a cotação do dia. A comparação completa está em [Comparar adquirentes](/docs/cartao/comparar).

Nas seis, você manda o valor na moeda do comprador e ele paga nessa moeda; o seu saldo é creditado em reais, pela cotação fixada na criação. Veja [Moedas e limites](/docs/cartao/moeda).

Duas formas de cobrar mais de uma vez entram pelo mesmo endpoint, como campos opcionais, e hoje só a Apex as aceita: [Upsell em um clique](/docs/cartao/oneclick), para cobrar um segundo produto sem pedir o cartão de novo, e [Recorrência](/docs/cartao/recorrencias), para a cobrança que se repete sozinha.

## Para assistentes de código e ferramentas automáticas

Toda a documentação existe também em texto puro, para quem integra com ajuda de um assistente de código:

- [`/llms.txt`](/llms.txt): índice curto, com um link por guia e a data da última atualização.
- [`/docs/llms-full.txt`](/docs/llms-full.txt): todos os guias num arquivo só.
- Qualquer guia em Markdown: acrescente `.md` ao endereço (por exemplo, [`/docs/pix.md`](/docs/pix.md)).
- [`/openapi.json`](/openapi.json) e [`/openapi.yaml`](/openapi.yaml): especificação OpenAPI 3.1 com todos os campos e respostas.
- [Changelog](/docs/changelog): o que mudou, com data.