P2P Cripto — ordens
Uma ordem é uma negociação sobre um anúncio. Quem toma o anúncio abre a ordem; o anunciante é a outra parte. Rotas em /v1/accounts/{accountId}/p2p/orders.
Abertura
POST .../p2p/orders com Idempotency-Key, adId, walletId (opcional, senão a padrão) e amount (reais) ou cryptoAmount. Antes de responder 201, a CorpX:
- tria de novo as duas carteiras;
- reserva o estoque do anúncio;
- bloqueia o valor do comprador (o hold).
Se qualquer passo falha, a resposta é 4xx e nada fica travado. Na recusa de carteira (422 wallet_not_approved), details.walletOf diz de quem é: taker (quem abriu) ou maker (o anunciante). A repetição com a mesma chave e o mesmo corpo devolve a mesma ordem.
Preço da ordem e evidência
O preço é travado na abertura com uma consulta ao vivo ao preço spot da Binance (GET /api/v3/ticker/price?symbol={ATIVO}BRL), a única fonte de cotação do mercado. Anúncio com spread aplica os pontos-base sobre esse spot; anúncio com offset soma a diferença em reais (até 4 casas); anúncio com fixed mantém o preço fixo, mas a Binance é consultada do mesmo jeito, para registrar o mercado do momento. A consulta não usa cache: é a leitura daquele instante.
O preço por unidade fica com 4 casas (5.4321) na ordem, na evidência e no contrato. O valor em reais da ordem é que vira centavos, truncado (cripto × preço); a taxa arredonda ao centavo para cima.
A troca HTTP inteira fica guardada como evidência da ordem: request (método, URL, headers), resposta (status, todos os headers, corpo cru e sha256 do corpo), transporte (IP remoto, sessão TLS e cadeia de certificados), horários com milissegundos e o sha256 do registro canônico. Ordem e evidência são gravadas na mesma transação: não existe ordem sem evidência.
GET .../p2p/orders/{orderId}/price-evidence devolve o registro para qualquer uma das partes desde a abertura. verified diz se o hash ainda confere; orderPrice é o preço travado e spotPrice o spot que o gerou. O mesmo registro entra no contrato (cotacao_binance, cotacao_horario, cotacao_evidencia_sha256) e fica à disposição da análise de disputa.
Se a Binance não responde (tempo esgotado, erro, limite de requisições, resposta inválida), a abertura responde 409 price_unavailable e nada é criado nem travado; repita em instantes com a mesma Idempotency-Key. A repetição de uma ordem que já existe não consulta a Binance de novo.
Ciclo de vida
Com a assinatura desligada no mercado, a ordem vai de funded direto para signed.
Prazos
A CorpX ajusta as durações para o mercado inteiro. deadlineAt é sempre o prazo que corre agora; em disputa ou status final, null. Use esse campo para o cronômetro da tela.
Compra de ponta a ponta
Cancelamento e falta
POST .../cancel com reason opcional:
- antes de assinar a própria via, qualquer parte cancela; a falta (
fault) fica com quem cancelou; - depois das duas assinaturas, cancelar não existe: o caminho é a disputa;
- prazo vencido cancela com a falta de quem deixou vencer;
- recusa da assinatura cancela com a falta de quem recusou.
A ordem cancelada mostra cancelledBy, fault e cancelReason. O valor volta ao comprador e o estoque ao anúncio. A falta entra na reputação.
Timeline
GET .../p2p/orders/{orderId} traz timeline: a história da ordem do ponto de vista de quem consulta. Cada item tem at, type, title, actor (buyer, seller, corpx ou system), actorIsYou e data.
- O título já sai pronto em português e relativo a quem lê: “Você assinou o contrato”, “A contraparte enviou a cripto”.
- A contraparte nunca aparece por nome nem documento, e o atendente da CorpX aparece só como “CorpX”.
datasó traz campos públicos do tipo (valor, prazo, txid, confirmações, motivo). O comprador vê o valor bloqueado e devolvido; quem paga a taxa vê a cobrança.
Quando a ordem é concluída
A ordem tem concluded e concludedAt. Ela conclui quando tudo abaixo vale:
- está
released, ouresolvedcom a disputa decidida para o vendedor; - as duas partes assinaram o contrato (quando a assinatura está ligada);
- o pagamento ao vendedor foi gravado;
- a taxa foi cobrada (quando há taxa).
Ordem cancelada ou devolvida ao comprador não conclui.
Comprovante
GET .../p2p/orders/{orderId}/receipt responde só para ordem concluída (senão, 409 order_not_concluded). É o único lugar em que as partes se identificam: nome, username e documento mascarado (***.456.789-**, 12.345.678/****-**).
No comprovante, a timeline usa os nomes das partes nos títulos. A via assinada da própria parte fica em GET .../contract, disponível depois da liberação.