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

# Flujos de Primera Parte

> Caminos de implementación cuando la misma entidad legal posee ambos lados del movimiento: transferencias únicas, Onramper Accounts y Offloader Wallets.

**Cuándo Sphere te enruta aquí:** El descubrimiento confirmó que la misma entidad legal posee tanto el origen como el destino — por ejemplo, on-ramp de tesorería, off-ramp de tesorería, o fondeo reutilizable/retiro para la cuenta bancaria y billetera propia de esa entidad.

Esta página define el **patrón de implementación de primera parte** a construir. Para definiciones de objetos y payloads de API, sigue los enlaces hacia [Conceptos](/es/concepts/overview) y [Referencia API](/es/api-reference/customer/post).

<Note>
  ¿Pagando empleados, proveedores, vendedores de marketplace u otros terceros? Usa [Flujos de Tercera Parte](/es/implementation-guides/third-party-flows) en su lugar.
</Note>

## Salida de definición

Al final del descubrimiento, tú y SpherePay deben acordar sobre:

* Tipo de cliente — individual o empresarial
* Entidad legal que posee **tanto** el origen como el destino
* Primer movimiento — on-ramp, off-ramp, o ambos
* Patrón — transferencia única, Onramper Account u Offloader Wallet
* Divisa fiat y riel
* Stablecoin y red
* Transferencias únicas vs instrucciones reutilizables
* Solo movimiento/conversión vs tenencia de saldo fiat
* Volumen mensual esperado, tamaño de transacción promedio y máximo
* Requisitos de perfil de verificación y habilitación de corredor
* Campos de conciliación que necesita tu equipo de finanzas

## Elige tu patrón

<CardGroup cols={3}>
  <Card title="Transferencia única" icon="arrow-left-right" href="#pattern-one-off-transfer">
    Control explícito de API por on-ramp u off-ramp. Mejor cuando cada movimiento se inicia individualmente.
  </Card>

  <Card title="Onramper Account" icon="landmark" href="#pattern-onramper-account">
    Instrucciones de depósito fiat reutilizables que convierten automáticamente a stablecoin en la billetera del cliente.
  </Card>

  <Card title="Offloader Wallet" icon="wallet" href="#pattern-offloader-wallet">
    Dirección de depósito de stablecoin reutilizable que convierte automáticamente a fiat en la cuenta bancaria del cliente.
  </Card>
</CardGroup>

