> ## Documentation Index
> Fetch the complete documentation index at: https://t3sa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Primeira chamada em 5 minutos

> Da chave de API ao webhook de resgate, no sandbox

<Warning>
  Rascunho: especificação em definição. Endpoints e campos podem mudar.
</Warning>

Este roteiro usa o sandbox, sem fundos reais. As URLs são propostas e ainda não estão ativas, e todos os valores são ilustrativos.

<Steps>
  <Step title="Obtenha uma chave de API">
    Solicite acesso em [contact@t3sa.com](mailto:contact@t3sa.com?subject=Chave%20de%20API%20Tesa). Depois do onboarding, um administrador cria a chave no painel. Chaves de sandbox começam com `tesa_test_`.

    ```bash theme={null}
    export TESA_API_KEY="tesa_test_..."
    ```
  </Step>

  <Step title="Leia as posições">
    ```bash theme={null}
    curl https://sandbox.api.t3sa.com/v1/posicoes \
      -H "Authorization: Bearer $TESA_API_KEY"
    ```

    ```json Resposta 200 theme={null}
    {
      "total": "1284530.00",
      "rendendo": "842110.00",
      "disponivel": "442420.00",
      "por_ativo": [
        { "ativo": "USDY", "valor": "505266.00", "percentual": 60.00 },
        { "ativo": "BUIDL", "valor": "336844.00", "percentual": 40.00 }
      ],
      "yield_acumulado": "18432.55",
      "atualizado_em": "2026-09-01T12:00:00Z"
    }
    ```
  </Step>

  <Step title="Crie um resgate">
    O resgate vai sempre para uma carteira vinculada da própria empresa e exige `Idempotency-Key`.

    ```bash theme={null}
    curl -X POST https://sandbox.api.t3sa.com/v1/resgates \
      -H "Authorization: Bearer $TESA_API_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{"valor":"150000.00","carteira_destino_id":"cart_3k9d","referencia_interna":"folha-2026-09"}'
    ```

    O resgate nasce `pendente`. Uma chave com escopo `admin`, ou um aprovador no painel, aprova com `POST /resgates/res_4t7x/aprovar`.
  </Step>

  <Step title="Assine no custodiante">
    Depois da aprovação, o resgate passa a `aguardando_assinatura` e traz as transações em `transacoes[].payload_nao_assinado`. Envie esse payload ao custodiante da empresa, que assina e transmite. A TESA nunca vê a chave.
  </Step>

  <Step title="Receba o webhook">
    Cadastre um destino com `POST /webhooks`. Quando a transação confirma on-chain, chega o evento:

    ```json theme={null}
    {
      "id": "evt_9k2m4p",
      "tipo": "resgate.concluido",
      "criado_em": "2026-09-01T14:07:12Z",
      "ambiente": "sandbox",
      "organizacao_id": "org_1a2b",
      "dados": { "id": "res_4t7x", "status": "concluido", "valor": "150000.00" }
    }
    ```

    Verifique a assinatura antes de processar. Veja [Webhooks](/docs/api/webhooks).
  </Step>
</Steps>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Arquitetura" icon="network" href="/docs/api/arquitetura">
    Quem guarda as chaves e como cada operação passa do preparo ao registro.
  </Card>

  <Card title="Guia de resgate" icon="arrow-down-to-line" href="/docs/api/guias/resgate">
    O fluxo de resgate completo, com tratamento de erros.
  </Card>
</CardGroup>