> ## 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.

# Realiza tu Primera Llamada a la API de SpherePay

> Recorre la creación de un cliente, el registro de una cuenta bancaria y billetera, y luego ejecuta tu primera transferencia on-ramp con la API de SpherePay.

Esta guía te lleva por la secuencia completa de tu primera integración con SpherePay: crea un cliente (`customer`), registra una cuenta bancaria (`bank_account`) y una billetera (`wallet`), luego ejecuta una transferencia on-ramp. Al final, habrás realizado llamadas API reales contra cada recurso central del modelo de SpherePay.

Todas las solicitudes van a la URL base: `https://api.spherepay.co/`

## Requisitos previos

* Tienes una clave API. Si no, consulta [Autenticación](/es/get-started/authentication).
* Entiendes el modelo de integración. Si no, lee [Cómo funciona](/es/get-started/how-it-works) primero.

<Steps>
  <Step title="Crear un cliente">
    Crea un cliente individual enviando una solicitud `POST` a `/v2/customer`. Incluye los datos de contacto e información de identificación fiscal del 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"
        }
      }'
    ```

    Una respuesta exitosa devuelve el objeto de cliente recién creado con un `id` generado por el sistema y un arreglo `verificationProfiles` que muestra el estado 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>
      El cliente debe completar la verificación KYC y alcanzar un estado `approved` antes de que puedas crear una transferencia en su nombre. La incorporación es un requisito previo obligatorio para todas las transferencias. Consulta el [Flujo KYC Individual](/es/concepts/onboarding/individual-kyc) o el [Flujo KYB Empresarial](/es/concepts/onboarding/business-kyb) para los próximos pasos.
    </Note>
  </Step>

  <Step title="Registrar una cuenta bancaria">
    Una vez que tu cliente tenga aprobación KYC, registra la cuenta bancaria que servirá como origen fiat para una transferencia on-ramp. Envía una solicitud `POST` a `/v2/bank-account` con el ID de cliente y los detalles de la cuenta.

    ```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"]
      }'
    ```

    Una respuesta exitosa devuelve el objeto de cuenta bancaria con un `id` generado por el 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 una billetera">
    Registra la billetera cripto que servirá como destino para la transferencia on-ramp. Envía una solicitud `POST` a `/v2/wallet` con el ID de cliente y los detalles de la billetera.

    ```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"
      }'
    ```

    Una respuesta exitosa devuelve el objeto de billetera con un `id` generado por el 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="Crear una transferencia on-ramp">
    Con un cliente verificado, una cuenta bancaria y una billetera registradas, ahora puedes crear una transferencia on-ramp. Especifica la cuenta bancaria como `source` (origen) y la billetera como `destination` (destino).

    ```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"
        }
      }'
    ```

    Una respuesta exitosa devuelve el objeto de transferencia. El `status` inicial será `pendingFunding` mientras SpherePay espera los fondos:

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

  <Step title="Rastrear el estado de la transferencia">
    Consulta el estado de la transferencia enviando una solicitud `GET` a `/v2/transfer/{id}` usando el `id` devuelto en el paso anterior.

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

    La respuesta devuelve el objeto de transferencia con un campo `status` actualizado. Una transferencia avanza por `pendingFunding` → `fundsReceived` → `processing` → `succeeded` (o `failed` si ocurre un error). Consulta [Ciclo de Vida de la Transferencia](/es/concepts/transfers/lifecycle) para todos los posibles estados y sus significados.
  </Step>
</Steps>