| Patrón                                           | Señales del descubrimiento                                                                                     | Objetos principales                                                                                                                                             |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Transferencia única](#pattern-one-off-transfer) | Control de API por movimiento; conversiones ad-hoc; seguimiento de estado por transferencia                    | Cliente, [billetera](/es/concepts/transfers/wallets), [cuenta bancaria](/es/concepts/transfers/bank-accounts), [transferencia](/es/concepts/transfers/overview) |
| [Onramper Account](#pattern-onramper-account)    | Depósitos fiat reutilizables; conversión automática a stablecoin; sin llamada de transferencia por depósito    | Cliente, billetera, [Onramper Account](/es/concepts/automation/onramper-accounts)                                                                               |
| [Offloader Wallet](#pattern-offloader-wallet)    | Depósitos de stablecoin reutilizables; conversión automática a fiat; sin llamada de transferencia por depósito | Cliente, cuenta bancaria, [Offloader Wallet](/es/concepts/automation/offloader-wallets)                                                                         |

## Cómo funciona el flujo

<Tabs>
  <Tab title="On-ramp">
    Cuenta bancaria del cliente o cuenta de fondeo reutilizable → SpherePay → Billetera del cliente

    ```mermaid theme={"dark"}
    flowchart LR
        BA["Customer<br/>bank account"] -->|Fiat deposit| SP["SpherePay"]
        SP -->|Stablecoin| W["Customer<br/>wallet"]
    ```
  </Tab>

  <Tab title="Off-ramp">
    Billetera del cliente → SpherePay → Cuenta bancaria del cliente

    ```mermaid theme={"dark"}
    flowchart LR
        W["Customer<br/>wallet"] -->|Stablecoin| SP["SpherePay"]
        SP -->|Fiat payout| BA["Customer<br/>bank account"]
    ```
  </Tab>
</Tabs>

Para un ejemplo de viaje de ida y vuelta de tesorería, consulta [Gestión de tesorería](/es/solutions/treasury-management).

## Patrón: Transferencia única

**Usar cuando:** El cliente inicia cada on-ramp u off-ramp individualmente y necesita control explícito por transferencia.

**Señales del descubrimiento:**

* Cada movimiento se inicia en un momento específico — no activado por una dirección de depósito permanente
* El integrador posee el reintento, la idempotencia y la UX de estado por transferencia
* El cliente puede necesitar cotizar o ejecutar transferencias una a la vez

<Steps>
  <Step title="Crear o recuperar el cliente">
    Registra la entidad legal vía [POST /v2/customer](/es/api-reference/customer/post).
  </Step>

  <Step title="Completar KYC o KYB">
    Termina el [KYC individual](/es/concepts/onboarding/individual-kyc) o el [KYB empresarial](/es/concepts/onboarding/business-kyb) hasta que el [perfil de verificación](/es/concepts/onboarding/verification-profile) alcance `approved`.
  </Step>

  <Step title="Registrar instrumentos">
    Vincula la [billetera](/es/api-reference/wallet/post) y la [cuenta bancaria](/es/api-reference/bank-account/post) del cliente en el mismo registro de cliente.
  </Step>

  <Step title="Bloquear una tasa (opcional)">
    Si el cliente necesita una tasa garantizada, crea una cotización con tasa bloqueada vía [POST /v2/quote](/es/api-reference/quote/post) (válida por 30, 60 o 300 segundos, canjeable una vez) y referencia su `quoteId` al crear la transferencia.
  </Step>

  <Step title="Crear cada transferencia">
    Llama a [POST /v2/transfer](/es/api-reference/transfer/post) con cliente, origen y destino.
  </Step>

  <Step title="Rastrear y conciliar">
    Consulta [GET /v2/transfer/{transferId}](/es/api-reference/transfer/get-id) hasta un estado terminal — consulta el [ciclo de vida de la transferencia](/es/concepts/transfers/lifecycle).
  </Step>
</Steps>

<Note>
  Confirma que los instrumentos de origen y destino pertenecen al **mismo** cliente incorporado. Algunos corredores requieren habilitación específica del proveedor más allá del KYC/KYB estándar — confirma el acceso con SpherePay antes de construir.
</Note>

**Solución relacionada:** [Gestión de tesorería](/es/solutions/treasury-management)

## Patrón: Onramper Account

**Usar cuando:** El cliente necesita instrucciones de depósito fiat reutilizables que convierten automáticamente a stablecoin en una billetera que posee.

**Señales del descubrimiento:**

* El cliente enviará fiat a las mismas instrucciones de depósito repetidamente
* No debe dispararse una llamada `POST /v2/transfer` en cada depósito
* El destino es una billetera de stablecoin propiedad de la misma entidad legal

<Steps>
  <Step title="Crear o recuperar el cliente">
    Registra la entidad legal vía [POST /v2/customer](/es/api-reference/customer/post).
  </Step>

  <Step title="Completar KYC o KYB">
    Alcanza `approved` en el perfil de verificación requerido.
  </Step>

  <Step title="Registrar la billetera de destino">
    El cliente ya debe poseer la dirección on-chain. Registra vía [POST /v2/wallet](/es/api-reference/wallet/post).
  </Step>

  <Step title="Crear un Onramper Account">
    Llama a [POST /v2/virtual-account](/es/api-reference/virtual-account/post). Consulta [Onramper Accounts](/es/concepts/automation/onramper-accounts).
  </Step>

  <Step title="Compartir instrucciones de depósito">
    Proporciona `depositInstructions` de la respuesta. SpherePay convierte el fiat entrante y entrega stablecoin automáticamente.
  </Step>

  <Step title="Rastrear depósitos y conversiones">
    Consulta [GET /v2/transfer](/es/api-reference/transfer/get) filtrado por cliente (usa `type=microdeposit` para depósitos de verificación) para listar las transferencias procesadas a través de la cuenta. Cada depósito fiat aparece como una transferencia una vez detectado — concilia contra tus depósitos esperados. No hay una llamada de API por depósito en la que anclar el estado, así que diseña tu cadencia de polling y claves de conciliación antes del lanzamiento.
  </Step>
</Steps>

<Warning>
  Los Onramper Accounts son un producto adicional. Crea **una cuenta por cliente** — las cuentas compartidas rompen la atribución de depósitos. Confirma que el producto está habilitado para tu riel y región.
</Warning>

**Soluciones relacionadas:** [Aceptación de pagos](/es/solutions/payment-acceptance), [Gestión de tesorería](/es/solutions/treasury-management)

## Patrón: Offloader Wallet

**Usar cuando:** El cliente necesita una dirección on-chain reutilizable que convierte automáticamente stablecoin entrante a fiat en una cuenta bancaria que posee.

**Señales del descubrimiento:**

* El cliente enviará stablecoin a la misma dirección repetidamente
* No debe dispararse una llamada `POST /v2/transfer` en cada depósito
* El destino fiat es una cuenta bancaria propiedad de la misma entidad legal

<Steps>
  <Step title="Crear o recuperar el cliente">
    Registra la entidad legal vía [POST /v2/customer](/es/api-reference/customer/post).
  </Step>

  <Step title="Completar KYC o KYB">
    Alcanza `approved` en el perfil de verificación requerido.
  </Step>

  <Step title="Registrar la cuenta bancaria de destino">
    Vincula la cuenta existente del cliente vía [POST /v2/bank-account](/es/api-reference/bank-account/post).
  </Step>

  <Step title="Crear un Offloader Wallet">
    Llama a [POST /v2/offloader-wallet](/es/api-reference/offloader-wallet/post). Consulta [Offloader Wallets](/es/concepts/automation/offloader-wallets).
  </Step>

  <Step title="Compartir la dirección offloader">
    Proporciona la dirección on-chain de la respuesta. SpherePay convierte la stablecoin y paga el fiat automáticamente.
  </Step>

  <Step title="Rastrear depósitos y pagos">
    Consulta [GET /v2/transfer](/es/api-reference/transfer/get) filtrado por cliente para rastrear depósitos de stablecoin y los pagos fiat resultantes hasta un estado terminal — consulta el [ciclo de vida de la transferencia](/es/concepts/transfers/lifecycle).
  </Step>
</Steps>

<Warning>
  Los Offloader Wallets son un producto adicional. Crea **una billetera por cliente**. Para cambiar el tipo de divisa/destino de origen o el tipo de riel, crea una nueva billetera — otros campos pueden ser PATCHeable vía [Actualizar Offloader Wallet](/es/api-reference/offloader-wallet/patch-id). Verifica el nombre legal y la dirección física del titular de la cuenta bancaria (sin apartados postales) antes de crear la billetera — los socios rechazan direcciones con apartado postal, y las vías de corrección para una cuenta bancaria adjunta son limitadas.
</Warning>

**Solución relacionada:** [Gestión de tesorería](/es/solutions/treasury-management)

## Qué enviar a Sphere antes del inicio

* Tipo de cliente: individual o empresarial
* Entidad legal que posee origen y destino
* Primer flujo: on-ramp, off-ramp, o ambos
* Patrón seleccionado: transferencia única, Onramper Account u Offloader Wallet
* Divisa fiat y riel
* Stablecoin y red
* Volumen mensual esperado
* Tamaño de transacción promedio y máximo
* Transferencias únicas vs instrucciones reutilizables
* Solo movimiento/conversión vs tenencia de saldo fiat
* Requisitos de conciliación

## Validar antes de que comience la ingeniería

| Bloqueo                             | Qué suele significar                                                                                                                      |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Perfil de verificación no aprobado  | El perfil KYC/KYB requerido está incompleto, pendiente, faltante o rechazado                                                              |
| Proveedor/corredor no habilitado    | El cliente puede estar aprobado en general pero no habilitado para el corredor o riel específico                                          |
| Riel, divisa o red no soportados    | Combinación no disponible para tu producto — [Rieles soportados](/es/concepts/transfers/supported-rails)                                  |
| Discrepancia de propiedad           | El instrumento de origen o destino no pertenece al cliente incorporado                                                                    |
| Confusión con billeteras            | [POST /v2/wallet](/es/api-reference/wallet/post) registra una dirección existente — SpherePay no genera ni custodia claves privadas       |
| Confusión con Onramper Account      | Automatiza la conversión de fiat a stablecoin vía instrucciones de depósito — confirma requisitos de solo movimiento vs tenencia de saldo |
| Actualizaciones de Offloader Wallet | Cambiar el tipo de divisa/destino de origen o el tipo de riel requiere una nueva billetera; otros campos pueden ser PATCHeables           |

## Lista de verificación pre-inicio

* [ ] La misma entidad legal posee origen y destino
* [ ] Patrón seleccionado y confirmado con SpherePay
* [ ] Cliente creado o recuperado; perfil de verificación `approved` para el corredor objetivo
* [ ] Proveedor/corredor habilitado si es requerido
* [ ] Billetera y/o cuenta bancaria registrada en el cliente correcto
* [ ] Riel, divisa y red confirmados
* [ ] Mapeo de conciliación y estado definido
* [ ] Entradas de inicio enviadas a SpherePay

## Antes del lanzamiento

SpherePay no tiene un sandbox separado — las pruebas de integración se ejecutan contra producción con datos de identidad reales. Ejecuta una transferencia en vivo de bajo monto en cada corredor antes del lanzamiento.

La primera transferencia a un nuevo beneficiario puede activar un RFI de cumplimiento del socio bancario. Establece esta expectativa con tu cliente desde el inicio, y asegúrate de que tu propietario de RFI designado esté listo para responder.

Para preguntas de liquidación de usuarios finales, comparte los artículos de la Base de Conocimiento de SpherePay [When will the funds land in my account?](https://spherepay-knowledge-base.help.usepylon.com/articles/9934878291-when-will-the-funds-land-in-my-account) y [My funds are missing or have not landed in my account](https://spherepay-knowledge-base.help.usepylon.com/articles/9884755317-my-funds-are-missing-or-have-not-landed-in-my-account-what-should-i-do) para que los usuarios se autoatiendan en lugar de abrir tickets de soporte contigo.

## Profundizar

<CardGroup cols={2}>
  <Card title="Gestión de tesorería" icon="landmark" href="/es/solutions/treasury-management">
    Resultado de tesorería de primera parte — ejemplos de on-ramp/off-ramp de ida y vuelta.
  </Card>

  <Card title="Transferencias" icon="arrow-left-right" href="/es/concepts/transfers/overview">
    Ciclo de vida de transferencia única, restricciones BRL/PIX y referencia de estados.
  </Card>

  <Card title="Flujos de Tercera Parte" icon="users" href="/es/implementation-guides/third-party-flows">
    Cuando origen y destino no son la misma entidad legal.
  </Card>

  <Card title="Incorporación" icon="user-check" href="/es/concepts/onboarding/overview">
    Requisitos de KYC, KYB y perfil de verificación.
  </Card>

  <Card title="Base de Conocimiento y FAQ" icon="book-open" href="https://spherepay-knowledge-base.help.usepylon.com/">
    Artículos de soporte para usuarios finales — tiempos de liquidación, fondos faltantes, mínimos y guías del panel — para compartir con tus usuarios.
  </Card>
</CardGroup>