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

# Faça Sua Primeira Chamada à API do SpherePay

> Passo a passo para criar um cliente, registrar uma conta bancária e carteira, e executar sua primeira transferência de on-ramp com a API do SpherePay.

Este guia apresenta a sequência completa para sua primeira integração com o SpherePay: criar um cliente (`customer`), registrar uma conta bancária e carteira, e executar uma transferência de on-ramp. Ao final, você terá feito chamadas reais de API para todos os recursos centrais do modelo SpherePay.

Todas as requisições vão para a URL base: `https://api.spherepay.co/`

## Pré-requisitos

* Você tem uma chave de API. Caso contrário, consulte [Autenticação](/pt-BR/get-started/authentication).
* Você entende o modelo de integração. Caso contrário, leia [Como funciona](/pt-BR/get-started/how-it-works) primeiro.

<Steps>
  <Step title="Criar um cliente">
    Crie um cliente pessoa física enviando uma requisição `POST` para `/v2/customer`. Inclua os dados de contato e as informações de identificação fiscal do cliente.

    ```bash theme={"dark"}
    curl -X POST https://api.spherepay.co/v2/customer \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "email": "jane.smith@example.com",
        "phone": "+14155550123",
        "address": {
          "line1": "233 South Wacker Drive",
          "line2": "Suite 4700",
          "city": "Chicago",
          "postalCode": "60606",
          "state": "IL",
          "country": "USA"
        },
        "personalInformation": {
          "taxIdentificationNumber": "123456789",
          "taxIdentificationNumberType": "ssn",
          "taxIdentificationNumberCountry": "USA"
        }
      }'
    ```

    Uma resposta bem-sucedida retorna o objeto do cliente recém-criado com um `id` gerado pelo sistema e um array `verificationProfiles` mostrando o status do KYC como `incomplete`:

    ```json theme={"dark"}
    {
        "id": "customer_4fbb292cc6e447da8858e054d1937e7e",
        "email": "jane.smith@example.com",
        "phone": "+14155550123",
        "verificationProfiles": [
            {
                "name": "kyc_profile_a",
                "status": "incomplete",
                "criteria": {
                    "complete": [],
                    "pending": [],
                    "required": [],
                    "errors": []
                }
            }
        ],
        "createdAt": "2026-03-03T21:25:03.102Z",
        "updatedAt": "2026-03-03T21:25:03.102Z",
        "type": "individual"
    }
    ```

    <Note>
      O cliente deve completar a verificação KYC e atingir o status `approved` antes que você possa criar uma transferência em seu nome. O onboarding é um pré-requisito obrigatório para todas as transferências. Consulte o [Fluxo de KYC Individual](/pt-BR/concepts/onboarding/individual-kyc) ou o [Fluxo de KYB Empresarial](/pt-BR/concepts/onboarding/business-kyb) para os próximos passos.
    </Note>
  </Step>

  <Step title="Registrar uma conta bancária">
    Assim que seu cliente tiver aprovação no KYC, registre a conta bancária (`bank_account`) que servirá como origem fiat para uma transferência de on-ramp. Envie uma requisição `POST` para `/v2/bank-account` com o ID do cliente e os detalhes da conta.

    ```bash theme={"dark"}
    curl -X POST https://api.spherepay.co/v2/bank-account \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
        "bankName": "Chase",
        "accountName": "Jane Doe Checking",
        "accountOwner": {
          "accountHolderName": "Jane Doe",
          "address": {
            "line1": "233 South Wacker Drive",
            "city": "Chicago",
            "state": "IL",
            "postalCode": "60606",
            "country": "USA"
          }
        },
        "currency": "usd",
        "accountDetails": {
          "accountNumber": "123456789",
          "routingNumber": "021000021",
          "accountType": "checking"
        },
        "networks": ["ach"]
      }'
    ```

    Uma resposta bem-sucedida retorna o objeto da conta bancária com um `id` gerado pelo sistema:

    ```json theme={"dark"}
    {
        "id": "bankAccount_7c3d2a1b4e8f4290a1c2d3e4f5a6b7c8",
        "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
        "bankName": "Chase",
        "accountName": "Jane Doe Checking",
        "currency": "usd",
        "networks": ["ach"],
        "createdAt": "2026-03-03T21:30:00.000Z",
        "updatedAt": "2026-03-03T21:30:00.000Z"
    }
    ```
  </Step>

  <Step title="Registrar uma carteira">
    Registre a carteira (`wallet`) cripto que servirá como destino para a transferência de on-ramp. Envie uma requisição `POST` para `/v2/wallet` com o ID do cliente e os detalhes da carteira.

    ```bash theme={"dark"}
    curl -X POST https://api.spherepay.co/v2/wallet \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
        "address": "0xAbC1234567890dEfAB1234567890DEFaB123456",
        "network": "ethereum",
        "currency": "usdc"
      }'
    ```

    Uma resposta bem-sucedida retorna o objeto da carteira com um `id` gerado pelo sistema:

    ```json theme={"dark"}
    {
        "id": "wallet_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
        "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
        "address": "0xAbC1234567890dEfAB1234567890DEFaB123456",
        "network": "ethereum",
        "currency": "usdc",
        "status": "active",
        "createdAt": "2026-03-03T21:35:00.000Z",
        "updatedAt": "2026-03-03T21:35:00.000Z"
    }
    ```
  </Step>

  <Step title="Criar uma transferência de on-ramp">
    Com um cliente verificado, uma conta bancária e uma carteira registradas, você já pode criar uma transferência de on-ramp. Especifique a conta bancária como `source` e a carteira como `destination`.

    ```bash theme={"dark"}
    curl -X POST https://api.spherepay.co/v2/transfer \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": "100.00",
        "customer": "customer_4fbb292cc6e447da8858e054d1937e7e",
        "source": {
          "type": "bank_account",
          "id": "bankAccount_7c3d2a1b4e8f4290a1c2d3e4f5a6b7c8",
          "currency": "usd",
          "network": "ach"
        },
        "destination": {
          "type": "wallet",
          "id": "wallet_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
          "currency": "usdc",
          "network": "ethereum"
        }
      }'
    ```

    Uma resposta bem-sucedida retorna o objeto da transferência. O `status` inicial será `pendingFunding` enquanto o SpherePay aguarda os fundos:

    ```json theme={"dark"}
    {
        "id": "payout_9z8y7x6w5v4u3t2s1r0q",
        "type": "on_ramp",
        "status": "pendingFunding",
        "customer": "customer_4fbb292cc6e447da8858e054d1937e7e"
    }
    ```
  </Step>

  <Step title="Acompanhar o status da transferência">
    Consulte o status da transferência enviando uma requisição `GET` para `/v2/transfer/{id}` usando o `id` retornado na etapa anterior.

    ```bash theme={"dark"}
    curl https://api.spherepay.co/v2/transfer/payout_9z8y7x6w5v4u3t2s1r0q \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    A resposta retorna o objeto da transferência com um campo `status` atualizado. Uma transferência avança por `pendingFunding` → `fundsReceived` → `processing` → `succeeded` (ou `failed` se ocorrer um erro). Consulte [Ciclo de Vida da Transferência](/pt-BR/concepts/transfers/lifecycle) para todos os status possíveis e seus significados.
  </Step>
</Steps>