Documentação da API
RateON Exchange API v1
Esta documentação explica como integrar o serviço de câmbio da RateON em uma wallet, plataforma de monitoramento, aplicação ou serviço parceiro. A API permite obter direções de câmbio, calcular valores, criar ordens e acompanhar seus status.
https://rateon.io/api/userapi/v1/{method}
Direções de câmbio
Criação de ordens
Acompanhamento de status
Formato do endpoint
https://rateon.io/api/userapi/v1/{method}
Content type
Para os parâmetros no corpo da solicitação, recomenda-se usar application/x-www-form-urlencoded.
curl -X POST "https://rateon.io/api/userapi/v1/test"
-H "API-LOGIN: YOUR_API_LOGIN"
-H "API-KEY: YOUR_API_KEY"
-H "API-LANG: en_US"
| Header | Obrigatório | Descrição |
|---|---|---|
API-LOGIN | Sim | API login emitido para sua conta de integração. |
API-KEY | Sim | Chave API privada emitida para sua conta de integração. |
API-LANG | Não | Idioma forçado da resposta. Exemplos: en_US, ru_RU. |
Carregar moedas e direções
Chame get_direction_currencies e get_directions para exibir os pares de câmbio disponíveis.
Obter detalhes da direção
Chame get_direction para obter taxa, reserva, limites, comissões e campos obrigatórios.
Calcular o valor
Chame get_calc imediatamente antes da criação da ordem para calcular os valores atuais de envio e recebimento.
Criar e acompanhar a ordem
Chame create_bid e depois use bid_info, get_exchanges ou callbacks para acompanhar o status.
1. Criar seleção de par
Use get_direction_currencies e get_directions para obter moedas, pares e direction_id.
2. Exibir campos dinâmicos
Use get_direction para exibir os campos obrigatórios give_fields, get_fields e dir_fields.
3. Calcular antes de enviar
Use get_calc logo antes de criar a ordem para mostrar o valor atual e detectar possíveis alterações.
4. Criar ordem e salvar IDs
Use create_bid e salve os valores retornados id, hash, status e os dados da ação de pagamento.
5. Acompanhar status
Use callback_url para notificações push e depois verifique o status por bid_info ou get_exchanges.
6. Respeitar ações da API
Chame pay_bid e cancel_bid somente se o valor retornado em api_actions permitir explicitamente a ação via API.
| Método | Finalidade | Uso típico |
|---|---|---|
test | Verifica o acesso à API. | Use primeiro para verificar credentials e a IP allowlist. |
get_direction_currencies | Retorna as moedas disponíveis para câmbio. | Criar seletores de moedas. |
get_directions | Retorna as direções de câmbio disponíveis. | Criar a lista de pares e obter direction_id. |
get_direction | Retorna informações detalhadas sobre uma direção. | Mostrar taxa, limites, reserva e campos obrigatórios. |
get_calc | Calcula o valor do câmbio. | Mostrar o valor atual antes de criar a ordem. |
create_bid | Cria uma ordem de câmbio. | Enviar a solicitação final de câmbio. |
bid_info | Retorna informações de pagamento e status de uma ordem criada via API. | Verificar por id ou hash. |
get_exchanges | Retorna ordens criadas pela chave API atual. | Mostrar histórico de ordens ou sincronizar status. |
pay_bid | Marca uma ordem como paga quando permitido. | Use somente se api_actions.pay = api. |
cancel_bid | Cancela uma ordem quando permitido. | Use somente se api_actions.cancel = api. |
Parâmetros da solicitação
Não há parâmetros obrigatórios.
Parâmetros opcionais
currency_id_give, currency_id_get.
Resposta
Retorna as moedas disponíveis para o lado de envio e recebimento. Use este método para criar seletores de moedas.
Parâmetros opcionais
currency_id_give, currency_id_get.
Resposta
Cada direção inclui direction_id, IDs das moedas de envio/recebimento, nomes das moedas e logotipos.
Parâmetro obrigatório
direction_id — ID da direção de câmbio.
Campos da resposta
Use campos de resposta como reserve, course_give, course_get, min_give, max_give, min_get, max_get, give_fields, get_fields e dir_fields.
Parâmetros obrigatórios
direction_id, calc_amount, calc_action.
Valores de calc_action
1 valor de envio, 2 valor de recebimento, 3 valor de envio com comissão, 4 valor de recebimento com comissão.
Campos da resposta
Use sum_give, sum_give_com, sum_get, sum_get_com, com_give, com_get, limites e o flag changed.
Parâmetros principais
direction_id, calc_amount, calc_action, account1, account2, campos personalizados cf1–cf99.
Parâmetros opcionais
api_id, partner_id, callback_url. Use callback_url se quiser que a RateON notifique seu servidor quando o status da ordem mudar.
Campos da resposta
Salve os valores retornados id e hash. Use status, status_title, campos de valor, instrução de pagamento e api_actions.
Parâmetros
Envie id ou hash. Use este método após callback notifications e quando o usuário abrir a tela da ordem.
Filtros opcionais
start_time, end_time, ip, id, api_id, status_history, limit, offset.
api_actions.pay
Se o valor for api, a wallet pode chamar pay_bid. Se um link ou instrução de pagamento for retornado, mostre isso ao usuário.
api_actions.cancel
Se o valor for api, a wallet pode chamar cancel_bid. Caso contrário, o cancelamento pode não estar disponível para essa ordem.
api_actions. Algumas ações podem ser processadas automaticamente por merchant modules ou não estar disponíveis para uma ordem específica.Use callbacks como notificações server-to-server de que uma ordem pode ter sido alterada. A wallet deve sempre verificar o estado final pela API antes de atualizar a interface do usuário.
Ativar callbacks
Envie callback_url ao chamar create_bid. A URL deve estar disponível via HTTPS e ser capaz de receber solicitações POST da RateON.
Receber dados do callback
O callback payload pode incluir bid_id, account1, account2 e campos personalizados da ordem cf1–cf99, dependendo da direção selecionada e dos campos da ordem.
Verificar status da ordem
Após receber um callback, chame bid_info usando o id ou hash da ordem. Se precisar sincronizar várias ordens, use get_exchanges.
Atualizar a interface da wallet
Atualize a tela da ordem somente após a verificação pela API. Isso evita alterações incorretas de status caso o callback seja atrasado, duplicado ou reenviado.
bid_info ou get_exchanges.| Erro | Possível causa | Ação recomendada |
|---|---|---|
Api disabled | Credentials incorretas ou acesso à API desativado. | Verifique API-LOGIN, API-KEY, acesso à API e IP allowlist. |
Empty response | Os dados solicitados não foram encontrados ou os parâmetros estão incorretos. | Verifique os parâmetros obrigatórios e IDs. |
No bid exists | A ordem solicitada não existe. | Verifique o id ou hash da ordem. |
Method not supported | O método API selecionado não está habilitado para esta chave API. | Solicite acesso ao método necessário. |
Direction not found | A direção de câmbio solicitada não está disponível via API. | Verifique a disponibilidade da direção e as permissões da API. |
FAQ
get_calc imediatamente antes de create_bid para calcular o valor atual do câmbio.bid_info para uma ordem, get_exchanges para o histórico de ordens ou envie callback_url ao criar uma ordem.Pronto para a integração?
Envie seu caso de uso, os métodos API necessários e os IPs dos seus servidores. Prepararemos as credentials e ajudaremos com a primeira solicitação de teste.
Entrar em contato com o suporte