Conversão
Entidade central do offramp. Representa a operação do aceite da cotação até a liquidação do Pix. Lista completa de estados.
Conversão (conversion) é a entidade central do offramp. Ela existe a partir do aceite da cotação e atravessa todo o ciclo até a liquidação do Pix ou um desfecho terminal alternativo. É o recurso que você lê (GET /v1/conversions/:id) e aciona (/cancel, /liquidate).
Por que conversão é separada da cotação
Cotação e conversão respondem a perguntas diferentes:
- Cotação responde: "qual a taxa agora?". É um preço congelado, descartável, sem efeito colateral.
- Conversão responde: "qual operação está em andamento, em que estado, com quanto recebido?". É a operação executável, com endereço de depósito, janela, reserva de limite e máquina de estados.
Separar evita que cotações descartadas poluam o histórico de operações reais e mantém a máquina de estados da conversão enxuta.
Diagrama de estados
Estados, um a um
| Estado | O que significa | O que você está esperando | Ações disponíveis |
|---|---|---|---|
awaiting_deposit | Conversão criada, endereço de depósito emitido, janela de 15 minutos rodando | O cliente final depositar USDT | cancel |
funded | Depósito on-chain confirmado no valor exato dentro da janela | A liquidação do Pix avançar automaticamente | (nenhuma) |
standby | Depósito divergente, janela expirada com depósito, ou ambos. A conversão não avança automaticamente | Sua decisão entre liquidate ou suporte | liquidate |
liquidated | Liquidação manual disparada via /liquidate; nova taxa aplicada | A liquidação do Pix avançar automaticamente | (nenhuma) |
completed | Pix entregue ao destinatário. Terminal | (terminal) | (nenhuma) |
failed | Erro irrecuperável após funded ou liquidated. Veja failure_reason. Terminal | (terminal) | (nenhuma) |
expired | Janela passou sem depósito. Reserva liberada. Terminal | (terminal) | (nenhuma) |
canceled | Você cancelou em awaiting_deposit. Reserva liberada. Terminal | (terminal) | (nenhuma) |
abandoned | 7 dias em standby sem ação. Resolução manual fora da plataforma. Terminal | Contato com o suporte da BlendFi | (nenhuma) |
`partially_funded` é interno
O schema reserva o status partially_funded para um cenário transiente que, na política atual, resolve imediatamente para standby com standby_reason='under_funded'. Você nunca observa partially_funded no fio. Está documentado aqui apenas para completude.
Campos chave
A conversão expõe (entre outros):
id,quote_id,liquidation_quote_id,status,transaction_type(pix_offramp).expected_source_amount(o USDT esperado, fixado no aceite) ereceived_amount(a soma efetivamente recebida on-chain).deposit_address,deposit_address_network,deposit_window_expires_at.standby_at,standby_expires_at,standby_reason(quando aplicável).- Campos de execução populados após a liquidação: identificadores Pix de ponta a ponta, hash da transação USDT, timestamps,
failure_reason.
A lista completa de campos vai na referência da API quando ela for publicada.
Webhooks por transição
| Transição | Evento |
|---|---|
(criação) → awaiting_deposit | conversion.created |
awaiting_deposit → standby | conversion.standby |
awaiting_deposit → expired | conversion.expired |
awaiting_deposit → canceled | conversion.canceled |
funded → completed, liquidated → completed | conversion.completed |
funded → failed, liquidated → failed | conversion.failed |
standby → abandoned | conversion.abandoned |
Não há webhook intermediário para funded ou liquidated: o evento de interesse é o desfecho (completed, failed, standby, expired, canceled, abandoned). A liquidação manual é síncrona e o desfecho subsequente chega via conversion.completed.
Próximos passos
- Lock por usuário e tipo: a regra de uma conversão aberta por cliente final.
- Standby e liquidação manual: a operação mais sensível do ciclo.