Developers

Pedidos e idempotência

Criar uma ordem bloqueia a taxa e atribui um endereço de depósito. É o único lugar onde um erro de integração move dinheiro: idempotência não é uma conveniência ali.

Contrato publicado, ainda não aberto

Esses endpoints não estão expostos hoje. Eles são documentados para que você possa construir sua integração antecipadamente; sua forma está definida, e qualquer mudança significativa passará por uma nova versão e uma entrada no changelog.

POST/api/v1/ordersPublished contract, not open

Criar uma ordem

Bloqueia a taxa e retorna um endereço de depósito dedicado. A ordem carrega o detalhamento como bloqueado: é reproduzível, o que permite reconstruir o preço exato aplicado mesmo meses depois. O cabeçalho Idempotency-Key é obrigatório.

Autenticação: Authorization: Bearer … Ver autenticação

Parâmetros

Parâmetros
Campo	Tipo	Descrição
`quoteId`obrigatório	string	Identificador da cotação aceita.
`beneficiary`obrigatório	object	Campos impostos pelo esquema do canal. O nome deve corresponder à identidade verificada: sem pagamentos a terceiros.
`networkId`obrigatório	string	Rede na qual o depósito será enviado. Ela determina o endereço retornado e, em algumas redes, o memo obrigatório.

Solicitaçãobash

curl -sS -X POST https://fiatside.com/api/v1/orders \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "qt_01J9Z...",
    "networkId": "tron",
    "beneficiary": {
      "railId": "sepa_instant",
      "beneficiaryName": "Camille Dupont",
      "iban": "FR7630001007941234567890185"
    }
  }'

Resposta — contrato publicadojson

{
  "reference": "K7Q4-M2XB",
  "state": "AWAITING_DEPOSIT",
  "deposit": {
    "asset": "USDT",
    "network": "tron",
    "address": "T...",
    "memo": null,
    "amountBase": "1000000000",
    "expiresAt": "2026-09-02T12:41:00Z"
  },
  "payout": { "railId": "sepa_instant", "netMinor": 91228, "currency": "EUR" },
  "rateLock": { "midRate": "0.92168430", "lockedUntil": "2026-09-02T12:41:00Z" }
}

O memo é nulo na maioria das redes e obrigatório em XRP, Stellar e TON. Omiti-lo lá perde os fundos: trate o campo como obrigatório assim que for não nulo.

Erros possíveis: unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. Catálogo completo

GET/api/v1/orders/{reference}Published contract, not open

Ler uma ordem

Estado atual e histórico de transições com carimbo de data/hora. O histórico é a fonte da verdade: é somente de acréscimo, nunca reescrito, e é o que responde “por que minha ordem mudou para esse estado naquele momento”.

Autenticação: Authorization: Bearer … Ver autenticação

Solicitaçãobash

curl -sS https://fiatside.com/api/v1/orders/K7Q4-M2XB \
  -H 'Authorization: Bearer sk_live_...'

Resposta — contrato publicadojson

{
  "reference": "K7Q4-M2XB",
  "state": "COMPLETED",
  "transitions": [
    { "at": "2026-09-02T12:11:04Z", "from": "QUOTE_LOCKED",     "to": "AWAITING_DEPOSIT" },
    { "at": "2026-09-02T12:19:52Z", "from": "AWAITING_DEPOSIT", "to": "DEPOSIT_DETECTED" },
    { "at": "2026-09-02T12:21:10Z", "from": "CONFIRMING",       "to": "DEPOSIT_CONFIRMED" },
    { "at": "2026-09-02T12:21:44Z", "from": "PAYOUT_QUEUED",    "to": "PAYOUT_SENT" },
    { "at": "2026-09-02T12:22:03Z", "from": "PAYOUT_SENT",      "to": "COMPLETED" }
  ]
}

Erros possíveis: unauthorized, not_found. Catálogo completo

Idempotência

Uma solicitação de criação que expira na rede não informa se a ordem foi criada. Sem uma chave de idempotência, você só tem duas opções ruins: tentar novamente e arriscar duas ordens, ou não tentar e arriscar nenhuma.

Cabeçalhohttp

Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33

Uma chave por intenção

A chave identifica a intenção “criar essa ordem”, não a solicitação HTTP. Um id único do seu lado: um ID de carrinho, um UUID gerado antes da chamada, nunca um contador.

Uma repetição retorna a resposta original

Repetir a mesma chave com o mesmo corpo retorna a resposta da primeira solicitação, com o mesmo status HTTP. Isso é o que torna uma nova tentativa segura, inclusive após um timeout.

Mesma chave, corpo diferente: conflito

A resposta é um conflito explícito. Se o conteúdo mudar, a chave deve mudar: caso contrário, ninguém pode dizer qual das duas ordens repetir.

Retenção de 24 horas

Depois disso, a chave é esquecida e uma repetição criaria uma nova ordem. Tente novamente dentro da janela ou verifique o estado com o endpoint de leitura.

O memo, em redes que exigem um

Em XRP, Stellar e TON, o endereço de depósito não é suficiente: um identificador extra designa o destinatário final. É a causa mais cara de incidentes em uma integração de saída.

Um depósito sem seu memo é um depósito perdido

O campo memo é nulo na maioria das redes e não nulo naquelas que exigem um. Trate-o como obrigatório assim que for não nulo e exiba-o com o mesmo peso que o endereço. Um depósito que chega sem seu memo em um endereço compartilhado precisa de recuperação manual, que nem sempre é bem-sucedida.

Estados da ordem

Os estados abaixo são os que sua integração pode observar. As transições são registradas com timestamp e anexadas, nunca reescritas: o histórico responde “por que minha ordem mudou para esse estado naquele momento”.

Estados da ordem
Estado	O que significa
`QUOTE_LOCKED`	A taxa está congelada. A ordem aguarda detalhes do beneficiário ou verificação de identidade.
`AWAITING_DEPOSIT`	O endereço de depósito é atribuído e a janela de depósito está em execução. Esse é o único momento para enviar fundos.
`DEPOSIT_DETECTED`	Uma transação recebida é vista na rede, ainda não confirmada. Tranquilize o usuário, não entregue nada.
`CONFIRMING`	As confirmações estão se acumulando. O número necessário depende da rede, não do valor.
`DEPOSIT_CONFIRMED`	O depósito está garantido. Regras de conformidade e reajuste são avaliadas a partir daqui.
`UNDERPAID`	O valor recebido está abaixo do esperado além da tolerância. Três resultados: completar, continuar com o valor recebido ou ser reembolsado.
`OVERPAID`	O valor recebido excede o esperado. O valor inicial permanece na taxa bloqueada, o excedente é tratado separadamente.
`PAGAMENTO_NA_FILA`	A transferência está na fila. A fila garante que um pagamento seja enviado uma vez, mesmo que vários workers disparem em paralelo.
`PAGAMENTO_ENVIADO`	A transferência saiu pelo canal. Enviado não é recebido: o atraso final depende do banco do beneficiário.
`CONCLUÍDO`	A liquidação é confirmada pelo canal. Estado terminal.
`FALHA_NO_PAGAMENTO`	O canal rejeitou ou devolveu a transferência. Sem nova tentativa automática: a causa está quase sempre nos detalhes.
`REEMBOLSADO`	Fundos devolvidos ao endereço de origem, líquidos de taxas de rede. Estado terminal.