# Visão geral (/br/) ## Comece por aqui ### Integração ### Conecte sua aplicação Entenda a autenticação, escolha uma chave de Sandbox e explore os exemplos de requisição e resposta na Referência da API. Mantenha a chave secreta no backend da sua aplicação. [https://api.raims.com](https://api.raims.com) [Começar integração](/br/integracoes/autenticacao) [SDKs oficiais](/br/integracoes/sdks) · [Chaves de API](/br/integracoes/chaves-api) · [Referência da API](/br/api) ### Pagamentos ### Receba com Pix e boleto Conheça os meios de pagamento e configure o checkout. Para integrar pela API, veja como criar uma cobrança e consultar seus dados de pagamento. [Criar sua primeira cobrança](/br/api/charges/overview) [Meios de pagamento](/br/meios-de-pagamento) · [Checkout](/br/checkout#formas-de-pagamento) ### Conta e equipe ### Organize o acesso da equipe Confira os convites e as permissões antes de conceder acesso à sua conta. Use os guias financeiros para entender as condições e o acompanhamento dos saques. [Revisar permissões](/br/usuarios-e-permissoes) [Saques](/br/financeiro/saques) · [Saques automáticos](/br/financeiro/saques-automaticos) ## Use a documentação com IA Copie um prompt para usar esta página como contexto no seu agente de IA. ### Abra no seu agente de IA ## Guias por área - [Autenticação](/br/integracoes/autenticacao): Configure o header Bearer e escolha a chave da empresa e do ambiente. - [Chaves de API](/br/integracoes/chaves-api): Autenticação, ambientes, armazenamento seguro e restrições de IP. - [Webhooks](/br/integracoes/webhooks): Cadastro, eventos, assinatura e proteção do segredo. - [Saques](/br/financeiro/saques): Saldo disponível, conta de destino, limites, tarifa e acompanhamento. - [Saques automáticos](/br/financeiro/saques-automaticos): Valor mínimo, horário, tarifa e próxima execução. - [Meios de pagamento](/br/meios-de-pagamento): Pix, boleto e os códigos usados nas cobranças da API. - [Checkout](/br/checkout#formas-de-pagamento): Formas de pagamento padrão e aparência do checkout. - [Usuários e permissões](/br/usuarios-e-permissoes): Convites, administração da equipe e alcance de cada permissão. - [Rate limiting](/br/integracoes/rate-limiting): Limites de requisições, concorrência e tratamento de HTTP 429. - [Tipos e identificadores](/br/tipos-e-identificadores): Formatos e valores usados na API pública e nos recursos da Raims. **Disponibilidade no seu acesso** As opções dependem das permissões, do ambiente e da situação da conta. # Configurar agentes (/br/agentes) ## Escolha seu agente Selecione um agente para ver as instruções de configuração do seu projeto. * [Claude Code](/br/agentes/claude-code) * [Codex](/br/agentes/codex) * [Cursor](/br/agentes/cursor) * [GitHub Copilot](/br/agentes/github-copilot) * [OpenCode](/br/agentes/opencode) * [Vibe](/br/agentes/vibe) * [Devin](/br/agentes/devin) * [Visual Studio Code](/br/agentes/visual-studio-code) * [Command Code](/br/agentes/command-code) * [Bionic](/br/agentes/bionic) ## Dúvidas frequentes ### Preciso de uma chave Raims para configurar o contexto? A documentação é pública e pode ser consultada sem uma chave. Para enviar requisições, sua aplicação precisa de uma [chave de API](/br/integracoes/chaves-api) da empresa e do ambiente desejados. Guarde o segredo no backend. ### Por onde começar a integração? Consulte a [autenticação](/br/integracoes/autenticacao) e a [Referência da API](/br/api). Comece em Sandbox e revise os exemplos gerados antes de executar uma requisição. Os prompts destes guias preparam um plano e não solicitam credenciais reais no chat. ### E se o agente não conseguir ler um link? Abra o guia no navegador e forneça o trecho público relevante como contexto. O [índice](https://docs.raims.com/llms.txt) e a [documentação consolidada](https://docs.raims.com/llms-full.txt) também podem ser consultados pelo agente quando ele tiver acesso à rede. # Bionic + Raims (/br/agentes/bionic) ## Início rápido ### Prepare o agente Instale o Bionic a partir da [documentação oficial da LM Studio](https://lmstudio.ai/docs/bionic). Abra o aplicativo e crie um **Project** para sua integração. ### Abra seu projeto Ative **Allow coding**, escolha **Choose a folder for Bionic to work in** e selecione a raiz da sua aplicação. Crie o projeto e escolha o modelo da sessão. ### Adicione a documentação Peça ao agente para ler o [índice da documentação Raims](https://docs.raims.com/llms.txt) e abrir os guias relevantes. O [llms-full.txt](https://docs.raims.com/llms-full.txt) reúne o conteúdo completo. Comece por [autenticação](/br/integracoes/autenticacao) e [cobranças](/br/api/charges/overview). ### Experimente um prompt ```text Leia https://docs.raims.com/llms.txt e os guias de autenticação e cobranças. Analise o backend desta aplicação e proponha um plano para consultar uma cobrança existente em Sandbox com GET /v1/charges/{id}. Prepare um exemplo com a chave em configuração protegida do servidor. Não envie requisições nem use credenciais reais. Apresente as fontes e os arquivos que pretende alterar antes de editar. ``` ## Contexto do projeto Salve o texto abaixo em um arquivo de referência, como `raims-context.md`, e adicione-o aos arquivos do projeto Bionic. Esses arquivos são compartilhados entre as sessões do projeto. Ao iniciar uma conversa, peça ao agente para ler esse arquivo antes de planejar a integração. ```md # Integração Raims - Consulte https://docs.raims.com/llms.txt antes de escolher endpoints e campos. - Use https://docs.raims.com/llms-full.txt para a documentação completa. - URL base da API: https://api.raims.com. - Nos exemplos de instalação de produtos Raims, obtenha a versão estável mais recente pelo gerenciador de pacotes (`latest` quando disponível). - Prepare exemplos para Sandbox, com autenticação Bearer no backend. - Mantenha a chave em configuração protegida do servidor. Não coloque segredos no código, em prompts, logs ou aplicações de navegador. - Explique o plano e peça autorização antes de enviar requisições à API. ``` ## Verificar a configuração Peça ao agente para indicar os guias lidos, a URL base e o ponto do backend em que a chave será carregada. Ele deve preparar o plano e o exemplo sem solicitar uma credencial real no chat. Ler a documentação não autentica a aplicação. As requisições usam uma [chave de API Raims](/br/integracoes/chaves-api) da empresa e do ambiente desejados. ## Problemas comuns ### A nova sessão não considerou o contexto Abra a sessão no mesmo Project, confira os arquivos do projeto e peça explicitamente a leitura de `raims-context.md`. Confirme também a pasta de código selecionada. ### O agente não consegue abrir a documentação Abra o guia relevante no navegador e forneça o trecho público como contexto. Peça ao agente para apontar o que falta antes de sugerir código. ### O exemplo usa a autenticação errada Peça ao agente para revisar o guia de autenticação. O backend envia a chave Raims com Bearer; uma credencial do provedor de IA não a substitui. ## Fontes oficiais * [Criar um projeto no Bionic](https://lmstudio.ai/docs/bionic/quick-start) * [Trabalhar com código](https://lmstudio.ai/docs/bionic/agent/code-project) * [Projetos e sessões](https://lmstudio.ai/docs/bionic/projects-and-sessions) # Claude Code + Raims (/br/agentes/claude-code) ## Início rápido ### Prepare o agente Instale o Claude Code seguindo o [início rápido oficial](https://code.claude.com/docs/en/quickstart), com as instruções do seu sistema operacional. Abra uma sessão e conclua o login solicitado pelo agente. ### Abra seu projeto Abra um terminal na raiz da aplicação que você vai integrar à Raims e execute: ```bash claude ``` ### Adicione a documentação Peça ao agente para ler o [índice da documentação Raims](https://docs.raims.com/llms.txt) e abrir os guias relevantes. O [llms-full.txt](https://docs.raims.com/llms-full.txt) reúne o conteúdo completo. Comece por [autenticação](/br/integracoes/autenticacao) e [cobranças](/br/api/charges/overview). ### Experimente um prompt ```text Leia https://docs.raims.com/llms.txt e os guias de autenticação e cobranças. Analise o backend desta aplicação e proponha um plano para consultar uma cobrança existente em Sandbox com GET /v1/charges/{id}. Prepare um exemplo com a chave em configuração protegida do servidor. Não envie requisições nem use credenciais reais. Apresente as fontes e os arquivos que pretende alterar antes de editar. ``` ## Contexto do projeto Acrescente as instruções abaixo ao `CLAUDE.md` na raiz do seu projeto. Preserve as orientações que já estiverem no arquivo. O Claude Code carrega esse arquivo como contexto nas sessões do projeto. ```md # Integração Raims - Consulte https://docs.raims.com/llms.txt antes de escolher endpoints e campos. - Use https://docs.raims.com/llms-full.txt para a documentação completa. - URL base da API: https://api.raims.com. - Nos exemplos de instalação de produtos Raims, obtenha a versão estável mais recente pelo gerenciador de pacotes (`latest` quando disponível). - Prepare exemplos para Sandbox, com autenticação Bearer no backend. - Mantenha a chave em configuração protegida do servidor. Não coloque segredos no código, em prompts, logs ou aplicações de navegador. - Explique o plano e peça autorização antes de enviar requisições à API. ``` ## Verificar a configuração Peça ao agente para indicar os guias lidos, a URL base e o ponto do backend em que a chave será carregada. Ele deve preparar o plano e o exemplo sem solicitar uma credencial real no chat. Ler a documentação não autentica a aplicação. As requisições usam uma [chave de API Raims](/br/integracoes/chaves-api) da empresa e do ambiente desejados. ## Problemas comuns ### O agente não encontrou as instruções Confira se abriu o terminal na pasta correta e se `CLAUDE.md` está na raiz desse projeto. Peça ao Claude Code para ler o arquivo antes de continuar. ### O agente não consegue abrir a documentação Abra o guia relevante no navegador e forneça o trecho público como contexto. Peça ao agente para apontar o que falta antes de sugerir código. ### O exemplo usa a autenticação errada Peça ao agente para revisar o guia de autenticação. O backend envia a chave Raims com Bearer; uma credencial do provedor de IA não a substitui. ## Fontes oficiais * [Início rápido do Claude Code](https://code.claude.com/docs/en/quickstart) * [Instruções em CLAUDE.md](https://code.claude.com/docs/en/memory) # Codex + Raims (/br/agentes/codex) ## Início rápido ### Instale o Codex Com Node.js e npm disponíveis, instale o CLI: ```bash npm install -g @openai/codex ``` O [guia oficial do CLI](https://learn.chatgpt.com/docs/codex/cli) apresenta também os instaladores de Windows, macOS e Linux. Se preferir o aplicativo, o editor ou a nuvem, siga o [início rápido da OpenAI](https://learn.chatgpt.com/docs/quickstart). ### Abra a pasta da sua aplicação Na raiz do projeto que você pretende integrar à Raims, execute: ```bash codex ``` Conclua a autenticação indicada pelo Codex. A conta do agente e a chave da API Raims têm finalidades diferentes. ### Forneça o contexto da Raims Peça ao Codex para ler o [índice da documentação](https://docs.raims.com/llms.txt) e localizar os guias de [autenticação](/br/integracoes/autenticacao) e [cobranças](/br/api/charges/overview). O [conteúdo consolidado](https://docs.raims.com/llms-full.txt) também pode ser usado como referência. ### Experimente um prompt ```text Leia https://docs.raims.com/llms.txt e os guias de autenticação e cobranças. Analise o backend desta aplicação e proponha um plano para consultar uma cobrança existente em Sandbox com GET /v1/charges/{id}. Prepare um exemplo com a chave em configuração protegida do servidor. Não envie requisições nem use credenciais reais. Apresente as fontes e os arquivos que pretende alterar antes de editar. ``` ## Contexto do projeto Acrescente estas orientações ao `AGENTS.md` na raiz da sua aplicação, preservando as instruções existentes. O Codex lê os arquivos `AGENTS.md` ao iniciar uma sessão e considera também instruções mais específicas dos diretórios. ```md # Integração Raims - Consulte https://docs.raims.com/llms.txt antes de escolher endpoints e campos. - Use https://docs.raims.com/llms-full.txt para a documentação completa. - URL base da API: https://api.raims.com. - Nos exemplos de instalação de produtos Raims, obtenha a versão estável mais recente pelo gerenciador de pacotes (`latest` quando disponível). - Prepare exemplos para Sandbox, com autenticação Bearer no backend. - Mantenha a chave em configuração protegida do servidor. Não coloque segredos no código, em prompts, logs ou aplicações de navegador. - Explique o plano e peça autorização antes de enviar requisições à API. ``` Depois de salvar, inicie uma nova sessão no projeto para carregar as instruções. ## Verificar a configuração Peça ao Codex para resumir as instruções ativas, indicar os guias consultados e explicar onde a aplicação carregará a chave. Confira o plano e o código antes de autorizar um teste. Ler a documentação não autentica a aplicação. As requisições usam uma [chave de API Raims](/br/integracoes/chaves-api) da empresa e do ambiente desejados, armazenada na parte privada do sistema. ## Problemas comuns ### O Codex não leu as instruções Confira se a sessão foi aberta na pasta correta, salve `AGENTS.md` e inicie outra sessão. Peça ao Codex para informar quais instruções carregou. ### A documentação não abre no agente Confira as permissões de rede do agente. Você também pode fornecer o trecho público do guia como contexto e pedir que o Codex identifique as informações que ainda faltam. ### O exemplo usa uma chave do provedor de IA Peça a revisão da autenticação. A aplicação usa a chave Raims no header Bearer; as credenciais usadas para acessar o Codex não a substituem. ## Fontes oficiais * [Codex CLI](https://learn.chatgpt.com/docs/codex/cli) * [Início rápido](https://learn.chatgpt.com/docs/quickstart) * [Instruções em AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) # Command Code + Raims (/br/agentes/command-code) ## Início rápido ### Prepare o agente Confira os requisitos e instale o agente pelo [início rápido oficial](https://commandcode.ai/docs/quickstart). A instalação com npm usa: ```bash npm i -g command-code@latest ``` ### Abra seu projeto Na pasta da sua aplicação, execute o comando abaixo e conclua o login do agente. No Windows nativo, o alias curto é `cmdc`. ```bash command-code ``` ### Adicione a documentação Peça ao agente para ler o [índice da documentação Raims](https://docs.raims.com/llms.txt) e abrir os guias relevantes. O [llms-full.txt](https://docs.raims.com/llms-full.txt) reúne o conteúdo completo. Comece por [autenticação](/br/integracoes/autenticacao) e [cobranças](/br/api/charges/overview). ### Experimente um prompt ```text Leia https://docs.raims.com/llms.txt e os guias de autenticação e cobranças. Analise o backend desta aplicação e proponha um plano para consultar uma cobrança existente em Sandbox com GET /v1/charges/{id}. Prepare um exemplo com a chave em configuração protegida do servidor. Não envie requisições nem use credenciais reais. Apresente as fontes e os arquivos que pretende alterar antes de editar. ``` ## Contexto do projeto Acrescente o conteúdo abaixo ao `AGENTS.md` na raiz da aplicação. O Command Code usa esse arquivo como memória do projeto. O comando `/memory` permite abrir o arquivo para edição dentro da sessão. ```md # Integração Raims - Consulte https://docs.raims.com/llms.txt antes de escolher endpoints e campos. - Use https://docs.raims.com/llms-full.txt para a documentação completa. - URL base da API: https://api.raims.com. - Nos exemplos de instalação de produtos Raims, obtenha a versão estável mais recente pelo gerenciador de pacotes (`latest` quando disponível). - Prepare exemplos para Sandbox, com autenticação Bearer no backend. - Mantenha a chave em configuração protegida do servidor. Não coloque segredos no código, em prompts, logs ou aplicações de navegador. - Explique o plano e peça autorização antes de enviar requisições à API. ``` ## Verificar a configuração Peça ao agente para indicar os guias lidos, a URL base e o ponto do backend em que a chave será carregada. Ele deve preparar o plano e o exemplo sem solicitar uma credencial real no chat. Ler a documentação não autentica a aplicação. As requisições usam uma [chave de API Raims](/br/integracoes/chaves-api) da empresa e do ambiente desejados. ## Problemas comuns ### O comando abriu o interpretador do Windows Use `command-code` ou o alias `cmdc` no Windows nativo. O nome `cmd` também identifica o interpretador de comandos do Windows. ### O agente não consegue abrir a documentação Abra o guia relevante no navegador e forneça o trecho público como contexto. Peça ao agente para apontar o que falta antes de sugerir código. ### O exemplo usa a autenticação errada Peça ao agente para revisar o guia de autenticação. O backend envia a chave Raims com Bearer; uma credencial do provedor de IA não a substitui. ## Fontes oficiais * [Instalar e iniciar o Command Code](https://commandcode.ai/docs/quickstart) * [Memória do projeto](https://commandcode.ai/docs/memory) # Cursor + Raims (/br/agentes/cursor) ## Início rápido ### Prepare o agente Instale o Cursor pelo [guia oficial](https://cursor.com/docs/get-started/quickstart) e entre na sua conta. ### Abra seu projeto Abra a pasta da aplicação que vai consumir a API Raims e inicie uma conversa no painel Agent. Confirme que a pasta selecionada contém o código do seu backend. ### Adicione a documentação Peça ao agente para ler o [índice da documentação Raims](https://docs.raims.com/llms.txt) e abrir os guias relevantes. O [llms-full.txt](https://docs.raims.com/llms-full.txt) reúne o conteúdo completo. Comece por [autenticação](/br/integracoes/autenticacao) e [cobranças](/br/api/charges/overview). ### Experimente um prompt ```text Leia https://docs.raims.com/llms.txt e os guias de autenticação e cobranças. Analise o backend desta aplicação e proponha um plano para consultar uma cobrança existente em Sandbox com GET /v1/charges/{id}. Prepare um exemplo com a chave em configuração protegida do servidor. Não envie requisições nem use credenciais reais. Apresente as fontes e os arquivos que pretende alterar antes de editar. ``` ## Contexto do projeto Na paleta de comandos, selecione **New Cursor Rule**, dê o nome `raims` e escolha **Always Apply**. O Cursor salva a regra como `.cursor/rules/raims.mdc`. Use o conteúdo abaixo no corpo da regra; mantenha os metadados criados pelo editor. ```md # Integração Raims - Consulte https://docs.raims.com/llms.txt antes de escolher endpoints e campos. - Use https://docs.raims.com/llms-full.txt para a documentação completa. - URL base da API: https://api.raims.com. - Nos exemplos de instalação de produtos Raims, obtenha a versão estável mais recente pelo gerenciador de pacotes (`latest` quando disponível). - Prepare exemplos para Sandbox, com autenticação Bearer no backend. - Mantenha a chave em configuração protegida do servidor. Não coloque segredos no código, em prompts, logs ou aplicações de navegador. - Explique o plano e peça autorização antes de enviar requisições à API. ``` ## Verificar a configuração Peça ao agente para indicar os guias lidos, a URL base e o ponto do backend em que a chave será carregada. Ele deve preparar o plano e o exemplo sem solicitar uma credencial real no chat. Ler a documentação não autentica a aplicação. As requisições usam uma [chave de API Raims](/br/integracoes/chaves-api) da empresa e do ambiente desejados. ## Problemas comuns ### A regra não aparece no contexto Confira se a regra foi salva em `.cursor/rules` com a extensão `.mdc` e está marcada como Always Apply. Abra uma conversa no mesmo projeto. ### O agente não consegue abrir a documentação Abra o guia relevante no navegador e forneça o trecho público como contexto. Peça ao agente para apontar o que falta antes de sugerir código. ### O exemplo usa a autenticação errada Peça ao agente para revisar o guia de autenticação. O backend envia a chave Raims com Bearer; uma credencial do provedor de IA não a substitui. ## Fontes oficiais * [Início rápido do Cursor](https://cursor.com/docs/get-started/quickstart) * [Regras do projeto](https://cursor.com/docs/rules) # Devin + Raims (/br/agentes/devin) ## Início rápido ### Prepare o agente Acesse o [Devin](https://app.devin.ai) com sua conta e siga o [guia da primeira sessão](https://docs.devin.ai/get-started/first-run) para conectar e preparar o repositório da sua aplicação. ### Abra seu projeto Selecione o repositório que vai consumir a API Raims. Comece em **Ask** para investigar o código e preparar o plano antes de iniciar a implementação em **Agent**. ### Adicione a documentação Peça ao agente para ler o [índice da documentação Raims](https://docs.raims.com/llms.txt) e abrir os guias relevantes. O [llms-full.txt](https://docs.raims.com/llms-full.txt) reúne o conteúdo completo. Comece por [autenticação](/br/integracoes/autenticacao) e [cobranças](/br/api/charges/overview). ### Experimente um prompt ```text Leia https://docs.raims.com/llms.txt e os guias de autenticação e cobranças. Analise o backend desta aplicação e proponha um plano para consultar uma cobrança existente em Sandbox com GET /v1/charges/{id}. Prepare um exemplo com a chave em configuração protegida do servidor. Não envie requisições nem use credenciais reais. Apresente as fontes e os arquivos que pretende alterar antes de editar. ``` ## Contexto do projeto Inclua o texto abaixo no `AGENTS.md` da raiz do seu repositório e disponibilize essa versão para a sessão do Devin. O agente procura esse arquivo antes de começar a programar. Preserve as instruções de build e as convenções da sua aplicação. ```md # Integração Raims - Consulte https://docs.raims.com/llms.txt antes de escolher endpoints e campos. - Use https://docs.raims.com/llms-full.txt para a documentação completa. - URL base da API: https://api.raims.com. - Nos exemplos de instalação de produtos Raims, obtenha a versão estável mais recente pelo gerenciador de pacotes (`latest` quando disponível). - Prepare exemplos para Sandbox, com autenticação Bearer no backend. - Mantenha a chave em configuração protegida do servidor. Não coloque segredos no código, em prompts, logs ou aplicações de navegador. - Explique o plano e peça autorização antes de enviar requisições à API. ``` ## Verificar a configuração Peça ao agente para indicar os guias lidos, a URL base e o ponto do backend em que a chave será carregada. Ele deve preparar o plano e o exemplo sem solicitar uma credencial real no chat. Ler a documentação não autentica a aplicação. As requisições usam uma [chave de API Raims](/br/integracoes/chaves-api) da empresa e do ambiente desejados. ## Problemas comuns ### A sessão não encontrou o arquivo de contexto Confira o repositório e a versão usados pela sessão. O `AGENTS.md` precisa existir nessa versão, com as orientações de integração próximas do início. ### O agente não consegue abrir a documentação Abra o guia relevante no navegador e forneça o trecho público como contexto. Peça ao agente para apontar o que falta antes de sugerir código. ### O exemplo usa a autenticação errada Peça ao agente para revisar o guia de autenticação. O backend envia a chave Raims com Bearer; uma credencial do provedor de IA não a substitui. ## Fontes oficiais * [Primeira sessão no Devin](https://docs.devin.ai/get-started/first-run) * [AGENTS.md no Devin](https://docs.devin.ai/onboard-devin/agents-md) # GitHub Copilot + Raims (/br/agentes/github-copilot) ## Início rápido ### Prepare o agente Siga a [instalação oficial do GitHub Copilot](https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/set-up-copilot/install-copilot-extension) para o seu editor e entre na conta GitHub com acesso ao Copilot. Neste guia, os exemplos de configuração usam o VS Code. ### Abra seu projeto Abra no VS Code a pasta da aplicação que vai integrar a Raims. Abra o Chat do Copilot e selecione o agente para trabalhar com o código do projeto. ### Adicione a documentação Peça ao agente para ler o [índice da documentação Raims](https://docs.raims.com/llms.txt) e abrir os guias relevantes. O [llms-full.txt](https://docs.raims.com/llms-full.txt) reúne o conteúdo completo. Comece por [autenticação](/br/integracoes/autenticacao) e [cobranças](/br/api/charges/overview). ### Experimente um prompt ```text Leia https://docs.raims.com/llms.txt e os guias de autenticação e cobranças. Analise o backend desta aplicação e proponha um plano para consultar uma cobrança existente em Sandbox com GET /v1/charges/{id}. Prepare um exemplo com a chave em configuração protegida do servidor. Não envie requisições nem use credenciais reais. Apresente as fontes e os arquivos que pretende alterar antes de editar. ``` ## Contexto do projeto Crie ou complemente `.github/copilot-instructions.md` na raiz do seu repositório. Esse arquivo fornece as instruções gerais para as sessões do Copilot. Inclua o texto abaixo junto das convenções da sua aplicação. ```md # Integração Raims - Consulte https://docs.raims.com/llms.txt antes de escolher endpoints e campos. - Use https://docs.raims.com/llms-full.txt para a documentação completa. - URL base da API: https://api.raims.com. - Nos exemplos de instalação de produtos Raims, obtenha a versão estável mais recente pelo gerenciador de pacotes (`latest` quando disponível). - Prepare exemplos para Sandbox, com autenticação Bearer no backend. - Mantenha a chave em configuração protegida do servidor. Não coloque segredos no código, em prompts, logs ou aplicações de navegador. - Explique o plano e peça autorização antes de enviar requisições à API. ``` ## Verificar a configuração Peça ao agente para indicar os guias lidos, a URL base e o ponto do backend em que a chave será carregada. Ele deve preparar o plano e o exemplo sem solicitar uma credencial real no chat. Ler a documentação não autentica a aplicação. As requisições usam uma [chave de API Raims](/br/integracoes/chaves-api) da empresa e do ambiente desejados. ## Problemas comuns ### As instruções não foram consideradas Confira se `.github/copilot-instructions.md` pertence à pasta aberta no VS Code. Consulte as configurações de instruções do editor e peça ao agente para ler o arquivo explicitamente. ### O agente não consegue abrir a documentação Abra o guia relevante no navegador e forneça o trecho público como contexto. Peça ao agente para apontar o que falta antes de sugerir código. ### O exemplo usa a autenticação errada Peça ao agente para revisar o guia de autenticação. O backend envia a chave Raims com Bearer; uma credencial do provedor de IA não a substitui. ## Fontes oficiais * [Instalar o GitHub Copilot no editor](https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/set-up-copilot/install-copilot-extension) * [Instruções do Copilot no VS Code](https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/customize-copilot/configure-custom-instructions/add-repository-instructions-in-your-ide) # OpenCode + Raims (/br/agentes/opencode) ## Início rápido ### Prepare o agente Escolha a instalação para seu sistema no [guia oficial do OpenCode](https://opencode.ai/docs/). Configure o provedor de IA pelo fluxo indicado na documentação. A credencial desse provedor é separada da chave de API Raims. ### Abra seu projeto Abra um terminal na pasta da sua aplicação e inicie o agente: ```bash opencode ``` ### Adicione a documentação Peça ao agente para ler o [índice da documentação Raims](https://docs.raims.com/llms.txt) e abrir os guias relevantes. O [llms-full.txt](https://docs.raims.com/llms-full.txt) reúne o conteúdo completo. Comece por [autenticação](/br/integracoes/autenticacao) e [cobranças](/br/api/charges/overview). ### Experimente um prompt ```text Leia https://docs.raims.com/llms.txt e os guias de autenticação e cobranças. Analise o backend desta aplicação e proponha um plano para consultar uma cobrança existente em Sandbox com GET /v1/charges/{id}. Prepare um exemplo com a chave em configuração protegida do servidor. Não envie requisições nem use credenciais reais. Apresente as fontes e os arquivos que pretende alterar antes de editar. ``` ## Contexto do projeto Adicione o conteúdo abaixo ao `AGENTS.md` na raiz do seu projeto. O OpenCode usa esse arquivo para receber instruções do repositório. Se precisar gerar uma estrutura inicial, o comando `/init` analisa o projeto; revise o arquivo resultante. ```md # Integração Raims - Consulte https://docs.raims.com/llms.txt antes de escolher endpoints e campos. - Use https://docs.raims.com/llms-full.txt para a documentação completa. - URL base da API: https://api.raims.com. - Nos exemplos de instalação de produtos Raims, obtenha a versão estável mais recente pelo gerenciador de pacotes (`latest` quando disponível). - Prepare exemplos para Sandbox, com autenticação Bearer no backend. - Mantenha a chave em configuração protegida do servidor. Não coloque segredos no código, em prompts, logs ou aplicações de navegador. - Explique o plano e peça autorização antes de enviar requisições à API. ``` ## Verificar a configuração Peça ao agente para indicar os guias lidos, a URL base e o ponto do backend em que a chave será carregada. Ele deve preparar o plano e o exemplo sem solicitar uma credencial real no chat. Ler a documentação não autentica a aplicação. As requisições usam uma [chave de API Raims](/br/integracoes/chaves-api) da empresa e do ambiente desejados. ## Problemas comuns ### O agente usa o projeto errado Inicie `opencode` dentro da pasta da aplicação e confira o `AGENTS.md` desse repositório. Mantenha as instruções da integração junto das convenções locais. ### O agente não consegue abrir a documentação Abra o guia relevante no navegador e forneça o trecho público como contexto. Peça ao agente para apontar o que falta antes de sugerir código. ### O exemplo usa a autenticação errada Peça ao agente para revisar o guia de autenticação. O backend envia a chave Raims com Bearer; uma credencial do provedor de IA não a substitui. ## Fontes oficiais * [Instalação e configuração do OpenCode](https://opencode.ai/docs/) * [Instruções em AGENTS.md](https://opencode.ai/docs/rules/) # Vibe + Raims (/br/agentes/vibe) ## Início rápido ### Prepare o agente Instale o Vibe CLI seguindo as instruções do seu sistema no [guia oficial da Mistral](https://docs.mistral.ai/vibe/code/cli/install-setup). No primeiro acesso, conclua o assistente de login ou de configuração do provedor de IA. ### Abra seu projeto Abra um terminal na raiz da sua aplicação e execute: ```bash vibe ``` ### Adicione a documentação Peça ao agente para ler o [índice da documentação Raims](https://docs.raims.com/llms.txt) e abrir os guias relevantes. O [llms-full.txt](https://docs.raims.com/llms-full.txt) reúne o conteúdo completo. Comece por [autenticação](/br/integracoes/autenticacao) e [cobranças](/br/api/charges/overview). ### Experimente um prompt ```text Leia https://docs.raims.com/llms.txt e os guias de autenticação e cobranças. Analise o backend desta aplicação e proponha um plano para consultar uma cobrança existente em Sandbox com GET /v1/charges/{id}. Prepare um exemplo com a chave em configuração protegida do servidor. Não envie requisições nem use credenciais reais. Apresente as fontes e os arquivos que pretende alterar antes de editar. ``` ## Contexto do projeto Acrescente as instruções abaixo ao `AGENTS.md` da sua aplicação. O Vibe carrega esse arquivo nas pastas de projeto confiáveis. Confira a pasta antes de aceitar a solicitação de confiança do agente. ```md # Integração Raims - Consulte https://docs.raims.com/llms.txt antes de escolher endpoints e campos. - Use https://docs.raims.com/llms-full.txt para a documentação completa. - URL base da API: https://api.raims.com. - Nos exemplos de instalação de produtos Raims, obtenha a versão estável mais recente pelo gerenciador de pacotes (`latest` quando disponível). - Prepare exemplos para Sandbox, com autenticação Bearer no backend. - Mantenha a chave em configuração protegida do servidor. Não coloque segredos no código, em prompts, logs ou aplicações de navegador. - Explique o plano e peça autorização antes de enviar requisições à API. ``` ## Verificar a configuração Peça ao agente para indicar os guias lidos, a URL base e o ponto do backend em que a chave será carregada. Ele deve preparar o plano e o exemplo sem solicitar uma credencial real no chat. Ler a documentação não autentica a aplicação. As requisições usam uma [chave de API Raims](/br/integracoes/chaves-api) da empresa e do ambiente desejados. ## Problemas comuns ### O contexto do projeto não foi carregado Confira a pasta em que iniciou `vibe`, a presença de `AGENTS.md` e a confirmação de confiança do projeto. Consulte o guia oficial para revisar essa configuração. ### O agente não consegue abrir a documentação Abra o guia relevante no navegador e forneça o trecho público como contexto. Peça ao agente para apontar o que falta antes de sugerir código. ### O exemplo usa a autenticação errada Peça ao agente para revisar o guia de autenticação. O backend envia a chave Raims com Bearer; uma credencial do provedor de IA não a substitui. ## Fontes oficiais * [Instalar e iniciar o Vibe CLI](https://docs.mistral.ai/vibe/code/cli/install-setup) * [Instruções de projeto do Vibe](https://docs.mistral.ai/vibe/code/cli/agents) # Visual Studio Code + Raims (/br/agentes/visual-studio-code) ## Início rápido ### Prepare o agente Instale o VS Code e siga a [configuração oficial do GitHub Copilot](https://code.visualstudio.com/docs/setup/copilot). Este guia usa o Copilot no editor; conclua o login com a conta GitHub apropriada. ### Abra seu projeto Abra a pasta da aplicação no VS Code e inicie uma conversa no Chat. Use o agente do Copilot com acesso ao projeto do seu backend. ### Adicione a documentação Peça ao agente para ler o [índice da documentação Raims](https://docs.raims.com/llms.txt) e abrir os guias relevantes. O [llms-full.txt](https://docs.raims.com/llms-full.txt) reúne o conteúdo completo. Comece por [autenticação](/br/integracoes/autenticacao) e [cobranças](/br/api/charges/overview). ### Experimente um prompt ```text Leia https://docs.raims.com/llms.txt e os guias de autenticação e cobranças. Analise o backend desta aplicação e proponha um plano para consultar uma cobrança existente em Sandbox com GET /v1/charges/{id}. Prepare um exemplo com a chave em configuração protegida do servidor. Não envie requisições nem use credenciais reais. Apresente as fontes e os arquivos que pretende alterar antes de editar. ``` ## Contexto do projeto Crie ou complemente `.github/copilot-instructions.md` na raiz da aplicação. Esse é o arquivo de instruções gerais para o Copilot neste guia. Se escolher outro agente no VS Code, siga o formato de instruções documentado para ele. ```md # Integração Raims - Consulte https://docs.raims.com/llms.txt antes de escolher endpoints e campos. - Use https://docs.raims.com/llms-full.txt para a documentação completa. - URL base da API: https://api.raims.com. - Nos exemplos de instalação de produtos Raims, obtenha a versão estável mais recente pelo gerenciador de pacotes (`latest` quando disponível). - Prepare exemplos para Sandbox, com autenticação Bearer no backend. - Mantenha a chave em configuração protegida do servidor. Não coloque segredos no código, em prompts, logs ou aplicações de navegador. - Explique o plano e peça autorização antes de enviar requisições à API. ``` ## Verificar a configuração Peça ao agente para indicar os guias lidos, a URL base e o ponto do backend em que a chave será carregada. Ele deve preparar o plano e o exemplo sem solicitar uma credencial real no chat. Ler a documentação não autentica a aplicação. As requisições usam uma [chave de API Raims](/br/integracoes/chaves-api) da empresa e do ambiente desejados. ## Problemas comuns ### O agente selecionado não usa esse formato Confira qual agente está ativo no Chat. As instruções deste guia usam Copilot; Claude e Codex têm formatos próprios descritos na documentação do VS Code. ### O agente não consegue abrir a documentação Abra o guia relevante no navegador e forneça o trecho público como contexto. Peça ao agente para apontar o que falta antes de sugerir código. ### O exemplo usa a autenticação errada Peça ao agente para revisar o guia de autenticação. O backend envia a chave Raims com Bearer; uma credencial do provedor de IA não a substitui. ## Fontes oficiais * [Configurar o Copilot no VS Code](https://code.visualstudio.com/docs/setup/copilot) * [Instruções e formatos por agente](https://code.visualstudio.com/docs/agent-customization/custom-instructions) # Comece por aqui (/br/api) **Antes de testar** O console interativo desta documentação aceita somente credenciais de **Sandbox**, com prefixo `sk_test_`. Para testar, selecione ou informe uma chave de Sandbox. Consulte [Chaves de API](/br/integracoes/chaves-api) para criar e proteger sua credencial. A Referência da API reúne os endpoints, os parâmetros, as respostas e os exemplos de código da Raims. O console permite preencher os dados de uma requisição, enviá-la para teste e consultar a resposta na mesma página. Você pode escolher a linguagem do exemplo e copiar a requisição para adaptar ao seu sistema. Os exemplos acompanham os valores informados nos campos. **Preparando sua integração?** Consulte os guias de [Chaves de API](/br/integracoes/chaves-api) e [Webhooks](/br/integracoes/webhooks) para entender a configuração e os cuidados da integração. Use a Referência da API para consultar os detalhes de cada requisição durante a implementação. Para baixar ou importar o contrato e gerar um cliente no seu projeto, consulte o guia [Contrato OpenAPI](/br/api/openapi). Para interpretar os códigos dos recursos e os prefixos dos IDs, consulte o [mapa de tipos e identificadores](/br/tipos-e-identificadores), na área Guias. ## URL base A URL base da API da Raims é: ```text https://api.raims.com ``` Sandbox e Produção usam o mesmo endereço. O ambiente é definido pela credencial enviada na requisição. ## Ambientes da API Sandbox e Produção pertencem à mesma empresa, com dados e credenciais separados. A chave identifica a empresa e o ambiente da solicitação; esses valores não são escolhidos no corpo da requisição. | Ambiente | Prefixo da credencial | Uso | | -------- | --------------------- | -------------------------------------------------------------------------------------------------- | | Sandbox | `sk_test_` | Desenvolvimento, homologação e testes no console da documentação, sem movimentar dinheiro real. | | Produção | `sk_live_` | Requisições com efeitos reais na conta, enviadas pelo seu sistema fora do console da documentação. | Confira o método e o endereço completo exibidos na página de cada endpoint. Use esse endereço nos testes e nos exemplos da integração. Antes de usar Produção, confira a credencial e a configuração da sua aplicação. Para testar o pagamento aprovado ou a falha de uma cobrança sem movimentar dinheiro real, use o recurso [Simulação](/br/api/simulations/overview). Esses endpoints aceitam somente Sandbox. As demais requisições continuam nas páginas dos respectivos recursos, com a chave do ambiente de teste. ## Autenticação Consulte o guia de [Autenticação](/br/integracoes/autenticacao) para configurar os headers, escolher a chave do ambiente e revisar o acesso da integração. A API usa o header `Authorization` com o esquema HTTP Bearer: ```http Authorization: Bearer sk_test_... ``` `sk_test_...` é apenas um placeholder. No console, informe o valor completo da sua chave de Sandbox no campo **Credenciais**. O exemplo monta o header de autenticação para você. Quando você usa uma sessão do Dashboard, o seletor oferece somente chaves Sandbox cujos acessos estão dentro das suas permissões. Uma chave que aparece no gerenciador com o segredo oculto pode não estar disponível no console. Peça a uma pessoa autorizada para revisar os acessos em [Chaves de API](/br/integracoes/chaves-api#permissões-da-chave). As restrições de IP configuradas para a chave também valem nos testes. Uma origem fora das faixas autorizadas recebe `403`. Consulte [Restrições de IP](/br/integracoes/chaves-api#restrições-de-ip) antes de alterar essa configuração. O console não salva sua chave no navegador. No seu sistema, guarde o segredo no servidor responsável pela integração e não o exponha no navegador, em repositórios ou em logs. ## Como usar o console 1. Na barra lateral, escolha o endpoint que deseja testar. Confira o método, o endereço e as regras dos campos. 2. Selecione ou informe uma credencial de Sandbox em **Credenciais**. 3. Preencha os campos obrigatórios e os dados opcionais que pretende enviar. Os valores sugeridos nos placeholders não são enviados automaticamente. Se faltar um campo obrigatório, o console aponta o campo antes de enviar. Quando o endpoint aceitar idempotência, consulte [Idempotência](/br/api/idempotencia) antes de preencher `Idempotency-Key` em **Cabeçalhos**. 4. Escolha a linguagem para conferir o exemplo e selecione **Experimentar**. 5. Confira o status HTTP e o corpo no painel **Resposta**. A seção **Respostas**, no fim da página, detalha os resultados previstos. Uma resposta real também mostra `Request-Id`. Guarde esse valor ao investigar uma tentativa ou pedir ajuda ao suporte. Consulte [Identificador da requisição](/br/api/request-id) para entender seus limites. Para consultar um exemplo sem enviar uma requisição, expanda um status em **Respostas**. O painel **Resposta** mostra o exemplo correspondente, quando ele estiver definido para o endpoint. Se a credencial estiver inválida, corrija o campo antes de testar. Se aparecer um aviso sobre credenciais de Produção, substitua a chave por uma credencial de Sandbox. Consulte [Códigos HTTP das respostas](/br/api/codigos-http-das-respostas) para entender os erros gerais, o formato das respostas e os cuidados ao repetir uma requisição. Mesmo com erro ou conexão interrompida, a requisição pode ter sido processada. Confira o resultado antes de tentar novamente. # Recuperar número de conta (/br/api/accounts/account-number) Consulte a agência e o número da conta financeira da sua empresa na Raims. Use uma chave de Produção no servidor da integração. O Sandbox não possui esses dados; o console desta documentação aceita somente chaves Sandbox. Veja as condições da consulta em [Informações e personalização da conta](/br/api/accounts/overview#recuperar-número-de-conta). GET /v1/accounts/account_number # Consultar personalização do checkout (/br/api/accounts/checkout-settings) Consulte a configuração do checkout da sua empresa para conferir as imagens, as cores, o contato de suporte e os meios de pagamento padrão disponíveis. As imagens informam também o andamento de uma alteração enviada. Veja o alcance dessas preferências e como alterá-las em [Personalização do checkout](/br/api/accounts/overview#personalização-do-checkout). GET /v1/accounts/checkout_settings # Consultar contexto da conta (/br/api/accounts/context) Consulte a empresa autenticada, o ambiente e a situação atual da conta. Use esses dados para identificar a conta na sua integração e interpretar os valores e as datas das respostas. Veja como acompanhar mudanças entre consultas em [Informações e personalização da conta](/br/api/accounts/overview#consultar-contexto-da-conta). GET /v1/accounts/context # Descartar envio de imagem (/br/api/accounts/delete-checkout-upload) Descarte um envio que não será usado, com o `id` recebido ao preparar o arquivo. A requisição aceita envios que ainda não foram associados ao checkout, inclusive quando a autorização expirou. Para remover uma imagem já associada, use o PATCH da personalização. Veja as condições em [Descartar envio não utilizado](/br/api/accounts/overview#descartar-envio-não-utilizado). DELETE /v1/accounts/checkout_settings/uploads/{id} # Preparar envio do ícone (/br/api/accounts/favicon-upload) Informe os dados de uma imagem quadrada para obter a URL temporária de envio do ícone. Depois de enviar o arquivo, associe o identificador retornado à configuração do checkout. Essa requisição não troca o ícone por si só. Confira as etapas em [Logo e ícone do checkout](/br/api/accounts/overview#logo-e-ícone-do-checkout). POST /v1/accounts/checkout_settings/favicon_uploads # Consultar tarifas da conta (/br/api/accounts/fees) Consulte as tarifas de Pix e boleto aplicáveis à sua empresa para estimar custos no seu sistema e conferir as condições atuais da conta. Veja como interpretar os valores em [Informações e personalização da conta](/br/api/accounts/overview). GET /v1/accounts/fees # Preparar envio da logo (/br/api/accounts/logo-upload) Informe os dados da imagem para obter uma URL temporária de envio. Depois de enviar o arquivo, associe o identificador retornado à configuração do checkout. Essa requisição não troca a logo por si só. Confira o envio do arquivo e o acompanhamento em [Logo e ícone do checkout](/br/api/accounts/overview#logo-e-ícone-do-checkout). POST /v1/accounts/checkout_settings/logo_uploads # Informações e personalização da conta (/br/api/accounts/overview) Confirme a empresa e o ambiente da integração e consulte a agência e o número da conta financeira da sua empresa na Raims. Você também pode conferir as condições comerciais para estimar os custos de recebimento na integração e configurar as imagens, as cores e o contato de suporte apresentados no checkout. | Finalidade | Método e caminho | | -------------------------------------- | ----------------------------------------------------- | | Consultar empresa, ambiente e situação | `GET /v1/accounts/context` | | Recuperar agência e número da conta | `GET /v1/accounts/account_number` | | Consultar as tarifas vigentes | `GET /v1/accounts/fees` | | Consultar a personalização do checkout | `GET /v1/accounts/checkout_settings` | | Atualizar a personalização do checkout | `PATCH /v1/accounts/checkout_settings` | | Preparar envio da logo | `POST /v1/accounts/checkout_settings/logo_uploads` | | Preparar envio do ícone | `POST /v1/accounts/checkout_settings/favicon_uploads` | | Descartar um envio não utilizado | `DELETE /v1/accounts/checkout_settings/uploads/{id}` | ## Consultar contexto da conta Use [Consultar contexto da conta](/br/api/accounts/context), com `GET /v1/accounts/context`, para obter o identificador público, o nome exibível e a situação da empresa autenticada. A resposta informa também o ambiente autenticado e as referências de moeda, unidades e fuso horário usadas pela integração. A requisição não recebe parâmetros nem corpo. Use a chave do ambiente que deseja consultar. Uma empresa com cadastro pendente pode consultar o contexto somente com uma chave Sandbox. `checked_at` informa quando os dados foram consultados, em segundos Unix UTC. Compare `access_revision` com o valor de uma leitura anterior para reconhecer mudanças no contexto da conta ou no acesso da integração. Esse valor é uma revisão opaca; não o use como credencial. A chave representa a integração da empresa e do ambiente. Essa consulta não identifica o proprietário nem um funcionário e não confirma que uma cobrança, um estorno ou um saque possa ser executado. Cada endpoint conserva suas condições e verificações. ## Recuperar número de conta Use [Recuperar número de conta](/br/api/accounts/account-number), com `GET /v1/accounts/account_number`, para obter `agency` e `account` da conta financeira da própria empresa. A requisição usa a empresa identificada pela chave de API e não recebe parâmetros nem corpo. Essa consulta exige acesso autorizado em Produção e uma conta financeira aprovada e habilitada. O Sandbox não possui agência e conta financeira e retorna `403 DATA_ENVIRONMENT_NOT_SUPPORTED`. O console desta documentação aceita somente chaves Sandbox; consulte os dados pelo servidor da sua integração, sem inserir uma chave de Produção na documentação ou no navegador. Se a conta não estiver aprovada e habilitada, ou os dados não estiverem disponíveis, a resposta será `404 ACCOUNT_NUMBER_NOT_AVAILABLE`. Confira a situação da conta no Dashboard antes de tentar novamente. Preserve agência e conta como texto, incluindo zeros à esquerda e a formatação retornada. A consulta não cadastra uma conta nem altera o destino dos [saques](/br/api/withdrawals/overview). ## Consultar tarifas da conta Use [Consultar tarifas da conta](/br/api/accounts/fees), com `GET /v1/accounts/fees`. A resposta reúne as regras vigentes de Pix e boleto no plano selecionado pela empresa. A consulta não altera o plano nem as tarifas. Os valores atuais também não informam qual tarifa foi aplicada a uma transação antiga. Para conferir uma tarifa já cobrada, consulte os lançamentos do [Extrato](/br/api/statements/overview). ## Entender os valores Cada meio de pagamento retorna a parcela percentual, o valor fixo e os limites de tarifa que estiverem configurados: | Campo | Significado | | ------------------- | --------------------------------------------------------- | | `percentage_rate` | Percentual da tarifa. Por exemplo, `0.8` representa 0,8%. | | `fixed_fee_cents` | Parcela fixa da tarifa, em centavos de real. | | `minimum_fee_cents` | Valor mínimo da tarifa, em centavos de real. | | `maximum_fee_cents` | Valor máximo da tarifa, em centavos de real. | Um valor de `85` em um campo de centavos representa R$ 0,85. Um campo `null` indica que aquela parcela ou limite não está configurado. As parcelas percentual e fixa podem estar presentes na mesma regra. Se `pix` ou `boleto` for `null`, não há uma regra vigente para esse meio no plano selecionado. Isso não significa que o recebimento seja gratuito. A presença de uma regra também não confirma que o meio esteja habilitado para receber pagamentos. ## Personalização do checkout Use [Consultar personalização do checkout](/br/api/accounts/checkout-settings) para conferir as imagens, as cores, o e-mail de suporte e os meios de pagamento padrão da empresa no ambiente autenticado. Sandbox e Produção têm configurações separadas; uma alteração em um ambiente preserva a configuração do outro. Para alterar as cores ou o contato, use [Atualizar personalização do checkout](/br/api/accounts/update-checkout-settings). Envie `hex_primary_color` para a cor principal e `hex_secondary_color` para a cor de fundo, no formato `#RRGGBB`. Omitir um campo preserva seu valor. Em `support_email`, `null` ou texto vazio remove o contato de suporte. As cores precisam continuar preenchidas com valores válidos. Um corpo vazio mantém a configuração atual. `payment_method_types` informa os meios padrão habilitados e disponíveis para o checkout. A atualização pela API não altera essa lista. Para escolher Pix e boleto, use **Conta / Configurações / Checkout de pagamentos**. O padrão de meios da conta se aplica quando a cobrança e o link não têm uma configuração própria. Alterar esse padrão pode mudar as opções das cobranças que o utilizam. Uma lista própria da cobrança continua valendo; o link pode restringir essas opções. Consulte [Checkout e formas de pagamento](/br/checkout). Essas preferências não alteram valor, vencimento ou situação de uma cobrança e não confirmam pagamento. A consulta retorna a configuração atual; ela não informa qual aparência estava em uso em uma data passada. ## Logo e ícone do checkout O envio de cada imagem tem três etapas: 1. Use [Preparar envio da logo](/br/api/accounts/logo-upload) ou [Preparar envio do ícone](/br/api/accounts/favicon-upload). Informe o tipo, o tamanho em bytes, a largura e a altura do arquivo. PNG e JPEG são aceitos; o ícone precisa ser quadrado. Confira os limites nos parâmetros do endpoint correspondente. 2. Envie os bytes do arquivo para `upload_url`, com o método `PUT`. Use `Content-Type` e `Content-Length` conforme `content_type` e `file_size` da resposta. Não envie a chave de API Raims nesse endereço. A URL é temporária. Conclua o envio e a associação antes de `expires_at`, informado em segundos Unix UTC. 3. Use [Atualizar personalização do checkout](/br/api/accounts/update-checkout-settings) e informe o `id` recebido em `logo_upload_id` ou `favicon_upload_id`. Os dois campos são independentes. Use um envio de logo no campo da logo e um envio de ícone no campo do ícone, sempre na mesma empresa e ambiente. Obter a URL ou concluir o PUT não altera a imagem apresentada no checkout. A associação pelo PATCH pode retornar `202` enquanto a imagem é verificada. Consulte a configuração para acompanhar `logo.status` e `favicon.status`: | `status` | Como interpretar | | --------- | ------------------------------------------------------------- | | `absent` | Nenhuma imagem está configurada. | | `ready` | A imagem está pronta para uso no checkout. | | `pending` | A imagem enviada ainda está em processamento. | | `failed` | A imagem enviada não pôde ser aplicada. Confira `error_code`. | `url` apresenta a imagem atual ou `null` quando não houver uma disponível. Durante o processamento ou após uma falha, a imagem anterior continua em uso, quando existir. A nova imagem passa a ser usada quando a alteração termina com `status: ready`. Se precisar repetir o PATCH enquanto a imagem está em processamento, use o mesmo ID de envio. Um envio que falhou ou já foi substituído não pode ser aplicado novamente. Prepare um novo envio para trocar a imagem outra vez. Quando `error_code` estiver preenchido, confira o motivo: | `error_code` | O que fazer | | ---------------------------------- | ---------------------------------------------------------------------------------------------- | | `CHECKOUT_ASSET_INVALID_IMAGE` | Confira o arquivo, o tipo e as dimensões antes de preparar outro envio. | | `CHECKOUT_ASSET_UPLOAD_NOT_FOUND` | O arquivo não está disponível. Prepare outro envio. | | `CHECKOUT_ASSET_PROCESSING_FAILED` | A aplicação da imagem falhou. Prepare outro envio; se o problema persistir, procure o suporte. | ## Remover imagem do checkout Para remover uma imagem, envie `logo_upload_id: null` ou `favicon_upload_id: null`. Omitir esses campos preserva as imagens atuais. Uma remoção também pode ficar em processamento; ela termina com `status: absent`. Essa configuração também pode ser feita pelo Dashboard, na seção de aparência do checkout. ## Descartar envio não utilizado Se desistir de um envio antes de associá-lo, use [Descartar envio de imagem](/br/api/accounts/delete-checkout-upload), com o mesmo `id` retornado na preparação. O descarte também aceita uma autorização expirada. A resposta `deleted: true` confirma que o envio foi descartado e não pode mais ser aplicado; repetir o descarte conserva esse resultado. Um envio já associado ao checkout não pode ser descartado por esse endpoint. Para remover a imagem, use o PATCH com o campo correspondente em `null`. ## Empresa e ambiente As consultas identificam a empresa pela [autenticação por chave de API ou OAuth](/br/integracoes/autenticacao). Você não precisa informar o identificador da empresa na requisição. As tarifas são compartilhadas entre Sandbox e Produção. Uma chave Sandbox consulta as mesmas regras da empresa, enquanto os pagamentos de teste continuam separados das movimentações reais. Proteja a chave no servidor da sua integração. Trate os erros pelo status HTTP e por `error.code`, conforme [Códigos HTTP das respostas](/br/api/codigos-http-das-respostas). # Atualizar personalização do checkout (/br/api/accounts/update-checkout-settings) Altere as imagens, as cores e o e-mail de suporte do checkout da empresa. Envie somente os campos que deseja mudar. Os meios de pagamento continuam configurados pelo Dashboard. Para trocar uma imagem, envie o arquivo pela URL temporária antes de informar seu identificador nesta requisição. A resposta pode indicar que a imagem ainda está em processamento; acompanhe a configuração antes de considerar a troca concluída. Confira o efeito das mudanças em [Personalização do checkout](/br/api/accounts/overview#personalização-do-checkout). PATCH /v1/accounts/checkout_settings # Consultar saldo (/br/api/balances) Consulte os valores atuais da conta na empresa e no ambiente autenticado. A consulta não reserva dinheiro nem confirma que um saque ou estorno será aceito. Veja [Informações financeiras](/br/api/balances/overview) para entender os valores e sua relação com o extrato. GET /v1/balances # Consultar recebimentos previstos (/br/api/balances/forecast) Consulte a estimativa de recebimentos do período para acompanhar a projeção financeira no seu sistema. O saldo projetado é uma estimativa e não informa quanto pode ser sacado. Veja os critérios e a diferença entre previsão e saldo em [Recebimentos previstos](/br/api/balances/overview#recebimentos-previstos). GET /v1/balances/forecast # Informações financeiras (/br/api/balances/overview) Use o saldo para conferir quanto a conta tem no momento da consulta e qual parcela está disponível. Os valores podem mudar com novos recebimentos, saques, estornos, retenções e liberações. As estatísticas de cobranças apresentam os totais por período. Elas ajudam a acompanhar os recebimentos. A previsão apresenta uma estimativa do que ainda pode ser recebido no período. Nenhuma delas substitui a consulta de saldo. | Finalidade | Método e caminho | | -------------------------------------- | ----------------------------- | | Consultar o saldo atual | `GET /v1/balances` | | Consultar as estatísticas de cobranças | `GET /v1/charges/statistics` | | Consultar recebimentos previstos | `GET /v1/balances/forecast` | | Consultar saques em processamento | `GET /v1/withdrawals/summary` | ## Consultar o saldo atual Use [Consultar saldo](/br/api/balances), com `GET /v1/balances`. A resposta apresenta os valores em centavos de real. A consulta não reserva dinheiro. Um saque ou estorno continua sujeito às suas próprias condições, limites e à nova conferência do saldo no momento da solicitação. ## Entender os valores | Campo | Significado | | ------------------------ | ------------------------------------------------------------------------ | | `total_amount_cents` | Saldo total da conta, incluindo a parcela bloqueada. | | `blocked_amount_cents` | Parcela do saldo retida e indisponível para uso. | | `available_amount_cents` | Valor disponível após descontar a parcela bloqueada, com mínimo de zero. | Se a conta tiver R$ 100,00 no total e R$ 30,00 bloqueados, a resposta será: ```json { "total_amount_cents": 10000, "blocked_amount_cents": 3000, "available_amount_cents": 7000 } ``` O bloqueio preserva o valor total e reduz o disponível. Sua liberação torna o valor disponível novamente; ela não representa um novo recebimento. O total mantém um eventual valor negativo, enquanto o disponível fica em zero quando não há valor livre para uso. ## Saldo e extrato O saldo mostra os valores atuais. O [Extrato](/br/api/statements/overview) apresenta os lançamentos financeiros registrados, com seus tipos e vínculos. A soma de uma página ou de lançamentos filtrados não substitui a consulta de saldo. A resposta de saldo não informa quanto havia na conta após um lançamento antigo. Para conferir uma movimentação, use [Recuperar um lançamento](/br/api/statements/retrieve). ## Estatísticas de cobranças Use [Consultar estatísticas de cobranças](/br/api/charges/statistics), com `GET /v1/charges/statistics`, para acompanhar quantidades, valores e taxa de pagamento em um ERP, relatório ou painel próprio. A consulta reúne os totais da empresa e do ambiente autenticado, sem exigir que você percorra todas as páginas de cobranças. | Campo | O que considera | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `issued` | Cobranças criadas no período, inclusive canceladas, exceto as removidas. | | `issued_paid` | Cobranças criadas no período que estão pagas, parcialmente devolvidas ou devolvidas. | | `received` | Pagamentos confirmados no período, mesmo que a cobrança tenha sido criada antes. Considera cobranças pagas, parcialmente devolvidas ou devolvidas. | | `payment_rate` | Percentual da quantidade de `issued_paid` sobre a quantidade de `issued`. Retorna zero quando não houver cobranças emitidas. | Os grupos `issued`, `issued_paid` e `received` informam `count`, para a quantidade, e `amount_cents`, para o valor em centavos de real. Os valores são brutos, sem descontar tarifas ou devoluções. Uma cobrança devolvida permanece nesses totais pelo valor original enquanto estiver em um dos estados considerados. Cobranças em estado de contestação não entram em `issued_paid` nem em `received`. A consulta não informa o saldo disponível da conta. Por exemplo, uma cobrança criada ontem e paga hoje entra em `received` na consulta de hoje. Ela não entra em `issued` nem em `issued_paid` de hoje, pois foi criada fora desse período. Para conferir cobranças individuais, use [Listar cobranças](/br/api/charges/list). Para saber quanto dinheiro está disponível na conta, use [Consultar saldo](/br/api/balances). ## Período e atualização das estatísticas Se a resposta informar `INVALID_FIELDS` com `period` e `INVALID_VALUE` em `error.details`, escolha um dos períodos aceitos. Envie `period` uma única vez. Datas personalizadas em `start_at` ou `end_at` não são filtros: um parâmetro desconhecido recebe `UNKNOWN_QUERY_PARAMETER`. O parâmetro `period` aceita `today`, `last_7_days`, `last_15_days` e `last_30_days`. Quando omitido, a consulta considera hoje. Os períodos usam dias de calendário no horário de São Paulo e incluem o dia atual. `last_7_days`, por exemplo, começa à meia-noite de seis dias atrás e termina à meia-noite de amanhã. `start_at` e `end_at` são campos da resposta, não filtros. Eles informam o início incluído e o fim excluído do período, em segundos Unix UTC. Use esses limites para identificar o intervalo do relatório. A consulta aceita somente os períodos listados em `period`, sem datas personalizadas de início e fim. Os totais podem levar alguns segundos para refletir uma criação, pagamento, devolução ou remoção. `updated_at` informa a última atualização dos dados consultados, ou `null` quando essa informação não estiver disponível. Consultas repetidas não antecipam essa atualização. ## Recebimentos previstos Use [Consultar recebimentos previstos](/br/api/balances/forecast), com `GET /v1/balances/forecast`, para acompanhar a mesma estimativa financeira apresentada no Resumo do Dashboard. `receivable_amount_cents` apresenta os pagamentos confirmados que o cálculo ainda mantém como recebimentos previstos dentro do período escolhido. A consulta não soma cobranças abertas nem procura vencimentos futuros. O período se refere à data prevista de recebimento, não à data de criação da cobrança. `projected_balance_cents` soma essa estimativa ao saldo total atual da conta. Por exemplo, um saldo total de R$ 100,00 com R$ 25,00 previstos resulta em R$ 125,00 projetados. O valor pode incluir saldo bloqueado e não confirma liquidação bancária, prazo garantido ou disponibilidade para saque. Consulte [Consultar saldo](/br/api/balances) para saber os valores atuais total, bloqueado e disponível. O parâmetro `period` aceita `today`, `last_7_days`, `last_15_days` e `last_30_days`; o padrão é `today`. Os períodos incluem hoje e usam o calendário de São Paulo. `last_7_days`, por exemplo, começa à meia-noite de seis dias atrás e termina à meia-noite de amanhã. Essa consulta não projeta os próximos sete, quinze ou trinta dias. `start_at` informa o início incluído e `end_at`, o fim excluído do período. `forecast_date` identifica o dia de referência da estimativa, à meia-noite de hoje em São Paulo. Esses campos usam segundos Unix UTC. Os valores podem levar alguns segundos para acompanhar mudanças nos pagamentos. `updated_at` informa a atualização dos dados da previsão, ou `null` quando ela não estiver disponível. Uma estimativa igual a zero não comprova que todos os pagamentos foram liquidados. No Sandbox, os valores são simulados e não representam recebimentos reais. ## Saques em processamento Use [Consultar saques em processamento](/br/api/withdrawals/summary) para acompanhar o total das retiradas que ainda aguardam conclusão. A consulta exige acesso autorizado em Produção e considera os saques com situação `PENDING` ou `PROCESSING`. `processing_count` informa a quantidade de saques, e `processing_amount_cents` soma o valor solicitado, incluindo a tarifa, em centavos de real. Quando não houver saques nessas situações, os dois campos retornam zero. Esse total representa dinheiro comprometido com as solicitações. Não o some ao saldo disponível nem o trate como crédito confirmado na conta de destino. Para conferir cada pedido e seu resultado, use [Listar saques](/br/api/withdrawals). A consulta do resumo não solicita outra retirada nem altera o andamento dos saques. ## Empresa e ambiente As consultas seguem a [autenticação](/br/integracoes/autenticacao) por chave de API ou OAuth, com a empresa e o ambiente autorizados. A chave Sandbox consulta o saldo de simulação, separado do saldo de Produção. O console aceita somente chaves Sandbox. Você não precisa informar uma empresa ou conta no corpo da requisição. Trate os erros pelo status HTTP e por `error.code`, conforme [Códigos HTTP das respostas](/br/api/codigos-http-das-respostas). # Criar nova cobrança (/br/api/charges) Cria uma cobrança para um cliente já cadastrado na empresa e no ambiente da sua chave de API. Use em `customer_id` o identificador recebido no cadastro ou na consulta do cliente. Para receber os dados do Pix na criação, envie `payment_method: 1` sem uma lista própria em `payment_method_types`. A API usa o CPF/CNPJ do cliente vinculado. Para emitir boleto, envie `payment_method: 2` sem lista própria. A emissão usa o nome, e-mail válido, CPF/CNPJ e endereço do cliente. A Raims pode completar rua, bairro, cidade e UF ausentes a partir do CEP, quando esses dados estiverem disponíveis. Informe o número no cadastro do cliente; ele não vem do CEP. Veja as [condições do endereço](/br/api/charges/overview#receber-o-boleto-na-criação). Se a emissão de Pix ou boleto estiver pendente, guarde o ID retornado e acompanhe a mesma cobrança pela [consulta individual](/br/api/charges/retrieve). Para relacionar a cobrança ao pedido do seu sistema, use `external_reference`. Consulte [Referência no seu sistema](/br/api/charges/overview#referência-no-seu-sistema) para entender esse vínculo e evitar cobranças duplicadas ao repetir uma requisição. Use `create_checkout: true` para receber o link do checkout sem configurar uma URL de retorno. Informar uma URL de retorno também gera o link, mesmo com `send_email: false`, sem solicitar envio de e-mail. `cancel_redirect_url` é o destino para voltar ao site da empresa; essa navegação não revoga a cobrança. Consulte a [visão geral de cobranças](/br/api/charges/overview) para entender o vencimento, as URLs de retorno e o envio de e-mail. Os códigos de `payment_method` e a escolha no checkout estão em [Meios de pagamento](/br/meios-de-pagamento#códigos-na-api). POST /v1/charges # Baixar boleto (/br/api/charges/boleto) Obtenha uma URL temporária para baixar o boleto já emitido da cobrança. Consulte este endpoint com sua chave de API ou sessão OAuth e use a `url` retornada para baixar o PDF em `files.raims.com`, sem enviar a chave nesse download. A consulta não solicita outra emissão. O boleto serve para cobrança e não comprova pagamento. Para obter o documento de um pagamento confirmado, use [Baixar recibo de pagamento](/br/api/charges/receipt). Confira as condições em [Boleto em PDF](/br/api/charges/overview#boleto-em-pdf). GET /v1/charges/{id}/boleto # Listar cobranças (/br/api/charges/list) Consulta as cobranças da empresa e do ambiente autenticado. Você pode filtrar pelo identificador da cobrança, referência externa, cliente, e-mail registrado na cobrança, status, meio de pagamento ou período de criação, vencimento e pagamento. O filtro usa o meio atual da cobrança; apenas selecionar uma opção no checkout não muda esse valor. Alterações de status ou referência externa podem levar alguns segundos para aparecer nos resultados filtrados. Comece sem cursor, processe `list` e, enquanto `page.has_next` for `true`, copie `page.next_after` para `after`, mantendo os filtros e a ordenação. Copie o cursor inteiro, sem interpretar ou calcular seu conteúdo. Consulte [Listagem e paginação](/br/api/listagem-e-paginacao) para voltar com `before`. Veja como os filtros e a ordenação funcionam em [Listar cobranças](/br/api/charges/overview#listar-cobranças). O significado de `external_reference` está em [Referência no seu sistema](/br/api/charges/overview#referência-no-seu-sistema). GET /v1/charges # Cobranças (/br/api/charges/overview) Uma cobrança informa o valor que um cliente deve pagar à sua empresa. Depois de criá-la, acompanhe o status para saber se o cliente pagou. A criação por si só não confirma pagamento nem saldo disponível na conta. A base das requisições é `https://api.raims.com`. ## Cliente e ambiente Use um cliente já cadastrado na empresa e no ambiente autenticado. Se precisar cadastrar o pagador, consulte [Criar um cliente](/br/api/customers). Para obter os dados de um cadastro existente, use [Recuperar um único cliente](/br/api/customers/retrieve). Copie o `id` do cliente para `customer_id` ao criar a cobrança. Não envie o identificador do seu próprio sistema nesse campo. Cadastros e cobranças de Sandbox ficam separados dos dados de Produção. Use Sandbox para testar sem movimentar valores reais. Use [Simulação](/br/api/simulations/overview) para confirmar um pagamento ou aplicar uma falha a uma cobrança de teste. Você também pode testar a emissão e o cancelamento pendentes ou com falha, além da compensação do boleto antes da liquidação. Esses endpoints são exclusivos do Sandbox e permitem conferir o resultado sem realizar um pagamento real. Para emitir Pix na criação, o cliente vinculado precisa ter um CPF/CNPJ válido. A API usa esse cadastro; não envie outro documento no pedido da cobrança. O documento identifica o cliente cobrado, sem exigir que o pagamento venha de uma conta bancária desse titular. ## Criar uma cobrança [Criar nova cobrança](/br/api/charges), com `POST /v1/charges`, recebe o cliente e o valor da cobrança. Envie `amount_cents` como um inteiro em centavos: `10000` representa R$ 100,00. O valor permitido vai de 100 a 999999999999 centavos. Cada requisição cria uma cobrança única. `payment_method_types` permite definir uma lista própria de meios aceitos, que substitui o padrão da conta somente nessa cobrança. Omitir a lista ou enviar `null` mantém a herança da configuração usada pelo checkout. A disponibilidade da plataforma continua valendo, e uma configuração própria do link pode reduzir as opções da cobrança. `payment_method` é separado da lista e mantém os comportamentos de escolha ou restrição a um meio quando ela não é informada. Com uma lista própria, omita esse campo ou envie `0`. Consulte os formatos e códigos em [Meios de pagamento](/br/meios-de-pagamento#códigos-na-api). Título e descrição são opcionais e aceitam até 512 caracteres cada. Guarde o identificador retornado pela API para relacionar a cobrança ao seu sistema. Se uma requisição terminar sem uma resposta conclusiva, confira o resultado antes de repetir o pedido. ## Receber o Pix na criação Em `POST /v1/charges`, envie `customer_id` de um cliente já cadastrado e `payment_method: 1`, sem uma lista própria em `payment_method_types`. A emissão usa o CPF/CNPJ válido desse cadastro; não envie outro documento, nome ou e-mail no pedido da cobrança. A resposta inclui `payment_information.pix`, com `copy_paste`, `expires_at` e `qr_code_base64`. Você pode apresentar esses dados no seu sistema, sem encaminhar o pagador ao checkout da Raims. A emissão não confirma pagamento. `payment_information.pix_status` informa o resultado: `available` quando o Pix está disponível, `pending` enquanto a emissão não foi confirmada, `failed` quando não foi possível emitir e `not_generated` quando não há uma emissão Pix disponível. Em `failed`, confira `payment_information.pix_error` para identificar o motivo. ## Exibir o QR Code e usar o copia e cola Ao receber o Pix na criação com `POST /v1/charges`, o QR Code vem em `payment_information.pix.qr_code_base64`, como imagem PNG em Base64. Para exibi-lo em uma página, use o prefixo `data:image/png;base64,` antes desse valor. `copy_paste` é o código para copiar, e `expires_at` informa a expiração em segundos Unix UTC. ## Respostas 201 e 202 para Pix Se receber `202`, a cobrança já tem um ID, mas o Pix ainda não está disponível. Guarde esse ID e consulte a mesma cobrança em [Recuperar uma única cobrança](/br/api/charges/retrieve). Não crie outra cobrança para acompanhar essa emissão. A consulta devolve os dados disponíveis e o status atual; consultar não emite outro código. Se a emissão continuar pendente ou falhar, entre em contato com o suporte e informe o ID da cobrança. Uma resposta `201` confirma a criação da cobrança. Confira `payment_information.pix_status` e os dados de pagamento para saber se o Pix está disponível. ## Pix na criação ou no checkout Uma lista como `payment_method_types: [1]` configura os meios aceitos, mas mantém a emissão após a escolha no checkout. Para solicitar o Pix na própria criação, use o campo `payment_method: 1`. ## Receber o boleto na criação Em `POST /v1/charges`, envie `payment_method: 2`, sem lista própria em `payment_method_types`. Use em `customer_id` o ID de um cliente com nome, e-mail válido, CPF/CNPJ válido e endereço. O CEP fica em `zip_code` e o número em `street_number` no cadastro do cliente. Você não precisa enviar outro pagador ou endereço na requisição da cobrança. O e-mail é necessário para a emissão mesmo com `send_email: false`; informá-lo no cadastro não solicita envio de mensagem. A Raims pode completar logradouro, bairro, cidade e UF ausentes a partir do CEP, quando esses dados estiverem disponíveis. Os valores já informados no endereço são preservados. O número precisa estar no cadastro; ele e o complemento não vêm do CEP. O complemento é opcional. Se o CEP não fornecer todos os dados necessários, complete o endereço em [Atualizar cliente existente](/br/api/customers/update) antes de emitir o boleto. O endereço usado na emissão não altera o cadastro do cliente. Essa regra é diferente do preenchimento ao [criar um cliente](/br/api/customers): naquele cadastro, informar número ou complemento impede o preenchimento pelo CEP. Na emissão do boleto, eles podem estar preenchidos enquanto a Raims completa os demais campos ausentes. Quando o boleto estiver disponível, `payment_information.boleto` contém `line_digits`, `barcode` e `due_date`. Use a linha digitável e o código de barras no seu sistema. O vencimento vem em segundos Unix UTC e corresponde à data do boleto. Emitir esses dados não confirma pagamento. No Sandbox, o boleto é simulado e não deve ser usado para um pagamento real. Uma lista como `payment_method_types: [2]` configura o boleto no checkout, com emissão após a escolha do pagador. Para emitir na criação, use `payment_method: 2`. ## Respostas 201 e 202 para boleto `payment_information.boleto_status` informa `available` quando os dados estão disponíveis, `pending` quando a emissão ainda não foi confirmada, `failed` quando não foi possível emitir e `not_generated` quando não há emissão disponível ou solicitada. `boleto_error` informa o motivo da pendência ou da falha, quando houver. Uma resposta `201` confirma a criação da cobrança; confira `boleto_status` para saber se o boleto foi emitido. Em `202`, guarde o ID e acompanhe a mesma cobrança em [Recuperar uma única cobrança](/br/api/charges/retrieve). A consulta não repete nem renova a emissão. Se a pendência persistir ou houver falha, contate o suporte com o ID da cobrança, sem criar outra para repetir a emissão. Se os dados do cliente impedirem a criação, corrija o cadastro indicado pelo erro antes de enviar novamente a requisição. Uma emissão confirmada também não significa que o cliente pagou; acompanhe o status da cobrança. O andamento do pagamento do boleto aparece em `payment_information.boleto_payment_status`: `awaiting_payment` para boleto emitido que aguarda pagamento, `compensated` para pagamento compensado que aguarda liquidação e `settled` para pagamento liquidado. Sem andamento disponível, o campo retorna `null`. A compensação ainda não representa crédito disponível. Para testar essas etapas, veja [Compensação e liquidação do boleto](/br/api/simulations/overview#compensação-e-liquidação-do-boleto). ## Referência no seu sistema Envie em `external_reference` o identificador do pedido ou da cobrança no seu sistema, por exemplo `PEDIDO-123`. Esse campo pertence à cobrança e é independente da referência externa cadastrada no cliente. A referência é opcional. Na criação, omitir o campo, enviar `null`, texto vazio ou somente espaços deixa a cobrança sem referência. A API remove os espaços nas bordas. A resposta da criação, as consultas e a resposta da edição incluem `external_reference`, com o valor cadastrado ou `null`. Você pode alterar ou remover a referência em [Atualizar cobrança existente](/br/api/charges/update). Omitir o campo mantém o valor atual; enviar `null`, texto vazio ou somente espaços remove a referência. Essa alteração não muda o identificador da Raims nem o cliente vinculado. Na listagem `GET /v1/charges`, o filtro `external_reference` busca o valor completo atual da referência da cobrança. A comparação distingue maiúsculas, minúsculas e acentos. Mantenha o mesmo valor com os demais filtros ao navegar por cursor. Uma criação ou edição pode levar alguns segundos para aparecer nessa busca; evite consultas contínuas em intervalos curtos. A mesma referência pode aparecer em mais de uma cobrança. Repetir essa referência, por si só, não faz a API reutilizar uma cobrança. Guarde também o `id` retornado para reconhecer cada cobrança e conferir um resultado inconclusivo antes de tentar novamente. ## Dados adicionais da integração Use `metadata` para guardar pequenas informações que relacionem a cobrança ao seu sistema, como uma filial ou um canal de venda. Os dados do cliente e os da cobrança são separados: o mapa do cliente não é copiado para uma nova cobrança. ```json { "metadata": { "filial": "SP-01", "canal": "site" } } ``` O mapa aceita até 32 chaves, com nomes formados por letras sem acentos, números, ponto, hífen ou sublinhado e valores em texto. Os nomes diferenciam maiúsculas de minúsculas. Os limites também valem para o mapa completo depois de uma atualização. Não armazene senhas, tokens, documentos pessoais ou outros dados sensíveis. Se `metadata` não for informado na criação, a cobrança fica com um mapa vazio. Na atualização, as chaves enviadas são adicionadas ou substituídas; as demais permanecem. Omitir `metadata` ou enviar `{}` mantém os dados. Envie `null` no valor de uma chave para removê-la, ou `metadata: null` para apagar o mapa. Um texto vazio é um valor válido e não remove a chave. As respostas de criação, atualização e consulta retornam `metadata`, com `{}` quando não há valores. Esses dados não alteram valor, vencimento ou pagamento. Eles não são filtros da listagem nem entram automaticamente no corpo dos webhooks. Para pesquisar pelo código do seu sistema, use `external_reference`. Você pode atualizar somente `metadata` depois do pagamento ou estorno da cobrança. Se o mesmo pedido também alterar título, descrição ou referência externa, ele fica sujeito às regras desses campos. Quando o estado impedir essa edição, nenhum dos campos do pedido será alterado. ## Vencimento Informe o vencimento em `due_date`, em segundos Unix UTC. Escolha uma data e horário pelo menos cinco minutos à frente do momento em que a requisição chegar à API. Considere o tempo de envio ao calcular esse prazo. O limite máximo é o dia correspondente a dez anos após hoje, no horário de São Paulo. No Pix, o vencimento conserva o horário informado. O boleto usa a data de vencimento de São Paulo, inclusive o mesmo dia. A expiração da cobrança e do checkout não confirma o cancelamento de um boleto já emitido. Para deixar de receber por esse boleto, acompanhe a confirmação da revogação da cobrança. ## Link do checkout e envio de e-mail Para receber `checkout_url` sem enviar e-mail, use `create_checkout: true` na criação da cobrança e mantenha `send_email: false`. Não é necessário configurar uma URL de retorno para receber o link. Use o endereço retornado para encaminhar o pagador ao checkout daquela cobrança. Os campos `success_redirect_url` e `cancel_redirect_url` configuram os destinos de retorno do checkout ao site da empresa. `success_redirect_url` é o destino após a confirmação do pagamento. `cancel_redirect_url` é o destino da opção de voltar ao site; essa navegação não revoga a cobrança. Envie URLs HTTPS completas, de até 2048 caracteres cada, em um domínio da empresa. Não use credenciais na URL, endereço IP, localhost ou domínio Raims. Os campos são opcionais: você pode omiti-los, enviar `null` ou deixá-los vazios. Campos só com espaços também não definem uma URL de retorno. Informar pelo menos uma dessas URLs gera o link. Consulte a cobrança para confirmar o pagamento no seu sistema, mesmo que o pagador tenha voltado pela URL de sucesso. `create_checkout` e `send_email` são opcionais e usam `false` quando omitidos. Sem essas opções e sem URLs de retorno, a requisição cria a cobrança sem gerar link nem solicitar e-mail; `checkout_url` retorna `null`. Use `send_email: true` para solicitar o envio da cobrança ao e-mail cadastrado do cliente. Você também recebe o link em `checkout_url`. Confira antes se o cliente tem um e-mail válido. Para obter somente o link, use `create_checkout: true` com `send_email: false`. Esse checkout pertence a uma cobrança específica. Para obter ou configurar o link de uma cobrança já criada, use [Links de pagamento](/br/api/payment-links/overview). Enquanto a empresa aguarda a conclusão da análise cadastral, o envio fica restrito ao e-mail do titular. Um e-mail ausente, inválido ou diferente do e-mail do titular nessa condição impede a criação com envio. Fora dessa restrição de cadastro pendente, um e-mail ausente ou inválido não impede a criação da cobrança e do link, mas não há envio. A emissão direta de boleto exige e-mail válido mesmo sem solicitar mensagem. O sucesso da requisição não confirma que o e-mail foi entregue nem que a cobrança foi paga. ## Listar cobranças [Listar cobranças](/br/api/charges/list), com `GET /v1/charges`, consulta os cadastros da empresa e do ambiente autenticado. Use os filtros por identificador da cobrança, referência externa, cliente, e-mail registrado na cobrança, status, meio de pagamento cadastrado e intervalos de criação, vencimento e pagamento. Alterar o e-mail do cliente não modifica o e-mail já registrado nas cobranças existentes. Use `customer_id` com o ID recebido no cadastro ou na consulta do cliente para listar suas cobranças. O vínculo continua o mesmo se o nome ou o e-mail do cliente mudar. Você pode combinar esse filtro com os demais. Um ID válido sem cobranças acessíveis na empresa e no ambiente autenticado retorna uma lista vazia. Mantenha também `customer_id` ao copiar o cursor para a próxima página. Use `external_reference` para procurar pelo valor atual da referência da cobrança. A comparação é exata e distingue maiúsculas, minúsculas e acentos: `PEDIDO-123` não corresponde a `pedido-123` nem a um trecho como `123`. Você pode combinar esse filtro com os demais; mantenha o mesmo valor ao navegar por cursor. Uma criação ou edição pode levar alguns segundos para aparecer nessa busca. Evite consultas contínuas em intervalos curtos para tentar antecipar a atualização. Os filtros `status` e `payment_method` aceitam códigos separados por vírgula. Para status, use os códigos de `0` a `13` descritos no endpoint. Os códigos do filtro de meio de pagamento estão em [Meios de pagamento](/br/meios-de-pagamento#códigos-na-api). A resposta contém `list` e `page`. Comece sem cursor e processe as cobranças recebidas. Enquanto `page.has_next` for `true`, copie `page.next_after` para `after` na próxima requisição, mantendo os filtros e a ordenação. Copie o cursor completo, sem interpretar ou calcular seu conteúdo. A página aceita até 100 cobranças e usa 10 quando `page_size` não é informado. O guia de [Listagem e paginação](/br/api/listagem-e-paginacao) também explica como voltar com `before`. Envie apenas um cursor por requisição. `created_gte` e `created_lte` filtram a data de criação, em segundos Unix UTC, incluindo os instantes informados. Por padrão, os cadastros mais recentes aparecem primeiro. `sort_key` aceita `amount_cents` ou `created_at`; `sort_order` aceita `asc` ou `desc`, com padrão `desc`, e também permite inverter a direção da ordenação padrão. Se informar um intervalo de criação sem escolher `sort_key`, a consulta ordena por `created_at`. Use `due_gte` e `due_lte` para consultar cobranças pelo vencimento, em segundos Unix UTC. Os limites são inclusivos: `due_gte` inclui vencimentos a partir do instante informado, e `due_lte` inclui vencimentos até esse instante. Você pode informar somente um limite ou combinar os dois; o limite final deve ser igual ou posterior ao inicial. Para consultar um dia inteiro, converta o início e o fim desse dia para UTC conforme o fuso horário usado no seu sistema. O intervalo considera o `due_date` da cobrança, inclusive em cobranças pagas. Combine com `status` quando precisar selecionar uma situação específica, como cobranças expiradas. O filtro de vencimento pode ser usado junto dos demais filtros e não muda a ordenação escolhida. Mantenha todos os filtros ao usar `after` ou `before`; para consultar outro período, comece novamente sem cursor. Use `paid_gte` e `paid_lte` para encontrar cobranças pagas em um período. Os valores são segundos Unix UTC e incluem os dois limites. O filtro usa a data do pagamento original da cobrança, não a data de criação, o vencimento ou a data de disponibilidade do dinheiro. Cobranças sem uma data de pagamento ficam fora desse filtro. Um estorno posterior não retira a cobrança do período em que ela foi paga; combine com `status` se precisar restringir a situação atual. A confirmação de um pagamento pode levar alguns segundos para aparecer na busca. Mantenha os mesmos filtros ao navegar por cursor e evite consultas contínuas para tentar antecipar a atualização. `payment_method` informa o meio atual da cobrança; `payment_method_types` informa a lista própria configurada, ou `null` para herança, sem representar as opções disponíveis naquele momento. `checkout_payment_method` informa o meio usado para gerar o pagamento no checkout. Se `payment_method` era `0`, gerar Pix ou boleto no checkout muda esse valor para `1` ou `2`, respectivamente. Apenas selecionar a opção no checkout não muda o filtro. Consulte [Meios de pagamento](/br/meios-de-pagamento#meio-cadastrado-e-escolha-do-checkout). `checkout_url` devolve um link já existente ou `null`. Listar cobranças não cria link nem solicita e-mail. O status retornado considera o vencimento da cobrança. O filtro de status pode levar alguns segundos para refletir alterações; evite consultar continuamente em intervalos curtos para tentar acelerar essa atualização. ## Recuperar uma cobrança [Recuperar uma única cobrança](/br/api/charges/retrieve), com `GET /v1/charges/{id}`, consulta o cadastro, o status e os dados de pagamento em uma única requisição. Use o identificador recebido na criação ou na listagem. A cobrança precisa pertencer à empresa e ao ambiente autenticado. `payment_information.pix_status` e `payment_information.pix_error` informam o resultado da emissão do Pix. Para boleto, confira `boleto_status` e `boleto_error` no mesmo objeto. Se a criação retornou `202`, use o mesmo ID nessa consulta. A resposta pode continuar pendente; consultas repetidas não reiniciam a emissão. Use `status` para acompanhar a situação da cobrança e `is_payable` para saber se ela pode receber pagamento. `payment_method` informa o meio atual da cobrança; `payment_method_types` informa a lista própria configurada ou `null` para herança; `checkout_payment_method` informa o meio usado para gerar o pagamento, ou `null` antes da geração. Selecionar uma opção na tela não confirma emissão nem pagamento. Ao criar com `payment_method: 1`, confira `payment_information.pix`; com `payment_method: 2`, confira `payment_information.boleto` para obter os dados disponíveis. O objeto `payment_information` reúne o QR Code, o Pix copia e cola e sua expiração, ou os dados do boleto já emitido. Pix e boleto podem ser emitidos na criação com o respectivo `payment_method` ou após a escolha no checkout. Antes da emissão, a cobrança pode aceitar pagamento sem ter dados de Pix ou boleto. Quando não há uma emissão disponível para o meio escolhido ou a cobrança não pode receber pagamento, os dados ficam nulos. O cadastro e o status continuam disponíveis, inclusive para cobranças pagas, canceladas ou expiradas. A consulta devolve o link do checkout existente ou `null`. Ela não altera a cobrança nem gera ou renova Pix, boleto ou link. Também não solicita envio de e-mail. Consultas repetidas não aceleram a emissão ou a confirmação do pagamento. A listagem mostra um resumo da cobrança e seu status, sem os dados de Pix e boleto. Para consultar quantidades, valores e taxa de pagamento, veja [Estatísticas de cobranças](/br/api/balances/overview#estatísticas-de-cobranças) em Informações financeiras. ## Boleto em PDF Use [Baixar boleto](/br/api/charges/boleto), com `GET /v1/charges/{id}/boleto`, para obter o PDF de um boleto já emitido. O identificador é o da cobrança. Você pode anexar o arquivo ao seu sistema ou entregá-lo ao cliente sem abrir o checkout. A requisição exige autenticação na mesma empresa e ambiente. O download exige um boleto emitido, com os dados necessários para gerar o arquivo. Você pode obtê-lo enquanto ele aguarda pagamento, na compensação e após a liquidação. Um boleto cancelado, com falha ou sem os dados de emissão não tem PDF disponível. A expiração da cobrança, por si só, não confirma o cancelamento do boleto. Se receber `BOLETO_DOCUMENT_NOT_AVAILABLE`, consulte a cobrança para conferir a emissão e o andamento do boleto. Repetir o download não emite nem renova o boleto e não muda seu vencimento. O endpoint retorna JSON com `url` e `expires_at`. Faça um GET na `url` completa para baixar o PDF em `files.raims.com`, sem enviar `Authorization` ou a chave de API nesse download. `expires_at` informa a expiração em segundos Unix UTC; depois dela, consulte novamente o endpoint autenticado. Um link inválido ou expirado pode receber HTTP `403` no download, sem o envelope JSON de erros da API. A URL pode ser reutilizada até expirar e permite acesso a quem a possuir. Compartilhe-a somente com pessoas autorizadas e não a registre em logs. O documento contém as instruções do boleto e não comprova pagamento. No Sandbox, ele é identificado como simulação e não deve ser usado para pagar. Para comprovar um pagamento confirmado, use o recibo descrito a seguir. ## Dados do pagamento e recibo Use [Consultar dados do pagamento](/br/api/charges/payment), com `GET /v1/charges/{id}/payment`, para obter os dados de um pagamento confirmado e apresentá-los no seu sistema. Para receber o documento pronto, use [Baixar recibo de pagamento](/br/api/charges/receipt), com `GET /v1/charges/{id}/receipt`. O identificador é o da cobrança, com prefixo `ch_`. O recibo fica disponível para cobranças pagas, parcialmente devolvidas ou com contestação vencida pela empresa, desde que o pagamento tenha valor e data registrados. Se o documento não estiver disponível, consulte a cobrança para conferir seu estado antes de tentar novamente. A consulta dos dados informa o valor, o meio de pagamento, a data e os dados cadastrais do pagador e da empresa recebedora. O nome e o documento do pagador são os registrados na cobrança; eles não comprovam a titularidade da conta bancária que realizou o pagamento. Campos sem informação disponível podem ficar `null`. Nos pagamentos Pix de Produção, `end_to_end_id` informa o identificador bancário do recebimento quando ele está disponível. Use-o para conferir o pagamento com o comprovante bancário ou na conciliação do seu sistema. O campo fica `null` quando não há identificação bancária confirmada, nos pagamentos por boleto e no Sandbox. Um valor nulo não desfaz a confirmação do pagamento. Esse identificador é diferente do ID `ch_` da cobrança e dos dados usados para iniciar o Pix. A resposta do endpoint é JSON com `url` e `expires_at`. Faça a requisição pelo servidor da sua integração com chave de API ou sessão OAuth. Baixe o PDF pela `url` completa em `files.raims.com`, sem enviar a chave nesse download. `expires_at` informa a expiração em segundos Unix UTC. Se o link expirar, consulte novamente o endpoint autenticado para obter outro. Um link inválido ou expirado pode receber HTTP `403` no download, sem o envelope JSON de erros da API. A URL pode ser reutilizada até expirar e permite acesso a quem a possuir; compartilhe-a somente com pessoas autorizadas e não a registre em logs. O documento é emitido pela Raims e não substitui nota fiscal ou comprovante bancário. No Sandbox, os dados e o recibo identificam o pagamento como simulado. Uma devolução parcial não muda o valor original do recibo de pagamento. Para comprovar cada devolução concluída, use o [comprovante do estorno](/br/api/refunds/receipt), com o identificador `rf_` da solicitação correspondente. ## Atualizar uma cobrança [Atualizar cobrança existente](/br/api/charges/update), com `PATCH /v1/charges/{id}`, altera o título, a descrição, a referência externa e os dados de `metadata` pelo identificador público. Envie os campos que deseja mudar. Campos omitidos preservam o valor atual; nos campos de texto, `null` ou texto vazio limpa o campo enviado. Um corpo vazio (`{}`) mantém os dados. O mapa `metadata` segue a [atualização por chave](#dados-adicionais-da-integração). Veja como usar `external_reference` em [Referência no seu sistema](/br/api/charges/overview#referência-no-seu-sistema). O valor, o vencimento e o cliente vinculado são definidos na criação e não podem ser alterados por essa requisição. Para cobrar outro valor ou usar outro vencimento, revogue a cobrança elegível. Aguarde a confirmação da revogação antes de criar a cobrança substituta. O vencimento, por si só, não impede editar uma cobrança que permanece aberta. Cobranças pagas, canceladas, devolvidas ou em outros estados finais não permitem editar esses campos. Um pedido que altere somente `metadata` continua permitido em uma cobrança existente; veja [Dados adicionais da integração](#dados-adicionais-da-integração). Se o estado impedir a edição, `CHARGE_NOT_UPDATABLE` informa o estado atual e os aceitos. Consulte a cobrança antes de decidir como continuar; a edição não altera seu estado financeiro. A edição mantém o identificador, o status e os dados de pagamento. Ela não gera ou renova Pix, boleto ou link de checkout, nem solicita envio de e-mail. ## Revogar uma cobrança [Revogar cobrança](/br/api/charges/revoke), com `DELETE /v1/charges/{id}`, cancela uma cobrança que não deve mais receber pagamento. Use o ID da criação ou da consulta, na mesma empresa e no mesmo ambiente autenticado. Em Sandbox, você pode testar a revogação sem movimentar valores reais. Para conferir o acompanhamento de um cancelamento pendente ou com falha, prepare o resultado no recurso de [Simulação](/br/api/simulations/overview#emissão-e-cancelamento-com-pendência-ou-falha) antes de enviar a revogação. Em Produção, a revogação depende do status da cobrança e dos dados de pagamento já emitidos. Para Pix emitido, o cancelamento precisa ser confirmado. Para boleto, o pedido pode continuar pendente até a confirmação. Acompanhe a mesma cobrança pela [consulta individual](/br/api/charges/retrieve); um pedido aceito não significa cancelamento concluído. Se não receber a confirmação do cancelamento, consulte a mesma cobrança antes de tentar novamente. Uma recusa por `CHARGE_NOT_REVOCABLE` informa o estado ou a condição do pagamento que impediu a ação. Boleto ainda em emissão, pagamento já identificado e cancelamento recusado exigem acompanhamentos diferentes. Confira a mensagem e a cobrança; a revogação não é uma forma de estornar. O cadastro e o histórico continuam disponíveis para consulta após a revogação. Se repetir a requisição para uma cobrança já cancelada na mesma empresa e ambiente, receberá a mesma confirmação. Para voltar a cobrar, crie outra cobrança. Uma cobrança Pix paga pode seguir o fluxo de [estorno](/br/api/refunds/overview). Revogar não estorna, reembolsa ou devolve valores e não solicita envio de e-mail. Consulte os campos e as respostas em [Criar nova cobrança](/br/api/charges), [Listar cobranças](/br/api/charges/list), [Recuperar uma única cobrança](/br/api/charges/retrieve), [Atualizar cobrança existente](/br/api/charges/update) e [Revogar cobrança](/br/api/charges/revoke). Para preparar a credencial da integração, consulte [Autenticação](/br/integracoes/autenticacao). # Consultar dados do pagamento (/br/api/charges/payment) Obtenha o valor, a data e os dados cadastrais associados ao pagamento de uma cobrança. Nos recebimentos Pix, a resposta inclui o identificador bancário quando disponível. Use essa consulta para apresentar o recibo no seu sistema ou conferir o pagamento com o pedido do cliente. Os dados ficam disponíveis após a confirmação do pagamento. Para baixar o documento pronto, use [Baixar recibo de pagamento](/br/api/charges/receipt). Consulte as condições e o significado dos dados em [Dados do pagamento e recibo](/br/api/charges/overview#dados-do-pagamento-e-recibo). GET /v1/charges/{id}/payment # Baixar recibo de pagamento (/br/api/charges/receipt) Obtenha uma URL temporária para baixar o recibo de pagamento da cobrança. Consulte este endpoint com sua chave de API ou sessão OAuth e use a `url` retornada para baixar o PDF em `files.raims.com`, sem enviar a chave nesse download. O recibo é emitido pela Raims e não substitui uma nota fiscal ou um comprovante bancário. Veja as condições em [Dados do pagamento e recibo](/br/api/charges/overview#dados-do-pagamento-e-recibo). GET /v1/charges/{id}/receipt # Recuperar uma única cobrança (/br/api/charges/retrieve) Consulta uma cobrança pelo identificador recebido na criação ou na listagem. Use esta requisição para acompanhar a situação da cobrança ou obter o QR Code, o Pix copia e cola e os dados do boleto já emitido. A cobrança precisa pertencer à empresa e ao ambiente autenticado. A consulta lê os dados existentes e não emite nem renova Pix, boleto ou link de checkout. Veja quando os dados de pagamento ficam disponíveis em [Recuperar uma cobrança](/br/api/charges/overview#recuperar-uma-cobrança). GET /v1/charges/{id} # Revogar cobrança (/br/api/charges/revoke) Revoga uma cobrança pelo identificador público. Use esta requisição quando a cobrança não deve mais receber pagamento. Ela precisa pertencer à empresa e ao ambiente autenticado. O cadastro e o histórico permanecem disponíveis para consulta; a revogação não estorna nem devolve valores pagos. O cancelamento pode depender de confirmação bancária. Se o pedido continuar pendente ou terminar sem um resultado conclusivo, acompanhe a mesma cobrança pela [consulta individual](/br/api/charges/retrieve) antes de tentar novamente. Considere a cobrança cancelada somente após a confirmação. Veja as diferenças entre Sandbox e Produção e como acompanhar a confirmação em [Revogar uma cobrança](/br/api/charges/overview#revogar-uma-cobrança). DELETE /v1/charges/{id} # Consultar estatísticas de cobranças (/br/api/charges/statistics) Consulte os totais de cobranças e pagamentos da sua empresa para acompanhar o desempenho em um ERP, relatório ou painel próprio. Escolha o período desejado; a resposta reúne quantidades, valores e taxa de pagamento. Os valores são brutos e podem levar alguns segundos para refletir mudanças. Veja como interpretar cada total em [Estatísticas de cobranças](/br/api/balances/overview#estatísticas-de-cobranças). GET /v1/charges/statistics # Atualizar cobrança existente (/br/api/charges/update) Atualiza o título, a descrição, a referência externa e os dados de `metadata` de uma cobrança existente. Use o identificador recebido na criação ou na consulta da cobrança, na empresa e no ambiente da sua chave de API. Envie apenas os campos que deseja alterar. Campos omitidos mantêm o valor atual; nos campos de texto, `null` ou texto vazio limpa o campo enviado. Um corpo vazio (`{}`) preserva os dados. Valor, vencimento e cliente vinculado permanecem como definidos na criação. O mapa `metadata` é atualizado por chave. Veja como acrescentar ou remover valores em [Dados adicionais da integração](/br/api/charges/overview#dados-adicionais-da-integração). A edição aceita cobranças que permanecem abertas, inclusive após o vencimento. Cobranças pagas, canceladas, devolvidas ou em outros estados finais permitem alterar somente `metadata`. Se você misturar esses dados com os outros campos em um pedido recusado pelo estado, nada será alterado. Veja as regras de edição e substituição em [Atualizar uma cobrança](/br/api/charges/overview#atualizar-uma-cobrança). Para relacionar a cobrança ao seu sistema, consulte [Referência no seu sistema](/br/api/charges/overview#referência-no-seu-sistema). PATCH /v1/charges/{id} # Códigos HTTP das respostas (/br/api/codigos-http-das-respostas) Use o código HTTP junto ao corpo da resposta para identificar o resultado de uma requisição. Um mesmo código HTTP pode representar erros diferentes; confira também `error.code`, `error.message` e `error.details`, quando presente. * respostas `2xx` indicam sucesso; * respostas `4xx` indicam problemas relacionados à requisição, autenticação, autorização, recurso ou limites; * respostas `5xx` indicam falha no processamento pela Raims. ## Códigos das respostas | Código HTTP | O que indica | Como tratar | | ---------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `200 OK` | A requisição foi processada com sucesso. | Interprete o corpo conforme o endpoint utilizado. | | `201 Created` | Um recurso foi criado. | Armazene o identificador retornado para reconhecer o recurso nas próximas requisições. | | `202 Accepted` | A requisição foi aceita, mas o resultado ainda não foi confirmado. | Guarde o identificador e acompanhe o recurso indicado pelo endpoint antes de repetir a solicitação. | | `400 Bad Request` | Os dados da requisição estão inválidos ou incompletos. | Consulte a mensagem e os campos indicados na resposta para corrigir a requisição. | | `401 Unauthorized` | A credencial está ausente, inválida ou não pode ser usada. | Confira o header `Authorization: Bearer`, a credencial e, em uma sessão OAuth, a necessidade de renovar o acesso ou autorizar novamente. | | `403 Forbidden` | O acesso foi recusado por uma condição da empresa, uma restrição de IP ou uma regra de autorização. | Confira `error.code`, a situação da conta, as permissões e os IPs permitidos pela chave. O console da documentação aceita somente chaves de Sandbox. | | `404 Not Found` | A URL ou o recurso solicitado não foi encontrado. | Confira o método, o caminho e o identificador utilizados. | | `405 Method Not Allowed` | O método HTTP não é aceito nessa rota. | Use o método indicado para a requisição. O header `Allow`, quando presente, informa os métodos aceitos. | | `409 Conflict` | A condição atual do recurso ou outra solicitação em andamento impede o processamento do pedido. | Consulte `error.code` e `error.message`. Corrija a condição indicada; para uma solicitação em andamento, aguarde `Retry-After`, quando presente, antes de repetir. | | `413 Payload Too Large` | O corpo excede o limite permitido para a requisição. | Reduza o corpo enviado e respeite o limite documentado para o endpoint. | | `415 Unsupported Media Type` | O formato do corpo não é aceito. | Para requisições com corpo JSON, envie `Content-Type: application/json`. | | `422 Unprocessable Entity` | A solicitação não pôde ser processada nas condições informadas. | Confira `error.code` e `error.message` antes de reenviar o pedido. | | `429 Too Many Requests` | O limite ou o intervalo de espera da requisição foi atingido. | Aguarde os segundos informados em `Retry-After`, quando presente, antes de tentar novamente. | | `500 Internal Server Error` | Uma falha interna impediu a conclusão normal da resposta. | Confira o resultado da requisição antes de repetir uma solicitação que cria ou altera dados. | | `502 Bad Gateway` | Um serviço de pagamento recusou a solicitação. | Confira o resultado e o código de erro antes de decidir sobre outro pedido. | | `503 Service Unavailable` | Um serviço necessário está temporariamente indisponível. | Aguarde antes de tentar novamente e confira o resultado de requisições que possam ter sido processadas. | As páginas dos endpoints apresentam os sucessos, as validações e os erros específicos da requisição, inclusive quando usam um código HTTP descrito aqui. Consulte a seção Respostas do endpoint para conhecer suas condições e exemplos. Os erros gerais desta página também podem ocorrer nesses endpoints, mesmo quando não aparecem novamente em Respostas. `409 REQUEST_IN_PROGRESS` indica que outra solicitação ainda está sendo processada. Aguarde `Retry-After`, quando presente, antes de repetir o pedido. ## Permissões da chave de API `403 API_KEY_PERMISSION_DENIED` indica que a chave não tem acesso ao recurso ou à operação solicitada. Revise a seleção em **Integração / Chaves de API / Editar permissões** com uma pessoa autorizada a editar chaves. Selecione a ação correspondente ao pedido; criar, consultar, editar e remover são permissões independentes. Repetir a chamada sem mudar o acesso não resolve a recusa. Consulte [Permissões da chave](/br/integracoes/autenticacao#permissões-da-chave). ## Ambiente nas requisições OAuth `400 OAUTH_ENVIRONMENT_REQUIRED` exige informar `X-Raims-Environment` em uma chamada OAuth. `400 OAUTH_ENVIRONMENT_INVALID` indica um valor inválido ou repetido. Informe um único ambiente aceito pelo endpoint e autorizado para a conexão OAuth. Consulte a referência do recurso para conferir os ambientes disponíveis. `403 OAUTH_ENVIRONMENT_FORBIDDEN` indica que a conexão não tem acesso ao ambiente selecionado. `403 OAUTH_SCOPE_FORBIDDEN` indica uma requisição fora das permissões concedidas. Confira a autorização antes de tentar novamente. Com chave de API, o ambiente é definido pela própria chave. Consulte [Autenticação](/br/integracoes/autenticacao). ## Acesso bloqueado pela situação da empresa `403 COMPANY_STATUS_RESTRICTED` indica que a situação da empresa impede o acesso à API. A mensagem identifica a condição e orienta o próximo passo: | Situação | Acesso à API | Como proceder | | ----------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | Empresa suspensa | Bloqueado em Produção e Sandbox. | Contate o SAC em [sac@raims.com](mailto:sac@raims.com). | | Conta encerrada | Bloqueado em Produção e Sandbox. | Contate o SAC em [sac@raims.com](mailto:sac@raims.com) se precisar de ajuda. | | Cadastro pendente | Bloqueado em Produção. Sandbox permanece permitido, sujeito às demais regras. | Consulte a situação do cadastro no Dashboard. | Por exemplo, uma empresa suspensa recebe: ```json { "error": { "code": "COMPANY_STATUS_RESTRICTED", "message": "Your company is suspended and cannot access the API. Contact our support team at sac@raims.com for assistance." } } ``` O contato para essas solicitações da conta é o SAC, conforme os [canais de atendimento da Raims](https://raims.com/br/help). O erro mantém o mesmo código nas situações acima; use a mensagem para diagnóstico humano, sem comparar seu texto na lógica da integração. ## Formato dos erros Os erros da API são retornados em JSON, no objeto `error`, com `code` e `message`. `details` é opcional: aparece quando a resposta precisa identificar um campo inválido ou uma referência enviada no corpo que não foi encontrada. Cada detalhe informa onde corrigir a requisição e explica o motivo. Erros gerais de autenticação, autorização, conflito, limite, rota, JSON malformado, tamanho ou mídia usam somente código e mensagem. A ausência de `details` é normal. Por exemplo, uma chave ausente ou inválida recebe: ```json { "error": { "code": "UNAUTHORIZED", "message": "Provide a valid API key or OAuth access token in the Authorization: Bearer header." } } ``` As mensagens em `error.message` e `error.details[].message` são escritas em inglês. A documentação explica as condições e como tratá-las em português. Identifique o erro pelo status HTTP e por `error.code`. Para corrigir campos, use também `error.details[].field` e `error.details[].code`. Nunca compare o texto das mensagens na lógica da integração: ele pode mudar sem alterar o significado dos códigos. Seu sistema pode usar esses códigos para apresentar uma mensagem no idioma do cliente. Em validações de campos, `error.message` resume a categoria do erro. `error.details` mantém cada campo ou item da lista com seu código e sua explicação, sem repetir esse conteúdo no resumo. Confira todos os detalhes antes de reenviar. ### Como localizar o problema Cada item de `error.details` informa: | Campo | Como usar | | --------- | ------------------------------------------------------------------------------------------------------ | | `field` | Identifica o campo enviado, incluindo o caminho quando ele pertence a um objeto ou a um item de lista. | | `code` | Identifica a condição para tratar o erro no seu sistema. | | `message` | Explica em inglês o problema naquele campo. | Por exemplo, `customer_id` identifica o cliente da cobrança; `id` identifica o recurso informado no caminho da URL. O campo `$` representa o corpo JSON inteiro quando a validação exige outro tipo, como um objeto em vez de array. Parâmetros de consulta e rota usam seus nomes públicos. Confira todos os detalhes recebidos antes de reenviar a requisição. ### Exemplo de resposta HTTP 400 ```json { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "tax_id", "code": "REQUIRED", "message": "tax_id is required." } ] } } ``` `REQUIRED` indica um campo obrigatório ausente; `MIN_LENGTH` indica um valor abaixo do tamanho mínimo; `MAX_LENGTH` indica que o tamanho permitido foi ultrapassado. `INVALID_TAXID` indica um CPF ou CNPJ inválido; `INVALID_EMAIL` indica um e-mail inválido. `MAX_ITEMS` indica que uma coleção contém mais itens do que o limite aceito pela requisição. `MUTUALLY_EXCLUSIVE` indica campos que não podem ser preenchidos juntos, como `after` e `before` na paginação. Envie somente um deles. Confira também as regras da requisição. ## Recurso não encontrado Um `404 NOT_FOUND` pode indicar que o recurso consultado não está disponível para a empresa e o ambiente autenticado. Ao consultar um cliente por `id`, a mensagem identifica o recurso, sem detalhes adicionais: ```json { "error": { "code": "NOT_FOUND", "message": "The customer specified by id was not found." } } ``` Quando a referência foi enviada no corpo, como `customer_id` ao criar uma cobrança, a resposta usa `details` para identificar o campo a conferir: ```json { "error": { "code": "NOT_FOUND", "message": "A referenced resource was not found.", "details": [ { "field": "customer_id", "code": "NOT_FOUND", "message": "The customer specified by customer_id was not found." } ] } } ``` Confira o identificador e use a chave da empresa e do ambiente em que o recurso foi cadastrado. Essa resposta não confirma a existência do recurso em outra conta ou ambiente. Uma listagem sem resultados continua retornando uma lista vazia, conforme as regras do endpoint. Uma URL desconhecida também retorna `404`, mas sua mensagem indica o método e o caminho que não foram reconhecidos. Nesse caso, confira o endereço do endpoint na referência. ## JSON malformado e campos inválidos `INVALID_JSON` indica que o corpo não pôde ser interpretado como JSON, por exemplo, por uma vírgula ou aspas fora do lugar. Corrija a estrutura do corpo antes de reenviar a requisição. Quando o JSON está bem formado, mas contém campos desconhecidos, repetidos ou com um tipo incompatível, a resposta usa `INVALID_FIELDS` e identifica o problema em `error.details`: | Código em `details` | O que corrigir | | ------------------- | ---------------------------------------------------------------- | | `UNKNOWN_FIELD` | Remova o campo indicado ou corrija seu nome conforme o endpoint. | | `DUPLICATE_FIELD` | Envie o campo uma única vez no mesmo objeto. | | `INVALID_TYPE` | Use o tipo indicado no endpoint, como uma string para `tax_id`. | Por exemplo, enviar `tax_id` como número em vez de string retorna: ```json { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "tax_id", "code": "INVALID_TYPE", "message": "tax_id must be a JSON string." } ] } } ``` Quando o endpoint exige um objeto e recebe outro tipo de JSON, como um array, `field` usa `$` para indicar o corpo inteiro, com o código `INVALID_TYPE`. Campos obrigatórios ausentes e valores que não atendem às regras do endpoint continuam usando `INVALID_FIELDS`, com os códigos de validação correspondentes. Quando `error.details` indicar `field: tax_id` e `code: INVALID_TAXID`, consulte [Validação de CPF e CNPJ](/br/integracoes/validacao-cpf-cnpj#como-tratar-invalid_taxid). O guia explica como conferir o documento antes da requisição e orientar sua correção no sistema da integração. ## Conflitos de estado e condições de uso Um erro de estado informa a condição atual do recurso e os estados aceitos para a ação. O mesmo código pode ter explicações diferentes conforme a condição que impediu a requisição. Use `error.code` para tratar o motivo e leia `error.message` para entender a condição observada. Confira os exemplos específicos em Respostas e consulte o recurso antes de tentar novamente. Estar em um estado aceito não garante que as outras condições da requisição estejam atendidas. Alguns endpoints oferecem consultas para conferir a elegibilidade ou a disponibilidade de um recurso. Consulte a referência do endpoint para identificar a consulta e as condições aplicáveis. ## Limites de requisições `429 RATE_LIMITED` indica uma recusa por excesso de requisições. Aguarde `Retry-After` e ajuste a frequência ou a concorrência conforme `Raims-Rate-Limited-Reason`. Alguns endpoints têm regras e intervalos próprios, descritos na sua referência. O [guia de rate limiting](/br/integracoes/rate-limiting) explica os limites por empresa e ambiente, os motivos, as novas tentativas e um exemplo de consulta com fila. ## Falhas temporárias e resultados incertos Uma resposta `503` pode indicar indisponibilidade temporária ao autenticar, consultar dados ou usar um serviço de pagamento. Confira `error.code` e `error.message` para identificar a causa informada. `503 OAUTH_AUTHORIZATION_UNAVAILABLE` indica que o acesso atual não pôde ser confirmado. `503 OAUTH_AUTHORIZATION_CHANGED` informa que a autorização mudou durante a requisição e o resultado pode já ter sido aplicado. Depois de regularizar o acesso, consulte o recurso antes de repetir uma escrita. Ao retomar a requisição pela mesma conexão, preserve a `Idempotency-Key` original. Se precisar autorizar uma nova conexão, confira o resultado da tentativa anterior antes de enviar outra requisição. `503 RATE_LIMIT_STORE_UNAVAILABLE` indica que a API não pôde aceitar a requisição e ela não foi executada. Aguarde `Retry-After` antes de tentar novamente. Mesmo com uma resposta `500`, `502` ou `503`, ou uma conexão interrompida, a requisição pode ter sido processada. Antes de repetir uma chamada que cria ou altera dados, confira o resultado e siga as orientações do endpoint. Evite repetir requisições continuamente durante uma falha. Quando a resposta trouxer `Retry-After`, aguarde o número de segundos indicado. Esse header não aparece em todas as falhas. `Transient-Error: true`, quando presente, indica uma falha temporária. Você ainda precisa conferir o resultado antes de repetir uma requisição que cria ou altera dados. Ao pedir ajuda ao suporte, informe o método, o caminho, o horário, o status HTTP e o código de erro. Remova chaves de API e dados pessoais dos exemplos compartilhados. # Criar um cliente (/br/api/customers) Cria ou atualiza um cliente pelo CPF ou CNPJ na empresa e no ambiente autenticado. Um documento já cadastrado atualiza o cliente existente e mantém seu identificador. Quando somente `zip_code` é informado para o endereço, a Raims pode preencher `street`, `neigh`, `city` e `uf` com os dados do CEP. Para usar esse preenchimento, deixe `street`, `neigh`, `city`, `uf`, `street_number` e `complement` sem valor. Qualquer dado nesses campos impede o preenchimento automático; campos vazios ou só com espaços não impedem. Se o CEP não for encontrado, o cliente ainda pode ser cadastrado. Consulte [Criar um cliente](/br/api/customers/overview#criar-um-cliente) para ver as regras do cadastro. Use a [referência no seu sistema](/br/api/customers/overview#referência-no-seu-sistema) para relacionar esse cliente ao identificador usado na sua integração. POST /v1/customers # Remover cliente (/br/api/customers/delete) Remove um cliente pelo identificador público quando o cadastro não será mais utilizado. Ele precisa pertencer à empresa e ao ambiente autenticado. A remoção é permitida somente quando o cliente não tem cobranças vinculadas que ainda não foram removidas, inclusive cobranças pagas. Se houver uma dessas cobranças, o cliente é preservado. Esta requisição não remove cobranças nem devolve valores pagos. Se repetir a requisição para um cliente já removido da mesma empresa e ambiente, receberá a mesma confirmação. Veja como a remoção afeta as consultas em [Remover cliente](/br/api/customers/overview#remover-cliente). DELETE /v1/customers/{id} # Remover clientes em lote (/br/api/customers/delete-batch) Remove vários clientes da empresa e do ambiente autenticado em uma única requisição, usando os identificadores públicos retornados pela API. A remoção de cada cliente segue as mesmas condições de [Remover cliente](/br/api/customers/delete): cobranças vinculadas que ainda não foram removidas, inclusive pagas, impedem a remoção. A requisição não remove cobranças nem devolve valores. Alguns clientes do lote podem ser removidos e outros não. Confira os grupos `removed`, `blocked` e `invalid` para saber o resultado de cada cliente. O array `errors` explica cada impedimento e identifica a posição no pedido, como `identifiers[2]` para o terceiro item. Corrija somente os itens indicados. Se enviar novamente o ID de um cliente já removido, receberá a mesma confirmação. Veja como acompanhar o resultado em [Remover clientes em lote](/br/api/customers/overview#remover-clientes-em-lote). DELETE /v1/customers # Listar clientes (/br/api/customers/list) Consulta os clientes cadastrados na empresa e no ambiente autenticado. Use os filtros para localizar um cliente pelo identificador, nome, e-mail, CPF/CNPJ ou referência externa do seu sistema. Comece sem cursor, processe `list` e, enquanto `page.has_next` for `true`, copie `page.next_after` para `after`, mantendo os filtros. Copie o cursor inteiro, sem interpretar ou calcular seu conteúdo. Consulte [Listagem e paginação](/br/api/listagem-e-paginacao) para voltar com `before`. Veja como os filtros e a ordenação funcionam em [Listar clientes](/br/api/customers/overview#listar-clientes). GET /v1/customers # Clientes (/br/api/customers/overview) Cadastre como cliente a pessoa ou empresa que vai pagar à sua conta Raims. O CPF ou CNPJ identifica o cliente; você também pode informar nome, contato e endereço. Os clientes pertencem à empresa e ao ambiente autenticado na solicitação. Cadastros de Sandbox e de Produção ficam separados. A base das requisições é `https://api.raims.com`. Telefone e código de discagem são opcionais. Você pode informar um deles sem preencher o outro. A API não verifica se o número segue as regras de telefonia do país. Cadastrar um telefone não confirma que ele esteja ativo ou pertença ao cliente. ## Criar um cliente A requisição [Criar um cliente](/br/api/customers), com `POST /v1/customers`, recebe os dados do cadastro e devolve um identificador com prefixo `cus_`. Guarde esse identificador no seu sistema para reconhecer o cliente cadastrado. CPF ou CNPJ é obrigatório. Nome, contato e endereço são opcionais. Um documento já cadastrado na mesma empresa e no mesmo ambiente atualiza o cliente existente, mantendo seu identificador. Se a requisição terminar sem uma resposta conclusiva, confira o cadastro antes de repetir o pedido. Valide o CPF ou CNPJ no formulário e no servidor da sua integração antes de enviar o cadastro. O guia de [Validação de CPF e CNPJ](/br/integracoes/validacao-cpf-cnpj) explica os dígitos verificadores, o CNPJ alfanumérico e o tratamento de `INVALID_TAXID` para orientar a correção do campo pelo usuário. Ao informar somente `zip_code` para o endereço, a Raims pode preencher logradouro, bairro, cidade e UF com os dados disponíveis para o CEP. Qualquer valor em rua, bairro, cidade, UF, número ou complemento impede o preenchimento automático. Nesse caso, envie os dados do endereço que deseja cadastrar. Campos vazios ou só com espaços não impedem o preenchimento pelo CEP. Se o CEP não for encontrado, o cliente ainda pode ser cadastrado. ## Referência no seu sistema Envie em `external_reference` o identificador do cliente no seu sistema. A referência aparece nas consultas e pode ser alterada ou removida sem mudar o ID da Raims. Omitir esse campo mantém a referência atual, tanto no cadastro pelo mesmo CPF/CNPJ quanto na atualização por ID. Para localizar o cadastro pelo código do seu sistema, informe `external_reference` na [listagem de clientes](/br/api/customers/list). A busca compara o valor completo e distingue maiúsculas, minúsculas e acentos. Por exemplo, `ERP-123` não encontra `erp-123` nem valores que apenas contenham `123`. A referência pode se repetir em clientes diferentes; use também o `id` retornado para identificar cada cadastro. ## Dados adicionais da integração Use `metadata` para associar pequenas informações do seu sistema ao cliente, como o código da filial ou o canal de cadastro. Envie um objeto com nomes de chaves e valores em texto: ```json { "metadata": { "filial": "SP-01", "canal": "loja" } } ``` O mapa aceita até 32 chaves. Os nomes usam letras sem acentos, números, ponto, hífen ou sublinhado e diferenciam maiúsculas de minúsculas. Os limites de tamanho também são conferidos no mapa resultante de uma atualização, incluindo as chaves já existentes. Não use esse campo para senhas, tokens, documentos pessoais ou outros dados sensíveis. Se `metadata` não for informado ao criar um cliente, o mapa fica vazio. Ao cadastrar novamente um CPF/CNPJ existente ou atualizar por ID, as chaves enviadas são adicionadas ou substituídas; as demais permanecem. Omitir `metadata` ou enviar `{}` preserva o mapa. Envie `null` como valor de uma chave para removê-la, ou `metadata: null` para remover todas. Um texto vazio é um valor válido e não remove a chave. As respostas de cadastro, atualização e consulta retornam `metadata`, com `{}` quando não há valores. Esses dados não são filtros de pesquisa nem entram automaticamente no corpo dos webhooks. ## Listar clientes A requisição [Listar clientes](/br/api/customers/list), com `GET /v1/customers`, consulta os cadastros da empresa e do ambiente autenticado. Você pode filtrar por identificador, nome, e-mail, CPF/CNPJ ou referência externa e receber até 100 clientes por página. Sem `page_size`, a página contém até 10 clientes. Envie os filtros na URL, sem corpo JSON. Deixe vazios os filtros que não quiser usar. A resposta contém `list` e `page`. Comece sem cursor e processe os clientes de `list`. Enquanto `page.has_next` for `true`, copie `page.next_after` para `after` na próxima requisição, mantendo os filtros. Copie o valor completo, sem interpretar ou calcular seu conteúdo. O guia de [Listagem e paginação](/br/api/listagem-e-paginacao) também explica como voltar com `before`. Envie apenas um cursor por requisição; não preencha `after` e `before` juntos. Um cursor vazio ou só com espaços não é usado na consulta. Na listagem de clientes, remover o registro que marcava a posição de um cursor válido não gera erro. A busca continua com os mesmos filtros e na direção solicitada, sem usar essa posição anterior. A página pode repetir clientes já recebidos; use os novos cursores retornados para continuar. Cursores alterados ou pertencentes a outra empresa, ambiente ou consulta continuam sendo recusados com `400 INVALID_FIELDS` e `INVALID_CURSOR`. Os cadastros mais recentes aparecem primeiro, inclusive na busca por nome. Para buscar pelo nome, informe pelo menos dois caracteres, sem contar espaços no início ou no fim. Um filtro vazio ou só com espaços não restringe a busca. A busca por referência externa pode ser combinada com os demais filtros. Cadastros novos ou alterações podem levar alguns segundos para aparecer nessa busca. Evite consultas contínuas em intervalos curtos. Preserve a referência e os demais filtros ao continuar a paginação. ## Recuperar um único cliente Se você já tem o identificador com prefixo `cus_`, use [Recuperar um único cliente](/br/api/customers/retrieve), com `GET /v1/customers/{id}`, para consultar seus dados. Use o `id` retornado pela API, sem alterações, no caminho da URL. A consulta não recebe corpo JSON. A consulta permite conferir o cadastro sem percorrer a listagem. O cliente precisa pertencer à empresa e ao ambiente autenticado. Se não estiver disponível para essa chave, confira o identificador e a credencial usados. ## Atualizar cliente existente Use [Atualizar cliente existente](/br/api/customers/update) quando já tiver o `id` e precisar alterar nome, contato, endereço ou dados adicionais da integração, com `PATCH /v1/customers/{id}`. Informe o identificador no caminho e envie somente os campos que deseja mudar. Campos omitidos preservam o valor atual. Nos campos de texto opcionais, enviar `null` ou um valor vazio limpa o campo. O mapa `metadata` segue a [atualização por chave](#dados-adicionais-da-integração). O identificador e o CPF ou CNPJ permanecem os mesmos. Esta requisição não cria clientes e exige um cadastro da mesma empresa e do mesmo ambiente autenticado. Você pode alterar os campos de telefone separadamente. Alterar `zip_code` não preenche automaticamente os demais campos do endereço. ## Remover cliente Use [Remover cliente](/br/api/customers/delete) quando não for mais usar o cadastro, com `DELETE /v1/customers/{id}`. Informe o `id` retornado pela API no caminho. A requisição não tem corpo; o cliente precisa pertencer à empresa e ao ambiente autenticado. O cliente só pode ser removido quando não tem cobranças vinculadas que ainda não foram removidas, inclusive cobranças pagas. Caso contrário, o cadastro é preservado. A remoção do cliente não remove cobranças nem devolve valores. Se receber `CUSTOMER_HAS_CHARGES`, use `GET /v1/charges` com o filtro `customer_id` para identificar os vínculos. A referência do endpoint está em [Listar cobranças](https://docs.raims.com/br/api/charges/list). Cobranças pagas ou canceladas também impedem a remoção enquanto permanecem no cadastro. Revogar uma cobrança não apaga esse vínculo. O cliente deixa de aparecer na listagem e na consulta por ID. Se repetir a requisição para um cliente já removido da mesma empresa e ambiente, receberá a mesma confirmação. ## Remover clientes em lote [Remover clientes em lote](/br/api/customers/delete-batch) usa `DELETE /v1/customers` e recebe de 1 a 100 IDs no array `identifiers` do corpo JSON. Os resultados são separados em `removed`, `blocked` e `invalid`. Clientes com cobranças ainda não removidas, inclusive pagas, continuam cadastrados. Confira cada grupo para saber quais clientes foram removidos. O array `errors` identifica a posição de cada item com problema e explica o motivo. Por exemplo, `identifiers[2]` corresponde ao terceiro item do pedido. Use essas informações para corrigir os itens que não foram removidos. Consulte a página de cada endpoint para ver os campos, os exemplos de código e as respostas da API. Para preparar a credencial da integração, consulte [Chaves de API](/br/integracoes/chaves-api). # Recuperar um único cliente (/br/api/customers/retrieve) Consulta os dados de um cliente pelo identificador público recebido na criação ou na listagem. Use o `id` retornado pela API, sem alterações. O cadastro precisa pertencer à empresa e ao ambiente autenticado. Veja como usar o identificador na integração em [Recuperar um único cliente](/br/api/customers/overview#recuperar-um-único-cliente). GET /v1/customers/{id} # Atualizar cliente existente (/br/api/customers/update) Atualiza o cadastro e os dados de integração de um cliente existente pelo identificador público. O cadastro precisa pertencer à empresa e ao ambiente autenticado. Envie apenas os campos que deseja alterar. Campos omitidos mantêm o valor atual. Nos campos de texto opcionais, enviar `null` ou um valor vazio limpa o campo. O identificador e o CPF ou CNPJ permanecem os mesmos; esta requisição não cria um cliente. O mapa `metadata` é atualizado por chave. Veja como acrescentar ou remover valores em [Dados adicionais da integração](/br/api/customers/overview#dados-adicionais-da-integração). O endereço também é atualizado por campo. Alterar `zip_code` não preenche nem substitui automaticamente rua, bairro, cidade ou UF; envie os campos do endereço que deseja mudar. Veja as regras de atualização em [Atualizar cliente existente](/br/api/customers/overview#atualizar-cliente-existente). PATCH /v1/customers/{id} # Listar contestações (/br/api/disputes) Consulta os casos da empresa e do ambiente autenticado, com filtros e ordenação. Use o identificador de um resultado para consultar seus detalhes. Veja [Listar contestações e avançar pelas páginas](/br/api/disputes/overview#listar-contestações-e-avançar-pelas-páginas) para navegar pelas páginas e [Etapas de acompanhamento](/br/api/disputes/overview#etapas-de-acompanhamento) para interpretar o andamento de cada caso. GET /v1/disputes # Contestações (/br/api/disputes/overview) Acompanhe as contestações de pagamentos recebidos pela sua empresa, incluindo casos do Mecanismo Especial de Devolução (MED) do Pix. A API permite consultar os registros e seus resultados disponíveis. | Finalidade | Método e caminho | | ------------------------------------------- | ----------------------- | | Listar contestações e avançar pelas páginas | `GET /v1/disputes` | | Consultar os detalhes de uma contestação | `GET /v1/disputes/{id}` | ## Quando consultar uma contestação Use a listagem para identificar casos e acompanhar suas etapas. Consulte os detalhes quando precisar do motivo, relato, resposta da empresa ou datas disponíveis. Os dados refletem o acompanhamento apresentado pela Raims; consultar a API não abre uma contestação, envia defesa, aceita uma devolução nem movimenta dinheiro. O campo `kind` diferencia `med`, para o procedimento MED do Pix, e `chargeback`, para os demais registros de contestação apresentados pela Raims. Esse campo identifica o tipo do caso e deve ser considerado ao interpretar seus motivos e resultados. ## Listar contestações e avançar pelas páginas Use [Listar contestações](/br/api/disputes). Você pode filtrar pela cobrança, etapa, valor contestado ou intervalo de criação e escolher a ordenação por criação ou valor. O filtro de valor usa igualdade em centavos de real. As datas usam segundos Unix UTC e os limites do intervalo são inclusivos. Comece sem cursor, processe `list` e copie `page.next_after` para `after` enquanto `page.has_next` for verdadeiro. Preserve os filtros e a ordenação durante essa navegação. Para mudar a consulta, comece novamente sem cursor. Para voltar, use `page.previous_before` em `before`. Não envie `after` e `before` preenchidos juntos. Copie o cursor inteiro, sem interpretar ou alterar seu conteúdo. Veja [Listagem e paginação](/br/api/listagem-e-paginacao). Uma lista vazia informa que a página não contém casos que correspondam à consulta. Um filtro por cobrança não concede acesso a dados de outra empresa ou ambiente. ## Consultar uma contestação Use [Recuperar uma contestação](/br/api/disputes/retrieve) com o `id` recebido na listagem. Preserve o identificador completo: a API retorna IDs com prefixo `dp_` ou `med_` conforme o tipo de registro. `charge_id` identifica a cobrança vinculada, ou fica `null` quando não houver vínculo disponível. O detalhe inclui relato, resposta da empresa, motivo e datas quando estiverem disponíveis. `due_at` é o prazo registrado para resposta, ou `null` quando não houver prazo informado. A presença desse campo não significa que a API aceite o envio de uma resposta. ## Etapas de acompanhamento Use `stage` para acompanhar o caso: | `stage` | Significado | | -------------------- | ------------------------------------------------------------ | | `open` | Caso registrado, sem análise confirmada. | | `in_analysis` | Contestação em análise. | | `refund_in_analysis` | Devolução em análise, sem confirmar movimentação financeira. | | `closed` | Análise encerrada. Consulte os resultados disponíveis. | | `cancelled` | Contestação cancelada. | | `rejected` | Solicitação de abertura rejeitada. | | `failed` | O processamento não foi concluído devido a uma falha. | `closed` não significa, por si só, decisão favorável à empresa ou dinheiro devolvido. A etapa informa o andamento; os campos de resultado descrevem o que foi confirmado para aquele caso. Consultas repetidas não iniciam ou aceleram sua análise. ## Motivos e resultados Interprete `reason_code` junto de `kind`. O mesmo número pode representar motivos diferentes: | Código | `kind: med` | `kind: chargeback` | | ------ | ----------------------- | ------------------------------ | | `1` | Relato de golpe. | Alegação de fraude. | | `2` | Conta invadida. | Compra não reconhecida. | | `3` | Coação. | Serviço não reconhecido. | | `4` | Acesso fraudulento. | Produto ou serviço divergente. | | `5` | Outro motivo. | Cobrança indevida. | | `6` | Categoria desconhecida. | Outro motivo. | `reason_code: null` informa que o motivo não está disponível. Nos casos MED, `infraction_result` pode ser `agreed` para infração reconhecida ou `disagreed` para infração não reconhecida. `refund_result` pode ser `partially_accepted`, `totally_accepted` ou `rejected`, conforme a análise da devolução. Esses resultados não confirmam, sozinhos, que o dinheiro foi devolvido. `refunded_amount_cents` informa o total de devoluções confirmadas do caso MED. Nos registros `chargeback`, `won_amount_cents` e `lost_amount_cents` informam os valores de decisão favorável ou desfavorável à empresa, quando disponíveis. Cada campo fica `null` quando não se aplica ao tipo de caso ou quando não há resultado disponível; preserve a diferença entre `null` e um valor zero confirmado. `loss_reason_code`, quando informado, identifica prazo de resposta expirado (`1`), evidências insuficientes (`2`), documentação inválida (`3`), decisão final (`4`) ou outro motivo (`5`). `loss_reason_note` complementa esse motivo quando houver uma observação disponível. ## Empresa e ambiente As consultas seguem a [autenticação](/br/integracoes/autenticacao) por chave de API ou OAuth, com a empresa e o ambiente autorizados. Uma chave Sandbox consulta somente esse ambiente; ela não acessa contestações de Produção. O console desta documentação aceita somente chaves Sandbox. Use o identificador retornado pela Raims e trate os erros pelo status HTTP e por `error.code`. Nas falhas de validação, consulte também os campos indicados em `error.details`. A consulta individual retorna o mesmo erro quando o caso não existe ou não está disponível para a autenticação utilizada. # Recuperar uma contestação (/br/api/disputes/retrieve) Consulta uma contestação pelo identificador retornado na listagem. A etapa encerrada não confirma, sozinha, uma decisão favorável ou uma devolução de dinheiro. Consulte [Motivos e resultados](/br/api/disputes/overview#motivos-e-resultados) para interpretar os campos conforme o tipo do caso. GET /v1/disputes/{id} # Idempotência (/br/api/idempotencia) Use idempotência quando uma interrupção, um timeout ou a perda da resposta deixar dúvida sobre o processamento de uma requisição. A chave identifica uma mesma intenção durante as tentativas e evita que um retry aceito repita seu efeito. O header é opcional. A página de cada endpoint informa se ele aceita `Idempotency-Key`. ## Quando usar Envie uma chave nas requisições de criação e nas alterações em que repetir o efeito causaria duplicidade ou outra mudança indesejada. A chave não substitui o identificador do recurso, a referência do seu sistema nem a consulta do resultado. O CLI e o console desta documentação não repetem escritas automaticamente. Seu sistema decide quando fazer o retry e deve conservar a mesma chave enquanto trata a mesma intenção. ## Enviar a chave Gere uma chave única no seu sistema e envie-a no header: ```http Idempotency-Key: de305d54-75b4-431b-adb2-eb6b9e546014 ``` UUID é aceito. O valor deve ter de 1 a 255 caracteres ASCII visíveis, sem espaços nem caracteres de controle. Não inclua credenciais, documentos ou outros dados pessoais na chave. Guarde a chave junto do pedido ou ação correspondente. O console mostra o campo em **Cabeçalhos** quando o endpoint aceita idempotência. O valor fica somente na memória da aba, associado à operação e à conta. O console não cria nem troca a chave entre tentativas. ## Repetir a requisição Se a resposta for perdida, repita o mesmo método, caminho, corpo e `Idempotency-Key`. Uma repetição compatível devolve o resultado preservado em vez de executar novamente a requisição. Validações recusadas antes da execução não ficam armazenadas. Respostas `4xx` também não são preservadas. Corrija a requisição antes de tentar novamente e mantenha a mesma chave somente quando a intenção continuar a mesma. Se o armazenamento de idempotência estiver indisponível, uma requisição com o header recebe `503` antes de executar a ação. Essa resposta não é preservada e pode ser repetida com a mesma chave. Sem o header, a requisição segue o fluxo normal do endpoint. Reutilizar a chave com outro método, caminho ou conteúdo recebe `422`. Use a chave somente com a requisição que representa a intenção original. ## Interpretar o resultado Quando a resposta vier de uma repetição preservada, a API envia: ```http Idempotency-Replayed: true ``` O status e o corpo permanecem iguais ao resultado armazenado. Uma resposta `202` ainda representa processamento pendente. Guarde o identificador retornado e acompanhe o mesmo recurso; o replay não transforma a pendência em conclusão. Respostas de sucesso e falhas `5xx` ocorridas depois da admissão ficam preservadas. Por isso, repetir uma chave que recebeu `500` pode devolver o mesmo erro. Consulte o recurso e reconcilie o efeito antes de criar outra chave. Um `409 IDEMPOTENCY_RESULT_UNKNOWN` informa que o endpoint pode ter concluído, mas a resposta não pôde ser preservada. Consulte o recurso antes de repetir. Se a resposta trouxer `Location`, comece por esse endereço. Depois da reconciliação, um retry da mesma intenção mantém a mesma chave; nunca troque a chave para contornar esse estado. ## Retenção e reconciliação O resultado fica disponível por 24 horas. Depois desse prazo, a mesma chave pode iniciar outro processamento. Não use a expiração como forma de resolver uma operação financeira incerta. Antes de trocar a chave, consulte o recurso pelo identificador, use a referência do seu sistema quando houver filtro disponível e processe os webhooks recebidos. Só envie uma nova intenção depois de confirmar o estado atual. # Listagem e paginação (/br/api/listagem-e-paginacao) As listagens paginadas da API Raims dividem os resultados entre requisições. Os itens ficam em `list` e as informações para navegar entre páginas ficam em `page`. ## Como percorrer os resultados **Primeira consulta** Faça a primeira requisição sem `after` nem `before`. **Processar os resultados** Processe os itens recebidos em `list`, inclusive na última página. **Avançar ou encerrar** Se `page.has_next` for `true`, copie `page.next_after` para `after` e repita a consulta. Quando for `false`, encerre a listagem. Copie o cursor completo, sem interpretar seu conteúdo, alterar o valor ou calcular o próximo cursor. Mantenha os mesmos filtros e a mesma ordenação, quando o endpoint permitir escolhê-la, ao percorrer as páginas. Por exemplo, em [Listar clientes](/br/api/customers/list), comece com: ```http GET /v1/customers?page_size=10 ``` Nas consultas seguintes, preencha `after` com o cursor da resposta anterior: | Página | `page_size` | `after` | | -------- | ----------: | ----------------------------------------------- | | Primeira | `10` | Omitido | | Segunda | `10` | Valor de `page.next_after` da primeira resposta | | Terceira | `10` | Valor de `page.next_after` da segunda resposta | Cada nova requisição usa o cursor da página que você acabou de receber. ## Tamanho da página e avanço | Campo | Onde aparece | Descrição | | ----------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page_size` | Requisição | Quantidade máxima de itens por página. Aceita de `1` a `100`; um inteiro positivo acima do máximo usa o máximo. Omitido, vazio, zero, negativo, texto ou decimal usa `10`. | | `after` | Requisição | Cursor recebido em `page.next_after` para consultar a próxima página. | | `list` | Resposta | Itens encontrados na página. Sem resultados, retorna um array vazio. | | `page.page_size` | Resposta | Tamanho de página aplicado à consulta. | | `page.has_next` | Resposta | Indica se há uma próxima página. | | `page.next_after` | Resposta | Cursor para avançar. Quando não há próxima página, retorna `null`. | `page_size` é um limite: uma página pode ter menos itens do que a quantidade solicitada. Use `page.has_next` para decidir se deve continuar. ## Como voltar uma página Quando `page.has_previous` for `true`, envie `page.previous_before` em `before`, mantendo os filtros e a ordenação. Ao voltar, retire `after` da requisição. Ao avançar, retire `before`. | Campo | Onde aparece | Descrição | | ---------------------- | ------------ | --------------------------------------------------------------------------- | | `before` | Requisição | Cursor recebido em `page.previous_before` para consultar a página anterior. | | `page.has_previous` | Resposta | Indica se há uma página anterior. | | `page.previous_before` | Resposta | Cursor para voltar. Quando não há página anterior, retorna `null`. | Envie apenas um cursor por requisição. Informar `after` e `before` com valores na mesma requisição retorna `400 INVALID_FIELDS`, com `MUTUALLY_EXCLUSIVE` nos detalhes dos dois campos. Retire o cursor da direção que não vai usar. Se não for usar um cursor, omita o campo. Deixá-lo vazio ou só com espaços tem o mesmo efeito. ## Cuidados com os cursores O cursor pertence à empresa e ao ambiente autenticado, aos filtros e à ordenação usados na consulta. Para trocar esses critérios, comece uma nova listagem sem cursor. Um cursor alterado ou utilizado em outra consulta pode ser recusado por erro de validação. Se receber `INVALID_CURSOR` em `error.details`, reinicie a listagem sem `after` nem `before`, preservando os filtros desejados. No console da documentação, preencha esses valores em **Parâmetros de consulta**. Eles entram na URL da requisição e nos exemplos de código. Campos vazios são omitidos. **Consultas com filtros** Consulte a referência do endpoint de listagem para conferir os filtros, a ordenação e as regras próprias dos cursores. # Contrato OpenAPI (/br/api/openapi) O repositório [raimshq/openapi](https://github.com/raimshq/openapi) publica o contrato OpenAPI da versão da API Raims disponível para integrações. Use esse contrato para consultar a estrutura dos endpoints, importar a referência em uma ferramenta compatível ou gerar um cliente para o seu projeto. O diretório `latest` acompanha a versão efetivamente publicada da API. Ele não antecipa mudanças que ainda estejam somente no código-fonte. ## Arquivos disponíveis * [JSON](https://raw.githubusercontent.com/raimshq/openapi/main/latest/openapi.spec3.json) * [YAML](https://raw.githubusercontent.com/raimshq/openapi/main/latest/openapi.spec3.yaml) Os dois arquivos descrevem o mesmo contrato. Escolha o formato aceito pela sua ferramenta. ## Baixar ou importar Para baixar o JSON: ```sh curl --fail --location --output openapi.spec3.json https://raw.githubusercontent.com/raimshq/openapi/main/latest/openapi.spec3.json ``` No Postman, Insomnia ou outra ferramenta compatível com OpenAPI 3, escolha a importação por URL e informe o endereço do arquivo JSON ou YAML. Se a ferramenta aceitar somente arquivos locais, baixe um deles e faça a importação pelo disco. O contrato descreve a autenticação Bearer, mas não contém credenciais. Configure sua chave no ambiente seguro da ferramenta e não a grave na coleção exportada. ## Gerar um cliente Use o arquivo baixado como entrada de um gerador compatível com OpenAPI 3. Por exemplo, com o OpenAPI Generator CLI: ```sh openapi-generator-cli generate \ -i openapi.spec3.json \ -g SEU_GERADOR \ -o ./generated/raims ``` Escolha o gerador da linguagem e da biblioteca usadas no seu projeto. Revise o código gerado, mantenha a configuração do gerador versionada e execute os testes da integração antes de atualizar sua aplicação. Esse cliente pertence ao seu projeto e não é um SDK oficial da Raims. ## Manter o contrato atualizado Use os endereços de `main/latest` desta página para baixar o contrato atual, inclusive em geração de código e CI. Baixe o arquivo novamente antes de gerar o cliente para acompanhar a versão publicada da API. Revise as diferenças do contrato, regenere o cliente e execute os testes da integração antes de atualizar sua aplicação. Um novo download não altera automaticamente o código já gerado no seu projeto. # Criar um link de pagamento (/br/api/payment-links) Cria ou recupera o link de uma cobrança já cadastrada na empresa e no ambiente autenticado. Informe em `charge_id` o identificador da cobrança que o cliente deve pagar. A cobrança precisa estar aberta e dentro do vencimento para criar ou configurar seu link. O link usa o cliente, o valor, o vencimento e os demais dados da cobrança. Enquanto a cobrança permitir essa ação, repetir a requisição reutiliza o link existente. Você pode configurar as URLs de retorno e restringir os meios de pagamento aceitos no checkout. Criar o link não cria outra cobrança nem solicita e-mail. Um link novo começa ativo. Se a cobrança já tiver um link pausado, essa requisição conserva a pausa; use o PATCH para reativá-lo. Consulte [Links de pagamento](/br/api/payment-links/overview) para entender os campos de configuração e acompanhar o pagamento pela cobrança vinculada. POST /v1/payment_links # Listar links de pagamento (/br/api/payment-links/list) Consulta os links de pagamento da empresa e do ambiente autenticado. A resposta mostra os identificadores do link e da cobrança, a URL do checkout, `is_active` e as configurações de retorno e de meios de pagamento. Links pausados permanecem na lista. Use a consulta individual para saber se o checkout pode receber pagamento neste momento. Use `charge_id` para consultar o link de uma cobrança específica. Comece sem cursor, processe `list` e, enquanto `page.has_next` for `true`, copie `page.next_after` para `after` na próxima requisição. Copie o cursor completo, sem interpretar ou calcular seu conteúdo, e mantenha o mesmo filtro. Consulte [Listagem e paginação](/br/api/listagem-e-paginacao) para voltar com `before`. Veja como consultar os dados financeiros da cobrança vinculada em [Links de pagamento](/br/api/payment-links/overview). GET /v1/payment_links # Links de pagamento (/br/api/payment-links/overview) Um link de pagamento abre o checkout de uma cobrança específica. O cliente, o título, a descrição, o valor e o vencimento vêm dessa cobrança. O link permite configurar os destinos de retorno ao site e restringir os meios de pagamento oferecidos ao pagador. As requisições da integração usam `https://api.raims.com`. A gestão dos links tem estas cinco requisições: | Finalidade | Método e caminho | | --------------------------------------------- | ---------------------------------------- | | Criar ou recuperar o link de uma cobrança | `POST /v1/payment_links` | | Listar links da empresa e do ambiente | `GET /v1/payment_links` | | Consultar um link e sua disponibilidade atual | `GET /v1/payment_links/{id}` | | Configurar, pausar ou reativar o link | `PATCH /v1/payment_links/{id}` | | Solicitar envio ou reenvio por e-mail | `POST /v1/payment_links/{id}/send_email` | ## Vínculo com a cobrança Cadastre a cobrança antes de solicitar seu link e guarde o identificador retornado pela API. Em [Criar um link de pagamento](/br/api/payment-links), envie esse identificador no campo `charge_id`. A cobrança precisa pertencer à empresa e ao ambiente autenticado. `charge_id` usa o identificador da cobrança, com prefixo `ch_`. O `id` do link usa `pl_`; ele identifica o link nas consultas, na edição e no envio. O link não cria outro cliente nem outra cobrança. Ele também não define preço, prazo ou status financeiro próprios. Para consultar esses dados, use [Recuperar uma única cobrança](/br/api/charges/retrieve) com o `charge_id`. ## Criar ou recuperar o link `POST /v1/payment_links` cria o link de uma cobrança existente ou reutiliza o link que ela já possui. A resposta informa o `id` do link, o `charge_id` e a `url` para abrir o checkout, além das configurações do link. Para criar ou configurar o link, a cobrança precisa estar aberta e dentro do vencimento. Para receber o link junto da criação da cobrança, use `create_checkout: true` em [Criar nova cobrança](/br/api/charges). Essa opção dispensa uma requisição separada para obter a URL, sem exigir envio de e-mail ou URL de retorno. Criar ou recuperar o link não confirma pagamento nem solicita envio de e-mail. Enquanto a cobrança permitir essa ação, repetir a requisição não cria outro link. Um link novo começa ativo. Se o link existente estiver pausado, o POST preserva a pausa. Para reativá-lo, use o PATCH. ## Configurar o link Você pode enviar `success_redirect_url`, `cancel_redirect_url` e `payment_method_types` em `POST /v1/payment_links` ao criar o link ou usar `PATCH /v1/payment_links/{id}`, descrito em [Atualizar um link de pagamento](/br/api/payment-links/update) depois. Depois de configurar o link, consulte `GET /v1/payment_links/{id}` e confira `is_payable`. O campo `is_active` e a lista `effective_payment_method_types` podem continuar preenchidos sem que o checkout aceite pagamento. A lista informa os meios definidos pelas configurações; `is_payable` informa se ainda é possível pagar naquele instante. `success_redirect_url` configura o destino de retorno após a confirmação do pagamento, nas condições descritas em [Orientar quem recebeu um link](/br/checkout#orientar-quem-recebeu-um-link). `cancel_redirect_url` configura o endereço da opção de voltar ao site da empresa. Essa navegação não cancela a cobrança, o Pix ou o boleto. Envie URLs HTTPS completas e válidas. Omitir uma URL, enviar `null`, texto vazio ou somente espaços preserva o endereço já cadastrado. Em um link novo sem endereço informado, a respectiva opção de retorno fica sem destino. Para remover um destino cadastrado, use o PATCH com `clear_success_redirect_url: true` ou `clear_cancel_redirect_url: true`. Você pode enviar os dois comandos para remover ambos os destinos. Enviar `false` ou omitir o comando não solicita remoção. Esses comandos são exclusivos da atualização do link; não são enviados ao criar a cobrança ou o link e não aparecem na resposta. Depois da remoção, a URL correspondente retorna `null`. Sem destino de sucesso, o checkout não faz o retorno automático; sem destino de cancelamento, a opção de voltar ao site fica sem endereço. Remover um destino não cancela a cobrança, o Pix ou o boleto. A atualização exige cobrança aberta e dentro do vencimento, inclusive quando apenas remove um destino. Uma URL preenchida e seu comando de limpeza com `true` são incompatíveis na mesma requisição. A API retorna HTTP 400, com `INVALID_FIELDS` e detalhes `MUTUALLY_EXCLUSIVE` nos dois campos. Escolha entre cadastrar e remover aquele destino. É permitido remover um destino e alterar o outro. `payment_method_types` permite restringir os meios aceitos pelo link. Omitir o campo preserva a configuração existente. Enviar `null` remove a configuração própria do link e retoma a resolução pelos meios da cobrança e pelo checkout da conta. Uma lista preenchida precisa respeitar os meios aceitos pela cobrança e disponíveis na plataforma. Consulte os códigos em [Meios de pagamento](/br/meios-de-pagamento#códigos-na-api). Alterar a configuração do link não modifica o cliente, o título, o valor, o vencimento ou o status da cobrança. Use as requisições de [Cobranças](/br/api/charges/overview) para consultar os dados e fazer as alterações permitidas nesse recurso. Você também pode pausar o checkout com `is_active: false` e reativá-lo com `is_active: true` no PATCH. Para o pagador, um link pausado sem pagamento confirmado aparece como não encontrado ou indisponível, sem informar a pausa. Consulte [Pausar e reativar](#pausar-e-reativar) para as condições e os efeitos dessa configuração. ## Pausar e reativar Use [Atualizar um link de pagamento](/br/api/payment-links/update) com `PATCH /v1/payment_links/{id}` e `is_active: false` para pausar o checkout. Para reativá-lo, envie `is_active: true` no mesmo endpoint. Omitir esse campo preserva o estado atual; `null`, números e texto são inválidos. ```json { "is_active": false } ``` A pausa mantém o mesmo identificador e a mesma URL. O checkout bloqueia novas ações de pagamento e novos pedidos de envio ou reenvio por e-mail enquanto estiver pausado. Pedidos de e-mail e pagamentos aceitos antes da pausa podem continuar normalmente. Você pode alterar suas outras configurações sem reativá-lo. A cobrança precisa estar aberta e dentro do vencimento para pausar, reativar ou configurar o link. Depois que a cobrança vence, o PATCH não permite reativar seu link. Pausar ou reativar conserva o mesmo `id` e a mesma `url`; nenhuma dessas ações acrescenta prazo à cobrança. Ao abrir a URL de um link pausado sem pagamento confirmado, o pagador recebe o mesmo aviso de link não encontrado ou indisponível. A página não revela a pausa. Esse aviso sozinho não permite identificar o motivo; o pagador deve conferir o endereço recebido e procurar a empresa que emitiu a cobrança. A empresa pode consultar `is_active` pela API autenticada para verificar a configuração. Comprovantes de pagamentos confirmados continuam acessíveis. O vencimento continua correndo durante a pausa. Pix e boleto já emitidos não são cancelados e podem continuar sendo pagos fora do checkout. Para cancelar a cobrança, use [Revogar cobrança](/br/api/charges/revoke) e acompanhe a confirmação. Pausar o link não substitui a revogação. As respostas de criação, listagem, consulta e atualização informam `is_active`. Um valor `true` indica que o link não está pausado, mas não garante que a cobrança aceite pagamento. Confira `is_payable` no GET individual antes de oferecer o checkout. Repetir a configuração atual mantém o mesmo link. ## Consultar e compartilhar Use `GET /v1/payment_links`, descrito em [Listar links de pagamento](/br/api/payment-links/list), para percorrer os links da conta. O filtro `charge_id` seleciona os links vinculados à cobrança informada. Mantenha esse filtro ao navegar pelas páginas. Use `GET /v1/payment_links/{id}`, descrito em [Recuperar um link de pagamento](/br/api/payment-links/retrieve), com o `id` do link para consultar sua URL, configuração e disponibilidade atual. Os identificadores do link e da cobrança têm finalidades diferentes; use cada um no campo indicado. No GET individual, `is_payable` indica se a cobrança ainda pode ser paga pelo link. Quando ela é paga, revogada ou vence, o link continua disponível para consulta, mas não permite um novo pagamento. Outras situações, como um boleto aguardando confirmação, também podem impedir um novo pagamento. `payment_method_types` informa a configuração própria do link, ou `null` para usar a configuração da cobrança e da conta. Nessa consulta, a lista fica vazia se a configuração não contiver Pix nem boleto; isso não permite enviar uma lista vazia ao criar ou atualizar o link. `effective_payment_method_types` informa os meios definidos pelas configurações da cobrança, do link e da conta, entre os disponíveis na plataforma. Uma cobrança já paga ou um link pausado pode continuar mostrando Pix e boleto nessa lista. Use `is_payable` para saber se ainda é possível pagar pelo checkout. Quando `is_payable` é false, `unavailable_reason` informa o impedimento. Use `unavailable_reason.code` na integração; `message` é uma explicação em inglês para diagnóstico e seu texto pode mudar. Quando a cobrança pode ser paga pelo link, `unavailable_reason` é `null`. Quando o impedimento for o estado da cobrança, a mensagem informa o estado atual e os aceitos. Se uma cobrança aberta ultrapassou o vencimento, informa também `due_date` em segundos Unix UTC. A mesma explicação aparece quando essa condição impede configurar o link ou solicitar seu envio por e-mail. | Código | Como interpretar | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BOLETO_AWAITING_SETTLEMENT` | O boleto aguarda a atualização do pagamento na cobrança. Aguarde a confirmação antes de oferecer outra cobrança. | | `CHARGE_EXPIRED` | O prazo da cobrança terminou. Consulte seu status antes de definir como receber o pagamento. O fim do prazo do checkout não comprova o cancelamento de um boleto já emitido. | | `CHARGE_NOT_OPEN` | A cobrança não está aberta para pagamento. Consulte seu status atual. | | `PIX_CANCELLATION_PENDING` | O cancelamento do Pix aguarda confirmação. Consulte a cobrança antes de tentar outro pagamento. | | `PIX_CANCELLED` | O QR Code Pix foi cancelado e a cobrança não pode ser paga por esse link. | | `PAYMENT_LINK_PAUSED` | O link foi pausado. A empresa pode reativá-lo se a cobrança continuar aberta e dentro do vencimento. | | `PAYMENT_METHODS_UNAVAILABLE` | Nenhum meio está habilitado para esse checkout. Confira as configurações da cobrança, do link e da conta. | A disponibilidade acompanha as regras do checkout da cobrança e pode mudar depois da consulta. Esses campos não confirmam pagamento nem reservam um meio. A consulta não emite Pix ou boleto e não renova o vencimento. Criação, listagem e atualização continuam retornando a configuração do link; use o GET individual para conferir a disponibilidade. Compartilhe a `url` retornada pela API. Não monte o endereço a partir do `id`. As consultas usam o link existente e não geram outro checkout. ## Enviar por e-mail Para enviar ou reenviar um link de pagamento existente pela API, use `POST /v1/payment_links/{id}/send_email`, descrito em [Enviar link por e-mail](/br/api/payment-links/send-email). Informe o `id` no caminho, sem corpo de requisição. O link precisa estar ativo e a cobrança, aberta e dentro do vencimento. Um link pausado retorna HTTP 409 com `PAYMENT_LINK_PAUSED`; reative-o antes de solicitar o envio. O pedido não cria outro link, não altera o checkout e não emite Pix ou boleto. O destinatário é o e-mail do pagador registrado no boleto, quando houver. Sem esse endereço, usa o e-mail registrado na cobrança e, se também não houver, o e-mail do cadastro atual do cliente. Um endereço inválido impede o envio. Não é possível informar outro destinatário nessa requisição. Enquanto o cadastro da empresa estiver pendente, o envio fica restrito ao e-mail do titular. Após uma solicitação aceita por esse endpoint, aguarde 60 segundos antes de pedir outro envio da mesma cobrança. Esse prazo é compartilhado com a ação de reenvio do Dashboard e com as demais chaves e servidores da mesma empresa. Se receber HTTP 429, aguarde o prazo de `Retry-After` antes de tentar novamente pela API ou pelo Dashboard. A resposta de sucesso informa o destinatário em `recipient_email` e o prazo de reenvio em `retry_after_seconds` e `retry_after_until`, este em segundos Unix UTC. HTTP 202 confirma que o pedido de envio foi registrado. Não comprova a entrega na caixa de entrada nem a leitura pelo destinatário. Para acompanhar o pagamento, consulte a cobrança vinculada. Sandbox também pode enviar e-mails reais. Ao testar esse endpoint, use um endereço de teste sob seu controle. ## Acompanhar o pagamento Consulte a cobrança indicada em `charge_id` para acompanhar seu status e obter os dados de Pix ou boleto disponíveis. Abrir o link, emitir um meio de pagamento ou voltar ao site não confirma que a cobrança foi paga. O link acompanha as condições da cobrança vinculada. A expiração do checkout não comprova o cancelamento de um boleto já emitido. Para cancelar uma cobrança elegível, use [Revogar cobrança](/br/api/charges/revoke) e acompanhe a confirmação; editar o link não substitui essa ação. ## Ambiente e acesso A gestão dos links usa `https://api.raims.com` com [autenticação por chave de API ou OAuth](/br/integracoes/autenticacao). O acesso fica limitado à empresa e ao ambiente autenticados. Links e cobranças de Sandbox ficam separados dos dados de Produção. Use Sandbox para testar sem movimentar valores reais. Quem recebe a URL pode abrir o checkout. Não compartilhe sua chave de API com o pagador nem a inclua na URL. O endereço público não permite administrar a configuração do link ou da cobrança. # Recuperar um link de pagamento (/br/api/payment-links/retrieve) Consulta um link pelo identificador recebido na criação ou na listagem. O link precisa pertencer à empresa e ao ambiente autenticado. O campo `charge_id` identifica a cobrança vinculada. Use esse identificador em [Recuperar uma única cobrança](/br/api/charges/retrieve) para consultar o cliente, o valor, o vencimento, o status e os dados de pagamento disponíveis. `is_active` informa se o link está ativo ou pausado. Um link ativo ainda depende das condições da cobrança para aceitar pagamento. `is_payable` indica se a cobrança ainda pode ser paga por esse link. Uma cobrança já paga, revogada ou vencida, por exemplo, não permite outro pagamento pelo link. Se o valor for `false`, consulte `unavailable_reason.code` para entender o motivo. Quando o impedimento for a pausa, o código será `PAYMENT_LINK_PAUSED`. O link continua consultável e usa a mesma URL após a reativação. Veja como usar o endereço retornado em [Links de pagamento](/br/api/payment-links/overview#consultar-e-compartilhar). A consulta não cria ou altera a cobrança nem emite dados de pagamento. GET /v1/payment_links/{id} # Enviar link por e-mail (/br/api/payment-links/send-email) Solicita o envio do link ao destinatário da cobrança, sem recriar a cobrança ou alterar o checkout. Informe o identificador do link no caminho; esta requisição não recebe corpo nem permite escolher outro e-mail. O link precisa estar ativo e a cobrança, aberta e dentro do vencimento. Um link pausado retorna HTTP 409 com `PAYMENT_LINK_PAUSED`. Reative-o pelo PATCH antes de solicitar o envio. Solicitações aceitas respeitam o mesmo intervalo de 60 segundos da ação de reenvio do Dashboard. O sucesso confirma o pedido de envio, não a entrega do e-mail. Sandbox também pode enviar e-mails reais. Consulte [Enviar por e-mail](/br/api/payment-links/overview#enviar-por-e-mail) para entender o destinatário, a restrição de contas pendentes e os prazos para tentar novamente. POST /v1/payment_links/{id}/send_email # Atualizar um link de pagamento (/br/api/payment-links/update) Atualiza a configuração de um link existente. Use `is_active: false` para pausar o checkout e `is_active: true` para reativá-lo com a mesma URL. Omitir esse campo preserva a configuração; `null` não é aceito. A pausa também impede novos pedidos de envio do link por e-mail. Ela não cancela Pix ou boleto já emitidos nem prorroga o vencimento da cobrança. Você também pode enviar as URLs de retorno e a lista de meios aceitos no checkout. URLs omitidas, `null` ou vazias preservam os endereços cadastrados. Para remover um destino, envie `clear_success_redirect_url: true` ou `clear_cancel_redirect_url: true`. Enviar `false` ou omitir o comando não solicita remoção. Não envie uma URL preenchida junto do seu comando de limpeza com `true`. Essa combinação retorna HTTP 400, com `MUTUALLY_EXCLUSIVE` nos detalhes dos dois campos. Você pode remover um destino e atualizar o outro na mesma requisição. A resposta apresenta `null` no destino removido. A cobrança vinculada precisa estar aberta e dentro do vencimento, inclusive para pausar ou reativar. Outras alterações não reativam um link pausado. Omitir `payment_method_types` preserva a configuração do link. Enviar `null` remove essa configuração própria e volta a usar os meios definidos pela cobrança e pelo checkout da conta. A requisição mantém o vínculo com a cobrança e não altera cliente, título, valor, vencimento ou status. Para consultar ou editar os dados permitidos da cobrança, use a [referência de cobranças](/br/api/charges/overview). Consulte [Configurar o link](/br/api/payment-links/overview#configurar-o-link) para entender as URLs de retorno e a restrição dos meios de pagamento. PATCH /v1/payment_links/{id} # Solicitar estorno (/br/api/refunds) Solicita a devolução de um pagamento Pix recebido pela cobrança informada. O dinheiro retorna à conta de origem do pagamento. Envie o valor que deseja devolver; a mesma requisição atende devoluções integrais e parciais. Em Produção, o aceite do pedido ainda não confirma a devolução. No Sandbox, a simulação conclui na própria requisição. Guarde o identificador retornado e confira o estado da mesma solicitação. Consulte [Estornos](/br/api/refunds/overview) para conhecer as condições de uso e o acompanhamento do resultado. POST /v1/charges/{id}/refunds # Consultar elegibilidade para estorno (/br/api/refunds/eligibility) Consulta se uma cobrança pode receber um pedido de devolução, o valor restante, o máximo que pode ser solicitado agora e os valores de solicitações ainda pendentes. A resposta descreve as condições no momento da consulta. Ela não separa um valor para devolução nem garante que um pedido posterior será aceito. Consulte [Consultar o valor devolvível](/br/api/refunds/overview#consultar-o-valor-devolvível) para entender os impedimentos e quando solicitar o estorno. GET /v1/charges/{id}/refund_eligibility # Listar estornos de uma cobrança (/br/api/refunds/list) Lista as devoluções solicitadas para uma cobrança da empresa e do ambiente autenticado, das mais recentes para as mais antigas. Use o histórico para acompanhar devoluções parciais ou localizar uma solicitação após perder a resposta da criação. Você pode filtrar pelo período da solicitação. Consultar a lista não faz outro estorno. Veja [Consultar o histórico](/br/api/refunds/overview#consultar-o-histórico) e [Listagem e paginação](/br/api/listagem-e-paginacao) para continuar a consulta. GET /v1/charges/{id}/refunds # Listar estornos (/br/api/refunds/list-all) Lista as solicitações de estorno das cobranças da empresa e do ambiente autenticado, das mais recentes para as mais antigas. Use a lista para conciliar devoluções de várias cobranças ou localizar uma solicitação. Você pode filtrar pelo período em que os estornos foram solicitados. Consultar a lista não faz outro estorno. Veja [Consultar o histórico](/br/api/refunds/overview#consultar-o-histórico) e [Listagem e paginação](/br/api/listagem-e-paginacao) para continuar a consulta. GET /v1/refunds # Estornos (/br/api/refunds/overview) Use os estornos para devolver todo ou parte do valor de um pagamento Pix recebido. A devolução usa a cobrança original e retorna o dinheiro à conta que fez o pagamento; não é necessário informar outro cliente, conta de destino ou chave Pix. | Finalidade | Método e caminho | | ----------------------------------------------- | ----------------------------------------- | | Solicitar uma devolução integral ou parcial | `POST /v1/charges/{id}/refunds` | | Consultar uma solicitação | `GET /v1/refunds/{id}` | | Baixar o comprovante de uma devolução concluída | `GET /v1/refunds/{id}/receipt` | | Listar estornos de todas as cobranças | `GET /v1/refunds` | | Listar o histórico da cobrança | `GET /v1/charges/{id}/refunds` | | Consultar a disponibilidade e o valor restante | `GET /v1/charges/{id}/refund_eligibility` | ## Quando solicitar um estorno A cobrança precisa ter um pagamento Pix recebido e confirmado. Em Produção, a transferência original deve estar identificada. No Sandbox, use um pagamento confirmado pela simulação da Raims. Uma cobrança parcialmente devolvida pode receber outro pedido pelo valor restante, depois da conclusão do anterior. O valor precisa ser coberto pelo saldo disponível da conta. Os estados aceitos são `4` (`paid`) e `5` (`partially_refunded`). Estar em um desses estados não dispensa as demais condições, como pagamento Pix identificado, valor restante e saldo disponível. Uma cobrança aceita somente uma devolução em andamento. Se já houver um pedido pendente ou sem resultado confirmado, acompanhe essa solicitação antes de tentar outra. A consulta de elegibilidade informa o impedimento atual. Uma contestação em análise também pode impedir o pedido. Nesse caso, consulte as [contestações](/br/api/disputes/overview) da cobrança; pode não existir um estorno em andamento no histórico. Este recurso devolve pagamentos Pix. Cobranças ainda não pagas seguem a [revogação](/br/api/charges/revoke). O endpoint de estorno não devolve pagamentos de boleto e não recebe instruções de transferência para outra conta. ## Consultar o valor devolvível Use [Consultar elegibilidade para estorno](/br/api/refunds/eligibility), com `GET /v1/charges/{id}/refund_eligibility`, antes de oferecer a devolução. Informe o identificador da cobrança, com prefixo `ch_`. `eligible` indica se as condições atuais permitem um pedido. O campo `refundable_amount_cents` informa quanto ainda resta para devolver na cobrança. `max_refund_amount_cents` informa o máximo que pode ser solicitado agora, considerando esse restante e o saldo disponível, e fica em zero quando houver um impedimento. `pending_amount_cents` informa o valor dos pedidos que aguardam resultado. Quando houver impedimento, `reason` informa seu código e uma explicação em inglês. Use `reason.code` para decidir o tratamento; o texto de `reason.message` serve ao diagnóstico e pode ser melhorado. Sem impedimento, `reason` é `null`. | `reason.code` | Como interpretar | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `PIX_REFUND_NOT_AVAILABLE` | A mensagem identifica se o impedimento é o estado ou o meio de pagamento. Quando for o estado, informa o valor atual e os estados aceitos. | | `PIX_REFUND_CASHIN_NOT_FOUND` | O pagamento Pix original confirmado não foi identificado. Confira a cobrança e o meio de pagamento antes de solicitar. | | `PIX_REFUND_PROVIDER_ACCOUNT_NOT_READY` | Em Produção, a conta ainda não pode realizar a devolução. Entre em contato com o suporte da Raims para conferir a conta. | | `PIX_REFUND_IN_PROGRESS` | Há uma devolução em andamento ou uma contestação em análise. Consulte o histórico e as contestações da cobrança. | | `PIX_REFUND_ALREADY_COMPLETED` | Não há valor restante para devolver. | | `PIX_REFUND_INSUFFICIENT_BALANCE` | O saldo disponível não permite a devolução. Confira o saldo da conta antes de tentar novamente. | | `PIX_REFUND_PROVIDER_UNAVAILABLE` | Em Produção, o processamento está temporariamente indisponível. Consulte novamente antes de solicitar. | Se restarem R$ 100,00 na cobrança e houver R$ 40,00 disponíveis para a devolução, `refundable_amount_cents` será `10000` e `max_refund_amount_cents` será `4000`. Nesse momento, é possível solicitar até R$ 40,00. Esse campo não informa o saldo integral da conta. Envie um `amount_cents` positivo, até o máximo informado. Para devolver todo o restante, o máximo disponível precisa cobrir o valor restante da cobrança. A consulta não separa esse dinheiro nem garante a aceitação: as condições podem mudar, e são conferidas novamente no envio do estorno. ## Devolver um pagamento Pix pela API Use [Solicitar estorno](/br/api/refunds), com `POST /v1/charges/{id}/refunds`, e envie `amount_cents`. O valor usa centavos inteiros: por exemplo, `2500` representa R$ 25,00. `description` permite registrar uma descrição opcional da solicitação. ```json { "amount_cents": 2500, "description": "Devolução parcial do serviço" } ``` Para devolver tudo, envie o valor restante em `amount_cents`. Omitir esse campo é inválido. Para devolver uma parte, envie o valor parcial na mesma requisição. O cliente e a conta de destino vêm do pagamento original; não envie dados bancários nem uma chave Pix. Em Produção, uma resposta `202` confirma que a solicitação foi aceita para acompanhamento. No Sandbox, a simulação conclui na própria requisição e retorna `200` com `status: completed`. Guarde o `id` do estorno, com prefixo `rf_`, para consultar seu resultado. Ele é diferente do identificador `ch_` da cobrança. Se perder a resposta, consulte o histórico da cobrança antes de repetir o pedido. Um novo pedido pode representar outra devolução parcial. ## Acompanhar o resultado Use [Recuperar um estorno](/br/api/refunds/retrieve), com `GET /v1/refunds/{id}`, para consultar a mesma solicitação. A resposta informa a cobrança vinculada, o valor, a descrição, o estado atual e as datas disponíveis. Quando o estado for `failed`, `failure_reason` explica a falha confirmada com um código e uma mensagem em inglês. O pedido pendente ainda não confirma que o dinheiro voltou ao pagador. Considere a devolução concluída somente quando o estado retornado confirmar a conclusão. Quando houver falha, consulte a solicitação e a elegibilidade da cobrança antes de decidir sobre um novo pedido. | `status` | Como interpretar | | ----------- | ------------------------------------------------------------------------------------------ | | `reserved` | A solicitação está em preparação. Acompanhe o mesmo estorno. | | `accepted` | O pedido foi aceito e aguarda confirmação. | | `completed` | A devolução foi concluída. | | `failed` | A falha da solicitação foi confirmada. Confira a elegibilidade antes de outro pedido. | | `unknown` | O resultado ainda não foi confirmado. Acompanhe a mesma solicitação antes de tentar outra. | `created_at`, `completed_at` e `failed_at` usam segundos Unix UTC. As datas de conclusão e falha ficam `null` enquanto o respectivo resultado não estiver confirmado. Consultas repetidas não iniciam nem aceleram a devolução. Use `failure_reason.code` para tratar a causa conhecida. A mensagem serve ao diagnóstico e pode ser melhorada sem mudar o significado do código. Nos demais estados, `failure_reason` é `null`. Uma falha antiga sem causa registrada pode apresentar um motivo desconhecido; isso não autoriza presumir rejeição bancária nem criar automaticamente outro pedido. | `failure_reason.code` | Como interpretar | | ----------------------------------- | ------------------------------------------------------------------------------------------------------ | | `REFUND_NOT_SUBMITTED` | O pedido não foi enviado para processamento. Confira o histórico e a elegibilidade antes de tentar. | | `REFUND_REJECTED` | O pedido foi recusado. Confira o histórico e a elegibilidade antes de tentar novamente. | | `REFUND_PROCESSING_UNAVAILABLE` | O processamento estava indisponível e o pedido falhou. Confira o histórico antes de tentar. | | `REFUND_PROCESSING_FAILED` | O processador confirmou a falha sem informar uma causa detalhada. Confira o histórico antes de tentar. | | `REFUND_FAILURE_REASON_UNAVAILABLE` | Não há causa confirmada disponível. Confira o histórico e procure o suporte se precisar. | ## Consultar o histórico Use [Listar estornos](/br/api/refunds/list-all), com `GET /v1/refunds`, para consultar as solicitações de todas as cobranças da empresa e do ambiente autenticado. Cada item informa `charge_id`, permitindo associar a devolução à cobrança no seu sistema. Para acompanhar devoluções parciais de uma cobrança específica, use [Listar estornos de uma cobrança](/br/api/refunds/list), com `GET /v1/charges/{id}/refunds`. As duas listas apresentam as solicitações mais recentes primeiro e incluem pedidos pendentes, concluídos e com falha. Nas duas listagens, use `created_gte` e `created_lte` para filtrar o período em que o estorno foi solicitado. Informe segundos Unix UTC; os limites são inclusivos. Esse período considera `created_at` e não a data de pagamento da cobrança nem a conclusão da devolução. Você pode informar somente um dos limites ou os dois, com o final igual ou posterior ao início. A resposta usa `list` e `page`. Comece sem cursor, processe `list` e copie `page.next_after` para `after` enquanto `page.has_next` for verdadeiro. Mantenha a mesma conexão ou chave, os filtros e a mesma listagem durante a navegação; na lista por cobrança, mantenha também o mesmo `id`. Para consultar outro período, comece sem cursor. Não interprete nem altere o cursor recebido, nem troque cursores entre as duas listas. Para consultar uma página anterior, use `page.previous_before` em `before`. Não envie `after` e `before` juntos. Veja [Listagem e paginação](/br/api/listagem-e-paginacao) para as regras gerais. ## Comprovante de estorno Use [Baixar comprovante de estorno](/br/api/refunds/receipt), com `GET /v1/refunds/{id}/receipt`, para guardar o documento ou disponibilizá-lo ao cliente. Informe o identificador do estorno, com prefixo `rf_`, recebido na solicitação ou na consulta do histórico. O comprovante exige `status: completed`, valor positivo e data de conclusão registrada. Pedidos pendentes, com falha ou sem confirmação não têm comprovante de conclusão. Nesses casos, acompanhe o mesmo estorno em [Recuperar um estorno](/br/api/refunds/retrieve). O PDF informa o valor daquela devolução. Se uma cobrança tiver dois estornos parciais, cada solicitação tem seu próprio comprovante; o documento não soma o histórico nem substitui o valor original da cobrança. O endpoint retorna JSON com `url` e `expires_at`. Consulte-o pelo servidor da sua integração com chave de API ou sessão OAuth. Faça um GET na `url` completa para baixar o PDF em `files.raims.com`, sem enviar `Authorization` ou a chave de API nesse download. `expires_at` informa a expiração em segundos Unix UTC. Depois dela, consulte novamente o endpoint autenticado para obter outro link. Um link inválido ou expirado pode receber HTTP `403` no download, sem o envelope JSON de erros da API. A URL pode ser reutilizada até expirar e permite acesso a quem a possuir. Compartilhe-a somente com pessoas autorizadas e não a registre em logs. O documento é emitido pela Raims e não substitui uma nota fiscal ou um comprovante bancário. Um comprovante de Sandbox identifica a devolução como simulação, sem movimentação de dinheiro real. ## Estorno Pix na API: Sandbox e Produção O Sandbox permite testar devoluções integrais e parciais com o mesmo endpoint e os mesmos campos de Produção. Primeiro, confirme um pagamento Pix por [Confirmar pagamento](/br/api/simulations/confirm-payment) ou pela simulação do Dashboard. Use uma chave Sandbox da mesma empresa para consultar a elegibilidade e solicitar o estorno. A simulação considera o saldo disponível e o valor restante, conclui na própria requisição e retorna `200` com `status: completed`. A cobrança, o histórico de estornos, o saldo e o extrato do Sandbox refletem a devolução simulada. Nenhum dinheiro real é movimentado. O console desta documentação aceita somente chaves Sandbox. Para testar um pedido que aguarda resultado, use [Simular estorno pendente](/br/api/simulations/request-refund). Depois, escolha entre concluir a devolução e simular uma falha usando o mesmo ID do estorno. Assim você pode conferir o acompanhamento, o saldo e a disponibilidade do comprovante. Veja [Estorno Pix pendente e com falha](/br/api/simulations/overview#estorno-pix-pendente-e-com-falha). Os estados aceitos e as demais condições continuam valendo; boleto não permite estorno por este endpoint. As mudanças confirmadas geram eventos para os [webhooks do Sandbox](/br/integracoes/webhooks/receber-eventos) cadastrados para esses tipos. Em Produção, uma solicitação aceita pode retornar `202` enquanto aguarda a confirmação, que deve ser acompanhada pela consulta do estorno. As requisições usam `https://api.raims.com` com [autenticação por chave de API ou OAuth](/br/integracoes/autenticacao). No OAuth, o estorno precisa estar entre os acessos concedidos e permanecer permitido a quem autorizou a conexão. Com chave de API, consultas exigem **Consultar estornos**, e o pedido exige **Solicitar estorno Pix**. As duas ações são selecionadas separadamente na chave. Elas são diferentes da permissão de colaborador **Devolver Pix** usada no Dashboard. A empresa e o ambiente vêm da autenticação; um identificador de outra empresa ou ambiente não concede acesso à cobrança nem ao estorno. # Baixar comprovante de estorno (/br/api/refunds/receipt) Obtenha uma URL temporária para baixar o comprovante de uma devolução concluída usando o ID do estorno. Consulte este endpoint com sua chave de API ou sessão OAuth e use a `url` retornada para baixar o PDF em `files.raims.com`, sem enviar a chave nesse download. O documento informa o valor daquela solicitação, inclusive quando a devolução for parcial. Pedidos pendentes ou com falha não têm comprovante de conclusão. Consulte [Comprovante de estorno](/br/api/refunds/overview#comprovante-de-estorno) para entender as condições de emissão e o uso do documento. GET /v1/refunds/{id}/receipt # Recuperar um estorno (/br/api/refunds/retrieve) Consulte uma devolução pelo identificador recebido ao solicitar o estorno ou listar o histórico, na empresa e no ambiente autenticado. A resposta informa o estado, as datas e o motivo disponível quando houver falha confirmada. A consulta não solicita outro estorno nem acelera a confirmação da devolução. Consulte [Acompanhar o resultado](/br/api/refunds/overview#acompanhar-o-resultado) para interpretar a resposta. GET /v1/refunds/{id} # Identificador da requisição (/br/api/request-id) Cada resposta processada pela API inclui um identificador da tentativa. Guarde esse valor junto do status e do horário quando precisar investigar uma requisição. `Request-Id` é um header de resposta. Não envie esse nome na requisição nem tente escolher o valor. ## Onde encontrar A resposta contém o header principal e um alias com o mesmo valor: ```http Request-Id: req_4ZxYp8Q2mV7nR6sT5uW3aB X-Request-Id: req_4ZxYp8Q2mV7nR6sT5uW3aB ``` Use `Request-Id` nas novas integrações. `X-Request-Id` existe para compatibilidade. No Raims CLI, o campo aparece como `request_id` na saída JSON e como `Request-Id` na saída de texto. O console desta documentação mostra o valor na resposta real e permite copiá-lo. Exemplos de resposta não têm um ID real. ## Informar ao suporte Ao pedir ajuda sobre uma resposta da API, informe o `Request-Id`, o horário aproximado e o endpoint chamado. Não envie a chave da API, o segredo de webhook nem o payload com dados do cliente. O identificador ajuda a localizar uma tentativa quando os registros correspondentes estão disponíveis. A captura de logs da empresa pode estar desativada ou o histórico pode ter expirado; por isso, ter o ID não garante que a requisição ainda seja pesquisável. ## Limites do identificador Cada tentativa HTTP recebe outro `Request-Id`, inclusive um retry ou o replay de uma resposta idempotente. Para repetir a mesma intenção com segurança, use `Idempotency-Key`; não reutilize `Request-Id`. O valor com prefixo `req_` não é o ID do recurso, do pagamento ou de uma operação pendente. Continue usando os identificadores retornados no corpo para consultar o resultado. O header identifica respostas processadas pela API. Uma falha gerada antes dela, por exemplo na borda ou em um proxy, pode não conter `Request-Id`. # Simular compensação de boleto (/br/api/simulations/compensate-boleto) Simula a compensação de um boleto emitido para testar a espera pela liquidação. Essa etapa não credita o saldo nem confirma um recebimento no extrato. **Apenas Sandbox** Use uma chave com prefixo `sk_test_`. A compensação é simulada e não movimenta dinheiro real. Veja como concluir o pagamento em [Compensação e liquidação do boleto](/br/api/simulations/overview#compensação-e-liquidação-do-boleto). POST /v1/simulations/charges/{id}/compensate_boleto # Concluir estorno simulado (/br/api/simulations/complete-refund) Conclui uma devolução Pix iniciada por [Simular estorno pendente](/br/api/simulations/request-refund). Informe o ID do estorno para conferir o resultado concluído e seu comprovante. **Apenas Sandbox** Use uma chave com prefixo `sk_test_`. A conclusão não movimenta dinheiro real e não está disponível em Produção. Veja [Estorno Pix pendente e com falha](/br/api/simulations/overview#estorno-pix-pendente-e-com-falha) para preparar o teste e acompanhar os resultados. POST /v1/simulations/refunds/{id}/complete # Confirmar pagamento (/br/api/simulations/confirm-payment) Confirma o pagamento de uma cobrança de teste pelo ID. Use esta requisição para conferir o estado pago, o saldo e o recebimento no extrato do Sandbox. **Apenas Sandbox** Use uma chave com prefixo `sk_test_`. Esta confirmação é simulada, não movimenta dinheiro real e não está disponível em Produção. Consulte [Simulação](/br/api/simulations/overview#confirmar-um-pagamento) para preparar a cobrança e conferir os resultados. Repetir a mesma confirmação não credita o valor novamente. POST /v1/simulations/charges/{id}/confirm_payment # Simular falha no pagamento (/br/api/simulations/fail-payment) Simula uma falha no pagamento de uma cobrança pelo ID. Use esta requisição para conferir como sua integração trata o resultado sem pagamento. **Apenas Sandbox** Use uma chave com prefixo `sk_test_`. A falha simulada não movimenta saldo e não está disponível em Produção. Consulte [Simulação](/br/api/simulations/overview#simular-uma-falha) para preparar a cobrança e entender as condições para repetir o teste. POST /v1/simulations/charges/{id}/fail_payment # Simular falha no estorno (/br/api/simulations/fail-refund) Simula uma falha em um estorno Pix pendente, sem concluir a devolução. Use esta requisição para conferir o motivo da falha e a liberação do valor no saldo disponível. **Apenas Sandbox** Use uma chave com prefixo `sk_test_`. A falha simulada não está disponível em Produção. Veja [Estorno Pix pendente e com falha](/br/api/simulations/overview#estorno-pix-pendente-e-com-falha) para preparar o teste e acompanhar os resultados. POST /v1/simulations/refunds/{id}/fail # Emitir pagamento de teste (/br/api/simulations/issue-payment) Solicita a emissão de Pix ou boleto para uma cobrança de teste. Quando houver um cenário preparado para essa emissão, a requisição apresenta o resultado pendente ou com falha escolhido. **Apenas Sandbox** Use uma chave com prefixo `sk_test_`. Emitir os dados de pagamento não confirma que a cobrança foi paga. Veja as condições e a sequência de teste em [Emissão e cancelamento com pendência ou falha](/br/api/simulations/overview#emissão-e-cancelamento-com-pendência-ou-falha). POST /v1/simulations/charges/{id}/issue_payment # Simulação (/br/api/simulations/overview) Use a simulação para testar pagamentos Pix e boleto, estornos e resultados que aguardam confirmação. Os resultados alteram os registros do Sandbox para que você possa conferir o acompanhamento da cobrança e os efeitos no saldo, extrato e comprovantes. **Apenas Sandbox** Estes endpoints usam somente o ambiente Sandbox, com chave de API ou sessão OAuth autorizada nesse ambiente. As simulações não movimentam dinheiro real e não estão disponíveis em Produção. | Finalidade | Método e caminho | | ------------------------------------------------ | ----------------------------------------------------- | | Confirmar um pagamento de teste | `POST /v1/simulations/charges/{id}/confirm_payment` | | Simular uma falha de pagamento | `POST /v1/simulations/charges/{id}/fail_payment` | | Iniciar um estorno Pix pendente | `POST /v1/simulations/charges/{id}/refunds` | | Concluir um estorno pendente | `POST /v1/simulations/refunds/{id}/complete` | | Simular falha de um estorno | `POST /v1/simulations/refunds/{id}/fail` | | Simular a compensação de boleto | `POST /v1/simulations/charges/{id}/compensate_boleto` | | Preparar uma emissão ou um cancelamento | `POST /v1/simulations/charges/{id}/scenario` | | Emitir Pix ou boleto de teste | `POST /v1/simulations/charges/{id}/issue_payment` | | Resolver uma emissão ou um cancelamento pendente | `POST /v1/simulations/charges/{id}/resolve` | ## Usar somente no Sandbox Crie o cliente e a cobrança no Sandbox da sua empresa com [autenticação por chave de API ou OAuth](/br/integracoes/autenticacao). Use essa mesma empresa e ambiente para simular o resultado e consultar os registros. No OAuth, selecione Sandbox; com chave de API, use uma chave Sandbox. O ambiente não é informado no corpo ou na URL da requisição. Informe o identificador da cobrança ou do estorno no caminho, conforme a requisição. Uma chamada em Produção recebe `403 SANDBOX_ENVIRONMENT_REQUIRED`. Um ID inexistente, de outra empresa ou de outro ambiente recebe a mesma resposta de recurso não encontrado. ## Confirmar um pagamento Use [Confirmar pagamento](/br/api/simulations/confirm-payment) para concluir o pagamento de uma cobrança de teste que ainda esteja aberta. A resposta informa `status: 4`, correspondente a paga, e `amount_cents` com o valor da cobrança em centavos de real. O valor é creditado no saldo do Sandbox uma única vez. Você pode conferir o saldo em [Consultar saldo](/br/api/balances) e acompanhar o lançamento em [Extrato](/br/api/statements/overview). O lançamento pode levar alguns instantes para aparecer; não repita a confirmação para tentar acelerar essa atualização. Para testar os dados de pagamento e o recibo, crie a cobrança com o meio desejado: `payment_method: 1` para Pix ou `payment_method: 2` para boleto. Consulte as condições de emissão em [Cobranças](/br/api/charges/overview). Depois da confirmação, use as consultas de [dados do pagamento](/br/api/charges/payment) e [recibo](/br/api/charges/receipt). Os documentos de teste identificam o pagamento como simulado. A confirmação não escolhe um meio de pagamento para a cobrança. ## Simular uma falha Use [Simular falha no pagamento](/br/api/simulations/fail-payment) para testar o tratamento de uma cobrança aberta que não foi paga. A resposta informa `status: 9`, correspondente a falha. Esse resultado não credita saldo nem gera um recebimento no extrato. A falha encerra esse teste. Para conferir um pagamento aprovado depois disso, crie outra cobrança de Sandbox. ## Estorno Pix pendente e com falha Crie uma cobrança Pix, confirme o pagamento e use [Simular estorno pendente](/br/api/simulations/request-refund). Envie o valor em `amount_cents`, como no pedido normal de [estorno](/br/api/refunds/overview). As condições de saldo e valor restante continuam valendo. A resposta `202` retorna o ID do estorno com `status: accepted`. Guarde esse ID para [acompanhar a solicitação](/br/api/refunds/retrieve). O valor solicitado sai do saldo total e disponível enquanto o pedido aguarda resultado; o campo de saldo bloqueado permanece inalterado. O comprovante ainda não está disponível. Escolha um resultado para o mesmo estorno: * [Concluir estorno simulado](/br/api/simulations/complete-refund) retorna `completed`, atualiza a devolução na cobrança e permite consultar o comprovante. O valor não é descontado novamente. * [Simular falha no estorno](/br/api/simulations/fail-refund) retorna `failed`, com `REFUND_PROCESSING_FAILED` em `failure_reason.code`, e devolve o valor ao saldo disponível. Não há comprovante de devolução concluída. Repetir o mesmo resultado final retorna o estorno sem repetir seu efeito. Tentar trocar um resultado concluído por falha, ou uma falha por conclusão, retorna `409 REFUND_NOT_SIMULATABLE`. Para outro teste, confira a elegibilidade antes de criar uma nova solicitação. Repetir a criação de um pedido enquanto houver outro pendente recebe `PIX_REFUND_IN_PROGRESS`; use o ID já recebido para concluir ou falhar esse pedido. O endpoint normal `POST /v1/charges/{id}/refunds` continua concluindo a devolução imediatamente no Sandbox. Use as rotas de simulação quando precisar testar a espera e o resultado posterior. ## Compensação e liquidação do boleto Crie uma cobrança de boleto e emita as instruções de pagamento. Use [Simular compensação de boleto](/br/api/simulations/compensate-boleto) para registrar que o pagamento foi compensado, mas ainda aguarda liquidação. Essa etapa não credita o saldo nem disponibiliza um comprovante de pagamento concluído. A consulta da cobrança informa o andamento em `payment_information.boleto_payment_status`: `awaiting_payment` antes da compensação, `compensated` enquanto aguarda liquidação e `settled` depois da confirmação. Sem andamento disponível, o campo retorna `null`. Depois, use [Confirmar pagamento](/br/api/simulations/confirm-payment) para liquidar o boleto. Só essa confirmação credita o valor e permite consultar os dados do pagamento e o recibo. O extrato pode levar alguns instantes para mostrar o recebimento. Repetir a compensação ou a confirmação não repete o crédito. ## Emissão e cancelamento com pendência ou falha Use [Preparar cenário](/br/api/simulations/scenario) antes da ação que deseja testar. Envie `action` com `pix_issuance`, `boleto_issuance` ou `cancellation` e escolha `outcome: pending` ou `outcome: failed`. A resposta com `state: configured` confirma a preparação; ela ainda não emitiu nem cancelou a cobrança. Para emissão, crie a cobrança com `payment_method_types: [1]` para Pix ou `payment_method_types: [2]` para boleto, sem emissão na criação. Prepare o cenário e use [Emitir pagamento de teste](/br/api/simulations/issue-payment), informando `payment_method: 1` ou `2`. A emissão pelo checkout da cobrança também usa o cenário preparado. Consulte as condições de cadastro em [Cobranças](/br/api/charges/overview). Para cancelamento, a cobrança de Sandbox precisa estar aberta e ter um Pix ou boleto já emitido. Se ainda não houver dados de pagamento, emita-os pelo checkout ou por [Emitir pagamento de teste](/br/api/simulations/issue-payment) antes de preparar o cenário. Não confirme o pagamento nesse fluxo. Depois da emissão, prepare `action: cancellation` e use [Revogar cobrança](/br/api/charges/revoke). A requisição normal apresenta o resultado pendente ou a falha escolhida. Preparar o cenário não altera o saldo e não devolve um pagamento já recebido. Com `outcome: pending`, acompanhe a cobrança e use [Resolver cenário pendente](/br/api/simulations/resolve) para escolher `completed` ou `failed` para a mesma `action`. Essa requisição conclui uma ação que já começou; não inicia a emissão nem o cancelamento. Uma emissão concluída disponibiliza o Pix ou boleto, sem confirmar pagamento. Um cancelamento concluído revoga a cobrança, sem estornar valores. Com `outcome: failed`, a ação apresenta a falha sem passar pela etapa de resolução. A falha de emissão fica em `pix_status` ou `boleto_status` e seu motivo em `pix_error` ou `boleto_error`. Ela é diferente de [Simular falha no pagamento](/br/api/simulations/fail-payment), que encerra a cobrança com falha de pagamento. Cada cenário vale para a cobrança informada. Repetir a mesma preparação ou resolução preserva o resultado; tentar substituir um cenário já definido recebe `409 CHARGE_SCENARIO_CONFLICT`. Crie outra cobrança para testar uma combinação diferente. ## Repetir uma simulação Se a conexão for interrompida, consulte a cobrança ou o estorno pelo mesmo ID. Repetir uma confirmação, falha de pagamento, compensação ou etapa de cenário já aplicada informa `duplicate: true`, sem aplicar novamente o efeito financeiro. Nas conclusões e falhas de estorno, a resposta apresenta o mesmo estorno com seu estado final. Uma cobrança já paga não pode receber uma falha de pagamento simulada, e uma cobrança com falha não pode receber uma confirmação. Essas duas requisições também recusam cobranças canceladas ou com outro resultado encerrado, com `409 CHARGE_NOT_SIMULATABLE`. Consulte o estado atual e crie outra cobrança para testar um resultado diferente. ## Testar os demais recursos Use os endpoints de cada recurso com a chave Sandbox. Não é necessário um endpoint de simulação para criar clientes, criar ou atualizar cobranças, gerenciar links de pagamento ou revogar uma cobrança. Para testar uma devolução, crie uma cobrança Pix, confirme seu pagamento e use [Estornos](/br/api/refunds/overview). As condições de saldo, valor restante e estado da cobrança continuam valendo. A devolução no Sandbox é simulada; o endpoint de estorno não recebe boleto. As consultas de saldo, extrato, estatísticas, dados de pagamento e comprovantes permitem conferir os resultados de teste. A solicitação de saque continua restrita a Produção; as simulações de cobrança não transferem valores para uma conta bancária. Para testar uma cobrança vencida, crie-a com um prazo curto e aguarde o vencimento. A simulação de pagamento também pode confirmar uma cobrança cujo prazo passou, desde que ela continue aberta para receber o resultado. A simulação preserva a data de vencimento da cobrança. As consultas de [Contestações](/br/api/disputes/overview) retornam os casos disponíveis no ambiente consultado. Confirmar um pagamento de teste não abre uma contestação. As mudanças confirmadas pela simulação geram os eventos de webhook correspondentes para os destinos cadastrados no Sandbox. As requisições ao seu endpoint são reais; use um receptor de testes e consulte [Receber e validar eventos](/br/integracoes/webhooks/receber-eventos). Requisições de outros recursos que solicitam envio de e-mail mantêm suas próprias regras; use somente destinatários autorizados nos testes. # Simular estorno pendente (/br/api/simulations/request-refund) Inicia um estorno Pix de teste que aguarda confirmação. Use o identificador retornado para concluir a devolução ou simular uma falha em outra requisição. **Apenas Sandbox** Use uma chave com prefixo `sk_test_`. A devolução é simulada, sem movimentação de dinheiro real. Confira as condições e os efeitos no saldo em [Estorno Pix pendente e com falha](/br/api/simulations/overview#estorno-pix-pendente-e-com-falha). POST /v1/simulations/charges/{id}/refunds # Resolver cenário pendente (/br/api/simulations/resolve) Define o resultado de uma emissão ou de um cancelamento que ficou pendente no cenário de teste. A ação precisa ter sido iniciada sobre a cobrança. **Apenas Sandbox** Use uma chave com prefixo `sk_test_`. A resolução é simulada e não movimenta dinheiro real. Veja como preparar e iniciar a ação em [Emissão e cancelamento com pendência ou falha](/br/api/simulations/overview#emissão-e-cancelamento-com-pendência-ou-falha). POST /v1/simulations/charges/{id}/resolve # Preparar cenário (/br/api/simulations/scenario) Prepara o resultado de uma emissão de Pix ou boleto, ou de um cancelamento. Depois desta requisição, execute a ação correspondente sobre a mesma cobrança. Para `action: cancellation`, use uma cobrança de Sandbox aberta, com Pix ou boleto já emitido. Se ainda não houver dados de pagamento, emita-os antes de preparar o cenário. Depois, use [Revogar cobrança](/br/api/charges/revoke). Não confirme o pagamento nesse fluxo. **Apenas Sandbox** Use uma chave com prefixo `sk_test_`. O cenário não movimenta dinheiro real nem altera cobranças de Produção. Veja a sequência em [Emissão e cancelamento com pendência ou falha](/br/api/simulations/overview#emissão-e-cancelamento-com-pendência-ou-falha). POST /v1/simulations/charges/{id}/scenario # Recuperar extrato (/br/api/statements) Consulte os lançamentos financeiros da empresa e do ambiente autenticado. Use os filtros para selecionar um período, tipos de lançamento ou uma referência vinculada. Uma mesma transação pode gerar vários lançamentos. A consulta mostra o histórico registrado, sem executar pagamentos ou alterar valores da conta. Veja [Extrato](/br/api/statements/overview) para interpretar os valores e continuar a consulta pelas páginas. O [mapa de tipos e identificadores](/br/tipos-e-identificadores) explica os códigos do lançamento e os prefixos das referências que podem aparecer. GET /v1/statements # Extrato (/br/api/statements/overview) Use o extrato para conferir as movimentações registradas na conta e conciliar os valores com o seu sistema. Cada item representa um lançamento financeiro; um pagamento pode gerar uma entrada e uma tarifa em itens separados. | Finalidade | Método e caminho | | ----------------------------------- | ------------------------- | | Consultar os lançamentos do extrato | `GET /v1/statements` | | Recuperar um lançamento pelo ID | `GET /v1/statements/{id}` | ## Consultar movimentações Use [Recuperar extrato](/br/api/statements), com `GET /v1/statements`. Você pode consultar um período, selecionar tipos de lançamento ou filtrar pela referência vinculada. Combine os filtros conforme a consulta desejada. As datas usam segundos Unix UTC. `created_gte` inclui os lançamentos a partir do instante informado e `created_lte` inclui os lançamentos até esse instante. A ordem padrão apresenta os mais recentes primeiro; `sort_order: asc` apresenta os mais antigos primeiro. A consulta retorna o histórico registrado pela Raims. Ela não inicia pagamentos, saques, estornos ou liberações de saldo. Uma solicitação ainda em andamento pode não ter seu resultado financeiro no extrato; acompanhe também o recurso que originou a solicitação. ## Consultar um lançamento Use [Recuperar um lançamento](/br/api/statements/retrieve), com `GET /v1/statements/{id}`, para conferir um item sem percorrer novamente as páginas do extrato. Envie o identificador completo com prefixo `st_` recebido na listagem. A resposta apresenta os mesmos campos do item da lista. Um lançamento ausente ou que não pertence à empresa e ao ambiente autenticado recebe a mesma resposta de recurso não encontrado. ## Tipos e valores dos lançamentos `amount_cents` informa o valor em centavos de real, preservando o sinal: `10000` representa R$ 100,00 e `-250` representa um débito de R$ 2,50. Interprete o valor junto de `statement_type`. O guia de [tipos de lançamento](/br/tipos-e-identificadores/financeiro#tipos-de-lançamento-do-extrato) detalha todos os códigos, os sinais dos valores e os cuidados de cada caso. Retenção e liberação registram mudanças na disponibilidade do dinheiro. Uma liberação não representa um novo recebimento. O extrato não informa o saldo da conta após cada lançamento; somar uma página ou apenas os itens filtrados não fornece o saldo atual. Para consultar o saldo atual, use o recurso [Saldo](/br/api/balances/overview). Ele distingue o total da conta, a parcela bloqueada e o valor disponível. ## Vínculos com outros recursos `id`, com prefixo `st_`, identifica o lançamento e permite reconhecê-lo no seu sistema. `reference_id` identifica o recurso de origem quando há um vínculo disponível. `reference_type` informa a categoria dessa referência: cobrança (`1`), contestação (`2`), saque (`3`), ajuste (`4`) ou lançamento manual (`5`). Campos sem vínculo disponível ficam `null`. Consulte o mapa de [identificadores e prefixos](/br/tipos-e-identificadores/identificadores) para distinguir os IDs, inclusive referências sem endpoint público próprio. Quando a referência for um saque, copie o ID `wd_` para [Recuperar um saque](/br/api/withdrawals/retrieve). A consulta mostra o andamento e o destino registrado, sem solicitar outra transferência. `refund_id` identifica a solicitação de estorno vinculada ao lançamento, quando disponível. `dispute_id` identifica a contestação correspondente, incluindo casos MED. Use esses campos para consultar o [estorno](/br/api/refunds/retrieve) ou a [contestação](/br/api/disputes/retrieve) de origem. Esses campos ficam `null` quando não há vínculo confirmado. Uma tarifa ou outro lançamento da mesma cobrança não recebe automaticamente o ID do estorno ou da contestação. Preserve os IDs retornados, inclusive seus prefixos, ao consultar cada recurso. Use os detalhes de [Cobranças](/br/api/charges/overview) e [Contestações](/br/api/disputes/overview) para acompanhar os recursos correspondentes. O identificador do lançamento é diferente do identificador da cobrança ou da contestação. A presença de uma referência não significa que exista um endpoint público para consultar todas as categorias. ## Percorrer o histórico A resposta contém `list`, com os lançamentos da página, e `page`, com as informações de navegação. Comece sem cursor e processe os itens de `list`. Enquanto `page.has_next` for verdadeiro, copie `page.next_after` inteiro para `after` na próxima requisição. Mantenha a mesma conexão ou chave, os filtros e a ordenação durante a navegação. Para alterar a consulta, comece novamente sem cursor. Uma lista vazia indica que a página não contém lançamentos para os filtros informados. Para voltar, use `page.previous_before` em `before`. Não envie `after` e `before` preenchidos juntos nem interprete o conteúdo dos cursores. Veja [Listagem e paginação](/br/api/listagem-e-paginacao) para as regras gerais. ## Empresa e ambiente As consultas seguem a [autenticação](/br/integracoes/autenticacao) por chave de API ou OAuth. O ambiente autenticado define o histórico: Sandbox consulta somente as movimentações de simulação; Produção consulta o histórico financeiro correspondente. O console desta documentação aceita somente chaves Sandbox. Filtrar por uma referência não concede acesso a dados de outra empresa ou ambiente. Trate os erros pelo status HTTP e por `error.code`; nas validações, confira também os campos indicados em `error.details`. # Recuperar um lançamento (/br/api/statements/retrieve) Consulte o valor, o tipo e os vínculos de um lançamento da empresa e do ambiente autenticado. Use o `id` com prefixo `st_` recebido na listagem. Os vínculos com estorno ou contestação aparecem somente quando estão identificados para aquele lançamento. Veja [Extrato](/br/api/statements/overview) para interpretar os valores e as referências retornadas. Consulte também o [mapa de tipos e identificadores](/br/tipos-e-identificadores) para interpretar códigos e referências de outros recursos. GET /v1/statements/{id} # Listar entregas (/br/api/webhook-deliveries) Consulte as entregas da empresa e do ambiente autenticado. Use os filtros para localizar um envio e seu identificador para consultar os detalhes. Veja [Acompanhar uma entrega](/br/api/webhook-deliveries/overview#acompanhar-uma-entrega) e [Listagem e paginação](/br/api/listagem-e-paginacao). GET /v1/webhook_deliveries # Antecipar uma tentativa (/br/api/webhook-deliveries/advance) Solicite a antecipação de uma entrega pendente depois de corrigir seu receptor. O webhook precisa estar ativo, com a fila sem pausa, e a entrega deve continuar dentro do prazo. Eventos `webhook.test` não aceitam antecipação. Para conferir o receptor novamente, [solicite outro teste](/br/api/webhooks/test). O aceite do pedido não confirma o envio. Consulte a mesma entrega para acompanhar o resultado. Veja [Antecipar uma tentativa](/br/api/webhook-deliveries/overview#antecipar-uma-tentativa) para distinguir essa ação de um reenvio. POST /v1/webhook_deliveries/{delivery_id}/advance # Recuperar uma tentativa (/br/api/webhook-deliveries/attempt-retrieve) Consulte os dados registrados de uma tentativa para investigar a resposta do receptor ou uma falha de conexão. O registro pode não conter todos os dados de resposta. Veja [Consultar tentativas e respostas](/br/api/webhook-deliveries/overview#consultar-tentativas-e-respostas). GET /v1/webhook_deliveries/{delivery_id}/attempts/{attempt_id} # Listar tentativas (/br/api/webhook-deliveries/attempts) Consulte cada tentativa HTTP registrada para a entrega. Uma falha pode ser seguida por outra tentativa, dentro dos limites do ambiente. Veja [Consultar tentativas e respostas](/br/api/webhook-deliveries/overview#consultar-tentativas-e-respostas). GET /v1/webhook_deliveries/{delivery_id}/attempts # Entregas de webhooks (/br/api/webhook-deliveries/overview) Consulte o que aconteceu entre a criação de um evento e a resposta do seu receptor. Use a lista de entregas para acompanhar o andamento e os detalhes de cada tentativa para investigar falhas. Para cadastrar um destino ou alterar os eventos recebidos, use [Webhooks](/br/api/webhooks/overview). ## Evento, entrega e tentativa Um evento descreve uma mudança, como `charge.paid`. A entrega é o envio desse evento a um webhook. Uma tentativa é cada chamada HTTP feita para concluir a entrega. | Identificador | Onde encontrá-lo | Quando muda | | ------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Evento | `event_id` na consulta ou `id` no corpo recebido | Permanece igual nas tentativas, nos destinos do mesmo evento e no reenvio manual. | | Entrega | `id` na consulta, `delivery_id` no teste ou reenvio e cabeçalho `webhook-id` | Cada destino e cada reenvio têm sua própria entrega. | | Tentativa | `id` na lista ou no detalhe de tentativas | Cada chamada HTTP registrada tem seu próprio identificador. | Uma entrega pode ter várias tentativas, todas com o mesmo `webhook-id`. Use o identificador devolvido pela consulta de tentativas ao recuperar seu detalhe; ele é diferente dos IDs do evento e da entrega. Use o evento para evitar repetir seu efeito no sistema e a entrega para reconhecer novas tentativas. Veja [Tratar reentregas e ordem](/br/integracoes/webhooks/receber-eventos#tratar-reentregas-e-ordem). ## Acompanhar uma entrega [Liste as entregas](/br/api/webhook-deliveries) e use o `id` de um resultado para [consultá-lo](/br/api/webhook-deliveries/retrieve). As informações de andamento podem aparecer com atraso; a ausência de um registro não comprova que o evento nunca foi enviado. A lista apresenta as entregas mais recentes primeiro. Você pode filtrar pelo webhook, tipo de evento, situação e período de criação da entrega. Se já tiver o UUID do evento, use `event_id` para reunir suas entregas, inclusive reenvios manuais. Para localizar primeiro o evento pelo recurso, consulte [Eventos de webhooks](/br/api/webhook-events/overview). Os limites `created_gte` e `created_lte` são inclusivos. A consulta abrange até [30 dias desde a criação da entrega](#histórico-por-30-dias), mesmo se você omitir o período. Comece a listagem sem cursor, processe `list` e copie `page.next_after` para `after` enquanto `page.has_next` for verdadeiro. Preserve filtros durante a navegação. Para voltar, use `page.previous_before` em `before`. Copie o cursor inteiro e não envie os dois sentidos na mesma requisição. Veja [Listagem e paginação](/br/api/listagem-e-paginacao). Datas do acompanhamento são retornadas em segundos Unix UTC. `event_created_at` identifica a criação do evento original; `created_at` identifica a entrega. No reenvio, essas datas podem ser diferentes. `deadline_at` é o limite para tentar concluir a entrega, e `next_attempt_at` informa a próxima tentativa prevista quando disponível. Consultas não iniciam nem aceleram envios. Uma fila pausada impede novas tentativas, mas conserva o prazo original da entrega. Confira `is_paused` na configuração do webhook antes de investigar uma espera. Veja [Pausar e retomar a fila](/br/api/webhooks/overview#pausar-e-retomar-a-fila). | `status` | Significado | | ------------ | ------------------------------------------------------------- | | `pending` | A entrega aguarda uma tentativa de envio. | | `processing` | Uma tentativa está em andamento ou aguarda seu resultado. | | `delivered` | O receptor respondeu com sucesso HTTP `2xx`. | | `failed` | A entrega terminou sem sucesso ou esgotou o prazo disponível. | | `canceled` | A entrega foi encerrada pela situação do cadastro do webhook. | Uma resposta HTTP `2xx` confirma que o receptor aceitou a entrega. Ela não comprova o processamento posterior no sistema de destino. Confira também os registros da sua aplicação. ## Consultar tentativas e respostas Para consultar pela API a resposta HTTP e o corpo de uma tentativa de webhook, [liste as tentativas](/br/api/webhook-deliveries/attempts) da entrega e [consulte uma delas](/br/api/webhook-deliveries/attempt-retrieve) para ver os detalhes disponíveis. O registro informa a resposta HTTP, a duração, o erro e o destino usado quando esses dados foram capturados. A lista reúne chamadas HTTP ao receptor. Uma espera anterior ao envio não é uma tentativa HTTP e pode manter a entrega pendente com a lista ainda vazia. As tentativas aparecem da mais recente para a mais antiga. Use a paginação para percorrer o histórico completo disponível. Nas tentativas, `created_at` informa a conclusão da tentativa. `duration_ms` mede o tempo total da tentativa, que pode incluir preparação e espera antes da chamada HTTP. Não use esse valor isoladamente como tempo de resposta do seu receptor. `status_code: null` indica que não há status HTTP disponível. Nesse caso, o erro pode ajudar a identificar uma falha de conexão ou timeout. Uma tentativa que falhou não significa que a entrega terminou: consulte seu andamento e a próxima tentativa prevista. `destination_ip` identifica o destino usado naquela conexão. Se houver um proxy na frente do receptor, esse IP pode ser o do proxy. O campo não informa o IP de origem da Raims nem o resultado atual de uma consulta DNS. Os corpos de requisição e resposta ficam no detalhe da tentativa. `request_available` e `response_body_available` informam sua disponibilidade. Um corpo indisponível difere de um corpo vazio que foi registrado. `response_body_truncated: true` indica uma captura parcial; o conteúdo pode não ser um JSON completo. A captura da resposta tem limite de 8 KiB. Respostas binárias, comprimidas ou sem texto UTF-8 válido também podem ficar indisponíveis. Registros antigos podem não conter corpo, URL ou IP. A existência dos metadados não garante que esses dados tenham sido capturados. Não coloque segredos nem dados pessoais desnecessários nas respostas do receptor. ## Histórico por 30 dias A API mantém a entrega, suas tentativas e os corpos capturados disponíveis para consulta por **30 dias a partir da criação da entrega**, indicada em `created_at`. Depois desse prazo, eles deixam de aparecer nas consultas. Uma nova tentativa da mesma entrega não reinicia os 30 dias. Um reenvio cria outra entrega, com seu próprio prazo de consulta. O limite para solicitar esse reenvio continua sendo **15 dias a partir da criação do evento original**, indicada em `event_created_at`. Guardar o histórico por 30 dias não amplia esse prazo. No Dashboard, os logs de cada tentativa podem ser consultados por 30 dias a partir da conclusão daquela tentativa. Por isso, um registro ainda pode aparecer nos logs depois de terminar o prazo da entrega na API. ## Investigar uma falha Consulte a entrega e abra a tentativa mais recente. O status HTTP da tentativa foi retornado pelo receptor ou por uma camada à frente dele; ele é diferente do status da requisição usada para consultar a API Raims. | Resultado da tentativa | O que conferir | | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Sem status HTTP | Verifique DNS, certificado HTTPS, conectividade e timeout. A ausência de resposta não comprova que o receptor deixou de aceitar o evento. | | `3xx` | Cadastre a URL HTTPS final. A Raims não segue redirecionamentos. | | `400`, `401` ou `403` | Consulte a resposta e os registros do receptor. Confira corpo original, assinatura, segredo do ambiente e eventuais bloqueios de login ou firewall. | | `404` | Confira o caminho cadastrado e se o receptor aceita `POST` nesse endereço. | | `429` | Reveja a capacidade e os limites do receptor. O `Retry-After` pode orientar a próxima tentativa dentro dos prazos da Raims. | | `5xx` ou timeout | Investigue o erro no receptor e reduza o trabalho feito antes da confirmação de recebimento. | | `2xx`, mas sem o resultado esperado no seu sistema | Verifique o processamento posterior ao aceite, os registros de duplicatas e o estado atual do recurso. | Se uma consulta ampla de entregas retornar `503`, aguarde e tente um período menor ou filtros mais específicos. Confira também a orientação geral de [indisponibilidade da API](/br/api/codigos-http-das-respostas). Confira URL, certificado, assinatura e regras de firewall antes de solicitar outro envio. Os prazos automáticos de Produção e Sandbox estão em [Falhas e novas tentativas de webhook](/br/integracoes/webhooks/receber-eventos#falhas-e-novas-tentativas-de-webhook). ## Antecipar uma tentativa Se o receptor já foi corrigido e a entrega ainda aguarda uma tentativa, use [Antecipar uma tentativa](/br/api/webhook-deliveries/advance). A entrega precisa estar pendente, dentro do prazo, com webhook ativo e fila sem pausa. A ação pede que a próxima tentativa fique apta a ocorrer antes do horário previsto, conforme os limites de envio. Ela preserva o evento e a entrega; o `delivery_id` permanece o mesmo. Não cria outra entrega, não amplia o prazo e não aumenta a quantidade de tentativas permitidas no Sandbox. Uma resposta `202` confirma o recebimento do pedido. A condição da entrega é conferida novamente antes de antecipar o envio, pois ela pode mudar nesse intervalo. Consulte a mesma entrega para acompanhar o resultado. Uma tentativa em andamento ou uma entrega já encerrada não pode ser antecipada. Para uma entrega encerrada, confira a elegibilidade de [reenvio](#reenviar-um-evento). O evento técnico `webhook.test` não aceita antecipação. Se precisar testar novamente o receptor, use [Enviar um evento de teste](/br/api/webhooks/test). ## Reenviar um evento [Solicite o reenvio](/br/api/webhook-deliveries/resend) a partir de uma entrega do evento. Ele precisa ter sido criado há no máximo 15 dias, manter o corpo disponível e continuar selecionado em um webhook ativo. Se você tem o ID do evento e precisa escolher o destino, use [Enviar um evento para um webhook](/br/api/webhook-events/deliver). Esse caminho permite a primeira entrega para o cadastro e segue os mesmos limites de elegibilidade. O pedido retorna `event_id` e `delivery_id`. Consulte a nova entrega para acompanhar o resultado. O aceite do pedido não confirma o recebimento e não cancela as tentativas automáticas da entrega anterior. O registro pode levar alguns instantes para aparecer na consulta após o aceite; aguarde brevemente antes de consultar de novo. Se a fila estiver pausada, a nova entrega também aguarda a retomada, enquanto seu próprio prazo de tentativas continua contando. O reenvio preserva os bytes do corpo original, inclusive seu `id` e `created_at`, e usa a URL e o segredo atuais do webhook. Prepare o receptor para receber o mesmo evento em entregas diferentes sem repetir seu efeito. Reenviar não repete a transação financeira que originou o evento. A nova entrega tem seu próprio prazo de tentativas. O limite para solicitar outro reenvio continua vinculado à criação do evento original; reenviar não renova os 15 dias. Veja [Reenvio manual de eventos](/br/integracoes/webhooks/receber-eventos#reenvio-manual-de-eventos). Eventos `webhook.test` não aceitam reenvio. Para conferir novamente o receptor, [solicite outro teste](/br/api/webhooks/test). Excluir um webhook preserva o histórico disponível para consulta. Use seu identificador como filtro para localizar as entregas anteriores. A exclusão impede o reenvio para aquele cadastro. ## Reenviar vários eventos Use [Reenviar vários eventos](/br/api/webhook-deliveries/resend-batch) para solicitar entregas de até 500 IDs em uma requisição. Cada item segue as mesmas condições do reenvio individual. Você pode reunir entregas de webhooks diferentes da mesma empresa e ambiente. A resposta mantém a ordem dos IDs enviados. Para cada item aceito, ela retorna o evento original e a nova entrega. Um item recusado traz o motivo em `error`, sem impedir o aceite dos demais. HTTP `202` confirma o processamento do pedido; confira cada resultado antes de acompanhar as novas entregas. Se o mesmo ID aparecer mais de uma vez, ou se várias entregas se referirem ao mesmo evento e webhook, o pedido cria uma única nova entrega para esse par. Os resultados correspondentes retornam o mesmo `delivery_id`. Reenviar não cancela as tentativas anteriores, inclusive as que estejam em andamento. Corrija o receptor antes de enviar o pedido e mantenha a deduplicação pelo ID do evento. Se uma falha impedir a resposta da API, parte dos itens pode ter sido aceita. Consulte as entregas antes de repetir todo o pedido. ## Empresa e ambiente Use [autenticação por chave de API ou OAuth](/br/integracoes/autenticacao) da mesma empresa e do mesmo ambiente dos webhooks. Filtros e identificadores não dão acesso a dados de outra empresa ou ambiente. O console aceita somente chaves Sandbox. As consultas não modificam a entrega ou o recurso financeiro. Preserve as chaves e os segredos no ambiente privado da integração. # Reenviar um evento (/br/api/webhook-deliveries/resend) Solicite outra entrega do evento original para o mesmo webhook. O pedido preserva o conteúdo do evento e usa a configuração atual do destino. O `event_id` permanece igual, e o `delivery_id` identifica a nova entrega. Aceitar o pedido não confirma o recebimento nem cancela tentativas da entrega anterior. Veja [Reenviar um evento](/br/api/webhook-deliveries/overview#reenviar-um-evento) para conferir as condições e tratar duplicatas no receptor. POST /v1/webhook_deliveries/{delivery_id}/resend # Reenviar vários eventos (/br/api/webhook-deliveries/resend-batch) Solicite o reenvio dos eventos de várias entregas em uma requisição. Confira o resultado de cada item: um evento recusado não impede o aceite dos demais. Itens do mesmo evento e webhook compartilham uma única nova entrega dentro do pedido. O reenvio preserva o evento original e não cancela as tentativas anteriores. Veja [Reenviar vários eventos](/br/api/webhook-deliveries/overview#reenviar-vários-eventos) para acompanhar os resultados e tratar falhas sem duplicar o pedido. POST /v1/webhook_deliveries/resend # Recuperar uma entrega (/br/api/webhook-deliveries/retrieve) Consulte o resultado e o andamento de uma entrega pelo identificador retornado na listagem, no teste ou no pedido de reenvio. Veja [Acompanhar uma entrega](/br/api/webhook-deliveries/overview#acompanhar-uma-entrega). GET /v1/webhook_deliveries/{delivery_id} # Listar eventos (/br/api/webhook-events) Consulte os eventos da empresa e do ambiente autenticado. Use o identificador do recurso para encontrar os eventos relacionados a uma cobrança ou estorno, mesmo sem conhecer o ID de uma entrega. Veja [Localizar um evento](/br/api/webhook-events/overview#localizar-um-evento) para interpretar os filtros e continuar a paginação. GET /v1/webhook_events # Enviar um evento para um webhook (/br/api/webhook-events/deliver) Informe o evento no caminho e o webhook no corpo. O destino precisa estar ativo, selecionar o tipo do evento e pertencer à mesma empresa e ambiente autenticado. O pedido permite a primeira entrega do evento para esse cadastro. O evento deve ter até 15 dias e manter seu corpo original disponível. A resposta retorna o `delivery_id` para acompanhamento; aceitar o pedido não confirma o recebimento pelo receptor. Com a fila pausada, a entrega aguarda a retomada dentro de seu próprio prazo. Veja [Enviar para um webhook](/br/api/webhook-events/overview#enviar-para-um-webhook) para conferir os limites, preservar a identificação do evento e tratar duplicatas. POST /v1/webhook_events/{event_id}/deliveries # Eventos de webhooks (/br/api/webhook-events/overview) Um evento registra uma mudança na Raims, como o pagamento de uma cobrança. Ele tem um identificador próprio, diferente dos IDs das entregas e das tentativas de envio. Use esta consulta quando tiver o ID recebido no corpo do webhook ou precisar encontrar os eventos de uma cobrança. ## Localizar um evento [Liste os eventos](/br/api/webhook-events) da empresa e do ambiente autenticado. Você pode filtrar por tipo, recurso e período de criação. Use `resource_id` com o identificador público do recurso, como o `ch_` de uma cobrança ou o `rf_` de um estorno. Esse campo não recebe o ID do evento nem da entrega. `created_gte` e `created_lte` são segundos Unix UTC, com limites inclusivos. A lista apresenta os eventos mais recentes primeiro. Comece sem cursor, processe `list` e copie `page.next_after` para `after` enquanto `page.has_next` for verdadeiro. Mantenha os mesmos filtros. Para voltar, use `page.previous_before` em `before`, sem combinar os dois cursores. Veja [Listagem e paginação](/br/api/listagem-e-paginacao). Cada item informa o ID, o tipo, a criação do evento e o recurso relacionado. Um reenvio manual mantém o mesmo evento e não cria outra ocorrência na listagem. O teste `webhook.test` cria um evento próprio para o webhook testado. ## Consultar o conteúdo original Use [Recuperar um evento](/br/api/webhook-events/retrieve) com o UUID do evento. Além dos dados da listagem, a resposta inclui `payload`, uma string com o JSON original. Interprete essa string como JSON quando precisar ler seus campos. A consulta não envia o evento ao seu receptor. O `created_at` da consulta usa segundos Unix UTC. Dentro de `payload`, o `created_at` original continua em ISO 8601. O conteúdo registra o evento naquele momento; consulte o recurso correspondente para conhecer seu estado atual. O conteúdo pode incluir dados da integração. Limite o acesso às pessoas e sistemas autorizados e não o envie ao suporte com informações sensíveis. Para validar notificações recebidas por HTTP, use a [assinatura dos webhooks](/br/integracoes/webhooks/receber-eventos#validar-a-assinatura). ## Encontrar as entregas do evento Use o filtro `event_id` em [Listar entregas](/br/api/webhook-deliveries) para encontrar os envios do mesmo evento, incluindo os reenvios manuais ainda disponíveis no histórico. Cada destino e cada reenvio têm seu próprio `delivery_id`. A existência de um evento não confirma que houve entrega. Ele pode não ter um destino selecionado ou seu envio ainda pode estar aguardando. Uma resposta HTTP `2xx` em uma tentativa confirma somente o aceite pelo receptor, não o processamento posterior no sistema de destino. ## Enviar para um webhook Use [Enviar um evento para um webhook](/br/api/webhook-events/deliver) com o `event_id` no caminho e o `webhook_id` no corpo. Você pode escolher um destino da mesma empresa e ambiente, inclusive quando ele não tinha uma entrega anterior desse evento. O evento precisa ter sido criado há no máximo 15 dias, com o corpo original disponível. O webhook deve estar ativo e selecionar o tipo do evento no momento do pedido. A consulta por 30 dias não amplia essa elegibilidade. Eventos `webhook.test` exigem [outro teste](/br/api/webhooks/test). A resposta `202` retorna o evento original e o identificador da nova entrega. Consulte essa entrega para acompanhar o resultado. O envio usa a URL e os segredos atuais do cadastro e preserva o corpo original, incluindo `id` e `created_at`. O pedido não altera o recurso financeiro nem cancela outras entregas do mesmo evento. Se a fila estiver pausada, a nova entrega aguarda a retomada, com prazo próprio de até 72 horas em Produção ou quatro horas no Sandbox. Seu receptor precisa reconhecer o mesmo evento em entregas diferentes para evitar repetir seus efeitos. Depois de uma resposta incerta da API, consulte as entregas por `event_id` antes de fazer outro pedido. ## Histórico e ambiente Os eventos ficam disponíveis por 30 dias desde sua criação original. Novas tentativas e reenvios não reiniciam esse prazo. O histórico de uma entrega tem seu próprio período, explicado em [Histórico por 30 dias](/br/api/webhook-deliveries/overview#histórico-por-30-dias). As consultas exigem [autenticação](/br/integracoes/autenticacao) por chave de API ou OAuth da mesma empresa e ambiente. O console aceita somente Sandbox. Os registros podem levar alguns instantes para aparecer; uma lista vazia não comprova que uma mudança financeira deixou de acontecer. Consulte a cobrança ou o estorno quando precisar confirmar seu estado. # Recuperar um evento (/br/api/webhook-events/retrieve) Use o UUID do evento para recuperar seus dados e o JSON original em `payload`. A consulta não envia outra notificação e não modifica o recurso financeiro. Veja [Consultar o conteúdo original](/br/api/webhook-events/overview#consultar-o-conteúdo-original) para interpretar a resposta e localizar as entregas relacionadas. GET /v1/webhook_events/{event_id} # Criar um webhook (/br/api/webhooks) Cadastre uma URL de recebimento e selecione os eventos que sua integração precisa acompanhar. Guarde o segredo retornado em um ambiente privado da aplicação: as consultas de configuração não retornam esse valor. Se o receptor ainda não estiver pronto, cadastre com `is_active: false`. Veja [Cadastrar o destino](/br/api/webhooks/overview#cadastrar-o-destino) e [Receber e validar eventos](/br/integracoes/webhooks/receber-eventos) antes de iniciar o recebimento. POST /v1/webhooks # Excluir um webhook (/br/api/webhooks/delete) Exclua o cadastro indicado para impedir novos envios. Requisições já autorizadas ou em andamento ainda podem terminar. Veja [Excluir um destino](/br/api/webhooks/overview#excluir-um-destino). DELETE /v1/webhooks/{webhook_id} # Listar tipos de evento (/br/api/webhooks/event-types) Consulte os tipos disponíveis antes de criar um webhook ou alterar sua seleção. Escolha os eventos que a integração precisa receber. Veja [Selecionar os eventos](/br/api/webhooks/overview#selecionar-os-eventos). GET /v1/webhook_event_types # Consultar a situação do webhook (/br/api/webhooks/health) Consulte a situação conhecida do destino a partir das tentativas de envio. Os horários podem aparecer com atraso; a requisição não testa a URL nem confirma que o receptor esteja disponível agora. Veja [Consultar a situação do destino](/br/api/webhooks/overview#consultar-a-situação-do-destino) para interpretar os estados e a duração das falhas. GET /v1/webhooks/{webhook_id}/health # Listar webhooks (/br/api/webhooks/list) Consulte os cadastros disponíveis para a chave usada na requisição. A listagem apresenta a configuração dos destinos, sem retornar o segredo de assinatura. Veja [Consultar e alterar a configuração](/br/api/webhooks/overview#consultar-e-alterar-a-configuração) e [Listagem e paginação](/br/api/listagem-e-paginacao). GET /v1/webhooks # Webhooks (/br/api/webhooks/overview) Webhooks avisam sua aplicação quando um evento acontece na Raims, como o pagamento de uma cobrança ou a conclusão de um estorno. Cadastre o endereço que receberá essas notificações e selecione os eventos usados pelo seu sistema. A API permite administrar os mesmos cadastros apresentados no [Dashboard](/br/integracoes/webhooks). Confira o recebimento nos registros da sua aplicação e use a situação do destino para acompanhar falhas conhecidas. ## Concluir a primeira integração 1. Prepare o receptor para [validar a assinatura e aceitar o evento](/br/integracoes/webhooks/receber-eventos) antes de processá-lo. 2. Consulte os [tipos de evento](/br/api/webhooks/event-types) e selecione os que sua aplicação vai tratar. 3. [Cadastre o destino](/br/api/webhooks) no Sandbox com `is_active: false`. Guarde o `id` retornado e configure o `secret_key` no servidor do receptor. 4. [Ative o cadastro](/br/api/webhooks/update) e [solicite um teste](/br/api/webhooks/test). Confira o recebimento nos registros da sua aplicação. 5. Use [Simulação](/br/api/simulations/overview) para gerar os eventos financeiros que seu sistema precisa tratar. Verifique as atualizações esperadas e o tratamento de duplicatas. O evento técnico confere o caminho até o receptor e a assinatura. Os testes financeiros conferem a reação da sua aplicação a eventos como `charge.paid`. Ao preparar Produção, use a chave, o cadastro e o segredo desse ambiente. ## Cadastrar o destino Antes de [criar um webhook](/br/api/webhooks), prepare uma URL HTTPS que aceite `POST` com JSON. Use um domínio controlado pela sua empresa, com DNS que resolva para um IPv4 público, na porta padrão `443`. O endereço não pode ser localhost, um IP direto nem conter usuário ou senha. Informe um nome que identifique o sistema e sua finalidade, a URL e os eventos que deseja receber. Guarde o `id` para administrar o cadastro e o `secret_key` para validar a assinatura. Consultas posteriores não retornam o segredo. O cadastro começa ativo. Se o receptor ainda não estiver pronto, use `is_active: false` e ative-o depois pela atualização. A mesma URL não pode ser cadastrada duas vezes na empresa e no ambiente autenticado. O receptor deve validar cada assinatura, reconhecer entregas repetidas e responder dentro do prazo de envio. Siga [Receber e validar eventos](/br/integracoes/webhooks/receber-eventos) para implementar esse tratamento. Se houver restrição de origem, permita os [IPs oficiais da Raims](/br/integracoes/webhooks/ips-oficiais). ## Selecionar os eventos [Liste os tipos de evento](/br/api/webhooks/event-types) para obter os códigos disponíveis no cadastro. Informe esses códigos em `events` e mantenha ao menos um selecionado. Assinar um evento não cria uma ocorrência; a notificação depende da mudança correspondente. Selecione somente os eventos que seu sistema precisa processar. O evento técnico `webhook.test` é enviado pelo comando de teste e não faz parte da seleção de eventos do cadastro. ## Consultar e alterar a configuração [Liste os webhooks](/br/api/webhooks/list) ou [consulte um cadastro](/br/api/webhooks/retrieve) pelo `id`. As consultas retornam a configuração e a situação do destino, sem o segredo de assinatura. Para [atualizar o cadastro](/br/api/webhooks/update), envie somente os campos que deseja alterar, com ao menos um campo na requisição. Omitir um campo preserva seu valor atual. Alterar o nome, a URL ou os eventos mantém o identificador e o segredo. Campos enviados precisam manter um valor válido: `null`, nome ou URL vazios e lista de eventos vazia não limpam a configuração. A edição de URL e eventos vale para as próximas seleções e tentativas de envio. Requisições já autorizadas ou em andamento podem terminar com a configuração anterior. Adicionar um tipo pode incluir eventos anteriores que ainda aguardavam preparação; a alteração não reenvia entregas já encerradas. Eventos antigos que continuam selecionados podem ser mantidos ou removidos, mas só podem ser adicionados novamente se estiverem no catálogo atual. ## Consultar a situação do destino [Consulte a situação do webhook](/br/api/webhooks/health) para saber se há um episódio de falhas registrado. A resposta reúne os horários disponíveis da primeira e da última falha do episódio, do último sucesso e da atualização dessas informações. | `status` | Significado | | ---------- | ---------------------------------------------------------------------------------- | | `healthy` | O resultado conhecido é um aceite HTTP `2xx`, sem um episódio de falhas em aberto. | | `failing` | Há falhas registradas desde o último encerramento do episódio. | | `disabled` | O cadastro está desativado. | | `unknown` | Não há informação disponível para determinar a situação. | Enquanto o status for `failing`, `failure_duration_seconds` informa há quanto tempo começou o episódio. Os horários de falha pertencem ao momento em que seu resultado foi registrado; não são a data de criação do evento. Uma entrega aceita com HTTP `2xx` encerra o episódio. A desativação também o encerra, por isso um destino desativado pode não ter horários de falha. As informações vêm das tentativas de envio e podem aparecer com atraso. `observed_at` informa a última atualização disponível. A consulta não testa a URL nem monitora sua disponibilidade continuamente. Use o [teste de recebimento](/br/api/webhooks/test) quando precisar conferir uma nova chamada; o resultado desse teste não altera a situação registrada. ## Pausar e retomar a fila [Pause a fila](/br/api/webhooks/pause) antes de uma manutenção no seu receptor. Envie `is_paused: true` para um webhook ativo. A Raims mantém as entregas pendentes e inclui os novos eventos selecionados, mas não inicia seus envios enquanto a pausa estiver ativa. Uma requisição já autorizada pode terminar. A pausa não congela nem amplia os prazos: entregas financeiras continuam limitadas a 72 horas em Produção e quatro horas no Sandbox. Uma entrega cujo prazo acabar durante a pausa não será enviada na retomada. Depois de corrigir ou atualizar o receptor, envie `is_paused: false` no mesmo endpoint. A retomada libera as entregas ainda válidas, de acordo com os limites de envio existentes. Ela não garante envio imediato, uma ordem específica ou a recuperação de entregas encerradas. As consultas de configuração informam `is_paused` e `paused_at`. Pausar ou retomar encerra o episódio anterior de falhas. Isso não confirma que o receptor se recuperou; confira os registros da sua aplicação depois da retomada. A pausa é separada de `is_active`: o cadastro continua ativo e mantém sua configuração. O [teste técnico](/br/api/webhooks/test) pode ser solicitado durante a pausa para conferir o receptor antes de retomar a fila. Ele mantém uma tentativa HTTP e prazo de cinco minutos, sem alterar a situação de falhas do cadastro. ## Desativar e reativar Use `is_active: false` na atualização para desativar o destino e `is_active: true` para reativá-lo. O cadastro, o segredo e a seleção de eventos são preservados. Desativar impede novos envios. Uma entrega pendente é encerrada se sua próxima tentativa encontrar o destino desativado. Se a reativação ocorrer antes, a entrega pode continuar dentro do prazo original. Reativar não reenvia o histórico nem recupera entregas encerradas. Falhas não pausam nem desativam o destino automaticamente. A Raims continua tentando cada entrega dentro dos [limites de seu ambiente](/br/integracoes/webhooks/receber-eventos#falhas-e-novas-tentativas-de-webhook). Alterar nome, URL, eventos ou segredo não reativa um cadastro desativado manualmente. Para uma manutenção com preservação das entregas ainda válidas, use [Pausar e retomar a fila](#pausar-e-retomar-a-fila). Se a fila estiver pausada, reativar o cadastro mantém essa pausa. Retome a fila separadamente quando o receptor estiver pronto. `disabled_reason: manual` identifica a desativação manual. Cadastros desativados anteriormente por falhas podem manter `continuous_failure`; confira e reative esses cadastros quando o receptor estiver pronto. Quando o webhook está ativo, esse campo fica `null`. ## Rotacionar o segredo [Solicite a rotação](/br/api/webhooks/rotate-secret) quando precisar substituir o segredo de assinatura. O identificador do webhook permanece o mesmo. Guarde o novo `secret_key` e atualize o receptor. Consultas de configuração não recuperam esse valor. Prepare o armazenamento seguro antes de solicitar a rotação. O período de transição permite receber assinaturas do segredo novo e do anterior enquanto sua aplicação é atualizada. Por padrão, ele dura 24 horas. Use `grace_period_seconds: 0` se houver suspeita de vazamento ou se precisar substituir o segredo imediatamente. Nesse caso, novos envios usam somente o novo segredo assim que a rotação é confirmada. Se houver uma transição ativa, ela é encerrada e os dois segredos anteriores são substituídos. Requisições já autorizadas ou em andamento ainda podem chegar com uma assinatura anterior. Retire os segredos antigos da configuração do receptor para que deixem de ser aceitos. Durante a transição, repetir a rotação com um período maior que zero retorna o mesmo segredo novo e o mesmo prazo, sem prorrogá-lo. Confira `previous_secret_expires_at` e aceite qualquer assinatura `v1` válida, conforme a [validação de assinatura](/br/integracoes/webhooks/receber-eventos#validar-a-assinatura). No Dashboard, a rotação sempre usa a troca imediata. A escolha do período de transição fica disponível na API. ## Testar o recebimento [Envie um evento de teste](/br/api/webhooks/test) para um webhook ativo. A requisição não recebe corpo e retorna `event_id` e `delivery_id` para identificar o evento e seu envio. O aceite do pedido não confirma que o receptor o recebeu. O evento tem `type: webhook.test`, `data.object: webhook` e `data.id` com o identificador do cadastro. Ele usa a URL e a assinatura do webhook e faz uma requisição HTTPS real. Não cria nem altera cobranças, pagamentos, estornos ou saldos. O teste realiza uma tentativa HTTP, com prazo de até cinco minutos para o envio. Se ela falhar, corrija o receptor antes de solicitar outro teste. O resultado desse teste não altera a contagem de falhas nem provoca a desativação automática do cadastro. Cada nova requisição de teste cria outro evento. Para testar novamente, use esse mesmo endpoint. Para verificar o tratamento de eventos financeiros, use [Simulação](/br/api/simulations/overview) com uma chave Sandbox. Mantenha os efeitos desses testes separados dos dados de produção da sua aplicação. ## Excluir um destino [Exclua o webhook](/br/api/webhooks/delete) quando ele deixar de ser usado. A exclusão impede novos envios para aquele cadastro. Requisições já autorizadas ou em andamento ainda podem terminar. Confira antes se algum sistema depende do destino. Para interromper o recebimento e manter a configuração, desative o cadastro. Os registros já existentes continuam sujeitos aos prazos de consulta do Dashboard, mas não podem ser reenviados para um cadastro excluído. ## Empresa e ambiente Todas as requisições seguem a [autenticação por chave de API ou OAuth](/br/integracoes/autenticacao). O acesso fica limitado à empresa e ao ambiente autenticados. Uma requisição no Sandbox administra somente os webhooks do Sandbox; uma requisição em Produção administra somente os de Produção. O console desta documentação aceita apenas chaves Sandbox. Com OAuth, cada requisição precisa estar entre os acessos concedidos e permanecer permitida a quem autorizou a conexão. As confirmações de identidade solicitadas pelo Dashboard pertencem às ações feitas naquela interface. Sandbox envia requisições HTTPS reais. Use um destino de testes separado e proteja o segredo no servidor da sua aplicação. Nunca o envie ao suporte ou o inclua em capturas de tela, URLs e logs. # Pausar ou retomar a fila (/br/api/webhooks/pause) Use `is_paused: true` para pausar e `is_paused: false` para retomar a fila de um webhook ativo. A pausa preserva entregas pendentes e novos eventos, mas mantém os prazos originais. Requisições já autorizadas podem terminar. Veja [Pausar e retomar a fila](/br/api/webhooks/overview#pausar-e-retomar-a-fila) para entender a expiração durante a pausa e o comportamento da retomada. PATCH /v1/webhooks/{webhook_id}/pause # Recuperar um webhook (/br/api/webhooks/retrieve) Consulte a URL, os eventos e a situação do webhook pelo identificador recebido no cadastro ou na listagem. A consulta não retorna o segredo de assinatura. Veja [Consultar e alterar a configuração](/br/api/webhooks/overview#consultar-e-alterar-a-configuração). GET /v1/webhooks/{webhook_id} # Rotacionar o segredo (/br/api/webhooks/rotate-secret) Solicite um novo segredo para o mesmo cadastro e atualize o receptor. Guarde o valor retornado em um cofre de segredos; as consultas de configuração não o recuperam. O período de transição permite atualizar o receptor antes de os envios passarem a usar somente o segredo novo. Se houver suspeita de vazamento, use `grace_period_seconds: 0` para substituir o segredo imediatamente, mesmo durante uma transição em andamento. Veja [Rotacionar o segredo](/br/api/webhooks/overview#rotacionar-o-segredo) para escolher o período de transição e validar as assinaturas durante a troca. POST /v1/webhooks/{webhook_id}/rotate_secret # Enviar um evento de teste (/br/api/webhooks/test) Solicite um evento técnico para o destino cadastrado. O teste faz uma requisição HTTPS real, sem criar cobrança, pagamento ou estorno. O aceite do pedido retorna os identificadores do evento e do envio, mas não confirma seu recebimento nem o tratamento de eventos financeiros pelo seu sistema. Veja [Testar o recebimento](/br/api/webhooks/overview#testar-o-recebimento) e confira o resultado nos registros do receptor. POST /v1/webhooks/{webhook_id}/test # Atualizar um webhook (/br/api/webhooks/update) Envie ao menos um campo para alterar o cadastro. Campos omitidos mantêm seus valores atuais. Confira a URL e os eventos antes de confirmar uma mudança que afete o recebimento. Veja [Consultar e alterar a configuração](/br/api/webhooks/overview#consultar-e-alterar-a-configuração) e [Desativar e reativar](/br/api/webhooks/overview#desativar-e-reativar). PATCH /v1/webhooks/{webhook_id} # Listar saques (/br/api/withdrawals) Consulte os saques da sua empresa para acompanhar o andamento e conciliar as saídas da Raims com a conta de destino. Você pode filtrar pela situação e pela data da solicitação. A consulta não solicita nem cancela saques. Veja como interpretar os valores e percorrer o histórico em [Saques](/br/api/withdrawals/overview). GET /v1/withdrawals # Consultar saque automático (/br/api/withdrawals/automatic-settings) Consulte a configuração da tentativa diária de saque da empresa. A resposta informa se ela está ativa, o valor mínimo, o horário e a próxima tentativa prevista. A consulta exige acesso autorizado em Produção. Veja as condições em [Saque automático](/br/api/withdrawals/overview#saque-automático). GET /v1/withdrawals/automatic_settings # Listar destinos de saque (/br/api/withdrawals/destinations) Consulte os destinos próprios cadastrados e verificados para saque. A lista mostra a chave Pix mascarada e identifica o destino padrão da empresa. Esta consulta exige acesso autorizado em Produção. O console aceita somente Sandbox. Veja como percorrer a lista e conferir o destino em [Destinos de saque](/br/api/withdrawals/overview#consultar-os-destinos-de-saque). GET /v1/withdrawal_destinations # Consultar condições de saque (/br/api/withdrawals/limits) Consulte as condições atuais da conta antes de solicitar um saque. A resposta informa o saldo disponível, o valor mínimo, a regra de tarifa e, em Produção, se há destino configurado e os limites do período. A consulta não reserva saldo ou limite. Veja como interpretar esses valores em [Saques](/br/api/withdrawals/overview#consultar-condições-e-limites). GET /v1/withdrawals/limits # Saques (/br/api/withdrawals/overview) Use a API de saques para retirar valores da conta Raims por Pix e acompanhar o envio para a conta da empresa. As consultas ajudam a planejar a retirada e conferir o valor recebido no destino. | Finalidade | Método e caminho | | ----------------------------- | ------------------------------------------ | | Consultar condições e limites | `GET /v1/withdrawals/limits` | | Solicitar um saque Pix | `POST /v1/withdrawals` | | Consultar saque automático | `GET /v1/withdrawals/automatic_settings` | | Atualizar saque automático | `PATCH /v1/withdrawals/automatic_settings` | | Listar o histórico de saques | `GET /v1/withdrawals` | | Recuperar um saque pelo ID | `GET /v1/withdrawals/{id}` | | Listar destinos verificados | `GET /v1/withdrawal_destinations` | | Recuperar um destino pelo ID | `GET /v1/withdrawal_destinations/{id}` | ## Consultar condições e limites Use [Consultar condições de saque](/br/api/withdrawals/limits), com `GET /v1/withdrawals/limits`, antes de solicitar uma retirada. A resposta informa o saldo disponível, o valor mínimo por saque e a tarifa para valores abaixo do limite indicado. A tarifa é descontada do valor solicitado. Os valores monetários usam centavos de real. Em Produção, `destination_configured` informa se existe um destino cadastrado. O objeto `limits` apresenta os limites diário e noturno, o limite do período atual, quanto já foi utilizado e quanto resta. O teto informado para uma solicitação considera os limites de saque; o valor solicitado também precisa caber no saldo disponível e respeitar a tarifa. O período diário começa às 06:00 e termina às 06:00 do dia seguinte, pelo horário de São Paulo. Das 20:00 às 06:00, o saque também precisa caber no limite noturno, que faz parte do diário. `period` identifica o período atual e `period_ends_at` informa seu término em segundos Unix UTC. Saques em processamento comprometem o limite; uma falha confirmada libera o valor. Essa consulta não reserva dinheiro ou limite nem garante que uma solicitação será aceita. Outros saques podem alterar as condições entre a consulta e o pedido. Os limites consideram os saques registrados na Raims; transferências feitas por outro canal na mesma conta também podem afetar o valor aceito. No Sandbox, a resposta apresenta o saldo simulado e as regras de mínimo e tarifa. `destination_configured` retorna `false` e `limits` retorna `null`. Esses campos não informam o destino nem os limites da conta de Produção. Em Produção, `limits` também pode retornar `null` quando não houver limites disponíveis para consulta. Isso não significa que a conta pode sacar sem limite. ## Consultar os destinos de saque Use [Listar destinos de saque](/br/api/withdrawals/destinations) para conferir as chaves Pix verificadas da própria empresa. Cada destino informa o nome do titular, o ISPB da instituição, o tipo e a chave mascarada. `is_default` identifica o destino padrão atual; `verified_at` informa a data da verificação em segundos Unix UTC. A listagem exige acesso autorizado em Produção. O Sandbox retorna `403 DATA_ENVIRONMENT_NOT_SUPPORTED`, pois não tem destinos bancários. O console desta documentação aceita somente chaves Sandbox; faça a consulta pelo servidor da integração, sem inserir uma chave de Produção no navegador. Comece sem cursor, processe `list` e copie `page.next_after` para `after` enquanto `page.has_next` for verdadeiro. Uma página pode ter menos itens que `page_size` ou estar vazia e ainda indicar outra página. Continue pelo cursor até `has_next` ser `false`; não use o tamanho de `list` para concluir a navegação. Para voltar, copie `page.previous_before` para `before`, sem enviar os dois cursores juntos. Consulte [Listagem e paginação](/br/api/listagem-e-paginacao). Para conferir um destino específico, use [Recuperar um destino de saque](/br/api/withdrawals/retrieve-destination) e o `id` completo recebido, com prefixo `wdst_`. Esse identificador pertence ao destino, enquanto `wd_` identifica uma solicitação de saque. Um destino removido ou que não esteja mais disponível para a empresa retorna a mesma resposta de recurso não encontrado. Consultar um destino não o seleciona nem solicita uma transferência. Para cadastrar uma chave, removê-la ou trocar o padrão, use **Conta / Configurações / Chave Pix de saque**. A solicitação pela API usa o destino padrão disponível naquele momento. Para exigir que o destino continue sendo o mesmo que você conferiu, envie seu `id` em `expected_destination_id`. Esse campo não seleciona outro destino. Confira também as condições e os limites antes de pedir o saque; a presença de um destino na lista não garante que a retirada será aceita. ## Solicitar um saque Pix Use [Solicitar saque](/br/api/withdrawals/request), com `POST /v1/withdrawals`, e informe `amount_cents` com o valor total que deseja retirar, incluindo a tarifa. A requisição exige acesso autorizado em Produção. O destino é a chave Pix padrão cadastrada em **Conta / Configurações / Chave Pix de saque**. A chave deve pertencer ao mesmo CNPJ da empresa. A Raims confere a titularidade ao cadastrar o destino e ao solicitar o saque. A API não recebe ou altera a chave Pix de destino. Para cadastrar ou trocar essa chave, use o Dashboard antes de solicitar. A solicitação está sujeita à disponibilidade da conta para saques, ao saldo disponível, ao valor mínimo e aos limites aplicáveis. Ter uma credencial válida não elimina essas condições. O campo opcional `expected_destination_id` permite vincular o pedido ao destino próprio verificado que você consultou. Copie o `id` do item com `is_default: true`. Se esse destino mudar ou deixar de ser válido, a resposta será `409 WITHDRAWAL_DESTINATION_CHANGED`, sem aceitar o saque para outro destino. Confira novamente o padrão e revise a solicitação antes de tentar outra vez. Omitir o campo ou enviar `null` mantém o uso do destino padrão vigente. A resposta `202` informa que o saque ainda precisa ser acompanhado. Guarde o `id` retornado e consulte `GET /v1/withdrawals/{id}`. Enquanto o saque estiver pendente, em processamento ou com resultado desconhecido, acompanhe esse mesmo identificador antes de solicitar outra retirada. A resposta `200` pode apresentar o resultado já encerrado de uma solicitação repetida. Se a resposta informar `PIX_WITHDRAWAL_RESULT_UNKNOWN`, use o caminho retornado no header `Location` para consultar o saque antes de solicitar outra retirada. Para falta de saldo ou limite, consulte novamente as condições. Quando o erro indicar um destino ausente ou alterado, confira a chave Pix padrão no Dashboard. Para conferir o fluxo pelo Dashboard, consulte [Saques por Pix](/br/financeiro/saques). ## Saque automático Use [Consultar saque automático](/br/api/withdrawals/automatic-settings) para ler a configuração e [Atualizar saque automático](/br/api/withdrawals/update-automatic-settings) para ativar, desativar ou ajustar a tentativa diária. Os dois endpoints exigem acesso autorizado em Produção. A requisição usa a chave de API ou a sessão OAuth, sem código de confirmação (OTP) por requisição ou cookie do Dashboard. O saque automático usa o destino próprio selecionado no Dashboard. Cadastre e verifique a chave Pix da empresa antes de ativar a configuração. A API não recebe outra chave Pix nem muda o destino da retirada. Envie `enabled: true` para ativar e `enabled: false` para desativar. `minimum_amount_cents` é o saldo mínimo que permite a tentativa, em centavos de real. Esse campo não fixa o valor de cada saque: a tentativa considera o saldo disponível e o limite Pix restante. Se o limite permitir retirar apenas parte do saldo, o restante continua na conta. `time` define o horário diário em `HH:mm`, pelo fuso de São Paulo. Por exemplo, `18:30` representa 18h30 em São Paulo. Omitir um campo preserva seu valor atual; `null` não é aceito. Enviar novamente os mesmos valores mantém a configuração e a próxima tentativa prevista. Salvar a configuração não solicita um saque imediato. `next_execution_at` informa a próxima tentativa prevista em segundos Unix UTC, ou `null` quando não houver uma programada. Esse horário não confirma uma retirada. Desativar o saque automático impede novas tentativas; acompanhe no histórico os saques que já tiverem sido solicitados. A tentativa depende de a conta estar apta para sacar e de o destino continuar válido. O saldo disponível precisa alcançar o mínimo configurado, e o limite restante precisa permitir pelo menos o valor mínimo de um saque. Se uma dessas condições não for atendida, não há retirada naquela tentativa. As mesmas regras de tarifa e limites dos saques manuais se aplicam. Acompanhe os pedidos gerados em [Listar saques](/br/api/withdrawals) e confira seu `status`. Configuração ativa ou próxima tentativa informada não comprovam transferência concluída. Para os passos no Dashboard, consulte [Saques automáticos](/br/financeiro/saques-automaticos). ## Consultar o histórico de saques Use [Listar saques](/br/api/withdrawals), com `GET /v1/withdrawals`. Você pode filtrar pela situação e pelo intervalo da solicitação. As datas `requested_gte` e `requested_lte` usam segundos Unix UTC e incluem os instantes informados. Por padrão, os saques mais recentes aparecem primeiro. A resposta usa `list` e `page`. Comece sem cursor, processe `list` e copie `page.next_after` para `after` enquanto `page.has_next` for verdadeiro. Mantenha os filtros, a ordenação e a mesma conexão ou chave durante a navegação. Para mudar a consulta, comece novamente sem cursor. Para voltar, use `page.previous_before` em `before`. Copie o cursor inteiro, sem interpretar ou alterar seu conteúdo, e não envie os dois cursores juntos. Veja [Listagem e paginação](/br/api/listagem-e-paginacao). ## Recuperar um saque pelo ID Use [Recuperar um saque](/br/api/withdrawals/retrieve), com `GET /v1/withdrawals/{id}`. Informe o `id` completo, com prefixo `wd_`, recebido na listagem. No [Extrato](/br/api/statements/overview), um lançamento com `reference_type: 3` pode informar esse identificador em `reference_id`. Use-o para consultar o saque relacionado e conferir seu resultado. O ID do saque é diferente do ID do lançamento, que usa o prefixo `st_`. ## Valores e destino Os valores usam centavos de real: | Campo | Significado | | ------------------ | --------------------------------------------------------- | | `amount_cents` | Valor solicitado para o saque, incluindo a tarifa. | | `fee_amount_cents` | Tarifa prevista, cobrada quando o saque é concluído. | | `net_amount_cents` | Valor destinado à transferência, após descontar a tarifa. | Por exemplo, um saque com `amount_cents: 10000` e `fee_amount_cents: 100` tem `net_amount_cents: 9900`, equivalentes a R$ 99,00 para o destino. Esses valores não confirmam a transferência. Considere o saque concluído somente quando `status` for `COMPLETED`; falha ou cancelamento não comprovam recebimento nem cobrança da tarifa. `pix_destination` identifica o destino Pix disponível, com a chave mascarada. `bank_account` apresenta os dados disponíveis de uma conta bancária usada no saque, também com o número da conta mascarado. Esses campos ficam `null` quando não houver dados daquele tipo de destino. Consultar o histórico não permite mudar o destino cadastrado. ## Acompanhar a situação do saque Confira `status` antes de considerar o saque concluído: | `status` | Como interpretar | | ------------ | ------------------------------------------------------------------------------------------------- | | `PENDING` | A solicitação aguarda processamento. | | `PROCESSING` | O saque está em processamento e ainda não tem conclusão confirmada. | | `COMPLETED` | O saque foi concluído. | | `FAILED` | A falha foi confirmada. Consulte `failure_reason`, quando disponível. | | `CANCELED` | A solicitação foi cancelada. | | `UNKNOWN` | Não há uma situação reconhecida para apresentar. Confira o saque antes de concluir a conciliação. | `requested_at` informa quando o saque foi solicitado. As datas de conclusão, falha e cancelamento ficam `null` enquanto o respectivo resultado não estiver registrado. Todas usam segundos Unix UTC. Quando houver falha, `failure_reason` informa um código público e uma mensagem em inglês. Use o código no tratamento da integração. A mensagem serve ao diagnóstico; não é necessário compará-la literalmente. Consulte [Motivos de falha do saque](/br/tipos-e-identificadores/financeiro#motivos-de-falha-do-saque) para entender cada código e a conferência indicada antes de outra solicitação. Consultas repetidas não iniciam nem aceleram o saque. Um registro pendente ou em processamento não comprova que o dinheiro chegou à conta de destino. ## Empresa e ambiente As requisições seguem a [autenticação](/br/integracoes/autenticacao) por chave de API ou OAuth, com a empresa e o ambiente autorizados. Uma chave Sandbox não acessa saques de Produção. Se não houver saques no ambiente consultado, a listagem retorna `list` vazia. A solicitação de saque está disponível somente em Produção; uma chave Sandbox permite consultar o histórico simulado e as condições de teste, mas não solicitar uma transferência. O console desta documentação aceita somente chaves Sandbox. A consulta individual devolve a mesma resposta de recurso não encontrado quando o ID não existe ou não pertence à empresa e ao ambiente autenticado. # Solicitar saque (/br/api/withdrawals/request) Solicite um saque Pix informando o valor que deseja retirar. O destino é a chave Pix da própria empresa cadastrada no Dashboard. A tarifa é descontada do valor solicitado. Para exigir o destino padrão que você conferiu, envie `expected_destination_id`. O campo não cadastra nem seleciona outro destino. Veja a orientação em [Solicitar um saque Pix](/br/api/withdrawals/overview#solicitar-um-saque-pix). Guarde o identificador retornado e acompanhe o mesmo saque enquanto ele estiver pendente ou em processamento. O aceite não confirma que o dinheiro chegou à conta de destino. Veja as condições de uso e o acompanhamento em [Saques](/br/api/withdrawals/overview). POST /v1/withdrawals # Recuperar um saque (/br/api/withdrawals/retrieve) Consulte um saque pelo identificador recebido na listagem ou na referência de um lançamento do extrato. A resposta informa os valores, o destino disponível e a situação atual, na empresa e no ambiente autenticado. Consultar não altera o saque nem acelera sua conclusão. Veja como acompanhar o resultado em [Saques](/br/api/withdrawals/overview). GET /v1/withdrawals/{id} # Recuperar um destino de saque (/br/api/withdrawals/retrieve-destination) Consulte um destino de saque pelo ID recebido na listagem. A consulta apresenta os dados mascarados e informa se ele é o padrão atual. Use uma chave de Produção no servidor da sua integração. Cadastro e troca de destino são feitos no Dashboard. Consulte [Destinos de saque](/br/api/withdrawals/overview#consultar-os-destinos-de-saque). GET /v1/withdrawal_destinations/{id} # Consultar saques em processamento (/br/api/withdrawals/summary) Consulte a quantidade e o valor total dos saques pendentes ou em processamento da empresa. A resposta exige acesso autorizado em Produção e não confirma o recebimento na conta de destino. Veja como interpretar os valores em [Saques em processamento](/br/api/balances/overview#saques-em-processamento). GET /v1/withdrawals/summary # Atualizar saque automático (/br/api/withdrawals/update-automatic-settings) Configure a tentativa diária de saque para o destino próprio selecionado no Dashboard. Envie somente os campos que deseja alterar. A requisição exige acesso autorizado em Produção e não pede código de confirmação (OTP). Salvar a configuração não solicita uma retirada imediata. Confira as regras de valor, horário e acompanhamento em [Saque automático](/br/api/withdrawals/overview#saque-automático). PATCH /v1/withdrawals/automatic_settings # Changelog (/br/changelog) # As atualizações da Raims em um só lugar (/br/changelog/post/2026-10-28-changelog) O changelog passa a reunir as novidades, melhorias e correções dos produtos da Raims. Cada publicação registra a data e a descrição da mudança, com links para a documentação dos produtos envolvidos. Consulte os guias de cada produto para conferir as condições de uso atuais. No [changelog](/br/changelog), filtre as atualizações por produto ou grupo de produtos. Cada publicação tem um link próprio com a data e o texto completo da mudança. Use a paginação para consultar publicações anteriores. # SDK .NET da API pública disponível no NuGet (/br/changelog/post/2026-10-29-sdk-dotnet) O SDK oficial .NET da API pública pode ser instalado pelo NuGet como pacote `Raims`. Ele atende aplicações x64 em .NET Framework 4.8/4.8.1 e .NET 10, com serviços por recurso, respostas tipadas, paginação e validação de webhooks. ```bash dotnet add package Raims ``` Use a chave de API no backend da integração. Empresa, ambiente e permissões continuam definidos pela credencial validada; as respostas pendentes e as regras de idempotência da API permanecem aplicáveis. Consulte o [guia do SDK .NET](/br/integracoes/sdk-dotnet) para instalar, configurar e começar a integração. # Instalação direta e licenças do Raims CLI (/br/changelog/post/2026-10-30-raims-cli-direct) O Raims CLI 0.1.1 oferece instaladores para Windows x64, Linux (x64 e ARM64) e macOS (x64 e ARM64). A instalação direta usa uma pasta do usuário e permite executar o CLI pelo caminho completo, sem Node.js ou npm. O instalador mostra um plano por padrão e só aplica a instalação com `-apply`. O instalador 0.1.1 seleciona o patch estável mais recente da linha 0.1. Para instalar pelo npm, inclusive em CI, use `npm install -g @raimshq/cli@latest`. Na instalação direta, uma atualização pode ser baixada silenciosamente e ativada na próxima execução elegível. O comando em andamento mantém sua versão. Você pode desativar a atualização ou exigir uma versão já disponível; preserve o cache de versões e os backups. `raims licenses` apresenta os avisos e licenças incluídos na versão executada, sem perfil ou rede. `raims licenses --output json` devolve o texto e seu SHA-256. Consulte [Instalação direta](/br/cli/direct-installation), [CI e automação](/br/cli/automation#controlar-a-versão) e [Avisos e licenças](/br/cli#consultar-avisos-e-licencas). # Raims CLI disponível no npm (/br/changelog/post/2026-10-30-raims-cli-npm) O Raims CLI está disponível no npm como pacote `@raimshq/cli`. A primeira release é a versão `0.1.0`. Você também pode instalar esse pacote com Yarn Classic, pnpm ou Bun. O [guia de instalação](/br/cli#instalar-pelo-npm) reúne os comandos e explica a execução sob demanda com Yarn 2 ou superior. Ele requer Node.js 22 ou superior e oferece pacotes para Windows x64, Linux (x64 e ARM64) e macOS (x64 e ARM64). ```bash npm install -g @raimshq/cli@latest raims version ``` Use os comandos para consultar e gerenciar recursos da API pública no terminal ou em scripts. Configure um perfil com o nome da variável de ambiente que contém sua chave de API. O perfil não guarda o valor da chave; a credencial validada pela API determina a empresa, o ambiente e as permissões. Atualize pelo mesmo gerenciador usado na instalação. O CLI não troca automaticamente a versão mantida por esse gerenciador. Com npm: ```bash npm install -g @raimshq/cli@latest ``` Consulte o [guia do Raims CLI](/br/cli) para instalar e configurar os perfis e a [referência dos comandos](/br/cli/reference) para escolher as opções da sua integração. # SDK PHP da API pública disponível no Packagist (/br/changelog/post/2026-10-30-sdk-php) O SDK oficial PHP da API pública pode ser instalado pelo Composer como pacote `raims/raims-php`. Ele requer PHP 8.2 ou superior em 64 bits e oferece serviços por recurso, respostas tipadas, paginação por cursor e validação de assinaturas de webhook. ```bash composer require raims/raims-php ``` Use a chave de API no backend da integração. Empresa, ambiente e permissões continuam definidos pela credencial validada; as respostas pendentes e as regras de idempotência da API permanecem aplicáveis. Consulte o [guia do SDK PHP](/br/integracoes/sdk-php) para instalar, configurar e começar a integração. # Login pelo navegador no CLI e conexão MCP (/br/changelog/post/2026-10-31-oauth-cli-mcp) O Raims CLI 0.1.3 permite conectar sua conta pelo navegador com OAuth. Os perfis com chave de API continuam disponíveis para scripts e automações. Para instalar ou atualizar pelo npm, execute `npm install -g @raimshq/cli@latest`. Depois, escolha um perfil e o ambiente de acesso: ```bash raims login --profile pessoal --environment sandbox ``` O navegador abre o login e o consentimento da Raims. Confira a conta, escolha as permissões e conclua a confirmação de segurança quando solicitada. Os tokens ficam cifrados, com proteção pelo cofre nativo do sistema operacional. O [MCP da Raims](/br/integracoes/mcp) conecta aplicativos de IA compatíveis à sua conta por `https://mcp.raims.com`, com OAuth e acesso às operações autorizadas. A conexão não exige copiar uma chave de API. A cada consulta ou alteração de dados, o aplicativo seleciona um ambiente permitido pela conexão. Em **Integração / Aplicativos autorizados**, você pode consultar as conexões que seu perfil permite ver, editar os acessos que pode gerenciar e revogar o acesso. As permissões atuais da pessoa e da conta continuam limitando as operações. A conexão não exige uma nova tela de autorização a cada tarefa. Consulte [Configuração do CLI](/br/cli/configuration), [Conectar um aplicativo MCP](/br/integracoes/mcp), [Aplicativos autorizados](/br/integracoes/aplicativos) e [Contexto da conta](/br/api/accounts/context) para conferir a conta e o ambiente antes de usar os acessos concedidos. # Raims CLI para Windows ARM64 (/br/changelog/post/2026-10-31-raims-cli-windows-arm64) O Raims CLI 0.1.2 inclui o executável nativo para Windows ARM64 nos canais npm e de instalação direta. Para instalar ou atualizar pelo npm, use Node.js 22 ou superior para ARM64 e execute `npm install -g @raimshq/cli@latest`. O npm seleciona o executável pela arquitetura do Node.js. O instalador direto para Windows ARM64 dispensa Node.js e mostra o plano antes de aplicar a instalação com `-apply`. As instalações diretas mantêm a arquitetura escolhida ao executar o CLI e atualizar suas versões. Consulte [Instalar pelo npm](/br/cli#instalar-pelo-npm), [Instalação direta](/br/cli/direct-installation) e [Conferir a arquitetura](/br/cli/diagnostics#conferir-a-arquitetura). # Permissões detalhadas para chaves e aplicativos (/br/changelog/post/2026-11-01-permissoes-integracoes) As chaves de API permitem selecionar ações individuais, como consultar clientes, criar cobranças, revogá-las e solicitar estornos. Conceder uma ação não seleciona as outras automaticamente. Você pode editar as permissões sem trocar o segredo, e cada item tem uma descrição e um link **Saiba mais**. Em **Aplicativos autorizados**, o consentimento e o editor seguem o mesmo padrão de escolhas individuais. A edição permite remover e restaurar acessos da autorização original; outras operações exigem um novo consentimento. Os limites da conta e de quem autorizou continuam valendo. A criação de uma chave pede confirmação de identidade antes de abrir o formulário quando não há uma autorização válida. Enquanto essa autorização for aceita, ela é reutilizada ao criar a chave. Se for necessário confirmar novamente ao salvar, a criação continua com os dados preenchidos, sem outro clique. Funcionários só podem copiar um segredo Sandbox ou rotacionar uma chave quando seus acessos abrangem todas as ações concedidas a ela. O Raims CLI 0.1.4 e o console da documentação também alinham a escolha de ambiente ao modo de autenticação. Com chave de API, a própria chave define empresa e ambiente. No OAuth, a operação precisa aceitar o ambiente informado e a conexão precisa autorizá-lo. No CLI, `--environment` é exclusivo do OAuth; simulações continuam restritas ao Sandbox. Para atualizar o CLI pelo npm, execute `npm install -g @raimshq/cli@latest`. Consulte [Chaves de API](/br/integracoes/chaves-api), [Aplicativos autorizados](/br/integracoes/aplicativos) e [Autenticação](/br/integracoes/autenticacao) para revisar os acessos da sua integração. # SDK Delphi da API pública disponível em código-fonte (/br/changelog/post/2026-11-01-sdk-delphi) O SDK oficial Delphi da API pública está disponível em [código-fonte no GitHub](https://github.com/raimshq/raims-delphi/releases/latest). Ele oferece serviços, parâmetros e modelos de resposta para uso no backend, com paginação e verificação de assinaturas de webhook. O [guia do SDK Delphi](/br/integracoes/sdk-delphi) explica a inclusão de `src` no Search path ou Library path, os requisitos por plataforma e o gerenciamento dos objetos retornados. Compile as units no alvo da sua aplicação e confira seus requisitos. Mantenha a chave de API no backend, fora de executáveis distribuídos aos clientes. # SDK Elixir da API pública disponível no GitHub (/br/changelog/post/2026-11-01-sdk-elixir) O SDK oficial Elixir da API pública está disponível no [GitHub](https://github.com/raimshq/raims-elixir/releases/latest). Aplicações com Elixir 1.18 ou superior e Erlang/OTP 27 ou superior podem adicioná-lo como dependência Git no Mix, com a revisão selecionada registrada em `mix.lock`. O [guia do SDK Elixir](/br/integracoes/sdk-elixir) mostra instalação, cliente, criação de cobranças, paginação e verificação de webhooks. A chave permanece no backend e define o ambiente da integração; simulações financeiras exigem uma chave Sandbox. # SDK Go da API pública disponível (/br/changelog/post/2026-11-01-sdk-go) O SDK oficial Go integra aplicações de servidor à API pública da Raims pelo módulo `github.com/raimshq/raims-go`. Requer Go 1.26.5 ou superior e oferece serviços e respostas tipadas, paginação por cursor e autenticação de webhooks. ```bash go get github.com/raimshq/raims-go@latest ``` Mantenha a chave de API no backend. Empresa, ambiente e permissões continuam definidos pela credencial validada, com as regras de idempotência e resultados pendentes da API. Consulte o [guia do SDK Go](/br/integracoes/sdk-go) para instalar, configurar e começar a integração. # SDK Java da API pública disponível no GitHub (/br/changelog/post/2026-11-01-sdk-java) O SDK oficial Java da API pública está disponível em [releases no GitHub](https://github.com/raimshq/raims-java/releases/latest), com JAR, POM, fontes e Javadoc. Ele requer Java 11 ou superior e oferece builders e respostas tipadas, paginação por cursor e autenticação de webhooks. Baixe os artefatos da release atual antes de instalar o JAR com seu POM: ```bash mvn install:install-file -Dfile=raims-java-release/raims-java.jar -DpomFile=raims-java-release/raims-java.pom ``` Mantenha a chave de API no backend. Empresa, ambiente e permissões continuam definidos pela credencial validada, com as regras de idempotência e resultados pendentes da API. Consulte o [guia do SDK Java](/br/integracoes/sdk-java) para instalar, configurar e começar a integração. # SDK Node.js e TypeScript da API pública disponível no GitHub (/br/changelog/post/2026-11-01-sdk-node) O SDK oficial Node.js da API pública está disponível como pacote `raims`, com módulos ESM e CommonJS e declarações TypeScript. Ele requer Node.js 22 ou superior e oferece serviços por recurso, paginação por cursor e autenticação de webhooks. Baixe `raims-node.tgz` da [release estável atual](https://github.com/raimshq/raims-node/releases/latest) antes de instalar: ```bash npm install ./raims-node-release/raims-node.tgz ``` Mantenha a chave de API no backend. Empresa, ambiente e permissões continuam definidos pela credencial validada, com as regras de idempotência e resultados pendentes da API. Consulte o [guia do SDK Node.js](/br/integracoes/sdk-node) para instalar, configurar e começar a integração. # SDK Python da API pública disponível no GitHub (/br/changelog/post/2026-11-01-sdk-python) O SDK oficial Python da API pública está disponível em [releases no GitHub](https://github.com/raimshq/raims-python/releases/latest), com um wheel instalável pelo pip. Ele requer Python 3.10 ou superior e oferece clientes síncrono e assíncrono, respostas tipadas, paginação por cursor e autenticação de webhooks. Mantenha a chave de API no backend. Empresa, ambiente e permissões continuam definidos pela credencial validada, com as regras de idempotência e resultados pendentes da API. Consulte o [guia do SDK Python](/br/integracoes/sdk-python) para instalar, configurar e começar a integração. # SDK Ruby da API pública disponível no GitHub (/br/changelog/post/2026-11-01-sdk-ruby) O SDK oficial Ruby da API pública está disponível nas [releases do GitHub](https://github.com/raimshq/raims-ruby/releases/latest), com a gem para instalação local. Ele requer Ruby 3.3 ou superior e oferece serviços por recurso, respostas tipadas, paginação por cursor e verificação de webhooks. Consulte o [guia do SDK Ruby](/br/integracoes/sdk-ruby) para baixar, instalar, configurar a credencial e atualizar a integração. Mantenha a chave de API no backend; a credencial validada continua definindo empresa, ambiente e permissões. # SDK Rust da API pública disponível no GitHub (/br/changelog/post/2026-11-01-sdk-rust) O SDK oficial Rust da API pública está disponível no [GitHub](https://github.com/raimshq/raims-rust/releases/latest), com fontes e arquivo `.crate`. A integração usa Rust 1.90 ou superior e Tokio; Cargo pode resolver a dependência Git e registrar a revisão em `Cargo.lock`. Consulte o [guia do SDK Rust](/br/integracoes/sdk-rust) para instalar, configurar o cliente e usar parâmetros tipados, paginação e webhooks. A chave fica no backend. As regras de idempotência e os resultados pendentes da API permanecem aplicáveis. # SDK Elixir da API pública disponível no Hex (/br/changelog/post/2026-11-02-sdk-elixir-hex) O SDK oficial Elixir da API pública está disponível no Hex como pacote [`raims`](https://hex.pm/packages/raims). Se o Hex ainda não estiver instalado, instale-o uma vez: ```bash mix local.hex ``` No projeto da aplicação, consulte a configuração da versão estável atual: ```bash mix hex.info raims ``` Copie a linha `Config:` para a lista de dependências em `deps/0` no `mix.exs`. Depois busque as dependências e compile: ```bash mix deps.get mix compile ``` O SDK requer Elixir 1.18 ou superior com Erlang/OTP 27 ou superior e oferece módulos por recurso, modelos de resposta, paginação por cursor e verificação de webhooks. Os módulos `Raims` permanecem iguais para quem instalava pelo GitHub. Para migrar uma dependência Git ou local, substitua a declaração anterior pela configuração atual do Hex e execute `mix deps.update raims`. Revise e preserve o `mix.lock` e teste a integração antes de atualizar a aplicação. Mantenha a chave de API no backend. Empresa, ambiente e permissões continuam definidos pela credencial validada. Consulte o [guia do SDK Elixir](/br/integracoes/sdk-elixir) para instalar, configurar o cliente e receber webhooks. # SDK Java da API pública disponível no Maven Central (/br/changelog/post/2026-11-02-sdk-java-maven-central) O SDK oficial Java da API pública está disponível no Maven Central como [`com.raims:raims-java`](https://central.sonatype.com/artifact/com.raims/raims-java). Adicione a dependência pelo Maven ou Gradle para resolver o SDK e suas dependências durante o build da aplicação. O SDK requer Java 11 ou superior e oferece builders e respostas tipadas, paginação por cursor e autenticação de webhooks. As coordenadas permanecem iguais para quem instalava o JAR com seu POM pelo GitHub. Atualize a versão da dependência para a versão estável atual no Maven Central e teste os fluxos usados pela integração. Mantenha a chave de API no backend. Empresa, ambiente e permissões continuam definidos pela credencial validada. Consulte o [guia do SDK Java](/br/integracoes/sdk-java) para instalar pelo Maven ou Gradle, configurar o cliente e receber webhooks. # SDK Node.js e TypeScript da API pública disponível no npm (/br/changelog/post/2026-11-02-sdk-node-npm) O SDK oficial Node.js e TypeScript da API pública está disponível no npm como pacote [`@raimshq/raims`](https://www.npmjs.com/package/@raimshq/raims). Instale no diretório da aplicação: ```bash npm install @raimshq/raims ``` O SDK requer Node.js 22 ou superior e inclui módulos ESM e CommonJS, declarações TypeScript, paginação por cursor e autenticação de webhooks. Mantenha a chave de API no backend. Empresa, ambiente e permissões continuam definidos pela credencial validada. Para atualizar para a versão estável atual, use `npm install @raimshq/raims@latest` e teste os fluxos usados pela integração. Se usava um TGZ anterior, substitua a dependência e os imports pelo novo nome do pacote. Consulte o [guia do SDK Node.js](/br/integracoes/sdk-node) para configurar o cliente, integrar os recursos e receber webhooks. # SDK Python da API pública disponível no PyPI (/br/changelog/post/2026-11-02-sdk-python-pypi) O SDK oficial Python da API pública está disponível no PyPI como pacote [`raims`](https://pypi.org/project/raims/). Instale no ambiente virtual da aplicação: ```bash python -m pip install raims ``` O SDK requer Python 3.10 ou superior e inclui clientes síncrono e assíncrono, parâmetros tipados, paginação por cursor e autenticação de webhooks. Mantenha a chave de API no backend. Empresa, ambiente e permissões continuam definidos pela credencial validada. Para atualizar para a versão estável atual, use `python -m pip install --upgrade raims` e teste os fluxos usados pela integração. O import `raims` permanece igual para quem instalava pelo GitHub; ajuste a origem da dependência se a aplicação fixar uma URL Git ou um wheel local. Consulte o [guia do SDK Python](/br/integracoes/sdk-python) para configurar o cliente, integrar os recursos e receber webhooks. # SDK Ruby da API pública disponível no RubyGems (/br/changelog/post/2026-11-02-sdk-ruby-rubygems) O SDK oficial Ruby da API pública está disponível no RubyGems como gem [`raims`](https://rubygems.org/gems/raims). Instale no ambiente da aplicação: ```bash gem install raims ``` O SDK requer Ruby 3.3 ou superior e oferece serviços por recurso, respostas tipadas, paginação por cursor e verificação de webhooks. O `require 'raims'` permanece igual para quem instalava a gem pelo GitHub. Em aplicações com Bundler, adicione `gem 'raims'` ao `Gemfile` e execute `bundle install`. Para atualizar uma dependência existente, use `bundle update raims`; em instalações gerenciadas diretamente pelo RubyGems, use `gem update raims`. Teste os fluxos usados pela integração antes de atualizar a aplicação. Mantenha a chave de API no backend. Empresa, ambiente e permissões continuam definidos pela credencial validada. Consulte o [guia do SDK Ruby](/br/integracoes/sdk-ruby) para instalar, configurar o cliente e receber webhooks. # SDK Rust da API pública disponível no crates.io (/br/changelog/post/2026-11-02-sdk-rust-crates) O SDK oficial Rust da API pública está disponível no crates.io como crate [`raims`](https://crates.io/crates/raims). No projeto da aplicação: ```bash cargo add raims cargo add tokio --features macros,rt-multi-thread ``` O SDK requer Rust 1.90 ou superior e um runtime Tokio. Oferece serviços e respostas tipados, paginação por cursor e verificação de webhooks para integrações assíncronas no backend. Cargo registra as versões resolvidas em `Cargo.lock`. Preserve esse arquivo e use `cargo update -p raims` para atualizar dentro do requisito declarado. Confira no guia como renovar esse requisito para a versão estável atual ou migrar uma dependência Git ou local. Teste a integração antes de atualizar a aplicação. Mantenha a chave de API no backend. Empresa, ambiente e permissões continuam definidos pela credencial validada. Consulte o [guia do SDK Rust](/br/integracoes/sdk-rust) para instalar, configurar o cliente e receber webhooks. # Checkout e formas de pagamento (/br/checkout) O link **Saiba mais** aparece em **Conta / Configurações / Checkout de pagamentos**, abaixo das formas de pagamento padrão. Consultar essa seção exige **Ver configurações da conta**. **Editar aparência do checkout** e **Editar formas de pagamento** controlam suas respectivas alterações. As opções também dependem da disponibilidade da conta. ## Formas de pagamento Os meios habilitados nessa seção formam o padrão da conta. O checkout usa esse padrão quando a cobrança e o link não têm uma configuração própria de meios de pagamento. Alterar o padrão também muda as opções dessas cobranças. | Item | Tipo | Descrição | | --- | --- | --- | | Pix | Padrão da conta | Oferece Pix quando o checkout usa o padrão da conta. | | Boleto | Padrão da conta | Oferece boleto quando o checkout usa o padrão da conta. | **Configuração própria do link** Quando um link é criado com uma configuração própria de meios de pagamento, essa escolha vale somente para o link e não altera o padrão da conta. Se a cobrança já tiver uma lista própria, o link só pode reduzir suas opções. ## Cobranças criadas por integração A requisição [Criar nova cobrança](/br/api/charges) aceita uma lista própria em `payment_method_types`: `[1]` para Pix, `[2]` para boleto ou `[1, 2]` para ambos. Essa lista substitui o padrão da conta somente na cobrança, respeitando a disponibilidade da plataforma. Uma configuração própria do link pode reduzir suas opções. Omitir a lista ou enviar `null` preserva a herança da configuração usada pelo checkout. Sem lista própria, `payment_method: 0` deixa o pagador escolher, enquanto `1` ou `2` restringe a cobrança ao meio indicado. Com a lista preenchida, omita `payment_method` ou envie `0`. Nenhuma dessas opções altera o padrão da conta. Sem lista própria, `payment_method: 1` solicita Pix e `payment_method: 2` solicita boleto na criação, com os dados disponíveis para o integrador apresentar ao pagador. O boleto usa o cadastro do cliente e pode completar campos de endereço ausentes pelo CEP. Uma lista como `payment_method_types: [1]` ou `[2]` mantém a emissão após a escolha no checkout. Veja [Receber o Pix na criação](/br/api/charges/overview#receber-o-pix-na-criação) e [Receber o boleto na criação](/br/api/charges/overview#receber-o-boleto-na-criação). Consulte [Meios de pagamento](/br/meios-de-pagamento#códigos-na-api) para conferir os códigos e a diferença entre o meio cadastrado e a escolha do checkout. Para entender o cadastro do cliente, o valor, o vencimento e o envio opcional do link por e-mail, consulte [Cobranças](/br/api/charges/overview). Use `create_checkout: true` na criação da cobrança para receber seu link em `checkout_url`, mesmo sem envio de e-mail ou URL de retorno. O link pertence àquela cobrança. Para obter ou configurar o link de uma cobrança existente, consulte [Links de pagamento](/br/api/payment-links/overview). O vencimento deve estar pelo menos cinco minutos à frente do horário atual quando a API validar a requisição. O Pix conserva o horário informado; o boleto usa a data de São Paulo, inclusive o mesmo dia. Um checkout expirado não confirma o cancelamento de um boleto já emitido. ## Alterar o padrão ### Abra a aba Formas de Pagamento Acesse **Conta / Configurações / Checkout de pagamentos / Formas de Pagamento** com **Editar formas de pagamento**. ### Defina Pix e boleto Ative ou desative Pix e boleto conforme o padrão desejado. Pelo menos uma forma disponível deve permanecer habilitada. Para desativar a única forma ativa, habilite outra primeiro. ### Salve e confirme Selecione **Salvar forma de pagamento** e aguarde a mensagem de sucesso antes de fechar a seção. **Cartão** pode aparecer como **Indisponível**. Um método mostrado na interface não deve ser considerado habilitado para a operação quando o controle estiver bloqueado. ## Alterar a aparência 1. Acesse **Conta / Configurações / Checkout de pagamentos / Aparência** com **Editar aparência do checkout**. 2. Use **Enviar logo** e **Enviar ícone** para os arquivos da marca. Respeite os formatos, dimensões e tamanho mostrados e aguarde o envio terminar. 3. Informe **E-mail de suporte ao cliente** se quiser indicar um contato da sua empresa no checkout. 4. Ajuste **Cor principal** e **Cor de fundo** em formato hexadecimal. Use **Restaurar cores padrão** se quiser voltar à paleta original. 5. Confira a **Prévia do checkout** no modo de celular ou desktop e selecione **Salvar identidade**. A prévia permite revisar a aparência; ela não cria nem paga uma cobrança. As alterações só devem ser consideradas salvas depois da confirmação. ## Orientar quem recebeu um link O pagador abre o link compartilhado pela empresa e confere os dados da cobrança e os métodos disponíveis. Para Pix, segue o QR Code ou código de pagamento mostrado; para boleto, usa o documento ou a linha de pagamento disponibilizada. A confirmação depende do estado mostrado no checkout e na cobrança. Quando o link tem uma **URL de cancelamento** HTTPS válida e aceita pela Raims, o checkout mostra a seta **Voltar ao site** ao lado da marca. Selecionar essa seta abre o endereço configurado pela empresa. Ela não cancela a cobrança, o Pix ou o boleto e não confirma um pagamento. Sem um endereço de retorno válido, a seta não aparece. Fechar a aba não executa esse retorno automaticamente. A seta pertence às etapas de preenchimento e pagamento do checkout; ela não aparece no recibo nem em um link inválido. Com uma **URL de sucesso** HTTPS válida e aceita pela Raims, o checkout pode tentar abrir automaticamente esse endereço quando receber a confirmação de que a cobrança foi paga. Essa tentativa exige que a mesma abertura já estivesse acompanhando o pagamento antes da confirmação e continue válida para esse acompanhamento. A Raims autoriza no máximo uma tentativa automática por cobrança, mesmo que ela esteja aberta em várias abas ou dispositivos. Recarregar ou reabrir uma cobrança já paga e consultar diretamente a fatura ou o recibo não iniciam nem repetem esse retorno. Se o pagador escolher **Voltar ao site**, consultar a fatura ou o recibo enquanto aguarda o retorno, a navegação automática não é retomada. Gerar um Pix, emitir um boleto ou mostrar um pagamento em processamento não confirma que a cobrança foi paga. Falha, cancelamento e devolução também não acionam esse retorno. Sem URL de sucesso válida, o checkout não usa a URL de cancelamento como destino automático. A tentativa de retorno não garante a chegada ao site: fechar a aba ou perder a conexão pode interromper a navegação. Use o estado confirmado da cobrança para conferir o pagamento; uma visita à URL de sucesso não substitui essa confirmação. Um link de Sandbox indica teste e não deve ser apresentado como pagamento real. Se o checkout informar link não encontrado ou indisponível, confira se abriu o endereço completo enviado pela empresa, sem alterar nenhuma parte. Se o aviso continuar, peça à empresa que emitiu a cobrança para conferir o link. A mensagem não informa o motivo da indisponibilidade e não permite concluir se o link foi pausado, se a cobrança foi cancelada ou se houve pagamento. # Raims CLI (/br/cli) Use `raims` no terminal para consultar e gerenciar recursos da API pública, como clientes, cobranças, links de pagamento, saques e webhooks. Os comandos também funcionam em scripts e pipelines, com saída JSON e códigos de saída definidos. Conecte sua conta pelo navegador com OAuth ou use uma chave de API para scripts e integrações. As requisições usam `https://api.raims.com` nos dois modos. A API confere a empresa, o ambiente, as permissões e as condições de cada recurso. ## Instalar **Node.js é obrigatório** Para usar o CLI pelos gerenciadores de pacotes, instale o [Node.js 22 ou superior](https://nodejs.org/en/download) e confirme a versão com `node --version`. Sem Node.js disponível no terminal, o comando `raims` não inicia. Após instalar o Node.js, reabra o terminal. Há pacotes para Windows (x64 e ARM64), Linux (x64 e ARM64) e macOS (x64 e ARM64). No Windows ARM64, use o Node.js ARM64 para instalar e executar o CLI nativo. Escolha o gerenciador de pacotes de sua preferência e instale o CLI globalmente: ### npm ```bash npm install -g @raimshq/cli@latest ``` ### yarn ```bash yarn global add @raimshq/cli@latest ``` ### pnpm ```bash pnpm add -g @raimshq/cli@latest ``` ### bun ```bash bun add -g @raimshq/cli@latest ``` Após instalar o CLI, execute `raims version` para conferir a versão. Os comandos da aba yarn usam Yarn Classic (1.x). Com Yarn 2 ou superior, execute `yarn dlx @raimshq/cli@latest version`; substitua `version` pelo comando desejado. Essa execução sob demanda dispensa a instalação global. O npm seleciona o executável pela arquitetura do Node.js. Se tiver dúvidas, confira a [arquitetura da instalação](/br/cli/diagnostics#conferir-a-arquitetura). Instalação e atualização precisam de acesso à internet para obter o pacote. Os comandos da API precisam de acesso a `api.raims.com`; a consulta de guias precisa de acesso a `docs.raims.com`, exceto na leitura explícita do cache com `--offline`. Ajuda, mapa de comandos, perfis locais e `doctor` não exigem rede. Para atualizar ou remover o CLI, use o mesmo gerenciador da instalação: ### npm ```bash npm install -g @raimshq/cli@latest npm uninstall -g @raimshq/cli ``` ### yarn ```bash yarn global add @raimshq/cli@latest yarn global remove @raimshq/cli ``` ### pnpm ```bash pnpm add -g @raimshq/cli@latest pnpm remove -g @raimshq/cli ``` ### bun ```bash bun add -g @raimshq/cli@latest bun remove -g @raimshq/cli ``` Em pipelines, obtenha a versão atual na etapa de instalação conforme [CI e automação](/br/cli/automation#controlar-a-versão). Instalações por gerenciadores de pacotes seguem a atualização do gerenciador e não ativam o atualizador da instalação direta. A [instalação direta](/br/cli/direct-installation) oferece o executável nativo com atualizações próprias do CLI. ## Descobrir comandos Use `raims --map` para ver a árvore completa, com uma descrição de cada comando. Um grupo limita a consulta: ```bash raims --map raims charges --map=compact raims --map=paths raims --map=json ``` `compact` omite as descrições, `paths` lista os caminhos completos e `json` retorna a árvore em formato estruturado. O mapa não exige perfil, chave nem corpo e não executa os comandos apresentados. Para preparar uma requisição, acrescente `--help` ao comando. Nos comandos com corpo JSON, a ajuda mostra os campos, os tipos, a obrigatoriedade, a aceitação de `null` e os valores permitidos. Os exemplos de invocação usam `--dry-run`; substitua os placeholders e revise o arquivo antes de enviar. Os exemplos de corpo, quando presentes, vêm da referência pública da API. A ajuda reorganiza as colunas conforme a largura do terminal. Exemplos de comandos e JSON preservam seu conteúdo para você copiá-los; por isso, essas linhas podem ultrapassar a largura disponível. Em arquivos e pipes, a ajuda mantém a apresentação original. ## Primeiros comandos ### Consulte a ajuda ```bash raims --help ``` Acrescente `--help` a um comando para consultar seus argumentos e opções. ### Conecte sua conta ```bash raims login --profile pessoal --environment sandbox ``` Conclua o login e a autorização no navegador. Confira a conta, os ambientes e as permissões antes de autorizar **Raims CLI**. O perfil usa o ambiente escolhido no login. Para automação com chave de API, siga [Configuração e perfis](/br/cli/configuration). ### Confira o acesso à API ```bash raims --profile pessoal auth check ``` O comando consulta as tarifas da conta, sem alterar configurações. Sucesso confirma acesso a essa leitura; outros endpoints mantêm suas próprias permissões e condições. ### Consulte um recurso ```bash raims --profile pessoal --output json customers list --page-size 20 ``` O resultado contém o status HTTP em `status_code`, o identificador da tentativa em `request_id` e a resposta da API em `data`. Use `--help` para consultar filtros, argumentos e opções. ### Verifique a configuração ```bash raims doctor ``` O diagnóstico reúne as verificações da configuração, das permissões locais, da instalação e da política de atualização. Comandos de criação e atualização recebem o corpo JSON por `--data-file` ou pelas flags de campos simples indicadas em `--help`. Consulte [CI e automação](/br/cli/automation) para enviar arquivos, percorrer páginas e tratar resultados pendentes ou falhas. O grupo `simulations` executa as simulações permitidas pela API para a credencial e o recurso. ## Consultar avisos e licenças A partir da versão `0.1.1`, `raims licenses` lê os avisos, licenças e termos de terceiros incluídos na versão em execução: ```bash raims licenses raims licenses --output json ``` Essa consulta é local e não exige perfil, chave ou rede. A saída JSON contém o texto em `text` e seu hash SHA-256 em `sha256`. ## Consultar guias no terminal Use `raims docs search` para encontrar orientações na documentação pública: ```bash raims docs search "webhooks" raims docs search "API keys" --language en --limit 5 ``` Para ler um guia, informe seu caminho no site. Sem caminho, `raims docs` apresenta o guia do CLI: ```bash raims docs /br/integracoes/webhooks raims docs /en/cli --language en ``` Os comandos não exigem perfil ou chave. A busca usa o conteúdo público da Raims e pode ser capturada com `--output json`. `--language br|en` seleciona o idioma; o padrão é português. O caminho deve corresponder ao idioma escolhido. URLs externas e caminhos locais não são aceitos. O conteúdo fica em cache por 24 horas. Use `--refresh` para buscar a versão mais recente ou `--offline` para consultar somente o cache, inclusive quando antigo. O resultado informa a origem e a idade do conteúdo. Sem cache, `--offline` termina com erro. As duas opções não podem ser combinadas; uma atualização que falhar não usa uma cópia antiga silenciosamente. ## Abrir páginas oficiais `raims open` lista atalhos para a documentação, a referência da API, o Dashboard, as chaves de API, os webhooks e o status da Raims. Para abrir a documentação do CLI: ```bash raims open docs ``` Os destinos são fixos e o comando não aceita outra URL. Em CI, com `--no-input` ou sem um terminal, ele imprime o endereço sem iniciar um navegador. Use `--output json` para receber `target`, `url` e `opened`. ## Escolha seu caminho - [Instalação direta](/br/cli/direct-installation): Escolha o instalador, confira o plano e controle as atualizações. - [Configuração e perfis](/br/cli/configuration): Crie perfis e escolha qual usar em cada execução. - [CI e automação](/br/cli/automation): Capture resultados JSON, trate falhas e controle a versão dos seus scripts. - [Diagnóstico](/br/cli/diagnostics): Verifique a instalação e investigue problemas com o comando doctor. - [Referência dos comandos](/br/cli/reference): Consulte a sintaxe, os argumentos e as opções do executável. ## Perfis e credenciais Um perfil pode usar uma sessão OAuth ou uma chave de API. No OAuth, o login acontece no navegador e a sessão fica protegida pelo armazenamento seguro do sistema. Para scripts, associe uma variável de ambiente à chave da API; o arquivo de perfis guarda somente o nome dessa variável. Consulte [Configuração e perfis](/br/cli/configuration) para conectar, conferir o acesso, selecionar o ambiente e sair. Para credenciais de integração, consulte [Chaves de API](/br/integracoes/chaves-api) e [Autenticação](/br/integracoes/autenticacao). # CI e automação (/br/cli/automation) Em scripts e pipelines, escolha o perfil explicitamente e use a saída JSON para interpretar os resultados. Injete credenciais pelo gerenciador de segredos do seu ambiente e preserve seus valores fora dos logs. Use perfis de chave de API em pipelines: configure a variável da chave pelo gerenciador de segredos e associe seu nome com `raims profile set`. O login OAuth exige uma pessoa no navegador e um armazenamento seguro disponível. Ele não é iniciado automaticamente por uma requisição nem por `--no-input`. ## Executar sem interação Use `--no-input` para impedir perguntas durante a execução: ```bash raims --no-input --profile sandbox --output json accounts fees ``` O CLI também considera a execução sem interação quando identifica um ambiente de CI ou quando a entrada não é um terminal. Um comando que precisar de uma entrada ausente termina com erro, sem aguardar uma resposta no terminal. O perfil deve existir na configuração do usuário que executa o processo. Consulte [Configuração e perfis](/br/cli/configuration) para preparar essa configuração e a variável associada à chave. ## Capturar a saída `--output json`, ou `-o json`, seleciona JSON para os resultados dos comandos que apresentam dados. A saída padrão (`stdout`) contém o resultado; as falhas e o diagnóstico usam a saída de erros (`stderr`). Ajuda e scripts de autocompletar preservam seu formato próprio. ```bash raims --no-input --output json version ``` Comandos da API retornam um objeto com `status_code`, `request_id` e `data`. Os dois primeiros campos preservam o status HTTP e o identificador da tentativa; `data` contém a resposta JSON. HTTP 204 retorna `data: null`. HTTP 202 indica um resultado pendente: o comando não aguarda a conclusão. Consulte o recurso indicado na resposta antes de repetir uma solicitação de criação, alteração, cancelamento ou devolução. Use `--debug` quando precisar investigar uma execução. Ele acrescenta eventos JSON em `stderr`, um por linha, preservando o resultado em `stdout`. Os eventos omitem argumentos livres e valores de credenciais. Antes de compartilhar um arquivo capturado, revise também os caminhos e nomes locais que possam identificar seu ambiente. Respostas da API podem conter dados da conta e segredos, como os retornados na criação ou rotação de um webhook. Proteja arquivos e logs que capturem `stdout`; a ocultação das credenciais no debug não remove dados da resposta solicitada. ## Inspecionar headers de resposta Use `--show-headers` nos comandos da API para incluir os headers públicos disponíveis na resposta: ```bash raims --profile sandbox --output json accounts fees --show-headers ``` No sucesso, o JSON acrescenta `response_headers`; na falha, acrescenta `error.response_headers`. Sem a opção, o formato padrão permanece igual. Com `--all`, cada página mantém seus próprios headers. A propriedade é omitida quando não há metadados permitidos. A seleção contém `Request-Id`, `X-Request-Id`, `Idempotency-Replayed`, `Retry-After` e `Raims-Rate-Limited-Reason`, quando presentes e válidos. Isso permite conferir um replay idempotente ou a espera informada pela API. Credenciais, cookies e outros headers não são apresentados. A opção não altera o resultado da requisição nem a política de retry. Erros em modo texto também apresentam o identificador da tentativa, os detalhes por campo, a espera e o motivo do limite, quando disponíveis. Os códigos de saída permanecem os mesmos. ## Controlar as cores do terminal No modo texto, o CLI usa cores na ajuda, nos campos JSON, nos status e nas mensagens de erro. `--color auto` é o padrão: cada saída usa cores quando está conectada a um terminal compatível e o ambiente permite. Para desativar as cores em uma execução: ```bash raims --color off doctor ``` `--color on` força cores na saída de texto, inclusive em arquivos e pipes. `on` e `off` prevalecem sobre as variáveis de ambiente. Em `auto`, `NO_COLOR` não vazio desativa cores; depois dele, `CLICOLOR_FORCE` não vazio e diferente de `0` força cores. Sem essas condições, `CLICOLOR=0`, CI ou `TERM=dumb` desativam as cores. O CLI avalia stdout e stderr separadamente. `--output json`, eventos JSONL de `--debug` e scripts de autocompletar sempre saem sem códigos ANSI, mesmo com `--color on`. As cores não alteram os valores, os status HTTP ou os códigos de saída. ## Enviar um corpo JSON Use `--data-file CAMINHO` nos comandos que recebem corpo. Prepare um arquivo UTF-8 com os campos descritos na referência da API. Por exemplo, para editar os textos de uma cobrança: ```json title="charge-update.json" { "title": "Pedido de integração", "description": null } ``` ```bash raims --profile sandbox --output json charges update CHARGE_ID --data-file charge-update.json ``` Substitua `CHARGE_ID` pelo ID de uma cobrança da empresa e do ambiente da chave. Nesse PATCH, `description: null` limpa a descrição, enquanto um campo omitido preserva seu valor. O CLI valida a entrada e envia o JSON sem converter inteiros nem trocar omissão por `null`. As regras de cada campo seguem o endpoint. O limite de corpo no CLI é 8 MiB. `--data-file -` lê o JSON de `stdin`, inclusive em CI e com `--no-input`. Essa opção recebe dados do pipeline e não abre uma pergunta no terminal. ## Usar flags para campos simples Os comandos com corpo oferecem flags para campos escalares de primeiro nível, derivadas dos nomes da API. Por exemplo, `tax_id` vira `--tax-id`: ```bash raims customers create --tax-id 12345678909 --full-name "Cliente de teste" --dry-run ``` Consulte `--help` para ver as flags de cada comando. Strings, inteiros, números e booleanos mantêm seus tipos; `0`, `false` e uma string vazia são enviados quando informados explicitamente. Uma flag omitida não envia o campo nem aplica o valor padrão exibido na ajuda. Use `--body-null CAMPO` para enviar `null` em um campo com flag que permita esse valor. Informe o nome JSON do campo; repita a opção para outros campos: ```bash raims charges update CHARGE_ID --title "Pedido revisado" --body-null description --dry-run ``` Não informe um valor e `--body-null` para o mesmo campo. Flags de corpo não podem ser combinadas com `--data-file`, mesmo quando ele lê stdin. Objetos sem opções próprias, listas de objetos e campos sem flag continuam sendo enviados pelo arquivo JSON ou por stdin. As validações e regras do endpoint permanecem as mesmas. ## Enviar listas por flags Repita a flag de uma lista para enviar seus itens na ordem informada. Por exemplo, para preparar o cadastro de um webhook com dois tipos de evento: ```bash raims webhooks create --name "Pedidos pagos" --url https://webhooks.example.com/raims --events charge.paid --events refund.completed --dry-run ``` O mesmo formato atende `--payment-method-types` em cobranças e links de pagamento e `--identifiers` na exclusão em lote de clientes. Cada ocorrência adiciona um item; vírgulas não separam valores. Os tipos, os valores aceitos, a quantidade de itens e a aceitação de duplicatas seguem o endpoint. Omitir a flag preserva a omissão do campo. Nas listas que aceitam `null`, use o nome JSON com `--body-null`, por exemplo `--body-null payment_method_types`. As listas desses comandos exigem pelo menos um item quando informadas; enviar `[]` por arquivo também é inválido. Não combine valores e `null` para a mesma lista, nem flags de corpo com `--data-file`. ## Enviar metadata por flags Na criação e atualização de clientes e cobranças, repita `--metadata CHAVE=VALOR` para associar informações do seu sistema ao recurso: ```bash raims customers update CUSTOMER_ID --metadata pedido=123 --metadata origem=site --dry-run ``` Substitua `CUSTOMER_ID` pelo ID do cliente. Os valores são sempre textos: `pedido=123` envia `"123"`, e `observacao=null` envia o texto `"null"`. O primeiro `=` separa a chave do valor; os seguintes fazem parte do texto. `--metadata observacao=` envia uma string vazia. Pontos nas chaves são literais, sem criar objetos aninhados. | Intenção | Opção | | ---------------------------------------------------- | ------------------------ | | Adicionar ou substituir uma chave | `--metadata chave=valor` | | Remover uma chave no PATCH | `--metadata-null chave` | | Enviar um mapa vazio, que preserva os dados no PATCH | `--metadata-empty` | | Limpar todo o mapa | `--body-null metadata` | Omitir essas opções preserva a omissão de `metadata`. Não repita uma chave nem combine um valor com `--metadata-null` para a mesma chave. As opções de mapa vazio e de limpeza não podem ser combinadas com valores ou remoções individuais. Flags de corpo continuam exclusivas com `--data-file`. O mapa aceita até 32 chaves, com 1 a 40 caracteres cada. Use letras sem acentos, números, ponto, hífen ou sublinhado. Os valores aceitam até 500 caracteres, e o conteúdo total do mapa tem limite de 8 KiB. Consulte os guias de [clientes](/br/api/customers/overview) e [cobranças](/br/api/charges/overview) para as regras do recurso. ## Enviar logo e favicon Use `--upload-file CAMINHO` nos comandos de preparação de logo ou favicon para obter os metadados da imagem e enviar seu conteúdo: ```bash raims --profile sandbox accounts checkout-settings logo-uploads create --upload-file logo.png raims --profile sandbox accounts checkout-settings favicon-uploads create --upload-file favicon.png ``` O arquivo deve ser PNG ou JPEG, com até 512 KiB. O logo aceita de 128 a 2048 pixels em cada dimensão. O favicon deve ser quadrado, com lados de 128 a 512 pixels. O CLI lê um arquivo local; essa opção não recebe stdin. Não combine `--upload-file` com `--data-file` ou flags dos campos do corpo: tipo, tamanho e dimensões vêm do próprio arquivo. Para conferir a imagem e os metadados antes de preparar o envio: ```bash raims accounts checkout-settings logo-uploads create --upload-file logo.png --dry-run ``` A prévia lê e valida a imagem sem usar perfil, chave ou rede. A execução real prepara o envio na API e faz o PUT dos bytes pela URL temporária, sem enviar a chave da Raims a esse destino. O prazo retornado em `expires_at` limita o envio; `--timeout` também vale para cada requisição. Não há repetição automática. O resultado preserva os dados da API em `data` e acrescenta `upload.bytes` quando o arquivo é enviado. Para mudar a imagem do checkout, use o `data.id` retornado na flag `--logo-upload-id` ou `--favicon-upload-id` de `raims accounts checkout-settings update`. Consulte o resultado com `raims accounts checkout-settings get`; a aplicação pode continuar pendente. Enviar o arquivo sozinho não altera a aparência. Se o envio dos bytes falhar, a imagem não será aplicada. Prepare um novo envio antes de tentar novamente. Sem `--upload-file`, os comandos continuam recebendo metadados JSON e retornando as instruções para você enviar o arquivo. ## Salvar boletos e comprovantes Acrescente `--save CAMINHO` para salvar o PDF retornado pela consulta de boleto, comprovante de pagamento ou comprovante de estorno: ```bash raims --profile sandbox charges boleto CHARGE_ID --save boleto.pdf raims --profile sandbox charges receipt CHARGE_ID --save pagamento.pdf raims --profile sandbox refunds receipt REFUND_ID --save estorno.pdf ``` O diretório de destino deve existir. O CLI não sobrescreve um arquivo existente e só disponibiliza o destino depois de receber o arquivo inteiro e conferir seu formato. Sem `--save`, o comando continua retornando os dados e a URL temporária do documento. Com a opção, o resultado acrescenta `download`, com `path` e `bytes`. O limite é 32 MiB. `--timeout` também limita a requisição de download. `--save` não pode ser combinado com `--dry-run`. Salvar um boleto não confirma seu pagamento; os documentos de Sandbox continuam identificando uma simulação. ## Conferir uma requisição sem enviar Acrescente `--dry-run` a um comando da API para validar e apresentar a requisição sem enviá-la: ```bash raims --no-input --output json customers list --page-size 20 --dry-run ``` A prévia não lê a configuração, o perfil ou a chave, não consulta a API e não ativa atualizações. O resultado JSON informa `dry_run`, `method`, `url`, `headers` e, quando houver, `body`. `Authorization` não aparece na saída. Em comandos com corpo, informe um arquivo ou as flags de campos aceitas pelo comando. A entrada passa pela mesma validação de campos e tipos. A prévia pode conter dados pessoais ou financeiros informados no corpo; proteja a saída como protegeria o arquivo original. Não combine `--dry-run` com `--all`, pois as páginas seguintes dependem dos cursores retornados pela API. ## Percorrer páginas Por padrão, uma listagem consulta uma página. Use `--page-size` para informar o tamanho e consulte `--help` para os filtros daquele comando. Flags de consulta usam hífen, como `--page-size`, preservando os nomes JSON da API nas respostas. Para percorrer as páginas seguintes: ```bash raims --no-input --profile sandbox --output json customers list --all --max-pages 100 ``` Com `--all --output json`, `stdout` usa JSON Lines: cada linha é um objeto com `status_code`, `request_id` e `data`, que contém `list` e `page` daquela página. A saída não é um único array. O CLI preserva filtros, ordenação e tamanho da página e avança pelos cursores retornados pela API. `--max-pages` exige `--all`, aceita de 1 a 10.000 e usa 100 por padrão. Se o limite for atingido com resultados restantes, o comando termina com `API_PAGE_LIMIT_REACHED`. Para continuar, copie `data.page.next_after` da última página para `--after`, preservando os filtros. Copie o cursor inteiro, sem calcular ou interpretar seu conteúdo. Não combine `--after` e `--before`. Uma consulta iniciada com `--before` percorre o sentido inverso e continua por `data.page.previous_before`. Uma falha de rede, cancelamento ou limite pode ocorrer depois de páginas emitidas. Confira o código de saída e trate os resultados anteriores como parciais quando o percurso terminar com erro. ## Tratar falhas Confira o código de saída do processo antes de interpretar o resultado: | Código de saída | Significado | | --------------- | --------------------------------------------------------------------- | | `0` | Comando concluído. | | `1` | Falha interna. | | `2` | Argumento, opção ou uso inválido. | | `3` | Falha de configuração, diagnóstico com erro ou versão fixada ausente. | | `4` | Falha de autenticação ou autorização. | | `5` | Falha de rede ou timeout. | | `6` | Erro retornado pela API ou na resposta recebida. | | `130` | Execução cancelada. | Com `--output json`, uma falha gera um objeto em `stderr`, em uma única linha: ```json { "error": { "code": "PROFILE_NOT_FOUND", "message": "The selected profile does not exist. Run 'raims profile list'.", "kind": "config" }, "exit_code": 3 } ``` Use `error.code` e o código de saída para decidir a ação da automação. `error.message` serve ao diagnóstico humano e seu texto pode melhorar. Quando disponíveis, `error.status_code` e `error.request_id` identificam o status HTTP e a requisição. Validações podem incluir `error.details`, com `field`, `code` e `message`. Limites podem incluir `error.retry_after_seconds` e `error.rate_limit_reason`. Use os códigos e os campos para decidir a ação, preservando a espera informada antes de tentar outra vez. Com `--output json` e `--debug` juntos, cada linha de `stderr` é um objeto JSON separado. No modo texto, os eventos de debug continuam em JSON por linha, e a mensagem de erro segue o formato de texto. Falhas antes do primeiro resultado deixam `stdout` vazio. `doctor` pode apresentar o relatório e terminar com `3`; listagens com `--all` podem ter emitido páginas antes do erro. `--timeout` usa 60 segundos por requisição, incluindo tentativas e esperas; por exemplo, `--timeout 30s` reduz esse prazo. Com `--all`, o prazo vale para cada página. Leituras podem repetir falhas transitórias até três tentativas, respeitando o prazo e `Retry-After`. Escritas não são repetidas automaticamente. Um timeout ou cancelamento local não desfaz uma requisição aceita pela API; consulte o recurso antes de enviar outra escrita. ## Controlar a versão Na etapa de instalação do pipeline, obtenha a versão atual pelo npm: ```bash npm install -g @raimshq/cli@latest raims --no-input --output json version ``` Execute a instalação com `@latest` em cada execução que deva usar a versão atual publicada. O comando `version` informa qual versão será usada. Uma instalação já concluída permanece na mesma versão até você atualizar pelo gerenciador; a tag não ativa atualizações automáticas futuras. Em CI, a atualização fica a cargo dessa etapa de instalação. Se `RAIMS_CLI_PIN_VERSION` estiver definido, ele exige a versão indicada já instalada ou conservada pelo CLI e pode impedir o uso de uma atualização. Para acompanhar a versão atual, remova essa fixação da configuração da automação. A variável não baixa versões. ### Selecionar uma versão disponível na instalação direta O instalador direto `0.1.2` consulta o patch estável mais recente da linha `0.1`; seu nome não fixa a versão instalada. Os exemplos de instalação por npm também usam `@latest` para resolver a versão atual. A atualização automática exige uma instalação direta com pacote assinado e canal de distribuição configurado. Consulte `raims update status` para conferir a política da sua instalação. Ambientes de CI desativam consultas e ativações automáticas. Para exigir a versão selecionada na sua instalação direta, derive `RAIMS_CLI_PIN_VERSION` da versão executada. Os exemplos usam o destino padrão; ajuste o caminho se instalou em outra pasta: ### PowerShell ```powershell $cliExecutable = "$env:LOCALAPPDATA\Raims\CLI\raims.exe" $cliBuild = & $cliExecutable --no-input --output json version | ConvertFrom-Json if ($LASTEXITCODE -eq 0 -and $cliBuild.version) { $env:RAIMS_CLI_PIN_VERSION = $cliBuild.version & $cliExecutable --no-input --output json version } ``` ### Bash e Zsh ```bash cli_executable="$HOME/.local/share/raims/cli/raims" installed_version="$("$cli_executable" --no-input --color off version | awk 'NR == 1 { print $2; exit }')" test -n "$installed_version" && export RAIMS_CLI_PIN_VERSION="$installed_version" && "$cli_executable" --no-input --output json version ``` O pin exige uma versão já instalada ou conservada pelo CLI; ele não baixa outra versão. Se ela não estiver disponível, a execução termina com erro. Definir o pin não instala uma versão nem transforma `@latest` em uma instalação fixada para execuções futuras. A fixação vale para comandos como `version` e os de perfis. Para investigar uma versão fixada ausente, `doctor`, `update status`, ajuda, autocompletar, `open` e prévias com `--dry-run` continuam acessíveis. Esses comandos de inspeção preservam a versão instalada, sem consultar, baixar ou ativar atualizações. `raims licenses` também permanece acessível quando a versão fixada está ausente. Ele lê somente os textos incluídos no executável em uso. `RAIMS_CLI_NO_UPDATE=1` desativa a consulta e a ativação de atualizações pendentes, preservando a versão já ativa. Instalações mantidas por um gerenciador de pacotes seguem o mecanismo de atualização desse gerenciador. Consulte a política da instalação com: ```bash raims --output json update status ``` Na [instalação direta](/br/cli/direct-installation), uma atualização pode ser baixada silenciosamente durante o uso e ativada na próxima execução elegível. O comando em andamento mantém sua versão. Preserve as versões em cache, a instalação original e os backups; não há limpeza automática desse histórico. # raims accounts (/br/cli/commands/accounts) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims accounts` Consulte os dados da conta e configure a aparência do checkout. ```bash raims accounts [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de accounts. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims accounts account-number`](#raims-accounts-account-number), [`raims accounts checkout-settings`](#raims-accounts-checkout-settings), [`raims accounts context`](#raims-accounts-context), [`raims accounts fees`](#raims-accounts-fees). ### `raims accounts account-number` Consulte o número da conta. ```bash raims accounts account-number [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de account-number. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get the account number. GET /v1/accounts/account_number Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json accounts account-number --dry-run ``` ### `raims accounts checkout-settings` Gerencie a aparência do checkout e os uploads de imagem preparados. ```bash raims accounts checkout-settings [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de checkout-settings. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims accounts checkout-settings favicon-uploads`](#raims-accounts-checkout-settings-favicon-uploads), [`raims accounts checkout-settings get`](#raims-accounts-checkout-settings-get), [`raims accounts checkout-settings logo-uploads`](#raims-accounts-checkout-settings-logo-uploads), [`raims accounts checkout-settings update`](#raims-accounts-checkout-settings-update), [`raims accounts checkout-settings uploads`](#raims-accounts-checkout-settings-uploads). #### `raims accounts checkout-settings favicon-uploads` Prepare uploads de favicon para o checkout. ```bash raims accounts checkout-settings favicon-uploads [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de favicon-uploads. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims accounts checkout-settings favicon-uploads create`](#raims-accounts-checkout-settings-favicon-uploads-create). ##### `raims accounts checkout-settings favicon-uploads create` Prepare o upload de um favicon para o checkout. ```bash raims accounts checkout-settings favicon-uploads create [flags] ``` * `--content-type` string padrão: vazio * Defina content\_type no corpo JSON: texto obrigatório. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--file-size` integer padrão: 0 * Defina file\_size no corpo JSON: inteiro obrigatório. * `--height` integer padrão: 0 * Defina height no corpo JSON: inteiro obrigatório. * `--help`, `-h` bool padrão: false * Exibe a ajuda de create. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. * `--upload-file` string padrão: vazio * Prepare o envio de um PNG ou JPEG local e envie seus bytes; não combine com opções do corpo JSON. A imagem não é aplicada ao checkout por este comando. * `--width` integer padrão: 0 * Defina width no corpo JSON: inteiro obrigatório. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Prepare a checkout favicon upload. POST /v1/accounts/checkout_settings/favicon_uploads Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: content_type string required; allowed: "image/png", "image/jpeg" file_size integer required height integer required width integer required Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "content_type": "image/png", "file_size": 4567, "width": 128, "height": 128 } Example values are illustrative. Replace resource IDs and review the request before sending it. Without --upload-file, this operation prepares an upload using JSON metadata and returns the API's upload instructions. Use --upload-file PATH to read a PNG or JPEG, prepare its metadata and upload its bytes. Do not combine it with --data-file or body options. With --dry-run, the file is validated locally and only the metadata request is previewed. Uploading does not apply the image: update checkout settings with the returned upload ID in a separate request. With --upload-file, image metadata is read from the same bytes that are uploaded. The file must be PNG or JPEG, up to 524288 bytes, with width 128..512 pixels and height 128..512 pixels. The favicon must be square. --dry-run validates the local file and previews only the preparation request; it does not upload bytes. Apply the returned upload ID separately to change the checkout image. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json accounts checkout-settings favicon-uploads create --data-file request.json --dry-run raims accounts checkout-settings favicon-uploads create --content-type="image/png" --file-size=4567 --height=128 --width=128 --dry-run raims accounts checkout-settings favicon-uploads create --upload-file image.png --dry-run ``` #### `raims accounts checkout-settings get` Consulte as configurações de aparência do checkout. ```bash raims accounts checkout-settings get [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de get. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get checkout appearance settings. GET /v1/accounts/checkout_settings Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json accounts checkout-settings get --dry-run ``` #### `raims accounts checkout-settings logo-uploads` Prepare uploads de logo para o checkout. ```bash raims accounts checkout-settings logo-uploads [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de logo-uploads. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims accounts checkout-settings logo-uploads create`](#raims-accounts-checkout-settings-logo-uploads-create). ##### `raims accounts checkout-settings logo-uploads create` Prepare o upload de uma logo para o checkout. ```bash raims accounts checkout-settings logo-uploads create [flags] ``` * `--content-type` string padrão: vazio * Defina content\_type no corpo JSON: texto obrigatório. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--file-size` integer padrão: 0 * Defina file\_size no corpo JSON: inteiro obrigatório. * `--height` integer padrão: 0 * Defina height no corpo JSON: inteiro obrigatório. * `--help`, `-h` bool padrão: false * Exibe a ajuda de create. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. * `--upload-file` string padrão: vazio * Prepare o envio de um PNG ou JPEG local e envie seus bytes; não combine com opções do corpo JSON. A imagem não é aplicada ao checkout por este comando. * `--width` integer padrão: 0 * Defina width no corpo JSON: inteiro obrigatório. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Prepare a checkout logo upload. POST /v1/accounts/checkout_settings/logo_uploads Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: content_type string required; allowed: "image/png", "image/jpeg" file_size integer required height integer required width integer required Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "content_type": "image/png", "file_size": 12345, "width": 512, "height": 128 } Example values are illustrative. Replace resource IDs and review the request before sending it. Without --upload-file, this operation prepares an upload using JSON metadata and returns the API's upload instructions. Use --upload-file PATH to read a PNG or JPEG, prepare its metadata and upload its bytes. Do not combine it with --data-file or body options. With --dry-run, the file is validated locally and only the metadata request is previewed. Uploading does not apply the image: update checkout settings with the returned upload ID in a separate request. With --upload-file, image metadata is read from the same bytes that are uploaded. The file must be PNG or JPEG, up to 524288 bytes, with width 128..2048 pixels and height 128..2048 pixels. --dry-run validates the local file and previews only the preparation request; it does not upload bytes. Apply the returned upload ID separately to change the checkout image. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json accounts checkout-settings logo-uploads create --data-file request.json --dry-run raims accounts checkout-settings logo-uploads create --content-type="image/png" --file-size=12345 --height=128 --width=512 --dry-run raims accounts checkout-settings logo-uploads create --upload-file image.png --dry-run ``` #### `raims accounts checkout-settings update` Atualize as configurações de aparência do checkout. ```bash raims accounts checkout-settings update [flags] ``` * `--body-null` stringArray padrão: [] * Envie null em um campo do corpo que aceite esse valor, usando o nome JSON; repita para outros campos e não combine com --data-file. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--favicon-upload-id` string padrão: vazio * Defina favicon\_upload\_id no corpo JSON: texto que aceita null. * `--help`, `-h` bool padrão: false * Exibe a ajuda de update. * `--hex-primary-color` string padrão: vazio * Defina hex\_primary\_color no corpo JSON: texto. * `--hex-secondary-color` string padrão: vazio * Defina hex\_secondary\_color no corpo JSON: texto. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--logo-upload-id` string padrão: vazio * Defina logo\_upload\_id no corpo JSON: texto que aceita null. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--support-email` string padrão: vazio * Defina support\_email no corpo JSON: texto que aceita null. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Update checkout appearance settings. PATCH /v1/accounts/checkout_settings Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: favicon_upload_id string optional, nullable hex_primary_color string optional hex_secondary_color string optional logo_upload_id string optional, nullable support_email string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "logo_upload_id": "cau_3AbHiWSrsZBoaTg47OcMzC", "favicon_upload_id": "cau_1AbXiWSrsCBoaTg47OcMzC" } Example values are illustrative. Replace resource IDs and review the request before sending it. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json accounts checkout-settings update --data-file request.json --dry-run raims accounts checkout-settings update --favicon-upload-id="cau_1AbXiWSrsCBoaTg47OcMzC" --dry-run ``` #### `raims accounts checkout-settings uploads` Gerencie os uploads de imagem preparados para o checkout. ```bash raims accounts checkout-settings uploads [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de uploads. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims accounts checkout-settings uploads delete`](#raims-accounts-checkout-settings-uploads-delete). ##### `raims accounts checkout-settings uploads delete` Descarte um upload de imagem preparado para o checkout. ```bash raims accounts checkout-settings uploads delete ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de delete. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Discard a prepared checkout image upload. DELETE /v1/accounts/checkout_settings/uploads/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json accounts checkout-settings uploads delete ID --dry-run ``` ### `raims accounts context` Consulte o contexto da conta autenticada. ```bash raims accounts context [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Ajuda para context. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get the authenticated account context. GET /v1/accounts/context Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json accounts context --dry-run ``` ### `raims accounts fees` Consulte as tarifas da conta. ```bash raims accounts fees [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de fees. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get account fees. GET /v1/accounts/fees Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json accounts fees --dry-run ``` # raims balances (/br/cli/commands/balances) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims balances` Consulte os saldos e os recebimentos previstos. ```bash raims balances [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de balances. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims balances forecast`](#raims-balances-forecast), [`raims balances get`](#raims-balances-get). ### `raims balances forecast` Consulte os recebimentos previstos para um período. ```bash raims balances forecast [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de forecast. * `--period` string padrão: today * Período da consulta: today, last\_7\_days, last\_15\_days ou last\_30\_days. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get expected receivables for a period. GET /v1/balances/forecast Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json balances forecast --dry-run ``` ### `raims balances get` Consulte o saldo atual. ```bash raims balances get [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de get. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get the current balance. GET /v1/balances Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json balances get --dry-run ``` # raims charges (/br/cli/commands/charges) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims charges` Gerencie as cobranças e seus dados de pagamento. ```bash raims charges [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de charges. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims charges boleto`](#raims-charges-boleto), [`raims charges create`](#raims-charges-create), [`raims charges get`](#raims-charges-get), [`raims charges list`](#raims-charges-list), [`raims charges payment`](#raims-charges-payment), [`raims charges receipt`](#raims-charges-receipt), [`raims charges refund-eligibility`](#raims-charges-refund-eligibility), [`raims charges refunds`](#raims-charges-refunds), [`raims charges revoke`](#raims-charges-revoke), [`raims charges statistics`](#raims-charges-statistics), [`raims charges update`](#raims-charges-update). ### `raims charges boleto` Consulte os dados para baixar o boleto. ```bash raims charges boleto ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de boleto. * `--save` string padrão: vazio * Salve o PDF no caminho informado, até 32 MiB; o diretório deve existir e o arquivo deve ser novo. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get the boleto download information. GET /v1/charges/{id}/boleto Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json charges boleto ID --dry-run ``` ### `raims charges create` Crie uma cobrança. ```bash raims charges create [flags] ``` * `--amount-cents` integer padrão: 0 * Defina amount\_cents no corpo JSON: inteiro obrigatório. * `--body-null` stringArray padrão: [] * Envie null em um campo do corpo que aceite esse valor, usando o nome JSON; repita para outros campos e não combine com --data-file. * `--cancel-redirect-url` string padrão: vazio * Defina cancel\_redirect\_url no corpo JSON: texto que aceita null. * `--create-checkout` bool padrão: false * Defina create\_checkout no corpo JSON: booleano. * `--customer-id` string padrão: vazio * Defina customer\_id no corpo JSON: texto obrigatório. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--description` string padrão: vazio * Defina description no corpo JSON: texto que aceita null. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--due-date` integer padrão: 0 * Defina due\_date no corpo JSON: inteiro obrigatório. * `--external-reference` string padrão: vazio * Defina external\_reference no corpo JSON: texto que aceita null. * `--help`, `-h` bool padrão: false * Exibe a ajuda de create. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--metadata` stringArray padrão: vazio * Defina um texto de metadata como CHAVE=VALOR; repita para outras chaves. Pontos nas chaves são literais. * `--metadata-empty` bool padrão: false * Envie metadata vazio; na atualização, as chaves existentes são preservadas. * `--metadata-null` stringArray padrão: [] * Envie null para uma chave de metadata; repita para outras chaves. Na atualização, a chave é removida. * `--payment-method` integer padrão: 0 * Defina payment\_method no corpo JSON: inteiro. * `--payment-method-types` integerArray padrão: vazio * Defina payment\_method\_types no corpo JSON: lista de inteiros que aceita null; repita a opção para cada item. * `--send-email` bool padrão: false * Defina send\_email no corpo JSON: booleano. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--success-redirect-url` string padrão: vazio * Defina success\_redirect\_url no corpo JSON: texto que aceita null. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. * `--title` string padrão: vazio * Defina title no corpo JSON: texto que aceita null. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Create a charge. POST /v1/charges Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: amount_cents integer required cancel_redirect_url string optional, nullable create_checkout boolean optional customer_id string required description string optional, nullable due_date integer required external_reference string optional, nullable metadata object optional, nullable payment_method integer optional; allowed: 0, 1, 2 payment_method_types array optional, nullable; allowed: 1, 2 send_email boolean optional success_redirect_url string optional, nullable title string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 0, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "send_email": false, "external_reference": "pedido_12345" } Example values are illustrative. Replace resource IDs and review the request before sending it. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. Metadata options send a text map: repeat --metadata KEY=VALUE for values, use --metadata-null KEY for a null value, or --metadata-empty for an empty object. Empty text, numeric-looking values and the text null remain strings. Omitted metadata and an empty object preserve existing keys when updating; null values remove individual keys, and --body-null metadata clears the entire map. Do not combine these options with --data-file, or use multiple values for the same key. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json charges create --data-file request.json --dry-run raims charges create --amount-cents=10000 --customer-id="cus_1Q2W3E4R5T6Y7U8I9O0P" --due-date=1893456000 --dry-run ``` ### `raims charges get` Consulte uma cobrança. ```bash raims charges get ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de get. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get a charge. GET /v1/charges/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json charges get ID --dry-run ``` ### `raims charges list` Liste as cobranças. ```bash raims charges list [flags] ``` * `--after` string padrão: vazio * Consulte após este cursor opaco. Não combine com --before. * `--all` bool padrão: false * Leia todas as páginas como resultados separados. Com --output json, a saída usa JSON Lines. * `--before` string padrão: vazio * Consulte antes deste cursor opaco. Não combine com --after. * `--created-gte` int64 padrão: 0 * Criado a partir desta data Unix, em segundos. * `--created-lte` int64 padrão: 0 * Criado até esta data Unix, em segundos. * `--customer-id` string padrão: vazio * Filtre pelo identificador do cliente. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--due-gte` int64 padrão: 0 * Vencimento a partir desta data Unix, em segundos. * `--due-lte` int64 padrão: 0 * Vencimento até esta data Unix, em segundos. * `--email` string padrão: vazio * Filtre pelo endereço de e-mail. * `--external-reference` string padrão: vazio * Filtre pela referência externa. * `--help`, `-h` bool padrão: false * Exibe a ajuda de list. * `--identifier` string padrão: vazio * Filtre pelo identificador público do recurso. * `--max-pages` int padrão: 100 * Limite de páginas com --all, entre 1 e 10000. * `--page-size` int64 padrão: 10 * Quantidade de resultados por página. A API ajusta o tamanho solicitado. * `--paid-gte` int64 padrão: 0 * Pago a partir desta data Unix, em segundos. * `--paid-lte` int64 padrão: 0 * Pago até esta data Unix, em segundos. * `--payment-method` string padrão: vazio * Filtre pelos códigos dos meios de pagamento, separados por vírgula. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--sort-key` string padrão: vazio * Ordene os resultados por este campo da API. * `--sort-order` string padrão: desc * Direção da ordenação: asc ou desc. * `--status` string padrão: vazio * Filtre pelos códigos de status das cobranças, separados por vírgula. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text List charges. GET /v1/charges Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json charges list --dry-run ``` ### `raims charges payment` Consulte os dados de pagamento de uma cobrança. ```bash raims charges payment ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de payment. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get payment details for a charge. GET /v1/charges/{id}/payment Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json charges payment ID --dry-run ``` ### `raims charges receipt` Consulte os dados para baixar o comprovante de pagamento. ```bash raims charges receipt ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de receipt. * `--save` string padrão: vazio * Salve o PDF no caminho informado, até 32 MiB; o diretório deve existir e o arquivo deve ser novo. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get the payment receipt download information. GET /v1/charges/{id}/receipt Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json charges receipt ID --dry-run ``` ### `raims charges refund-eligibility` Confira se uma cobrança pode ser estornada. ```bash raims charges refund-eligibility ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de refund-eligibility. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Check whether a charge can be refunded. GET /v1/charges/{id}/refund_eligibility Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json charges refund-eligibility ID --dry-run ``` ### `raims charges refunds` Consulte e solicite estornos de uma cobrança. ```bash raims charges refunds [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de refunds. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims charges refunds create`](#raims-charges-refunds-create), [`raims charges refunds list`](#raims-charges-refunds-list). #### `raims charges refunds create` Solicite um estorno de uma cobrança. ```bash raims charges refunds create ID [flags] ``` * `--amount-cents` integer padrão: 0 * Defina amount\_cents no corpo JSON: inteiro obrigatório. * `--body-null` stringArray padrão: [] * Envie null em um campo do corpo que aceite esse valor, usando o nome JSON; repita para outros campos e não combine com --data-file. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--description` string padrão: vazio * Defina description no corpo JSON: texto que aceita null. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de create. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Request a refund for a charge. POST /v1/charges/{id}/refunds Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: amount_cents integer required description string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "amount_cents": 2500, "description": "Devolução parcial do serviço" } Example values are illustrative. Replace resource IDs and review the request before sending it. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json charges refunds create ID --data-file request.json --dry-run raims charges refunds create ID --amount-cents=2500 --dry-run ``` #### `raims charges refunds list` Liste os estornos de uma cobrança. ```bash raims charges refunds list ID [flags] ``` * `--after` string padrão: vazio * Consulte após este cursor opaco. Não combine com --before. * `--all` bool padrão: false * Leia todas as páginas como resultados separados. Com --output json, a saída usa JSON Lines. * `--before` string padrão: vazio * Consulte antes deste cursor opaco. Não combine com --after. * `--created-gte` int64 padrão: 0 * Criado a partir desta data Unix, em segundos. * `--created-lte` int64 padrão: 0 * Criado até esta data Unix, em segundos. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de list. * `--max-pages` int padrão: 100 * Limite de páginas com --all, entre 1 e 10000. * `--page-size` int64 padrão: 10 * Quantidade de resultados por página. A API ajusta o tamanho solicitado. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text List refunds for a charge. GET /v1/charges/{id}/refunds Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json charges refunds list ID --dry-run ``` ### `raims charges revoke` Revogue uma cobrança. ```bash raims charges revoke ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de revoke. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Revoke a charge. DELETE /v1/charges/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json charges revoke ID --dry-run ``` ### `raims charges statistics` Consulte as estatísticas de cobranças de um período. ```bash raims charges statistics [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de statistics. * `--period` string padrão: today * Período da consulta: today, last\_7\_days, last\_15\_days ou last\_30\_days. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get charge statistics for a period. GET /v1/charges/statistics Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json charges statistics --dry-run ``` ### `raims charges update` Atualize uma cobrança. ```bash raims charges update ID [flags] ``` * `--body-null` stringArray padrão: [] * Envie null em um campo do corpo que aceite esse valor, usando o nome JSON; repita para outros campos e não combine com --data-file. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--description` string padrão: vazio * Defina description no corpo JSON: texto que aceita null. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--external-reference` string padrão: vazio * Defina external\_reference no corpo JSON: texto que aceita null. * `--help`, `-h` bool padrão: false * Exibe a ajuda de update. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--metadata` stringArray padrão: vazio * Defina um texto de metadata como CHAVE=VALOR; repita para outras chaves. Pontos nas chaves são literais. * `--metadata-empty` bool padrão: false * Envie metadata vazio; na atualização, as chaves existentes são preservadas. * `--metadata-null` stringArray padrão: [] * Envie null para uma chave de metadata; repita para outras chaves. Na atualização, a chave é removida. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. * `--title` string padrão: vazio * Defina title no corpo JSON: texto que aceita null. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Update a charge. PATCH /v1/charges/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: description string optional, nullable external_reference string optional, nullable metadata object optional, nullable title string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "title": "Serviço atualizado", "description": "Descrição atualizada da cobrança", "external_reference": "pedido_12345_atualizado" } Example values are illustrative. Replace resource IDs and review the request before sending it. Metadata options send a text map: repeat --metadata KEY=VALUE for values, use --metadata-null KEY for a null value, or --metadata-empty for an empty object. Empty text, numeric-looking values and the text null remain strings. Omitted metadata and an empty object preserve existing keys when updating; null values remove individual keys, and --body-null metadata clears the entire map. Do not combine these options with --data-file, or use multiple values for the same key. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json charges update ID --data-file request.json --dry-run raims charges update ID --description="Descrição atualizada da cobrança" --dry-run ``` # raims customers (/br/cli/commands/customers) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims customers` Gerencie os clientes. ```bash raims customers [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de customers. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims customers create`](#raims-customers-create), [`raims customers delete`](#raims-customers-delete), [`raims customers delete-batch`](#raims-customers-delete-batch), [`raims customers get`](#raims-customers-get), [`raims customers list`](#raims-customers-list), [`raims customers update`](#raims-customers-update). ### `raims customers create` Cadastre ou atualize um cliente pelo CPF ou CNPJ. ```bash raims customers create [flags] ``` * `--body-null` stringArray padrão: [] * Envie null em um campo do corpo que aceite esse valor, usando o nome JSON; repita para outros campos e não combine com --data-file. * `--city` string padrão: vazio * Defina city no corpo JSON: texto que aceita null. * `--complement` string padrão: vazio * Defina complement no corpo JSON: texto que aceita null. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dial-code` string padrão: vazio * Defina dial\_code no corpo JSON: texto que aceita null. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--email` string padrão: vazio * Defina email no corpo JSON: texto que aceita null. * `--external-reference` string padrão: vazio * Defina external\_reference no corpo JSON: texto que aceita null. * `--full-name` string padrão: vazio * Defina full\_name no corpo JSON: texto que aceita null. * `--help`, `-h` bool padrão: false * Exibe a ajuda de create. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--metadata` stringArray padrão: vazio * Defina um texto de metadata como CHAVE=VALOR; repita para outras chaves. Pontos nas chaves são literais. * `--metadata-empty` bool padrão: false * Envie metadata vazio; na atualização, as chaves existentes são preservadas. * `--metadata-null` stringArray padrão: [] * Envie null para uma chave de metadata; repita para outras chaves. Na atualização, a chave é removida. * `--neigh` string padrão: vazio * Defina neigh no corpo JSON: texto que aceita null. * `--phone-local` string padrão: vazio * Defina phone\_local no corpo JSON: texto que aceita null. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--street` string padrão: vazio * Defina street no corpo JSON: texto que aceita null. * `--street-number` string padrão: vazio * Defina street\_number no corpo JSON: texto que aceita null. * `--tax-id` string padrão: vazio * Defina tax\_id no corpo JSON: texto obrigatório. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. * `--uf` string padrão: vazio * Defina uf no corpo JSON: texto que aceita null. * `--zip-code` string padrão: vazio * Defina zip\_code no corpo JSON: texto que aceita null. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Create or update a customer by tax ID. POST /v1/customers Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: city string optional, nullable complement string optional, nullable dial_code string optional, nullable email string optional, nullable external_reference string optional, nullable full_name string optional, nullable metadata object optional, nullable neigh string optional, nullable phone_local string optional, nullable street string optional, nullable street_number string optional, nullable tax_id string required uf string optional, nullable zip_code string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "full_name": "Cliente de teste", "tax_id": "12345678909", "email": "cliente@example.invalid", "dial_code": "55", "phone_local": "11987654321", "zip_code": "01310000", "street": "Avenida de exemplo", "street_number": "100", "complement": "Sala 1", "neigh": "Centro", "city": "São Paulo", "uf": "SP" } Example values are illustrative. Replace resource IDs and review the request before sending it. Metadata options send a text map: repeat --metadata KEY=VALUE for values, use --metadata-null KEY for a null value, or --metadata-empty for an empty object. Empty text, numeric-looking values and the text null remain strings. Omitted metadata and an empty object preserve existing keys when updating; null values remove individual keys, and --body-null metadata clears the entire map. Do not combine these options with --data-file, or use multiple values for the same key. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json customers create --data-file request.json --dry-run raims customers create --tax-id="12345678909" --dry-run ``` ### `raims customers delete` Exclua um cliente. ```bash raims customers delete ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de delete. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Delete a customer. DELETE /v1/customers/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json customers delete ID --dry-run ``` ### `raims customers delete-batch` Exclua os clientes informados no corpo da requisição. ```bash raims customers delete-batch [flags] ``` * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de delete-batch. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--identifiers` stringArray padrão: vazio * Defina identifiers no corpo JSON: lista obrigatória de textos; repita a opção para cada item. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Delete the customers listed in the request body. DELETE /v1/customers Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: identifiers array required Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "identifiers": [ "cus_3AbHiWSrsZBoaTg47OcMzC", "cus_1szWVIyZES2MJoAMUmjwW" ] } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json customers delete-batch --data-file request.json --dry-run raims customers delete-batch --identifiers="cus_3AbHiWSrsZBoaTg47OcMzC" --identifiers="cus_1szWVIyZES2MJoAMUmjwW" --dry-run ``` ### `raims customers get` Consulte um cliente. ```bash raims customers get ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de get. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get a customer. GET /v1/customers/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json customers get ID --dry-run ``` ### `raims customers list` Liste os clientes. ```bash raims customers list [flags] ``` * `--after` string padrão: vazio * Consulte após este cursor opaco. Não combine com --before. * `--all` bool padrão: false * Leia todas as páginas como resultados separados. Com --output json, a saída usa JSON Lines. * `--before` string padrão: vazio * Consulte antes deste cursor opaco. Não combine com --after. * `--document` string padrão: vazio * Filtre pelo CPF ou CNPJ do cliente. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--email` string padrão: vazio * Filtre pelo endereço de e-mail. * `--external-reference` string padrão: vazio * Filtre pela referência externa. * `--help`, `-h` bool padrão: false * Exibe a ajuda de list. * `--identifier` string padrão: vazio * Filtre pelo identificador público do recurso. * `--max-pages` int padrão: 100 * Limite de páginas com --all, entre 1 e 10000. * `--name` string padrão: vazio * Filtre pelo nome do cliente. * `--page-size` int64 padrão: 10 * Quantidade de resultados por página. A API ajusta o tamanho solicitado. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text List customers. GET /v1/customers Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json customers list --dry-run ``` ### `raims customers update` Atualize um cliente. ```bash raims customers update ID [flags] ``` * `--body-null` stringArray padrão: [] * Envie null em um campo do corpo que aceite esse valor, usando o nome JSON; repita para outros campos e não combine com --data-file. * `--city` string padrão: vazio * Defina city no corpo JSON: texto que aceita null. * `--complement` string padrão: vazio * Defina complement no corpo JSON: texto que aceita null. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dial-code` string padrão: vazio * Defina dial\_code no corpo JSON: texto que aceita null. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--email` string padrão: vazio * Defina email no corpo JSON: texto que aceita null. * `--external-reference` string padrão: vazio * Defina external\_reference no corpo JSON: texto que aceita null. * `--full-name` string padrão: vazio * Defina full\_name no corpo JSON: texto que aceita null. * `--help`, `-h` bool padrão: false * Exibe a ajuda de update. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--metadata` stringArray padrão: vazio * Defina um texto de metadata como CHAVE=VALOR; repita para outras chaves. Pontos nas chaves são literais. * `--metadata-empty` bool padrão: false * Envie metadata vazio; na atualização, as chaves existentes são preservadas. * `--metadata-null` stringArray padrão: [] * Envie null para uma chave de metadata; repita para outras chaves. Na atualização, a chave é removida. * `--neigh` string padrão: vazio * Defina neigh no corpo JSON: texto que aceita null. * `--phone-local` string padrão: vazio * Defina phone\_local no corpo JSON: texto que aceita null. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--street` string padrão: vazio * Defina street no corpo JSON: texto que aceita null. * `--street-number` string padrão: vazio * Defina street\_number no corpo JSON: texto que aceita null. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. * `--uf` string padrão: vazio * Defina uf no corpo JSON: texto que aceita null. * `--zip-code` string padrão: vazio * Defina zip\_code no corpo JSON: texto que aceita null. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Update a customer. PATCH /v1/customers/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: city string optional, nullable complement string optional, nullable dial_code string optional, nullable email string optional, nullable external_reference string optional, nullable full_name string optional, nullable metadata object optional, nullable neigh string optional, nullable phone_local string optional, nullable street string optional, nullable street_number string optional, nullable uf string optional, nullable zip_code string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "full_name": "Cliente atualizado", "email": "atualizado@example.invalid" } Example values are illustrative. Replace resource IDs and review the request before sending it. Metadata options send a text map: repeat --metadata KEY=VALUE for values, use --metadata-null KEY for a null value, or --metadata-empty for an empty object. Empty text, numeric-looking values and the text null remain strings. Omitted metadata and an empty object preserve existing keys when updating; null values remove individual keys, and --body-null metadata clears the entire map. Do not combine these options with --data-file, or use multiple values for the same key. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json customers update ID --data-file request.json --dry-run raims customers update ID --email="atualizado@example.invalid" --dry-run ``` # raims disputes (/br/cli/commands/disputes) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims disputes` Consulte as contestações. ```bash raims disputes [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de disputes. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims disputes get`](#raims-disputes-get), [`raims disputes list`](#raims-disputes-list). ### `raims disputes get` Consulte uma contestação. ```bash raims disputes get ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de get. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get a dispute. GET /v1/disputes/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json disputes get ID --dry-run ``` ### `raims disputes list` Liste as contestações. ```bash raims disputes list [flags] ``` * `--after` string padrão: vazio * Consulte após este cursor opaco. Não combine com --before. * `--all` bool padrão: false * Leia todas as páginas como resultados separados. Com --output json, a saída usa JSON Lines. * `--before` string padrão: vazio * Consulte antes deste cursor opaco. Não combine com --after. * `--charge-id` string padrão: vazio * Filtre pelo identificador da cobrança. * `--created-gte` int64 padrão: 0 * Criado a partir desta data Unix, em segundos. * `--created-lte` int64 padrão: 0 * Criado até esta data Unix, em segundos. * `--disputed-amount-cents` int64 padrão: 0 * Filtre pelo valor contestado, em centavos. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de list. * `--max-pages` int padrão: 100 * Limite de páginas com --all, entre 1 e 10000. * `--page-size` int64 padrão: 10 * Quantidade de resultados por página. A API ajusta o tamanho solicitado. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--sort-key` string padrão: created_at * Ordene os resultados por este campo da API. * `--sort-order` string padrão: desc * Direção da ordenação: asc ou desc. * `--stage` string padrão: vazio * Filtre pelas etapas das contestações, separadas por vírgula. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text List disputes. GET /v1/disputes Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json disputes list --dry-run ``` # raims payment-links (/br/cli/commands/payment-links) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims payment-links` Gerencie os links de pagamento. ```bash raims payment-links [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de payment-links. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims payment-links create`](#raims-payment-links-create), [`raims payment-links get`](#raims-payment-links-get), [`raims payment-links list`](#raims-payment-links-list), [`raims payment-links send-email`](#raims-payment-links-send-email), [`raims payment-links update`](#raims-payment-links-update). ### `raims payment-links create` Crie ou consulte um link de pagamento. ```bash raims payment-links create [flags] ``` * `--body-null` stringArray padrão: [] * Envie null em um campo do corpo que aceite esse valor, usando o nome JSON; repita para outros campos e não combine com --data-file. * `--cancel-redirect-url` string padrão: vazio * Defina cancel\_redirect\_url no corpo JSON: texto que aceita null. * `--charge-id` string padrão: vazio * Defina charge\_id no corpo JSON: texto obrigatório. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de create. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--payment-method-types` integerArray padrão: vazio * Defina payment\_method\_types no corpo JSON: lista de inteiros que aceita null; repita a opção para cada item. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--success-redirect-url` string padrão: vazio * Defina success\_redirect\_url no corpo JSON: texto que aceita null. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Create or retrieve a payment link. POST /v1/payment_links Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: cancel_redirect_url string optional, nullable charge_id string required payment_method_types array optional, nullable; allowed: 1, 2 success_redirect_url string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "success_redirect_url": "https://loja.example.com/pedido/concluido", "cancel_redirect_url": "https://loja.example.com/pedido", "payment_method_types": [ 1 ] } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json payment-links create --data-file request.json --dry-run raims payment-links create --charge-id="ch_4CnJiWSrsZBoaTg47OcMzD" --dry-run ``` ### `raims payment-links get` Consulte um link de pagamento. ```bash raims payment-links get ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de get. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get a payment link. GET /v1/payment_links/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json payment-links get ID --dry-run ``` ### `raims payment-links list` Liste os links de pagamento. ```bash raims payment-links list [flags] ``` * `--after` string padrão: vazio * Consulte após este cursor opaco. Não combine com --before. * `--all` bool padrão: false * Leia todas as páginas como resultados separados. Com --output json, a saída usa JSON Lines. * `--before` string padrão: vazio * Consulte antes deste cursor opaco. Não combine com --after. * `--charge-id` string padrão: vazio * Filtre pelo identificador da cobrança. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de list. * `--max-pages` int padrão: 100 * Limite de páginas com --all, entre 1 e 10000. * `--page-size` int64 padrão: 10 * Quantidade de resultados por página. A API ajusta o tamanho solicitado. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text List payment links. GET /v1/payment_links Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json payment-links list --dry-run ``` ### `raims payment-links send-email` Solicite o envio de um link de pagamento por e-mail. ```bash raims payment-links send-email ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de send-email. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Request delivery of a payment link by email. POST /v1/payment_links/{id}/send_email Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json payment-links send-email ID --dry-run ``` ### `raims payment-links update` Atualize um link de pagamento. ```bash raims payment-links update ID [flags] ``` * `--body-null` stringArray padrão: [] * Envie null em um campo do corpo que aceite esse valor, usando o nome JSON; repita para outros campos e não combine com --data-file. * `--cancel-redirect-url` string padrão: vazio * Defina cancel\_redirect\_url no corpo JSON: texto que aceita null. * `--clear-cancel-redirect-url` bool padrão: false * Defina clear\_cancel\_redirect\_url no corpo JSON: booleano. * `--clear-success-redirect-url` bool padrão: false * Defina clear\_success\_redirect\_url no corpo JSON: booleano. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de update. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--is-active` bool padrão: false * Defina is\_active no corpo JSON: booleano. * `--payment-method-types` integerArray padrão: vazio * Defina payment\_method\_types no corpo JSON: lista de inteiros que aceita null; repita a opção para cada item. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--success-redirect-url` string padrão: vazio * Defina success\_redirect\_url no corpo JSON: texto que aceita null. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Update a payment link. PATCH /v1/payment_links/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: cancel_redirect_url string optional, nullable clear_cancel_redirect_url boolean optional clear_success_redirect_url boolean optional is_active boolean optional payment_method_types array optional, nullable; allowed: 1, 2 success_redirect_url string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "clear_success_redirect_url": true, "cancel_redirect_url": "https://loja.example.com/pedido" } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json payment-links update ID --data-file request.json --dry-run raims payment-links update ID --cancel-redirect-url="https://loja.example.com/pedido" --dry-run ``` # raims refunds (/br/cli/commands/refunds) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims refunds` Consulte os estornos e seus comprovantes. ```bash raims refunds [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de refunds. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims refunds get`](#raims-refunds-get), [`raims refunds list`](#raims-refunds-list), [`raims refunds receipt`](#raims-refunds-receipt). ### `raims refunds get` Consulte um estorno. ```bash raims refunds get ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de get. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get a refund. GET /v1/refunds/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json refunds get ID --dry-run ``` ### `raims refunds list` Liste os estornos. ```bash raims refunds list [flags] ``` * `--after` string padrão: vazio * Consulte após este cursor opaco. Não combine com --before. * `--all` bool padrão: false * Leia todas as páginas como resultados separados. Com --output json, a saída usa JSON Lines. * `--before` string padrão: vazio * Consulte antes deste cursor opaco. Não combine com --after. * `--created-gte` int64 padrão: 0 * Criado a partir desta data Unix, em segundos. * `--created-lte` int64 padrão: 0 * Criado até esta data Unix, em segundos. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de list. * `--max-pages` int padrão: 100 * Limite de páginas com --all, entre 1 e 10000. * `--page-size` int64 padrão: 10 * Quantidade de resultados por página. A API ajusta o tamanho solicitado. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text List refunds. GET /v1/refunds Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json refunds list --dry-run ``` ### `raims refunds receipt` Consulte os dados para baixar o comprovante de estorno. ```bash raims refunds receipt ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de receipt. * `--save` string padrão: vazio * Salve o PDF no caminho informado, até 32 MiB; o diretório deve existir e o arquivo deve ser novo. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get the refund receipt download information. GET /v1/refunds/{id}/receipt Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json refunds receipt ID --dry-run ``` # raims simulations (/br/cli/commands/simulations) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims simulations` Execute as simulações permitidas pela API para a credencial selecionada. ```bash raims simulations [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de simulations. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims simulations charges`](#raims-simulations-charges), [`raims simulations refunds`](#raims-simulations-refunds). ### `raims simulations charges` Simule cobranças e pagamentos. ```bash raims simulations charges [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de charges. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims simulations charges compensate-boleto`](#raims-simulations-charges-compensate-boleto), [`raims simulations charges configure-scenario`](#raims-simulations-charges-configure-scenario), [`raims simulations charges confirm-payment`](#raims-simulations-charges-confirm-payment), [`raims simulations charges fail-payment`](#raims-simulations-charges-fail-payment), [`raims simulations charges issue-payment`](#raims-simulations-charges-issue-payment), [`raims simulations charges refunds`](#raims-simulations-charges-refunds), [`raims simulations charges resolve-scenario`](#raims-simulations-charges-resolve-scenario). #### `raims simulations charges compensate-boleto` Simule a compensação de um boleto. ```bash raims simulations charges compensate-boleto ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de compensate-boleto. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Simulate boleto clearing. POST /v1/simulations/charges/{id}/compensate_boleto Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json simulations charges compensate-boleto ID --dry-run ``` #### `raims simulations charges configure-scenario` Configure o resultado da próxima simulação. ```bash raims simulations charges configure-scenario ID [flags] ``` * `--action` string padrão: vazio * Defina action no corpo JSON: texto obrigatório. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de configure-scenario. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--outcome` string padrão: vazio * Defina outcome no corpo JSON: texto obrigatório. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Configure the result of the next simulated operation. POST /v1/simulations/charges/{id}/scenario Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: action string required; allowed: "pix_issuance", "boleto_issuance", "cancellation" outcome string required; allowed: "pending", "failed" Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "action": "boleto_issuance", "outcome": "failed" } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json simulations charges configure-scenario ID --data-file request.json --dry-run raims simulations charges configure-scenario ID --action="boleto_issuance" --outcome="failed" --dry-run ``` #### `raims simulations charges confirm-payment` Confirme um pagamento simulado. ```bash raims simulations charges confirm-payment ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de confirm-payment. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Confirm a simulated payment. POST /v1/simulations/charges/{id}/confirm_payment Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json simulations charges confirm-payment ID --dry-run ``` #### `raims simulations charges fail-payment` Simule uma falha de pagamento. ```bash raims simulations charges fail-payment ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de fail-payment. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Simulate a failed payment. POST /v1/simulations/charges/{id}/fail_payment Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json simulations charges fail-payment ID --dry-run ``` #### `raims simulations charges issue-payment` Emita um pagamento simulado para uma cobrança. ```bash raims simulations charges issue-payment ID [flags] ``` * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de issue-payment. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--payment-method` integer padrão: 0 * Defina payment\_method no corpo JSON: inteiro obrigatório. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Issue a simulated payment for a charge. POST /v1/simulations/charges/{id}/issue_payment Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: payment_method integer required Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "payment_method": 2 } Example values are illustrative. Replace resource IDs and review the request before sending it. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json simulations charges issue-payment ID --data-file request.json --dry-run raims simulations charges issue-payment ID --payment-method=2 --dry-run ``` #### `raims simulations charges refunds` Simule estornos pendentes de uma cobrança. ```bash raims simulations charges refunds [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de refunds. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims simulations charges refunds create`](#raims-simulations-charges-refunds-create). ##### `raims simulations charges refunds create` Crie um estorno simulado pendente. ```bash raims simulations charges refunds create ID [flags] ``` * `--amount-cents` integer padrão: 0 * Defina amount\_cents no corpo JSON: inteiro obrigatório. * `--body-null` stringArray padrão: [] * Envie null em um campo do corpo que aceite esse valor, usando o nome JSON; repita para outros campos e não combine com --data-file. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--description` string padrão: vazio * Defina description no corpo JSON: texto que aceita null. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de create. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Create a pending simulated refund. POST /v1/simulations/charges/{id}/refunds Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: amount_cents integer required description string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "amount_cents": 2500, "description": "Devolução parcial do serviço" } Example values are illustrative. Replace resource IDs and review the request before sending it. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json simulations charges refunds create ID --data-file request.json --dry-run raims simulations charges refunds create ID --amount-cents=2500 --dry-run ``` #### `raims simulations charges resolve-scenario` Resolva uma simulação pendente. ```bash raims simulations charges resolve-scenario ID [flags] ``` * `--action` string padrão: vazio * Defina action no corpo JSON: texto obrigatório. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de resolve-scenario. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--outcome` string padrão: vazio * Defina outcome no corpo JSON: texto obrigatório. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Resolve a pending simulated operation. POST /v1/simulations/charges/{id}/resolve Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: action string required; allowed: "pix_issuance", "boleto_issuance", "cancellation" outcome string required; allowed: "completed", "failed" Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "action": "boleto_issuance", "outcome": "failed" } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json simulations charges resolve-scenario ID --data-file request.json --dry-run raims simulations charges resolve-scenario ID --action="boleto_issuance" --outcome="failed" --dry-run ``` ### `raims simulations refunds` Conclua ou simule a falha de estornos. ```bash raims simulations refunds [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de refunds. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims simulations refunds complete`](#raims-simulations-refunds-complete), [`raims simulations refunds fail`](#raims-simulations-refunds-fail). #### `raims simulations refunds complete` Conclua um estorno simulado. ```bash raims simulations refunds complete ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de complete. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Complete a simulated refund. POST /v1/simulations/refunds/{id}/complete Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json simulations refunds complete ID --dry-run ``` #### `raims simulations refunds fail` Simule uma falha de estorno. ```bash raims simulations refunds fail ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de fail. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Simulate a failed refund. POST /v1/simulations/refunds/{id}/fail Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json simulations refunds fail ID --dry-run ``` # raims statements (/br/cli/commands/statements) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims statements` Consulte os lançamentos do extrato. ```bash raims statements [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de statements. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims statements get`](#raims-statements-get), [`raims statements list`](#raims-statements-list). ### `raims statements get` Consulte um lançamento do extrato. ```bash raims statements get ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de get. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get an account statement entry. GET /v1/statements/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json statements get ID --dry-run ``` ### `raims statements list` Liste os lançamentos do extrato. ```bash raims statements list [flags] ``` * `--after` string padrão: vazio * Consulte após este cursor opaco. Não combine com --before. * `--all` bool padrão: false * Leia todas as páginas como resultados separados. Com --output json, a saída usa JSON Lines. * `--before` string padrão: vazio * Consulte antes deste cursor opaco. Não combine com --after. * `--created-gte` int64 padrão: 0 * Criado a partir desta data Unix, em segundos. * `--created-lte` int64 padrão: 0 * Criado até esta data Unix, em segundos. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de list. * `--max-pages` int padrão: 100 * Limite de páginas com --all, entre 1 e 10000. * `--page-size` int64 padrão: 10 * Quantidade de resultados por página. A API ajusta o tamanho solicitado. * `--reference-id` string padrão: vazio * Filtre pelo identificador do recurso referenciado. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--sort-order` string padrão: desc * Direção da ordenação: asc ou desc. * `--statement-type` string padrão: vazio * Filtre pelos códigos dos tipos de lançamento, separados por vírgula. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text List account statement entries. GET /v1/statements Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json statements list --dry-run ``` # raims webhook-event-types (/br/cli/commands/webhook-event-types) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims webhook-event-types` Consulte os tipos de evento aceitos nos webhooks. ```bash raims webhook-event-types [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de webhook-event-types. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims webhook-event-types list`](#raims-webhook-event-types-list). ### `raims webhook-event-types list` Liste os tipos de evento aceitos nos webhooks. ```bash raims webhook-event-types list [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de list. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text List supported webhook event types. GET /v1/webhook_event_types Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json webhook-event-types list --dry-run ``` # raims webhooks (/br/cli/commands/webhooks) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims webhooks` Gerencie os webhooks. ```bash raims webhooks [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de webhooks. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims webhooks create`](#raims-webhooks-create), [`raims webhooks delete`](#raims-webhooks-delete), [`raims webhooks get`](#raims-webhooks-get), [`raims webhooks health`](#raims-webhooks-health), [`raims webhooks list`](#raims-webhooks-list), [`raims webhooks rotate-secret`](#raims-webhooks-rotate-secret), [`raims webhooks set-pause`](#raims-webhooks-set-pause), [`raims webhooks test`](#raims-webhooks-test), [`raims webhooks update`](#raims-webhooks-update). ### `raims webhooks create` Cadastre um webhook. ```bash raims webhooks create [flags] ``` * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--events` stringArray padrão: vazio * Defina events no corpo JSON: lista obrigatória de textos; repita a opção para cada item. * `--help`, `-h` bool padrão: false * Exibe a ajuda de create. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--is-active` bool padrão: false * Defina is\_active no corpo JSON: booleano. * `--name` string padrão: vazio * Defina name no corpo JSON: texto obrigatório. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. * `--url` string padrão: vazio * Defina url no corpo JSON: texto obrigatório. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Create a webhook endpoint. POST /v1/webhooks Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: events array required; allowed: "charge.created", "charge.paid", "charge.canceled", "charge.failed", "refund.requested", "refund.completed", "refund.failed" is_active boolean optional name string required url string required Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "name": "Pedidos pagos", "url": "https://webhooks.example.com/raims", "events": [ "charge.paid" ], "is_active": true } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json webhooks create --data-file request.json --dry-run raims webhooks create --events="charge.paid" --name="Pedidos pagos" --url="https://webhooks.example.com/raims" --dry-run ``` ### `raims webhooks delete` Exclua um webhook. ```bash raims webhooks delete WEBHOOK_ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de delete. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Delete a webhook endpoint. DELETE /v1/webhooks/{webhook_id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json webhooks delete WEBHOOK_ID --dry-run ``` ### `raims webhooks get` Consulte um webhook. ```bash raims webhooks get WEBHOOK_ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de get. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get a webhook endpoint. GET /v1/webhooks/{webhook_id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json webhooks get WEBHOOK_ID --dry-run ``` ### `raims webhooks health` Consulte as falhas de entrega do webhook. ```bash raims webhooks health WEBHOOK_ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de health. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get webhook delivery failures. GET /v1/webhooks/{webhook_id}/health Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json webhooks health WEBHOOK_ID --dry-run ``` ### `raims webhooks list` Liste os webhooks. ```bash raims webhooks list [flags] ``` * `--after` string padrão: vazio * Consulte após este cursor opaco. Não combine com --before. * `--all` bool padrão: false * Leia todas as páginas como resultados separados. Com --output json, a saída usa JSON Lines. * `--before` string padrão: vazio * Consulte antes deste cursor opaco. Não combine com --after. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de list. * `--max-pages` int padrão: 100 * Limite de páginas com --all, entre 1 e 10000. * `--page-size` int64 padrão: 10 * Quantidade de resultados por página. A API ajusta o tamanho solicitado. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text List webhook endpoints. GET /v1/webhooks Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json webhooks list --dry-run ``` ### `raims webhooks rotate-secret` Rotacione o segredo de assinatura de um webhook. ```bash raims webhooks rotate-secret WEBHOOK_ID [flags] ``` * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--grace-period-seconds` integer padrão: 0 * Defina grace\_period\_seconds no corpo JSON: inteiro. * `--help`, `-h` bool padrão: false * Exibe a ajuda de rotate-secret. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Rotate a webhook signing secret. POST /v1/webhooks/{webhook_id}/rotate_secret Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: grace_period_seconds integer optional Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "grace_period_seconds": 86400 } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json webhooks rotate-secret WEBHOOK_ID --data-file request.json --dry-run raims webhooks rotate-secret WEBHOOK_ID --grace-period-seconds=86400 --dry-run ``` ### `raims webhooks set-pause` Pause ou retome as entregas de webhook com uma requisição JSON. ```bash raims webhooks set-pause WEBHOOK_ID [flags] ``` * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de set-pause. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--is-paused` bool padrão: false * Defina is\_paused no corpo JSON: booleano obrigatório. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Pause or resume webhook deliveries using a JSON request. PATCH /v1/webhooks/{webhook_id}/pause Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: is_paused boolean required Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "is_paused": true } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json webhooks set-pause WEBHOOK_ID --data-file request.json --dry-run raims webhooks set-pause WEBHOOK_ID --is-paused=true --dry-run ``` ### `raims webhooks test` Solicite um evento de teste para um webhook. ```bash raims webhooks test WEBHOOK_ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de test. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Request a test event for a webhook endpoint. POST /v1/webhooks/{webhook_id}/test Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json webhooks test WEBHOOK_ID --dry-run ``` ### `raims webhooks update` Atualize um webhook. ```bash raims webhooks update WEBHOOK_ID [flags] ``` * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--events` stringArray padrão: vazio * Defina events no corpo JSON: lista de textos; repita a opção para cada item. * `--help`, `-h` bool padrão: false * Exibe a ajuda de update. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--is-active` bool padrão: false * Defina is\_active no corpo JSON: booleano. * `--name` string padrão: vazio * Defina name no corpo JSON: texto. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. * `--url` string padrão: vazio * Defina url no corpo JSON: texto. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Update a webhook endpoint. PATCH /v1/webhooks/{webhook_id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: events array optional is_active boolean optional name string optional url string optional Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "events": [ "charge.paid", "refund.completed" ] } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json webhooks update WEBHOOK_ID --data-file request.json --dry-run raims webhooks update WEBHOOK_ID --events="charge.paid" --events="refund.completed" --dry-run ``` # raims withdrawal-destinations (/br/cli/commands/withdrawal-destinations) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims withdrawal-destinations` Consulte os destinos de saque. ```bash raims withdrawal-destinations [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de withdrawal-destinations. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims withdrawal-destinations get`](#raims-withdrawal-destinations-get), [`raims withdrawal-destinations list`](#raims-withdrawal-destinations-list). ### `raims withdrawal-destinations get` Consulte um destino de saque. ```bash raims withdrawal-destinations get ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de get. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get a withdrawal destination. GET /v1/withdrawal_destinations/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json withdrawal-destinations get ID --dry-run ``` ### `raims withdrawal-destinations list` Liste os destinos de saque. ```bash raims withdrawal-destinations list [flags] ``` * `--after` string padrão: vazio * Consulte após este cursor opaco. Não combine com --before. * `--all` bool padrão: false * Leia todas as páginas como resultados separados. Com --output json, a saída usa JSON Lines. * `--before` string padrão: vazio * Consulte antes deste cursor opaco. Não combine com --after. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de list. * `--max-pages` int padrão: 100 * Limite de páginas com --all, entre 1 e 10000. * `--page-size` int64 padrão: 10 * Quantidade de resultados por página. A API ajusta o tamanho solicitado. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text List withdrawal destinations. GET /v1/withdrawal_destinations Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json withdrawal-destinations list --dry-run ``` # raims withdrawals (/br/cli/commands/withdrawals) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## `raims withdrawals` Consulte e solicite saques. ```bash raims withdrawals [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de withdrawals. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims withdrawals automatic-settings`](#raims-withdrawals-automatic-settings), [`raims withdrawals create`](#raims-withdrawals-create), [`raims withdrawals get`](#raims-withdrawals-get), [`raims withdrawals limits`](#raims-withdrawals-limits), [`raims withdrawals list`](#raims-withdrawals-list), [`raims withdrawals summary`](#raims-withdrawals-summary). ### `raims withdrawals automatic-settings` Gerencie as configurações de saque automático. ```bash raims withdrawals automatic-settings [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de automatic-settings. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims withdrawals automatic-settings get`](#raims-withdrawals-automatic-settings-get), [`raims withdrawals automatic-settings update`](#raims-withdrawals-automatic-settings-update). #### `raims withdrawals automatic-settings get` Consulte as configurações de saque automático. ```bash raims withdrawals automatic-settings get [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de get. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get automatic withdrawal settings. GET /v1/withdrawals/automatic_settings Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json withdrawals automatic-settings get --dry-run ``` #### `raims withdrawals automatic-settings update` Atualize as configurações de saque automático. ```bash raims withdrawals automatic-settings update [flags] ``` * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--enabled` bool padrão: false * Defina enabled no corpo JSON: booleano. * `--help`, `-h` bool padrão: false * Exibe a ajuda de update. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--minimum-amount-cents` integer padrão: 0 * Defina minimum\_amount\_cents no corpo JSON: inteiro. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--time` string padrão: vazio * Defina time no corpo JSON: texto. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Update automatic withdrawal settings. PATCH /v1/withdrawals/automatic_settings Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: enabled boolean optional minimum_amount_cents integer optional time string optional Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "time": "10:00" } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json withdrawals automatic-settings update --data-file request.json --dry-run raims withdrawals automatic-settings update --time="10:00" --dry-run ``` ### `raims withdrawals create` Solicite um saque para a chave Pix padrão da empresa. ```bash raims withdrawals create [flags] ``` * `--amount-cents` integer padrão: 0 * Defina amount\_cents no corpo JSON: inteiro obrigatório. * `--body-null` stringArray padrão: [] * Envie null em um campo do corpo que aceite esse valor, usando o nome JSON; repita para outros campos e não combine com --data-file. * `--data-file` string padrão: vazio * Leia o corpo JSON de um arquivo UTF-8 ou use '-' para stdin. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--expected-destination-id` string padrão: vazio * Defina expected\_destination\_id no corpo JSON (string, aceita null). * `--help`, `-h` bool padrão: false * Exibe a ajuda de create. * `--idempotency-key` string padrão: vazio * Reutilize esta chave de idempotência opcional ao repetir a mesma requisição. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Request a withdrawal to the company's default Pix key. POST /v1/withdrawals Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: amount_cents integer required expected_destination_id string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "amount_cents": 25000 } Example values are illustrative. Replace resource IDs and review the request before sending it. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json withdrawals create --data-file request.json --dry-run raims withdrawals create --amount-cents=25000 --dry-run ``` ### `raims withdrawals get` Consulte um saque. ```bash raims withdrawals get ID [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de get. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get a withdrawal. GET /v1/withdrawals/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json withdrawals get ID --dry-run ``` ### `raims withdrawals limits` Consulte as condições e os limites de saque. ```bash raims withdrawals limits [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de limits. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get withdrawal conditions and limits. GET /v1/withdrawals/limits Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json withdrawals limits --dry-run ``` ### `raims withdrawals list` Liste os saques. ```bash raims withdrawals list [flags] ``` * `--after` string padrão: vazio * Consulte após este cursor opaco. Não combine com --before. * `--all` bool padrão: false * Leia todas as páginas como resultados separados. Com --output json, a saída usa JSON Lines. * `--before` string padrão: vazio * Consulte antes deste cursor opaco. Não combine com --after. * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de list. * `--max-pages` int padrão: 100 * Limite de páginas com --all, entre 1 e 10000. * `--page-size` int64 padrão: 10 * Quantidade de resultados por página. A API ajusta o tamanho solicitado. * `--requested-gte` int64 padrão: 0 * Solicitado a partir desta data Unix, em segundos. * `--requested-lte` int64 padrão: 0 * Solicitado até esta data Unix, em segundos. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--sort-order` string padrão: desc * Direção da ordenação: asc ou desc. * `--status` string padrão: vazio * Filtre pelos nomes dos status dos saques, separados por vírgula. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text List withdrawals. GET /v1/withdrawals Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json withdrawals list --dry-run ``` ### `raims withdrawals summary` Consulte o resumo dos saques em andamento. ```bash raims withdrawals summary [flags] ``` * `--dry-run` bool padrão: false * Valide e apresente a requisição sem credenciais ou acesso à rede. * `--help`, `-h` bool padrão: false * Exibe a ajuda de summary. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas. Exemplos: 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Get a summary of withdrawals in progress. GET /v1/withdrawals/summary Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. ``` **Exemplo do comando** ```bash raims --profile PROFILE --output json withdrawals summary --dry-run ``` # Configuração e perfis (/br/cli/configuration) Use um perfil para cada conta ou integração. Você pode conectar o CLI pelo navegador com OAuth ou associar uma chave de API a uma variável de ambiente. A configuração guarda as referências necessárias; os segredos ficam fora do arquivo de perfis. ## Conectar pelo navegador Para usar sua conta no terminal, escolha um nome de perfil e o ambiente: ```bash raims login --profile pessoal --environment sandbox raims profile use pessoal ``` O CLI abre a página de login da Raims. Confira a conta e o aplicativo **Raims CLI**, escolha as permissões, revise os ambientes autorizados e conclua a confirmação de segurança. Volte ao terminal quando a autorização terminar. Você não precisa copiar uma chave de API nem informar sua senha ao CLI. Ao repetir o login, o CLI confere a autorização no servidor. Se a sessão continuar válida, ele reutiliza a conexão. Se ela tiver expirado ou sido revogada, abre um novo consentimento. Uma indisponibilidade temporária não cria outra conexão: aguarde e tente novamente. Para conectar outra conta, escolha outro nome de perfil. O acesso continua limitado às permissões concedidas e ao acesso atual de quem autorizou. A sessão é renovada automaticamente enquanto a conexão permanecer válida. As credenciais são protegidas pelo armazenamento seguro do sistema operacional. Se ele estiver indisponível, corrija seu acesso ou use um perfil de chave de API; o CLI não salva a sessão em texto aberto. Antes de cada requisição, o CLI confere se o token continua válido durante o prazo definido por `--timeout` e o renova quando necessário. Se a validade continuar insuficiente, a requisição não é enviada. Consulte a orientação de `OAUTH_TOKEN_LIFETIME_INSUFFICIENT` em [Diagnóstico](/br/cli/diagnostics). Para conferir os metadados locais da sessão sem acessar a rede: ```bash raims --profile pessoal auth status ``` Essa consulta não confirma o acesso atual no servidor. Use `auth check` para fazer uma leitura autenticada. Se preferir abrir o navegador manualmente, execute: ```bash raims login --profile pessoal --environment sandbox --no-browser ``` Abra o endereço apresentado e mantenha o comando em execução até concluir. O navegador precisa alcançar o retorno local na máquina que executa o CLI. A opção não transforma o login em um fluxo por código para outro dispositivo. Login exige um terminal interativo; para pipelines, use uma chave de API. ## Selecionar o ambiente No login OAuth, `--environment sandbox` ou `--environment production` define o ambiente inicial do perfil. Os comandos seguintes usam essa escolha. Para executar um comando em outro ambiente autorizado, informe a opção: ```bash raims --profile pessoal --environment sandbox customers list raims --profile pessoal --environment production accounts fees ``` A opção só seleciona um ambiente já autorizado. Ela não amplia o acesso nem altera os ambientes da conexão. Confira a conta e o ambiente antes de enviar uma escrita em Produção. Em perfis de chave de API, a própria chave determina o ambiente. Use a chave do ambiente desejado; uma opção de ambiente não converte a credencial. ## Encerrar a sessão Para revogar a conexão OAuth do perfil: ```bash raims logout --profile pessoal ``` Após confirmar a revogação, o CLI remove a sessão e o perfil locais. Se a revogação falhar, eles são preservados para você tentar novamente. Você também pode revogar o acesso em **Integração / Aplicativos autorizados**. Sair da sessão do Dashboard não encerra a conexão do CLI. Para conectar novamente, execute `raims login` e revise as permissões. ## Criar um perfil Para scripts e integrações que usam uma chave de API: ### Associe a variável de ambiente ```bash raims profile set sandbox --api-key-env RAIMS_SANDBOX_API_KEY ``` Informe o nome da variável em `--api-key-env`. Ele aceita letras maiúsculas, dígitos e sublinhado, começando por letra ou sublinhado. Configure o valor da chave separadamente no seu terminal ou gerenciador de segredos. ### Selecione o padrão ```bash raims profile use sandbox ``` Esse comando salva a seleção usada quando a execução não informa outro perfil. ### Confira os perfis ```bash raims profile list raims profile show sandbox ``` A listagem identifica o perfil padrão. A consulta mostra o nome do perfil e a variável associada, sem imprimir o valor da chave. O nome `sandbox` não define o ambiente de uma requisição. A chave validada pela API determina o ambiente e a empresa, conforme o guia de [autenticação](/br/integracoes/autenticacao). Para uma credencial de Produção, você pode criar outro perfil com uma variável separada: ```bash raims profile set production --api-key-env RAIMS_PRODUCTION_API_KEY ``` Disponibilize o valor da chave nessa variável para o processo do CLI. Requisições de ambos os perfis usam `https://api.raims.com`. O CLI não aceita outro endereço por flag, variável de ambiente ou configuração do perfil. ## Verificar o acesso à API ```bash raims --profile sandbox --output json auth check ``` O comando lê `GET /v1/accounts/fees` em `https://api.raims.com` com a credencial do perfil selecionado, sem alterar a conta. Ele aceita os perfis OAuth e de chave de API. No sucesso, retorna: ```json { "status_code": 200, "data": { "authenticated": true, "profile": "sandbox" } } ``` Esse resultado confirma acesso à leitura de tarifas. Cada outro endpoint valida suas próprias permissões e condições. Uma recusa nesse comando também pode indicar falta de permissão para essa leitura; ela não comprova, sozinha, que a credencial é inválida. Confira o status HTTP e `error.code` retornados. Em um perfil de chave de API, uma variável ausente ou vazia impede o envio da requisição. O CLI não lê a chave de um argumento nem grava seu valor no perfil. ## Escolher o perfil da execução A seleção segue esta ordem: | Prioridade | Origem | Quando usar | | ---------- | ------------------- | ---------------------------------------------- | | 1 | `--profile NOME` | Escolher o perfil de um comando. | | 2 | `RAIMS_PROFILE` | Escolher o perfil do terminal ou da automação. | | 3 | Perfil padrão salvo | Reutilizar a seleção de `raims profile use`. | Para selecionar somente nesta execução: ```bash raims --profile sandbox profile show ``` A flag não altera o padrão salvo. Um perfil informado em `--profile` tem prioridade sobre `RAIMS_PROFILE`. `raims profile show NOME` consulta o perfil informado no argumento, mesmo quando outro perfil está selecionado. A listagem preserva a identificação do padrão salvo e informa também a seleção da execução na saída JSON. ### PowerShell ```powershell $env:RAIMS_PROFILE = 'sandbox' raims profile show ``` ### Bash e Zsh ```bash export RAIMS_PROFILE=sandbox raims profile show ``` ## Remover um perfil Para retirar um perfil antigo da configuração local: ```bash raims profile remove old-project ``` Perfis OAuth exigem `raims logout` antes da remoção ou da substituição por um perfil de chave de API. Informe o nome exato do perfil de chave. A remoção não revoga a chave na API nem altera a variável de ambiente que a contém. Se o perfil removido era o padrão salvo, o CLI limpa essa seleção e não escolhe outro perfil. Use `raims profile use NOME` para salvar um novo padrão. Repetir o comando para um perfil já ausente termina com sucesso. Com `--output json`, o resultado informa `name` e `configured: false`. Se `RAIMS_PROFILE` ainda apontar para o perfil removido, atualize ou remova essa seleção no seu terminal antes de executar outro comando que use perfil. ## Preparar o autocompletar Use o assistente para detectar o shell e ver as instruções de ativação: ```bash raims completion setup ``` Sem `--save`, o comando apresenta o plano sem criar arquivos. Se a detecção não identificar um shell compatível, informe `--shell powershell|bash|zsh|fish`. Para ver o plano de gravação e depois salvar o script de PowerShell: ```bash raims completion setup --shell powershell --save ./raims-completion.ps1 --dry-run raims completion setup --shell powershell --save ./raims-completion.ps1 ``` O diretório deve existir e o arquivo deve ser novo. O CLI não sobrescreve arquivos nem altera o perfil ou o arquivo de inicialização do shell. Depois de gravar, siga as instruções apresentadas para ativar o autocompletar na sessão desejada, respeitando a política do seu terminal. O assistente funciona sem perfil, chave ou rede e não ativa atualizações. Com `--output json`, retorna o shell escolhido, a origem dessa escolha, o caminho quando informado, os indicadores de gravação e prévia e as instruções. Os comandos existentes, como `raims completion powershell`, continuam gerando o script em stdout para quem prefere configurar manualmente. ## Local da configuração Consulte o caminho usado pelo CLI: ```bash raims config path ``` Por padrão, o arquivo fica na pasta `raims` do diretório de configurações do usuário. Defina `RAIMS_CONFIG_DIR` com um caminho absoluto para usar outra pasta, por exemplo em uma automação com configuração isolada. Mantenha essa pasta sob as permissões do usuário que executa o CLI. O arquivo de perfis contém referências e metadados de autenticação, sem segredos em texto aberto. A sessão OAuth permanece cifrada e depende do armazenamento seguro do sistema para ser lida. # Diagnóstico (/br/cli/diagnostics) Use `raims doctor` para conferir a configuração do CLI e identificar o que precisa ser corrigido na sua instalação. ## Executar o diagnóstico ```bash raims doctor ``` As verificações abrangem a leitura da configuração e do perfil selecionado, as permissões dos arquivos locais, a identidade do executável e a política de atualização. O resultado de cada verificação informa a condição encontrada e a orientação aplicável. | Resultado | Significado | | --------- | -------------------------------------------------------------------------------------------------- | | `ok` | A verificação foi concluída sem problemas. | | `warning` | Há uma condição a conferir, como perfil não selecionado ou variável da chave ausente. | | `error` | Há uma falha, como configuração inválida, perfil solicitado inexistente ou permissão insuficiente. | Uma verificação com `error` faz o comando terminar com código `3`. Avisos permitem concluir o diagnóstico com código `0`. Para escolher outro perfil ou capturar o resultado em uma automação: ```bash raims --profile sandbox --output json doctor ``` O JSON reúne `status`, `build`, `interactive`, o `profile` selecionado quando houver um e a lista `checks`. Cada verificação contém `name`, `status` e `message`. Os nomes são `configuration`, `profile`, `permissions`, `installation` e `updates`. O diagnóstico não envia requisições à API nem confirma a validade da credencial, as permissões da empresa ou a conectividade com o serviço. Consulte os guias de [autenticação](/br/integracoes/autenticacao) e [chaves de API](/br/integracoes/chaves-api) para essas condições. ## Conferir a arquitetura Para consultar o sistema e a arquitetura do executável em uso: ```bash raims --output json version ``` No CLI nativo para Windows ARM64, o resultado contém `os: "windows"` e `arch: "arm64"`. Essa consulta é local e não exige perfil, chave ou rede. Se instalou pelo npm, confira também o Node.js usado no mesmo terminal: ```bash node -p "process.platform + '/' + process.arch" ``` Para usar o pacote nativo no Windows ARM64, tenha Node.js 22 ou superior para ARM64. O comando acima deve retornar `win32/arm64`. Um Node.js x64 seleciona o pacote x64, inclusive quando o Windows é ARM64. Com o Node.js ARM64 disponível, instale ou atualize com `npm install -g @raimshq/cli@latest` e confira novamente a versão do CLI. Na instalação direta, escolha o instalador da arquitetura desejada e confira o executável pelo caminho completo. O instalador não substitui uma instalação de outra versão ou arquitetura. Se precisar manter ambas, escolha outro diretório do usuário com `-directory CAMINHO`, preserve a instalação existente e use o caminho completo da nova. Consulte [Instalação direta](/br/cli/direct-installation). ## Conferir o acesso à API ```bash raims --profile sandbox --output json auth check --timeout 30s ``` Esse comando envia `GET /v1/accounts/fees` a `https://api.raims.com` com a sessão OAuth ou a chave de API associada ao perfil. Ele não altera a conta. O resultado de sucesso contém `data.authenticated: true` e o nome do perfil, confirmando acesso a essa leitura. Os demais endpoints continuam sujeitos às suas permissões e condições. Chaves de Sandbox e de Produção usam o mesmo endereço. Em um perfil de chave, a API determina o ambiente pela credencial. Em um perfil OAuth, use o ambiente escolhido no login ou informe `--environment sandbox|production`. Para conferir o acesso a outro recurso, use seu comando de leitura e consulte o status HTTP e `error.code` se houver uma recusa. `auth check` não concede permissões nem executa escritas de teste. Para conferir somente os metadados locais de uma sessão OAuth, sem acessar o cofre ou a rede, use `raims --profile pessoal auth status`. Essa consulta não substitui a verificação de acesso no servidor. ## Fazer login novamente no mesmo perfil do CLI Execute `raims login --profile pessoal --environment sandbox`. O CLI confere a autorização no servidor e reutiliza uma sessão válida. Se ela tiver expirado ou sido revogada, abre um novo consentimento no navegador. Confira o nome do perfil, a conta e os acessos antes de autorizar. Para outra conta, use outro perfil. ## Renovação de sessão temporariamente indisponível Se receber `OAUTH_SERVICE_UNAVAILABLE`, aguarde e repita o comando. Essa recusa temporária da renovação preserva a sessão para outra tentativa, sem exigir um novo consentimento. Se o erro informar que a renovação não pôde ser confirmada, siga a orientação apresentada antes de tentar novamente. ## Cancelamento do CLI e código de saída Interromper o comando com Ctrl+C retorna `CANCELLED` e o código de saída `130`, inclusive durante o login ou a renovação da sessão. Cancelar uma requisição não desfaz o que a API já aceitou. Se ela alterava um recurso, consulte o resultado antes de repetir. ## Investigar uma falha Quando você digita um nome próximo de um comando conhecido, o CLI sugere a grafia correta e mostra como abrir a ajuda do grupo. Por exemplo, `raims customers creat` pode sugerir `raims customers create`. A sugestão não é executada. O erro mantém o código `UNKNOWN_COMMAND` e o código de saída `2`. Quando uma opção estiver escrita de forma próxima a uma opção conhecida, o CLI pode sugerir a correção, como `--full-name` ao receber `--full_name`. Se faltar um valor ou seu formato estiver incorreto, a mensagem indica o tipo ou os valores aceitos e a ajuda do comando, como `raims charges create --help`. Sugestões ambíguas são omitidas. Para metadata, use `--metadata chave=valor`; pontos na chave fazem parte do nome, sem criar opções aninhadas. Os erros de opções mantêm `INVALID_ARGUMENT`, a categoria `usage` e o código de saída `2`, sem repetir os valores informados. Esses erros não executam a requisição. `OAUTH_TOKEN_LIFETIME_INSUFFICIENT` indica que o CLI não obteve um token válido por todo o prazo da requisição, mesmo após tentar renová-lo. A requisição à API não foi enviada. Use um `--timeout` menor que ainda seja adequado ao comando ou execute `raims logout` e `raims login` para renovar a autorização. Esse erro usa o código de saída `4`. ### O armazenamento seguro não está disponível Confira se a sessão do sistema operacional tem acesso ao seu armazenamento seguro. O CLI precisa dele para proteger e ler a sessão OAuth. Em um pipeline sem esse recurso, use um perfil de chave de API e injete o segredo pela variável associada. Não copie arquivos de sessão para contornar o erro. ### O perfil não foi encontrado Execute `raims profile list` e confira o nome informado. A seleção segue `--profile`, `RAIMS_PROFILE` e, por último, o padrão salvo. Para salvar outro padrão, use `raims profile use NOME`. ### A configuração não pode ser lida Consulte `raims config path` e confira as permissões do usuário que executa o processo. Se usar `RAIMS_CONFIG_DIR`, informe um caminho absoluto para a pasta correta. Preserve uma cópia do arquivo antes de corrigi-lo. ### A variável da chave está ausente Consulte `raims profile show` para identificar a variável associada ao perfil selecionado. Disponibilize a chave nessa variável para o processo do CLI pelo terminal ou gerenciador de segredos. Não passe seu valor em `--api-key-env`: essa opção recebe somente o nome da variável. ### A API recusou o acesso Confira o status HTTP e `error.code`. Uma chave válida pode não ter acesso ao endpoint consultado. Verifique a credencial, as permissões e as restrições de acesso aplicáveis àquela requisição. O código de saída `4` indica falha de autenticação ou autorização. ### A requisição terminou sem resposta confirmada O código de saída `5` indica falha de rede ou timeout. Confira a conectividade e o prazo informado em `--timeout`. Se a requisição alterava um recurso, consulte seu resultado antes de repetir: um timeout ou cancelamento local não desfaz o que a API já aceitou. ### O gerenciador bloqueou uma versão recém-publicada Alguns gerenciadores exigem um prazo de segurança após a publicação de uma versão. Se a instalação informar esse bloqueio, aguarde o prazo indicado e tente novamente. No Yarn, o erro `YN0016` pode indicar essa condição; confira se a mensagem menciona a quarentena da versão. ### A atualização está desativada Consulte `raims update status` para ver o motivo. Confira os controles `RAIMS_CLI_NO_UPDATE` e `RAIMS_CLI_PIN_VERSION` e se o processo está em CI. Instalações mantidas por gerenciadores de pacotes seguem a atualização do respectivo gerenciador. Se instalou pelo npm, atualize com `npm install -g @raimshq/cli@latest`. Em pipelines, use `@latest` na etapa de instalação e confira se `RAIMS_CLI_PIN_VERSION` está exigindo uma versão anterior. O atualizador próprio permanece desativado nessa instalação. Uma atualização desativada não impede o uso da versão instalada. Para uma instalação direta, confira o executável pelo caminho completo e siga a [política de atualização](/br/cli/direct-installation#controlar-as-atualizações). O pin exige uma versão já disponível e não baixa arquivos. Preserve o cache e os backups ao investigar uma falha. ## Compartilhar um diagnóstico Acrescente `--debug` para obter detalhes de uma execução em `stderr`: ```bash raims --debug --output json doctor ``` O diagnóstico preserva o resultado do comando em `stdout` e oculta os valores das credenciais. Revise caminhos, nomes de perfis e outras informações locais antes de compartilhar os arquivos. Nunca envie chaves de API, tokens ou o endereço completo de um login em andamento junto do relato. Para requisições à API, inclua o código de saída, `error.code` e, quando disponíveis, `error.status_code` e `error.request_id`. Revise também a resposta capturada em `stdout`, pois ela pode conter dados da conta ou segredos do recurso consultado. Para identificar os textos legais incluídos na versão em execução, use `raims licenses --output json`. Essa consulta local não exige perfil nem rede; veja [Avisos e licenças](/br/cli#consultar-avisos-e-licencas). # Instalação direta (/br/cli/direct-installation) A instalação direta usa o executável nativo do Raims CLI. Esse canal não exige Node.js nem npm. O instalador consulta o canal de distribuição pela internet, verifica os arquivos e grava a instalação em uma pasta do usuário, sem pedir uma chave de API. Para instalar pelo npm em uma automação, siga [CI e automação](/br/cli/automation#controlar-a-versão), que usa `@latest`. ## Escolher o instalador Escolha o sistema e a arquitetura da máquina onde o CLI será executado: | Plataforma | Instalador | | ------------- | ----------------------------------------------------------------------------------------------------------------------- | | Windows x64 | [Baixar para Windows x64](https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-windows-amd64.exe) | | Windows ARM64 | [Baixar para Windows ARM64](https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-windows-arm64.exe) | | Linux x64 | [Baixar para Linux x64](https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-linux-amd64) | | Linux ARM64 | [Baixar para Linux ARM64](https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-linux-arm64) | | macOS x64 | [Baixar para macOS x64](https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-darwin-amd64) | | macOS ARM64 | [Baixar para macOS ARM64](https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-darwin-arm64) | `0.1.2` identifica a versão do instalador. Ao consultar o canal, ele seleciona o patch estável mais recente da linha `0.1`. O nome do arquivo não fixa a versão do CLI que será instalada. Confira a versão apresentada no plano. No Windows ARM64, escolha o instalador ARM64 para executar o CLI nativo. Essa instalação direta não exige Node.js. Para conferir a arquitetura de uma instalação existente, consulte [Diagnóstico](/br/cli/diagnostics#conferir-a-arquitetura). No Windows, você pode conferir a assinatura digital do arquivo com `Get-AuthenticodeSignature`. Se o resultado não for `Valid`, não execute o arquivo e confira o download oficial. ## Conferir o plano e instalar Sem `-apply`, o instalador consulta o canal e mostra a versão e o destino, sem aplicar a instalação. Execute novamente com `-apply` depois de conferir o plano. Os exemplos abaixo baixam o instalador e usam o destino padrão. ### Windows x64 ```powershell Invoke-WebRequest -Uri 'https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-windows-amd64.exe' -OutFile '.\raims-install-0.1.2-windows-amd64.exe' .\raims-install-0.1.2-windows-amd64.exe .\raims-install-0.1.2-windows-amd64.exe -apply ``` ### Windows ARM64 ```powershell Invoke-WebRequest -Uri 'https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-windows-arm64.exe' -OutFile '.\raims-install-0.1.2-windows-arm64.exe' .\raims-install-0.1.2-windows-arm64.exe .\raims-install-0.1.2-windows-arm64.exe -apply ``` ### Linux x64 ```bash curl --fail --show-error --output ./raims-install 'https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-linux-amd64' chmod u+x ./raims-install ./raims-install ./raims-install -apply ``` ### Linux ARM64 ```bash curl --fail --show-error --output ./raims-install 'https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-linux-arm64' chmod u+x ./raims-install ./raims-install ./raims-install -apply ``` ### macOS x64 ```bash curl --fail --show-error --output ./raims-install 'https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-darwin-amd64' chmod u+x ./raims-install ./raims-install ./raims-install -apply ``` ### macOS ARM64 ```bash curl --fail --show-error --output ./raims-install 'https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-darwin-arm64' chmod u+x ./raims-install ./raims-install ./raims-install -apply ``` `-directory CAMINHO` escolhe outro destino absoluto dentro do espaço do usuário. A pasta precisa ser gravável e não pode ser acessada por links ou junctions. O instalador não eleva permissões nem substitui arquivos desconhecidos ou uma instalação de outra versão. Uma repetição exata reutiliza a instalação e preserva arquivos adicionais. ## Usar o executável instalado Os destinos padrão são: | Sistema | Executável | | ------------- | ------------------------------------ | | Windows | `%LOCALAPPDATA%\Raims\CLI\raims.exe` | | Linux e macOS | `~/.local/share/raims/cli/raims` | Você pode usar o caminho completo, sem alterar PATH: ### PowerShell ```powershell & "$env:LOCALAPPDATA\Raims\CLI\raims.exe" version & "$env:LOCALAPPDATA\Raims\CLI\raims.exe" update status ``` ### Bash e Zsh ```bash "$HOME/.local/share/raims/cli/raims" version "$HOME/.local/share/raims/cli/raims" update status ``` Se escolheu outro destino, use o executável nessa pasta. A instalação não cria um perfil nem guarda a chave de API. Para fazer requisições, siga [Configuração e perfis](/br/cli/configuration). ## Criar um comando no PATH `-link-user-path` é uma escolha explícita e exige `-apply` e `-path-directory CAMINHO`. Esse diretório precisa existir no espaço do usuário e já fazer parte do PATH da sessão. O instalador não edita perfis de shell, registro ou o valor do PATH. No exemplo abaixo, use `~/.local/bin` somente se essa pasta já existir e estiver no PATH: ```bash ./raims-install -apply -link-user-path -path-directory "$HOME/.local/bin" raims version ``` No Windows, as mesmas opções recebem um diretório do usuário já presente no PATH. `WindowsApps` não é aceito como destino dessa integração. Resolva conflitos com outras instalações, aliases ou funções do shell antes de criar a entrada. O instalador recusa um comando anterior no PATH ou uma entrada conflitante no diretório escolhido. Se a integração falhar, a instalação verificada é preservada; use o caminho completo do executável. ## Controlar as atualizações Na instalação direta, o CLI pode consultar atualizações silenciosamente enquanto é usado. Uma versão baixada fica pendente e pode ser ativada na próxima execução elegível, sem interromper o comando que já estava rodando. Se a consulta ou a verificação falhar, a versão instalada é preservada. `raims update status` mostra a política e as versões locais, sem buscar uma atualização. `RAIMS_CLI_NO_UPDATE=1` desativa consultas e ativações pendentes; não reverte uma versão já ativa. `RAIMS_CLI_PIN_VERSION` exige uma versão que já esteja instalada ou conservada pelo CLI. O pin não baixa uma versão. Ambientes de CI desativam consultas e ativações automáticas. Nos exemplos de instalação por npm, inclusive em CI, use `@latest`. Veja como derivar o pin da instalação direta em [CI e automação](/br/cli/automation#controlar-a-versão). ## Conservar versões e backups Preserve as versões em cache, a instalação original e os backups do CLI. Esses arquivos permitem selecionar versões conservadas e recuperar uma instalação. Não há limpeza automática do histórico nesta entrega. Não apague versões enquanto houver comandos em execução. Uma falha de um comando que já iniciou não faz o CLI repeti-lo automaticamente. ## Consultar avisos e licenças `raims licenses` lê os textos incluídos na versão em execução, sem perfil, chave ou rede. A saída JSON contém `text` e `sha256`. Veja os exemplos em [Avisos e licenças](/br/cli#consultar-avisos-e-licencas). # Referência dos comandos (/br/cli/reference) Consulte a sintaxe, os argumentos e as opções de cada comando. Use `raims COMANDO --help` para ler a ajuda no terminal. ## Comandos da API - [raims accounts](/br/cli/commands/accounts): Consulte os dados da conta e configure a aparência do checkout. - [raims balances](/br/cli/commands/balances): Consulte os saldos e os recebimentos previstos. - [raims charges](/br/cli/commands/charges): Gerencie as cobranças e seus dados de pagamento. - [raims customers](/br/cli/commands/customers): Gerencie os clientes. - [raims disputes](/br/cli/commands/disputes): Consulte as contestações. - [raims payment-links](/br/cli/commands/payment-links): Gerencie os links de pagamento. - [raims refunds](/br/cli/commands/refunds): Consulte os estornos e seus comprovantes. - [raims simulations](/br/cli/commands/simulations): Execute as simulações permitidas pela API para a credencial selecionada. - [raims statements](/br/cli/commands/statements): Consulte os lançamentos do extrato. - [raims webhook-event-types](/br/cli/commands/webhook-event-types): Consulte os tipos de evento aceitos nos webhooks. - [raims webhooks](/br/cli/commands/webhooks): Gerencie os webhooks. - [raims withdrawal-destinations](/br/cli/commands/withdrawal-destinations): Consulte os destinos de saque. - [raims withdrawals](/br/cli/commands/withdrawals): Consulte e solicite saques. ## `raims` Interface de linha de comando da Raims. ```bash raims [flags] ``` * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--help`, `-h` bool padrão: false * Exibe a ajuda de raims. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. * `--version`, `-v` bool padrão: false * Exibe a versão de raims. **Descrição detalhada da ajuda do executável** ```text Use the Raims public API, manage local profiles and inspect the installed version and automatic updates. ``` **Exemplo do comando** ```bash raims --map raims charges --map=compact raims --map=json ``` Subcomandos: [`raims accounts`](/br/cli/commands/accounts#raims-accounts), [`raims auth`](#raims-auth), [`raims balances`](/br/cli/commands/balances#raims-balances), [`raims charges`](/br/cli/commands/charges#raims-charges), [`raims completion`](#raims-completion), [`raims config`](#raims-config), [`raims customers`](/br/cli/commands/customers#raims-customers), [`raims disputes`](/br/cli/commands/disputes#raims-disputes), [`raims docs`](#raims-docs), [`raims doctor`](#raims-doctor), [`raims help`](#raims-help), [`raims licenses`](#raims-licenses), [`raims login`](#raims-login), [`raims logout`](#raims-logout), [`raims mcp`](#raims-mcp), [`raims open`](#raims-open), [`raims payment-links`](/br/cli/commands/payment-links#raims-payment-links), [`raims profile`](#raims-profile), [`raims refunds`](/br/cli/commands/refunds#raims-refunds), [`raims simulations`](/br/cli/commands/simulations#raims-simulations), [`raims statements`](/br/cli/commands/statements#raims-statements), [`raims update`](#raims-update), [`raims version`](#raims-version), [`raims webhook-event-types`](/br/cli/commands/webhook-event-types#raims-webhook-event-types), [`raims webhooks`](/br/cli/commands/webhooks#raims-webhooks), [`raims withdrawal-destinations`](/br/cli/commands/withdrawal-destinations#raims-withdrawal-destinations), [`raims withdrawals`](/br/cli/commands/withdrawals#raims-withdrawals). ## `raims auth` Confira a autenticação na API com o perfil selecionado. ```bash raims auth [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de auth. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims auth check`](#raims-auth-check), [`raims auth status`](#raims-auth-status). ### `raims auth check` Valide a credencial selecionada com uma consulta de leitura da conta. ```bash raims auth check [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de check. * `--show-headers` bool padrão: false * Mostre os headers públicos da resposta, sem credenciais ou cookies. * `--timeout` duration padrão: 1m0s * Prazo total da requisição, incluindo novas tentativas e esperas. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Validate the selected profile's API key or OAuth session with GET /v1/accounts/fees at https://api.raims.com. A successful check confirms access to this endpoint; other requests retain their own authorization and eligibility rules. ``` ### `raims auth status` Consulte os metadados locais de autenticação sem ler credenciais nem acessar a rede. ```bash raims auth status [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de status. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. ## `raims completion` Gera o script de autocompletar para o terminal escolhido. ```bash raims completion [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de completion. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Generate the autocompletion script for raims for the specified shell. See each sub-command's help for details on how to use the generated script. ``` Subcomandos: [`raims completion bash`](#raims-completion-bash), [`raims completion fish`](#raims-completion-fish), [`raims completion powershell`](#raims-completion-powershell), [`raims completion setup`](#raims-completion-setup), [`raims completion zsh`](#raims-completion-zsh). ### `raims completion bash` Gera o script de autocompletar para Bash. ```bash raims completion bash ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de bash. * `--no-descriptions` bool padrão: false * Omite as descrições nas sugestões de autocompletar. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Generate the autocompletion script for the bash shell. This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager. To load completions in your current shell session: source <(raims completion bash) To load completions for every new session, execute once: #### Linux: raims completion bash > /etc/bash_completion.d/raims #### macOS: raims completion bash > $(brew --prefix)/etc/bash_completion.d/raims You will need to start a new shell for this setup to take effect. ``` ### `raims completion fish` Gera o script de autocompletar para Fish. ```bash raims completion fish [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de fish. * `--no-descriptions` bool padrão: false * Omite as descrições nas sugestões de autocompletar. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Generate the autocompletion script for the fish shell. To load completions in your current shell session: raims completion fish | source To load completions for every new session, execute once: raims completion fish > ~/.config/fish/completions/raims.fish You will need to start a new shell for this setup to take effect. ``` ### `raims completion powershell` Gera o script de autocompletar para PowerShell. ```bash raims completion powershell [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de powershell. * `--no-descriptions` bool padrão: false * Omite as descrições nas sugestões de autocompletar. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Generate the autocompletion script for powershell. To load completions in your current shell session: raims completion powershell | Out-String | Invoke-Expression To load completions for every new session, add the output of the above command to your powershell profile. ``` ### `raims completion setup` Veja o plano de autocompletar ou salve um novo script. ```bash raims completion setup [flags] ``` * `--dry-run` bool padrão: false * Mostre o plano de autocompletar sem gravar arquivo. * `--help`, `-h` bool padrão: false * Ajuda para setup. * `--save` string padrão: vazio * Salve um novo script no caminho informado sem alterar o perfil do shell. * `--shell` string padrão: auto * Shell do autocompletar: auto, powershell, bash, zsh ou fish. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Detect a supported shell and show completion setup instructions. Use --shell to select one explicitly. Without --save, no file is written. With --save PATH, write a new script generated from the current command tree; the parent directory must exist and the destination must not exist. The command never edits shell profiles or loads the script. --dry-run shows the plan without writing a file. ``` **Exemplo do comando** ```bash raims completion setup raims completion setup --shell powershell --save raims-completion.ps1 --dry-run raims completion setup --shell bash --save raims-completion.bash raims --output json completion setup --shell zsh ``` ### `raims completion zsh` Gera o script de autocompletar para Zsh. ```bash raims completion zsh [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de zsh. * `--no-descriptions` bool padrão: false * Omite as descrições nas sugestões de autocompletar. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Generate the autocompletion script for the zsh shell. If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once: echo "autoload -U compinit; compinit" >> ~/.zshrc To load completions in your current shell session: source <(raims completion zsh) To load completions for every new session, execute once: #### Linux: raims completion zsh > "${fpath[1]}/_raims" #### macOS: raims completion zsh > $(brew --prefix)/share/zsh/site-functions/_raims You will need to start a new shell for this setup to take effect. ``` ## `raims config` Consulta a configuração local do CLI. ```bash raims config [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de config. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims config path`](#raims-config-path). ### `raims config path` Mostra o caminho do arquivo de configuração sem criá-lo. ```bash raims config path [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de path. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. ## `raims docs` Leia a documentação pública da Raims no terminal. ```bash raims docs [PATH] [flags] ``` * `--help`, `-h` bool padrão: false * Ajuda para docs. * `--language` string padrão: br * Idioma da documentação: br ou en. * `--offline` bool padrão: false * Leia somente o cache existente da documentação, inclusive uma cópia antiga. * `--refresh` bool padrão: false * Baixe uma cópia atual da documentação pública em vez de ler o cache. * `--timeout` duration padrão: 1m0s * Prazo da consulta à documentação, como 30s ou 2m. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Read a public Raims documentation page without an API key. Use a path such as cli/configuration or /br/cli/configuration. Without a path, read the CLI guide in the selected language. The public source is cached for 24 hours. --offline reads an existing cache, including an older copy, and reports its age. --refresh downloads a new copy and fails if the download is unavailable. Markdown is printed as plain text; commands and links are not executed. ``` **Exemplo do comando** ```bash raims docs raims docs cli/configuration raims docs /en/cli --language en raims --output json docs cli/automation --offline raims docs search webhooks ``` Subcomandos: [`raims docs search`](#raims-docs-search). ### `raims docs search` Busque na documentação pública da Raims. ```bash raims docs search QUERY... [flags] ``` * `--help`, `-h` bool padrão: false * Ajuda para search. * `--limit` int padrão: 10 * Quantidade máxima de resultados da busca na documentação, de 1 a 50. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--language` string padrão: br * Idioma da documentação: br ou en. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--offline` bool padrão: false * Leia somente o cache existente da documentação, inclusive uma cópia antiga. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. * `--refresh` bool padrão: false * Baixe uma cópia atual da documentação pública em vez de ler o cache. * `--timeout` duration padrão: 1m0s * Prazo da consulta à documentação, como 30s ou 2m. **Descrição detalhada da ajuda do executável** ```text Search public Raims documentation by title, path and content in the selected language. Results include the page URL and a plain text excerpt. Searches ignore case and accents. The search runs locally after reading the public source or its cache; your search terms are not sent to a search service. Use --limit to control how many results are shown. ``` **Exemplo do comando** ```bash raims docs search webhooks raims docs search "chaves de API" --offline raims --output json docs search checkout --language en --limit 5 ``` ## `raims doctor` Verifica a configuração local, as permissões, a instalação e a política de atualização. ```bash raims doctor [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de doctor. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. ## `raims help` Consulta a ajuda de um comando. ```bash raims help [command] [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de help. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Help provides help for any command in the application. Simply type raims help [path to command] for full details. ``` ## `raims licenses` Leia os avisos de terceiros incluídos neste executável. ```bash raims licenses [flags] ``` * `--help`, `-h` bool padrão: false * Ajuda para licenses. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Read the original third-party license, notice and patent texts included in this version. This local command does not require a profile or network access. ``` ## `raims login` Conecte um perfil pelo login no navegador. ```bash raims login [flags] ``` * `--help`, `-h` bool padrão: false * Ajuda para login. * `--no-browser` bool padrão: false * Mostre o endereço de login sem abrir o navegador; mantenha este terminal aberto para receber o retorno local. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Sign in through the Raims browser and authorize the CLI. Choose an environment explicitly. OAuth credentials are encrypted with a key held by the system credential store. Requires an interactive terminal; use API-key profiles in CI. Repeating login verifies and reuses an active authorization, or opens a new consent when it has expired or been revoked. A profile backed by an API key is never overwritten. ``` **Exemplo do comando** ```bash raims login --profile personal --environment sandbox raims login --profile personal --environment sandbox --no-browser ``` ## `raims logout` Revogue uma conexão OAuth e remova seu perfil local. ```bash raims logout [flags] ``` * `--help`, `-h` bool padrão: false * Ajuda para logout. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Revoke the selected OAuth connection, then remove its encrypted credentials and local profile. A failed revocation preserves the local session so you can retry. API-key profiles remain managed by 'profile remove'. ``` ## `raims mcp` Configure um cliente de IA para o MCP da Raims. ```bash raims mcp [flags] ``` * `--help`, `-h` bool padrão: false * Ajuda para mcp. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Show connection instructions and safe configuration snippets for the Raims remote MCP server. Your MCP client handles browser sign-in and consent. This group does not read an API profile, load credentials, contact the server or change an installed client's settings. ``` Subcomandos: [`raims mcp setup`](#raims-mcp-setup). ### `raims mcp setup` Veja as instruções do MCP ou salve um novo snippet de configuração. ```bash raims mcp setup [flags] ``` * `--client` string padrão: all * Cliente MCP: all, codex, claude-code ou cursor. * `--dry-run` bool padrão: false * Valide e apresente o plano de configuração sem gravar arquivo. * `--help`, `-h` bool padrão: false * Ajuda para setup. * `--save` string padrão: vazio * Salve um novo snippet de configuração no caminho informado. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Show setup instructions for Codex, Claude Code or Cursor. OAuth uses the Raims browser sign-in and consent flow. Without --save, no file is written. With --save PATH and one --client, save a new standalone snippet; the destination must not exist and its parent directory must already exist. Merge the snippet into your client settings yourself, preserving other servers. The command never runs another client or edits an existing configuration. --dry-run validates the plan without writing a file. ``` **Exemplo do comando** ```bash raims mcp setup raims mcp setup --client codex raims mcp setup --client cursor --save raims-mcp.json --dry-run raims mcp setup --client claude-code raims --output json mcp setup --client codex ``` ## `raims open` Abra a documentação e páginas do Dashboard da Raims. ```bash raims open [shortcut] [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de open. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Open a known Raims page in the default browser. Without a shortcut, list the available destinations. Non-interactive execution prints the URL without opening a browser. ``` **Exemplo do comando** ```bash raims open docs raims open api raims open webhooks raims --no-input --output json open docs ``` ## `raims profile` Gerencia perfis locais sem armazenar os valores das chaves de API. ```bash raims profile [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de profile. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims profile list`](#raims-profile-list), [`raims profile remove`](#raims-profile-remove), [`raims profile set`](#raims-profile-set), [`raims profile show`](#raims-profile-show), [`raims profile use`](#raims-profile-use). ### `raims profile list` Lista os perfis configurados. ```bash raims profile list [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de list. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. ### `raims profile remove` Remova um perfil local sem revogar sua chave de API. ```bash raims profile remove NAME [flags] ``` * `--help`, `-h` bool padrão: false * Ajuda para remove. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. **Descrição detalhada da ajuda do executável** ```text Remove a named profile from local configuration. If it is the saved default, clear that selection without choosing another profile. The key and its environment variable remain unchanged. Repeating the command succeeds when the profile is already absent. ``` **Exemplo do comando** ```bash raims profile remove old-project raims --output json profile remove old-project ``` ### `raims profile set` Salva um perfil associado ao nome da variável de ambiente da chave de API. ```bash raims profile set NAME --api-key-env VARIABLE [flags] ``` * `--api-key-env` string obrigatório padrão: vazio * Nome da variável de ambiente da chave de API, com letras maiúsculas, dígitos e sublinhado. * `--help`, `-h` bool padrão: false * Exibe a ajuda de set. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. ### `raims profile show` Mostra o perfil informado ou o selecionado quando o nome é omitido. ```bash raims profile show [name] [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de show. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. ### `raims profile use` Seleciona o perfil local padrão. ```bash raims profile use NAME [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de use. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. ## `raims update` Consulta as atualizações automáticas. ```bash raims update [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de update. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. Subcomandos: [`raims update status`](#raims-update-status). ### `raims update status` Mostra a política de atualização automática e as versões instaladas. ```bash raims update status [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de status. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. ## `raims version` Mostra a versão do CLI e os dados do build. ```bash raims version [flags] ``` * `--help`, `-h` bool padrão: false * Exibe a ajuda de version. **Opções globais** * `--color` string padrão: auto * Cores no terminal: auto, on ou off. JSON e scripts de autocompletar continuam sem cores. * `--debug` bool padrão: false * Envia eventos de diagnóstico em JSON para stderr, sem credenciais nem argumentos do comando. * `--environment` string padrão: vazio * Selecione sandbox ou production para OAuth ou uma prévia OAuth; a chave de API define o próprio ambiente. * `--map` string padrão: vazio * Liste a árvore de comandos sem executar uma ação: tree, compact, paths ou json. * `--no-input` bool padrão: false * Desativa perguntas durante a execução; também se aplica em CI e quando não há um terminal. * `--output`, `-o` string padrão: text * Formato da saída: text ou json. * `--profile` string padrão: vazio * Usa um perfil neste comando, com prioridade sobre RAIMS\_PROFILE e o padrão salvo. # Saques (/br/financeiro/saques) Este guia complementa o **Saiba mais** do diálogo **Solicitar saque**. Abra **Meu Dinheiro / Saques** em Produção. A consulta exige **Saques**. Solicitar exige também **Solicitar saques** e **Ver chaves Pix de saque**. Uma conta limitada pode ter os saques bloqueados mesmo quando o usuário possui essas permissões. ## Saldo disponível para saque O diálogo separa três valores: | Item | Tipo | Descrição | | --- | --- | --- | | Saldo disponível | Total apresentado | Pode incluir valores que ainda não estão liberados para retirada. | | Saldo bloqueado | Temporariamente retido | Valores relacionados a disputas, reservas ou outras restrições. | | Disponível para saque | Valor utilizável | É o máximo do saldo que pode participar da solicitação naquele momento. | **Use Disponível para saque como referência** O saldo total da conta pode ser maior que o valor liberado para retirada. ## Chave Pix de destino O saque é enviado para a chave Pix cadastrada em **Conta / Configurações / Chave Pix de saque**. A chave deve pertencer ao mesmo CNPJ da empresa. A Raims confere a titularidade antes de salvar o destino e novamente ao solicitar cada saque. Antes de confirmar, revise a chave mascarada, o banco e o ISPB mostrados no diálogo. Se o destino estiver incorreto, selecione **Alterar chave Pix** e cadastre a chave correta antes de solicitar. ## Limites e tarifa Estas são as condições padrão para saques Pix: | Regra | Valor padrão | | ------------------------------------------------------------------- | -----------: | | Valor mínimo por saque | R$ 2,00 | | Limite diário da conta, das 06:00 às 06:00 do dia seguinte | R$ 50.000,00 | | Limite noturno dentro do diário, das 20:00 às 06:00 do dia seguinte | R$ 10.000,00 | | Tarifa para saques abaixo de R$ 500,00 | R$ 1,00 | Os horários seguem o fuso de São Paulo. O período noturno vai das **20:00 às 06:00 do dia seguinte**. Os saques manuais e automáticos solicitados desde as **06:00** consomem o limite diário. Durante o período noturno, também precisam caber no limite noturno, que faz parte do diário. O limite diário é renovado às **06:00**. Se você sacar R$ 45.000,00 durante o dia, poderá solicitar até R$ 5.000,00 à noite, desde que tenha saldo. Saques em processamento comprometem o limite; uma falha confirmada libera o valor. O diálogo mostra quanto você pode solicitar naquele momento. O valor restante considera os saques registrados na Raims. Uma transferência feita por outro canal na mesma conta pode reduzir o limite aceito pela instituição parceira. Uma condição específica da empresa pode alterar os valores padrão. Nesse caso, o painel apresenta os limites registrados para a conta antes da confirmação. **A tarifa é descontada do valor solicitado** O resultado apresenta separadamente o valor solicitado, a tarifa e o valor líquido enviado à chave Pix. ## Solicitar e acompanhar ### Abra a solicitação Acesse **Meu Dinheiro / Saques / Solicitar saque** e confira a chave Pix de destino. Cadastre uma chave antes se a tela informar que ainda não existe um destino. ### Informe o valor Use **Usar máximo disponível** quando quiser preencher o maior valor permitido naquele momento. ### Confirme o destino, a tarifa e sua identidade Revise os dados apresentados antes de selecionar **Solicitar saque**. Confirme a operação com o método de segurança da sua conta. ### Guarde o identificador A tela mostra o identificador usado para localizar a solicitação. O aceite do pedido ainda não confirma que o dinheiro chegou ao destino. ### Acompanhe o status Consulte a listagem até o saque ser concluído ou apresentar uma falha. Se o resultado estiver em verificação, acompanhe o mesmo identificador antes de solicitar outro saque. ### Pendente A solicitação foi registrada e aguarda processamento. ### Em processamento A transferência ainda está em andamento. O saldo segue reservado enquanto a instituição parceira confirma o resultado. ### Concluído O detalhe apresenta o valor enviado por Pix, a tarifa e a data de conclusão. ### Falha ou cancelamento Abra o detalhe para consultar a orientação apresentada e corrigir o que for necessário antes de uma nova tentativa. ## Consultar os detalhes de um saque 1. Acesse **Meu Dinheiro / Saques** no ambiente em que a solicitação foi feita. 2. Use os filtros de data, identificador, valor ou status para encontrar o saque. 3. Abra o registro e confira destino, valor solicitado, tarifa, valor líquido e estado informado. Acompanhe o mesmo identificador enquanto o resultado estiver em processamento ou em verificação. A mensagem de aceite da solicitação não confirma o crédito na instituição de destino. # Saques automáticos (/br/financeiro/saques-automaticos) O saque automático usa a chave Pix de saque verificada da empresa. A tentativa ocorre no horário configurado quando o saldo disponível alcança o valor mínimo. Essa configuração fica em Produção e exige **Saques**, **Configurar saques** e **Ver chaves Pix de saque**. Use a chave padrão já confirmada em **Conta / Configurações / Chaves Pix de saque**. **Agendamento não garante execução** A rotina só solicita o saque quando existe saldo elegível e a chave Pix continua vinculada ao CNPJ da empresa. Acompanhe o resultado na área Saques; a próxima execução prevista não é comprovante de transferência. **Horário configurado** O saque automático está ativo em Produção e chegou o horário escolhido, no horário de São Paulo. **Conta e chave Pix** A conta está apta para saques, sem limitação. A chave Pix padrão continua verificada e pertence ao mesmo CNPJ da empresa. **Saldo e limite** O saldo elegível alcança o mínimo configurado. O limite Pix restante permite um saque de pelo menos R$ 2,00. **Solicitar o saque** A tentativa usa até o limite restante. Acompanhe o resultado em Saques; a solicitação não confirma a transferência. **Não solicitar nesta tentativa** O saldo permanece na conta. Confira a configuração, a conta, a chave Pix, o saldo e o limite antes de aguardar outra tentativa. ## Configurar ### Abra as configurações de saques Acesse **Conta / Configurações / Saques** e selecione **Editar**. ### Ative o saque automático Cadastre antes uma chave Pix de saque em nome do mesmo CNPJ da empresa. Ao salvar a ativação ou alterar valor e horário enquanto o saque estiver ativo, confirme a ação com o método de segurança da sua conta. O controle pode ficar indisponível para usuários sem permissão ou quando a empresa está limitada. ### Defina o valor mínimo O painel aceita valores entre **R$ 2,00** e **R$ 1.000.000,00**. A tentativa é ignorada quando o saldo elegível não alcança o mínimo. A tentativa também é ignorada quando o limite Pix restante é inferior ao mínimo por saque de R$ 2,00. Cada tentativa solicita até o limite Pix disponível naquele horário. Se houver saldo maior, o restante fica na conta para as próximas tentativas. ### Escolha o horário Escolha o horário da tentativa diária, no formato de 24 horas. Você pode escolher um horário diurno ou noturno; os limites Pix aplicados dependem do horário da tentativa. O Dashboard usa o fuso de São Paulo e apresenta a próxima execução prevista depois que a configuração é salva. ## Como o valor é tratado O período noturno começa às **20:00** e termina às **06:00 do dia seguinte**, no horário de São Paulo. Nesse intervalo, o saque precisa caber tanto no limite noturno quanto no restante do limite diário. | Limite | Período no horário de São Paulo | Valor padrão | | ------------------------------------ | ---------------------------------- | -----------: | | Diário, incluindo os saques noturnos | Das 06:00 às 06:00 do dia seguinte | R$ 50.000,00 | | Noturno, dentro do limite diário | Das 20:00 às 06:00 do dia seguinte | R$ 10.000,00 | O limite diário é renovado às **06:00**, quando começa o período diurno. Os saques manuais e automáticos da conta consomem o mesmo limite. Por exemplo, se já foram usados R$ 45.000,00 no ciclo diário, restam até R$ 5.000,00 para sacar à noite, desde que haja saldo disponível. Esses são os valores padrão. Uma condição específica da empresa pode alterar os limites da conta; a tentativa usa os valores aplicáveis naquele momento. | Item | Tipo | Descrição | | --- | --- | --- | | Abaixo do mínimo | Não executa | O saldo permanece na conta para uma tentativa futura. | | Entre o mínimo e R$ 499,99 | Tarifa de R$ 1,00 | A mesma regra de tarifa informada para saques abaixo de R$ 500,00 é aplicada. | | A partir de R$ 500,00 | Sem a tarifa inferior | A dedução de R$ 1,00 indicada para valores abaixo do limite não se aplica. | | Conta limitada | Temporariamente desativado | Saques manuais e automáticos permanecem bloqueados enquanto durar a limitação. | ## Operação segura ### A próxima execução não apareceu Confirme que a configuração foi salva, que o controle está ativado e que a conta não está limitada. Recarregue a seção para ler o estado confirmado. ### O horário passou e não houve saque Verifique saldo elegível, valor mínimo, chave Pix de saque e histórico de saques. O agendamento pode ser ignorado quando uma condição não é atendida. ### Preciso desativar temporariamente Edite a configuração, desligue o controle e salve. Confirme que a interface passou a mostrar **Saque automático desativado**. - [Saques](/br/financeiro/saques): Acompanhe as solicitações geradas e os estados finais. # Aplicativos autorizados (/br/integracoes/aplicativos) A área **Integração / Aplicativos autorizados** reúne os aplicativos que receberam acesso à sua conta pelo fluxo de autorização da Raims. A mesma autorização atende clientes [MCP](/br/integracoes/mcp) e outros aplicativos compatíveis, incluindo integrações de plataformas e serviços. Cada conexão identifica o aplicativo, quem autorizou o acesso, os ambientes e as permissões concedidas. O aplicativo continua sujeito às permissões atuais de quem o autorizou e às regras da conta. A coluna **Autorizado por** mostra o identificador de quem concedeu o acesso. Confira esse identificador para distinguir conexões do mesmo aplicativo. Instalar um aplicativo em outra plataforma e autorizar o acesso à Raims são etapas distintas. Conclua o fluxo apresentado pelo aplicativo e confira a conta na página da Raims antes de conceder acesso. ## Autorizar um aplicativo 1. No aplicativo compatível, inicie a conexão com a Raims. 2. Conclua o login na página da Raims aberta no navegador. 3. Confira o aplicativo e defina seus acessos em **Permissões**. 4. Selecione **Revisar** para conferir o aplicativo, a conta, os ambientes, o destino de retorno e as permissões. 5. Escolha **Autorizar acesso** e conclua a confirmação de segurança quando solicitada. 6. Volte ao aplicativo para continuar. O login mantém os controles da conta, incluindo MFA quando solicitado. Sua senha da Raims não precisa ser compartilhada com o aplicativo. A conexão usa OAuth e dispensa criar ou informar uma chave de API para o aplicativo. O nome e o ícone ajudam a identificar quem solicita o acesso, mas não são um selo de verificação ou parceria. Se não reconhecer o pedido ou não quiser conceder as permissões, feche a página sem autorizar. ## Permissões e ambientes Cada operação tem uma seleção própria. Permitir criar uma cobrança não concede consulta, edição, revogação nem estorno. Os grupos organizam a matriz; não substituem a escolha individual das operações. Os perfis sugeridos preenchem uma seleção que você pode revisar antes de autorizar. Use **Saiba mais** abaixo de uma operação para conferir o que ela permite, seus efeitos e os ambientes aceitos. O cadastro de cliente por CPF/CNPJ, por exemplo, pode atualizar um cliente existente com o mesmo documento. Uma nova conexão inclui os ambientes permitidos à conta e ao seu acesso. As permissões selecionadas valem para esses ambientes. Trocar o ambiente do Dashboard não muda o alcance de uma conexão existente. Renovar a autorização também não amplia suas permissões ou seus ambientes. A edição permite restaurar acessos que já faziam parte da autorização original; outros acessos exigem uma nova conexão iniciada pelo aplicativo. O consentimento autoriza a conexão uma vez. As operações concedidas podem ser executadas sem outra tela de aprovação para cada tarefa, sempre sujeitas às permissões atuais, aos limites e às validações da Raims. Se os acessos ou os ambientes mudarem durante a conexão, confira novamente o resumo antes de concluir. A autorização não é repetida automaticamente. ## Consultar os acessos Abra **Integração / Aplicativos autorizados** para consultar os aplicativos, o responsável pela autorização, os ambientes e a validade. Cada membro pode consultar as próprias conexões. **Ver aplicativos da empresa** amplia a lista para as conexões do titular e da equipe. **Revogar conexões da equipe** também permite essa consulta e a revogação de conexões de outros funcionários, sem permitir revogar as do titular. Para conferir as permissões de uma conexão, abra **Editar permissões** no menu de ações, quando disponível. Abrir o editor, pesquisar e expandir os grupos não altera os acessos. A linha do aplicativo permanece destacada enquanto o editor estiver aberto. Consultar as conexões da empresa não permite editar ou revogar acessos de outras pessoas. As permissões de sessões e dispositivos não concedem gestão de aplicativos. Esses acessos precisam ser concedidos por um administrador autorizado, sem alteração automática das permissões dos membros existentes. As [chaves de API](/br/integracoes/chaves-api) têm sua própria gestão em **Integração / Chaves de API**. ## Editar permissões No menu da conexão, selecione **Editar permissões**, quando disponível. Use **Pesquisar por permissão...** para localizar os acessos. Escolha um dos **Perfis sugeridos** ou expanda os grupos para ajustar as permissões individualmente. Selecione **Salvar alterações** e conclua a confirmação de segurança. Os perfis exibidos dependem dos acessos já autorizados para o aplicativo. O indicador **Perfil atual** acompanha a seleção, e cada grupo informa quantas permissões estão selecionadas. A busca filtra a apresentação sem alterar a seleção. Confira os grupos antes de salvar. Cada item informa o nome e uma descrição da operação. O link **Saiba mais** abre sua explicação completa nesta documentação sem alterar a seleção. Quem autorizou a conexão e o titular da conta podem editar os acessos, respeitando as permissões atuais de ambos. A permissão para consultar ou revogar conexões da equipe não libera sua edição automaticamente. A edição permite remover e restaurar permissões da autorização original. Um acesso que deixou de estar disponível pode ser mantido ou removido, mas só pode ser restaurado quando estiver disponível novamente. A seleção não substitui as permissões atuais. Para conceder outros acessos, inicie uma nova conexão pelo aplicativo. Os ambientes, a validade e a credencial são preservados. A remoção impede o uso da permissão nas chamadas seguintes, sem desfazer operações concluídas nem apagar dados que o aplicativo já recebeu. Se outra alteração tornar a edição desatualizada, use **Descartar alterações e recarregar** e confira os acessos antes de salvar novamente. Uma falha ao salvar mantém sua seleção para que você possa conferir a mensagem e tentar de novo. ## Revogar uma conexão 1. Localize o aplicativo em **Aplicativos autorizados** e confira o identificador em **Autorizado por** e os ambientes. 2. No menu de ações, selecione **Revogar acesso**. 3. Confira o aplicativo e o identificador de quem autorizou na confirmação e conclua a ação. A revogação impede novas chamadas autorizadas pela conexão. Ela não desfaz operações concluídas nem apaga dados que o aplicativo externo já recebeu. Sair do Dashboard não substitui a revogação. Para voltar a usar um aplicativo revogado, inicie uma nova conexão nele e revise as permissões novamente. ## Acompanhar atividades Abra **Conta / Registro de Atividades** para acompanhar autorizações aceitas ou recusadas, alterações de permissões, revogações e expirações. Uma revogação de segurança por reutilização de credencial também aparece no histórico. Os eventos automáticos são identificados como **Sistema**. Cada membro consulta as próprias atividades. **Ver auditoria completa** permite consultar as atividades de toda a empresa. As ações registradas de um funcionário por um aplicativo preservam sua identificação no histórico. Consultar a conexão ou abrir o editor sem salvar não representa uma mudança de permissões. ## Quando a conexão não puder ser concluída * Se a solicitação expirou, já foi usada ou não está mais disponível, volte ao aplicativo e inicie outra conexão. Reabrir o mesmo link não renova o pedido. * Se uma falha temporária impedir a consulta do pedido, aguarde as tentativas automáticas da página. Somente a consulta é repetida; autorizar continua exigindo sua confirmação. * Se o acesso for negado, confira a conta e suas permissões atuais. * Se o aplicativo pedir autenticação novamente, inicie a conexão e confira o consentimento apresentado pela Raims. * Se o resultado de uma operação ficar incerto, consulte o recurso antes de solicitar outra criação. ## Operações da autorização As operações abaixo podem ser selecionadas individualmente quando estiverem disponíveis para a conta e para quem autoriza. A conexão só permite as que fazem parte do consentimento, e a edição não acrescenta operações fora da autorização original. Escolher um ambiente não dispensa essa autorização. A descrição mantém as regras da operação pública; a conexão OAuth fornece a credencial para a chamada. Você não precisa criar ou informar uma chave de API. | Item | Descrição | | --- | --- | | Recuperar número de conta | Consulte a agência e o número da conta financeira da sua empresa na Raims. A consulta exige acesso ao ambiente de Produção e uma conta aprovada e habilitada. Ambientes autorizáveis: Produção. | | Consultar personalização do checkout | Consulte as imagens, as cores, o e-mail de suporte e os meios de pagamento padrão do checkout da empresa no ambiente autenticado. Ambientes autorizáveis: Sandbox e Produção. | | Atualizar personalização do checkout | Altere as imagens, as cores e o e-mail de suporte do checkout. Campos omitidos preservam o valor atual. O envio de uma nova imagem pode exigir acompanhamento até sua aplicação. Ambientes autorizáveis: Sandbox e Produção. | | Preparar envio do ícone | Obtenha uma URL temporária para enviar a imagem. Depois do envio dos bytes, associe o ID retornado à personalização do checkout. A preparação não altera a imagem atual. Ambientes autorizáveis: Sandbox e Produção. | | Preparar envio da logo | Obtenha uma URL temporária para enviar a imagem. Depois do envio dos bytes, associe o ID retornado à personalização do checkout. A preparação não altera a imagem atual. Ambientes autorizáveis: Sandbox e Produção. | | Descartar envio de imagem | Descarte um envio de logo ou ícone que ainda não foi associado ao checkout. Um envio expirado também pode ser descartado. Para remover uma imagem já aplicada, use o PATCH da personalização. Ambientes autorizáveis: Sandbox e Produção. | | Consultar contexto da conta | Consulte a identidade pública, o nome empresarial, a situação cadastral e o ambiente da conta identificada pela chave. Use a data e a revisão da resposta para reconhecer informações antigas. Esta leitura não identifica a pessoa que criou a chave e não confirma que uma operação financeira pode ser executada. Ambientes autorizáveis: Sandbox e Produção. | | Consultar tarifas da conta | Consulte as condições comerciais vigentes da sua empresa para recebimentos por Pix e boleto. Ambientes autorizáveis: Sandbox e Produção. | | Recuperar saldo atual | Consulta os valores total, bloqueado e disponível na empresa e no ambiente autenticado. Os valores são expressos em centavos de real. O saldo disponível considera os bloqueios e não confirma a autorização de um saque ou estorno. Ambientes autorizáveis: Sandbox e Produção. | | Consultar recebimentos previstos | Consulte a estimativa de recebimentos pendentes no período e o saldo total projetado. Os valores são estimativas e não indicam disponibilidade para saque. Ambientes autorizáveis: Sandbox e Produção. | | Listar cobranças | Lista cobranças da empresa e do ambiente autenticado, com filtros e paginação por cursor. Para avançar, use page.next_after em after enquanto page.has_next for true, mantendo os filtros e a ordenação. Alterações de status podem levar alguns segundos para aparecer nos filtros; aguarde antes de consultar novamente. Ambientes autorizáveis: Sandbox e Produção. | | Criar nova cobrança | Cria uma cobrança para um cliente já cadastrado. Informe o valor em centavos. Sem lista própria de meios, payment_method 1 solicita Pix e 2 solicita boleto, com os dados disponíveis em payment_information. Boleto usa nome, e-mail válido, CPF/CNPJ e endereço do cliente. Logradouro, bairro, cidade e UF ausentes podem ser preenchidos a partir do CEP quando disponíveis; número e complemento vêm do cadastro. Com lista própria, a emissão ocorre após a escolha no checkout. Use create_checkout true para obter o link sem solicitar e-mail. Uma URL de retorno ou send_email true também gera o link; somente send_email true solicita envio de e-mail. Ambientes autorizáveis: Sandbox e Produção. | | Revogar cobrança | Revoga uma cobrança em aberto da empresa e do ambiente autenticado, preservando seu histórico. No Sandbox, o cancelamento é simulado. Em Produção, a revogação pode aguardar confirmação. Ambientes autorizáveis: Sandbox e Produção. | | Recuperar uma única cobrança | Consulta os dados, o status e as instruções de pagamento disponíveis de uma cobrança da empresa e do ambiente autenticado. Ambientes autorizáveis: Sandbox e Produção. | | Atualizar cobrança existente | Atualiza título, descrição, referência externa e dados de integração de uma cobrança da empresa e do ambiente autenticado. Você pode alterar somente metadata mesmo após o pagamento ou estorno. Alterações nos demais campos continuam sujeitas ao estado da cobrança; se algum campo não puder ser alterado, nenhuma mudança da requisição será aplicada. Ambientes autorizáveis: Sandbox e Produção. | | Baixar boleto | Obtenha uma URL temporária para baixar o PDF de um boleto já emitido, inclusive antes do pagamento. A consulta exige autorização para a mesma empresa e ambiente e não emite nem renova o boleto. O documento não comprova pagamento. No Sandbox, o PDF identifica a simulação e não deve ser usado para pagar. Ambientes autorizáveis: Sandbox e Produção. | | Consultar dados do pagamento | Consulte o valor, a data e o meio de pagamento confirmado de uma cobrança. Nos recebimentos Pix, end_to_end_id informa o identificador bancário quando disponível. A cobrança precisa estar paga, parcialmente estornada ou com contestação ganha, com a data do pagamento registrada. A consulta considera a empresa e o ambiente autenticado. Ambientes autorizáveis: Sandbox e Produção. | | Baixar recibo de pagamento | Obtenha uma URL temporária para baixar o recibo de um pagamento confirmado em PDF. A cobrança precisa estar paga, parcialmente estornada ou com contestação ganha, com a data do pagamento registrada. O recibo informa o valor original da cobrança paga; devoluções têm comprovantes próprios. O documento é emitido pela Raims e não substitui nota fiscal nem comprovante bancário. A requisição usa a empresa e o ambiente autorizados para a conexão. Ambientes autorizáveis: Sandbox e Produção. | | Consultar elegibilidade para estorno | Consulta se uma cobrança aceita um pedido de devolução, o valor restante, o máximo disponível para solicitar agora e os valores pendentes. As condições são conferidas novamente ao solicitar o estorno. Ambientes autorizáveis: Sandbox e Produção. | | Listar estornos de uma cobrança | Lista as solicitações de estorno de uma cobrança, das mais recentes para as mais antigas, com paginação por cursor. A consulta não inicia nem repete devoluções. Ambientes autorizáveis: Sandbox e Produção. | | Solicitar estorno | Solicita a devolução integral ou parcial de um pagamento Pix recebido. Em Produção, o valor retorna à conta de origem e uma solicitação aceita ainda precisa de confirmação. No Sandbox, a simulação conclui na própria requisição, sem movimentar dinheiro real. Ambientes autorizáveis: Sandbox e Produção. | | Consultar estatísticas de cobranças | Consulte quantidades, valores e taxa de pagamento das cobranças para acompanhar seus recebimentos no ERP ou sistema de gestão. A consulta considera a empresa e o ambiente autenticado. Os dados podem levar alguns segundos para refletir alterações nas cobranças. Ambientes autorizáveis: Sandbox e Produção. | | Remover clientes em lote | Remove até 100 clientes da empresa e do ambiente autenticado em uma requisição. Confira o resultado de cada identificador em removed, blocked ou invalid. Cobranças não removidas impedem a remoção do cliente, inclusive quando pagas. Identificadores repetidos são processados uma vez; clientes já removidos aparecem em removed. A remoção de clientes não remove cobranças nem devolve valores. Ambientes autorizáveis: Sandbox e Produção. | | Listar clientes | Lista os clientes da empresa e do ambiente autenticado conforme os filtros informados, com paginação por cursor. Envie os parâmetros na URL, sem corpo na requisição. Ambientes autorizáveis: Sandbox e Produção. | | Criar cliente | Cria um cliente na empresa e no ambiente autenticado. Se o CPF ou CNPJ já estiver cadastrado, atualiza esse cliente e mantém seu identificador. Ao informar somente o CEP como endereço, logradouro, bairro, cidade e UF podem ser preenchidos automaticamente. Retorna 201 ao criar e 200 ao atualizar. Ambientes autorizáveis: Sandbox e Produção. | | Remover cliente | Remove um cliente pelo identificador público na empresa e no ambiente autenticado. A remoção é permitida somente quando não há cobranças vinculadas ainda não removidas, inclusive pagas. Não remove cobranças nem devolve valores. Repetir a requisição para o mesmo cadastro já removido retorna o mesmo identificador com deleted: true. A requisição não tem corpo. Ambientes autorizáveis: Sandbox e Produção. | | Recuperar um único cliente | Consulta os dados cadastrais de um cliente pelo identificador público na empresa e no ambiente autenticado. A requisição não tem corpo. Ambientes autorizáveis: Sandbox e Produção. | | Atualizar cliente existente | Atualiza os campos enviados do cadastro e os dados de integração do cliente. Campos omitidos mantêm o valor atual. Nos campos de texto, null ou texto vazio limpam o conteúdo; metadata possui as regras indicadas no campo. CPF/CNPJ, identificador e data de criação permanecem iguais. O CEP não preenche outros campos de endereço nesta requisição. Enviar {} retorna o cadastro atual. Ambientes autorizáveis: Sandbox e Produção. | | Listar contestações | Consulta as contestações da empresa e do ambiente autenticado, com filtros e paginação por cursor. Ambientes autorizáveis: Sandbox e Produção. | | Recuperar uma contestação | Consulta a etapa, os motivos e os resultados disponíveis de uma contestação da empresa e do ambiente autenticado. Ambientes autorizáveis: Sandbox e Produção. | | Listar links de pagamento | Lista os links da empresa e do ambiente autenticado, pela ordem decrescente das cobranças vinculadas. Use charge_id para localizar o link de uma cobrança e page.next_after para continuar. Ambientes autorizáveis: Sandbox e Produção. | | Criar ou recuperar um link de pagamento | Cria o link de uma cobrança existente ou retorna o mesmo link quando ele já existe. Informe charge_id. Um link novo começa ativo; reutilizar um link pausado preserva a pausa. Título, valor, vencimento e cliente vêm da cobrança. Esta requisição não cria outra cobrança, não emite pagamentos e não solicita e-mail. Ambientes autorizáveis: Sandbox e Produção. | | Recuperar um link de pagamento | Consulta a URL, a configuração e a disponibilidade atual do link. is_active informa se o link está ativo; is_payable indica se o checkout pode receber pagamento neste momento. O link precisa pertencer à empresa e ao ambiente autenticado. Para valor, vencimento, cliente e status financeiro, use GET /v1/charges/{charge_id}. Ambientes autorizáveis: Sandbox e Produção. | | Atualizar um link de pagamento | Atualiza as URLs de retorno, os meios de pagamento e a pausa do link. Envie is_active false para pausar e true para reativar a mesma URL; omitir preserva o estado. A pausa bloqueia novas ações no checkout e novos pedidos de envio por e-mail, sem cancelar Pix ou boleto emitidos nem prorrogar o vencimento. A cobrança precisa estar aberta e dentro do vencimento. Use clear_success_redirect_url ou clear_cancel_redirect_url com true para remover o respectivo destino. Ambientes autorizáveis: Sandbox e Produção. | | Enviar link por e-mail | Solicita o envio ou reenvio do link ao destinatário da cobrança, sem criar outra cobrança ou alterar o checkout. A cobrança precisa estar aberta e dentro do vencimento. O intervalo mínimo de 60 segundos entre solicitações aceitas é compartilhado com a ação de reenvio do Dashboard. A resposta confirma o pedido de envio, não a entrega do e-mail. Sandbox também pode enviar e-mails reais. O link precisa estar ativo; a pausa impede o envio. Ambientes autorizáveis: Sandbox e Produção. | | Listar estornos | Lista as solicitações de estorno das cobranças da empresa e do ambiente autenticado, das mais recentes para as mais antigas. Use a paginação para conciliar as devoluções sem consultar cada cobrança. A consulta não inicia nem repete estornos. Ambientes autorizáveis: Sandbox e Produção. | | Recuperar um estorno | Consulta o estado, o valor, as datas e o motivo disponível de uma falha confirmada no estorno. A consulta não inicia nem repete a devolução. Ambientes autorizáveis: Sandbox e Produção. | | Baixar comprovante de estorno | Obtenha uma URL temporária para baixar o comprovante em PDF de um estorno concluído. O documento informa o ID, o valor e a data de conclusão desse estorno. Para cobranças com mais de uma devolução, consulte cada ID desejado. A solicitação precisa estar em completed, com a data de conclusão registrada. A requisição usa a empresa e o ambiente autorizados para a conexão. O documento é emitido pela Raims e não substitui nota fiscal nem comprovante bancário. Ambientes autorizáveis: Sandbox e Produção. | | Simular compensação de boleto | Registre um boleto como compensado, ainda aguardando liquidação. Esta etapa não credita o saldo nem disponibiliza recibo de pagamento concluído. Ambientes autorizáveis: Sandbox. | | Confirmar pagamento | Confirme o pagamento de uma cobrança de teste e confira o crédito no saldo do Sandbox. Ambientes autorizáveis: Sandbox. | | Simular falha no pagamento | Simule a falha de uma cobrança aberta para testar o tratamento desse resultado no Sandbox. Ambientes autorizáveis: Sandbox. | | Emitir pagamento de teste | Emita Pix ou boleto de uma cobrança existente no Sandbox. Um cenário preparado para essa emissão define se ela ficará pendente ou apresentará falha. Ambientes autorizáveis: Sandbox. | | Simular estorno pendente | Inicie uma devolução Pix de teste que aguarda confirmação. Use o ID retornado para concluir o estorno ou simular uma falha. Ambientes autorizáveis: Sandbox. | | Resolver cenário pendente | Conclua ou falhe uma emissão ou um cancelamento que ficou pendente no cenário de teste. A ação precisa ter sido iniciada sobre a cobrança. Ambientes autorizáveis: Sandbox. | | Preparar cenário | Escolha uma pendência ou falha para a emissão de Pix ou boleto, ou para o cancelamento de uma cobrança no Sandbox. Depois, execute a ação sobre a mesma cobrança. Ambientes autorizáveis: Sandbox. | | Concluir estorno simulado | Conclua um estorno Pix pendente no Sandbox. O valor não é descontado novamente do saldo. Ambientes autorizáveis: Sandbox. | | Simular falha no estorno | Simule a falha de um estorno Pix pendente no Sandbox e confira a devolução do valor ao saldo disponível. Ambientes autorizáveis: Sandbox. | | Recuperar extrato | Consulte os lançamentos do extrato da empresa e do ambiente autenticado. Filtre por período, tipo de lançamento ou referência e percorra os resultados com os cursores retornados. Valores positivos representam entradas ou liberações; valores negativos representam saídas, tarifas ou bloqueios. Uma confirmação financeira pode levar alguns instantes para aparecer no extrato. Ambientes autorizáveis: Sandbox e Produção. | | Recuperar um lançamento | Consulta um lançamento do extrato pelo ID, com seus valores e vínculos disponíveis, na empresa e no ambiente autenticado. Ambientes autorizáveis: Sandbox e Produção. | | Listar os eventos disponíveis | Consulte os códigos que podem ser selecionados ao cadastrar ou atualizar um webhook. O teste técnico webhook.test é solicitado no endpoint de teste e não entra na lista de eventos do cadastro. Ambientes autorizáveis: Sandbox e Produção. | | Listar webhooks | Consulte os destinos cadastrados na empresa e no ambiente autenticado, incluindo os desativados. Para avançar, copie page.next_after para after. A listagem não retorna segredos de assinatura. Ambientes autorizáveis: Sandbox e Produção. | | Criar um webhook | Cadastre o endereço HTTPS que receberá os eventos escolhidos da empresa e do ambiente autenticado. Guarde o id para administrar o destino e o secret_key para validar as assinaturas. As consultas do cadastro não retornam o segredo. Ambientes autorizáveis: Sandbox e Produção. | | Excluir um webhook | Exclua um destino que não será mais usado. A exclusão impede novos envios, mas uma requisição já autorizada ou em andamento pode terminar. O histórico disponível continua consultável, inclusive pelo webhook_id excluído. Ambientes autorizáveis: Sandbox e Produção. | | Recuperar um webhook | Consulte a URL, os eventos assinados e a situação de um webhook. O segredo de assinatura não é retornado nesta consulta. Ambientes autorizáveis: Sandbox e Produção. | | Atualizar um webhook | Altere o nome, a URL, a seleção de eventos ou a ativação de um webhook. Envie apenas os campos que deseja mudar; omitir um campo preserva seu valor. A seleção de eventos enviada substitui a anterior. Os campos não aceitam null nem valores vazios. Ambientes autorizáveis: Sandbox e Produção. | | Consultar as falhas de um webhook | Consulte a situação conhecida do destino e há quanto tempo suas entregas estão falhando. Os dados refletem os resultados de envio disponíveis e podem levar um tempo para aparecer após uma tentativa. A consulta não faz uma chamada ao destino. O estado healthy indica um sucesso conhecido; não garante que o endereço continua disponível. O estado unknown indica que ainda não há dados suficientes para informar a situação. Ambientes autorizáveis: Sandbox e Produção. | | Pausar ou retomar envios | Pausa os envios de um webhook ativo sem desativá-lo. Eventos novos e entregas pendentes aguardam a retomada enquanto estiverem dentro de seu prazo original. A pausa não amplia esse prazo: 72 horas em Produção e 4 horas no Sandbox. Envie is_paused false para retomar as entregas ainda válidas. A retomada respeita os limites de envio, sem garantir ordem ou horário. O envio explícito de um evento de teste continua disponível durante a pausa. Ambientes autorizáveis: Sandbox e Produção. | | Rotacionar o segredo de assinatura | Substitua o segredo usado para assinar os eventos, preservando o identificador e a configuração do webhook. Guarde o secret_key retornado e atualize o receptor durante o período de transição. Repetir uma rotação com período positivo enquanto a transição está ativa retorna o mesmo segredo e o mesmo vencimento. Para revogar os segredos anteriores, envie grace_period_seconds igual a zero: uma nova assinatura será gerada, inclusive durante uma transição ativa. Requisições já autorizadas ou em andamento podem chegar com a assinatura anterior. Ambientes autorizáveis: Sandbox e Produção. | | Enviar um evento de teste | Envie webhook.test para conferir o recebimento e a validação da assinatura de um webhook ativo. A requisição não recebe corpo. O teste faz uma tentativa HTTP em até cinco minutos e não altera cobranças, saldo ou a contagem de falhas do destino. O aceite do pedido não confirma a entrega. Confira o recebimento nos registros do receptor. Ambientes autorizáveis: Sandbox e Produção. | | Listar destinos de saque | Consulte os destinos Pix próprios verificados e identifique o padrão antes de solicitar um saque. A consulta exige acesso ao ambiente de Produção. Ambientes autorizáveis: Produção. | | Recuperar um destino de saque | Consulte um destino Pix próprio pelo identificador recebido na listagem. A resposta apresenta a chave mascarada e informa se ela é o padrão atual. Use o ambiente de Produção. Ambientes autorizáveis: Produção. | | Listar saques | Consulte o histórico de saques da sua empresa. Use os filtros de status e período para acompanhar as transferências e conferir as saídas do extrato. A consulta considera o ambiente autenticado. Ambientes autorizáveis: Sandbox e Produção. | | Solicitar saque | Solicite um saque Pix para a chave padrão da própria empresa cadastrada no Dashboard. O valor solicitado inclui a tarifa. Para exigir o destino padrão que você conferiu, informe expected_destination_id. Guarde o identificador e acompanhe o mesmo saque enquanto o resultado estiver pendente. Ambientes autorizáveis: Produção. | | Recuperar um saque | Consulte o status, os valores e o destino de um saque pelo identificador. Use o mesmo ID que aparece no histórico de saques ou na referência do extrato. Ambientes autorizáveis: Sandbox e Produção. | | Consultar saque automático | Consulte a ativação, o valor mínimo, o horário diário e a próxima tentativa prevista de saque da empresa. A consulta exige acesso ao ambiente de Produção. Ambientes autorizáveis: Produção. | | Atualizar saque automático | Ative, desative ou ajuste a tentativa diária de saque para o destino próprio selecionado. Use o ambiente de Produção. Campos omitidos preservam o valor atual; salvar não solicita um saque imediato. Ambientes autorizáveis: Produção. | | Consultar condições de saque | Consulte saldo disponível, mínimo, tarifa e limites de saque para planejar uma retirada. A consulta não reserva dinheiro nem limite e não garante que uma solicitação será aceita. Ambientes autorizáveis: Sandbox e Produção. | | Consultar saques em processamento | Consulte a quantidade e o valor total dos saques pendentes ou em processamento da empresa. A consulta exige acesso ao ambiente de Produção e não altera o andamento dos pedidos. Ambientes autorizáveis: Produção. | # Autenticação (/br/integracoes/autenticacao) A API da Raims aceita chaves de API e acesso OAuth de aplicativos autorizados. Use uma chave de API no backend da sua integração. Para trabalhar no terminal, você também pode conectar o Raims CLI pelo navegador. Os dois modos usam o header `Authorization` com o esquema **Bearer**. A credencial e o acesso atual determinam quais requisições podem ser executadas. ## Antes de começar Crie uma chave de API para o ambiente que sua aplicação vai utilizar. Consulte [Chaves de API](/br/integracoes/chaves-api) para obter e gerenciar a credencial. Para integrar com um cliente da sua linguagem, consulte os [SDKs oficiais](/br/integracoes/sdks). Cada guia informa o canal de instalação e mostra como configurar a credencial no backend. Armazene o segredo em um cofre de segredos ou em uma variável de ambiente protegida, acessível somente ao backend responsável pela integração. **Proteja sua chave de API** Não exponha a chave em aplicações frontend, aplicativos distribuídos, imagens, logs ou repositórios. Envie o segredo somente no header de autenticação, nunca na URL ou no corpo da requisição. ## OAuth no CLI Execute `raims login --profile pessoal --environment sandbox` e conclua a autorização no navegador. Confira a conta, os ambientes e as permissões antes de autorizar. O CLI protege a sessão no sistema operacional e renova o acesso enquanto a conexão permanecer válida. Consulte [Configuração e perfis](/br/cli/configuration#conectar-pelo-navegador). As chamadas OAuth usam um access token emitido para a API pública e informam `X-Raims-Environment` com `Sandbox` ou `Production`. O CLI preenche esse header a partir do ambiente escolhido. Selecionar um ambiente não concede acesso a ele: o ambiente e a requisição precisam estar autorizados para a conexão e para quem a aprovou. O token de uma conexão MCP não autentica chamadas diretas à API pública. Cada conexão usa o acesso emitido para seu destino. Para encerrar o acesso OAuth do CLI, execute `raims logout --profile pessoal`. ## Header de autenticação Ao usar uma chave de API, configure o cliente HTTP do seu backend com os seguintes headers ao enviar um corpo JSON: ```json { "Authorization": "Bearer SUA_CHAVE_API", "Content-Type": "application/json" } ``` | Header | Uso | | --------------- | ------------------------------------------------------------------------------------------------ | | `Authorization` | Obrigatório nas requisições autenticadas. Use `Bearer` seguido de um espaço e da chave completa. | | `Content-Type` | Envie `application/json` quando a requisição tiver corpo JSON. | Requisições `GET` devem usar os parâmetros definidos pelo endpoint e ser enviadas sem corpo. O identificador da chave, uma máscara do segredo ou uma credencial de acesso ao Dashboard não substituem a chave de API. Use HTTPS para as chamadas à API. O segredo deve ser enviado exatamente como foi gerado, sem modificar letras ou acrescentar caracteres. ## Sandbox e Produção A URL base é a mesma nos dois ambientes: ```text https://api.raims.com ``` Com chave de API, o ambiente e a empresa são definidos pela chave enviada no header `Authorization`. Não envie outro header nem um campo na URL ou no corpo para escolher o ambiente. `X-Raims-Environment` é usado somente com OAuth; enviá-lo com uma chave de API não altera o ambiente da requisição. | Ambiente | Prefixo da chave | Uso | | -------- | ---------------- | ---------------------------------------------------------------------------------- | | Sandbox | `sk_test_` | Desenvolvimento e homologação, com dados de teste separados dos dados de Produção. | | Produção | `sk_live_` | Requisições com efeitos reais na conta, enviadas pelo seu backend. | Valide a integração no Sandbox antes de usar Produção. Para mudar de ambiente, atualize a chave configurada no seu backend e confira os dados e os identificadores enviados. Um recurso criado em Sandbox não passa a pertencer à Produção pela troca da credencial. ## Permissões da chave Uma chave de API precisa ter a ação solicitada entre suas permissões. Consultar, criar, editar, remover e outras ações são selecionadas separadamente. Por exemplo, permitir criar cobranças não permite revogá-las nem solicitar estornos. As regras da empresa e do ambiente continuam valendo. `403 API_KEY_PERMISSION_DENIED` indica que a chave não autoriza a operação. Peça a uma pessoa com **Editar chaves de API** para revisar os acessos em **Integração / Chaves de API / Editar permissões**. Reenviar a mesma chamada ou trocar o header de ambiente não amplia as permissões. Consulte [Permissões da chave](/br/integracoes/chaves-api#permissões-da-chave) para configurar o acesso da integração. ## Restrições de IP Se a chave tiver restrições de IP, as requisições precisam sair de um endereço autorizado. Configure o IP público de saída do servidor ou da infraestrutura que executa seu backend, considerando também as faixas autorizadas quando utilizar CIDR. Consulte [Restrições de IP](/br/integracoes/chaves-api#restrições-de-ip) para configurar as faixas permitidas. ## Erros de autenticação Uma resposta `401 Unauthorized` indica que a requisição não pôde ser autenticada. Confira: * se `Authorization` contém `Bearer`, um espaço e a chave completa; * se a chave está correta, sem caracteres adicionais ou partes ausentes; * se a credencial pertence à empresa e ao ambiente pretendidos; * se a chave continua válida e não foi revogada ou substituída por uma rotação. Após uma rotação, atualize a configuração do seu backend com o novo segredo. A chave anterior deixa de autenticar as requisições. Para uma sessão OAuth expirada ou revogada, faça o login novamente no CLI. Confira também se a requisição e o ambiente estão entre os acessos concedidos. Uma renovação não acrescenta permissões à autorização original. Uma resposta `403 Forbidden` pode indicar falta de permissão da chave, uma restrição de IP, uma condição da conta ou outra regra de autorização. Uma chave válida não libera uma requisição recusada por essas condições. `COMPANY_STATUS_RESTRICTED` indica que a situação da empresa impede o acesso. Empresas suspensas ou com conta encerrada não podem usar a API em nenhum dos ambientes. Cadastro pendente permite somente Sandbox. A mensagem identifica a condição e orienta o contato com o SAC ou a consulta do cadastro no Dashboard. Consulte [Códigos HTTP das respostas](/br/api/codigos-http-das-respostas) para interpretar o status, o código e a mensagem retornados pela API. # Chaves de API (/br/integracoes/chaves-api) A área **Integração / Chaves de API** administra as credenciais usadas para conectar o sistema da sua empresa à Raims. Chaves de Sandbox e de produção pertencem a ambientes distintos e não devem ser reutilizadas entre eles. Consultar exige **Chaves de API**. Criação, rotação, alteração do nome e dos acessos, revogação e gestão de IPs têm permissões próprias. As ações também podem ser bloqueadas quando a conta estiver em modo de consulta. Use essas credenciais para [autenticar as requisições à API da Raims](/br/integracoes/autenticacao). Os acessos da chave são sempre definidos pela seleção salva. Uma seleção vazia não autoriza nenhuma operação da API. Consultar os logs exige também **Ver logs de solicitações**. Esse acesso permite ler os detalhes e os corpos de solicitações e respostas disponíveis no histórico. Ter acesso às chaves não libera os logs automaticamente. Confira [como conceder essa permissão à equipe](/br/usuarios-e-permissoes#integracao-api_keys_view_logs). **Mantenha a chave em segredo** Nunca coloque uma chave Raims no navegador, em aplicativos distribuídos, repositórios, screenshots ou logs. Guarde a credencial na parte privada do sistema responsável pela integração. ## Criar uma chave ### Abra Chaves de API Acesse **Integração / Chaves de API / Criar nova chave de API** com **Criar chaves de API**. Confirme o ambiente selecionado antes de criar. Se a tela solicitar, confirme sua identidade para abrir o formulário. Contas ainda sem acesso à produção podem gerar somente chaves de Sandbox. ### Dê um nome operacional Preencha **Nome da chave** e confira **Tipo da chave**. Use um nome que identifique o sistema e o ambiente, como **ERP - Sandbox** ou **Integração principal - Produção**. ### Escolha os acessos Em **Permissões da API**, selecione somente as ações necessárias à integração. Consultar, criar, editar, remover e outras ações têm seleções independentes. Use **Saiba mais** para conferir o alcance de cada uma. A seleção começa vazia. ### Restrinja a origem quando possível Se o sistema usa endereços de saída fixos, autorize somente esses endereços IPv4 ou intervalos CIDR. ### Copie e armazene imediatamente Depois de preencher o formulário, selecione **Criar**. Conclua a confirmação de identidade quando solicitada; a criação continua automaticamente, sem outro clique em **Criar**. Copie o segredo exibido e salve-o em um cofre de segredos antes de fechar o diálogo. ## Separação por ambiente ### Sandbox Chaves de teste usam placeholders como `sk_test_...` e servem para desenvolvimento e homologação. Elas não processam dinheiro real. ### Produção Chaves de produção usam placeholders como `sk_live_...` e podem autorizar requisições com efeitos reais na conta. Use-as somente depois que a integração estiver aprovada e pronta para produção. A [Referência da API](/br/api) apresenta a autenticação, os campos e os exemplos de cada requisição. O console aceita chaves de Sandbox para testar a integração. ## Armazenamento seguro Use um gerenciador de segredos ou uma variável protegida no ambiente em que a integração é executada. Arquivos de exemplo devem conter somente o nome da variável: ```dotenv title=".env.example" RAIMS_API_KEY=sk_test_... ``` Não versione um arquivo `.env` real e permita acesso somente às pessoas e aos sistemas que precisam usar a integração. ## Permissões da chave Cada chave tem uma seleção de ações da API. Você pode permitir criar uma cobrança sem permitir consultar, editar, revogar ou estornar cobranças. Selecionar uma ação não concede automaticamente as outras ações do recurso. As regras da conta e do ambiente continuam valendo. Os acessos da chave são diferentes das permissões do funcionário para administrá-la no Dashboard. As tabelas abaixo explicam cada ação oferecida na matriz e no link **Saiba mais**. Para copiar o segredo de uma chave Sandbox ou rotacionar uma chave, o funcionário precisa ter acesso a todos os recursos e ações que ela permite. Quando a chave concede acessos além dos seus, ela continua na lista com o segredo oculto, e as ações de copiar e rotacionar ficam indisponíveis. Peça a uma pessoa autorizada para revisar a chave; consultar seus metadados não concede acesso ao segredo. ## Editar permissões 1. Acesse **Integração / Chaves de API** e abra as ações da chave desejada. 2. Selecione **Editar permissões** e confira os acessos atuais. 3. Ajuste a seleção por ação e escolha **Salvar permissões**. 4. Conclua a confirmação de segurança quando solicitada. A ação exige **Editar chaves de API**. A edição conserva o segredo da chave; não é preciso trocar o token no sistema integrador. Conceda somente os acessos necessários. Seu próprio acesso também limita quais permissões você pode conceder. Se outra pessoa alterar a chave durante a edição, carregue a seleção atual, revise as diferenças e salve novamente. Não confirme uma seleção antiga sem conferir a alteração. Uma chamada sem o acesso necessário recebe `403 API_KEY_PERMISSION_DENIED`. Confira as permissões da chave antes de repetir a requisição. Consulte [Autenticação](/br/integracoes/autenticacao#permissões-da-chave). ## Restrições de IP O Dashboard aceita um endereço IPv4 individual, como `203.0.113.10`, ou um intervalo CIDR, como `203.0.113.0/24`. Use somente endereços de saída estáveis e confirmados pela sua infraestrutura. Informe os quatro números decimais do IPv4, separados por pontos, sem zeros à esquerda. Cada número deve estar entre `0` e `255`. Para um intervalo CIDR, acrescente `/` e um prefixo inteiro de `0` a `32`, sem sinal ou zeros à esquerda. O intervalo inclui toda a rede indicada pelo prefixo. Por exemplo, `203.0.113.7/24` aparece como `203.0.113.0/24` e abrange de `203.0.113.0` até `203.0.113.255`. O prefixo `/32` aparece como um IP individual. Entradas que representam a mesma faixa aparecem uma única vez. Confira a lista antes de salvar, especialmente quando informar um prefixo menor, que permite uma faixa maior de endereços. | Item | Tipo | Descrição | | --- | --- | --- | | Sem restrição | Maior superfície de risco | Qualquer origem que obtenha o segredo pode tentar utilizá-lo. | | IPv4 individual | Origem específica | Adequado quando o sistema se conecta sempre pelo mesmo endereço. | | CIDR | Faixa controlada | Útil para um conjunto conhecido de endereços de saída; evite redes amplas. | ## Renomear uma chave 1. Acesse **Integração / Chaves de API** e abra as ações da chave desejada. 2. Selecione **Renomear chave**, informe o novo nome e confirme **Renomear chave**. 3. Aguarde a confirmação e confira o nome na lista. A ação exige **Editar chaves de API**. Ela altera somente o nome exibido; integrações existentes continuam usando o mesmo segredo. ## Rotacionar uma chave 1. Acesse **Integração / Chaves de API** e abra as ações da chave correta. 2. Selecione **Alterar token da chave**, confira o aviso e confirme **Alterar token**. 3. Copie e armazene o novo segredo antes de fechar o diálogo. 4. Atualize os sistemas que utilizavam o token anterior. A ação exige **Rotacionar chaves de API**. Funcionários também precisam ter acesso a todos os recursos e ações concedidos pela chave. A rotação substitui o segredo anterior; a chave mantém as configurações apresentadas. ## Gerenciar restrições de IP 1. Acesse **Integração / Chaves de API** e abra as ações da chave. 2. Selecione **Gerenciar restrições de IP**. 3. Adicione, ajuste ou remova somente os endereços IPv4 e intervalos CIDR usados pelo seu sistema. Confira a confirmação de cada alteração. 4. Use **Baixar lista** se precisar guardar a lista de endereços configurados. A alteração exige **Gerenciar IPs de API**. Consulte **Restrições de IP** neste guia antes de definir uma faixa de rede. Uma lista vazia deixa a chave sem restrição por origem. ## Revogar uma chave 1. Acesse **Integração / Chaves de API** e abra as ações da chave que deseja desativar. 2. Selecione **Revogar chave de API**, confira o token identificado e confirme **Revogar chave**. 3. Aguarde **Chave revogada**. A ação exige **Excluir chaves de API** e revoga a chave. Sistemas que ainda dependam desse token precisam ser atualizados com outra credencial válida. ## Ações da conta e do checkout | Item | Descrição | | --- | --- | | Consultar informações da conta | Consulta a identificação, a situação e as tarifas da empresa, além dos dados da conta financeira quando disponíveis. Não altera o cadastro. A consulta dos dados bancários continua sujeita ao ambiente e à habilitação da conta. | | Consultar personalização do checkout | Consulta imagens, cores, e-mail de suporte e meios de pagamento padrão do checkout. Não altera a personalização nem cria uma cobrança. | | Alterar personalização do checkout | Altera os campos de personalização aceitos pela API, como imagens, cores e e-mail de suporte. Para enviar uma imagem nova, selecione também Preparar envio de imagens. Alterar a personalização não confirma pagamentos. | | Preparar envio de imagens | Obtém a autorização temporária para enviar uma logo ou um ícone do checkout. Enviar a imagem não a aplica automaticamente; a aplicação exige Alterar personalização do checkout. | | Descartar envio de imagem | Descarta um envio de logo ou ícone que ainda não foi aplicado, inclusive quando expirado. Não remove a imagem atual do checkout. Para isso, use Alterar personalização do checkout. | ## Consulta de saldo | Item | Descrição | | --- | --- | | Consultar saldos e previsão | Consulta os saldos total, bloqueado e disponível, além da previsão de recebimentos. Não solicita saques nem separa valores para uma operação. Uma previsão não garante disponibilidade de dinheiro. | ## Consulta do extrato | Item | Descrição | | --- | --- | | Consultar extrato | Lista os lançamentos do extrato e consulta um lançamento pelo identificador, com seus valores e referências disponíveis. Não cria lançamentos nem altera saldos. | ## Ações de clientes | Item | Descrição | | --- | --- | | Consultar clientes | Lista clientes com os filtros e a paginação da API e consulta um cadastro pelo identificador. Não autoriza criar, editar ou remover clientes. | | Criar cliente por CPF/CNPJ | Cria o cliente ou atualiza o cadastro existente com o mesmo CPF/CNPJ. Esse é o comportamento do cadastro por documento, mesmo sem a ação de edição selecionada. O identificador do cliente existente é preservado. | | Editar cliente pelo identificador | Atualiza os campos permitidos de um cliente identificado na requisição, preservando os campos omitidos. Não altera CPF/CNPJ nem cria outro cadastro. Dados de integração seguem as regras do campo metadata. | | Remover clientes | Remove um cliente ou solicita a remoção em lote. Cobranças vinculadas ainda não removidas podem impedir a ação. A permissão não remove cobranças nem devolve pagamentos. | ## Ações de cobranças | Item | Descrição | | --- | --- | | Consultar cobranças | Lista e consulta cobranças, estatísticas, dados de pagamento e documentos disponíveis, como boleto e recibo. As consultas não emitem outro pagamento nem confirmam recebimento. Criar, editar, revogar e estornar são ações separadas. | | Criar cobranças | Cria uma cobrança para um cliente cadastrado, com os meios e as opções aceitos pela API. Conforme o pedido, pode solicitar a emissão de Pix ou boleto, gerar um link e solicitar e-mail. Não autoriza consultar, editar, revogar ou estornar cobranças. | | Editar cobranças | Altera os campos de uma cobrança aceitos pelo endpoint de edição, respeitando as condições do estado atual. Não altera o pagamento nem solicita cancelamento ou estorno. | | Revogar cobranças | Solicita o cancelamento de uma cobrança que permite revogação. O histórico permanece disponível, e a conclusão pode depender de confirmação. Revogar não devolve um pagamento recebido; isso exige Solicitar estorno Pix. | ## Ações de estornos | Item | Descrição | | --- | --- | | Consultar estornos | Consulta elegibilidade, valores devolvíveis, solicitações, histórico e comprovantes de estornos. Não inicia nem repete uma devolução. A elegibilidade consultada pode mudar antes do pedido. | | Solicitar estorno Pix | Solicita a devolução integral ou parcial de um pagamento Pix recebido. O pedido continua sujeito a valor restante, saldo, estado e demais condições da API. Para acompanhar o resultado ou baixar o comprovante, selecione também Consultar estornos. | ## Ações de links de pagamento | Item | Descrição | | --- | --- | | Consultar links de pagamento | Lista e consulta a URL, a configuração e a disponibilidade dos links de pagamento. Não cria nem altera links. Os dados financeiros da cobrança exigem Consultar cobranças. | | Criar links de pagamento | Cria ou recupera o link de uma cobrança existente. A ação preserva um link já criado e sua situação de pausa. Não cria outra cobrança nem solicita envio de e-mail. | | Editar links de pagamento | Altera os campos permitidos do link, incluindo URLs de retorno, meios aceitos e pausa ou reativação. Pausar o link não cancela Pix ou boleto já emitidos nem prorroga o vencimento da cobrança. | | Enviar links por e-mail | Solicita o envio ou reenvio do link ao destinatário da cobrança, respeitando as condições do link e o intervalo entre pedidos. Não cria outra cobrança. O aceite confirma o pedido, não a entrega do e-mail. Sandbox também pode enviar e-mails reais. | ## Ações de saques | Item | Descrição | | --- | --- | | Consultar saques e destinos | Consulta saques, valores em processamento, limites e destinos Pix próprios disponíveis. Não solicita uma retirada nem altera o destino padrão. Alguns dados e destinos exigem Produção. | | Solicitar saques Pix | Solicita um saque para o destino próprio padrão, respeitando saldo, tarifa, limites e demais regras da conta. Não cadastra outro destino. Para acompanhar o pedido, selecione também Consultar saques e destinos. | | Consultar saque automático | Consulta ativação, valor mínimo, horário e próxima tentativa prevista de saque automático. A consulta exige Produção e não inicia uma retirada. | | Configurar saque automático | Ativa, desativa ou altera as opções de saque automático aceitas pela API em Produção. Salvar a configuração não solicita um saque imediato nem cadastra outro destino. | ## Consulta de contestações | Item | Descrição | | --- | --- | | Consultar contestações | Lista e consulta as contestações, com etapa, motivo e resultados disponíveis. Não envia defesa, aceita devolução nem encerra uma contestação. | ## Ações de webhooks | Item | Descrição | | --- | --- | | Consultar webhooks | Consulta destinos, configuração, eventos disponíveis para assinatura e situação conhecida de falhas. Não retorna o segredo de assinatura nem modifica o webhook. Criar, editar, excluir, pausar, testar e rotacionar são ações separadas. | | Criar webhooks | Cadastra um destino HTTPS e os eventos que ele receberá. A resposta de criação fornece o segredo para validar as assinaturas; armazene-o com segurança. Não autoriza editar ou excluir outros destinos. | | Editar webhooks | Altera os campos aceitos do destino, como nome, URL, eventos selecionados e ativação. A lista enviada de eventos substitui a anterior. A pausa de envios e a rotação do segredo têm permissões próprias. | | Excluir webhooks | Exclui um destino que não será mais usado e impede novos envios. Uma tentativa já autorizada ou em andamento pode terminar. Não altera os recursos financeiros relacionados aos eventos. | | Rotacionar segredo de webhook | Substitui o segredo de assinatura e devolve o novo valor para atualizar o receptor. A configuração e o identificador do destino são preservados. O período de transição e a revogação imediata seguem as opções da API. | | Pausar ou retomar envios | Pausa os envios de um webhook ativo ou retoma entregas ainda válidas. A pausa não amplia o prazo de entrega, e a retomada não garante ordem nem horário. O envio explícito de um teste exige Testar webhooks. | | Testar webhooks | Solicita um evento técnico de teste para um destino ativo. O aceite não comprova recebimento; confira os registros do receptor. O teste não confirma pagamentos nem altera saldos. | ## Ações de simulação | Item | Descrição | | --- | --- | | Confirmar pagamento de teste | Confirma o pagamento de uma cobrança de teste e aplica os efeitos correspondentes no Sandbox. Não movimenta dinheiro real e não pode ser usado com uma chave de Produção. | | Simular falha no pagamento | Marca a falha de uma cobrança aberta no Sandbox para testar o tratamento desse resultado. Não falha nem cancela um pagamento real. | | Preparar cenário de teste | Prepara uma pendência ou falha de emissão de Pix ou boleto, ou de cancelamento, para uma cobrança Sandbox. A ação normal correspondente ainda precisa ser executada e ter sua própria permissão. | | Resolver cenário pendente | Conclui ou falha uma emissão ou um cancelamento já iniciado e mantido pendente pelo cenário Sandbox. Não inicia outra cobrança nem resolve operações reais. | | Emitir pagamento de teste | Emite Pix ou boleto de teste para uma cobrança existente no Sandbox. O cenário preparado para a emissão pode produzir pendência ou falha. Emitir não confirma que a cobrança foi paga. | | Simular compensação de boleto | Registra um boleto como compensado no Sandbox, ainda aguardando liquidação. Essa etapa não credita saldo nem disponibiliza recibo de pagamento concluído. Confirmar o pagamento é outra ação. | | Iniciar estorno de teste pendente | Inicia uma devolução Pix no Sandbox que aguarda confirmação. Use o identificador retornado para concluir o estorno ou simular sua falha com as permissões correspondentes. | | Concluir estorno de teste | Conclui um estorno Pix pendente no Sandbox, sem descontar o valor novamente do saldo. Não conclui uma devolução real nem cria outro pedido de estorno. | | Simular falha no estorno | Falha um estorno Pix pendente no Sandbox e devolve seu valor ao saldo disponível de teste. Não interfere em devoluções ou saldos de Produção. | - [Webhooks](/br/integracoes/webhooks): Configure notificações e segredos separados das chaves de API. - [Usuários e permissões](/br/usuarios-e-permissoes#integracao): Separe consulta de chaves e logs, criação, rotação, revogação e gestão de IPs. - [Comece por aqui](/br/api): Prepare sua credencial de Sandbox e veja como usar o console da API. # MCP da Raims (/br/integracoes/mcp) O MCP da Raims permite que um aplicativo de IA consulte dados e solicite operações na conta que você autorizar. Uma conexão reúne os ambientes permitidos da empresa e os acessos definidos no consentimento. ```text https://mcp.raims.com ``` A autenticação no aplicativo de IA e a autenticação na Raims são separadas. O aplicativo não precisa receber sua senha da Raims nem uma chave da Public API. As permissões atuais de quem autorizou a conexão continuam limitando o acesso. O MCP usa a autorização geral de [Aplicativos autorizados](/br/integracoes/aplicativos). A mesma tela de permissões e a mesma lista atendem outros aplicativos compatíveis que conectam sua conta à Raims. Em aplicativos autenticados, `search_raims_documentation` permite buscar instruções e exemplos na documentação pública, com trechos e links nas respostas. A busca dispensa uma permissão específica no consentimento. Consultas e operações da conta seguem os acessos que você autorizar. ## Conectar sua conta 1. Adicione a URL do MCP nas configurações do aplicativo compatível. 2. Inicie a conexão e conclua o login na página da Raims aberta no navegador. 3. Em **Permissões**, confira o aplicativo e selecione as operações que ele poderá executar. Use um perfil sugerido ou ajuste cada item. 4. Selecione **Revisar** para conferir o aplicativo, a conta, os ambientes, o destino de retorno e as permissões no resumo. 5. Escolha **Autorizar acesso** e conclua a confirmação de segurança quando solicitada. 6. Volte ao aplicativo de IA para continuar. As operações são independentes e aparecem organizadas por recurso, como Clientes, Cobranças e Webhooks. Marcar criação não seleciona consulta, edição, revogação ou estorno. Use a busca para localizar uma operação e **Saiba mais** para conferir sua explicação e os ambientes aceitos. Use **Voltar** na revisão para ajustar as permissões. A seleção é mantida. O login mantém os controles de segurança da conta, incluindo MFA quando solicitado. Se não reconhecer o pedido ou não quiser conceder as permissões, feche a página sem autorizar. A conexão só é concedida após a confirmação. O consentimento autoriza a conexão uma vez. Depois disso, a IA pode executar as operações concedidas sem abrir uma aprovação no Dashboard para cada tarefa. As permissões atuais da conta e as regras de cada recurso continuam valendo. Se os acessos, os ambientes permitidos ou a situação da conta mudarem durante a conexão, a página pede que você confira novamente os dados e revise os acessos antes de concluir. A autorização não é repetida automaticamente. O aplicativo compatível pode renovar a autorização sem pedir sua senha novamente. Se a conexão expirar, for revogada ou não puder ser renovada, conecte a conta novamente e confira o consentimento. Sandbox e Produção usam a mesma URL. Uma nova conexão inclui todos os ambientes permitidos à conta e ao seu acesso, sem escolher um ambiente no consentimento. As permissões selecionadas valem para esses ambientes. Trocar o ambiente do Dashboard não altera o alcance da conexão. Ambientes, recursos e permissões indisponíveis continuam bloqueados. Se uma conexão estiver limitada a um ambiente, refaça a conexão para autorizar os ambientes atualmente permitidos. Renovar a autorização mantém seu alcance. ## Configurar seu aplicativo Com o [Raims CLI](/br/cli) instalado, consulte as instruções do cliente: ```bash raims mcp setup --client codex raims mcp setup --client claude-code raims mcp setup --client cursor ``` O comando apresenta configurações sem credenciais e não executa o aplicativo. `--save CAMINHO` salva um snippet em um arquivo novo; ele não sobrescreve nem mescla configurações existentes. Confira o plano com `--dry-run`. ### Codex ```bash codex mcp add raims --url https://mcp.raims.com codex mcp login raims ``` ### Claude Code ```bash claude mcp add --transport http raims https://mcp.raims.com ``` Depois, abra o Claude Code, execute `/mcp` e conclua a autenticação da Raims. ### Cursor Acrescente a entrada abaixo em `.cursor/mcp.json` ou nas configurações pessoais de MCP do Cursor, preservando os outros servidores: ```json { "mcpServers": { "raims": { "url": "https://mcp.raims.com" } } } ``` Conecte o servidor no Cursor e conclua o consentimento no navegador. ## Conferir o contexto da conta Peça ao assistente para consultar `get_raims_account_context` antes de orientar uma ação que dependa da conta. O assistente informa `data_environment` como `Sandbox` ou `Production` entre os ambientes autorizados. A ferramenta informa a empresa, o ambiente consultado, a situação atual, as capacidades disponíveis e o horário da consulta. O contexto também descreve moeda, unidades e fuso de referência. Valores financeiros usam centavos inteiros. Previsão de recebimento não é saldo disponível, e uma solicitação aceita não confirma pagamento ou conclusão. Depois de uma mudança de acesso ou de conta, consulte o contexto novamente. Uma informação indisponível não deve ser tratada como zero. A autorização para iniciar uma chamada não substitui a validação da operação pela Raims. ## Executar operações autorizadas Após autorizar a conexão, peça ao aplicativo as ações que deseja realizar. Por exemplo, ele pode cadastrar, editar ou excluir webhooks quando esses acessos estiverem concedidos. Não é necessário aprovar cada tarefa em outra tela da Raims. A conexão continua limitada à empresa, aos ambientes autorizados, aos acessos concedidos e às permissões atuais de quem a autorizou. Em cada chamada de `raims_api_read`, `raims_api_write` ou `get_raims_account_context`, o assistente informa o `data_environment` adequado ao pedido. O resultado identifica o ambiente consultado ou alterado. Limites, saldo, elegibilidade e validações dos recursos são conferidos pela Raims em cada solicitação. Antes de executar, consulte `raims_api_details`: o campo `data_environments` informa quais ambientes o endpoint aceita. O ambiente escolhido precisa ser aceito pelo endpoint e autorizado pela conexão. Simulações aceitam somente `Sandbox` e não alteram dados de Produção. Se o resultado de uma escrita ficar incerto, consulte o recurso antes de solicitar outra criação. Um pedido aceito não confirma que um saque chegou ao destino ou que um e-mail foi entregue. ## Gerenciar e revogar o acesso No Dashboard, abra **Integração / Aplicativos autorizados**. Cada membro pode consultar as próprias conexões. **Ver aplicativos da empresa** inclui as conexões do titular e da equipe. **Revogar conexões da equipe** também permite consultá-las e revogar conexões de outros funcionários, sem atingir as do titular. As permissões de dispositivos não concedem esses acessos. No menu de ações, use **Editar permissões** para conferir os acessos concedidos ou **Revogar acesso** para encerrar uma conexão, conforme suas permissões. Abrir o editor não altera os acessos. **Editar permissões** permite remover ou restaurar acessos da autorização original, com confirmação de segurança, sem mudar ambientes ou validade. Consulte [Editar permissões](/br/integracoes/aplicativos#editar-permissões) para conferir quem pode editar e quando é necessária uma nova autorização. As chaves de integração ficam em **Integração / Chaves de API** e exigem as permissões correspondentes. Sair do Dashboard não substitui a revogação do aplicativo. Use **Revogar acesso** para encerrar essa autorização. A revogação impede novas chamadas autorizadas pela conexão. Ela não desfaz operações concluídas nem apaga dados que o aplicativo externo já tenha recebido. As permissões atuais da conta e do membro da equipe continuam sendo conferidas. As ações registradas de um funcionário pelo MCP preservam sua identificação em **Conta / Registro de Atividades**. Cada membro vê as próprias atividades; **Ver auditoria completa** amplia a consulta para a empresa. O histórico também mostra autorizações, alterações de permissões, revogações e expirações das conexões. Eventos automáticos são identificados como **Sistema**. ## Resolver problemas de conexão Se uma falha de rede ou indisponibilidade temporária impedir a consulta do pedido de conexão, a página mantém o carregamento e tenta novamente automaticamente enquanto a falha for temporária. Aguarde o resultado. Somente a consulta do pedido é repetida; autorizar o acesso continua exigindo sua confirmação. * Se a solicitação estiver expirada ou não estiver mais disponível, volte ao aplicativo que iniciou a conexão e solicite um novo acesso. Reabrir o mesmo link não renova o pedido. * Se a consulta do pedido for negada, confira a conta e seu acesso atual. Uma negativa de acesso encerra as tentativas automáticas. * Se o aplicativo pedir autenticação novamente, inicie a conexão e confira o consentimento apresentado pela Raims. * Se uma operação não estiver permitida, confira o ambiente, as permissões concedidas e o acesso atual do operador. A conexão não amplia esse acesso. * Se receber `DATA_ENVIRONMENT_NOT_ALLOWED`, ajuste o pedido para um dos ambientes indicados em `raims_api_details.data_environments`. Uma nova autorização não libera um ambiente que o endpoint não aceita, nem permite simulações em Produção. * Se a conta estiver diferente do esperado, interrompa a ação e conecte a conta correta. Se o ambiente estiver incorreto, ajuste o pedido ao assistente antes de continuar. Um ambiente fora do alcance da conexão exige nova autorização. * Se o resultado de uma solicitação ficar incerto, confira o estado do recurso antes de pedir outra criação ou repetir a ação. ## Fontes dos aplicativos * [MCP no Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) * [MCP no Claude Code](https://code.claude.com/docs/en/mcp) * [MCP no Cursor](https://cursor.com/docs/mcp) # Rate limiting (/br/integracoes/rate-limiting) A API limita a frequência de chamadas e a quantidade de requisições em andamento. Sua integração deve controlar os dois valores, tratar `429 Too Many Requests` e distribuir o trabalho ao longo do tempo. Use este guia ao preparar uma integração, investigar recusas por excesso ou planejar um aumento de volume. Os limites apresentados aqui são os da API Raims; as regras próprias de cada endpoint também precisam ser respeitadas. ## Como os limites são compartilhados A cota pertence à empresa e ao ambiente da chave de API. Todas as chaves da mesma empresa compartilham os limites naquele ambiente, mesmo quando as chamadas vêm de servidores, processos ou aplicações diferentes. Criar ou rotacionar uma chave não aumenta a cota. Produção e Sandbox têm cotas separadas. Cada endpoint tem um limite adicional de frequência. O método HTTP e o caminho da referência identificam o endpoint: `GET /v1/charges/{id}` compartilha a mesma cota para todos os IDs. Já `GET /v1/charges` e `POST /v1/charges` têm cotas de endpoint distintas e compartilham a cota total da empresa no ambiente. Coordene o consumo entre os componentes da sua integração. Um controle local em cada processo, sozinho, não controla a soma de todos eles. ### Limites da API por empresa e ambiente Os valores abaixo são os limites padrão. Eles podem variar conforme os limites definidos para sua empresa. | Limite | Produção | Sandbox | | ---------------------------------------- | -------- | ------- | | Total de requisições por segundo | 100 | 25 | | Requisições por segundo em cada endpoint | 25 | 25 | | Total de requisições em andamento | 50 | 50 | Os limites se aplicam juntos. Em Produção, por exemplo, o teto total de 100 requisições por segundo não permite concentrar esse volume em um endpoint limitado a 25. No Sandbox, chamadas a endpoints diferentes também dividem o teto total de 25. Considere esses valores tetos de uso, sem mantê-los como meta permanente de envio. Uma chamada HTTP pode consultar ou alterar um recurso; a cota não representa uma quantidade de pagamentos processados por segundo. ## Frequência e concorrência Frequência é a quantidade de chamadas enviadas ao longo do tempo. Concorrência é a quantidade que ainda não terminou. Uma consulta demorada continua ocupando capacidade mesmo quando nenhuma nova chamada é enviada. Por exemplo, enviar dez chamadas por segundo que levam cinco segundos cada pode manter cerca de cinquenta chamadas em andamento. Reduzir somente a frequência não libera imediatamente as chamadas que já estão em execução. Distribua o início das chamadas e limite quantas podem ficar em andamento. Evite disparar um lote inteiro ao mesmo tempo. Picos curtos podem receber `429` mesmo quando a média observada está abaixo do teto; a passagem de um segundo para outro não deve ser usada para concentrar dois lotes. ## Interpretar o 429 `429 RATE_LIMITED` indica que a requisição foi recusada por excesso e não foi executada. A resposta informa quanto esperar e qual controle ajustar: ```http HTTP/1.1 429 Too Many Requests Content-Type: application/json Cache-Control: no-store Retry-After: 1 Raims-Rate-Limited-Reason: endpoint-rate { "error": { "code": "RATE_LIMITED", "message": "The API request limit was exceeded. Wait for Retry-After and reduce the request rate or the number of concurrent requests." } } ``` `Retry-After` é um número inteiro positivo de segundos. Espere pelo menos esse intervalo antes de repetir. O valor `1` acima é um exemplo; use sempre o valor recebido na resposta. | `Raims-Rate-Limited-Reason` | O que ajustar | | --------------------------- | ----------------------------------------------------------------------------------- | | `global-rate` | Reduza a frequência total de chamadas da empresa no ambiente. | | `endpoint-rate` | Reduza a frequência de chamadas ao mesmo endpoint, incluindo IDs diferentes. | | `global-concurrency` | Reduza o total de chamadas simultâneas da empresa no ambiente. | | `endpoint-concurrency` | Quando habilitado para a empresa, reduza as chamadas simultâneas ao mesmo endpoint. | | `resource-specific` | Respeite o intervalo próprio do recurso indicado por `error.code`. | Alguns endpoints têm limites e intervalos próprios, que se somam aos limites gerais da API. Consulte a referência de cada endpoint para conhecer as regras aplicáveis. Decida pelo status, por `error.code` e pelo motivo do header. O texto em `error.message` ajuda no diagnóstico e não deve ser comparado na lógica do seu sistema. Os erros gerais não precisam de `error.details`. ## Repetir com espera Ao receber `429`, preserve o trabalho pendente e reagende a tentativa: 1. Leia `Retry-After` e o motivo do limite. 2. Reduza a frequência ou a concorrência conforme o motivo. 3. Espere pelo menos o intervalo recebido. Nas recusas seguintes, aumente a espera e acrescente uma pequena variação aleatória, chamada *jitter*. 4. Defina um máximo de tentativas e um prazo total. Se forem atingidos, encerre a tentativa atual e mantenha o trabalho para tratamento posterior. Uma regra possível é usar o maior valor entre `Retry-After` e uma espera crescente, acrescentando o jitter depois. Nunca reduza a espera indicada pelo servidor para caber em um prazo local: se ela ultrapassar esse prazo, adie o trabalho em vez de repetir antes da hora. Não reinicie todas as chamadas recusadas juntas quando a espera terminar. Use uma fila e mantenha o ritmo de saída também nas novas tentativas. Centralize o retry para que diferentes camadas da sua aplicação não repitam a mesma chamada ao mesmo tempo. Em chamadas que criam ou alteram dados, ou quando a conexão termina sem uma resposta, confira o resultado antes de reenviar. Uma perda de resposta não comprova que a requisição deixou de ser processada. Não recrie uma cobrança para resolver uma dúvida sobre a anterior. ## Exemplo de consulta com fila Este exemplo de Node.js consulta um cliente por `GET`. Ele mantém uma chamada em andamento por processo, espera 100 ms entre itens e tenta no máximo quatro vezes quando recebe `429`. Cada tentativa tem timeout de até 30 segundos; o prazo de execução do item é de dois minutos, contado quando ele sai da fila. Esses valores são escolhas do exemplo, não limites adicionais da API. Armazene a chave em `RAIMS_API_KEY`, no backend da integração. Passe o ID de um cliente da mesma empresa e ambiente da chave. Não execute o código no navegador nem registre a chave nos logs. ```javascript const apiKey = process.env.RAIMS_API_KEY; const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); let queue = Promise.resolve(); function retrieveCustomer(id) { const task = queue.then(() => retrieveWithRetry(id)); queue = task.catch(() => {}).then(() => sleep(100)); return task; } async function retrieveWithRetry(id) { if (!apiKey) throw new Error('RAIMS_API_KEY is required.'); const deadline = Date.now() + 120_000; for (let attempt = 0; attempt < 4; attempt += 1) { const remaining = deadline - Date.now(); if (remaining <= 0) throw new Error('Request deadline exceeded.'); const response = await fetch( `https://api.raims.com/v1/customers/${encodeURIComponent(id)}`, { method: 'GET', headers: { Authorization: `Bearer ${apiKey}`, Accept: 'application/json', }, redirect: 'error', signal: AbortSignal.timeout(Math.min(30_000, remaining)), }, ); if (response.ok) return response.json(); const retryAfter = response.headers.get('Retry-After'); await response.body?.cancel(); if (response.status !== 429) throw new Error(`HTTP ${response.status}`); const seconds = /^[1-9]\d*$/.test(retryAfter ?? '') ? Number(retryAfter) : NaN; if (attempt === 3 || !Number.isSafeInteger(seconds)) { throw new Error('Rate limit: stop and reschedule the request.'); } const delay = Math.max(seconds * 1000, 500 * 2 ** attempt) + Math.floor(Math.random() * 250); if (delay >= deadline - Date.now()) { throw new Error('Retry-After exceeds the remaining request deadline.'); } await sleep(delay); } } ``` A função devolve o erro ao chamador quando o prazo acaba, o header não pode ser interpretado ou ocorre outra falha. Ela não repete automaticamente timeouts, erros de conexão ou respostas HTTP diferentes de `429`. Trate esses resultados na aplicação e preserve o trabalho que precisar ser reagendado. Essa fila é local. Ao executar várias instâncias, coordene o consumo entre elas e mantenha limites para a quantidade de itens pendentes e o tempo na fila. O exemplo não substitui esse controle compartilhado nem é um cliente completo da API. ## Evitar chamadas desnecessárias Use [webhooks](/br/integracoes/webhooks/receber-eventos) para receber os tipos de alteração disponíveis, em vez de consultar continuamente o mesmo recurso. Valide a assinatura e trate reentregas sem repetir o efeito. Consulte o recurso quando precisar recuperar seu estado atual; não dependa da ordem dos eventos. Em listagens, aplique os filtros disponíveis, processe cada página e avance somente enquanto `page.has_next` for verdadeiro. Copie `page.next_after` para `after`, mantendo os filtros. Não reinicie a listagem inteira a cada tentativa. Confira [Listagem e paginação](/br/api/listagem-e-paginacao). Separe tarefas de consulta em lote das chamadas necessárias ao pagamento. Reserve capacidade para o uso interativo e evite repetir consultas cujo resultado sua aplicação ainda pode utilizar. ## Diagnosticar e pedir revisão Meça a frequência total e por endpoint, o número de chamadas simultâneas, a duração das respostas e as recusas por motivo. Registre método, template do endpoint, ambiente, horário, status HTTP, `error.code`, motivo do limite, `Retry-After` e quantidade de tentativas. Use métricas agregadas. Não registre chaves de API, headers de autenticação, corpos com dados pessoais ou links sensíveis. Para diagnóstico, o template `/v1/charges/{id}` evita gravar o identificador de cada cobrança na métrica. Se as recusas persistirem, confira o consumo de todas as aplicações da mesma empresa e ambiente. Para avaliar um aumento dos limites conforme as necessidades da sua integração, fale com seu gerente de contas pelo chat do Dashboard Raims ou envie um e-mail para [integracoes@raims.com](mailto:integracoes@raims.com). Informe os endpoints, volume esperado, picos, concorrência, latência e horários de maior uso. Não envie sua chave. A solicitação será analisada; o contato não confirma aumento de cota. # SDK Delphi (/br/integracoes/sdk-delphi) O SDK Delphi integra um backend à API pública da Raims por fontes com serviços, parâmetros e respostas tipadas. A distribuição é código-fonte para compilar no alvo da sua aplicação. Confira os requisitos por plataforma ao configurar a instalação. Não incorpore a chave de API em executáveis desktop ou mobile distribuídos. A [referência do SDK](https://github.com/raimshq/raims-delphi/blob/main/docs/reference.md) lista os métodos e parâmetros de cada recurso. ## Instalar o SDK Baixe os fontes da [release atual no GitHub](https://github.com/raimshq/raims-delphi/releases/latest) e preserve o diretório `src` completo. A base dos fontes exige Delphi 10.4; alguns alvos exigem versões posteriores. Consulte os [requisitos por plataforma](https://github.com/raimshq/raims-delphi/blob/main/docs/installation.md#platform-requirements) e use uma edição que inclua seu compilador e os SDKs nativos necessários. No IDE, abra **Project**, **Options** e **Delphi Compiler**. Adicione o caminho para `src` ao **Search path** do projeto em cada alvo e configuração usados. Para uma configuração global, a página **Library** das opções Delphi permite adicionar o diretório ao **Library path** da plataforma selecionada. A [documentação da biblioteca do IDE](https://docwiki.embarcadero.com/RADStudio/Sydney/en/Library) explica essa seleção. Mantenha os arquivos compilados no diretório de saída da sua aplicação, separados dos fontes. Use `Raims.Client`, `Raims.Core`, `Raims.Params` e `Raims.Models`; para webhooks, adicione `Raims.Webhooks`. O SDK usa `System.JSON` e `System.Net.HttpClient` da biblioteca padrão, sem um framework de interface. Os exemplos são trechos de procedimentos Delphi; importe também `System.SysUtils` e `System.JSON`. ## Configurar o cliente Obtenha a credencial em [Chaves de API](/br/integracoes/chaves-api) e guarde-a no backend. Empresa, ambiente e permissões vêm da chave validada. Sandbox e Produção usam `https://api.raims.com`. ```pascal uses System.SysUtils, Raims.Client, Raims.Core, Raims.Models; var Client: TRaimsClient; Options: TRaimsClientOptions; begin Options := TRaimsClientOptions.Default; Options.TimeoutMilliseconds := 80000; Options.MaxNetworkRetries := 0; Client := TRaimsClient.Create(GetEnvironmentVariable('RAIMS_API_KEY'), Options); try // Use Client here. finally Client.Free; end; end; ``` Inicialize opções com `Default`. Timeouts usam milissegundos e se aplicam às fases do transporte nativo, não a um prazo total da operação. As chamadas são síncronas; em uma aplicação visual, execute rede fora da thread da interface. Os próximos trechos usam um `Client` aberto. Ele é dono dos serviços; a aplicação libera o cliente, os parâmetros e os recursos retornados com `try/finally`. ## Criar um cliente e uma cobrança `CustomerTaxId` é o CPF ou CNPJ válido do cliente autorizado. `CustomerKey` e `ChargeKey` são strings distintas, persistidas antes de enviar. `DueDateUnix` é um `Int64` com o vencimento em segundos Unix UTC; `RequestId` é uma string da aplicação. Os tipos usados estão em `Raims.Params`, `Raims.Models` e `Raims.Core`. ```pascal var CustomerParams: TCreateCustomerParams; ChargeParams: TCreateChargeParams; Customer: TCustomerCreated; Charge: TChargeCreated; RequestOptions: TRaimsRequestOptions; CustomerId: string; begin CustomerParams := TCreateCustomerParams.Create; try CustomerParams.SetTaxId(CustomerTaxId); RequestOptions := TRaimsRequestOptions.Default; RequestOptions.IdempotencyKey := CustomerKey; Customer := Client.Customers.Create(CustomerParams, RequestOptions); try CustomerId := Customer.Id; finally Customer.Free; end; finally CustomerParams.Free; end; ChargeParams := TCreateChargeParams.Create; try ChargeParams.SetCustomerId(CustomerId).SetAmountCents(15000); ChargeParams.SetDueDate(DueDateUnix).SetTitle('Pedido 1234'); RequestOptions := TRaimsRequestOptions.Default; RequestOptions.IdempotencyKey := ChargeKey; Charge := Client.Charges.Create(ChargeParams, RequestOptions); try RequestId := Charge.LastResponse.RequestId; finally Charge.Free; end; finally ChargeParams.Free; end; end; ``` `15000` representa R$ 150,00. Não chamar um setter deixa o campo ausente; `SetExternalReferenceNull` em `TUpdateCustomerParams` envia null quando o contrato permite limpar essa referência. `UnsetExternalReference` remove o campo da entrada. Nas respostas, `HasField` e `IsNull` distinguem presença e null antes de interpretar um getter que retorna zero ou string vazia. ## Paginação e resultados pendentes Para listar clientes e percorrer até cem itens: ```pascal var Page: TCustomerListResponse; begin Page := Client.Customers.List; try Page.AutoPagingEach( procedure(CustomerJson: TJSONObject) begin ProcessCustomer(CustomerJson); end, 100); finally Page.Free; end; end; ``` `ProcessCustomer` é seu handler. O callback recebe um `TJSONObject` emprestado: não libere nem altere esse objeto, e copie-o para retê-lo após o callback. `AutoPagingEach` libera as páginas adicionais; a aplicação libera a primeira. `NextPage` e `PreviousPage` retornam páginas novas ou `nil`; a aplicação é dona dessas páginas. Filtros e opções são preservados. HTTP `202` aceita uma operação com resultado pendente. Consulte o recurso ou acompanhe o webhook antes de confirmar o efeito financeiro. Preserve `LastResponse.StatusCode` e `RequestId` para identificar a tentativa. ## Idempotência e erros ```pascal var Current: TCustomerListItem; begin try Current := Client.Customers.Retrieve(CustomerId); try RequestId := Current.LastResponse.RequestId; finally Current.Free; end; except on E: ERaimsApiError do HandleApiFailure(E.LastResponse.StatusCode, E.Code, E.LastResponse.RequestId); on E: ERaimsConnectionError do HandleConnectionFailure; end; end; ``` Os handlers pertencem à aplicação. `ERaimsApiError` expõe `Code`, `ErrorType`, `ApiMessage` e `LastResponse`; `ERaimsConnectionError` representa falhas de transporte. Registre somente os metadados necessários, sem credenciais ou corpos completos. Se acessar `ApiError`, guarde a cópia retornada e libere-a. O SDK não gera chaves nem repete escritas automaticamente. Após uma resposta perdida, reconcilie a operação e mantenha chave e parâmetros se o endpoint permitir nova tentativa. `MaxNetworkRetries` habilita somente retries de leituras elegíveis; o padrão é zero. `Retry-After` segue a política de espera limitada do SDK. Veja [Idempotência](/br/api/idempotencia). ## Usar o Sandbox Use uma chave Sandbox e uma cobrança criada nesse ambiente: ```pascal var SandboxClient: TRaimsClient; Simulation: TChargeSimulation; begin SandboxClient := TRaimsClient.Create(GetEnvironmentVariable('RAIMS_SANDBOX_API_KEY')); try Simulation := SandboxClient.Simulations.Charges.ConfirmPayment(SandboxChargeId); try RequestId := Simulation.LastResponse.RequestId; finally Simulation.Free; end; finally SandboxClient.Free; end; end; ``` `SandboxChargeId` e `RequestId` são strings da aplicação. A chave define o ambiente; o SDK não o altera por header ou pelo sistema operacional. Simulações financeiras exigem Sandbox. Consulte [Simulações](/br/api/simulations/overview). E-mails e webhooks podem alcançar destinos externos; use destinos autorizados. ## Receber webhooks Preserve `RawBody` como os `TBytes` originais recebidos pelo servidor. Use `WebhookSecret` com o `secret_key` do webhook; os três valores `Received...` vêm dos headers originais. Antes de montar o array abaixo, rejeite ocorrências duplicadas de qualquer header de assinatura, sem escolher uma delas. ```pascal var Headers: TArray; Event: TJSONObject; begin SetLength(Headers, 3); Headers[0] := TRaimsHeader.Create('webhook-id', ReceivedDeliveryId); Headers[1] := TRaimsHeader.Create('webhook-timestamp', ReceivedTimestamp); Headers[2] := TRaimsHeader.Create('webhook-signature', ReceivedSignature); Event := TRaimsWebhook.ConstructEvent(RawBody, Headers, WebhookSecret); try PersistEvent(Event); finally Event.Free; end; end; ``` Os tipos estão em `System.JSON`, `Raims.Core` e `Raims.Webhooks`. `PersistEvent` é seu handler e `Event` pertence ao chamador. `ERaimsSignatureError` indica falha: não processe o evento nesse caso. Não reserialize o corpo antes da verificação. O padrão de tolerância é de 300 segundos; mantenha o relógio sincronizado. Após verificar, confira tipo e ambiente, deduplique o `id` do evento e grave o trabalho de forma durável antes de responder com sucesso. `webhook-id` identifica a entrega. Veja [Receber eventos](/br/integracoes/webhooks/receber-eventos). ## Atualizar o SDK Revise as notas da [release](https://github.com/raimshq/raims-delphi/releases/latest) e substitua todas as units pelos fontes da mesma revisão. Preserve o Search path ou Library path escolhido, remova unidades compiladas antigas da saída da aplicação e recompile cada alvo utilizado. Não misture uma unit nova com o restante de uma versão anterior. Confira sua integração no compilador, sistema operacional e configuração usados antes de disponibilizar a aplicação. # SDK .NET (/br/integracoes/sdk-dotnet) Use o pacote `Raims` para integrar uma aplicação de servidor em C# à API pública. O SDK oferece serviços por recurso, entradas e respostas tipadas, paginação por cursor e validação de assinaturas de webhook. Os métodos têm versões síncronas e assíncronas, com sufixo `Async`. A integração exige uma aplicação x64 em .NET Framework 4.8/4.8.1 ou .NET 10. Não distribua a chave de API em aplicações de navegador, desktop ou mobile entregues aos seus clientes. Ela deve permanecer no backend da integração. ## Instalar o pacote No diretório da aplicação: ```bash dotnet add package Raims ``` Sem informar a versão, o NuGet instala a versão estável mais recente compatível com o projeto e registra a referência na aplicação. Os destinos do pacote são `netstandard2.0` e `net10.0`. O NuGet seleciona o destino adequado; os consumidores suportados são validados em .NET Framework 4.8 e .NET 10, x64. ## Configurar o cliente Obtenha a chave em [Chaves de API](/br/integracoes/chaves-api) e armazene-a em uma variável de ambiente protegida ou no cofre da aplicação. Empresa, ambiente e permissões são determinados pela credencial validada na API. Sandbox e Produção usam `https://api.raims.com`. O exemplo abaixo é um trecho para um método `async`: ```csharp using System; using Raims; string apiKey = Environment.GetEnvironmentVariable("RAIMS_API_KEY") ?? throw new InvalidOperationException("Configure RAIMS_API_KEY."); using (var raims = new RaimsClient(apiKey)) { var customers = await raims.Customers.ListAsync(new ListCustomersOptions { PageSize = 20, }); foreach (var customer in customers) { Console.WriteLine(customer.Id); } } ``` Reutilize o cliente durante a vida da integração para aproveitar as conexões HTTP e encerre-o quando não for mais necessário. Os próximos trechos consideram uma instância `raims` configurada pela aplicação. ## Criar um cliente e uma cobrança `customerTaxId` é o CPF ou CNPJ válido do cliente autorizado pela aplicação. `customerIdempotencyKey` e `chargeIdempotencyKey` são chaves distintas, criadas e persistidas antes das requisições. `chargeDueDate` é o vencimento escolhido e persistido para o pedido, em segundos Unix UTC. ```csharp var customer = await raims.Customers.CreateAsync(new CreateCustomerOptions { TaxId = customerTaxId, }, new RequestOptions { IdempotencyKey = customerIdempotencyKey }); var charge = await raims.Charges.CreateAsync(new CreateChargeOptions { CustomerId = customer.Id, AmountCents = 15000, DueDate = chargeDueDate, Title = "Pedido 1234", }, new RequestOptions { IdempotencyKey = chargeIdempotencyKey }); int? httpStatus = charge.LastResponse?.StatusCode; var requestId = charge.LastResponse?.RequestId; ``` Se o CPF ou CNPJ já existir na mesma empresa e ambiente, o cadastro do cliente é atualizado e mantém seu identificador. `15000` representa R$ 150,00. Consulte os campos e condições em [Criar cobrança](/br/api/charges). Para repetir a mesma intenção após perder a resposta, conserve a chave e todos os parâmetros, inclusive o vencimento. A referência externa de um pedido não substitui a idempotência. ## Paginação e resultados pendentes Enumerar uma página não faz novas requisições. Use `NextPageAsync()` e `PreviousPageAsync()` para navegar pelos cursores; o SDK conserva os filtros da consulta. `GetAutoPagingEnumerable()` e `GetAutoPagingAsyncEnumerable()` carregam as próximas páginas durante a enumeração e podem fazer várias requisições. Limite o trabalho da aplicação e use cancelamento quando necessário. Uma resposta HTTP `202` mantém o significado de resultado pendente. Ela não confirma pagamento nem conclusão financeira e não inicia consultas automáticas. Consulte o recurso ou acompanhe o evento apropriado antes de confirmar o efeito na sua aplicação. ## Idempotência e erros O SDK envia `Idempotency-Key` somente quando a aplicação o informa em um endpoint que aceita esse header. Ele não cria chaves nem repete POST, PATCH ou DELETE automaticamente. Retries de leitura são opcionais; o padrão é zero. Decida o tratamento pelo status HTTP e por `ApiErrorException.ErrorCode`. `RequestId` ajuda a identificar a tentativa. `ErrorMessage` é um diagnóstico humano e não deve ser comparado como código de controle. Não registre a resposta completa, credenciais, documentos pessoais ou links temporários. Consulte [Idempotência](/br/api/idempotencia) e a [referência do SDK](https://github.com/raimshq/raims-dotnet/blob/main/docs/reference.md). As opções usam `Optional` para distinguir um campo omitido de um valor explícito. Em atualizações, omitir preserva o valor; `null` limpa somente os campos cujo contrato permite essa ação. Veja as condições de cada endpoint. ## Usar o Sandbox Use uma chave Sandbox para as simulações em `raims.Simulations.Charges` e `raims.Simulations.Refunds`. Uma chave de Produção não se transforma em Sandbox por usar esses serviços. As regras e condições de cada simulação estão na [referência de Simulações](/br/api/simulations/overview). Requisições que solicitam e-mail ou entregas de webhook podem alcançar destinos externos mesmo em Sandbox. Use somente destinos autorizados para a integração. ## Receber webhooks Leia os bytes originais do corpo e os headers recebidos pelo seu servidor: ```csharp using System.Collections.Generic; using Raims; var headers = new Dictionary { ["webhook-id"] = receivedDeliveryId, ["webhook-timestamp"] = receivedTimestamp, ["webhook-signature"] = receivedSignature, }; var webhookEvent = WebhookUtility.ConstructEvent(rawBodyBytes, headers, webhookSecret); ``` `webhookSecret` é o `secret_key` retornado ao criar ou rotacionar o webhook, e não a chave Bearer da API. Não reserialize o JSON antes de autenticar. Uma falha gera `SignatureVerificationException`; não processe o corpo nesse caso. A assinatura válida não elimina duplicidades. Confira tipo e ambiente, deduplique pelo `id` do evento e grave o trabalho de forma durável antes de responder com sucesso. O header `webhook-id` identifica a entrega e não substitui o identificador do evento. Consulte [Receber eventos](/br/integracoes/webhooks/receber-eventos). ## Atualizar o SDK Para buscar a versão estável mais recente no NuGet, execute novamente o comando sem informar um número de versão: ```bash dotnet add package Raims ``` O NuGet atualiza a referência do projeto. Confira as [releases](https://github.com/raimshq/raims-dotnet/releases) e teste os fluxos usados pela sua integração. A versão do SDK é independente da versão HTTP `/v1` da API. Os guias completos de configuração, paginação, erros e webhooks estão no [repositório do SDK](https://github.com/raimshq/raims-dotnet). # SDK Elixir (/br/integracoes/sdk-elixir) O SDK oficial Elixir integra aplicações de servidor à API pública da Raims. Use módulos por recurso, modelos de resposta, paginação e verificação de webhooks. A chave da API deve permanecer no backend, fora de aplicações distribuídas aos clientes e dos logs. A [referência do SDK](https://github.com/raimshq/raims-elixir/blob/main/docs/reference.md) lista os métodos e parâmetros de cada recurso. ## Instalar o SDK Use Elixir 1.18 ou superior com Erlang/OTP 27 ou superior. O pacote oficial [`raims`](https://hex.pm/packages/raims) está disponível no Hex. Se o Hex ainda não estiver instalado, instale-o uma vez: ```bash mix local.hex ``` Na raiz do projeto, consulte a versão estável e a configuração atuais: ```bash mix hex.info raims ``` Copie a linha `Config:` para a lista devolvida por `deps/0` no `mix.exs` da aplicação. Em seguida, busque as dependências e compile: ```bash mix deps.get mix compile ``` O Mix resolve as dependências conforme a configuração e registra as versões em `mix.lock`. Preserve esse arquivo para repetir a instalação. As [releases do GitHub](https://github.com/raimshq/raims-elixir/releases/latest) continuam fornecendo os fontes e o arquivo de distribuição. Para instalar por Git ou por um diretório local, consulte as [instruções do repositório](https://github.com/raimshq/raims-elixir/blob/main/docs/installation.md). ## Configurar o cliente Obtenha uma chave em [Chaves de API](/br/integracoes/chaves-api) e armazene-a em uma variável protegida ou no cofre da aplicação. Ela define empresa, ambiente e permissões. A URL é `https://api.raims.com` em Sandbox e Produção. ```elixir client = Raims.Client.new(System.fetch_env!("RAIMS_API_KEY"), timeout: 30_000, max_network_retries: 0 ) {:ok, balance} = Raims.Balances.retrieve(client) request_id = balance.request_id ``` Timeouts usam milissegundos. O cliente é imutável e pode ser reutilizado; não mantém um processo que precise ser encerrado. Cada tentativa HTTP fecha sua conexão ao terminar. Os exemplos seguintes usam esse `client`. ## Criar um cliente e uma cobrança `customer_tax_id` contém o CPF ou CNPJ válido do cliente autorizado. `customer_key` e `charge_key` são chaves distintas, persistidas antes das requisições. Persista também `due_date_unix`, o vencimento em segundos Unix UTC. ```elixir with {:ok, customer} <- Raims.Customers.create(client, %{tax_id: customer_tax_id}, idempotency_key: customer_key ), {:ok, charge} <- Raims.Charges.create( client, %{ customer_id: customer.data["id"], amount_cents: 15000, due_date: due_date_unix, title: "Pedido 1234" }, idempotency_key: charge_key ) do {:ok, charge.data["id"], charge.status_code} else {:error, error} -> {:error, error.kind, error.request_id} end ``` `15000` representa R$ 150,00. Mapas aceitam chaves atom ou string com os nomes JSON. Omitir um campo o mantém ausente; `nil` envia null onde permitido. Em uma atualização, `%{external_reference: nil}` pode limpar a referência; omiti-la preserva o valor. As respostas usam `response.data`; `Access.fetch/2` distingue um campo ausente de um campo com `nil`. ## Paginação e resultados pendentes ```elixir {:ok, first_page} = Raims.Customers.list(client, %{page_size: 50}) first_page |> Raims.Page.stream() |> Stream.map(fn customer -> customer["id"] end) |> Enum.take(100) ``` A lista de uma resposta contém só a página recebida. `Raims.Page.stream/1` busca novas páginas sob demanda; `Enum.take/2` limita a coleta. O stream levanta `Raims.Error` se uma página falhar. `next_page/1` e `previous_page/1` retornam `{:ok, response}`, `{:ok, nil}` ou `{:error, error}` e preservam filtros e opções. Não envie `after` e `before` juntos. HTTP `202` aceita trabalho com resultado pendente. Consulte o recurso ou acompanhe o evento apropriado antes de confirmar seu efeito financeiro. ## Idempotência e erros ```elixir case Raims.Customers.retrieve(client, customer_id) do {:ok, response} -> MyApp.process_customer(response.data) {:error, error} -> MyApp.handle_failure(error.kind, error.status_code, error.code, error.request_id) end ``` `MyApp` representa seu tratamento de negócio. As funções retornam tuplas `{:ok, response}` ou `{:error, %Raims.Error{}}`; variantes com `!` levantam a exceção. Argumentos locais inválidos geram `ArgumentError`. Use categoria, status, código e Request-Id, sem registrar corpos ou credenciais. O SDK não gera idempotência nem repete escritas. Após perder uma resposta, consulte a operação; quando for permitido repetir, use a mesma chave e os mesmos parâmetros. `max_network_retries` habilita somente retries de leituras GET/HEAD elegíveis, com padrão zero. Esperas, `Retry-After` e tentativas compartilham o orçamento de timeout. Veja [Idempotência](/br/api/idempotencia). ## Usar o Sandbox Use uma chave Sandbox e um recurso desse ambiente: ```elixir sandbox = Raims.Client.new(System.fetch_env!("RAIMS_SANDBOX_API_KEY")) {:ok, result} = Raims.Simulations.Charges.confirm_payment(sandbox, sandbox_charge_id) ``` O SDK não seleciona nem troca o ambiente de uma credencial. As simulações financeiras aceitam somente Sandbox; uma chave de Produção continua sendo de Produção em um host local. Consulte [Simulações](/br/api/simulations/overview). E-mails e webhooks podem alcançar destinos externos mesmo nesse ambiente; use somente destinos autorizados. ## Receber webhooks Use o binário original `raw_body` e uma lista de pares de headers recebidos com `webhook-id`, `webhook-timestamp` e `webhook-signature`. A lista preserva duplicidades para que o verificador rejeite ambiguidade. ```elixir case Raims.Webhook.construct_event(raw_body, signing_headers, webhook_secret) do {:ok, event} -> MyApp.persist_event(event) {:error, error} -> MyApp.reject_delivery(error) end ``` `webhook_secret` é o `secret_key` do webhook mantido no cofre; os handlers `MyApp` pertencem à aplicação. Não parseie e reconstrua o JSON antes de verificar a assinatura. O padrão de tolerância é 300 segundos, com relógio sincronizado. `verify_signature/4` permite verificar sem decodificar o JSON. Após verificar, confira tipo e ambiente, deduplique pelo `id` do evento e grave o trabalho de forma durável antes de responder com sucesso. Uma assinatura válida não impede reentregas; `webhook-id` identifica a entrega. Veja [Receber eventos](/br/integracoes/webhooks/receber-eventos). ## Atualizar o SDK Consulte a versão estável e a configuração atuais: ```bash mix hex.info raims ``` Se necessário, ajuste a declaração em `deps/0` com a linha `Config:` exibida pelo Hex. Depois atualize o SDK dentro das restrições declaradas: ```bash mix deps.update raims mix compile ``` Se a dependência usava `github:`, `git:` ou `path:`, substitua essa declaração pela configuração atual do Hex e execute os mesmos comandos. Remova também as opções exclusivas do Git, como `ref:`, `branch:` e `tag:`. Os módulos `Raims` continuam iguais. Revise e preserve o `mix.lock` atualizado. Confira as [notas da release](https://github.com/raimshq/raims-elixir/releases/latest) e teste os fluxos usados pela integração antes de atualizar a aplicação. A instalação não aplica atualizações futuras automaticamente. # SDK Go (/br/integracoes/sdk-go) Use o módulo `github.com/raimshq/raims-go` no backend da integração. O SDK oferece serviços por recurso, parâmetros e respostas tipados, paginação por cursor e autenticação de webhooks. ## Instalar o pacote O SDK requer Go 1.26.5 ou superior. No projeto que contém o `go.mod`: ```bash go get github.com/raimshq/raims-go@latest ``` O Go resolve a versão estável mais recente do módulo e registra a dependência na aplicação. Mantenha `go.mod` e `go.sum` junto do projeto. ## Configurar o cliente Obtenha uma chave em [Chaves de API](/br/integracoes/chaves-api) e guarde-a no cofre ou em uma variável de ambiente protegida da aplicação. Mantenha a credencial no backend, fora do navegador, de aplicações distribuídas aos seus clientes e dos logs. Empresa, ambiente e permissões são determinados pela chave validada na API. Sandbox e Produção usam `https://api.raims.com`. ```go package main import ( "context" "fmt" "log" "os" raims "github.com/raimshq/raims-go" ) func main() { client, err := raims.NewClient(os.Getenv("RAIMS_API_KEY"), raims.WithMaxNetworkRetries(0), ) if err != nil { log.Fatal(err) } defer client.CloseIdleConnections() page, err := client.Customers.List(context.Background(), &raims.ListCustomersParams{ PageSize: raims.Set[int64](20), }) if err != nil { log.Fatal(err) } for _, customer := range page.List { fmt.Println(customer.ID) } } ``` Reutilize o cliente entre requisições e goroutines. `context.Context` permite cancelar chamadas e limitar sua duração. Encerre conexões ociosas ao finalizar o uso. Os próximos trechos consideram `client` configurado e um contexto `ctx` da aplicação. ## Criar um cliente e uma cobrança `customerTaxID` é o CPF ou CNPJ válido do cliente autorizado. `customerIdempotencyKey` e `chargeIdempotencyKey` são chaves distintas criadas e persistidas antes das requisições. `chargeDueDate` é um `int64` com o vencimento escolhido e persistido, em segundos Unix UTC. O trecho abaixo pertence a uma função que retorna `error`. ```go customer, err := client.Customers.Create(ctx, &raims.CreateCustomerParams{ TaxID: raims.Set(customerTaxID), }, raims.WithIdempotencyKey(customerIdempotencyKey)) if err != nil { return err } charge, err := client.Charges.Create(ctx, &raims.CreateChargeParams{ CustomerID: raims.Set(customer.ID), AmountCents: raims.Set[int64](15000), DueDate: raims.Set(chargeDueDate), Title: raims.Set("Pedido 1234"), }, raims.WithIdempotencyKey(chargeIdempotencyKey)) if err != nil { return err } fmt.Println(charge.LastResponse.StatusCode, charge.LastResponse.RequestID) ``` Se o CPF ou CNPJ já existir na mesma empresa e ambiente, o cadastro é atualizado e mantém seu identificador. `15000` representa R$ 150,00. Preserve a chave e todos os parâmetros, inclusive o vencimento, ao recuperar a mesma intenção após perder uma resposta. Consulte [Criar cobrança](/br/api/charges). `Optional[T]` preserva a diferença entre omitir um campo, enviar um valor com `Set` e enviar null com `Null[T]()`. Consulte o contrato do campo antes de limpar um valor. ## Paginação e resultados pendentes `List` busca uma página, disponível em `page.List`. `NextPage(ctx)` e `PreviousPage(ctx)` preservam filtros e retornam `nil` quando não há continuação. `ListAll` avança conforme o consumo; interromper o loop impede novas buscas. `processCustomer` representa o tratamento da aplicação. ```go for customer, err := range client.Customers.ListAll(ctx, nil).All() { if err != nil { return err } processCustomer(customer.ID) } ``` Copie os cursores recebidos e mantenha os filtros; não envie `after` e `before` juntos. Consulte [Listagem e paginação](/br/api/listagem-e-paginacao). Uma resposta HTTP `202` indica resultado pendente. Ela não confirma pagamento nem conclusão financeira e não inicia consultas automáticas. Consulte o recurso ou acompanhe o evento apropriado antes de confirmar o efeito na aplicação. ## Idempotência e erros Use `errors.As` para identificar `*raims.APIError` e decida pelo `StatusCode` e `Code`. `Response.RequestID` identifica a tentativa quando há resposta. `ConnectionError` indica falha de transporte e pode deixar uma escrita inconclusiva. `WithMaxNetworkRetries` configura retries somente de GET; o padrão é zero. O SDK envia a chave de idempotência somente quando a aplicação a informa em um endpoint que aceita `Idempotency-Key`. Ele não gera chaves nem repete escritas automaticamente. Um timeout não prova que a escrita foi recusada. Decida pelo status HTTP e pelo código estruturado; `error.message` é um diagnóstico humano que pode mudar. Não registre respostas completas, credenciais, documentos pessoais ou links temporários. Veja [Idempotência](/br/api/idempotencia) e o [guia de erros do SDK](https://github.com/raimshq/raims-go/blob/main/docs/errors-and-retries.md). ## Usar o Sandbox Use uma chave Sandbox para as simulações em `client.Simulations.Charges` e `client.Simulations.Refunds`. Uma chave de Produção não se transforma em Sandbox por usar esses serviços. Confira as condições na [referência de Simulações](/br/api/simulations/overview). Requisições que solicitam e-mail ou entregas de webhook podem alcançar destinos externos mesmo em Sandbox. Use somente destinos autorizados para a integração. ## Receber webhooks `rawBody` contém os bytes recebidos e `headers` contém os headers HTTP originais. O helper retorna o evento autenticado ou um erro; não processe o corpo se a autenticação falhar. ```go import ( "encoding/json" "net/http" "time" raims "github.com/raimshq/raims-go" ) func authenticateDelivery(rawBody []byte, headers http.Header, webhookSecret string) (map[string]json.RawMessage, error) { return raims.ConstructWebhookEvent(rawBody, headers, webhookSecret, raims.DefaultWebhookTolerance, time.Now()) } ``` Use o `secret_key` retornado ao criar ou rotacionar o webhook, diferente da chave Bearer da API. Leia o corpo antes do parser JSON e preserve seus bytes: não reserialize o conteúdo antes de autenticar. Depois da autenticação, confira tipo e ambiente, deduplique pelo `id` do evento e grave o trabalho de forma durável antes de responder com sucesso. O header `webhook-id` identifica a entrega, não o evento. Consulte [Receber eventos](/br/integracoes/webhooks/receber-eventos). ## Atualizar o SDK Execute novamente `go get github.com/raimshq/raims-go@latest` no projeto. Revise as releases e os arquivos `go.mod` e `go.sum`, e teste os fluxos usados pela aplicação antes de implantar a atualização. A versão do SDK é independente da versão HTTP `/v1` da API. Os guias completos e a referência de métodos estão no [repositório do SDK](https://github.com/raimshq/raims-go). # SDK Java (/br/integracoes/sdk-java) Use `com.raims:raims-java` para integrar seu backend Java à API pública. O SDK oferece serviços por recurso, builders tipados, respostas tipadas, paginação por cursor e autenticação de webhooks. ## Instalar o pacote O SDK requer Java 11 ou superior e está no Maven Central como [`com.raims:raims-java`](https://central.sonatype.com/artifact/com.raims/raims-java). Consulte a versão estável atual nesse link e substitua `SDK_VERSION` nos exemplos abaixo por essa versão. Mantenha a versão escolhida na configuração da aplicação. ### Maven Adicione a dependência ao `pom.xml`: ```xml com.raims raims-java SDK_VERSION ``` ### Gradle No `build.gradle`, use o repositório Maven Central e declare a dependência: ```groovy repositories { mavenCentral() } dependencies { implementation 'com.raims:raims-java:SDK_VERSION' } ``` Com Kotlin DSL, no `build.gradle.kts`: ```kotlin repositories { mavenCentral() } dependencies { implementation("com.raims:raims-java:SDK_VERSION") } ``` Maven e Gradle resolvem o SDK e suas dependências transitivas pelo Maven Central. As [releases do GitHub](https://github.com/raimshq/raims-java/releases/latest) também fornecem JAR, POM, fontes, Javadoc e `SHA256SUMS`. Para usar esses arquivos, consulte a [instalação pelo GitHub](https://github.com/raimshq/raims-java/blob/main/docs/installation.md#github-release-downloads). ## Configurar o cliente Obtenha uma chave em [Chaves de API](/br/integracoes/chaves-api) e guarde-a no cofre ou em uma variável de ambiente protegida da aplicação. Mantenha a credencial no backend, fora do navegador, de aplicações distribuídas aos seus clientes e dos logs. Empresa, ambiente e permissões são determinados pela chave validada na API. Sandbox e Produção usam `https://api.raims.com`. ```java import com.raims.RaimsClient; import com.raims.param.ListCustomersParams; try (RaimsClient raims = RaimsClient.builder() .setApiKey(System.getenv("RAIMS_API_KEY")) .setMaxNetworkRetries(0) .build()) { var customers = raims.customers().list( ListCustomersParams.builder().setPageSize(20).build()); customers.getList().forEach(customer -> System.out.println(customer.getId())); } ``` Reutilize uma instância de `RaimsClient` entre chamadas e threads. O cliente implementa `AutoCloseable`; use try-with-resources para um escopo curto ou `close()` ao encerrar o cliente compartilhado. Os próximos trechos consideram `raims` configurado e aberto pela aplicação. ## Criar um cliente e uma cobrança `customerTaxId` é o CPF ou CNPJ válido do cliente autorizado. `customerIdempotencyKey` e `chargeIdempotencyKey` são chaves distintas criadas e persistidas antes das requisições. `chargeDueDate` é um `long` com o vencimento escolhido e persistido, em segundos Unix UTC. ```java import com.raims.RequestOptions; import com.raims.param.CreateCustomerParams; import com.raims.param.CreateChargeParams; var customer = raims.customers().create( CreateCustomerParams.builder().setTaxId(customerTaxId).build(), RequestOptions.builder().setIdempotencyKey(customerIdempotencyKey).build()); var charge = raims.charges().create( CreateChargeParams.builder() .setCustomerId(customer.getId()) .setAmountCents(15000) .setDueDate(chargeDueDate) .setTitle("Pedido 1234") .build(), RequestOptions.builder().setIdempotencyKey(chargeIdempotencyKey).build()); int httpStatus = charge.getLastResponse().getStatusCode(); String requestId = charge.getLastResponse().getRequestId(); ``` Se o CPF ou CNPJ já existir na mesma empresa e ambiente, o cadastro é atualizado e mantém seu identificador. `15000` representa R$ 150,00. Preserve a chave e todos os parâmetros, inclusive o vencimento, ao recuperar a mesma intenção após perder uma resposta. Consulte [Criar cobrança](/br/api/charges). Omitir um setter mantém o campo ausente. Os setters com sufixo `Null` enviam null nos campos que permitem essa ação. Consulte o contrato antes de limpar um valor. ## Paginação e resultados pendentes `list()` busca uma página tipada, com `getList()`. `nextPage()` e `previousPage()` preservam filtros e retornam `null` quando não há continuação. `autoPagingIterable()` avança conforme o consumo; mantenha o cliente aberto durante a enumeração. `processCustomer` representa o tratamento da aplicação. ```java for (var customer : raims.customers().list().autoPagingIterable()) { processCustomer(customer.getId()); } ``` Copie os cursores recebidos e mantenha os filtros; não envie `after` e `before` juntos. Consulte [Listagem e paginação](/br/api/listagem-e-paginacao). Uma resposta HTTP `202` indica resultado pendente. Ela não confirma pagamento nem conclusão financeira e não inicia consultas automáticas. Consulte o recurso ou acompanhe o evento apropriado antes de confirmar o efeito na aplicação. ## Idempotência e erros As falhas usam exceções em `com.raims.exception`. Use `getStatusCode()`, `getCode()` e `getRequestId()` para tratar erros HTTP. Uma falha de conexão pode deixar uma escrita inconclusiva. `setMaxNetworkRetries` configura retries de leitura; o padrão é zero. O SDK envia a chave de idempotência somente quando a aplicação a informa em um endpoint que aceita `Idempotency-Key`. Ele não gera chaves nem repete escritas automaticamente. Um timeout não prova que a escrita foi recusada. Decida pelo status HTTP e pelo código estruturado; `error.message` é um diagnóstico humano que pode mudar. Não registre respostas completas, credenciais, documentos pessoais ou links temporários. Veja [Idempotência](/br/api/idempotencia) e o [guia de erros do SDK](https://github.com/raimshq/raims-java/blob/main/docs/errors-and-retries.md). ## Usar o Sandbox Use uma chave Sandbox para as simulações em `raims.simulations().charges()` e `raims.simulations().refunds()`. Uma chave de Produção não se transforma em Sandbox por usar esses serviços. Confira as condições na [referência de Simulações](/br/api/simulations/overview). Requisições que solicitam e-mail ou entregas de webhook podem alcançar destinos externos mesmo em Sandbox. Use somente destinos autorizados para a integração. ## Receber webhooks `rawBodyBytes` contém os bytes recebidos. `receivedDeliveryId`, `receivedTimestamp` e `receivedSignature` são os valores dos headers do servidor. Rejeite a entrega se `constructEvent` lançar uma exceção de verificação de assinatura. ```java import com.raims.WebhookUtility; import com.google.gson.JsonObject; import java.util.Map; Map headers = Map.of( "webhook-id", receivedDeliveryId, "webhook-timestamp", receivedTimestamp, "webhook-signature", receivedSignature); JsonObject event = WebhookUtility.constructEvent(rawBodyBytes, headers, webhookSecret); ``` Use o `secret_key` retornado ao criar ou rotacionar o webhook, diferente da chave Bearer da API. Leia o corpo antes do parser JSON e preserve seus bytes: não reserialize o conteúdo antes de autenticar. Depois da autenticação, confira tipo e ambiente, deduplique pelo `id` do evento e grave o trabalho de forma durável antes de responder com sucesso. O header `webhook-id` identifica a entrega, não o evento. Consulte [Receber eventos](/br/integracoes/webhooks/receber-eventos). ## Atualizar o SDK Consulte a versão estável atual de [`com.raims:raims-java` no Maven Central](https://central.sonatype.com/artifact/com.raims/raims-java), atualize a versão da dependência no `pom.xml`, `build.gradle` ou `build.gradle.kts` e execute os testes da integração. Se a aplicação instalava o JAR pelo GitHub, as coordenadas `com.raims:raims-java` continuam iguais. Use a versão disponível no Maven Central na dependência da aplicação. A versão do SDK é independente da versão HTTP `/v1` da API. Os guias completos e a referência de métodos estão no [repositório do SDK](https://github.com/raimshq/raims-java). # SDK Node.js (/br/integracoes/sdk-node) Use o pacote `@raimshq/raims` no backend Node.js. O SDK inclui módulos ESM e CommonJS, declarações TypeScript, serviços por recurso, paginação por cursor e autenticação de webhooks. ## Instalar o pacote O SDK requer Node.js 22 ou superior e inclui módulos ESM, CommonJS e tipos TypeScript. No diretório da aplicação: ```bash npm install @raimshq/raims ``` O pacote [`@raimshq/raims`](https://www.npmjs.com/package/@raimshq/raims) inclui o runtime e as declarações de tipos. Preserve o lockfile da aplicação para reproduzir as versões instaladas. As [releases do GitHub](https://github.com/raimshq/raims-node/releases/latest) também oferecem `raims-node.tgz` e `SHA256SUMS`. Para instalar o arquivo, baixe ambos para uma pasta `raims-node-release`, confira o hash e execute: ```bash npm install ./raims-node-release/raims-node.tgz ``` ## Configurar o cliente Obtenha uma chave em [Chaves de API](/br/integracoes/chaves-api) e guarde-a no cofre ou em uma variável de ambiente protegida da aplicação. Mantenha a credencial no backend, fora do navegador, de aplicações distribuídas aos seus clientes e dos logs. Empresa, ambiente e permissões são determinados pela chave validada na API. Sandbox e Produção usam `https://api.raims.com`. ```js import Raims from '@raimshq/raims'; const apiKey = process.env.RAIMS_API_KEY; if (!apiKey) throw new Error('Set RAIMS_API_KEY on the server.'); const raims = new Raims(apiKey, { maxNetworkRetries: 0 }); const customers = await raims.customers.list({ page_size: 20 }); for (const customer of customers.list) { console.log(customer.id); } ``` Reutilize a instância para aproveitar as conexões HTTP. Em CommonJS, importe com `const Raims = require('@raimshq/raims')`. Os próximos trechos consideram `raims` configurado pela aplicação. ## Criar um cliente e uma cobrança `customerTaxId` é o CPF ou CNPJ válido do cliente autorizado. `customerIdempotencyKey` e `chargeIdempotencyKey` são chaves distintas criadas e persistidas antes das requisições. `chargeDueDate` é o vencimento escolhido e persistido, em segundos Unix UTC. ```js const customer = await raims.customers.create( { tax_id: customerTaxId, }, { idempotencyKey: customerIdempotencyKey }, ); const charge = await raims.charges.create( { customer_id: customer.id, amount_cents: 15000, due_date: chargeDueDate, title: 'Pedido 1234', }, { idempotencyKey: chargeIdempotencyKey }, ); const { statusCode, requestId } = charge.lastResponse; ``` Se o CPF ou CNPJ já existir na mesma empresa e ambiente, o cadastro é atualizado e mantém seu identificador. `15000` representa R$ 150,00. Preserve a chave e todos os parâmetros, inclusive o vencimento, ao recuperar a mesma intenção após perder uma resposta. Consulte [Criar cobrança](/br/api/charges). `undefined` omite uma propriedade; `null` é enviado como null. Consulte o contrato antes de limpar um campo. Valores inteiros devem caber em `Number.MAX_SAFE_INTEGER`, sem conversão por números fracionários. ## Paginação e resultados pendentes `await list()` busca uma página em `list`; `nextPage()` e `previousPage()` preservam os filtros e retornam `null` quando não há continuação. `for await` carrega as próximas páginas conforme o consumo; sair do loop impede novas buscas. `processCustomer` representa o tratamento da aplicação. ```js for await (const customer of raims.customers.list({ page_size: 50 })) { await processCustomer(customer.id); } ``` Copie os cursores recebidos e mantenha os filtros; não envie `after` e `before` juntos. Consulte [Listagem e paginação](/br/api/listagem-e-paginacao). Uma resposta HTTP `202` indica resultado pendente. Ela não confirma pagamento nem conclusão financeira e não inicia consultas automáticas. Consulte o recurso ou acompanhe o evento apropriado antes de confirmar o efeito na aplicação. ## Idempotência e erros Os erros HTTP expõem `statusCode`, `code` e `requestId`. `ConnectionError` indica falha de transporte e pode deixar uma escrita inconclusiva. `maxNetworkRetries` configura retries somente de GET; o padrão é zero. O SDK envia a chave de idempotência somente quando a aplicação a informa em um endpoint que aceita `Idempotency-Key`. Ele não gera chaves nem repete escritas automaticamente. Um timeout não prova que a escrita foi recusada. Decida pelo status HTTP e pelo código estruturado; `error.message` é um diagnóstico humano que pode mudar. Não registre respostas completas, credenciais, documentos pessoais ou links temporários. Veja [Idempotência](/br/api/idempotencia) e o [guia de erros do SDK](https://github.com/raimshq/raims-node/blob/main/docs/usage.md). ## Usar o Sandbox Use uma chave Sandbox para as simulações em `raims.simulations.charges` e `raims.simulations.refunds`. Uma chave de Produção não se transforma em Sandbox por usar esses serviços. Confira as condições na [referência de Simulações](/br/api/simulations/overview). Requisições que solicitam e-mail ou entregas de webhook podem alcançar destinos externos mesmo em Sandbox. Use somente destinos autorizados para a integração. ## Receber webhooks `rawBody` contém os bytes originais, como `Buffer` ou `Uint8Array`. `receivedHeaders` contém os headers recebidos. `persistEvent` e `rejectDelivery` representam o tratamento da aplicação; uma falha de persistência deve retornar erro HTTP para permitir nova entrega. ```js import { SignatureVerificationError, Webhook } from '@raimshq/raims'; try { const event = Webhook.constructEvent(rawBody, receivedHeaders, webhookSecret); await persistEvent(event); } catch (error) { if (error instanceof SignatureVerificationError) rejectDelivery(); else throw error; } ``` Use o `secret_key` retornado ao criar ou rotacionar o webhook, diferente da chave Bearer da API. Leia o corpo antes do parser JSON e preserve seus bytes: não reserialize o conteúdo antes de autenticar. Depois da autenticação, confira tipo e ambiente, deduplique pelo `id` do evento e grave o trabalho de forma durável antes de responder com sucesso. O header `webhook-id` identifica a entrega, não o evento. Consulte [Receber eventos](/br/integracoes/webhooks/receber-eventos). ## Atualizar o SDK Para instalar a versão estável atual, execute no diretório da aplicação: ```bash npm install @raimshq/raims@latest ``` Revise as [notas de versão](https://github.com/raimshq/raims-node/releases) e teste os fluxos usados pela integração. Atualizações futuras não são instaladas automaticamente. Se você usa o TGZ, baixe novamente os arquivos da release estável atual, confira o hash e instale o novo arquivo. Ao migrar de um TGZ anterior, substitua a dependência `raims` por `@raimshq/raims` e ajuste os imports e as chamadas de `require`. A versão do SDK é independente da versão HTTP `/v1` da API. Os guias completos e a referência de métodos estão no [repositório do SDK](https://github.com/raimshq/raims-node). # SDK PHP (/br/integracoes/sdk-php) Use o pacote `raims/raims-php` para integrar uma aplicação de servidor em PHP à API pública. O SDK organiza os recursos em serviços, com respostas tipadas, paginação por cursor e validação de assinaturas de webhook. Mantenha a chave de API no backend da integração. Não distribua a credencial em código entregue ao navegador ou em aplicações dos seus clientes. ## Instalar o pacote O SDK requer PHP 8.2 ou superior em 64 bits, Composer 2 e as extensões `curl`, `json` e `hash`. No diretório da aplicação: ```bash composer require raims/raims-php ``` O pacote está no [Packagist](https://packagist.org/packages/raims/raims-php). Sem informar a versão, o Composer instala a versão estável mais recente compatível com o projeto e registra a restrição em `composer.json`. Mantenha o `composer.lock` da aplicação para repetir a instalação da mesma versão. Confira as extensões e a plataforma com `composer check-platform-reqs` após instalar. O SDK não exige bibliotecas de terceiros em produção. ## Configurar o cliente Obtenha uma chave em [Chaves de API](/br/integracoes/chaves-api) e armazene-a em uma variável de ambiente protegida ou no cofre da aplicação. Empresa, ambiente e permissões são determinados pela credencial validada na API. Sandbox e Produção usam `https://api.raims.com`. ```php customers->all(['page_size' => 20]); foreach ($customers as $customer) { echo $customer->id, PHP_EOL; } ``` Reutilize a instância para aproveitar as conexões HTTP. Os próximos trechos consideram a variável `$raims` configurada pela aplicação. ## Criar um cliente e uma cobrança `$customerTaxId` é o CPF ou CNPJ válido do cliente autorizado pela aplicação. `$customerIdempotencyKey` e `$chargeIdempotencyKey` são chaves distintas, criadas e persistidas antes das requisições. `$chargeDueDate` é o vencimento escolhido e persistido para o pedido, em segundos Unix UTC. ```php $customer = $raims->customers->create([ 'tax_id' => $customerTaxId, ], [ 'idempotency_key' => $customerIdempotencyKey, ]); $charge = $raims->charges->create([ 'customer_id' => $customer->id, 'amount_cents' => 15000, 'due_date' => $chargeDueDate, 'title' => 'Pedido 1234', ], [ 'idempotency_key' => $chargeIdempotencyKey, ]); $httpStatus = $charge->getLastResponse()->statusCode; $requestId = $charge->getLastResponse()->getRequestId(); ``` Se o CPF ou CNPJ já existir na mesma empresa e ambiente, o cadastro do cliente é atualizado e mantém seu identificador. `15000` representa R$ 150,00. Consulte os campos e condições em [Criar cobrança](/br/api/charges). Para repetir a mesma intenção após perder a resposta, conserve a chave e todos os parâmetros, inclusive o vencimento. A referência externa do pedido não substitui a idempotência. ## Paginação e resultados pendentes `all()` busca uma página. Enumerar essa página não faz novas requisições. Use `nextPage()` e `previousPage()` para navegar; o SDK conserva os filtros e retorna `null` quando não há página na direção escolhida. `autoPagingIterator()` carrega as próximas páginas durante a enumeração e pode fazer várias requisições. Sair do `foreach` interrompe novas buscas. Copie os cursores recebidos e mantenha os filtros; não envie `after` e `before` juntos. Consulte [Listagem e paginação](/br/api/listagem-e-paginacao). Uma resposta HTTP `202` mantém o significado de resultado pendente. Ela não confirma pagamento nem conclusão financeira e não inicia consultas automáticas. Consulte o recurso ou acompanhe o evento apropriado antes de confirmar o efeito na sua aplicação. ## Idempotência e erros Informe `idempotency_key` nas opções da requisição somente nos endpoints que aceitam `Idempotency-Key`. O SDK não cria chaves nem repete POST, PATCH ou DELETE automaticamente. Retries de leitura são opcionais; o padrão é zero. Trate falhas HTTP por `ApiErrorException`, usando `getHttpStatus()` e `getErrorCode()`. `getRequestId()` ajuda a identificar a tentativa. O texto de `error.message` é um diagnóstico humano e não deve ser comparado como código de controle. Não registre respostas completas, credenciais, documentos pessoais ou links temporários. Consulte [Idempotência](/br/api/idempotencia) e o [guia de erros do SDK](https://github.com/raimshq/raims-php/blob/main/docs/errors-and-retries.md). Em atualizações, omitir um campo preserva seu valor. Enviar `null` limpa somente os campos cujo contrato permite essa ação. Um objeto vazio em uma entrada usa `(object) []`; um array PHP vazio representa uma lista. Veja as condições de cada endpoint. ## Usar o Sandbox Use uma chave Sandbox para as simulações em `$raims->simulations->charges` e `$raims->simulations->refunds`. Uma chave de Produção não se transforma em Sandbox por usar esses serviços. As regras e condições estão na [referência de Simulações](/br/api/simulations/overview). Requisições que solicitam e-mail ou entregas de webhook podem alcançar destinos externos mesmo em Sandbox. Use somente destinos autorizados para a integração. ## Receber webhooks Leia o corpo original e os headers recebidos pelo seu servidor: ```php use Raims\Exception\SignatureVerificationException; use Raims\Webhook; $payload = file_get_contents('php://input'); if ($payload === false) { throw new RuntimeException('Unable to read the request body.'); } $headers = [ 'webhook-id' => $_SERVER['HTTP_WEBHOOK_ID'] ?? '', 'webhook-timestamp' => $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '', 'webhook-signature' => $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '', ]; try { $event = Webhook::constructEvent($payload, $headers, $webhookSecret); } catch (SignatureVerificationException $error) { http_response_code(400); exit; } ``` `$webhookSecret` é o `secret_key` retornado ao criar ou rotacionar o webhook, e não a chave Bearer da API. Preserve os bytes originais e não reserialize o JSON antes de autenticar. Uma falha gera `SignatureVerificationException`; não processe o corpo nesse caso. A assinatura válida não elimina duplicidades. Confira tipo e ambiente, deduplique pelo `id` do evento e grave o trabalho de forma durável antes de responder com sucesso. O header `webhook-id` identifica a entrega e não substitui o identificador do evento. Consulte [Receber eventos](/br/integracoes/webhooks/receber-eventos). ## Atualizar o SDK Para buscar a versão estável mais recente, execute novamente o comando sem informar um número de versão: ```bash composer require raims/raims-php ``` O Composer escolhe a restrição com base nas versões disponíveis e atualiza `composer.json` e `composer.lock`. Confira as [releases](https://github.com/raimshq/raims-php/releases) e teste os fluxos usados pela sua integração. A versão do SDK é independente da versão HTTP `/v1` da API. Os guias completos e a referência dos serviços estão no [repositório do SDK](https://github.com/raimshq/raims-php). # SDK Python (/br/integracoes/sdk-python) Use o pacote `raims` no backend da integração, com clientes síncrono e assíncrono, parâmetros tipados, respostas somente leitura, paginação por cursor e autenticação de webhooks. ## Instalar o pacote O SDK requer Python 3.10 ou superior. No ambiente virtual da aplicação: ```bash python -m pip install raims ``` O pacote [`raims`](https://pypi.org/project/raims/) está no PyPI e mantém o mesmo nome no import. O pip resolve suas dependências. Consulte o [histórico de versões](https://pypi.org/project/raims/#history) e fixe a versão escolhida no `requirements.txt` ou no arquivo de lock da aplicação. As [releases do GitHub](https://github.com/raimshq/raims-python/releases/latest) também fornecem wheel e código-fonte. Para instalar o wheel, baixe o arquivo `.whl` e `SHA256SUMS` para uma pasta `raims-python-release`, preserve o nome original e confira o hash. Em um shell Bash, com apenas esse wheel na pasta: ```bash python -m pip install ./raims-python-release/raims-*.whl ``` No PowerShell, selecione o arquivo baixado: ```powershell $wheels = @([System.IO.Directory]::GetFiles((Resolve-Path ./raims-python-release).Path, '*.whl')) if ($wheels.Count -ne 1) { throw 'Keep exactly one downloaded wheel in this directory.' } python -m pip install $wheels[0] ``` ## Configurar o cliente Obtenha uma chave em [Chaves de API](/br/integracoes/chaves-api) e guarde-a no cofre ou em uma variável de ambiente protegida da aplicação. Mantenha a credencial no backend, fora do navegador, de aplicações distribuídas aos seus clientes e dos logs. Empresa, ambiente e permissões são determinados pela chave validada na API. Sandbox e Produção usam `https://api.raims.com`. ```python import os from raims import RaimsClient api_key = os.environ["RAIMS_API_KEY"] with RaimsClient(api_key, max_network_retries=0) as raims: customers = raims.customers.list({"page_size": 20}) for customer in customers: print(customer.id) ``` Reutilize o cliente durante seu ciclo de uso. `with` encerra o cliente síncrono; para o assíncrono, use `AsyncRaimsClient` com `async with` e `await` nas chamadas. Mantenha uma instância assíncrona por ciclo de vida do event loop. ## Criar um cliente e uma cobrança `customer_tax_id` é o CPF ou CNPJ válido do cliente autorizado. `customer_idempotency_key` e `charge_idempotency_key` são chaves distintas criadas e persistidas antes das requisições. `charge_due_date` é o vencimento escolhido e persistido, em segundos Unix UTC. ```python from raims import RequestOptions with RaimsClient(api_key) as raims: customer = raims.customers.create( {"tax_id": customer_tax_id}, options=RequestOptions(idempotency_key=customer_idempotency_key), ) charge = raims.charges.create( { "customer_id": customer.id, "amount_cents": 15000, "due_date": charge_due_date, "title": "Pedido 1234", }, options=RequestOptions(idempotency_key=charge_idempotency_key), ) response = charge.last_response if response is not None: print(response.status_code, response.request_id) ``` Se o CPF ou CNPJ já existir na mesma empresa e ambiente, o cadastro é atualizado e mantém seu identificador. `15000` representa R$ 150,00. Preserve a chave e todos os parâmetros, inclusive o vencimento, ao recuperar a mesma intenção após perder uma resposta. Consulte [Criar cobrança](/br/api/charges). As entradas mantêm os nomes JSON da API. Omitir uma chave mantém o campo ausente; `None` envia null. Consulte o contrato antes de limpar um valor. Respostas preservam campos futuros e não devem ser alteradas diretamente. ## Paginação e resultados pendentes `list()` busca uma página. A iteração normal lê somente os itens recebidos; `next_page()` e `previous_page()` preservam os filtros. `auto_paging_iter()` carrega as próximas páginas conforme o consumo. No cliente assíncrono, use `await` na consulta e `async for` no iterador. `process_customer` representa o tratamento da aplicação. ```python with RaimsClient(api_key) as raims: page = raims.customers.list({"page_size": 50}) for customer in page.auto_paging_iter(): process_customer(customer.id) ``` Copie os cursores recebidos e mantenha os filtros; não envie `after` e `before` juntos. Consulte [Listagem e paginação](/br/api/listagem-e-paginacao). Uma resposta HTTP `202` indica resultado pendente. Ela não confirma pagamento nem conclusão financeira e não inicia consultas automáticas. Consulte o recurso ou acompanhe o evento apropriado antes de confirmar o efeito na aplicação. ## Idempotência e erros Trate erros HTTP por `ApiError`, usando `status_code`, `code` e `request_id`. `ConnectionError` indica falha de transporte e pode deixar uma escrita inconclusiva. `max_network_retries` configura retries somente de leitura; o padrão é zero. O SDK envia a chave de idempotência somente quando a aplicação a informa em um endpoint que aceita `Idempotency-Key`. Ele não gera chaves nem repete escritas automaticamente. Um timeout não prova que a escrita foi recusada. Decida pelo status HTTP e pelo código estruturado; `error.message` é um diagnóstico humano que pode mudar. Não registre respostas completas, credenciais, documentos pessoais ou links temporários. Veja [Idempotência](/br/api/idempotencia) e o [guia de erros do SDK](https://github.com/raimshq/raims-python/blob/main/docs/errors-and-retries.md). ## Usar o Sandbox Use uma chave Sandbox para as simulações em `raims.simulations.charges` e `raims.simulations.refunds`. Uma chave de Produção não se transforma em Sandbox por usar esses serviços. Confira as condições na [referência de Simulações](/br/api/simulations/overview). Requisições que solicitam e-mail ou entregas de webhook podem alcançar destinos externos mesmo em Sandbox. Use somente destinos autorizados para a integração. ## Receber webhooks `raw_body` contém os bytes recebidos e `received_headers` contém `webhook-id`, `webhook-timestamp` e `webhook-signature`. `reject_delivery` e `persist_event` representam o tratamento da aplicação. Não processe a entrega cuja assinatura falhou. ```python from raims import SignatureVerificationError, Webhook try: event = Webhook.construct_event(raw_body, received_headers, webhook_secret) except SignatureVerificationError: reject_delivery() else: persist_event(event) ``` Use o `secret_key` retornado ao criar ou rotacionar o webhook, diferente da chave Bearer da API. Leia o corpo antes do parser JSON e preserve seus bytes: não reserialize o conteúdo antes de autenticar. Depois da autenticação, confira tipo e ambiente, deduplique pelo `id` do evento e grave o trabalho de forma durável antes de responder com sucesso. O header `webhook-id` identifica a entrega, não o evento. Consulte [Receber eventos](/br/integracoes/webhooks/receber-eventos). ## Atualizar o SDK Para instalar a versão estável atual, execute no ambiente da aplicação: ```bash python -m pip install --upgrade raims ``` Revise as [notas da release](https://github.com/raimshq/raims-python/releases) e teste os fluxos usados pela integração. Fixe a versão e as dependências na configuração da aplicação para reproduzir a instalação. Atualizações futuras não são instaladas automaticamente. Se instalou pelo GitHub, o import `raims` permanece igual. Atualize a origem da dependência na configuração da aplicação se ela fixar uma URL Git ou um arquivo local. Para continuar usando o wheel do GitHub, baixe os arquivos da nova release, confira o hash e instale o novo wheel com `--upgrade`. A versão do SDK é independente da versão HTTP `/v1` da API. Os guias completos e a referência de métodos estão no [repositório do SDK](https://github.com/raimshq/raims-python). # SDK Ruby (/br/integracoes/sdk-ruby) O SDK oficial Ruby integra aplicações de servidor à API pública da Raims. Ele oferece serviços por recurso, respostas tipadas, paginação por cursor e verificação de webhooks. Mantenha a chave de API no backend, fora do código distribuído aos seus clientes e dos logs. A [referência do SDK](https://github.com/raimshq/raims-ruby/blob/main/docs/reference.md) lista os métodos e parâmetros de cada recurso. ## Instalar o SDK Use Ruby 3.3 ou superior. A gem [`raims`](https://rubygems.org/gems/raims) está no RubyGems. Instale no ambiente da aplicação: ```bash gem install raims ``` Com Bundler, adicione a dependência ao `Gemfile`, usando o RubyGems como fonte: ```ruby source 'https://rubygems.org' gem 'raims' ``` Instale as dependências: ```bash bundle install ``` RubyGems e Bundler resolvem as dependências declaradas pela gem. Preserve o `Gemfile.lock` da aplicação para manter as versões escolhidas. O SDK é carregado com `require 'raims'`. As [releases estáveis do GitHub](https://github.com/raimshq/raims-ruby/releases/latest) também fornecem `raims.gem` e `SHA256SUMS`. Para instalar por arquivo, baixe ambos em um diretório novo, pela página da release ou pelo GitHub CLI: ```bash gh release download --repo raimshq/raims-ruby --pattern raims.gem --pattern SHA256SUMS --dir raims-ruby-release ``` Confira a origem do download e compare o SHA-256 de `raims.gem` com sua entrada em `SHA256SUMS`. Instale o arquivo local: ```bash gem install ./raims-ruby-release/raims.gem ``` ## Configurar o cliente Obtenha uma credencial em [Chaves de API](/br/integracoes/chaves-api) e armazene-a em `RAIMS_API_KEY` ou no cofre da aplicação. A chave define empresa, ambiente e permissões. Sandbox e Produção usam `https://api.raims.com`. ```ruby require 'raims' raims = Raims::RaimsClient.new(ENV.fetch('RAIMS_API_KEY')) begin balance = raims.balances.retrieve request_id = balance.last_response.request_id ensure raims.close end ``` Reutilize o cliente e feche-o ao encerrar seu uso. `RaimsClient.open` com bloco também garante fechamento. Os trechos seguintes pressupõem uma instância `raims` aberta. Timeouts usam segundos; retries de leitura ficam desativados por padrão. ## Criar um cliente e uma cobrança Defina `customer_tax_id` com o CPF ou CNPJ válido do cliente autorizado. Crie e persista `customer_key` e `charge_key`, distintas para cada intenção, antes de enviar. `due_date_unix` é o vencimento escolhido para a cobrança, em segundos Unix UTC; preserve-o quando repetir a mesma intenção. ```ruby customer = raims.customers.create( {tax_id: customer_tax_id}, {idempotency_key: customer_key} ) charge = raims.charges.create( {customer_id: customer.id, amount_cents: 15000, due_date: due_date_unix, title: 'Pedido 1234'}, {idempotency_key: charge_key} ) pending = charge.last_response.status_code == 202 ``` `15000` representa R$ 150,00. As entradas usam hashes com nomes JSON; campos omitidos ficam ausentes e `nil` envia JSON `null` quando permitido. Por exemplo, `raims.customers.update(customer.id, {external_reference: nil})` limpa essa referência; omiti-la preserva o valor. Respostas oferecem leitores como `customer.id`; use `key?` para distinguir ausência de null. ## Paginação e resultados pendentes ```ruby page = raims.customers.list({page_size: 50}) page.auto_paging_each do |customer| process_customer(customer) end ``` `process_customer` pertence à aplicação. `each` percorre apenas a página recebida; `auto_paging_each` busca as seguintes e preserva filtros e opções. `next_page` e `previous_page` retornam outra página ou `nil`. Não combine `after` e `before` nem interprete os cursores. HTTP `202` indica resultado pendente. Consulte o recurso ou processe o webhook adequado antes de confirmar um pagamento, estorno ou cancelamento. ## Idempotência e erros ```ruby begin customer = raims.customers.retrieve(customer_id) rescue Raims::RaimsError => error handle_failure(error.http_status, error.code, error.request_id) end ``` `handle_failure` representa seu tratamento de falhas. Use status, código e Request-Id; mensagens humanas não são códigos de controle. `ArgumentError` indica argumentos locais inválidos. Não registre credenciais, corpos completos ou links temporários. O SDK não gera chaves de idempotência nem repete escritas automaticamente. Após perder uma resposta, consulte o recurso e, quando o endpoint permitir repetir a requisição, reutilize chave e parâmetros originais. Configure `max_network_retries` no cliente ou nas opções para repetir somente leituras GET/HEAD elegíveis. O padrão é zero; `Retry-After` é respeitado dentro da política de espera do SDK. Veja [Idempotência](/br/api/idempotencia). ## Usar o Sandbox Use uma chave Sandbox e uma cobrança desse ambiente: ```ruby Raims::RaimsClient.open(ENV.fetch('RAIMS_SANDBOX_API_KEY')) do |sandbox| result = sandbox.simulations.charges.confirm_payment(sandbox_charge_id) end ``` O SDK não transforma uma chave de Produção em Sandbox e não oferece seletor de ambiente. Consulte as condições em [Simulações](/br/api/simulations/overview). Pedidos de envio por e-mail e entregas de webhook podem alcançar destinos externos mesmo no Sandbox; use destinos autorizados. ## Receber webhooks Preserve `raw_body`, a string com os bytes originais recebidos pelo servidor, e `signing_headers`, o hash com `webhook-id`, `webhook-timestamp` e `webhook-signature`. Preserve ocorrências repetidas para rejeitar ambiguidade. ```ruby begin event = Raims::Webhook.construct_event( raw_body, signing_headers, ENV.fetch('RAIMS_WEBHOOK_SECRET') ) persist_event(event) rescue Raims::SignatureVerificationError reject_delivery end ``` `persist_event` e `reject_delivery` são responsabilidades da aplicação. `RAIMS_WEBHOOK_SECRET` contém o `secret_key` do webhook, não a chave da API. Não reserialize o JSON antes da verificação. Em falha, não processe o evento. A tolerância padrão é de 300 segundos; mantenha o relógio sincronizado. Uma assinatura válida não elimina reentregas: confira tipo e ambiente, deduplique pelo `id` do evento e grave o trabalho de forma durável antes de responder com sucesso. `webhook-id` identifica a entrega. Veja [Receber eventos](/br/integracoes/webhooks/receber-eventos). ## Atualizar o SDK Em aplicações com Bundler, atualize a gem e suas dependências conforme as restrições do `Gemfile`: ```bash bundle update raims ``` Revise e preserve o `Gemfile.lock` atualizado. Em uma instalação gerenciada diretamente pelo RubyGems, use: ```bash gem update raims ``` Se o `Gemfile` usava os fontes baixados do GitHub, substitua a declaração com `path:` ou `git:` por `gem 'raims'`, com a fonte `https://rubygems.org`, e execute `bundle update raims`. O `require 'raims'` permanece igual. Confira o [histórico de versões](https://rubygems.org/gems/raims/versions) e teste os fluxos usados pela integração antes de atualizar a aplicação. A instalação não ativa atualizações automáticas futuras. # SDK Rust (/br/integracoes/sdk-rust) O SDK oficial Rust oferece serviços tipados, paginação e verificação de webhooks para integrar servidores à API pública. Mantenha a chave da API no backend, sem distribuí-la em aplicações dos clientes. A [referência do SDK](https://github.com/raimshq/raims-rust/blob/main/docs/reference.md) lista os métodos e parâmetros de cada recurso. ## Instalar o SDK Use Rust 1.90 ou superior e um runtime Tokio. O crate oficial [`raims`](https://crates.io/crates/raims) está disponível no crates.io. No diretório da aplicação: ```bash cargo add raims cargo add tokio --features macros,rt-multi-thread ``` Cargo consulta o crates.io, seleciona a versão estável compatível e registra as versões resolvidas em `Cargo.lock`. Preserve o lockfile para repetir a instalação. As [releases no GitHub](https://github.com/raimshq/raims-rust/releases/latest) continuam fornecendo fontes e o arquivo `.crate`. Para instalar por Git ou por um diretório local, consulte as [instruções do repositório](https://github.com/raimshq/raims-rust/blob/main/docs/installation.md). ## Configurar o cliente Obtenha uma chave em [Chaves de API](/br/integracoes/chaves-api), guardada em `RAIMS_API_KEY` ou no cofre da aplicação. Ela define empresa, ambiente e permissões. Sandbox e Produção usam `https://api.raims.com`. ```rust use raims::RaimsClient; #[tokio::main] async fn main() -> Result<(), Box> { let client = RaimsClient::new(std::env::var("RAIMS_API_KEY")?)?; let balance = client.balances().retrieve().await?; println!("HTTP status: {}", balance.last_response.status_code); Ok(()) } ``` Reutilize o cliente; seus clones compartilham o pool HTTP. Os demais trechos com `await` pertencem a funções assíncronas que retornam `Result`. Use `RaimsClient::builder` com `timeout`, recebendo `std::time::Duration`, e `max_read_retries` para configurar timeout e retries de leitura. O timeout inclui tentativas e esperas; o padrão de retries é zero. ## Criar um cliente e uma cobrança `customer_tax_id`, `customer_key` e `charge_key` são `String` da aplicação. O primeiro é um CPF ou CNPJ válido e autorizado; as chaves são distintas e persistidas antes de enviar. `due_date_unix` é um `i64` em segundos Unix UTC, escolhido e persistido para essa cobrança. ```rust use raims::{params::{CreateCustomerParams, CreateChargeParams}, Optional, RequestOptions}; let customer_params = CreateCustomerParams { tax_id: Optional::Value(customer_tax_id), ..Default::default() }; let customer_options = RequestOptions { idempotency_key: Some(customer_key), ..Default::default() }; let customer = client.customers() .create_with_options(&customer_params, &customer_options).await?; let charge_params = CreateChargeParams { customer_id: Optional::Value(customer.data.id), amount_cents: Optional::Value(15000), due_date: Optional::Value(due_date_unix), title: Optional::Value("Pedido 1234".to_owned()), ..Default::default() }; let charge_options = RequestOptions { idempotency_key: Some(charge_key), ..Default::default() }; let charge = client.charges() .create_with_options(&charge_params, &charge_options).await?; let pending = charge.last_response.status_code == 202; ``` `15000` representa R$ 150,00. `Optional::Unset` mantém um campo ausente, `Optional::Null` envia null quando permitido e `Optional::Value(...)` define um valor. Nos updates, omissão preserva o campo e null pode limpá-lo conforme o contrato. `ApiResponse` contém `data`, `last_response` e `raw`; use `raw` quando precisar distinguir ausência de null na resposta. ## Paginação e resultados pendentes ```rust use raims::{params::ListCustomersParams, Optional}; let filters = ListCustomersParams { page_size: Optional::Value(50), ..Default::default() }; let mut pages = client.customers().list_pages(&filters)?; while let Some(response) = pages.next_page().await? { for customer in response.data.list { process_customer(customer); } } ``` `process_customer` representa sua aplicação. Criar o pager não envia HTTP; `next_page().await` busca a primeira página e avança pelos cursores. A lista de uma resposta não busca páginas sozinha. O pager preserva filtros e opções; uma falha não avança o cursor. Use `previous_page().await` para voltar. Cursores são opacos; não combine `after` e `before`. HTTP `202` mantém resultado pendente. Consulte o recurso ou acompanhe o webhook adequado antes de confirmar pagamento, estorno ou cancelamento. ## Idempotência e erros ```rust match client.customers().retrieve(&customer_id).await { Ok(response) => process_customer(response.data), Err(error) => handle_failure( error.kind(), error.status_code(), error.code(), error.request_id() ), } ``` Os handlers pertencem à aplicação. Requisições retornam `Result, Error>`; `kind()`, `status_code()`, `code()` e `request_id()` ajudam a decidir a ação. Não use a mensagem humana como código nem registre corpos ou segredos. O SDK não gera chaves nem repete escritas automaticamente. Quando uma resposta se perder, reconcilie a operação e preserve a chave e os parâmetros originais se o endpoint permitir nova tentativa. `max_read_retries` permite somente retries de leituras elegíveis. `Retry-After` e as tentativas ficam no orçamento de timeout; um cancelamento local não desfaz trabalho aceito pela API. Consulte [Idempotência](/br/api/idempotencia). ## Usar o Sandbox Use uma credencial Sandbox e uma cobrança desse ambiente: ```rust let sandbox = RaimsClient::new(std::env::var("RAIMS_SANDBOX_API_KEY")?)?; let result = sandbox.simulations().charges() .confirm_payment(&sandbox_charge_id).await?; ``` `sandbox_charge_id` é uma `String` obtida na sua integração Sandbox. O SDK não seleciona ambiente por header nem transforma uma credencial de Produção. Veja [Simulações](/br/api/simulations/overview). E-mails e webhooks ainda podem alcançar destinos externos; use somente destinos autorizados. ## Receber webhooks Preserve `raw_body` como `&[u8]`, `signing_headers` como lista de pares `(&str, &str)` e `webhook_secret` como a string `secret_key` do webhook. Inclua todas as ocorrências de `webhook-id`, `webhook-timestamp` e `webhook-signature`; não as colapse antes de verificar. ```rust use std::time::SystemTime; use raims::{construct_webhook_event, DEFAULT_WEBHOOK_TOLERANCE}; let event = construct_webhook_event( raw_body, &signing_headers, &webhook_secret, DEFAULT_WEBHOOK_TOLERANCE, SystemTime::now(), )?; persist_event(event); ``` `persist_event` pertence à aplicação. A assinatura é conferida antes do JSON; não reserialize o corpo. A tolerância padrão é de cinco minutos nos dois sentidos; mantenha o relógio sincronizado. `verify_webhook_signature` permite autenticar sem decodificar o evento. Confira tipo e ambiente, deduplique o `id` do evento e persista o trabalho antes de retornar sucesso. `webhook-id` identifica a entrega, não substitui o evento. Veja [Receber eventos](/br/integracoes/webhooks/receber-eventos). ## Atualizar o SDK Confira as [notas da release](https://github.com/raimshq/raims-rust/releases/latest) e atualize o SDK dentro do requisito declarado em `Cargo.toml`: ```bash cargo update -p raims ``` Esse comando preserva o requisito existente. Para selecionar a versão estável atual fora desse requisito ou migrar de Git ou de um diretório local, anote as opções da dependência usadas pela aplicação. Remova somente a entrada `raims` do manifesto que a declara e preserve `Cargo.lock`. Se a dependência vier de um workspace, altere a entrada em `[workspace.dependencies]`. Se ela for opcional, preserve e remova temporariamente as referências à dependência em `[features]`, como `dep:raims`, para manter o manifesto válido. Depois da adição, restaure essas declarações junto das opções `optional` e de features. No diretório da aplicação: ```bash cargo add raims ``` Reaplique as opções da dependência, como features, e confira a entrada em `Cargo.toml`: ela deve usar o requisito de versão do registro selecionado pelo Cargo, sem `git`, `path`, `branch`, `tag` ou `rev`. Revise e preserve o `Cargo.lock` atualizado e teste os fluxos usados pela integração antes de atualizar a aplicação. A instalação não aplica atualizações futuras automaticamente. # SDKs oficiais (/br/integracoes/sdks) Os SDKs oficiais conectam o backend da sua aplicação à API pública da Raims. Cada guia reúne requisitos, instalação, configuração, criação de cobranças, paginação, erros e validação de webhooks. ## Escolher um SDK Use o guia da linguagem do seu backend. O canal de instalação varia por SDK: | Linguagem | Guia | Distribuição | | -------------------- | ---------------------------------------- | ------------------------------------- | | C# e .NET | [SDK .NET](/br/integracoes/sdk-dotnet) | NuGet, pacote `Raims` | | PHP | [SDK PHP](/br/integracoes/sdk-php) | Packagist, pacote `raims/raims-php` | | Go | [SDK Go](/br/integracoes/sdk-go) | Módulo Go no GitHub | | Java | [SDK Java](/br/integracoes/sdk-java) | Maven Central, `com.raims:raims-java` | | Python | [SDK Python](/br/integracoes/sdk-python) | PyPI, pacote `raims` | | Node.js e TypeScript | [SDK Node.js](/br/integracoes/sdk-node) | npm, pacote `@raimshq/raims` | | Ruby | [SDK Ruby](/br/integracoes/sdk-ruby) | RubyGems, gem `raims` | | Elixir | [SDK Elixir](/br/integracoes/sdk-elixir) | Hex, pacote `raims` | | Rust | [SDK Rust](/br/integracoes/sdk-rust) | crates.io, crate `raims` | | Delphi | [SDK Delphi](/br/integracoes/sdk-delphi) | Código-fonte nas releases do GitHub | Consulte o guia antes de instalar para conferir a versão da linguagem, as dependências e os requisitos da plataforma. Para atualizar, siga as instruções do mesmo guia e revise as notas da release escolhida. ## Preparar a integração Mantenha a chave de API no servidor. Não a inclua em código entregue ao navegador, aplicativos mobile ou aplicações desktop dos seus clientes. Obtenha a credencial em [Chaves de API](/br/integracoes/chaves-api). A credencial validada determina empresa, ambiente e permissões. Sandbox e Produção usam `https://api.raims.com`; o SDK não troca o ambiente da chave. Comece com uma chave Sandbox e consulte as condições em [Autenticação](/br/integracoes/autenticacao). Os SDKs preservam as regras da API: valores monetários em centavos, datas em segundos Unix UTC, resultados HTTP `202` pendentes e idempotência informada pela aplicação. Confira a [referência da API](/br/api) para os campos e as condições de cada operação. # Validação de CPF e CNPJ (/br/integracoes/validacao-cpf-cnpj) Antes de chamar a API da Raims com `tax_id`, sua integração deve validar o formato e os dígitos verificadores do CPF ou CNPJ no próprio sistema. Faça essa verificação enquanto seu cliente informa o documento, para indicar no próprio campo o que precisa ser corrigido. Isso evita requisições com `tax_id` inválido e erros de validação na aplicação que consome nossa API, oferecendo uma experiência melhor aos seus clientes finais. O campo `tax_id` aceita CPF, CNPJ numérico e CNPJ alfanumérico. A validação confere o formato e os dois dígitos verificadores, que são calculados a partir dos caracteres anteriores. Nas respostas da API, `tax_id_type` identifica o documento retornado em `tax_id`: `cpf` para CPF e `cnpj` para CNPJ, numérico ou alfanumérico. ## Antes de enviar tax\_id Complete estas etapas no seu sistema antes de enviar a requisição aos servidores da Raims: **Receber o documento** Leia como texto. Preserve zeros à esquerda e letras do CNPJ alfanumérico. **Normalizar e validar** Normalize a formatação e confira tamanho, caracteres e dígitos verificadores no backend. **Enviar à API** Envie `tax_id` como string no JSON e trate a resposta da API, que também valida o documento. **Pedir correção** Destaque o campo e preserve o valor digitado. Peça a correção antes de enviar, sem substituir os dígitos. A validação feita no formulário não substitui a validação no backend da integração. Use uma mensagem como "Confira o CPF ou CNPJ informado". Preserve o valor digitado para que seu cliente possa corrigir. A integração deve enviar o documento informado pelo cliente, sem substituir os dígitos verificadores por outros que façam o cálculo passar. ### Exemplo em JavaScript O código em JavaScript serve como referência para implementar a validação na linguagem da sua integração. Aplique as mesmas regras no backend e, quando houver formulário, também na interface para orientar o preenchimento. Neste exemplo, a função retorna o documento normalizado quando ele é válido, ou `null` quando precisa de correção. Ela aceita CPF, CNPJ numérico e CNPJ alfanumérico. ```js title="validacao-cpf-cnpj.js" function normalizeAndValidateTaxId(value) { if (typeof value !== 'string') return null; const input = value.replace(/[\p{White_Space}./-]/gu, ''); if (!/^[0-9A-Za-z]+$/.test(input)) return null; const taxId = input.toUpperCase(); const isCpf = /^[0-9]{11}$/.test(taxId); const isCnpj = /^[0-9A-Z]{12}[0-9]{2}$/.test(taxId); if (!isCpf && !isCnpj) return null; if (isCpf && /^([0-9])\1{10}$/.test(taxId)) return null; const base = taxId.slice(0, -2); if (isCnpj && base === '000000000000') return null; const weights = isCpf ? [11, 10, 9, 8, 7, 6, 5, 4, 3, 2] : [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2]; const first = calculateCheckDigit(base, weights.slice(1)); const second = calculateCheckDigit(`${base}${first}`, weights); return taxId.endsWith(`${first}${second}`) ? taxId : null; } function calculateCheckDigit(base, weights) { const sum = [...base].reduce( (total, character, index) => total + (character.charCodeAt(0) - 48) * weights[index], 0, ); const remainder = sum % 11; return remainder < 2 ? 0 : 11 - remainder; } // Documento ilustrativo usado no manual de cálculo da Receita Federal. const taxId = normalizeAndValidateTaxId('12.abc.345/01de-35'); if (taxId === null) { throw new Error('Confira o CPF ou CNPJ informado'); } const body = { tax_id: taxId }; // { tax_id: '12ABC34501DE35' } // Acrescente os demais campos exigidos pelo endpoint antes de enviar. ``` Para um CPF como `123.456.789-09`, a função retorna `12345678909`. Entradas como `00000000000`, `12ABC34501DE34` ou um valor recebido como número retornam `null`. Trate esse resultado no formulário ou no fluxo do seu backend antes de montar a requisição. ### Normalize o documento Remova espaços, pontos (`.`), barras (`/`) e hífens (`-`) e converta letras para maiúsculas. A Raims aceita essa formatação e aplica a normalização antes de conferir o documento. | Entrada ilustrativa | Valor normalizado | | -------------------- | ----------------- | | `123.456.789-09` | `12345678909` | | `12.abc.345/01de-35` | `12ABC34501DE35` | Mantenha o documento como texto em todas as etapas. Converter para número remove zeros à esquerda; extrair somente números apaga as letras de um CNPJ alfanumérico. Caracteres fora dos conjuntos permitidos devem causar uma mensagem de validação, em vez de serem apagados silenciosamente. Os CNPJs numéricos continuam válidos e coexistem com o formato alfanumérico. Prepare campos, máscaras e bibliotecas para ambos, conforme as [perguntas e respostas da Receita Federal sobre o CNPJ alfanumérico](https://www.gov.br/receitafederal/pt-br/centrais-de-conteudo/publicacoes/perguntas-e-respostas/cnpj/cnpj-alfanumerico.pdf). ### Como validar um CPF Após a normalização, um CPF deve ter exatamente 11 caracteres, todos de `0` a `9`. A Raims recusa sequências com o mesmo dígito repetido, como `00000000000` e `11111111111`. Os nove primeiros dígitos formam a base; os dois últimos são verificadores. Calcule cada verificador com o módulo 11: 1. Multiplique os nove dígitos da base, da esquerda para a direita, pelos pesos `10, 9, 8, 7, 6, 5, 4, 3, 2` e some os produtos. 2. Obtenha o resto da divisão da soma por `11`. Se for `0` ou `1`, o verificador é `0`; caso contrário, é `11 - resto`. 3. Acrescente o primeiro verificador calculado à base. Repita usando os pesos `11, 10, 9, 8, 7, 6, 5, 4, 3, 2` para obter o segundo. 4. Compare os dois resultados com os dois últimos dígitos recebidos. A rotina está documentada no [Protocolo de Arrecadação da GRU, seção IV, do Tesouro Nacional](https://cdn.tesouro.gov.br/sistemas-internos/apex/producao/sistemas/thot/arquivos/publicacoes/31906_1049829/Protocolo_arrecadacao_GRU.pdf?v=7014). No exemplo ilustrativo `12345678909`, a primeira soma é `210`, com resto `1`, resultando em `0`. A segunda soma é `255`, com resto `2`, resultando em `9`. Os verificadores calculados coincidem com `09`. ### Como validar um CNPJ Após a normalização, confira estas condições: | Parte | Formato | | ----------------------- | ------------------------------------------------------- | | Primeiros 12 caracteres | Números de `0` a `9` ou letras de `A` a `Z`. | | Últimos 2 caracteres | Somente números de `0` a `9`, os dígitos verificadores. | | Total | Exatamente 14 caracteres. | A Raims também recusa CNPJ com os 12 caracteres da base iguais a zero, incluindo `00000000000000`. O cálculo é o mesmo para CNPJ numérico e alfanumérico: 1. Converta cada caractere da base para `código ASCII - 48`. Números mantêm seu valor; `A` vale `17`, `B` vale `18` e `Z` vale `42`. 2. Multiplique os 12 valores pelos pesos `5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2` e some os produtos. 3. Divida a soma por `11`. Resto `0` ou `1` produz verificador `0`; nos demais casos, use `11 - resto`. 4. Acrescente o primeiro verificador e repita com os pesos `6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2`. 5. Compare os dois verificadores calculados com os recebidos. O [manual de cálculo dos dígitos verificadores publicado pela Receita Federal](https://www.gov.br/receitafederal/pt-br/centrais-de-conteudo/publicacoes/documentos-tecnicos/cnpj/manual-dv-cnpj.pdf) usa `12ABC34501DE35`: as somas `459` e `424` resultam nos verificadores `3` e `5`. Esse é um exemplo de cálculo, sem identificação de um cliente Raims. ## Como tratar INVALID\_TAXID Quando a API retornar HTTP `400`, com `error.code` igual a `INVALID_FIELDS`, procure em `error.details` o item com `field: "tax_id"` e `code: "INVALID_TAXID"`. Esse detalhe indica que o valor informado não passou na validação de CPF ou CNPJ. Confira o tamanho após a normalização, os caracteres permitidos e os dois verificadores. Um CPF com todos os dígitos iguais ou um CNPJ com os 12 caracteres da base iguais a zero também é recusado. | Código em `error.details` para `tax_id` | O que corrigir | | --------------------------------------- | ---------------------------------------------------------------------------------------- | | `REQUIRED` | Informe o documento. O campo está ausente, nulo ou vazio após a normalização. | | `INVALID_TYPE` | Envie uma string JSON, entre aspas, em vez de número, objeto ou outro tipo incompatível. | | `INVALID_TAXID` | Corrija o formato ou os dígitos verificadores do documento informado. | Associe o erro ao campo CPF/CNPJ na interface do seu sistema e mantenha os demais dados preenchidos. Peça a correção antes de tentar novamente; reenviar o mesmo valor inválido não resolve o problema. A API continua validando o documento em todas as requisições, mesmo que sua aplicação já o tenha conferido. Consulte a referência do endpoint para os campos e requisitos da requisição e [Códigos HTTP das respostas](/br/api/codigos-http-das-respostas) para o formato geral dos erros. ## O que essa validação confirma Passar no cálculo confirma somente que o formato e os dígitos verificadores estão consistentes. Isso não comprova existência do cadastro, situação cadastral regular ou titularidade. Os exemplos deste guia servem para entender o cálculo; não os use como documentos de clientes reais. Quando seu fluxo exigir comprovação cadastral ou de identidade, faça a verificação correspondente. Consulte os serviços oficiais da Receita Federal para [situação cadastral do CPF](https://www.gov.br/pt-br/servicos/consultar-cadastro-de-pessoas-fisicas) e [consulta de CNPJ](https://www.gov.br/pt-br/servicos/consultar-cadastro-nacional-de-pessoas-juridicas). # Webhooks (/br/integracoes/webhooks) A área Webhooks reúne os endereços cadastrados pela empresa para receber notificações e os eventos selecionados para cada destino. Acesse **Integração / Webhooks**. Cada cadastro pertence ao ambiente selecionado. Os eventos de **Sandbox e Produção** são enviados aos destinos cadastrados no respectivo ambiente. Sandbox usa dados de teste, mas realiza uma requisição HTTPS real ao seu endpoint. Use um destino de testes separado para evitar que uma simulação altere o seu sistema de produção. Consulte [Receber e validar eventos](/br/integracoes/webhooks/receber-eventos) para implementar o receptor, validar a assinatura e tratar reentregas. Para administrar os mesmos cadastros pelo seu sistema, use a [API de Webhooks](/br/api/webhooks/overview). Consultar exige **Webhooks**. Criar, renomear, editar URL e eventos, pausar a fila, desativar, reativar, rotacionar e excluir são ações com permissões próprias e podem ficar bloqueadas quando a conta está em modo de consulta. Se o seu endpoint restringe as origens das requisições, adicione os [IPs oficiais da Raims](/br/integracoes/webhooks/ips-oficiais) à lista de permissões antes de receber os webhooks. ## Cadastrar um webhook ### Prepare o endereço de recebimento Acesse **Integração / Webhooks / Cadastro de Webhook** com **Criar webhooks**. Informe uma URL HTTPS na porta padrão `443`, controlada pela sua empresa e com DNS que resolva para um IPv4 público. O endereço não pode usar localhost, IP direto nem incluir usuário ou senha. ### Dê um nome claro Identifique sistema, finalidade e ambiente, por exemplo **ERP - pagamentos Sandbox**. ### Selecione ao menos um evento Escolha somente os grupos que o seu sistema realmente precisa acompanhar. ### Guarde o segredo Selecione **Criar** e guarde o segredo mostrado em um cofre de segredos. Não o exponha no navegador, em URLs, repositórios ou logs. ## Eventos disponíveis no Dashboard O formulário organiza os eventos em cobranças e reembolsos. Os nomes abaixo identificam as categorias selecionadas no cadastro. Selecionar um tipo não cria uma ocorrência. O envio depende da confirmação do evento correspondente. | Item | Tipo | Descrição | | --- | --- | --- | | charge.created | Cobranças | Criação de uma cobrança. | | charge.paid | Cobranças | Confirmação do pagamento de uma cobrança. | | charge.canceled | Cobranças | Cancelamento de uma cobrança. | | charge.failed | Cobranças | Falha no pagamento. | | refund.requested | Reembolsos | Solicitação de reembolso. | | refund.completed | Reembolsos | Conclusão de um reembolso. | | refund.failed | Reembolsos | Falha no reembolso. | ## Última atividade do webhook **Última atividade** mostra o horário da última tentativa de envio registrada, incluindo tentativas que falharam. Esse horário não confirma que o endpoint recebeu ou processou o evento e pode aparecer com atraso. **Sem registro** significa que não há uma tentativa confirmada disponível para exibir. Isso não comprova que nunca houve envios. **Indisponível** significa que a informação não pôde ser consultada naquele momento; tente novamente depois. Uma atividade antiga pode continuar visível mesmo quando os logs daquela tentativa já não estiverem no período disponível para consulta. O acesso a essa informação exige somente **Webhooks**; a consulta dos logs tem permissão própria. Para investigar um episódio de falhas pela API, use [Consultar a situação do webhook](/br/api/webhooks/health). Essa consulta mostra os horários disponíveis e a duração das falhas registradas, sem testar a URL do receptor. ## Proteger o segredo O segredo completo é um dado de autenticação. Guarde-o no ambiente privado da sua aplicação e limite o acesso a quem administra a integração. O identificador do webhook não substitui esse segredo. Para conferir a autenticidade de cada requisição, siga a [validação de assinatura](/br/integracoes/webhooks/receber-eventos#validar-a-assinatura) usando o corpo original recebido. Não envie o segredo ao suporte nem o inclua em capturas de tela. Se houver suspeita de exposição, rotacione o segredo e atualize a configuração que o utiliza. Consulte o estado atual da cobrança ou do estorno pela API antes de tomar uma decisão financeira. ## Renomear um webhook 1. Acesse **Integração / Webhooks** e abra as ações do destino. 2. Selecione **Renomear webhook**, informe o novo nome e confirme a alteração. 3. Confira o nome atualizado na lista. A ação exige **Editar webhooks**. Renomear não altera a URL nem os eventos. ## Editar URL e eventos A ação **Editar URL e eventos** altera o endereço de recebimento e a seleção de eventos do mesmo cadastro. Exige **Webhooks** e **Editar URL e eventos de webhooks**, além da confirmação de identidade solicitada pelo Dashboard. A URL segue as [mesmas regras do cadastro](#cadastrar-um-webhook), e pelo menos um evento precisa permanecer selecionado. Nome, identificador, segredo e status são preservados. Editar a configuração não reativa um webhook desativado, não reinicia a contagem de falhas e não prolonga os prazos de novas tentativas. As alterações valem para as próximas seleções e tentativas de envio. Ao remover um tipo de evento, ele deixa de ser autorizado para novos envios. Requisições já autorizadas ou em andamento podem terminar com a configuração anterior. Ao incluir um tipo, também podem ser enviados eventos anteriores que ainda aguardavam preparação. A edição não reenvia entregas já encerradas. Eventos antigos já selecionados podem ser mantidos ou removidos, mesmo quando não estão mais disponíveis para novos cadastros. Se você remover um desses eventos e salvar, ele não poderá ser selecionado novamente enquanto estiver fora do catálogo atual. ## Pausar e retomar a fila Use **Pausar fila** no menu do webhook antes de uma manutenção no receptor. Confira o aviso e conclua a confirmação de identidade. A ação exige **Webhooks** e **Editar URL e eventos de webhooks** e está disponível para um cadastro ativo. A indicação **Fila pausada** confirma a configuração. As entregas pendentes e os novos eventos selecionados aguardam, mas seus prazos continuam contando: até 72 horas em Produção e quatro horas no Sandbox. Requisições já autorizadas podem terminar. Se o prazo de uma entrega acabar durante a pausa, ela não será enviada na retomada. Depois da manutenção, escolha **Retomar fila** no mesmo menu e confirme. As entregas ainda válidas voltam a poder ser enviadas, conforme os limites de envio. A retomada não garante entrega imediata nem uma ordem específica. Pausar e retomar encerram o episódio anterior de falhas, sem comprovar que o receptor se recuperou. Confira o resultado nos logs. Para controlar a pausa pela integração, use [Pausar ou retomar a fila](/br/api/webhooks/pause). Um [teste técnico](/br/api/webhooks/test) pode ser solicitado durante a pausa para conferir o receptor antes de retomar. ## Desativar e reativar um webhook As ações **Desativar webhook** e **Reativar webhook** exigem **Editar webhooks** e a confirmação de identidade solicitada pelo Dashboard. Elas preservam o cadastro, o segredo e os eventos selecionados. Um webhook desativado não recebe novos envios. Se uma tentativa pendente encontrar o cadastro desativado, a entrega é encerrada. Reativar antes dessa tentativa permite que a entrega continue dentro do prazo original. A ação não reenvia o histórico nem recupera entregas encerradas automaticamente. O [reenvio manual](/br/integracoes/webhooks/receber-eventos#reenvio-manual-de-eventos) permite solicitar outra entrega de um evento elegível. Para manutenção com preservação das entregas ainda válidas, use [Pausar e retomar a fila](#pausar-e-retomar-a-fila). Se um cadastro for desativado enquanto a fila estiver pausada, reativá-lo mantém a pausa; use **Retomar fila** para liberar os envios. As falhas não pausam nem desativam o cadastro automaticamente. Corrija o receptor e acompanhe as novas tentativas, que continuam dentro dos limites de cada entrega. Consulte [Falhas e novas tentativas de webhook](/br/integracoes/webhooks/receber-eventos#falhas-e-novas-tentativas-de-webhook) e os [alertas de falhas](/br/integracoes/webhooks/receber-eventos#alertas-de-falhas). ## Rotacionar a assinatura 1. Acesse **Integração / Webhooks** e abra as ações do destino correto. 2. Selecione **Rotacionar assinatura**. 3. Confira o aviso, confirme a rotação e guarde o novo segredo. 4. Atualize o receptor e confira se ele aceita eventos com o novo segredo. A ação exige **Rotacionar webhooks** e mantém o identificador do cadastro. No Dashboard, a troca é imediata: os novos envios usam somente o segredo novo assim que a rotação é confirmada. Se houver uma transição iniciada pela API, a rotação no Dashboard também encerra essa transição e substitui os dois segredos anteriores. Atualize o receptor para evitar rejeições. Requisições já autorizadas ou em andamento ainda podem chegar com uma assinatura anterior. Em caso de vazamento, retire também os segredos antigos da configuração do receptor. A rotação não reativa um webhook desativado nem zera a contagem de falhas. A API permite escolher um [período de transição](/br/api/webhooks/overview#rotacionar-o-segredo) para uma troca planejada. Essa opção não é usada pelo Dashboard. ## Excluir um webhook 1. Acesse **Integração / Webhooks** e abra as ações do destino que deseja remover. 2. Selecione **Excluir webhook**, confira o destino e confirme a exclusão. 3. Aguarde o resultado e confira a lista. A ação exige **Excluir webhooks** e remove o destino permanentemente. Confira antes se algum sistema depende dele. A exclusão impede novos envios para esse cadastro. Requisições já autorizadas ou em andamento ainda podem terminar. - [Receber e validar eventos](/br/integracoes/webhooks/receber-eventos): Valide a assinatura, reconheça o recurso e trate novas tentativas. - [IPs oficiais da Raims](/br/integracoes/webhooks/ips-oficiais): Configure as origens permitidas no firewall, WAF ou proxy. - [Chaves de API](/br/integracoes/chaves-api): Proteja as credenciais usadas pela sua integração. # IPs oficiais dos webhooks da Raims (/br/integracoes/webhooks/ips-oficiais) Todos os webhooks enviados pela Raims utilizam os IPv4 listados nesta página. Adicione os cinco endereços à lista de permissões da infraestrutura que protege o seu endpoint de recebimento. ## IPs de origem dos webhooks ```text 18.230.162.249 54.94.189.157 54.21.10.37 54.233.100.88 54.232.137.193 ``` Permita todos os endereços: uma entrega pode partir de qualquer um deles. Se a ferramenta exigir a notação CIDR, acrescente `/32` a cada IPv4 para autorizar somente aquele endereço. ### Produção e Sandbox Os webhooks de **Produção e Sandbox** utilizam os mesmos cinco IPs. Libere essa lista no firewall também nos testes de integração em Sandbox; não há uma lista adicional de endereços para esse ambiente. ## Quando configurar a lista de permissões Configure a lista quando o acesso ao endpoint depender de uma regra de origem, como em um firewall, WAF, Security Group, proxy reverso ou balanceador de carga. Em uma infraestrutura que já aceita requisições públicas, confira se alguma outra regra pode bloquear os webhooks. ## Configure o acesso ao endpoint 1. Localize a camada que controla o acesso ao endereço cadastrado para receber os webhooks. 2. Adicione os cinco IPv4 oficiais como origens permitidas. 3. Restrinja a regra ao domínio e ao caminho do endpoint de webhook, quando a ferramenta permitir. Autorize as requisições `POST` recebidas por HTTPS. 4. Confira se outras regras de segurança continuam bloqueando a requisição, mesmo depois de o IP ter sido permitido. Se o endpoint for exclusivo para webhooks da Raims, você pode restringir suas origens a essa lista. Preserve o acesso necessário às outras rotas da aplicação; não aplique essa restrição ao site inteiro. **Webhooks não respondem a desafios de navegador** O endpoint precisa receber requisições entre sistemas, sem CAPTCHA, desafio JavaScript ou login interativo. Se alguma dessas verificações bloquear a entrega, configure uma exceção somente para o endpoint de webhook e os IPs oficiais, mantendo as demais proteções. ### Cloudflare e outros proxies Se o domínio utiliza o proxy da Cloudflare, configure a lista de IPs da Raims nas regras de entrada da Cloudflare. O servidor de origem recebe a conexão da Cloudflare, por isso seu firewall precisa continuar permitindo os endereços do proxy. Restringir esse firewall diretamente aos cinco IPs da Raims pode bloquear as requisições encaminhadas. O mesmo cuidado vale para outros proxies e balanceadores. Ao usar um cabeçalho como `CF-Connecting-IP` ou `X-Forwarded-For` para identificar a origem, aceite essa informação somente de proxies confiáveis. Um cabeçalho enviado diretamente por um cliente não comprova o IP de origem. Consulte a documentação da Cloudflare sobre [endereços IP](https://developers.cloudflare.com/fundamentals/concepts/cloudflare-ip-addresses/) e [exceções de WAF](https://developers.cloudflare.com/waf/managed-rules/waf-exceptions/) para configurar sua infraestrutura. ## Valide a configuração Depois de salvar as regras, acompanhe uma entrega de webhook: 1. Confira nos registros do firewall, WAF ou proxy se a requisição foi permitida. 2. Confirme nos registros da aplicação que o `POST` chegou ao endpoint correto. 3. Se houver uma resposta `403 Forbidden`, identifique qual camada a gerou e revise a regra correspondente. Outras regras de WAF ou da própria aplicação podem recusar a requisição mesmo quando o IP já está permitido. Se não houver registro da requisição na aplicação, confira também o endereço cadastrado, a resolução DNS, o certificado HTTPS e as regras das camadas que ficam antes do servidor. **A lista de IPs complementa a autenticação** Autorizar a origem na rede não substitui a validação de autenticidade do webhook. Mantenha HTTPS e a validação da assinatura no receptor. Proteja o [segredo do webhook](/br/integracoes/webhooks#proteger-o-segredo) e não o inclua em URLs, registros ou mensagens de suporte. # Receber e validar webhooks (/br/integracoes/webhooks/receber-eventos) Prepare um endpoint HTTPS que aceite `POST` com `Content-Type: application/json`. Use a porta padrão `443` e um domínio com DNS que resolva para um IPv4 público. Ele deve receber chamadas entre sistemas, sem login interativo, CAPTCHA ou redirecionamento. Configure o destino e os eventos em [Webhooks](/br/integracoes/webhooks) e permita os [cinco IPs oficiais](/br/integracoes/webhooks/ips-oficiais) quando houver restrição de origem. ## Corpo do evento Cada requisição identifica o evento, o ambiente e o recurso alterado: ```json { "id": "d377b4c5-5678-4c42-8ea3-8f823156948e", "type": "charge.paid", "created_at": "2026-10-15T12:30:00.000Z", "environment": "sandbox", "data": { "object": "charge", "id": "ch_4ZxYp8Q2mV7nR6sT5uW3aB" } } ``` | Campo | Significado | | ------------- | --------------------------------------------------------------------------------------- | | `id` | UUID do evento, preservado nas reentregas e nos destinos que recebem o mesmo evento. | | `type` | Nome do evento, como `charge.paid`, `refund.completed` ou `webhook.test`. | | `created_at` | Data do evento em UTC, no formato ISO 8601. Não representa o horário de cada tentativa. | | `environment` | `sandbox` ou `production`, conforme o ambiente do recurso. | | `data.object` | Tipo do recurso: `charge` para cobrança, `refund` para estorno ou `webhook` para teste. | | `data.id` | Identificador público do recurso: cobrança `ch_`, estorno `rf_` ou webhook `whk_`. | O corpo mantém os mesmos bytes em todas as tentativas. Use `data.id` para consultar o estado atual em [Cobranças](/br/api/charges/overview) ou [Estornos](/br/api/refunds/overview), com uma chave da mesma empresa e ambiente. O evento informa uma mudança; seu processamento não deve presumir que esse continua sendo o estado mais recente do recurso. `data` identifica o recurso e não contém o cadastro completo da cobrança ou do estorno. `created_at` usa ISO 8601 neste corpo; as datas retornadas pelas consultas de entregas e tentativas usam segundos Unix UTC. ## Cabeçalhos de assinatura | Cabeçalho | Significado | | ------------------- | ------------------------------------------------------------------------------------------ | | `webhook-id` | UUID da entrega para aquele destino. Permanece igual nas novas tentativas. | | `webhook-timestamp` | Horário da tentativa em segundos Unix UTC. | | `webhook-signature` | Uma ou mais assinaturas `v1=`, com 64 caracteres hexadecimais cada, separadas por vírgula. | O `webhook-id` difere do `id` do corpo: um evento pode ser entregue a mais de um destino ou reenviado manualmente. Cada entrega tem seu próprio `webhook-id`. Novas tentativas da mesma entrega preservam esse ID e o corpo original, mas podem ter outro timestamp e outra assinatura. Durante o [período de transição escolhido pela API](/br/api/webhooks/overview#rotacionar-o-segredo), o mesmo cabeçalho contém primeiro a assinatura do segredo novo e depois a do anterior: `v1=,v1=`. O receptor deve aceitar a requisição quando qualquer assinatura `v1` corresponder ao segredo configurado. Quando o prazo termina ou uma rotação imediata encerra a transição, os novos envios incluem somente a assinatura do segredo atual. ## Validar a assinatura 1. Capture o corpo HTTP como bytes, antes de interpretar o JSON. 2. Leia os três cabeçalhos de assinatura. 3. Retire o prefixo `whsec_` do segredo do cadastro e decodifique a parte restante em Base62, nesta ordem: dígitos de `0` a `9`, letras de `A` a `Z` e letras de `a` a `z`. Represente o número em **32 bytes little-endian**, completando com zeros à direita quando necessário. Esses bytes são a chave do HMAC. 4. Monte a mensagem com os bytes UTF-8 de `webhook-id + "." + webhook-timestamp + "."`, seguidos pelos bytes exatos do corpo recebido. 5. Separe as assinaturas do cabeçalho pela vírgula e selecione os valores `v1`. Calcule HMAC-SHA256 e compare o resultado com cada assinatura usando uma comparação em tempo constante. Aceite a requisição se houver uma correspondência. Não use o texto `whsec_...` diretamente como chave do HMAC. Não serialize o JSON novamente: espaços, quebras de linha e ordem das propriedades fazem parte da assinatura. Configure o framework para preservar o corpo original nessa rota. Um objeto já convertido de JSON para a linguagem da aplicação não serve para conferir a assinatura. Rejeite a requisição se a assinatura ou o timestamp não forem válidos, sem executar seus efeitos. Recomendamos aceitar timestamps com diferença de até cinco minutos em relação ao relógio do receptor, mantendo esse relógio sincronizado. Essa verificação reduz o uso de requisições antigas. A deduplicação da entrega continua necessária dentro dessa janela. A tolerância se aplica ao `webhook-timestamp` da tentativa, não ao `created_at` do corpo. Novas tentativas e reenvios recebem timestamp e assinatura atuais, enquanto a data do evento original permanece no corpo. ### Exemplo em Node.js O exemplo recebe o segredo privado, os cabeçalhos e um `Buffer` com o corpo original. Ele aceita tanto um único `v1` quanto as assinaturas do período de transição, sem depender da posição da assinatura válida. Não registra esses valores nem interpreta o JSON antes da validação. ```js import { createHmac, timingSafeEqual } from 'node:crypto'; const alphabet = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'; function decodeWebhookSecret(secret) { if (!/^whsec_[0-9A-Za-z]{1,43}$/.test(secret)) { throw new Error('Invalid webhook secret'); } const encoded = secret.slice('whsec_'.length); if (encoded.length > 1 && encoded.startsWith('0')) { throw new Error('Invalid webhook secret'); } let value = 0n; for (const character of encoded) { value = value * 62n + BigInt(alphabet.indexOf(character)); } const key = Buffer.alloc(32); for (let index = 0; index < key.length; index += 1) { key[index] = Number(value & 255n); value >>= 8n; } if (value !== 0n) throw new Error('Invalid webhook secret'); return key; } export function verifyWebhook( secret, headers, rawBody, nowSeconds = Date.now() / 1000, ) { const id = headers['webhook-id']; const timestamp = headers['webhook-timestamp']; const signature = headers['webhook-signature']; if ( !Buffer.isBuffer(rawBody) || typeof id !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test( id, ) || typeof timestamp !== 'string' || !/^\d{1,12}$/.test(timestamp) || !Number.isFinite(nowSeconds) || Math.abs(nowSeconds - Number(timestamp)) > 300 || typeof signature !== 'string' ) { return false; } const signatures = signature .split(',') .map((entry) => entry.trim()) .filter((entry) => /^v1=[0-9a-f]{64}$/i.test(entry)); if (signatures.length === 0) return false; const key = decodeWebhookSecret(secret); try { const expected = createHmac('sha256', key) .update(`${id}.${timestamp}.`, 'utf8') .update(rawBody) .digest(); return signatures.some((entry) => { const received = Buffer.from(entry.slice('v1='.length), 'hex'); return timingSafeEqual(expected, received); }); } finally { key.fill(0); } } ``` Após uma assinatura válida, interprete o JSON, confira o ambiente e registre a entrega antes de responder. Guarde o segredo no servidor da integração, com acesso restrito. Nunca o inclua em URLs, código de navegador, capturas de tela ou mensagens de suporte. ## Confirmar o recebimento Responda com um status HTTP `2xx` somente depois de aceitar o evento em um armazenamento durável do seu sistema. Encaminhe o processamento demorado para uma fila e execute-o de forma assíncrona. A resposta de sucesso confirma que o receptor aceitou a entrega; não confirma uma nova transação financeira. O receptor deve seguir esta sequência: 1. Valide a assinatura com o corpo original e confira o ambiente do evento. 2. Registre o `id` do evento e o trabalho que será processado de forma durável. Faça essa aceitação impedir duplicatas mesmo quando duas requisições chegarem ao mesmo tempo. 3. Se o evento já foi aceito, devolva `2xx` sem registrar o mesmo trabalho novamente. Caso contrário, confirme o recebimento depois de salvar. 4. Processe o trabalho aceito e controle sua conclusão separadamente. Se esse processamento falhar após a resposta, seu sistema precisa recuperá-lo: a Raims já recebeu a confirmação de entrega. Se não conseguir guardar o evento, não confirme com `2xx`. O processamento posterior também deve tolerar repetições sem duplicar seus efeitos. O timeout de cada envio HTTP de webhook é de **5 segundos no total**. Valide a assinatura, registre o evento com segurança e devolva `2xx` dentro desse prazo, sem esperar o processamento demorado terminar. As até 72 horas de Produção são a janela para novas tentativas; uma requisição não fica aberta durante esse período. A Raims não segue redirecionamentos; cadastre diretamente a URL HTTPS final, incluindo a barra final quando ela fizer parte do caminho do receptor. O cadastro preserva essa barra. Configure o certificado com uma cadeia pública válida. O detalhe de cada tentativa nos logs pode mostrar o corpo da resposta do endpoint, limitado a 8 KiB, e o IP de destino usado naquela conexão. Respostas capturadas parcialmente têm um aviso. Conteúdo não registrado difere de corpo vazio confirmado; registros antigos podem não conter essas informações. O corpo ajuda a explicar erros devolvidos pela integração, mas não deve conter segredos ou dados pessoais desnecessários. Use os logs do Dashboard e os registros do receptor para relacionar o resultado à correção necessária. ## Tratar reentregas e ordem Uma entrega pode chegar mais de uma vez, inclusive quando o receptor já aceitou o evento e a resposta se perdeu. Registre `webhook-id` para reconhecer novas tentativas da mesma entrega e use o `id` do corpo para impedir que um reenvio manual do mesmo evento repita seu efeito. Confirme também as duplicatas já aceitas com `2xx`. Não dependa da ordem de chegada. Eventos de recursos diferentes ou novas tentativas podem chegar em outra sequência. Consulte o recurso pela API quando precisar decidir com base no estado atual. Se destinos diferentes alimentarem a mesma rotina, o `id` do corpo identifica o mesmo evento entre eles. ## Reenvio manual de eventos O Dashboard permite solicitar o reenvio de um evento por até **15 dias após sua criação**, quando o payload está disponível, o webhook está ativo e o tipo de evento continua selecionado no cadastro. A ação exige **Webhooks**, **Ver logs de eventos** e **Reenviar eventos de webhooks**. Para recuperar vários eventos, use **Reenviar selecionados** nos logs do Dashboard. Cada item continua sujeito às mesmas condições do reenvio individual. Confira os resultados aceitos e recusados antes de repetir o pedido. Eventos técnicos `webhook.test` não aceitam reenvio; solicite outro teste. O reenvio cria uma entrega com outro `webhook-id` e preserva os bytes do corpo original, incluindo `id` e `created_at`. A URL e o segredo usados são os atuais do webhook. Se houver uma transição de segredo ativa, valem as mesmas regras de assinatura dos demais envios. O pedido não cancela novas tentativas automáticas da entrega anterior. Com a fila pausada, a nova entrega também aguarda a retomada e seu próprio prazo continua contando. Prepare o receptor para reconhecer o mesmo `id` do corpo em entregas diferentes. Solicitar um reenvio não repete a operação financeira que gerou o evento nem confirma seu recebimento pelo endpoint. A janela de novas tentativas dessa entrega começa quando o pedido de reenvio é aceito: até 72 horas em Produção ou até quatro horas no Sandbox, com no máximo três novas tentativas após a inicial no Sandbox. Em Produção, os intervalos aumentam exponencialmente e variam entre tentativas, sem uma quantidade fixa dentro do prazo. O limite para solicitar outro reenvio continua sendo quinze dias após a criação do evento original; reenviar não renova esse limite nem altera o `created_at` do corpo. ## Pausar e retomar a fila Antes de uma manutenção, [pause a fila do webhook](/br/api/webhooks/overview#pausar-e-retomar-a-fila). Entregas pendentes e novos eventos selecionados aguardam a retomada dentro de seus prazos originais. A pausa não interrompe uma chamada HTTP já autorizada nem congela a janela de 72 horas de Produção ou quatro horas do Sandbox. Você pode solicitar um [teste técnico](/br/api/webhooks/test) enquanto a fila estiver pausada. Depois de conferir o receptor, retome a fila para permitir os envios ainda válidos. A retomada não recupera entregas cujo prazo acabou. ## Falhas e novas tentativas de webhook Uma resposta HTTP `2xx` conclui a entrega. Falhas de conexão, timeout e os demais códigos HTTP permitem novas tentativas dentro dos limites do ambiente. Isso inclui `3xx`, `400`, `401`, `403`, `404`, `429` e `5xx`. A Raims não segue redirecionamentos: configure diretamente a URL HTTPS final. O evento técnico `webhook.test` tem uma tentativa HTTP e prazo de até cinco minutos para o envio. As regras de novas tentativas abaixo se aplicam aos eventos de cobrança e estorno. Em **Produção**, a Raims repete a entrega por até **72 horas a partir do evento**. Os intervalos calculados aumentam exponencialmente e variam entre as tentativas, até o limite de uma hora. Não há uma quantidade fixa de tentativas dentro desse prazo. Em **Sandbox**, há até **três novas tentativas após a primeira**, distribuídas ao longo de poucas horas, dentro de uma janela de até **quatro horas a partir do evento**. Use esse ambiente para conferir como seu receptor lida com duplicatas e falhas. `Retry-After` pode indicar uma espera mínima em segundos ou uma data HTTP. Quando válido, ele pode aumentar o intervalo para além de uma hora. Se essa espera levar a próxima tentativa ao fim da janela de entrega ou depois dele, a Raims não agenda outra tentativa. O cabeçalho não prolonga a janela nem aumenta a quantidade de tentativas do Sandbox. Confira endereço, assinatura e regras de firewall ao investigar uma falha; não dependa de um horário exato para a próxima tentativa. ## Alertas de falhas As falhas não pausam a fila nem desativam o webhook automaticamente. Cada entrega continua seguindo sua política de novas tentativas e seu prazo. Depois que uma entrega esgota os limites, eventos novos continuam gerando suas próprias entregas enquanto o cadastro estiver ativo. A Raims avisa no Dashboard ao confirmar a quinta e a décima falhas de um mesmo episódio. Cada alerta é enviado uma vez por episódio. Uma resposta HTTP `2xx` encerra esse episódio; novas falhas podem iniciar outro. Os alertas não interrompem as novas tentativas nem ampliam seus prazos. O envio desses alertas por e-mail depende da preferência **Falha no webhook**. Os destinatários são os e-mails validados da própria conta. Os alertas podem ser reunidos em resumos por e-mail, com um link para consultar os avisos no Dashboard. Os avisos individuais continuam disponíveis no Dashboard. Consulte o estado atual do cadastro e os logs para investigar uma falha; um resumo por e-mail pode incluir alertas anteriores à recuperação do endpoint. Corrija o receptor e acompanhe as próximas tentativas. Se você desativou o webhook manualmente, reative-o para permitir novos envios. A reativação inicia um novo episódio de falhas e preserva o cadastro, o segredo e os eventos selecionados. Rotacionar o segredo não zera a contagem nem reativa um webhook desativado. Editar a URL ou os eventos também preserva o estado do cadastro, a contagem de falhas e os prazos de novas tentativas. Desativar o cadastro impede novos envios. Se a próxima tentativa de uma entrega pendente encontrar o webhook desativado, essa entrega é encerrada. Reativá-lo antes dessa tentativa permite que ela continue dentro dos limites originais. A reativação não reenvia eventos anteriores nem recupera entregas já encerradas automaticamente. Quando elegível, um evento pode receber uma nova entrega por [reenvio manual](#reenvio-manual-de-eventos). Requisições em andamento ainda podem terminar. ## Testar o recebimento pela API Depois de preparar o receptor, use [Enviar um evento de teste](/br/api/webhooks/test) para o webhook ativo. O evento chega pela mesma URL e com a mesma validação de assinatura dos demais envios, com `type: webhook.test`, `data.object: webhook` e o identificador do cadastro em `data.id`. O teste verifica conectividade e assinatura. Ele não altera cobranças, pagamentos, estornos, saldo ou a contagem de falhas do webhook. Confira o resultado nos registros do receptor. O prazo de até cinco minutos inclui a espera até que o teste possa ser enviado. A chamada HTTP ao receptor continua limitada a cinco segundos. Uma resposta `2xx` ao teste não comprova que sua aplicação trata eventos financeiros; confira esse fluxo com as simulações do Sandbox. Cada nova requisição cria um teste. Se houver falha, corrija a integração antes de solicitar outro; o evento técnico não tem repetição automática após a tentativa HTTP. ## Testar webhooks no Sandbox Cadastre um destino no Sandbox e selecione os eventos desejados. Crie uma cobrança e use [Simulação](/br/api/simulations/overview) para confirmar um pagamento ou testar falhas e estornos. As mudanças confirmadas geram os eventos correspondentes do Sandbox para esse destino, sem movimentar dinheiro real. As requisições de webhook são reais e usam os mesmos IPs oficiais de Produção. O corpo informa `environment: sandbox`. Mantenha o receptor e os efeitos desse teste separados dos dados de produção do seu sistema. # Meios de pagamento (/br/meios-de-pagamento) A Raims oferece Pix e boleto. O checkout mostra as opções permitidas para a cobrança, respeitando a disponibilidade da plataforma e as configurações da cobrança, do link e da conta. Cartão de crédito e cartão de débito estão desabilitados e não são oferecidos para pagamento. ## Pix e boleto No Pix, o pagador usa o QR Code ou o código Pix copia e cola apresentado no checkout. No boleto, usa o documento ou a linha de pagamento disponibilizada. A emissão dos dados de pagamento não confirma que a cobrança foi paga. Confira o estado da cobrança para acompanhar a confirmação. Para ajustar as opções padrão da conta, consulte [Checkout e formas de pagamento](/br/checkout#formas-de-pagamento). ## Códigos na API Ao [criar uma cobrança](/br/api/charges), use `payment_method_types` para definir uma lista própria de meios aceitos. Envie os códigos como números, sem repetição: `[1]` aceita Pix, `[2]` aceita boleto e `[1, 2]` aceita ambos. A lista preenchida substitui o padrão da conta somente nessa cobrança. Ela continua respeitando os meios disponíveis na plataforma, e uma configuração própria do link pode reduzir as opções dessa lista. Omitir `payment_method_types` ou enviar `null` mantém a herança da configuração usada pelo checkout. Quando não há uma configuração própria do link, vale o padrão atual da conta, inclusive suas alterações posteriores. Uma lista vazia não representa essa herança. `payment_method` é um campo separado, opcional, que usa `0` quando omitido. Sem uma lista própria, ele mantém os seguintes comportamentos: | Código | Meio de pagamento | Comportamento | | ------ | ----------------- | ----------------------------------------------------------------- | | `0` | Indefinido | O pagador escolhe entre os meios habilitados para a cobrança. | | `1` | Pix | Solicita a emissão do Pix na criação e permite somente Pix. | | `2` | Boleto | Solicita a emissão do boleto na criação e permite somente boleto. | Sem `payment_method_types`, escolher `payment_method: 1` ou `payment_method: 2` restringe a cobrança ao meio indicado, sem habilitar uma opção desativada na configuração usada pelo checkout. Se esse meio estiver desabilitado, outro não é oferecido como alternativa. Com uma lista própria em `payment_method_types`, omita `payment_method` ou envie `0`. Não combine a lista com `payment_method: 1` ou `payment_method: 2`. A cobrança começa com meio indefinido, mesmo que a lista permita somente Pix ou somente boleto. A lista aceita somente `1` e `2`. Não envie `0`, outros códigos, textos, booleanos ou itens `null`. Nenhuma dessas configurações altera o padrão da conta nem confirma pagamento. Com `payment_method: 1`, os dados disponíveis do Pix vêm em `payment_information.pix`; com `payment_method: 2`, os do boleto vêm em `payment_information.boleto`. Uma emissão pendente conserva o ID da cobrança para acompanhamento pela consulta individual. Veja [Receber o Pix na criação](/br/api/charges/overview#receber-o-pix-na-criação) e [Receber o boleto na criação](/br/api/charges/overview#receber-o-boleto-na-criação), incluindo os dados do cliente e o preenchimento do endereço por CEP. ## Meio cadastrado e escolha do checkout Nas consultas da API, `payment_method` informa o meio atual cadastrado na cobrança. Quando a geração de Pix ou boleto é registrada, uma cobrança indefinida passa de `0` para `1` ou `2`, conforme o meio usado. `payment_method_types` informa a lista própria configurada na criação, ou `null` quando a cobrança usa a herança. Essa lista não muda para refletir o meio escolhido nem representa as opções disponíveis naquele momento. `checkout_payment_method` informa o meio registrado no checkout e retorna `null` enquanto esse registro não existir. Por exemplo, depois de registrar a geração de Pix para uma cobrança criada com `payment_method: 0`, a consulta informa `payment_method: 1` e `checkout_payment_method: 1`. Definir `payment_method: 1` na criação solicita a emissão direta do Pix. Selecionar uma opção na tela, por si só, não confirma geração nem pagamento. Se a cobrança foi criada com `payment_method_types: [1, 2]`, registrar a geração de Pix faz a consulta informar `payment_method: 1`, preservando `payment_method_types: [1, 2]`. O filtro `payment_method` de [Listar cobranças](/br/api/charges/list) considera o meio atual cadastrado. Um clique no checkout sem registro da geração não faz uma cobrança indefinida corresponder ao filtro de Pix ou boleto. # Tipos e identificadores (/br/tipos-e-identificadores) Use este mapa para entender um valor retornado pela API ou um identificador apresentado no Dashboard. Cada página explica o que o valor representa, onde aparece e o que ele permite concluir. ## Como encontrar o significado | O que você encontrou | Onde consultar | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | Um ID como `st_`, `ch_`, `wd_` ou `med_` | [Identificadores e prefixos](/br/tipos-e-identificadores/identificadores) | | `statement_type`, `reference_type` ou meio de pagamento | [Tipos financeiros](/br/tipos-e-identificadores/financeiro) | | Estado de cobrança ou estorno, etapa e motivo de contestação | [Estados e resultados](/br/tipos-e-identificadores/estados) | | Sandbox, Produção ou chave de API | [Autenticação](/br/integracoes/autenticacao) e [Chaves de API](/br/integracoes/chaves-api) | | Um erro de requisição, como `INVALID_FIELDS` | [Códigos HTTP das respostas](/br/api/codigos-http-das-respostas) | | Nome de evento ou permissão de colaborador | [Webhooks](/br/integracoes/webhooks) e [Usuários e permissões](/br/usuarios-e-permissoes) | Para `pix_status`, veja [Receber o Pix na criação](/br/api/charges/overview#receber-o-pix-na-criação). Os motivos que impedem uma devolução estão em [Consultar o valor devolvível](/br/api/refunds/overview#consultar-o-valor-devolvível). A [consulta de links](/br/api/payment-links/overview#consultar-e-compartilhar) explica sua disponibilidade para pagamento. Para `tax_id` e `tax_id_type`, consulte [Validação de CPF e CNPJ](/br/integracoes/validacao-cpf-cnpj). Os códigos de resposta ajudam a interpretar o recurso consultado. Os parâmetros de cada endpoint informam quais valores podem ser enviados em uma requisição. Por exemplo, reconhecer um meio de pagamento na resposta não significa que ele possa ser escolhido na criação de uma cobrança. ## O mesmo valor em campos diferentes O significado depende do nome do campo e do recurso consultado. No extrato: * `statement_type: 2` indica uma tarifa. * `reference_type: 2` indica que a referência é uma contestação. Esses campos podem aparecer no mesmo lançamento. Um descreve a movimentação; o outro identifica a categoria do recurso relacionado. Veja [Tipos de lançamento](/br/tipos-e-identificadores/financeiro#tipos-de-lançamento-do-extrato) e [Categorias de referência](/br/tipos-e-identificadores/financeiro#categorias-de-referência-do-extrato). Um identificador também não é um estado. `rf_` identifica um estorno, mas não informa se ele foi concluído. Consulte o estado da solicitação para acompanhar o resultado. Do mesmo modo, uma contestação encerrada não comprova que houve devolução de dinheiro. ## Quando o código não estiver no guia Não atribua um significado apenas pelo número, prefixo ou semelhança com outro campo. Preserve o valor original e confira o recurso, o nome do campo e o ambiente da consulta. Um valor desconhecido não deve ser tratado automaticamente como sucesso, falha, pagamento confirmado ou autorização para repetir um pedido. Consulte a referência do endpoint e a versão atual deste mapa. Se a dúvida continuar, informe ao suporte o campo e o identificador do recurso, sem enviar chaves de API, segredos de webhook ou outros dados de autenticação. `null` indica ausência de um valor naquele campo. Ele não equivale a zero nem comprova que uma transação nunca existiu. Campos como `refund_id` e `dispute_id` ficam nulos quando não há um vínculo confirmado para apresentar. # Estados e resultados (/br/tipos-e-identificadores/estados) Um estado informa o andamento de um recurso. Um motivo explica uma condição registrada, e um resultado descreve a conclusão de uma análise. Confira qual desses campos está sendo apresentado: eles não são intercambiáveis. ## Estados da cobrança Na API, `status` da cobrança usa os códigos abaixo. O histórico também pode conter estados de meios que não estão disponíveis para novas cobranças. | Código ou valor | Significado | Como interpretar | | --------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Criada | Cobrança cadastrada, sem pagamento confirmado. Poder pagar depende do vencimento, dos meios habilitados e dos dados de pagamento disponíveis. | | `1` | Aguardando pagamento | Cobrança que aguarda confirmação do pagamento. Ter aberto o checkout ou emitido Pix ou boleto não confirma o recebimento. | | `2` | Autorizada | Pagamento autorizado, ainda sem confirmação de conclusão. Não entregue o produto nem considere o valor recebido apenas com base neste estado. | | `3` | Em processamento | Pagamento em processamento, ainda sem resultado final. Acompanhe a cobrança existente antes de solicitar outro pagamento. | | `4` | Paga | Pagamento da cobrança confirmado. Tarifas, bloqueios e devoluções são informações separadas e podem afetar o valor disponível para movimentação. | | `5` | Parcialmente devolvida | Parte do valor recebido foi devolvida. Consulte o histórico e a elegibilidade de estorno para conhecer o valor restante que pode ser solicitado. | | `6` | Devolvida | O valor recebido foi devolvido integralmente. A devolução pode resultar de mais de um lançamento; consulte os vínculos e o histórico para conciliá-la. | | `7` | Cancelada | Cobrança cancelada para novos pagamentos. Cancelar uma cobrança não é o mesmo que devolver um pagamento recebido. | | `8` | Expirada | O prazo de pagamento terminou. Esse estado não comprova baixa bancária: confira a cobrança e o boleto antes de concluir que houve cancelamento. | | `9` | Com falha | A cobrança ou seu pagamento terminou com falha. Confira os detalhes disponíveis antes de solicitar outra cobrança; este estado não confirma recebimento. | | `10` | Contestada | O pagamento está associado a uma contestação. Consulte o caso para conhecer a etapa, os valores e as informações disponíveis. | | `11` | Contestação em análise | A contestação está sendo analisada. O resultado e o eventual efeito financeiro ainda precisam ser consultados no caso e no extrato. | | `12` | Contestação perdida | A contestação teve resultado desfavorável à empresa. Consulte os valores informados no caso e os lançamentos relacionados para apurar o efeito financeiro. | | `13` | Contestação ganha | A decisão foi favorável à empresa. Confira saldo e lançamentos: este estado não informa quando o valor bloqueado ficou disponível. | Autorização, emissão de dados de pagamento e processamento não confirmam que a cobrança está paga. Uma cobrança expirada não comprova que um boleto emitido foi cancelado. Consulte [Cobranças](/br/api/charges/overview) para as ações disponíveis e as condições de cada requisição. ## Estados do estorno `status` de um estorno na API é um texto. Ele não usa a numeração do estado da cobrança. Acompanhe o mesmo identificador `rf_` para saber o resultado. | Código ou valor | Significado | Como interpretar | | --------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reserved` | Solicitada | A solicitação de estorno foi registrada, mas a devolução ainda não foi confirmada. Acompanhe esse mesmo estorno antes de fazer outro pedido. | | `accepted` | Aceita para processamento | O pedido foi aceito e aguarda o resultado final. O aceite não confirma que o dinheiro voltou ao pagador. | | `completed` | Concluída | A devolução foi confirmada. Confira o valor do estorno e os lançamentos relacionados para conciliá-la. | | `failed` | Com falha | A falha do estorno foi confirmada. Consulte o motivo, os demais estornos da cobrança e a elegibilidade antes de uma nova solicitação. | | `unknown` | Aguardando confirmação | O resultado da devolução ainda não foi confirmado. Continue consultando a mesma solicitação; este estado não deve ser tratado como falha nem como devolução concluída. | Uma falha de conexão não significa que o pedido falhou. Confira a solicitação e o histórico da cobrança antes de tentar novamente. No Sandbox, uma devolução confirmada corresponde à simulação; ela não movimenta dinheiro real. ## Motivos de falha do estorno `failure_reason.code` informa uma causa pública de falha confirmada. Nos demais estados, `failure_reason` é `null`. | Código ou valor | Significado | Como interpretar | | ----------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `REFUND_NOT_SUBMITTED` | Pedido não enviado | Esse estorno não foi enviado para processamento. Confira o histórico e a elegibilidade da cobrança antes de solicitar novamente. | | `REFUND_REJECTED` | Pedido recusado | A solicitação de estorno foi recusada. Consulte os estornos da cobrança antes de uma nova tentativa. | | `REFUND_PROCESSING_UNAVAILABLE` | Processamento indisponível | O processamento estava indisponível e esse estorno terminou com falha. Confira a cobrança e sua elegibilidade antes de outro pedido. | | `REFUND_PROCESSING_FAILED` | Falha de processamento confirmada | A falha da devolução foi confirmada, sem um motivo mais detalhado. Consulte os estornos da cobrança antes de tentar novamente. | | `REFUND_FAILURE_REASON_UNAVAILABLE` | Motivo não informado | Não há um motivo confirmado disponível para a falha desse estorno. Consulte o histórico e entre em contato com o atendimento se precisar esclarecer o resultado. | Use o código para tratar a resposta. A mensagem explica o problema e pode ser melhorada sem alterar o significado do código. A falta de causa detalhada não autoriza presumir recusa do banco ou solicitar outra devolução automaticamente. ## Tipos de contestação O campo `kind` é necessário para interpretar os motivos e resultados. | Código ou valor | Significado | Como interpretar | | --------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `chargeback` | Contestação de pagamento | Identifica o histórico de contestações classificado como chargeback. Interprete o motivo usando o catálogo dessa categoria; o nome não confirma que cartão está habilitado para novas cobranças. | | `med` | Contestação Pix (MED) | Identifica um caso do Mecanismo Especial de Devolução do Pix. Consulte a etapa, o motivo e os resultados da análise; a existência do caso não confirma devolução nem fraude. | O nome `chargeback` não comprova que cartões estejam disponíveis para novas cobranças na Raims. Ele identifica a categoria do registro consultado. ## Etapas da contestação O campo público `stage` informa o acompanhamento da contestação: | Código ou valor | Significado | Como interpretar | | -------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `open` | Aberta | A contestação foi registrada e ainda não tem análise confirmada. Confira as informações e os prazos apresentados no caso. | | `in_analysis` | Em análise | A contestação está em análise. Ainda não há, por essa etapa, confirmação de resultado ou devolução. | | `refund_in_analysis` | Devolução em análise | A análise de uma possível devolução está em andamento. Consulte o resultado e o valor devolvido quando informados; essa etapa não comprova saída de dinheiro. | | `closed` | Encerrada | O acompanhamento da análise foi encerrado. Leia os resultados e os valores informados no caso: encerramento, sozinho, não significa vitória, perda ou devolução. | | `cancelled` | Cancelada | A contestação foi cancelada. A etapa não confirma uma devolução nem a liberação de saldo; confira os valores e o extrato. | | `rejected` | Abertura rejeitada | A solicitação de abertura da contestação foi rejeitada. Confira os detalhes disponíveis; esse resultado não é uma devolução ao pagador. | | `failed` | Com falha | O processamento da contestação não foi concluído devido a uma falha. Consulte o caso e o atendimento se precisar esclarecer o resultado. | `closed` informa encerramento da análise. Não significa, sozinho, decisão favorável à empresa ou devolução de dinheiro. Confira os resultados e valores disponíveis no [detalhe da contestação](/br/api/disputes/retrieve). ## Motivos relatados no MED Quando `kind` é `med`, interprete `reason_code` por esta tabela. O motivo é o relato apresentado na contestação, não uma conclusão de fraude. | Código ou valor | Significado | Como interpretar | | --------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `1` | Relato de golpe | O reclamante relatou que o pagamento está ligado a um golpe. A categoria registra o motivo da contestação e não confirma que houve fraude. | | `2` | Relato de conta invadida | O reclamante relatou uso da conta por outra pessoa sem autorização. A conclusão depende da análise do caso. | | `3` | Relato de coação | O reclamante informou que fez o pagamento sob coação. Consulte os resultados da análise para conhecer a conclusão do caso. | | `4` | Relato de acesso fraudulento | A contestação informa suspeita de acesso fraudulento relacionado ao pagamento. O motivo relatado não equivale a fraude comprovada. | | `5` | Outro motivo | O motivo foi classificado fora das demais categorias. Consulte os detalhes da reclamação quando disponíveis. | | `6` | Motivo não reconhecido | O motivo recebido não corresponde a uma categoria reconhecida neste catálogo. Não deduza a causa pelo código; consulte os detalhes disponíveis no caso. | ## Motivos de outras contestações Quando `kind` é `chargeback`, `reason_code` usa esta outra tabela. O mesmo número pode ter outro significado em um caso MED. | Código ou valor | Significado | Como interpretar | | --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `1` | Fraude alegada | A contestação foi registrada com alegação de fraude. O motivo não substitui o resultado da análise. | | `2` | Compra não reconhecida | O reclamante informou que não reconhece a compra. Consulte os detalhes e o resultado do caso. | | `3` | Serviço não reconhecido | O reclamante informou que não reconhece o serviço cobrado. A categoria registra a alegação e não define o resultado da contestação. | | `4` | Produto ou serviço divergente | O reclamante relatou divergência no produto ou serviço. Consulte os detalhes do caso para entender a reclamação. | | `5` | Cobrança indevida | O reclamante alegou cobrança indevida. A conclusão e o eventual efeito financeiro dependem do resultado informado no caso. | | `6` | Outro motivo | A contestação usa um motivo fora das demais categorias. Consulte os detalhes disponíveis; não interprete esse valor como o motivo equivalente de um caso MED. | Um motivo `null` não está disponível para apresentação. Não preencha esse campo com uma causa deduzida pelo valor, pela data ou pelo tipo de pagamento. ## Resultados de análise no MED `infraction_result` informa o resultado da análise da infração: | Código ou valor | Significado | Como interpretar | | --------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agreed` | Infração reconhecida | A análise reconheceu a infração relatada. Esse resultado não confirma devolução; consulte o resultado da análise de devolução e o valor efetivamente devolvido. | | `disagreed` | Infração não reconhecida | A análise não reconheceu a infração relatada. Consulte os demais resultados e valores disponíveis para entender o desfecho do caso. | `refund_result` informa o resultado da análise do pedido de devolução: | Código ou valor | Significado | Como interpretar | | -------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `partially_accepted` | Devolução parcialmente aceita | A análise aceitou devolver parte do valor solicitado. Confira o valor efetivamente devolvido; o aceite não comprova, sozinho, a movimentação do dinheiro. | | `totally_accepted` | Devolução integralmente aceita | A análise aceitou a devolução integral solicitada. Consulte o valor devolvido e o extrato para confirmar o efeito financeiro. | | `rejected` | Devolução rejeitada | A análise rejeitou a devolução solicitada. Confira o caso e os lançamentos relacionados para conciliar os valores, inclusive eventuais bloqueios ou liberações. | O reconhecimento da infração e o aceite de um pedido não confirmam, sozinhos, que o dinheiro foi devolvido. `refunded_amount_cents` informa o total de devoluções confirmadas do caso quando esse dado está disponível. Um resultado `null` permanece diferente de uma recusa ou de um valor zero confirmado. ## Motivos de perda da contestação `loss_reason_code`, quando informado, descreve o motivo registrado para a decisão desfavorável. Uma observação pode complementar esse código. | Código ou valor | Significado | Como interpretar | | --------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `1` | Prazo de resposta encerrado | O motivo registrado para a perda foi o encerramento do prazo de resposta. Consulte as datas e o resultado do caso. | | `2` | Evidências insuficientes | As evidências apresentadas foram consideradas insuficientes para a contestação. Consulte os detalhes disponíveis no caso. | | `3` | Documentação inválida | A documentação apresentada não foi aceita na análise. Consulte os detalhes do caso para entender o resultado informado. | | `4` | Decisão final | A perda foi registrada com base na decisão final da análise. Confira os valores do caso e o extrato para identificar o efeito financeiro. | | `5` | Outro motivo de perda | A perda tem um motivo diferente das demais categorias. Consulte a observação do motivo quando disponível; a ausência de observação não permite inferir uma causa. | Esses motivos não substituem a leitura da etapa e do resultado do caso. Consulte [Contestações](/br/api/disputes/overview) para acompanhar os dados disponíveis sem confundir análise, decisão e movimentação financeira. # Tipos do extrato e códigos financeiros (/br/tipos-e-identificadores/financeiro) Os campos desta página descrevem fatos diferentes. Confira sempre o recurso e o nome do campo antes de interpretar o código. Uma tarifa e um meio de pagamento não compartilham uma numeração universal. No extrato, `statement_type: 2` significa tarifa, enquanto `reference_type: 2` significa referência a uma contestação. O primeiro classifica a movimentação; o segundo classifica o recurso relacionado. ## Tipos de lançamento do extrato `statement_type` informa a natureza do lançamento no [Extrato](/br/api/statements/overview). `amount_cents` mantém o sinal do valor em centavos de real. | Código ou valor | Significado | Como interpretar | | --------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `1` | Recebimento | Entrada de valor confirmada no extrato, apresentada com sinal positivo. Consulte a referência do lançamento para identificar sua origem; nem todo recebimento precisa apontar para uma cobrança. | | `2` | Tarifa | Cobrança de tarifa, apresentada com valor negativo. Quando houver uma cobrança relacionada, o recebimento e a tarifa aparecem em lançamentos separados. | | `3` | Tarifa de serviço | Valor cobrado por um serviço, com sinal negativo. A referência disponível ajuda a identificar a origem da cobrança; o tipo, sozinho, não informa qual serviço foi utilizado. | | `4` | Saque | Saída de valor por saque, com sinal negativo. Use a referência do saque para consultar sua identificação e seu resultado. | | `5` | Devolução | Saída confirmada de valor devolvido, com sinal negativo. Pode ser o lançamento que completa a devolução de uma cobrança após devoluções anteriores; consulte o histórico para conhecer o total devolvido. | | `6` | Devolução parcial | Saída confirmada de parte do valor recebido, com sinal negativo. O restante devolvível depende também de outras devoluções e contestações vinculadas à cobrança. | | `7` | Ajuste a crédito | Ajuste que acrescenta valor ao saldo, apresentado com sinal positivo. Consulte a referência e os detalhes disponíveis para entender o motivo; esse tipo não identifica um pagamento de cliente. | | `8` | Ajuste a débito | Ajuste que retira valor do saldo, apresentado com sinal negativo. Consulte a referência e os detalhes disponíveis para entender o motivo; esse tipo não identifica necessariamente um saque ou estorno. | | `9` | Bloqueio de saldo | Valor que passou a ficar indisponível para movimentação, apresentado com sinal negativo. O bloqueio não confirma despesa nem devolução de dinheiro; confira o saldo bloqueado e o caso relacionado, quando informado. | | `10` | Liberação de saldo | Valor anteriormente bloqueado que voltou a ficar disponível, apresentado com sinal positivo. A liberação não é uma nova receita e não representa outro pagamento do cliente. | Um pagamento pode gerar mais de um lançamento, como recebimento e tarifa. Uma retenção reduz a disponibilidade do dinheiro, sem representar por si só uma despesa. Sua liberação não é uma nova receita. O saldo atual tem [consulta própria](/br/api/balances/overview), com total, bloqueado e disponível. Somar uma página do extrato não substitui essa consulta nem fornece o saldo após cada lançamento. ## Categorias de referência do extrato `reference_type` explica a que categoria pertence `reference_id`. Ele não informa se o lançamento é entrada, saída, tarifa ou retenção. | Código ou valor | Significado | Como interpretar | | --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `1` | Cobrança | O identificador de referência aponta para uma cobrança. Vários lançamentos, como recebimento, tarifa e devolução, podem se relacionar à mesma cobrança; confira também o tipo do lançamento e os vínculos de estorno ou contestação. | | `2` | Contestação | O identificador de referência aponta para uma contestação. Consulte o caso para interpretar o vínculo; a referência, sozinha, não comprova perda, ganho ou devolução. | | `3` | Saque | O identificador de referência aponta para um saque. A classificação indica a origem do lançamento e deve ser lida junto de seu valor e tipo. | | `4` | Ajuste | O identificador de referência aponta para um ajuste financeiro. O sentido do ajuste é informado pelo tipo do lançamento e pelo sinal do valor. | | `5` | Lançamento manual | A referência identifica um lançamento manual e pode não ter prefixo. Não a trate como identificador de cobrança nem presuma que exista um endpoint público para consultá-la. | `reference_id` e `reference_type` podem ser `null`. Os campos `refund_id` e `dispute_id` complementam os vínculos quando existe uma associação confirmada. Uma tarifa não recebe automaticamente o estorno de outra linha só porque ambas pertencem à mesma cobrança. ## Meios de pagamento Estes códigos identificam meios de pagamento no campo `payment_method` da API. A presença de um código na resposta não significa que ele esteja habilitado para criar uma cobrança ou pagar no checkout. | Código ou valor | Significado | Como interpretar | | --------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Não definido | A cobrança ainda não tem um meio de pagamento definido. As opções permitidas vêm da configuração da cobrança e do checkout; este valor não indica pagamento confirmado. | | `1` | Pix | Identifica pagamento por Pix. A emissão de um código Pix permite pagar a cobrança, mas a confirmação depende do recebimento do pagamento. | | `2` | Boleto | Identifica pagamento por boleto. Registro, compensação e liquidação são etapas diferentes; consulte o estado do boleto e o pagamento da cobrança. | | `3` | Cartão de crédito | Identifica cartão de crédito em dados que usem esse código. A existência do valor no catálogo não habilita esse meio no checkout; para criar uma cobrança, use somente os meios aceitos pelo endpoint. | | `4` | Débito | Identifica pagamento por débito em dados que usem esse código. A existência do valor no catálogo não habilita esse meio no checkout; para criar uma cobrança, use somente os meios aceitos pelo endpoint. | Para novas cobranças, consulte [Meios de pagamento](/br/meios-de-pagamento): o guia distingue `payment_method`, `payment_method_types` e `checkout_payment_method`. A lista aceita na criação segue as opções do endpoint, e a configuração de um link pode restringir as opções da cobrança. Emitir Pix ou boleto não confirma pagamento. ## Motivos de falha do saque Quando `status` de um saque é `FAILED`, `failure_reason.code` informa o motivo registrado. Nos demais estados, `failure_reason` é `null`. Esses códigos vêm da [consulta de saques](/br/api/withdrawals/retrieve) e são diferentes do status HTTP da requisição. | Código ou valor | Significado | Como interpretar | | --------------------------------------- | ---------------------- | ----------------------------------------------------------------------------- | | `INVALID_BANK_ACCOUNT` | Conta inválida | Os dados da conta de destino não foram aceitos. | | `BANK_ACCOUNT_UNAVAILABLE` | Conta indisponível | A conta de destino estava indisponível. | | `BANK_UNSUPPORTED` | Instituição não aceita | A instituição do destino não foi aceita para o saque. | | `INVALID_ACCOUNT_TYPE` | Tipo de conta inválido | O tipo da conta de destino não foi aceito. | | `INSUFFICIENT_BALANCE` | Saldo insuficiente | Não havia saldo suficiente para concluir o saque. | | `BLOCKED_BALANCE` | Saldo bloqueado | Valores bloqueados impediram o saque. | | `BELOW_MINIMUM_WITHDRAWAL` | Abaixo do mínimo | O valor solicitado era menor que o mínimo permitido. | | `ABOVE_MAXIMUM_WITHDRAWAL` | Acima do máximo | O valor solicitado excedia o máximo permitido. | | `WITHDRAWAL_LIMIT_REACHED` | Limite atingido | Um limite de saque impediu a solicitação. | | `DUPLICATED_REQUEST` | Solicitação duplicada | Confira o histórico antes de solicitar outra transferência. | | `RISK_POLICY_REJECTED` | Saque não autorizado | Confira os avisos da conta ou procure o suporte. | | `WITHDRAWAL_TEMPORARILY_UNAVAILABLE` | Saque indisponível | A solicitação não pôde ser concluída naquele momento. | | `BANK_PROCESSING_FAILURE` | Falha na transferência | Confira o histórico e procure o suporte se necessário. | | `BANK_TIMEOUT` | Prazo excedido | Não houve conclusão no prazo esperado. Consulte o histórico antes de repetir. | | `INTERNAL_ERROR` | Falha no processamento | Confira o histórico e procure o suporte se necessário. | | `WITHDRAWAL_FAILURE_REASON_UNAVAILABLE` | Motivo não disponível | Não há motivo confirmado para apresentar. Procure o suporte se necessário. | Use o código para tratar a resposta no seu sistema. A mensagem em inglês complementa o diagnóstico e pode mudar sem alterar o código. Consulte o saque e o histórico antes de fazer outra solicitação; a consulta não repete a transferência nem confirma que uma nova tentativa será aceita. # Identificadores e prefixos (/br/tipos-e-identificadores/identificadores) O prefixo é a parte inicial de um identificador, antes do restante do código. Ele ajuda a reconhecer o recurso. O identificador completo é necessário para consultar aquele registro; o prefixo sozinho não identifica uma transação. ## Identificadores financeiros | Código ou valor | Significado | Como interpretar | | --------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ch_` | Cobrança | Identifica uma cobrança nas respostas da API, nos links e no Dashboard. Use o valor completo ao consultar a cobrança; ele permanece distinto dos IDs de cliente, pagamento por link e estorno. | | `rf_` | Estorno Pix | Identifica uma solicitação de devolução de um pagamento Pix. Pode aparecer no histórico de estornos e no campo refund\_id do extrato; consulte o estado do estorno para saber se a devolução foi concluída. | | `pl_` | Link de pagamento | Identifica o cadastro do link de pagamento. A URL de checkout pode usar outro token sem prefixo; copie a URL retornada em vez de montá-la a partir deste ID. | | `cus_` | Cliente | Identifica o cliente cadastrado pela empresa e vinculado a uma cobrança. É o valor usado em customer\_id; não é o CPF, o CNPJ nem a referência do cliente no seu sistema. | | `st_` | Lançamento do extrato | Identifica um lançamento individual do extrato. Uma mesma cobrança pode gerar vários lançamentos, cada um com seu próprio ID, como recebimento, tarifa e devolução. | | `dp_` | Contestação | Identifica uma contestação de pagamento e pode aparecer no campo dispute\_id ou como referência do extrato. Preserve o ID recebido; os casos MED usam outro formato. | | `wd_` | Saque | Identifica um saque no Dashboard e nas respostas da API. Pode aparecer em reference\_id no extrato; use o valor completo para consultar o saque e acompanhar seu resultado. | | `wdst_` | Destino de saque | Identifica um destino Pix próprio verificado, retornado pela consulta de destinos em Produção. Use o valor completo para recuperar seus dados mascarados; ele não identifica um saque nem altera o destino padrão. | | `adj_` | Ajuste financeiro | Identifica o ajuste relacionado a um lançamento do extrato. Confira o tipo e o valor do lançamento para distinguir crédito de débito; o ID não informa a direção do ajuste nem define um endpoint público próprio. | | `med_` | Caso MED | Identifica um caso do Mecanismo Especial de Devolução do Pix, com sufixo numérico decimal. Pode aparecer como ID de contestação e no campo dispute\_id do extrato; o encerramento do caso não comprova, sozinho, uma devolução financeira. | O ID de caso MED usa um número decimal após o prefixo. Preserve o formato recebido ao [consultar uma contestação](/br/api/disputes/retrieve). Os demais IDs deste grupo usam uma combinação de letras e números que distingue maiúsculas de minúsculas. Copie o valor completo como foi recebido, sem remover zeros, alterar letras ou converter o código em número. ## Identificadores da conta e do Dashboard Estes identificadores aparecem nas configurações da conta, de chaves e de webhooks, nos arquivos de uma contestação e nos envios de imagens do checkout. Copie o valor completo quando precisar identificar o recurso. Eles não substituem as credenciais de autenticação. | Código ou valor | Significado | Como interpretar | | --------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mk_` | Cadastro da chave de API | Identifica a chave gerenciada no Dashboard, inclusive nas ações de configuração e rotação. Não é o segredo usado no header Authorization e não autentica uma requisição. | | `cau_` | Envio de imagem do checkout | Identifica um envio autorizado de logo ou ícone. Depois de enviar o arquivo, use o ID no campo correspondente da personalização do checkout. O ID não é a URL da imagem e não comprova que ela já foi aplicada. | | `co_` | Empresa | Identifica a conta empresarial em informações do Dashboard e registros de atividade. Conhecer este ID não concede acesso aos dados da empresa; a sessão ou a chave de API continua definindo o acesso permitido. | | `whk_` | Cadastro de webhook | Identifica o destino configurado na área de Webhooks do Dashboard. É diferente do segredo usado para verificar a origem das notificações. | | `emp_` | Membro da equipe | Identifica uma pessoa com acesso à conta por meio da equipe. Pode aparecer no cadastro, nos convites e nas atividades; suas permissões continuam sendo definidas pelo acesso concedido à pessoa. | | `df_` | Arquivo de contestação | Identifica um arquivo vinculado a uma contestação, como um documento de evidência. O acesso ao conteúdo depende das permissões da conta; o ID não é o endereço de download. | ## Credenciais e segredos Estes prefixos identificam dados de autenticação, não o cadastro de um recurso: | Código ou valor | Significado | Como interpretar | | --------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sk_test_` | Chave de API do Sandbox | Prefixo do segredo usado para autenticar requisições com dados de teste. Envie a chave completa no header Authorization com o esquema Bearer e mantenha o segredo protegido no backend da sua aplicação. | | `sk_live_` | Chave de API de Produção | Prefixo do segredo usado para autenticar requisições no ambiente de operações reais. O prefixo não comprova que a chave está válida: acesso, ambiente e restrições são conferidos a cada requisição. | | Código ou valor | Significado | Como interpretar | | --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `whsec_` | Segredo de webhook | Prefixo do segredo de assinatura mostrado ao gerenciar um webhook. Proteja o valor completo e siga a orientação de validação do webhook; ele não é o ID do cadastro nem uma chave Bearer da API. | O ID `mk_` de uma chave não autentica requisições. O ID `whk_` de um webhook não permite conferir a assinatura de uma mensagem. Para essas finalidades, use a credencial ou o segredo apropriado, conforme os guias de [Autenticação](/br/integracoes/autenticacao) e [Webhooks](/br/integracoes/webhooks). Não publique credenciais, não as inclua em URLs e não as envie ao suporte. Os exemplos da documentação abreviam os segredos; eles não são credenciais válidas para uso. ## Referências sem prefixo No extrato, uma referência manual pode aparecer sem prefixo. Nesse caso, `reference_type` informa a categoria. A ausência de prefixo não autoriza tratar esse valor como ID de cobrança, estorno ou contestação. O token presente na URL de pagamento também é diferente do ID `pl_` do link. Preserve a URL fornecida pela Raims; não construa uma URL de checkout trocando ou acrescentando prefixos. ## Como usar um identificador O prefixo não informa a empresa, o ambiente, o valor ou o estado do recurso. IDs de Sandbox e Produção seguem os mesmos prefixos de recurso. O acesso depende da credencial e do vínculo com a empresa e o ambiente corretos. Um `st_` identifica um lançamento. Seus campos `reference_id`, `refund_id` e `dispute_id`, quando preenchidos, identificam outros recursos relacionados. Use o campo certo para cada consulta; a cobrança e seus lançamentos não têm o mesmo identificador. # Usuários e permissões (/br/usuarios-e-permissoes) O link **Saiba mais** aparece abaixo de cada item da matriz em **Conta / Usuários e permissões**. Cada link abre diretamente a permissão correspondente nesta página. ## Convidar membros 1. Acesse **Conta / Usuários e Permissões / Cadastrar membro da equipe**. 2. Informe os e-mails e pressione Enter para confirmar cada endereço. O formulário permite até dez e-mails por envio. 3. Escolha um perfil sugerido e confira as permissões selecionadas. Ajuste a matriz conforme as tarefas que essas pessoas precisam executar. 4. Selecione **Enviar convite** e confirme sua identidade quando solicitado. 5. Confira o resultado de cada endereço. Um envio parcial pode deixar alguns convites pendentes de correção. A ação exige **Equipe** e **Cadastrar membros da equipe**. O membro só terá acesso depois de aceitar o convite recebido por e-mail. Não use o e-mail da conta principal como se fosse outro membro. ## Consultar permissões 1. Acesse **Conta / Usuários e Permissões** e encontre a pessoa pelos filtros disponíveis. 2. Abra **Ver permissões** no menu de ações da linha. 3. Confira as permissões atuais na matriz. A consulta exige **Equipe**. Seu próprio acesso fica em consulta nessa área. ## Alterar permissões 1. Acesse **Conta / Usuários e Permissões** e abra **Ver permissões** nas ações do membro desejado. 2. Ajuste a matriz e selecione **Salvar mudanças**. 3. Confirme sua identidade quando solicitado e aguarde **Permissões atualizadas**. Salvar exige **Alterar permissões**. Os limites para conceder permissões ou administrar outra pessoa estão em **Regras para administrar acessos** abaixo. A revisão deve considerar as permissões atuais, inclusive depois de uma mudança feita por outro administrador. ## Reenviar um convite 1. Acesse **Conta / Usuários e Permissões** e encontre o membro que ainda precisa concluir o acesso. 2. No menu de ações, use **Reenviar convite** quando a opção estiver disponível. 3. Respeite o tempo de espera e conclua a confirmação de identidade solicitada. A ação exige **Cadastrar membros da equipe** e não transforma um acesso removido em acesso ativo. O destinatário deve usar o convite recebido para concluir o cadastro. ## Remover um membro 1. Acesse **Conta / Usuários e Permissões** e abra as ações da pessoa correta. 2. Selecione **Remover membro**, confira quem perderá o acesso e confirme. 3. Conclua a confirmação de identidade solicitada e confira o resultado na lista. A ação exige **Remover membros da equipe**. Um membro não pode remover o próprio acesso nem administrar alguém fora do alcance de suas permissões. Para encerrar apenas sessões conectadas, acesse **Conta / Dispositivos**. ## Como as permissões funcionam As permissões de consulta liberam uma área ou um conjunto de informações. As permissões de ação liberam tarefas específicas, como criar, editar, remover ou administrar outros usuários. Ter acesso a um módulo não libera automaticamente todas as ações dele. As listas abaixo usam os mesmos nomes de permissões apresentados no Dashboard. **Use o menor acesso necessário** Comece por um perfil sugerido e remova o que a pessoa não precisa executar no trabalho diário. Alterar a seleção transforma o perfil em **Personalizado**. ## Regras para administrar acessos * O **Proprietário** possui acesso total à conta e não é um perfil sugerido de membro. **Super administrador** é um perfil de membro e continua sujeito às regras da matriz. * Um membro não pode alterar as próprias permissões nem remover o próprio acesso por esta área. * Um membro só pode conceder permissões que ele próprio possui. * Um membro não pode editar ou remover alguém que tenha permissões fora do seu próprio alcance. O Proprietário pode administrar todo o catálogo. * Cadastrar membros, alterar permissões, reenviar convites ou remover acessos pode exigir uma nova confirmação de identidade. * Perfil, segurança, notificações, atividades próprias e sessões próprias são recursos pessoais. As permissões de auditoria e sessões listadas abaixo ampliam a visualização ou a gestão para toda a empresa. **Criar cobrança também depende de clientes** Para escolher um cliente existente, habilite **Clientes**. Para cadastrar um cliente durante a criação, habilite também **Cadastrar clientes**. **Saques dependem da consulta da chave Pix** Para solicitar ou configurar saques e para editar chaves Pix de saque, conceda também **Ver chaves Pix de saque**. Ao marcar uma dessas ações, o Dashboard seleciona a permissão de consulta automaticamente. ## Operações comerciais Oito permissões controlam cobranças e clientes. | Item | Descrição | | --- | --- | | Cobranças | Consulta cobranças, pedidos e links de pagamento. Também libera detalhes e operações de consulta relacionadas. | | Criar cobranças | Cria novas cobranças e links de pagamento para clientes da empresa. | | Revogar cobranças | Cancela ou revoga cobranças que ainda permitem essa ação. | | Devolver Pix | Solicita devoluções totais ou parciais de cobranças Pix pagas. Cada pedido exige confirmação pelo método de segurança configurado para o usuário. | | Clientes | Acessa o módulo de clientes e consulta os cadastros existentes. | | Cadastrar clientes | Cria novos clientes no Dashboard, inclusive durante o fluxo de uma cobrança. | | Editar clientes | Altera os dados de clientes cadastrados. | | Remover clientes | Remove clientes que não devem mais permanecer ativos. | ## Financeiro Dez permissões controlam contestações, saldo, extrato, saques, chaves Pix de saque e planos. | Item | Descrição | | --- | --- | | Contestações | Consulta contestações, detalhes e arquivos já anexados. | | Saldo | Visualiza o saldo e a carteira da empresa. | | Extrato | Acessa o histórico financeiro e abre detalhes dos lançamentos. Para exportar esse histórico e acessar os arquivos, exige também Exportações. | | Saques | Acessa o módulo de saques, o histórico e os detalhes de cada solicitação. | | Configurar saques | Altera regras e configurações de saque, incluindo o saque automático. Requer consulta das chaves Pix de saque. | | Solicitar saques | Solicita novos saques da empresa. Requer consulta das chaves Pix de saque. | | Ver chaves Pix de saque | Consulta as chaves Pix cadastradas para receber saques, incluindo o destino selecionado. | | Editar chaves Pix de saque | Cadastra, seleciona e remove chaves Pix de saque. Requer a permissão de consulta e uma confirmação de identidade para cada alteração. | | Planos | Consulta a área de planos, precificação e condições atuais da conta. | | Alterar plano | Altera o plano comercial da conta. | ## Integração e API As permissões abaixo separam consulta e administração de aplicativos, chaves de API e webhooks. Cada membro mantém o acesso às próprias conexões de aplicativos. As permissões de sessões e dispositivos não ampliam esse acesso. | Item | Descrição | | --- | --- | | Ver aplicativos da empresa | Consulta as conexões de aplicativos do titular e da equipe. Não permite editar permissões nem revogar conexões de outras pessoas. | | Revogar conexões da equipe | Consulta os aplicativos da empresa e permite revogar conexões de outros funcionários. Não permite revogar conexões do titular nem editar as permissões de outras pessoas. | | Chaves de API | Consulta a listagem, os detalhes e as restrições de IP das chaves privadas. | | Ver logs de solicitações | Consulta o histórico de requisições da API, seus detalhes e os corpos disponíveis de solicitações e respostas. Requer também Chaves de API. Conceda somente a quem precisa consultar essas informações. | | Criar chaves de API | Gera novas chaves privadas para integração. | | Excluir chaves de API | Revoga e exclui chaves privadas existentes. | | Rotacionar chaves de API | Rotaciona o segredo e gera uma nova credencial para a chave. | | Gerenciar IPs de API | Adiciona, altera ou remove restrições de IPv4 e CIDR das chaves privadas. | | Editar chaves de API | Altera metadados da chave, como o nome exibido. | | Webhooks | Consulta a listagem, os detalhes e os eventos selecionados dos webhooks. | | Ver logs de eventos | Consulta o histórico de tentativas de webhook, seus detalhes e o payload disponível. Requer também Webhooks. Conceda somente a quem precisa consultar essas informações. | | Reenviar eventos de webhooks | Solicita outra entrega de um evento elegível pelo histórico. Requer Webhooks e Ver logs de eventos, além da confirmação de identidade. | | Criar webhooks | Cadastra novos destinos de webhook e seleciona seus eventos. | | Excluir webhooks | Remove destinos de webhook existentes. | | Rotacionar webhooks | Rotaciona o segredo usado pelo webhook. | | Editar webhooks | Altera o nome do webhook e permite desativar ou reativar o cadastro. A mudança de atividade exige confirmação de identidade. | | Editar URL e eventos de webhooks | Altera a URL e os eventos selecionados do webhook, preservando nome, identificador, segredo e status. Requer também Webhooks e confirmação de identidade. | ## Conta e segurança As permissões abaixo controlam configurações da conta, checkout, dados bancários, compliance, documentos, exportações e consulta de atividades. Para consultar atividades de outros membros, use **Ver auditoria completa**. **Exportações** libera a central em **Relatórios / Exportações**. Para solicitar, consultar e baixar um arquivo, o membro precisa também da permissão do recurso correspondente, como **Extrato**. A central mostra somente os pedidos do próprio usuário, na empresa e no ambiente selecionados. Se não tiver acesso a nenhum recurso exportável, a central abre sem pedidos. | Item | Descrição | | --- | --- | | Ver configurações da conta | Consulta configurações, status, limites operacionais e checkout da conta. | | Editar aparência do checkout | Altera identidade visual, logo e ícone do checkout de pagamentos. | | Editar formas de pagamento | Ativa ou desativa as formas de pagamento padrão usadas nos links de pagamento. | | Dados bancários | Consulta os dados bancários da empresa. | | Editar dados bancários | Altera os dados bancários da empresa. | | Compliance | Consulta os dados cadastrais da empresa e o nome do representante legal. | | Termos e documentos | Consulta os termos e documentos da conta e permite baixar os arquivos disponíveis no leitor. Não libera edição nem acesso aos dados cadastrais da empresa. | | Exportações | Acessa a central de exportações e permite solicitar, acompanhar e baixar os próprios arquivos. Cada arquivo exige também a permissão do recurso correspondente. | | Ver auditoria completa | Amplia o registro de atividades para incluir ações de todos os membros da empresa. Sem essa permissão, o membro continua vendo somente as próprias ações. | | Exportar auditoria | Exporta o Registro de Atividades da empresa. Requer também Exportações e Ver auditoria completa. | ## Equipe e dispositivos Seis permissões controlam a equipe e ampliam o acesso às sessões de toda a empresa. | Item | Descrição | | --- | --- | | Equipe | Acessa a área de membros, funções e permissões atuais. | | Cadastrar membros da equipe | Envia convites para adicionar novos membros à conta. | | Remover membros da equipe | Remove membros e revoga o acesso deles à conta. | | Alterar permissões | Edita as permissões de outros membros dentro do alcance permitido. | | Ver sessões da empresa | Amplia a tela de dispositivos conectados para incluir o Proprietário e os demais membros. Sem essa permissão, cada membro vê somente as próprias sessões. | | Gerenciar sessões da empresa | Encerra sessões conectadas de outros usuários da empresa. O gerenciamento das próprias sessões continua disponível como recurso pessoal. | ## Perfis sugeridos Os perfis apenas preenchem a matriz. É possível ajustar a seleção antes de convidar ou salvar um membro. As permissões de aplicativos não são concedidas automaticamente aos membros existentes. Um administrador autorizado precisa selecionar **Ver aplicativos da empresa** ou **Revogar conexões da equipe** quando esse acesso for necessário. Membros existentes precisam receber **Exportações** de um administrador autorizado. O acesso a **Extrato** sozinho não inclui essa permissão. Os perfis **Super administrador**, **Administrador**, **Financeiro** e **Somente visualização** a incluem quando são aplicados. A permissão do recurso continua necessária para seus arquivos. Permissões já salvas não recebem acesso aos logs da API, de webhooks ou ao reenvio automaticamente. Um administrador autorizado deve habilitar **Ver logs de solicitações** ou **Ver logs de eventos** na matriz do membro, junto da permissão de consulta correspondente, ou reaplicar um perfil que inclua esse acesso. O Proprietário mantém acesso aos logs. **Reenviar eventos de webhooks** exige **Webhooks** e **Ver logs de eventos**. Ao selecionar o reenvio, a matriz inclui essas dependências quando o administrador pode concedê-las. Retirar qualquer uma delas também retira a seleção de reenvio. O acesso aos logs, sozinho, permite consultar, mas não solicitar outra entrega. O mesmo cuidado vale para **Editar URL e eventos de webhooks**: membros existentes precisam receber essa permissão de um administrador autorizado. Os perfis **Super administrador**, **Administrador** e **Desenvolvedor** a incluem quando são aplicados. Salvar uma configuração não amplia as permissões de outros membros. Ao selecionar **Ver logs de eventos** ou **Editar URL e eventos de webhooks**, a matriz também seleciona **Webhooks**, quando você pode conceder esse acesso. Se não puder, peça a um administrador autorizado para conceder as duas permissões. Remover **Webhooks** também remove essas duas seleções dependentes. ### Super administrador Seleciona todas as permissões da matriz. Use este perfil somente para quem administra toda a conta. ### Administrador - 40 permissões Acesso amplo à operação, inclusive consulta das chaves Pix de saque e dos logs da API e de webhooks. Não inclui alteração dessas chaves, dados bancários, plano, formas de pagamento, devoluções Pix, auditoria completa ou sessões de toda a empresa. ### Desenvolvedor - 15 permissões Inclui todas as permissões de chaves de API e webhooks. ### Financeiro - 10 permissões Inclui consulta de contestações, saldo, extrato, saques, configuração e solicitação de saques, consulta das chaves Pix de saque, planos e alteração de plano, além da central de exportações. Não permite alterar as chaves. ### Suporte - 6 permissões Inclui consulta e criação de cobranças, consulta, cadastro e edição de clientes e consulta de contestações. ### Somente visualização - 16 permissões Inclui as permissões de consulta dos módulos e Exportações, com acesso aos arquivos dos recursos permitidos. Não libera criação de cadastros, edição, remoção, logs da API e de webhooks, auditoria completa ou sessões de toda a empresa. # Overview (/en/) ## Get started ### Integration ### Connect your application Learn how authentication works, choose a Sandbox key, and explore the request and response examples in the API reference. Keep your secret key on your application's backend. [https://api.raims.com](https://api.raims.com) [Start integrating](/en/integracoes/autenticacao) [Official SDKs](/en/integracoes/sdks) · [API keys](/en/integracoes/chaves-api) · [API reference](/en/api) ### Payments ### Accept payments with Pix and boleto Learn about payment methods and configure your checkout. For an API integration, see how to create a charge and retrieve its payment details. [Create your first charge](/en/api/charges/overview) [Payment methods](/en/meios-de-pagamento) · [Checkout](/en/checkout#formas-de-pagamento) ### Account and team ### Manage your team's access Review invitations and permissions before granting access to your account. Use the financial guides to understand withdrawal conditions and tracking. [Review permissions](/en/usuarios-e-permissoes) [Withdrawals](/en/financeiro/saques) · [Automatic withdrawals](/en/financeiro/saques-automaticos) ## Use the documentation with AI Copy a prompt to use this page as context in your AI coding agent. ### Open in your AI agent ## Guides by area - [Authentication](/en/integracoes/autenticacao): Set the Bearer header and choose the key for the company and environment. - [API keys](/en/integracoes/chaves-api): Authentication, environments, secure storage, and IP restrictions. - [Webhooks](/en/integracoes/webhooks): Configuration, events, signatures, and protecting the secret. - [Withdrawals](/en/financeiro/saques): Available balance, destination account, limits, fees, and tracking. - [Automatic withdrawals](/en/financeiro/saques-automaticos): Minimum amount, schedule, fee, and next run. - [Payment methods](/en/meios-de-pagamento): Pix, boleto, and the codes used in API charges. - [Checkout](/en/checkout#formas-de-pagamento): Default payment methods and checkout appearance. - [Users and permissions](/en/usuarios-e-permissoes): Invitations, team management, and the scope of each permission. - [Rate limiting](/en/integracoes/rate-limiting): Request limits, concurrency, and how to handle HTTP 429. - [Types and identifiers](/en/tipos-e-identificadores): Formats and values used in the public API and Raims resources. **Availability for your access** Options depend on your permissions, the environment, and the account status. # Agent setup (/en/agentes) ## Pick your agent Select an agent to get step-by-step setup instructions for your project. * [Claude Code](/en/agentes/claude-code) * [Codex](/en/agentes/codex) * [Cursor](/en/agentes/cursor) * [GitHub Copilot](/en/agentes/github-copilot) * [OpenCode](/en/agentes/opencode) * [Vibe](/en/agentes/vibe) * [Devin](/en/agentes/devin) * [Visual Studio Code](/en/agentes/visual-studio-code) * [Command Code](/en/agentes/command-code) * [Bionic](/en/agentes/bionic) ## Frequently asked questions ### Do I need a Raims key to set up context? The documentation is public and can be read without a key. To send requests, your application needs an [API key](/en/integracoes/chaves-api) for the intended company and environment. Keep the secret on the backend. ### Where should I start my integration? Read the [authentication guide](/en/integracoes/autenticacao) and [API reference](/en/api). Start in Sandbox and review generated examples before sending a request. The prompts in these guides prepare a plan and do not request real credentials in the chat. ### What if the agent cannot read a link? Open the guide in your browser and provide the relevant public excerpt as context. The [index](https://docs.raims.com/llms.txt) and [consolidated documentation](https://docs.raims.com/llms-full.txt) can also be read by agents with network access. # Bionic + Raims (/en/agentes/bionic) ## Quick start ### Prepare the agent Install Bionic from the [official LM Studio documentation](https://lmstudio.ai/docs/bionic). Open the application and create a **Project** for your integration. ### Open your project Enable **Allow coding**, choose **Choose a folder for Bionic to work in**, and select your application root. Create the project and select the session's model. ### Add the documentation Ask the agent to read [Raims' documentation index](https://docs.raims.com/llms.txt) and open the relevant guides. [llms-full.txt](https://docs.raims.com/llms-full.txt) provides the consolidated content. Start with [authentication](/en/integracoes/autenticacao) and [charges](/en/api/charges/overview). ### Try a prompt ```text Read https://docs.raims.com/llms.txt and the authentication and charges guides. Inspect this application's backend and propose a plan to retrieve an existing Sandbox charge with GET /v1/charges/{id}. Prepare an example using protected server configuration for the key. Do not send requests or use real credentials. Show the sources and the files you would change before editing. ``` ## Project context Save the text below in a reference file, such as `raims-context.md`, and add it to the Bionic project's files. Those files are shared across project sessions. When starting a conversation, ask the agent to read this file before planning the integration. ```md # Raims integration - Read https://docs.raims.com/llms.txt before choosing endpoints and fields. - Use https://docs.raims.com/llms-full.txt for the consolidated documentation. - API base URL: https://api.raims.com. - In Raims product installation examples, select the latest stable version through the package manager (`latest` where supported). - Prepare examples for Sandbox, with Bearer authentication in the backend. - Keep the key in protected server configuration. Never put secrets in code, prompts, logs, or browser applications. - Explain the plan and request authorization before sending API requests. ``` ## Verify the setup Ask the agent to identify the guides it read, the API base URL, and the place in your backend where the key will be loaded. It should prepare the plan and example without asking you to paste a real credential. Reading the documentation does not authenticate the application. Requests use a [Raims API key](/en/integracoes/chaves-api) for the intended company and environment. ## Common issues ### The new session did not use the context Open the session in the same Project, check its project files, and explicitly request a read of `raims-context.md`. Also confirm the selected code folder. ### The agent cannot open the documentation Open the relevant guide in your browser and provide the public excerpt as context. Ask the agent to identify any missing information before suggesting code. ### The example uses the wrong authentication Ask the agent to review the authentication guide. The backend sends the Raims key with Bearer authentication; an AI provider credential does not replace it. ## Official sources * [Create a Bionic project](https://lmstudio.ai/docs/bionic/quick-start) * [Work with code](https://lmstudio.ai/docs/bionic/agent/code-project) * [Projects and sessions](https://lmstudio.ai/docs/bionic/projects-and-sessions) # Claude Code + Raims (/en/agentes/claude-code) ## Quick start ### Prepare the agent Install Claude Code using the [official quickstart](https://code.claude.com/docs/en/quickstart) for your operating system. Start a session and complete the agent's sign-in flow. ### Open your project Open a terminal at the root of the application you are connecting to Raims and run: ```bash claude ``` ### Add the documentation Ask the agent to read [Raims' documentation index](https://docs.raims.com/llms.txt) and open the relevant guides. [llms-full.txt](https://docs.raims.com/llms-full.txt) provides the consolidated content. Start with [authentication](/en/integracoes/autenticacao) and [charges](/en/api/charges/overview). ### Try a prompt ```text Read https://docs.raims.com/llms.txt and the authentication and charges guides. Inspect this application's backend and propose a plan to retrieve an existing Sandbox charge with GET /v1/charges/{id}. Prepare an example using protected server configuration for the key. Do not send requests or use real credentials. Show the sources and the files you would change before editing. ``` ## Project context Add the instructions below to `CLAUDE.md` at your project root. Preserve any existing guidance. Claude Code loads this file as context in project sessions. ```md # Raims integration - Read https://docs.raims.com/llms.txt before choosing endpoints and fields. - Use https://docs.raims.com/llms-full.txt for the consolidated documentation. - API base URL: https://api.raims.com. - In Raims product installation examples, select the latest stable version through the package manager (`latest` where supported). - Prepare examples for Sandbox, with Bearer authentication in the backend. - Keep the key in protected server configuration. Never put secrets in code, prompts, logs, or browser applications. - Explain the plan and request authorization before sending API requests. ``` ## Verify the setup Ask the agent to identify the guides it read, the API base URL, and the place in your backend where the key will be loaded. It should prepare the plan and example without asking you to paste a real credential. Reading the documentation does not authenticate the application. Requests use a [Raims API key](/en/integracoes/chaves-api) for the intended company and environment. ## Common issues ### The agent cannot find the instructions Check that the terminal is in the correct folder and that `CLAUDE.md` is at that project's root. Ask Claude Code to read the file before continuing. ### The agent cannot open the documentation Open the relevant guide in your browser and provide the public excerpt as context. Ask the agent to identify any missing information before suggesting code. ### The example uses the wrong authentication Ask the agent to review the authentication guide. The backend sends the Raims key with Bearer authentication; an AI provider credential does not replace it. ## Official sources * [Claude Code quickstart](https://code.claude.com/docs/en/quickstart) * [CLAUDE.md instructions](https://code.claude.com/docs/en/memory) # Codex + Raims (/en/agentes/codex) ## Quick start ### Install Codex With Node.js and npm available, install the CLI: ```bash npm install -g @openai/codex ``` The [official CLI guide](https://learn.chatgpt.com/docs/codex/cli) also covers Windows, macOS, and Linux installers. To use the desktop app, editor, or cloud, follow [OpenAI's quickstart](https://learn.chatgpt.com/docs/quickstart). ### Open your application folder From the root of the project you want to integrate with Raims, run: ```bash codex ``` Complete the authentication requested by Codex. Your agent account and Raims API key serve different purposes. ### Provide Raims context Ask Codex to read the [documentation index](https://docs.raims.com/llms.txt) and find the [authentication](/en/integracoes/autenticacao) and [charges](/en/api/charges/overview) guides. The [consolidated documentation](https://docs.raims.com/llms-full.txt) is also available as a reference. ### Try a prompt ```text Read https://docs.raims.com/llms.txt and the authentication and charges guides. Inspect this application's backend and propose a plan to retrieve an existing Sandbox charge with GET /v1/charges/{id}. Prepare an example that loads the key from protected server configuration. Do not send requests or use real credentials. Show your sources and the files you intend to change before editing. ``` ## Project context Add these instructions to `AGENTS.md` at your application's root, preserving any existing guidance. Codex reads `AGENTS.md` files when starting a session and also considers more specific directory instructions. ```md # Raims integration - Read https://docs.raims.com/llms.txt before choosing endpoints and fields. - Use https://docs.raims.com/llms-full.txt for the complete documentation. - API base URL: https://api.raims.com. - In Raims product installation examples, select the latest stable version through the package manager (`latest` where supported). - Prepare Sandbox examples with Bearer authentication on the backend. - Keep the key in protected server configuration. Do not put secrets in code, prompts, logs, or browser applications. - Explain the plan and request approval before sending API requests. ``` After saving, start a new project session to load the instructions. ## Check the setup Ask Codex to summarize the active instructions, list the guides it read, and explain where the application will load the key. Review the plan and code before approving a test. Reading the documentation does not authenticate your application. Requests use a [Raims API key](/en/integracoes/chaves-api) for the intended company and environment, stored in the private part of your system. ## Common issues ### Codex did not read the instructions Check that the session was opened in the correct folder, save `AGENTS.md`, and start another session. Ask Codex which instructions it loaded. ### The documentation does not open in the agent Check the agent's network permissions. You can also provide the public guide excerpt as context and ask Codex to identify any missing information. ### The example uses an AI provider key Ask for an authentication review. Your application uses the Raims key in the Bearer header; the credentials used to access Codex do not replace it. ## Official sources * [Codex CLI](https://learn.chatgpt.com/docs/codex/cli) * [Quickstart](https://learn.chatgpt.com/docs/quickstart) * [AGENTS.md instructions](https://learn.chatgpt.com/docs/agent-configuration/agents-md) # Command Code + Raims (/en/agentes/command-code) ## Quick start ### Prepare the agent Check the requirements and install the agent using the [official quickstart](https://commandcode.ai/docs/quickstart). The npm installation uses: ```bash npm i -g command-code@latest ``` ### Open your project In your application folder, run the command below and complete the agent's sign-in. On native Windows, the short alias is `cmdc`. ```bash command-code ``` ### Add the documentation Ask the agent to read [Raims' documentation index](https://docs.raims.com/llms.txt) and open the relevant guides. [llms-full.txt](https://docs.raims.com/llms-full.txt) provides the consolidated content. Start with [authentication](/en/integracoes/autenticacao) and [charges](/en/api/charges/overview). ### Try a prompt ```text Read https://docs.raims.com/llms.txt and the authentication and charges guides. Inspect this application's backend and propose a plan to retrieve an existing Sandbox charge with GET /v1/charges/{id}. Prepare an example using protected server configuration for the key. Do not send requests or use real credentials. Show the sources and the files you would change before editing. ``` ## Project context Add the content below to `AGENTS.md` at the application root. Command Code uses this file as project memory. The `/memory` command lets you open the file for editing within the session. ```md # Raims integration - Read https://docs.raims.com/llms.txt before choosing endpoints and fields. - Use https://docs.raims.com/llms-full.txt for the consolidated documentation. - API base URL: https://api.raims.com. - In Raims product installation examples, select the latest stable version through the package manager (`latest` where supported). - Prepare examples for Sandbox, with Bearer authentication in the backend. - Keep the key in protected server configuration. Never put secrets in code, prompts, logs, or browser applications. - Explain the plan and request authorization before sending API requests. ``` ## Verify the setup Ask the agent to identify the guides it read, the API base URL, and the place in your backend where the key will be loaded. It should prepare the plan and example without asking you to paste a real credential. Reading the documentation does not authenticate the application. Requests use a [Raims API key](/en/integracoes/chaves-api) for the intended company and environment. ## Common issues ### The command opened the Windows command processor Use `command-code` or the `cmdc` alias on native Windows. The name `cmd` also identifies the Windows command processor. ### The agent cannot open the documentation Open the relevant guide in your browser and provide the public excerpt as context. Ask the agent to identify any missing information before suggesting code. ### The example uses the wrong authentication Ask the agent to review the authentication guide. The backend sends the Raims key with Bearer authentication; an AI provider credential does not replace it. ## Official sources * [Install and start Command Code](https://commandcode.ai/docs/quickstart) * [Project memory](https://commandcode.ai/docs/memory) # Cursor + Raims (/en/agentes/cursor) ## Quick start ### Prepare the agent Install Cursor using the [official guide](https://cursor.com/docs/get-started/quickstart) and sign in. ### Open your project Open the application folder that will use the Raims API and start a conversation in the Agent panel. Check that the selected folder contains your backend code. ### Add the documentation Ask the agent to read [Raims' documentation index](https://docs.raims.com/llms.txt) and open the relevant guides. [llms-full.txt](https://docs.raims.com/llms-full.txt) provides the consolidated content. Start with [authentication](/en/integracoes/autenticacao) and [charges](/en/api/charges/overview). ### Try a prompt ```text Read https://docs.raims.com/llms.txt and the authentication and charges guides. Inspect this application's backend and propose a plan to retrieve an existing Sandbox charge with GET /v1/charges/{id}. Prepare an example using protected server configuration for the key. Do not send requests or use real credentials. Show the sources and the files you would change before editing. ``` ## Project context In the command palette, select **New Cursor Rule**, name it `raims`, and choose **Always Apply**. Cursor saves the rule as `.cursor/rules/raims.mdc`. Add the content below to the rule body and keep the metadata created by the editor. ```md # Raims integration - Read https://docs.raims.com/llms.txt before choosing endpoints and fields. - Use https://docs.raims.com/llms-full.txt for the consolidated documentation. - API base URL: https://api.raims.com. - In Raims product installation examples, select the latest stable version through the package manager (`latest` where supported). - Prepare examples for Sandbox, with Bearer authentication in the backend. - Keep the key in protected server configuration. Never put secrets in code, prompts, logs, or browser applications. - Explain the plan and request authorization before sending API requests. ``` ## Verify the setup Ask the agent to identify the guides it read, the API base URL, and the place in your backend where the key will be loaded. It should prepare the plan and example without asking you to paste a real credential. Reading the documentation does not authenticate the application. Requests use a [Raims API key](/en/integracoes/chaves-api) for the intended company and environment. ## Common issues ### The rule is missing from context Check that the rule is saved in `.cursor/rules` with the `.mdc` extension and is set to Always Apply. Open a conversation in the same project. ### The agent cannot open the documentation Open the relevant guide in your browser and provide the public excerpt as context. Ask the agent to identify any missing information before suggesting code. ### The example uses the wrong authentication Ask the agent to review the authentication guide. The backend sends the Raims key with Bearer authentication; an AI provider credential does not replace it. ## Official sources * [Cursor quickstart](https://cursor.com/docs/get-started/quickstart) * [Project rules](https://cursor.com/docs/rules) # Devin + Raims (/en/agentes/devin) ## Quick start ### Prepare the agent Sign in to [Devin](https://app.devin.ai) and follow the [first-session guide](https://docs.devin.ai/get-started/first-run) to connect and prepare your application repository. ### Open your project Select the repository that will use the Raims API. Start in **Ask** to investigate the code and prepare a plan before implementing it in **Agent**. ### Add the documentation Ask the agent to read [Raims' documentation index](https://docs.raims.com/llms.txt) and open the relevant guides. [llms-full.txt](https://docs.raims.com/llms-full.txt) provides the consolidated content. Start with [authentication](/en/integracoes/autenticacao) and [charges](/en/api/charges/overview). ### Try a prompt ```text Read https://docs.raims.com/llms.txt and the authentication and charges guides. Inspect this application's backend and propose a plan to retrieve an existing Sandbox charge with GET /v1/charges/{id}. Prepare an example using protected server configuration for the key. Do not send requests or use real credentials. Show the sources and the files you would change before editing. ``` ## Project context Add the text below to `AGENTS.md` at your repository root and make that version available to the Devin session. The agent looks for this file before coding. Preserve your application's build instructions and conventions. ```md # Raims integration - Read https://docs.raims.com/llms.txt before choosing endpoints and fields. - Use https://docs.raims.com/llms-full.txt for the consolidated documentation. - API base URL: https://api.raims.com. - In Raims product installation examples, select the latest stable version through the package manager (`latest` where supported). - Prepare examples for Sandbox, with Bearer authentication in the backend. - Keep the key in protected server configuration. Never put secrets in code, prompts, logs, or browser applications. - Explain the plan and request authorization before sending API requests. ``` ## Verify the setup Ask the agent to identify the guides it read, the API base URL, and the place in your backend where the key will be loaded. It should prepare the plan and example without asking you to paste a real credential. Reading the documentation does not authenticate the application. Requests use a [Raims API key](/en/integracoes/chaves-api) for the intended company and environment. ## Common issues ### The session cannot find the context file Check the repository and version used by the session. `AGENTS.md` must exist in that version, with integration guidance near the beginning. ### The agent cannot open the documentation Open the relevant guide in your browser and provide the public excerpt as context. Ask the agent to identify any missing information before suggesting code. ### The example uses the wrong authentication Ask the agent to review the authentication guide. The backend sends the Raims key with Bearer authentication; an AI provider credential does not replace it. ## Official sources * [Your first Devin session](https://docs.devin.ai/get-started/first-run) * [AGENTS.md in Devin](https://docs.devin.ai/onboard-devin/agents-md) # GitHub Copilot + Raims (/en/agentes/github-copilot) ## Quick start ### Prepare the agent Follow the [official GitHub Copilot setup](https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/set-up-copilot/install-copilot-extension) for your editor and sign in with a GitHub account that has Copilot access. This guide uses VS Code for configuration examples. ### Open your project Open the application folder you are connecting to Raims in VS Code. Open Copilot Chat and select the agent to work with the project code. ### Add the documentation Ask the agent to read [Raims' documentation index](https://docs.raims.com/llms.txt) and open the relevant guides. [llms-full.txt](https://docs.raims.com/llms-full.txt) provides the consolidated content. Start with [authentication](/en/integracoes/autenticacao) and [charges](/en/api/charges/overview). ### Try a prompt ```text Read https://docs.raims.com/llms.txt and the authentication and charges guides. Inspect this application's backend and propose a plan to retrieve an existing Sandbox charge with GET /v1/charges/{id}. Prepare an example using protected server configuration for the key. Do not send requests or use real credentials. Show the sources and the files you would change before editing. ``` ## Project context Create or update `.github/copilot-instructions.md` at your repository root. This file provides general instructions for Copilot sessions. Add the text below alongside your application's conventions. ```md # Raims integration - Read https://docs.raims.com/llms.txt before choosing endpoints and fields. - Use https://docs.raims.com/llms-full.txt for the consolidated documentation. - API base URL: https://api.raims.com. - In Raims product installation examples, select the latest stable version through the package manager (`latest` where supported). - Prepare examples for Sandbox, with Bearer authentication in the backend. - Keep the key in protected server configuration. Never put secrets in code, prompts, logs, or browser applications. - Explain the plan and request authorization before sending API requests. ``` ## Verify the setup Ask the agent to identify the guides it read, the API base URL, and the place in your backend where the key will be loaded. It should prepare the plan and example without asking you to paste a real credential. Reading the documentation does not authenticate the application. Requests use a [Raims API key](/en/integracoes/chaves-api) for the intended company and environment. ## Common issues ### The instructions were not applied Check that `.github/copilot-instructions.md` belongs to the folder open in VS Code. Review the editor's instruction settings and ask the agent to read the file explicitly. ### The agent cannot open the documentation Open the relevant guide in your browser and provide the public excerpt as context. Ask the agent to identify any missing information before suggesting code. ### The example uses the wrong authentication Ask the agent to review the authentication guide. The backend sends the Raims key with Bearer authentication; an AI provider credential does not replace it. ## Official sources * [Install GitHub Copilot in your editor](https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/set-up-copilot/install-copilot-extension) * [Copilot instructions in VS Code](https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/customize-copilot/configure-custom-instructions/add-repository-instructions-in-your-ide) # OpenCode + Raims (/en/agentes/opencode) ## Quick start ### Prepare the agent Choose the installation for your system in the [official OpenCode guide](https://opencode.ai/docs/). Configure your AI provider using its documented setup flow. That provider's credential is separate from your Raims API key. ### Open your project Open a terminal in your application folder and start the agent: ```bash opencode ``` ### Add the documentation Ask the agent to read [Raims' documentation index](https://docs.raims.com/llms.txt) and open the relevant guides. [llms-full.txt](https://docs.raims.com/llms-full.txt) provides the consolidated content. Start with [authentication](/en/integracoes/autenticacao) and [charges](/en/api/charges/overview). ### Try a prompt ```text Read https://docs.raims.com/llms.txt and the authentication and charges guides. Inspect this application's backend and propose a plan to retrieve an existing Sandbox charge with GET /v1/charges/{id}. Prepare an example using protected server configuration for the key. Do not send requests or use real credentials. Show the sources and the files you would change before editing. ``` ## Project context Add the content below to `AGENTS.md` at your project root. OpenCode uses this file for repository instructions. To generate an initial structure, the `/init` command analyzes the project; review the resulting file. ```md # Raims integration - Read https://docs.raims.com/llms.txt before choosing endpoints and fields. - Use https://docs.raims.com/llms-full.txt for the consolidated documentation. - API base URL: https://api.raims.com. - In Raims product installation examples, select the latest stable version through the package manager (`latest` where supported). - Prepare examples for Sandbox, with Bearer authentication in the backend. - Keep the key in protected server configuration. Never put secrets in code, prompts, logs, or browser applications. - Explain the plan and request authorization before sending API requests. ``` ## Verify the setup Ask the agent to identify the guides it read, the API base URL, and the place in your backend where the key will be loaded. It should prepare the plan and example without asking you to paste a real credential. Reading the documentation does not authenticate the application. Requests use a [Raims API key](/en/integracoes/chaves-api) for the intended company and environment. ## Common issues ### The agent is using the wrong project Start `opencode` inside the application folder and check that repository's `AGENTS.md`. Keep the integration instructions alongside local conventions. ### The agent cannot open the documentation Open the relevant guide in your browser and provide the public excerpt as context. Ask the agent to identify any missing information before suggesting code. ### The example uses the wrong authentication Ask the agent to review the authentication guide. The backend sends the Raims key with Bearer authentication; an AI provider credential does not replace it. ## Official sources * [OpenCode installation and setup](https://opencode.ai/docs/) * [AGENTS.md instructions](https://opencode.ai/docs/rules/) # Vibe + Raims (/en/agentes/vibe) ## Quick start ### Prepare the agent Install Vibe CLI using the instructions for your system in [Mistral's official guide](https://docs.mistral.ai/vibe/code/cli/install-setup). On first launch, complete the sign-in or AI provider setup wizard. ### Open your project Open a terminal at your application root and run: ```bash vibe ``` ### Add the documentation Ask the agent to read [Raims' documentation index](https://docs.raims.com/llms.txt) and open the relevant guides. [llms-full.txt](https://docs.raims.com/llms-full.txt) provides the consolidated content. Start with [authentication](/en/integracoes/autenticacao) and [charges](/en/api/charges/overview). ### Try a prompt ```text Read https://docs.raims.com/llms.txt and the authentication and charges guides. Inspect this application's backend and propose a plan to retrieve an existing Sandbox charge with GET /v1/charges/{id}. Prepare an example using protected server configuration for the key. Do not send requests or use real credentials. Show the sources and the files you would change before editing. ``` ## Project context Add the instructions below to your application's `AGENTS.md`. Vibe loads this file in trusted project folders. Check the folder before accepting the agent's trust prompt. ```md # Raims integration - Read https://docs.raims.com/llms.txt before choosing endpoints and fields. - Use https://docs.raims.com/llms-full.txt for the consolidated documentation. - API base URL: https://api.raims.com. - In Raims product installation examples, select the latest stable version through the package manager (`latest` where supported). - Prepare examples for Sandbox, with Bearer authentication in the backend. - Keep the key in protected server configuration. Never put secrets in code, prompts, logs, or browser applications. - Explain the plan and request authorization before sending API requests. ``` ## Verify the setup Ask the agent to identify the guides it read, the API base URL, and the place in your backend where the key will be loaded. It should prepare the plan and example without asking you to paste a real credential. Reading the documentation does not authenticate the application. Requests use a [Raims API key](/en/integracoes/chaves-api) for the intended company and environment. ## Common issues ### Project context did not load Check the folder where you started `vibe`, the presence of `AGENTS.md`, and the project's trust confirmation. Consult the official guide to review that configuration. ### The agent cannot open the documentation Open the relevant guide in your browser and provide the public excerpt as context. Ask the agent to identify any missing information before suggesting code. ### The example uses the wrong authentication Ask the agent to review the authentication guide. The backend sends the Raims key with Bearer authentication; an AI provider credential does not replace it. ## Official sources * [Install and start Vibe CLI](https://docs.mistral.ai/vibe/code/cli/install-setup) * [Vibe project instructions](https://docs.mistral.ai/vibe/code/cli/agents) # Visual Studio Code + Raims (/en/agentes/visual-studio-code) ## Quick start ### Prepare the agent Install VS Code and follow the [official GitHub Copilot setup](https://code.visualstudio.com/docs/setup/copilot). This guide uses Copilot in the editor; sign in with the appropriate GitHub account. ### Open your project Open the application folder in VS Code and start a Chat conversation. Use the Copilot agent with access to your backend project. ### Add the documentation Ask the agent to read [Raims' documentation index](https://docs.raims.com/llms.txt) and open the relevant guides. [llms-full.txt](https://docs.raims.com/llms-full.txt) provides the consolidated content. Start with [authentication](/en/integracoes/autenticacao) and [charges](/en/api/charges/overview). ### Try a prompt ```text Read https://docs.raims.com/llms.txt and the authentication and charges guides. Inspect this application's backend and propose a plan to retrieve an existing Sandbox charge with GET /v1/charges/{id}. Prepare an example using protected server configuration for the key. Do not send requests or use real credentials. Show the sources and the files you would change before editing. ``` ## Project context Create or update `.github/copilot-instructions.md` at the application root. This is the general instruction file for Copilot in this guide. If you choose another agent in VS Code, follow its documented instruction format. ```md # Raims integration - Read https://docs.raims.com/llms.txt before choosing endpoints and fields. - Use https://docs.raims.com/llms-full.txt for the consolidated documentation. - API base URL: https://api.raims.com. - In Raims product installation examples, select the latest stable version through the package manager (`latest` where supported). - Prepare examples for Sandbox, with Bearer authentication in the backend. - Keep the key in protected server configuration. Never put secrets in code, prompts, logs, or browser applications. - Explain the plan and request authorization before sending API requests. ``` ## Verify the setup Ask the agent to identify the guides it read, the API base URL, and the place in your backend where the key will be loaded. It should prepare the plan and example without asking you to paste a real credential. Reading the documentation does not authenticate the application. Requests use a [Raims API key](/en/integracoes/chaves-api) for the intended company and environment. ## Common issues ### The selected agent uses a different format Check which agent is active in Chat. This guide uses Copilot instructions; Claude and Codex have their own formats described in the VS Code documentation. ### The agent cannot open the documentation Open the relevant guide in your browser and provide the public excerpt as context. Ask the agent to identify any missing information before suggesting code. ### The example uses the wrong authentication Ask the agent to review the authentication guide. The backend sends the Raims key with Bearer authentication; an AI provider credential does not replace it. ## Official sources * [Set up Copilot in VS Code](https://code.visualstudio.com/docs/setup/copilot) * [Instructions and formats by agent](https://code.visualstudio.com/docs/agent-customization/custom-instructions) # Start here (/en/api) **Before you test** The interactive console in this documentation accepts only **Sandbox** credentials, which start with `sk_test_`. To test, select or enter a Sandbox key. See [API keys](/en/integracoes/chaves-api) to create and protect your credential. The API Reference brings together Raims endpoints, parameters, responses and code examples. The console lets you enter request data, send a test request and inspect its response on the same page. Choose the language of the example and copy the request to adapt it to your system. Examples reflect the values entered in the fields. **Preparing your integration?** See the [API keys](/en/integracoes/chaves-api) and [Webhooks](/en/integracoes/webhooks) guides for setup and security guidance. Use the API Reference to check the details of each request during implementation. To download or import the contract and generate a client for your project, see the [OpenAPI contract](/en/api/openapi) guide. To interpret resource codes and ID prefixes, see the [types and identifiers map](/en/tipos-e-identificadores) in Guides. ## Base URL The base URL of the Raims API is: ```text https://api.raims.com ``` Sandbox and Production use the same address. The credential sent in the request determines the environment. ## API environments Sandbox and Production belong to the same company, with separate data and credentials. The key identifies the company and environment of the request; these values are not selected in the request body. | Environment | Credential prefix | Use | | ----------- | ----------------- | --------------------------------------------------------------------------------------------------- | | Sandbox | `sk_test_` | Development, integration testing and tests in the documentation console, without moving real money. | | Production | `sk_live_` | Requests with real effects on the account, sent by your system outside the documentation console. | Check the method and full address shown on each endpoint page. Use that address in tests and integration examples. Before using Production, check the credential and your application settings. To test an approved payment or a failed charge without moving real money, use [Simulation](/en/api/simulations/overview). These endpoints accept only Sandbox. Other requests remain on their respective resource pages and use the key for the test environment. ## Authentication See the [Authentication](/en/integracoes/autenticacao) guide to configure headers, choose the environment key and review integration access. The API uses the `Authorization` header with the HTTP Bearer scheme: ```http Authorization: Bearer sk_test_... ``` `sk_test_...` is only a placeholder. In the console, enter your full Sandbox key in **Credentials**. The example builds the authentication header for you. When you use a Dashboard session, the selector offers only Sandbox keys whose access is within your permissions. A key shown with a hidden secret in the key manager may be unavailable in the console. Ask an authorized person to review access in [API keys](/en/integracoes/chaves-api#permissões-da-chave). The key's configured IP restrictions also apply to tests. A source outside the authorized ranges receives `403`. See [IP restrictions](/en/integracoes/chaves-api#restrições-de-ip) before changing this setting. The console does not save your key in the browser. In your system, keep the secret on the server responsible for the integration and do not expose it in the browser, repositories or logs. ## Using the console 1. In the sidebar, choose the endpoint you want to test. Check its method, address and field rules. 2. Select or enter a Sandbox credential in **Credentials**. 3. Fill in the required fields and any optional data you want to send. Suggested placeholder values are not sent automatically. If a required field is missing, the console highlights it before sending. When the endpoint accepts idempotency, see [Idempotency](/en/api/idempotencia) before entering `Idempotency-Key` under **Headers**. 4. Choose the language to inspect the example, then select **Try it**. 5. Check the HTTP status and body in the **Response** panel. The **Responses** section at the end of the page details the expected results. A real response also shows `Request-Id`. Store it when investigating an attempt or asking support for help. See [Request identifier](/en/api/request-id) for its limits. To inspect an example without sending a request, expand a status in **Responses**. The **Response** panel shows the corresponding example when one is defined for the endpoint. If the credential is invalid, correct the field before testing. If a warning about Production credentials appears, replace the key with a Sandbox credential. See [HTTP response codes](/en/api/codigos-http-das-respostas) for general errors, response formats and retry guidance. Even after an error or connection loss, the request may have been processed. Check the result before trying again. # Retrieve the account number (/en/api/accounts/account-number) Retrieve the branch and financial account number for your company at Raims. Use a Production key on your integration's server. Sandbox does not have this information; the console in this documentation accepts only Sandbox keys. See the requirements in [Account information and customization](/en/api/accounts/overview#recuperar-número-de-conta). GET /v1/accounts/account_number # Retrieve checkout customization (/en/api/accounts/checkout-settings) Retrieve your company's checkout settings to check its images, colors, support contact, and available default payment methods. The image fields also show the progress of a submitted change. See what these preferences affect and how to change them in [Checkout customization](/en/api/accounts/overview#personalização-do-checkout). GET /v1/accounts/checkout_settings # Retrieve account context (/en/api/accounts/context) Retrieve the authenticated company, its environment, and the current account status. Use these details to identify the account in your integration and interpret response amounts and dates. See how to track changes between requests in [Account information and customization](/en/api/accounts/overview#consultar-contexto-da-conta). GET /v1/accounts/context # Discard an image upload (/en/api/accounts/delete-checkout-upload) Discard an unused upload with the `id` received when preparing the file. The request accepts uploads that have not yet been associated with the checkout, including those whose authorization has expired. To remove an image that is already associated, use the customization PATCH. See the requirements in [Discard an unused upload](/en/api/accounts/overview#descartar-envio-não-utilizado). DELETE /v1/accounts/checkout_settings/uploads/{id} # Prepare an icon upload (/en/api/accounts/favicon-upload) Send the details of a square image to get a temporary URL for uploading the icon. After uploading the file, associate the returned identifier with the checkout settings. This request does not replace the icon by itself. See the steps in [Checkout logo and icon](/en/api/accounts/overview#logo-e-ícone-do-checkout). POST /v1/accounts/checkout_settings/favicon_uploads # Retrieve account fees (/en/api/accounts/fees) Retrieve the Pix and boleto fees that apply to your company to estimate costs in your system and check the account's current terms. See how to interpret the values in [Account information and customization](/en/api/accounts/overview). GET /v1/accounts/fees # Prepare a logo upload (/en/api/accounts/logo-upload) Send the image details to get a temporary upload URL. After uploading the file, associate the returned identifier with the checkout settings. This request does not replace the logo by itself. See how to upload the file and check its progress in [Checkout logo and icon](/en/api/accounts/overview#logo-e-ícone-do-checkout). POST /v1/accounts/checkout_settings/logo_uploads # Account information and customization (/en/api/accounts/overview) Confirm the integration's company and environment, and retrieve your company's branch and financial account number at Raims. You can also check the commercial terms to estimate receipt costs in your integration and configure the images, colors, and support contact shown in the checkout. | Purpose | Method and path | | ----------------------------------------- | ----------------------------------------------------- | | Retrieve company, environment, and status | `GET /v1/accounts/context` | | Retrieve branch and account number | `GET /v1/accounts/account_number` | | Retrieve current fees | `GET /v1/accounts/fees` | | Retrieve checkout customization | `GET /v1/accounts/checkout_settings` | | Update checkout customization | `PATCH /v1/accounts/checkout_settings` | | Prepare a logo upload | `POST /v1/accounts/checkout_settings/logo_uploads` | | Prepare an icon upload | `POST /v1/accounts/checkout_settings/favicon_uploads` | | Discard an unused upload | `DELETE /v1/accounts/checkout_settings/uploads/{id}` | ## Retrieve account context Use [Retrieve account context](/en/api/accounts/context), with `GET /v1/accounts/context`, to get the public identifier, display name, and status of the company identified by the key. The response also provides the key's environment and the currency, unit, and time zone references used by the integration. The request accepts no parameters or body. Use a key for the environment you want to retrieve. A company with a pending registration can retrieve its context only with a Sandbox key. `checked_at` reports when the details were retrieved, in Unix seconds UTC. Compare `access_revision` with a previous response to recognize changes in the account context or integration access. This value is an opaque revision; do not use it as a credential. The key represents the company and environment integration. This request does not identify an owner or employee and does not confirm that a charge, refund, or withdrawal can be executed. Each endpoint retains its own requirements and checks. ## Retrieve the account number Use [Retrieve the account number](/en/api/accounts/account-number), with `GET /v1/accounts/account_number`, to get `agency` and `account` for your company's financial account. The request uses the company identified by the API key and accepts no parameters or body. This request requires authorized Production access and an approved, enabled financial account. Sandbox has no financial branch or account number and returns `403 DATA_ENVIRONMENT_NOT_SUPPORTED`. The console in this documentation accepts only Sandbox keys; retrieve the details from your integration's server, without entering a Production key in the documentation or browser. If the account is not approved and enabled, or its details are unavailable, the response is `404 ACCOUNT_NUMBER_NOT_AVAILABLE`. Check the account's status in the Dashboard before trying again. Keep the branch and account as text, including leading zeros and the returned formatting. The request does not register an account or change the destination of [withdrawals](/en/api/withdrawals/overview). ## Retrieve account fees Use [Retrieve account fees](/en/api/accounts/fees), with `GET /v1/accounts/fees`. The response contains the current Pix and boleto fee rules in the plan selected by the company. The request does not change the plan or fees. Current values also do not indicate which fee applied to a past transaction. To check a fee already charged, retrieve the entries in the [Statement](/en/api/statements/overview). ## Understand the values Each payment method returns its configured percentage component, fixed amount, and fee limits: | Field | Meaning | | ------------------- | ---------------------------------------------------- | | `percentage_rate` | Fee percentage. For example, `0.8` represents 0.8%. | | `fixed_fee_cents` | Fixed component of the fee, in Brazilian real cents. | | `minimum_fee_cents` | Minimum fee amount, in Brazilian real cents. | | `maximum_fee_cents` | Maximum fee amount, in Brazilian real cents. | A value of `85` in a cents field represents R$ 0.85. A `null` field indicates that the component or limit is not configured. Both percentage and fixed components can be present in the same rule. If `pix` or `boleto` is `null`, there is no current rule for that method in the selected plan. This does not mean that receiving payments is free. The presence of a rule also does not confirm that the method is enabled to receive payments. ## Checkout customization Use [Retrieve checkout customization](/en/api/accounts/checkout-settings) to check the company's images, colors, support email, and default payment methods in the key's environment. Sandbox and Production have separate settings; changing one environment preserves the other's settings. To change the colors or contact, use [Update checkout customization](/en/api/accounts/update-checkout-settings). Send `hex_primary_color` for the primary color and `hex_secondary_color` for the background color, in `#RRGGBB` format. Omitting a field keeps its value. In `support_email`, `null` or empty text removes the support contact. Colors must retain valid values. An empty body keeps the current settings. `payment_method_types` identifies the default methods enabled and available for the checkout. Updating through the API does not change this list. To choose Pix and boleto, use **Account / Settings / Payment checkout**. The account's default methods apply when the charge and link have no settings of their own. Changing this default may change the options on charges that use it. A charge's own list continues to apply; the link can restrict those options. See [Checkout and payment methods](/en/checkout). These preferences do not change a charge's amount, due date, or status, and do not confirm payment. The request returns the current settings; it does not show the appearance used on a past date. ## Checkout logo and icon Uploading each image has three steps: 1. Use [Prepare a logo upload](/en/api/accounts/logo-upload) or [Prepare an icon upload](/en/api/accounts/favicon-upload). Send the file's type, size in bytes, width, and height. PNG and JPEG are accepted; the icon must be square. Check the limits in the corresponding endpoint's parameters. 2. Send the file bytes to `upload_url` with the `PUT` method. Set `Content-Type` and `Content-Length` according to `content_type` and `file_size` in the response. Do not send the Raims API key to this address. The URL is temporary. Complete the upload and association before `expires_at`, expressed in Unix seconds UTC. 3. Use [Update checkout customization](/en/api/accounts/update-checkout-settings) and send the returned `id` in `logo_upload_id` or `favicon_upload_id`. The two fields are independent. Use a logo upload in the logo field and an icon upload in the icon field, always for the same company and environment. Getting the URL or completing the PUT does not change the image shown in the checkout. Association through PATCH may return `202` while the image is checked. Retrieve the settings to track `logo.status` and `favicon.status`: | `status` | How to interpret it | | --------- | ------------------------------------------------------------ | | `absent` | No image is configured. | | `ready` | The image is ready to use in the checkout. | | `pending` | The uploaded image is still being processed. | | `failed` | The uploaded image could not be applied. Check `error_code`. | `url` contains the current image or `null` when none is available. During processing or after a failure, the previous image remains in use, if one exists. The new image is used when the change finishes with `status: ready`. If you need to repeat the PATCH while the image is being processed, use the same upload ID. An upload that failed or has already been replaced cannot be applied again. Prepare a new upload to replace the image again. When `error_code` has a value, check the reason: | `error_code` | What to do | | ---------------------------------- | -------------------------------------------------------------------------------------------- | | `CHECKOUT_ASSET_INVALID_IMAGE` | Check the file, type, and dimensions before preparing another upload. | | `CHECKOUT_ASSET_UPLOAD_NOT_FOUND` | The file is unavailable. Prepare another upload. | | `CHECKOUT_ASSET_PROCESSING_FAILED` | Applying the image failed. Prepare another upload; if the problem persists, contact support. | ## Remove a checkout image To remove an image, send `logo_upload_id: null` or `favicon_upload_id: null`. Omitting these fields keeps the current images. Removal can also require processing; it finishes with `status: absent`. You can also change this setting in the checkout appearance section of the Dashboard. ## Discard an unused upload If you abandon an upload before associating it, use [Discard an image upload](/en/api/accounts/delete-checkout-upload), with the same `id` returned when preparing it. Discarding also accepts an expired authorization. The `deleted: true` response confirms that the upload was discarded and can no longer be applied; repeating the request keeps this result. An upload already associated with the checkout cannot be discarded through this endpoint. To remove the image, use PATCH with the corresponding field set to `null`. ## Company and environment These requests identify the company through [API-key or OAuth authentication](/en/integracoes/autenticacao). You do not need to send the company identifier in the request. Fees are shared between Sandbox and Production. A Sandbox key retrieves the same rules for the company, while test payments remain separate from real transactions. Protect the key on your integration's server. Handle errors using the HTTP status and `error.code`, as described in [HTTP response codes](/en/api/codigos-http-das-respostas). # Update checkout customization (/en/api/accounts/update-checkout-settings) Change the images, colors, and support email for your company's checkout. Send only the fields you want to change. Payment methods remain configured through the Dashboard. To replace an image, upload the file to the temporary URL before sending its identifier in this request. The response may indicate that the image is still being processed; check the settings before considering the replacement complete. See the effects of these changes in [Checkout customization](/en/api/accounts/overview#personalização-do-checkout). PATCH /v1/accounts/checkout_settings # Retrieve the balance (/en/api/balances) Retrieve the current account values for your key's company and environment. The request does not reserve money or confirm that a withdrawal or refund will be accepted. See [Financial information](/en/api/balances/overview) to understand the values and how they relate to the statement. GET /v1/balances # Retrieve expected receipts (/en/api/balances/forecast) Retrieve estimated receipts for the period to track the financial projection in your system. The projected balance is an estimate and does not indicate how much can be withdrawn. See the criteria and the difference between the forecast and balance in [Expected receipts](/en/api/balances/overview#recebimentos-previstos). GET /v1/balances/forecast # Financial information (/en/api/balances/overview) Use the balance to check how much the account holds at the time of the request and what portion is available. The values can change with new receipts, withdrawals, refunds, holds, and releases. Charge statistics show totals by period. They help you track receipts. The forecast estimates what may still be received during the period. Neither replaces a balance request. | Purpose | Method and path | | ------------------------------------ | ----------------------------- | | Retrieve the current balance | `GET /v1/balances` | | Retrieve charge statistics | `GET /v1/charges/statistics` | | Retrieve expected receipts | `GET /v1/balances/forecast` | | Retrieve withdrawals being processed | `GET /v1/withdrawals/summary` | ## Retrieve the current balance Use [Retrieve the balance](/en/api/balances), with `GET /v1/balances`. The response shows amounts in Brazilian real cents. The request does not reserve money. A withdrawal or refund remains subject to its own conditions, limits, and another balance check when requested. ## Understand the values | Field | Meaning | | ------------------------ | ----------------------------------------------------------------------------- | | `total_amount_cents` | Total account balance, including the blocked portion. | | `blocked_amount_cents` | Portion of the balance held and unavailable for use. | | `available_amount_cents` | Amount available after deducting the blocked portion, with a minimum of zero. | If the account has R$ 100.00 in total and R$ 30.00 blocked, the response is: ```json { "total_amount_cents": 10000, "blocked_amount_cents": 3000, "available_amount_cents": 7000 } ``` A hold preserves the total amount and reduces the available balance. Releasing it makes the amount available again; it does not represent a new receipt. The total retains any negative value, while the available balance is zero when there is no amount free to use. ## Balance and statement The balance shows current amounts. The [Statement](/en/api/statements/overview) shows recorded financial entries, with their types and references. Adding up a page or filtered entries does not replace a balance request. The balance response does not show how much the account held after a past entry. To check a transaction, use [Retrieve an entry](/en/api/statements/retrieve). ## Charge statistics Use [Retrieve charge statistics](/en/api/charges/statistics), with `GET /v1/charges/statistics`, to track counts, amounts, and payment rate in an ERP, report, or your own dashboard. The request gathers totals for the key's company and environment, so you do not need to traverse every page of charges. | Field | What it includes | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `issued` | Charges created during the period, including canceled charges, excluding deleted ones. | | `issued_paid` | Charges created during the period that are paid, partially refunded, or refunded. | | `received` | Payments confirmed during the period, even if the charge was created earlier. Includes paid, partially refunded, and refunded charges. | | `payment_rate` | Percentage of the `issued_paid` count relative to the `issued` count. Returns zero when no charges were issued. | The `issued`, `issued_paid`, and `received` groups provide `count` for the quantity and `amount_cents` for the amount in Brazilian real cents. Amounts are gross, without deducting fees or refunds. A refunded charge remains in these totals at its original amount while it is in one of the included states. Disputed charges are not included in `issued_paid` or `received`. The request does not show the account's available balance. For example, a charge created yesterday and paid today is included in `received` in today's request. It is not included in today's `issued` or `issued_paid`, because it was created outside that period. To check individual charges, use [List charges](/en/api/charges/list). To find how much money is available in the account, use [Retrieve the balance](/en/api/balances). ## Statistics period and updates If the response reports `INVALID_FIELDS` with `period` and `INVALID_VALUE` in `error.details`, choose one of the accepted periods. Send `period` only once. Custom dates in `start_at` or `end_at` are not filters: an unknown parameter receives `UNKNOWN_QUERY_PARAMETER`. The `period` parameter accepts `today`, `last_7_days`, `last_15_days`, and `last_30_days`. When omitted, the request uses today. Periods use calendar days in São Paulo time and include the current day. `last_7_days`, for example, starts at midnight six days ago and ends at midnight tomorrow. `start_at` and `end_at` are response fields, not filters. They provide the inclusive start and exclusive end of the period in Unix seconds UTC. Use these boundaries to identify the report's interval. The request accepts only the periods listed in `period`, without custom start and end dates. Totals can take a few seconds to reflect a creation, payment, refund, or deletion. `updated_at` provides the latest update to the retrieved data, or `null` when this information is unavailable. Repeated requests do not bring the update forward. ## Expected receipts Use [Retrieve expected receipts](/en/api/balances/forecast), with `GET /v1/balances/forecast`, to track the same financial estimate shown in the Dashboard Summary. `receivable_amount_cents` shows confirmed payments that the calculation still includes as expected receipts within the selected period. The request does not add open charges or look for future due dates. The period refers to the expected receipt date, not the charge's creation date. `projected_balance_cents` adds this estimate to the account's current total balance. For example, a total balance of R$ 100.00 with R$ 25.00 expected gives a projected R$ 125.00. The amount may include blocked balance and does not confirm bank settlement, a guaranteed deadline, or availability for withdrawal. Use [Retrieve the balance](/en/api/balances) to check the current total, blocked, and available amounts. The `period` parameter accepts `today`, `last_7_days`, `last_15_days`, and `last_30_days`; the default is `today`. Periods include today and use the São Paulo calendar. `last_7_days`, for example, starts at midnight six days ago and ends at midnight tomorrow. This request does not project the next seven, fifteen, or thirty days. `start_at` provides the inclusive start and `end_at` the exclusive end of the period. `forecast_date` identifies the estimate's reference day, at midnight today in São Paulo. These fields use Unix seconds UTC. Values can take a few seconds to reflect changes in payments. `updated_at` provides the forecast data's update time, or `null` when it is unavailable. An estimate of zero does not prove that all payments have settled. In Sandbox, values are simulated and do not represent real receipts. ## Withdrawals being processed Use [Retrieve withdrawals being processed](/en/api/withdrawals/summary) to track the total of withdrawals still awaiting completion. The request requires authorized Production access and includes withdrawals with status `PENDING` or `PROCESSING`. `processing_count` provides the number of withdrawals, and `processing_amount_cents` adds the requested amounts, including the fee, in Brazilian real cents. When no withdrawals have these statuses, both fields return zero. This total represents money committed to the requests. Do not add it to the available balance or treat it as a confirmed credit to the destination account. To check each request and its result, use [List withdrawals](/en/api/withdrawals). Retrieving the summary does not request another withdrawal or change the progress of existing ones. ## Company and environment These requests use [API-key or OAuth authentication](/en/integracoes/autenticacao) for the authorized company and environment. A Sandbox key retrieves the simulated balance, separate from the Production balance. The console accepts only Sandbox keys. You do not need to send a company or account in the request body. Handle errors using the HTTP status and `error.code`, as described in [HTTP response codes](/en/api/codigos-http-das-respostas). # Create a new charge (/en/api/charges) Creates a charge for a customer already registered in the company and authenticated environment. In `customer_id`, use the identifier received when creating or looking up the customer. To receive Pix data when creating the charge, send `payment_method: 1` without a custom list in `payment_method_types`. The API uses the linked customer's CPF/CNPJ. To issue a boleto, send `payment_method: 2` without a custom list. Issuance uses the customer's name, valid email, CPF/CNPJ and address. Raims can fill in missing street, neighborhood, city and state from the postal code when this data is available. Provide the number in the customer's record; it does not come from the postal code. See the [address conditions](/en/api/charges/overview#receber-o-boleto-na-criação). If Pix or boleto issuance is pending, store the returned ID and track the same charge through the [individual lookup](/en/api/charges/retrieve). To associate the charge with the order in your system, use `external_reference`. See [Reference in your system](/en/api/charges/overview#referência-no-seu-sistema) to understand this association and avoid duplicate charges when repeating a request. Use `create_checkout: true` to receive the checkout link without configuring a return URL. Providing a return URL also generates the link, even with `send_email: false`, without requesting an email. `cancel_redirect_url` is the destination for returning to the company's website; this navigation does not revoke the charge. See the [charges overview](/en/api/charges/overview) to understand due dates, return URLs and email requests. The `payment_method` codes and checkout selection are explained in [Payment methods](/en/meios-de-pagamento#códigos-na-api). POST /v1/charges # Download a boleto (/en/api/charges/boleto) Get a temporary URL to download the charge's boleto that has already been issued. Call this endpoint with your API key or OAuth session and use the returned `url` to download the PDF from `files.raims.com` without sending the key in that download. The lookup does not request another issuance. The boleto is used to collect payment and does not prove payment. For the document of a confirmed payment, use [Download a payment receipt](/en/api/charges/receipt). Check the conditions in [Boleto PDF](/en/api/charges/overview#boleto-em-pdf). GET /v1/charges/{id}/boleto # List charges (/en/api/charges/list) Looks up charges in the authenticated company and environment. You can filter by charge identifier, external reference, customer, email registered on the charge, status, payment method or creation, due date and payment periods. The filter uses the charge's current payment method; simply selecting an option in checkout does not change this value. Changes to status or external reference may take a few seconds to appear in filtered results. Start without a cursor, process `list` and, while `page.has_next` is `true`, copy `page.next_after` to `after`, keeping the filters and sorting. Copy the entire cursor without interpreting or calculating its contents. See [Listing and pagination](/en/api/listagem-e-paginacao) to go back with `before`. See how filters and sorting work in [List charges](/en/api/charges/overview#listar-cobranças). The meaning of `external_reference` is explained in [Reference in your system](/en/api/charges/overview#referência-no-seu-sistema). GET /v1/charges # Charges (/en/api/charges/overview) A charge specifies the amount a customer should pay your company. After creating it, track its status to check whether the customer paid. Creation alone does not confirm payment or available account balance. The base URL for requests is `https://api.raims.com`. ## Customer and environment Use a customer already registered in the authenticated company and environment. To register the payer, see [Create a customer](/en/api/customers). To look up an existing record, use [Retrieve a customer](/en/api/customers/retrieve). Copy the customer's `id` to `customer_id` when creating the charge. Do not send your own system's identifier in that field. Sandbox records and charges are kept separate from Production data. Use Sandbox to test without moving real funds. Use [Simulation](/en/api/simulations/overview) to confirm a payment or apply a failure to a test charge. You can also test pending or failed issuance and cancellation, as well as boleto clearing before settlement. These endpoints are exclusive to Sandbox and let you check results without making a real payment. To issue Pix when creating the charge, the linked customer must have a valid CPF/CNPJ. The API uses this record; do not send another tax ID in the charge request. The tax ID identifies the customer being charged without requiring payment from a bank account held by that person or business. ## Create a charge [Create a new charge](/en/api/charges), with `POST /v1/charges`, accepts the customer and charge amount. Send `amount_cents` as an integer in cents: `10000` represents R$ 100,00. The allowed amount ranges from 100 to 999999999999 cents. Each request creates one charge. `payment_method_types` lets you define a custom list of accepted methods that overrides the account default for that charge only. Omitting the list or sending `null` keeps inheritance from the checkout configuration. Platform availability still applies, and a custom link configuration can reduce the charge's options. `payment_method` is separate from the list and keeps the behavior for choosing or restricting a method when the list is not provided. With a custom list, omit this field or send `0`. See formats and codes in [Payment methods](/en/meios-de-pagamento#códigos-na-api). Title and description are optional and accept up to 512 characters each. Store the identifier returned by the API to associate the charge with your system. If a request ends without a conclusive response, check the result before repeating the request. ## Receive Pix when creating a charge In `POST /v1/charges`, send the `customer_id` of a registered customer and `payment_method: 1`, without a custom list in `payment_method_types`. Issuance uses the valid CPF/CNPJ in that record; do not send another tax ID, name or email in the charge request. The response includes `payment_information.pix`, with `copy_paste`, `expires_at` and `qr_code_base64`. You can display this data in your system without sending the payer to Raims checkout. Issuance does not confirm payment. `payment_information.pix_status` shows the result: `available` when Pix is available, `pending` while issuance has not been confirmed, `failed` when it could not be issued and `not_generated` when no Pix issuance is available. For `failed`, check `payment_information.pix_error` for the reason. ## Display the QR Code and use the copy-and-paste code When receiving Pix during creation with `POST /v1/charges`, the QR Code is returned in `payment_information.pix.qr_code_base64` as a Base64 PNG image. To display it on a page, add the `data:image/png;base64,` prefix before this value. `copy_paste` is the code to copy, and `expires_at` shows expiration in Unix UTC seconds. ## 201 and 202 responses for Pix If you receive `202`, the charge already has an ID but Pix is not yet available. Store that ID and look up the same charge in [Retrieve a charge](/en/api/charges/retrieve). Do not create another charge to track this issuance. The lookup returns the available data and current status; looking it up does not issue another code. If issuance remains pending or fails, contact support and provide the charge ID. A `201` response confirms charge creation. Check `payment_information.pix_status` and the payment data to see whether Pix is available. ## Pix at creation or in checkout A list such as `payment_method_types: [1]` configures the accepted methods but keeps issuance after checkout selection. To request Pix during creation itself, use `payment_method: 1`. ## Receive a boleto when creating a charge In `POST /v1/charges`, send `payment_method: 2`, without a custom list in `payment_method_types`. In `customer_id`, use the ID of a customer with a name, valid email, valid CPF/CNPJ and address. The postal code is in `zip_code` and the number in `street_number` in the customer record. You do not need to send another payer or address in the charge request. Email is required for issuance even with `send_email: false`; providing it in the record does not request a message. Raims can fill in missing street, neighborhood, city and state from the postal code when this data is available. Existing address values are kept. The number must be in the record; it and the address complement do not come from the postal code. The complement is optional. If the postal code does not supply all required data, complete the address in [Update an existing customer](/en/api/customers/update) before issuing the boleto. The address used for issuance does not change the customer record. This differs from completion when [creating a customer](/en/api/customers): there, providing a number or complement prevents postal code completion. During boleto issuance, they can be filled in while Raims completes the other missing fields. When the boleto is available, `payment_information.boleto` contains `line_digits`, `barcode` and `due_date`. Use the payment line and barcode in your system. The due date is in Unix UTC seconds and corresponds to the boleto date. Issuing this data does not confirm payment. In Sandbox, the boleto is simulated and must not be used for a real payment. A list such as `payment_method_types: [2]` configures boleto in checkout, with issuance after the payer's selection. To issue it during creation, use `payment_method: 2`. ## 201 and 202 responses for boleto `payment_information.boleto_status` shows `available` when data is available, `pending` when issuance has not yet been confirmed, `failed` when it could not be issued and `not_generated` when no issuance is available or requested. `boleto_error` gives the reason for a pending result or failure, when present. A `201` response confirms charge creation; check `boleto_status` to see whether the boleto was issued. For `202`, store the ID and track the same charge in [Retrieve a charge](/en/api/charges/retrieve). The lookup does not repeat or renew issuance. If it remains pending or fails, contact support with the charge ID without creating another charge to repeat issuance. If customer data prevents creation, correct the record indicated by the error before resending the request. Confirmed issuance also does not mean the customer paid; track the charge's status. Boleto payment progress appears in `payment_information.boleto_payment_status`: `awaiting_payment` for an issued boleto awaiting payment, `compensated` for a cleared payment awaiting settlement and `settled` for a settled payment. Without available progress data, the field returns `null`. Clearing does not yet mean available credit. To test these steps, see [Boleto clearing and settlement](/en/api/simulations/overview#compensação-e-liquidação-do-boleto). ## Reference in your system Send the order or charge identifier in your system as `external_reference`, for example `PEDIDO-123`. This field belongs to the charge and is separate from the external reference registered on the customer. The reference is optional. At creation, omitting the field, sending `null`, empty text or only spaces leaves the charge without a reference. The API removes leading and trailing spaces. The create, lookup and update responses include `external_reference`, with the registered value or `null`. You can change or remove the reference in [Update an existing charge](/en/api/charges/update). Omitting the field keeps the current value; sending `null`, empty text or only spaces removes the reference. This change does not change the Raims identifier or linked customer. In `GET /v1/charges`, the `external_reference` filter searches for the full current value of the charge's reference. The comparison is case-sensitive and accent-sensitive. Keep the same value along with other filters when navigating by cursor. A create or update may take a few seconds to appear in this search; avoid continuous requests at short intervals. The same reference can appear on more than one charge. Repeating this reference alone does not make the API reuse a charge. Also store the returned `id` to recognize each charge and check an inconclusive result before trying again. ## Additional integration data Use `metadata` to store small pieces of information that associate the charge with your system, such as a branch or sales channel. Customer and charge data are separate: the customer's map is not copied to a new charge. ```json { "metadata": { "filial": "SP-01", "canal": "site" } } ``` The map accepts up to 32 keys, with names made up of unaccented letters, numbers, periods, hyphens or underscores and text values. Names are case-sensitive. Limits also apply to the complete map after an update. Do not store passwords, tokens, personal documents or other sensitive data. If `metadata` is not provided at creation, the charge has an empty map. During updates, the keys you send are added or replaced; other keys are kept. Omitting `metadata` or sending `{}` keeps the data. Send `null` as a key's value to remove it, or `metadata: null` to clear the map. An empty string is a valid value and does not remove the key. Create, update and lookup responses return `metadata`, with `{}` when there are no values. This data does not change amount, due date or payment. It cannot be used as list filters and is not automatically included in webhook bodies. To search by your system's code, use `external_reference`. You can update only `metadata` after a charge is paid or refunded. If the same request also changes the title, description or external reference, it follows the rules for those fields. When the state prevents that edit, none of the request's fields are changed. ## Due date Provide the due date in `due_date`, in Unix UTC seconds. Choose a date and time at least five minutes after the request reaches the API. Account for transmission time when calculating that interval. The maximum is the corresponding day ten years from today, in São Paulo time. For Pix, the due date keeps the specified time. Boleto uses the São Paulo due date, including the same day. Charge and checkout expiration does not confirm cancellation of a boleto already issued. To stop receiving payments through that boleto, track confirmation of the charge revocation. ## Checkout link and email requests To receive `checkout_url` without sending an email, use `create_checkout: true` when creating the charge and keep `send_email: false`. A return URL is not required to receive the link. Use the returned address to send the payer to that charge's checkout. `success_redirect_url` and `cancel_redirect_url` configure the destinations for returning from checkout to the company's website. `success_redirect_url` is the destination after payment confirmation. `cancel_redirect_url` is the destination of the option to return to the website; this navigation does not revoke the charge. Send complete HTTPS URLs of up to 2048 characters each on a company domain. Do not use credentials in the URL, an IP address, localhost or a Raims domain. The fields are optional: you can omit them, send `null` or leave them empty. Fields containing only spaces also do not define a return URL. Providing at least one of these URLs generates the link. Look up the charge to confirm payment in your system even if the payer returned through the success URL. `create_checkout` and `send_email` are optional and use `false` when omitted. Without these options and without return URLs, the request creates the charge without generating a link or requesting an email; `checkout_url` returns `null`. Use `send_email: true` to request that the charge be emailed to the customer's registered email. You also receive the link in `checkout_url`. First check that the customer has a valid email. To obtain only the link, use `create_checkout: true` with `send_email: false`. This checkout belongs to a specific charge. To obtain or configure the link of a charge already created, use [Payment links](/en/api/payment-links/overview). While the company awaits completion of its registration review, sending is restricted to the account holder's email. An email that is missing, invalid or different from the holder's email under that condition prevents creation with an email request. Outside that pending-registration restriction, a missing or invalid email does not prevent creating the charge and link, but no email is sent. Direct boleto issuance requires a valid email even without requesting a message. A successful request does not confirm email delivery or payment of the charge. ## List charges [List charges](/en/api/charges/list), with `GET /v1/charges`, looks up records in the authenticated company and environment. Use filters for charge identifier, external reference, customer, email registered on the charge, status, registered payment method and creation, due date and payment intervals. Changing the customer's email does not change the email already registered on existing charges. Use `customer_id` with the ID received when creating or looking up the customer to list their charges. The link stays the same if the customer's name or email changes. You can combine this filter with others. A valid ID without accessible charges in the authenticated company and environment returns an empty list. Also keep `customer_id` when copying the cursor to the next page. Use `external_reference` to search for the charge reference's current value. The comparison is exact, case-sensitive and accent-sensitive: `PEDIDO-123` does not match `pedido-123` or a fragment such as `123`. You can combine this filter with others; keep the same value when navigating by cursor. A create or update may take a few seconds to appear in this search. Avoid continuous requests at short intervals to try to speed up the update. `status` and `payment_method` filters accept comma-separated codes. For status, use the codes from `0` to `13` described in the endpoint. The payment method filter codes are in [Payment methods](/en/meios-de-pagamento#códigos-na-api). The response contains `list` and `page`. Start without a cursor and process the received charges. While `page.has_next` is `true`, copy `page.next_after` to `after` in the next request, keeping the filters and sorting. Copy the entire cursor without interpreting or calculating its contents. A page accepts up to 100 charges and uses 10 when `page_size` is not provided. The [Listing and pagination](/en/api/listagem-e-paginacao) guide also explains how to go back with `before`. Send only one cursor per request. `created_gte` and `created_lte` filter the creation date in Unix UTC seconds, including the specified instants. By default, the newest records appear first. `sort_key` accepts `amount_cents` or `created_at`; `sort_order` accepts `asc` or `desc`, defaults to `desc`, and also lets you reverse the default sorting direction. If you provide a creation interval without choosing `sort_key`, the query sorts by `created_at`. Use `due_gte` and `due_lte` to look up charges by due date in Unix UTC seconds. The limits are inclusive: `due_gte` includes due dates from the specified instant onward, and `due_lte` includes due dates up to that instant. You can provide one limit or combine both; the end must be equal to or later than the start. To query a full day, convert the start and end of that day to UTC according to the time zone used in your system. The interval uses the charge's `due_date`, including for paid charges. Combine with `status` to select a specific condition, such as expired charges. The due-date filter can be used with other filters and does not change the chosen sorting. Keep all filters when using `after` or `before`; to query another period, start again without a cursor. Use `paid_gte` and `paid_lte` to find charges paid in a period. Values are Unix UTC seconds and include both limits. The filter uses the charge's original payment date, not creation, due date or funds availability date. Charges without a payment date are excluded from this filter. A later refund does not remove the charge from the period when it was paid; combine with `status` to restrict its current condition. Payment confirmation may take a few seconds to appear in the search. Keep the same filters when navigating by cursor and avoid continuous requests to try to speed up the update. `payment_method` shows the charge's current method; `payment_method_types` shows the configured custom list, or `null` for inheritance, without representing the options available at that moment. `checkout_payment_method` shows the method used to generate payment in checkout. If `payment_method` was `0`, generating Pix or boleto in checkout changes this value to `1` or `2`, respectively. Simply selecting the checkout option does not change the filter. See [Payment methods](/en/meios-de-pagamento#meio-cadastrado-e-escolha-do-checkout). `checkout_url` returns an existing link or `null`. Listing charges does not create a link or request an email. The returned status accounts for the charge's due date. The status filter may take a few seconds to reflect changes; avoid continuous requests at short intervals to try to speed up this update. ## Retrieve a charge [Retrieve a charge](/en/api/charges/retrieve), with `GET /v1/charges/{id}`, looks up the record, status and payment data in one request. Use the identifier received when creating or listing charges. The charge must belong to the authenticated company and environment. `payment_information.pix_status` and `payment_information.pix_error` show the Pix issuance result. For boleto, check `boleto_status` and `boleto_error` in the same object. If creation returned `202`, use the same ID in this lookup. The response may remain pending; repeated lookups do not restart issuance. Use `status` to track the charge's condition and `is_payable` to check whether it can accept payment. `payment_method` shows the charge's current method; `payment_method_types` shows the configured custom list or `null` for inheritance; `checkout_payment_method` shows the method used to generate payment, or `null` before generation. Selecting an option on screen does not confirm issuance or payment. When creating with `payment_method: 1`, check `payment_information.pix`; with `payment_method: 2`, check `payment_information.boleto` for the available data. The `payment_information` object brings together the QR Code, Pix copy-and-paste code and its expiration, or the data of a boleto already issued. Pix and boleto can be issued during creation with the respective `payment_method` or after checkout selection. Before issuance, a charge can accept payment without Pix or boleto data. When no issuance is available for the chosen method or the charge cannot accept payment, the data is null. The record and status remain available, including for paid, canceled or expired charges. The lookup returns the existing checkout link or `null`. It does not change the charge or generate or renew Pix, boleto or link. It also does not request an email. Repeated lookups do not speed up issuance or payment confirmation. The list shows a charge summary and status without Pix and boleto data. For counts, amounts and payment rate, see [Charge statistics](/en/api/balances/overview#estatísticas-de-cobranças) in Financial information. ## Boleto PDF Use [Download a boleto](/en/api/charges/boleto), with `GET /v1/charges/{id}/boleto`, to obtain the PDF of a boleto already issued. The identifier is the charge's ID. You can attach the file to your system or give it to the customer without opening checkout. The request requires authentication for the same company and environment. The download requires an issued boleto with the data needed to generate the file. You can obtain it while awaiting payment, during clearing and after settlement. A canceled or failed boleto or one without issuance data has no PDF available. Charge expiration alone does not confirm boleto cancellation. If you receive `BOLETO_DOCUMENT_NOT_AVAILABLE`, look up the charge to check boleto issuance and progress. Repeating the download does not issue or renew the boleto or change its due date. The endpoint returns JSON with `url` and `expires_at`. Make a GET request to the complete `url` to download the PDF from `files.raims.com` without sending `Authorization` or the API key in that download. `expires_at` shows expiration in Unix UTC seconds; after that, call the authenticated endpoint again. An invalid or expired link may receive HTTP `403` during download without the API's JSON error envelope. The URL can be reused until it expires and grants access to anyone who has it. Share it only with authorized people and do not record it in logs. The document contains boleto instructions and does not prove payment. In Sandbox, it is identified as a simulation and must not be used for payment. To document a confirmed payment, use the receipt described below. ## Payment data and receipt Use [Look up payment data](/en/api/charges/payment), with `GET /v1/charges/{id}/payment`, to obtain confirmed payment data and display it in your system. For the prepared document, use [Download a payment receipt](/en/api/charges/receipt), with `GET /v1/charges/{id}/receipt`. The identifier is the charge's ID, with the `ch_` prefix. The receipt is available for paid charges, partially refunded charges or charges with a dispute won by the company, as long as payment amount and date are recorded. If the document is unavailable, look up the charge to check its state before trying again. The data lookup shows amount, payment method, date and registered details of the payer and receiving company. The payer's name and tax ID are those registered on the charge; they do not prove ownership of the bank account that made the payment. Fields without available information may be `null`. For Production Pix payments, `end_to_end_id` shows the receipt's bank identifier when available. Use it to check the payment against the bank receipt or in your system's reconciliation. The field is `null` when there is no confirmed bank identification, for boleto payments and in Sandbox. A null value does not undo payment confirmation. This identifier differs from the charge's `ch_` ID and the data used to initiate Pix. The endpoint response is JSON with `url` and `expires_at`. Make the request from your integration's server with an API key or OAuth session. Download the PDF from the complete `url` at `files.raims.com` without sending the key in that download. `expires_at` shows expiration in Unix UTC seconds. If the link expires, call the authenticated endpoint again for another link. An invalid or expired link may receive HTTP `403` during download without the API's JSON error envelope. The URL can be reused until it expires and grants access to anyone who has it; share it only with authorized people and do not record it in logs. The document is issued by Raims and does not replace a tax invoice or bank payment receipt. In Sandbox, the data and receipt identify the payment as simulated. A partial refund does not change the payment receipt's original amount. To document each completed refund, use the [refund receipt](/en/api/refunds/receipt), with the `rf_` identifier of the corresponding request. ## Update a charge [Update an existing charge](/en/api/charges/update), with `PATCH /v1/charges/{id}`, changes the title, description, external reference and `metadata` by public identifier. Send the fields you want to change. Omitted fields keep their current value; for text fields, `null` or empty text clears the field you send. An empty body (`{}`) keeps the data. The `metadata` map follows the [update by key](#dados-adicionais-da-integração) rules. See how to use `external_reference` in [Reference in your system](/en/api/charges/overview#referência-no-seu-sistema). Amount, due date and linked customer are defined at creation and cannot be changed by this request. To charge another amount or use another due date, revoke the eligible charge. Wait for revocation confirmation before creating the replacement charge. The due date alone does not prevent editing a charge that remains open. Paid, canceled, refunded charges or charges in other final states do not allow these fields to be edited. A request that changes only `metadata` remains allowed for an existing charge; see [Additional integration data](#dados-adicionais-da-integração). If the state prevents editing, `CHARGE_NOT_UPDATABLE` shows the current state and accepted states. Look up the charge before deciding how to continue; editing does not change its financial state. Editing keeps the identifier, status and payment data. It does not generate or renew Pix, boleto or checkout link or request an email. ## Revoke a charge [Revoke a charge](/en/api/charges/revoke), with `DELETE /v1/charges/{id}`, cancels a charge that should no longer accept payment. Use the ID from creation or lookup, in the same authenticated company and environment. In Sandbox, you can test revocation without moving real funds. To check tracking of a pending or failed cancellation, prepare the result in [Simulation](/en/api/simulations/overview#emissão-e-cancelamento-com-pendência-ou-falha) before sending the revocation request. In Production, revocation depends on the charge's status and payment data already issued. For issued Pix, cancellation must be confirmed. For boleto, the request may remain pending until confirmation. Track the same charge through the [individual lookup](/en/api/charges/retrieve); an accepted request does not mean cancellation is complete. If you do not receive cancellation confirmation, look up the same charge before trying again. A rejection with `CHARGE_NOT_REVOCABLE` shows the state or payment condition that prevented the action. A boleto still being issued, a payment already identified and a rejected cancellation require different follow-up actions. Check the message and charge; revocation is not a way to request a refund. The record and history remain available for lookup after revocation. Repeating the request for a charge already canceled in the same company and environment returns the same confirmation. To charge again, create another charge. A paid Pix charge can follow the [refund](/en/api/refunds/overview) flow. Revocation does not refund, reimburse or return funds and does not request an email. See the fields and responses in [Create a new charge](/en/api/charges), [List charges](/en/api/charges/list), [Retrieve a charge](/en/api/charges/retrieve), [Update an existing charge](/en/api/charges/update) and [Revoke a charge](/en/api/charges/revoke). To prepare your integration credential, see [Authentication](/en/integracoes/autenticacao). # Look up payment data (/en/api/charges/payment) Get the amount, date and registered details associated with a charge's payment. For incoming Pix payments, the response includes the bank identifier when available. Use this lookup to display the receipt in your system or check the payment against the customer's order. The data becomes available after payment confirmation. To download the prepared document, use [Download a payment receipt](/en/api/charges/receipt). See the conditions and meaning of the data in [Payment data and receipt](/en/api/charges/overview#dados-do-pagamento-e-recibo). GET /v1/charges/{id}/payment # Download a payment receipt (/en/api/charges/receipt) Get a temporary URL to download the charge's payment receipt. Call this endpoint with your API key or OAuth session and use the returned `url` to download the PDF from `files.raims.com` without sending the key in that download. The receipt is issued by Raims and does not replace a tax invoice or bank payment receipt. See the conditions in [Payment data and receipt](/en/api/charges/overview#dados-do-pagamento-e-recibo). GET /v1/charges/{id}/receipt # Retrieve a charge (/en/api/charges/retrieve) Looks up a charge by the identifier received when creating or listing charges. Use this request to track the charge's status or obtain the QR Code, Pix copy-and-paste code and data from a boleto already issued. The charge must belong to the authenticated company and environment. The lookup reads existing data and does not issue or renew Pix, boleto or a checkout link. See when payment data becomes available in [Retrieve a charge](/en/api/charges/overview#recuperar-uma-cobrança). GET /v1/charges/{id} # Revoke a charge (/en/api/charges/revoke) Revokes a charge by public identifier. Use this request when the charge should no longer accept payment. It must belong to the company and authenticated environment. The record and history remain available for lookup; revocation does not refund or return paid amounts. Cancellation may depend on bank confirmation. If the request remains pending or ends without a conclusive result, track the same charge through the [individual lookup](/en/api/charges/retrieve) before trying again. Consider the charge canceled only after confirmation. See the differences between Sandbox and Production and how to track confirmation in [Revoke a charge](/en/api/charges/overview#revogar-uma-cobrança). DELETE /v1/charges/{id} # Look up charge statistics (/en/api/charges/statistics) Check your company's charge and payment totals to track performance in an ERP, report or your own dashboard. Choose the period you need; the response includes counts, amounts and payment rate. Amounts are gross and changes may take a few seconds to appear. See how to interpret each total in [Charge statistics](/en/api/balances/overview#estatísticas-de-cobranças). GET /v1/charges/statistics # Update an existing charge (/en/api/charges/update) Updates the title, description, external reference and `metadata` of an existing charge. Use the identifier received when creating or looking up the charge, in the authenticated company and environment. Send only the fields you want to change. Omitted fields keep their current value; for text fields, `null` or empty text clears the field you send. An empty body (`{}`) keeps the data. Amount, due date and linked customer remain as defined at creation. The `metadata` map is updated by key. See how to add or remove values in [Additional integration data](/en/api/charges/overview#dados-adicionais-da-integração). Editing is allowed for charges that remain open, including after their due date. Paid, canceled, refunded charges or charges in other final states only allow changes to `metadata`. If you mix this data with other fields in a request rejected because of the state, nothing is changed. See the editing and replacement rules in [Update a charge](/en/api/charges/overview#atualizar-uma-cobrança). To associate the charge with your system, see [Reference in your system](/en/api/charges/overview#referência-no-seu-sistema). PATCH /v1/charges/{id} # HTTP response codes (/en/api/codigos-http-das-respostas) Use the HTTP code together with the response body to identify a request's result. The same HTTP code can represent different errors; also check `error.code`, `error.message` and `error.details`, when present. * `2xx` responses indicate success; * `4xx` responses indicate problems with the request, authentication, authorization, resource or limits; * `5xx` responses indicate a processing failure on the Raims side. ## Response codes | HTTP code | What it indicates | How to handle it | | ---------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200 OK` | The request was processed successfully. | Interpret the body according to the endpoint used. | | `201 Created` | A resource was created. | Store the returned identifier to recognize the resource in future requests. | | `202 Accepted` | The request was accepted, but its result has not been confirmed yet. | Keep the identifier and follow the resource indicated by the endpoint before repeating the request. | | `400 Bad Request` | The request data is invalid or incomplete. | Check the message and fields indicated in the response to correct the request. | | `401 Unauthorized` | The credential is missing, invalid or cannot be used. | Check the `Authorization: Bearer` header, the credential and, for an OAuth session, whether access needs to be refreshed or authorized again. | | `403 Forbidden` | Access was denied because of a company condition, an IP restriction or an authorization rule. | Check `error.code`, the account status, and the key's permissions and allowed IPs. The documentation console accepts only Sandbox keys. | | `404 Not Found` | The requested URL or resource was not found. | Check the method, path and identifier used. | | `405 Method Not Allowed` | The HTTP method is not accepted on this route. | Use the method specified for the request. The `Allow` header, when present, lists the accepted methods. | | `409 Conflict` | The current resource condition or another request in progress prevents processing. | Check `error.code` and `error.message`. Correct the indicated condition; for a request in progress, wait for `Retry-After`, when present, before retrying. | | `413 Payload Too Large` | The body exceeds the request's allowed size. | Reduce the body sent and respect the endpoint's documented limit. | | `415 Unsupported Media Type` | The body format is not accepted. | For requests with a JSON body, send `Content-Type: application/json`. | | `422 Unprocessable Entity` | The request could not be processed under the supplied conditions. | Check `error.code` and `error.message` before submitting it again. | | `429 Too Many Requests` | The request limit or waiting interval was reached. | Wait the number of seconds in `Retry-After`, when present, before trying again. | | `500 Internal Server Error` | An internal failure prevented normal completion of the response. | Check the result before repeating a request that creates or changes data. | | `502 Bad Gateway` | A payment service rejected the request. | Check the result and error code before deciding whether to submit another request. | | `503 Service Unavailable` | A required service is temporarily unavailable. | Wait before trying again and check the result of requests that may have been processed. | Endpoint pages show successes, validation errors and request-specific errors, including those using an HTTP code described here. See the endpoint's Responses section for its conditions and examples. The general errors on this page can also occur on these endpoints, even when they are not repeated in Responses. `409 REQUEST_IN_PROGRESS` indicates that another request is still being processed. Wait for `Retry-After`, when present, before retrying. ## API key permissions `403 API_KEY_PERMISSION_DENIED` means the key cannot access the requested resource or operation. Ask someone authorized to edit keys to review the selection in **Integration / API keys / Edit permissions**. Select the action that matches the request; creating, viewing, updating, and deleting are independent permissions. Repeating the request without changing access does not resolve the denial. See [Key permissions](/en/integracoes/autenticacao#permissões-da-chave). ## Environment in OAuth requests `400 OAUTH_ENVIRONMENT_REQUIRED` requires `X-Raims-Environment` on an OAuth request. `400 OAUTH_ENVIRONMENT_INVALID` indicates an invalid or repeated value. Supply exactly one environment accepted by the endpoint and authorized for the OAuth connection. Check the resource reference for supported environments. `403 OAUTH_ENVIRONMENT_FORBIDDEN` means the connection cannot access the selected environment. `403 OAUTH_SCOPE_FORBIDDEN` means the request is outside the granted permissions. Check the authorization before trying again. With an API key, the key itself determines the environment. See [Authentication](/en/integracoes/autenticacao). ## Access blocked by company status `403 COMPANY_STATUS_RESTRICTED` indicates that the company's status prevents API access. The message identifies the condition and gives the next step: | Status | API access | What to do | | -------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | Suspended company | Blocked in Production and Sandbox. | Contact customer support at [sac@raims.com](mailto:sac@raims.com). | | Closed account | Blocked in Production and Sandbox. | Contact customer support at [sac@raims.com](mailto:sac@raims.com) if you need help. | | Pending registration | Blocked in Production. Sandbox remains allowed, subject to the other rules. | Check the registration status in the Dashboard. | For example, a suspended company receives: ```json { "error": { "code": "COMPANY_STATUS_RESTRICTED", "message": "Your company is suspended and cannot access the API. Contact our support team at sac@raims.com for assistance." } } ``` Contact customer support for these account requests, as listed in the [Raims support channels](https://raims.com/en/help). The error keeps the same code for the statuses above; use the message for human diagnosis, without comparing its text in integration logic. ## Error format API errors are returned as JSON in the `error` object, with `code` and `message`. `details` is optional: it appears when the response needs to identify an invalid field or a reference sent in the body that was not found. Each detail shows where to correct the request and explains why. General authentication, authorization, conflict, limit, route, malformed JSON, size and media errors use only a code and message. It is normal for `details` to be absent. For example, a missing or invalid key receives: ```json { "error": { "code": "UNAUTHORIZED", "message": "Provide a valid API key or OAuth access token in the Authorization: Bearer header." } } ``` Messages in `error.message` and `error.details[].message` are written in English. The documentation explains the conditions and how to handle them. Identify the error by its HTTP status and `error.code`. To correct fields, also use `error.details[].field` and `error.details[].code`. Never compare message text in integration logic: it may change without changing the meaning of the codes. Your system can use these codes to display a message in the customer's language. For field validation, `error.message` summarizes the error category. `error.details` keeps each field or list item with its code and explanation, without repeating that content in the summary. Check every detail before submitting again. ### Locating the problem Each item in `error.details` contains: | Field | How to use it | | --------- | --------------------------------------------------------------------------------------------- | | `field` | Identifies the submitted field, including its path when it belongs to an object or list item. | | `code` | Identifies the condition so your system can handle the error. | | `message` | Explains the problem with that field in English. | For example, `customer_id` identifies the charge's customer; `id` identifies the resource in the URL path. The `$` field represents the entire JSON body when validation requires a different type, such as an object instead of an array. Query and path parameters use their public names. Check every detail received before submitting the request again. ### Example HTTP 400 response ```json { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "tax_id", "code": "REQUIRED", "message": "tax_id is required." } ] } } ``` `REQUIRED` indicates a missing required field; `MIN_LENGTH` indicates a value below the minimum length; `MAX_LENGTH` indicates that the allowed length was exceeded. `INVALID_TAXID` indicates an invalid CPF or CNPJ; `INVALID_EMAIL` indicates an invalid email address. `MAX_ITEMS` indicates that a collection has more items than the request allows. `MUTUALLY_EXCLUSIVE` indicates fields that cannot both have values, such as `after` and `before` in pagination. Send only one of them. Also check the request's rules. ## Resource not found A `404 NOT_FOUND` can indicate that the queried resource is not available to the key's company and environment. When querying a customer by `id`, the message identifies the resource without additional details: ```json { "error": { "code": "NOT_FOUND", "message": "The customer specified by id was not found." } } ``` When the reference was sent in the body, such as `customer_id` when creating a charge, the response uses `details` to identify the field to check: ```json { "error": { "code": "NOT_FOUND", "message": "A referenced resource was not found.", "details": [ { "field": "customer_id", "code": "NOT_FOUND", "message": "The customer specified by customer_id was not found." } ] } } ``` Check the identifier and use the key for the company and environment where the resource was registered. This response does not confirm that the resource exists in another account or environment. A listing with no results still returns an empty list, according to the endpoint's rules. An unknown URL also returns `404`, but its message identifies the method and path that were not recognized. In that case, check the endpoint's address in the reference. ## Malformed JSON and invalid fields `INVALID_JSON` indicates that the body could not be parsed as JSON, for example because of a misplaced comma or quotation mark. Correct the body structure before submitting the request again. When the JSON is well formed but contains unknown or repeated fields, or fields with an incompatible type, the response uses `INVALID_FIELDS` and identifies the problem in `error.details`: | Code in `details` | What to correct | | ----------------- | ------------------------------------------------------------------------- | | `UNKNOWN_FIELD` | Remove the indicated field or correct its name according to the endpoint. | | `DUPLICATE_FIELD` | Send the field only once in the same object. | | `INVALID_TYPE` | Use the type specified by the endpoint, such as a string for `tax_id`. | For example, sending `tax_id` as a number instead of a string returns: ```json { "error": { "code": "INVALID_FIELDS", "message": "One or more request fields are invalid.", "details": [ { "field": "tax_id", "code": "INVALID_TYPE", "message": "tax_id must be a JSON string." } ] } } ``` When an endpoint requires an object and receives another JSON type, such as an array, `field` uses `$` to indicate the entire body, with code `INVALID_TYPE`. Missing required fields and values that do not meet the endpoint's rules still use `INVALID_FIELDS`, with the corresponding validation codes. When `error.details` indicates `field: tax_id` and `code: INVALID_TAXID`, see [CPF and CNPJ validation](/en/integracoes/validacao-cpf-cnpj#como-tratar-invalid_taxid). The guide explains how to check the tax ID before the request and guide its correction in the integration's system. ## State conflicts and usage conditions A state error reports the resource's current condition and the accepted states for the action. The same code can have different explanations depending on the condition that prevented the request. Use `error.code` to handle the cause, and read `error.message` to understand the observed condition. Check the specific examples in Responses and query the resource before trying again. Being in an accepted state does not guarantee that the request's other conditions are met. Some endpoints offer queries to check a resource's eligibility or availability. See the endpoint's reference to identify the query and applicable conditions. ## Request limits `429 RATE_LIMITED` indicates a refusal due to excess requests. Wait for `Retry-After` and adjust the rate or concurrency according to `Raims-Rate-Limited-Reason`. Some endpoints have their own rules and waiting intervals, described in their reference. The [rate limiting guide](/en/integracoes/rate-limiting) explains the limits per company and environment, reasons, retries and a queued query example. ## Temporary failures and uncertain results A `503` response can indicate temporary unavailability while authenticating, querying data or using a payment service. Check `error.code` and `error.message` to identify the reported cause. `503 OAUTH_AUTHORIZATION_UNAVAILABLE` means current access could not be confirmed. `503 OAUTH_AUTHORIZATION_CHANGED` means authorization changed during the request and the result may already have been applied. After restoring access, query the resource before repeating a write. When resuming through the same connection, keep the original `Idempotency-Key`. If you need to authorize a new connection, check the previous attempt's result before sending another request. `503 RATE_LIMIT_STORE_UNAVAILABLE` indicates that the API could not accept the request and did not execute it. Wait for `Retry-After` before trying again. Even with a `500`, `502` or `503` response, or connection loss, the request may have been processed. Before repeating a call that creates or changes data, check the result and follow the endpoint's guidance. Avoid repeating requests continuously during a failure. When the response includes `Retry-After`, wait the indicated number of seconds. This header does not appear in every failure. `Transient-Error: true`, when present, indicates a temporary failure. You still need to check the result before repeating a request that creates or changes data. When asking support for help, provide the method, path, time, HTTP status and error code. Remove API keys and personal data from shared examples. # Create a customer (/en/api/customers) Creates or updates a customer by CPF or CNPJ in the company and environment of your API key. An existing tax ID updates the customer and keeps the same identifier. When only `zip_code` is provided for the address, Raims can fill in `street`, `neigh`, `city` and `uf` using the postal code data. To use this feature, leave `street`, `neigh`, `city`, `uf`, `street_number` and `complement` empty. Any value in these fields prevents automatic completion; empty fields or fields containing only spaces do not. If the postal code is not found, the customer can still be registered. See [Create a customer](/en/api/customers/overview#criar-um-cliente) for the registration rules. Use the [reference in your system](/en/api/customers/overview#referência-no-seu-sistema) to associate this customer with the identifier used in your integration. POST /v1/customers # Delete a customer (/en/api/customers/delete) Deletes a customer by public identifier when you no longer need the record. The customer must belong to the authenticated company and environment. Deletion is allowed only when the customer has no linked charges that have not been deleted, including paid charges. If any such charge exists, the customer is kept. This request does not delete charges or refund payments. Repeating the request for a customer already deleted from the same company and environment returns the same confirmation. See how deletion affects lookups in [Delete a customer](/en/api/customers/overview#remover-cliente). DELETE /v1/customers/{id} # Delete customers in bulk (/en/api/customers/delete-batch) Deletes multiple customers from the authenticated company and environment in one request, using the public identifiers returned by the API. Each customer follows the same deletion conditions as [Delete a customer](/en/api/customers/delete): linked charges that have not been deleted, including paid charges, prevent deletion. The request does not delete charges or refund payments. Some customers in the batch may be deleted while others are kept. Check the `removed`, `blocked` and `invalid` groups for each customer's result. The `errors` array explains each issue and identifies its position in the request, such as `identifiers[2]` for the third item. Correct only the indicated items. Resending the ID of an already deleted customer returns the same confirmation. See how to check the result in [Delete customers in bulk](/en/api/customers/overview#remover-clientes-em-lote). DELETE /v1/customers # List customers (/en/api/customers/list) Looks up customers registered in the authenticated company and environment. Use the filters to find a customer by identifier, name, email, CPF/CNPJ or the external reference from your system. Start without a cursor, process `list` and, while `page.has_next` is `true`, copy `page.next_after` to `after`, keeping the filters. Copy the entire cursor without interpreting or calculating its contents. See [Listing and pagination](/en/api/listagem-e-paginacao) to go back with `before`. See how filters and sorting work in [List customers](/en/api/customers/overview#listar-clientes). GET /v1/customers # Customers (/en/api/customers/overview) Register the person or business that will pay your Raims account as a customer. Their CPF or CNPJ identifies them; you can also provide a name, contact details and address. Customers belong to the authenticated company and environment used in the request. Sandbox and Production records are kept separate. The base URL for requests is `https://api.raims.com`. Phone number and dialing code are optional. You can provide either one without the other. The API does not check whether the number follows the country's telephone numbering rules. Registering a phone number does not confirm that it is active or belongs to the customer. ## Create a customer [Create a customer](/en/api/customers), with `POST /v1/customers`, accepts the customer data and returns an identifier with the `cus_` prefix. Store this identifier in your system to recognize the registered customer. CPF or CNPJ is required. Name, contact details and address are optional. A tax ID already registered in the same company and environment updates the existing customer and keeps their identifier. If the request ends without a conclusive response, check the customer before repeating the request. Validate the CPF or CNPJ in your integration's form and server before sending the customer data. The [CPF and CNPJ validation](/en/integracoes/validacao-cpf-cnpj) guide explains check digits, alphanumeric CNPJ and how to handle `INVALID_TAXID` so the user can correct the field. When you provide only `zip_code` for the address, Raims can fill in the street, neighborhood, city and state using the available postal code data. Any value in the street, neighborhood, city, state, number or address complement prevents automatic completion. In that case, send the address data you want to register. Empty fields or fields containing only spaces do not prevent postal code completion. If the postal code is not found, the customer can still be registered. ## Reference in your system Send the customer's identifier in your system as `external_reference`. The reference appears in lookups and can be changed or removed without changing the Raims ID. Omitting this field keeps the current reference, both when registering the same CPF/CNPJ again and when updating by ID. To find the customer by your system's code, provide `external_reference` in the [customer list](/en/api/customers/list). The search compares the full value and is case-sensitive and accent-sensitive. For example, `ERP-123` does not match `erp-123` or values that only contain `123`. Different customers can share the same reference; also use the returned `id` to identify each record. ## Additional integration data Use `metadata` to associate small pieces of information from your system with the customer, such as a branch code or registration channel. Send an object with text key names and values: ```json { "metadata": { "filial": "SP-01", "canal": "loja" } } ``` The map accepts up to 32 keys. Names use unaccented letters, numbers, periods, hyphens or underscores and are case-sensitive. Size limits also apply to the resulting map after an update, including existing keys. Do not use this field for passwords, tokens, personal documents or other sensitive data. If `metadata` is not provided when creating a customer, the map is empty. When registering an existing CPF/CNPJ again or updating by ID, the keys you send are added or replaced; other keys are kept. Omitting `metadata` or sending `{}` keeps the map. Send `null` as a key's value to remove it, or `metadata: null` to remove all keys. An empty string is a valid value and does not remove the key. Create, update and lookup responses return `metadata`, with `{}` when there are no values. This data cannot be used as search filters and is not automatically included in webhook bodies. ## List customers [List customers](/en/api/customers/list), with `GET /v1/customers`, looks up customers in the authenticated company and environment. You can filter by identifier, name, email, CPF/CNPJ or external reference and receive up to 100 customers per page. Without `page_size`, the page contains up to 10 customers. Send filters in the URL, without a JSON body. Leave filters you do not want to use empty. The response contains `list` and `page`. Start without a cursor and process the customers in `list`. While `page.has_next` is `true`, copy `page.next_after` to `after` in the next request, keeping the filters. Copy the full value without interpreting or calculating its contents. The [Listing and pagination](/en/api/listagem-e-paginacao) guide also explains how to go back with `before`. Send only one cursor per request; do not fill in both `after` and `before`. A cursor that is empty or contains only spaces is not used in the query. In the customer listing, removing the record that marked the position of a valid cursor does not cause an error. The search continues with the same filters and in the requested direction, without using that previous position. The page may repeat customers already received; use the new cursors returned to continue. Modified cursors or cursors belonging to a different company, environment or query are still rejected with `400 INVALID_FIELDS` and `INVALID_CURSOR`. The newest customers appear first, including in name searches. To search by name, provide at least two characters, excluding leading and trailing spaces. A filter that is empty or contains only spaces does not restrict the search. The external reference search can be combined with other filters. New records or changes may take a few seconds to appear in this search. Avoid continuous requests at short intervals. Keep the reference and other filters when continuing pagination. ## Retrieve a customer If you already have the identifier with the `cus_` prefix, use [Retrieve a customer](/en/api/customers/retrieve), with `GET /v1/customers/{id}`, to look up their data. Use the `id` returned by the API without changes in the URL path. The request does not accept a JSON body. This lookup lets you check the customer without going through the list. The customer must belong to the authenticated company and environment. If they are not available to that key, check the identifier and credential used. ## Update an existing customer Use [Update an existing customer](/en/api/customers/update) when you already have the `id` and need to change the name, contact details, address or additional integration data, with `PATCH /v1/customers/{id}`. Provide the identifier in the path and send only the fields you want to change. Omitted fields keep their current value. For optional text fields, sending `null` or an empty value clears the field. The `metadata` map follows the [update by key](#dados-adicionais-da-integração) rules. The identifier and CPF or CNPJ stay the same. This request does not create customers and requires a record from the same authenticated company and environment. You can change the phone fields separately. Changing `zip_code` does not automatically fill in the other address fields. ## Delete a customer Use [Delete a customer](/en/api/customers/delete) when you no longer need the record, with `DELETE /v1/customers/{id}`. Provide the `id` returned by the API in the path. The request has no body; the customer must belong to the authenticated company and environment. A customer can only be deleted when they have no linked charges that have not been deleted, including paid charges. Otherwise, the customer is kept. Deleting a customer does not delete charges or refund payments. If you receive `CUSTOMER_HAS_CHARGES`, use `GET /v1/charges` with the `customer_id` filter to identify the linked charges. The endpoint reference is in [List charges](https://docs.raims.com/en/api/charges/list). Paid or canceled charges also prevent deletion while they remain in the records. Revoking a charge does not remove that link. The customer no longer appears in the list or in lookups by ID. Repeating the request for a customer already deleted from the same company and environment returns the same confirmation. ## Delete customers in bulk [Delete customers in bulk](/en/api/customers/delete-batch) uses `DELETE /v1/customers` and accepts 1 to 100 IDs in the `identifiers` array of the JSON body. Results are separated into `removed`, `blocked` and `invalid`. Customers with charges that have not been deleted, including paid charges, are kept. Check each group to see which customers were deleted. The `errors` array identifies the position of each item with an issue and explains the reason. For example, `identifiers[2]` corresponds to the third item in the request. Use this information to correct the items that were not deleted. See each endpoint page for fields, code examples and API responses. To prepare your integration credential, see [API keys](/en/integracoes/chaves-api). # Retrieve a customer (/en/api/customers/retrieve) Looks up a customer by the public identifier received when creating or listing customers. Use the `id` returned by the API without changes. The customer must belong to the authenticated company and environment. See how to use the identifier in your integration in [Retrieve a customer](/en/api/customers/overview#recuperar-um-único-cliente). GET /v1/customers/{id} # Update an existing customer (/en/api/customers/update) Updates an existing customer and their integration data by public identifier. The customer must belong to the authenticated company and environment. Send only the fields you want to change. Omitted fields keep their current value. For optional text fields, sending `null` or an empty value clears the field. The identifier and CPF or CNPJ stay the same; this request does not create a customer. The `metadata` map is updated by key. See how to add or remove values in [Additional integration data](/en/api/customers/overview#dados-adicionais-da-integração). The address is also updated by field. Changing `zip_code` does not automatically fill in or replace the street, neighborhood, city or state; send the address fields you want to change. See the update rules in [Update an existing customer](/en/api/customers/overview#atualizar-cliente-existente). PATCH /v1/customers/{id} # List disputes (/en/api/disputes) View cases for the authenticated company and environment, with filters and sorting. Use the identifier from a result to retrieve its details. See [List disputes and navigate pages](/en/api/disputes/overview#listar-contestações-e-avançar-pelas-páginas) for pagination and [Tracking stages](/en/api/disputes/overview#etapas-de-acompanhamento) to interpret the progress of each case. GET /v1/disputes # Disputes (/en/api/disputes/overview) Track disputes for payments received by your company, including cases under the Pix Special Refund Mechanism (Mecanismo Especial de Devolução, MED). The API lets you view records and their available results. | Purpose | Method and path | | -------------------------------- | ----------------------- | | List disputes and navigate pages | `GET /v1/disputes` | | View dispute details | `GET /v1/disputes/{id}` | ## When to look up a dispute Use the list to identify cases and track their stages. View the details when you need the reason, report, company response or available dates. The data reflects the tracking shown by Raims; querying the API does not open a dispute, submit a defense, accept a refund or move money. The `kind` field distinguishes `med`, for the Pix MED procedure, from `chargeback`, for the other dispute records shown by Raims. This field identifies the case type and must be considered when interpreting its reasons and results. ## List disputes and navigate pages Use [List disputes](/en/api/disputes). You can filter by charge, stage, disputed amount or creation date range and choose sorting by creation date or amount. The amount filter uses exact equality in Brazilian real cents. Dates use Unix seconds in UTC, and range boundaries are inclusive. Start without a cursor, process `list` and copy `page.next_after` to `after` while `page.has_next` is true. Keep the filters and sorting throughout navigation. To change the query, start again without a cursor. To go back, use `page.previous_before` in `before`. Do not send populated `after` and `before` together. Copy the entire cursor without interpreting or changing its contents. See [Listing and pagination](/en/api/listagem-e-paginacao). An empty list means the page has no cases matching the query. Filtering by charge does not grant access to another company or environment. ## View a dispute Use [Retrieve a dispute](/en/api/disputes/retrieve) with the `id` returned in the list. Keep the complete identifier: the API returns IDs with the `dp_` or `med_` prefix depending on the record type. `charge_id` identifies the linked charge, or is `null` when no link is available. The details include the report, company response, reason and dates when available. `due_at` is the recorded response deadline, or `null` when no deadline is provided. The presence of this field does not mean that the API accepts a response submission. ## Tracking stages Use `stage` to track the case: | `stage` | Meaning | | -------------------- | ------------------------------------------------------------- | | `open` | Case recorded, with no confirmed analysis. | | `in_analysis` | Dispute under review. | | `refund_in_analysis` | Refund under review, without confirming a financial movement. | | `closed` | Review closed. Check the available results. | | `cancelled` | Dispute canceled. | | `rejected` | Request to open a dispute rejected. | | `failed` | Processing did not complete because of a failure. | `closed` alone does not mean a decision in favor of the company or money refunded. The stage shows progress; the result fields describe what has been confirmed for that case. Repeated queries do not start or speed up its review. ## Reasons and results Interpret `reason_code` together with `kind`. The same number can represent different reasons: | Code | `kind: med` | `kind: chargeback` | | ---- | ------------------- | ------------------------------------ | | `1` | Reported scam. | Alleged fraud. | | `2` | Account taken over. | Unrecognized purchase. | | `3` | Coercion. | Unrecognized service. | | `4` | Fraudulent access. | Product or service not as described. | | `5` | Other reason. | Improper charge. | | `6` | Unknown category. | Other reason. | `reason_code: null` means the reason is unavailable. For MED cases, `infraction_result` can be `agreed` when the infraction is recognized or `disagreed` when it is not. `refund_result` can be `partially_accepted`, `totally_accepted` or `rejected`, according to the refund review. These results alone do not confirm that money was refunded. `refunded_amount_cents` shows the total confirmed refunds for the MED case. For `chargeback` records, `won_amount_cents` and `lost_amount_cents` show amounts decided in favor of or against the company, when available. Each field is `null` when it does not apply to the case type or no result is available; preserve the difference between `null` and a confirmed zero. `loss_reason_code`, when provided, identifies an expired response deadline (`1`), insufficient evidence (`2`), invalid documentation (`3`), a final decision (`4`) or another reason (`5`). `loss_reason_note` adds context when a note is available. ## Company and environment Queries use [API-key or OAuth authentication](/en/integracoes/autenticacao) for the authorized company and environment. A Sandbox key queries only that environment; it does not access Production disputes. This documentation console accepts only Sandbox keys. Use the identifier returned by Raims and handle errors by HTTP status and `error.code`. For validation failures, also check the fields indicated in `error.details`. The individual query returns the same error when the case does not exist or is unavailable to the credentials used. # Retrieve a dispute (/en/api/disputes/retrieve) Retrieve a dispute using the identifier returned in the list. A closed stage alone does not confirm a favorable decision or a refund. See [Reasons and results](/en/api/disputes/overview#motivos-e-resultados) to interpret the fields for each type of case. GET /v1/disputes/{id} # Idempotency (/en/api/idempotencia) Use idempotency when an interruption, timeout or lost response leaves doubt about whether a request was processed. The key identifies the same intent across attempts and prevents an accepted retry from repeating its effect. The header is optional. Each endpoint page indicates whether it accepts `Idempotency-Key`. ## When to use it Send a key on creation requests and changes where repeating the effect would cause a duplicate or another unwanted update. The key does not replace the resource identifier, your system's reference or a result query. The CLI and this documentation console do not retry writes automatically. Your system decides when to retry and must keep the same key while handling the same intent. ## Send the key Generate a unique key in your system and send it in the header: ```http Idempotency-Key: de305d54-75b4-431b-adb2-eb6b9e546014 ``` UUID is accepted. The value must contain 1 to 255 visible ASCII characters, without spaces or control characters. Do not include credentials, tax IDs or other personal data in the key. Store the key with its corresponding request or action. The console shows the field under **Headers** when the endpoint accepts idempotency. The value remains only in the tab's memory, associated with the operation and account. The console does not create or replace the key between attempts. ## Retry the request If the response is lost, retry the same method, path, body and `Idempotency-Key`. A compatible retry returns the preserved result instead of executing the request again. Validation failures returned before execution are not stored. `4xx` responses are not preserved either. Correct the request before trying again and keep the same key only when the intent remains the same. If the idempotency store is unavailable, a request with the header receives a `503` before the action runs. This response is not preserved and can be retried with the same key. Without the header, the request follows the endpoint's normal flow. Reusing the key with a different method, path or content returns `422`. Use the key only with the request that represents the original intent. ## Interpret the result When a response comes from a preserved retry, the API sends: ```http Idempotency-Replayed: true ``` The status and body remain identical to the stored result. A `202` response still means processing is pending. Store the returned identifier and track the same resource; replay does not turn a pending result into completion. Successful responses and `5xx` failures that occur after admission are preserved. Retrying a key that received `500` may therefore return the same error. Query the resource and reconcile the effect before creating another key. A `409 IDEMPOTENCY_RESULT_UNKNOWN` response means the endpoint may have completed, but its response could not be preserved. Query the resource before retrying. If the response contains `Location`, start with that address. After reconciliation, a retry of the same intent keeps the same key; never replace the key to bypass this state. ## Retention and reconciliation The result remains available for 24 hours. After that period, the same key may start another processing attempt. Do not use expiration to resolve an uncertain financial operation. Before changing the key, query the resource by its identifier, use your system's reference when a filter is available and process received webhooks. Send a new intent only after confirming the current state. # Listing and pagination (/en/api/listagem-e-paginacao) Paginated Raims API lists divide results across requests. Items are returned in `list`, and the information for navigating between pages is in `page`. ## Browsing results **First request** Make the first request without `after` or `before`. **Process results** Process the items received in `list`, including on the last page. **Continue or finish** If `page.has_next` is `true`, copy `page.next_after` to `after` and repeat the request. When it is `false`, finish the listing. Copy the entire cursor without interpreting its contents, changing its value or calculating the next cursor. Keep the same filters and sorting, when the endpoint allows you to choose them, as you browse pages. For example, in [List customers](/en/api/customers/list), start with: ```http GET /v1/customers?page_size=10 ``` In subsequent requests, set `after` to the cursor from the previous response: | Page | `page_size` | `after` | | ------ | ----------: | ------------------------------------------------ | | First | `10` | Omitted | | Second | `10` | `page.next_after` value from the first response | | Third | `10` | `page.next_after` value from the second response | Each new request uses the cursor from the page you just received. ## Page size and forward navigation | Field | Where it appears | Description | | ----------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page_size` | Request | Maximum items per page. Accepts `1` to `100`; a positive integer above the maximum uses the maximum. Omitted, empty, zero, negative, text or decimal values use `10`. | | `after` | Request | Cursor received in `page.next_after` to retrieve the next page. | | `list` | Response | Items found on the page. Returns an empty array when there are no results. | | `page.page_size` | Response | Page size applied to the request. | | `page.has_next` | Response | Indicates whether there is a next page. | | `page.next_after` | Response | Cursor for moving forward. Returns `null` when there is no next page. | `page_size` is a limit: a page may contain fewer items than requested. Use `page.has_next` to decide whether to continue. ## Going back one page When `page.has_previous` is `true`, send `page.previous_before` in `before`, keeping the filters and sorting. Remove `after` when moving back. Remove `before` when moving forward. | Field | Where it appears | Description | | ---------------------- | ---------------- | ------------------------------------------------------------------------ | | `before` | Request | Cursor received in `page.previous_before` to retrieve the previous page. | | `page.has_previous` | Response | Indicates whether there is a previous page. | | `page.previous_before` | Response | Cursor for moving back. Returns `null` when there is no previous page. | Send only one cursor per request. Providing values for both `after` and `before` in the same request returns `400 INVALID_FIELDS`, with `MUTUALLY_EXCLUSIVE` in the details of both fields. Remove the cursor for the direction you will not use. If you will not use a cursor, omit the field. Leaving it empty or containing only spaces has the same effect. ## Cursor considerations The cursor belongs to the authenticated company and environment, and to the filters and sorting used in the request. To change these criteria, start a new listing without a cursor. A modified cursor or one used with a different query may be rejected by validation. If you receive `INVALID_CURSOR` in `error.details`, restart the listing without `after` or `before`, keeping the filters you want. In the documentation console, enter these values in **Query Params**. They are included in the request URL and code examples. Empty fields are omitted. **Filtered queries** See the listing endpoint's reference for its filters, sorting and cursor rules. # OpenAPI contract (/en/api/openapi) The [raimshq/openapi](https://github.com/raimshq/openapi) repository publishes the OpenAPI contract for the Raims API version available to integrations. Use this contract to inspect endpoint structures, import the reference into a compatible tool or generate a client for your project. The `latest` directory tracks the API version that is actually published. It does not include changes that exist only in source code. ## Available files * [JSON](https://raw.githubusercontent.com/raimshq/openapi/main/latest/openapi.spec3.json) * [YAML](https://raw.githubusercontent.com/raimshq/openapi/main/latest/openapi.spec3.yaml) Both files describe the same contract. Choose the format accepted by your tool. ## Download or import To download the JSON file: ```sh curl --fail --location --output openapi.spec3.json https://raw.githubusercontent.com/raimshq/openapi/main/latest/openapi.spec3.json ``` In Postman, Insomnia or another OpenAPI 3 compatible tool, choose the option to import from a URL and enter the JSON or YAML address. If the tool accepts only local files, download either format and import it from disk. The contract describes Bearer authentication but contains no credentials. Configure your key in the tool's secure environment and do not save it in an exported collection. ## Generate a client Use the downloaded file as input for an OpenAPI 3 compatible generator. For example, with the OpenAPI Generator CLI: ```sh openapi-generator-cli generate \ -i openapi.spec3.json \ -g YOUR_GENERATOR \ -o ./generated/raims ``` Choose the generator for the language and library used by your project. Review the generated code, keep the generator configuration under version control and run your integration tests before updating your application. This client belongs to your project and is not an official Raims SDK. ## Keep the contract up to date Use the `main/latest` addresses on this page to download the current contract, including for code generation and CI. Download the file again before generating the client to follow the published API version. Review the contract diff, regenerate the client and run your integration tests before updating your application. Downloading a new contract does not automatically change code already generated in your project. # Create a payment link (/en/api/payment-links) Creates or retrieves the link for a charge already registered in the company and authenticated environment. In `charge_id`, provide the identifier of the charge the customer should pay. The charge must be open and within its due date to create or configure its link. The link uses the customer, amount, due date and other charge data. While the charge allows this action, repeating the request reuses the existing link. You can configure return URLs and restrict the payment methods accepted in the checkout. Creating the link does not create another charge or request an email. A new link starts active. If the charge already has a paused link, this request keeps it paused; use PATCH to reactivate it. See [Payment links](/en/api/payment-links/overview) to understand the configuration fields and track payment through the linked charge. POST /v1/payment_links # List payment links (/en/api/payment-links/list) Looks up payment links in the authenticated company and environment. The response shows the link and charge identifiers, checkout URL, `is_active`, return settings and payment method settings. Paused links remain in the list. Use the individual lookup to check whether the checkout can accept payment at this time. Use `charge_id` to look up the link for a specific charge. Start without a cursor, process `list` and, while `page.has_next` is `true`, copy `page.next_after` to `after` in the next request. Copy the entire cursor without interpreting or calculating its contents and keep the same filter. See [Listing and pagination](/en/api/listagem-e-paginacao) to go back with `before`. See how to look up the linked charge's financial data in [Payment links](/en/api/payment-links/overview). GET /v1/payment_links # Payment links (/en/api/payment-links/overview) A payment link opens the checkout for a specific charge. The customer, title, description, amount and due date come from that charge. The link lets you configure destinations for returning to your website and restrict the payment methods offered to the payer. Integration requests use `https://api.raims.com`. These five requests manage payment links: | Purpose | Method and path | | ------------------------------------------- | ---------------------------------------- | | Create or retrieve the link for a charge | `POST /v1/payment_links` | | List links in the company and environment | `GET /v1/payment_links` | | Look up a link and its current availability | `GET /v1/payment_links/{id}` | | Configure, pause or reactivate the link | `PATCH /v1/payment_links/{id}` | | Request an email or resend | `POST /v1/payment_links/{id}/send_email` | ## Link to the charge Create the charge before requesting its link and store the identifier returned by the API. In [Create a payment link](/en/api/payment-links), send this identifier in `charge_id`. The charge must belong to the company and authenticated environment. `charge_id` uses the charge identifier, with the `ch_` prefix. The link's `id` uses `pl_`; it identifies the link in lookups, updates and email requests. The link does not create another customer or charge. It does not define its own price, due date or financial status. To check this data, use [Retrieve a charge](/en/api/charges/retrieve) with the `charge_id`. ## Create or retrieve the link `POST /v1/payment_links` creates the link for an existing charge or reuses the link it already has. The response includes the link's `id`, `charge_id` and `url` for opening the checkout, along with the link settings. To create or configure the link, the charge must be open and within its due date. To receive the link when creating the charge, use `create_checkout: true` in [Create a new charge](/en/api/charges). This option avoids a separate request to obtain the URL without requiring an email request or return URL. Creating or retrieving the link does not confirm payment or request an email. While the charge allows this action, repeating the request does not create another link. A new link starts active. If the existing link is paused, POST keeps it paused. Use PATCH to reactivate it. ## Configure the link You can send `success_redirect_url`, `cancel_redirect_url` and `payment_method_types` in `POST /v1/payment_links` when creating the link, or use `PATCH /v1/payment_links/{id}`, described in [Update a payment link](/en/api/payment-links/update), afterward. After configuring the link, call `GET /v1/payment_links/{id}` and check `is_payable`. The `is_active` field and `effective_payment_method_types` list may still be populated even when the checkout cannot accept payment. The list shows the methods defined by the settings; `is_payable` indicates whether payment is still possible at that moment. `success_redirect_url` sets the return destination after payment is confirmed, under the conditions in [Guide someone who received a link](/en/checkout#orientar-quem-recebeu-um-link). `cancel_redirect_url` sets the address for the option to return to the company's website. This navigation does not cancel the charge, Pix or boleto. Send complete, valid HTTPS URLs. Omitting a URL, sending `null`, empty text or only spaces keeps the registered address. In a new link without an address, the corresponding return option has no destination. To remove a registered destination, use PATCH with `clear_success_redirect_url: true` or `clear_cancel_redirect_url: true`. You can send both commands to remove both destinations. Sending `false` or omitting the command does not request removal. These commands are only for updating a link; they are not sent when creating a charge or link and do not appear in the response. After removal, the corresponding URL returns `null`. Without a success destination, checkout does not redirect automatically; without a cancellation destination, the option to return to the website has no address. Removing a destination does not cancel the charge, Pix or boleto. The update requires an open charge within its due date, even when only removing a destination. A populated URL and its clearing command set to `true` are incompatible in the same request. The API returns HTTP 400 with `INVALID_FIELDS` and `MUTUALLY_EXCLUSIVE` details for both fields. Choose whether to set or remove that destination. You can remove one destination and change the other. `payment_method_types` lets you restrict the methods accepted by the link. Omitting the field keeps the existing configuration. Sending `null` removes the link's custom configuration and returns to the charge and account checkout settings. A populated list must respect the methods accepted by the charge and available on the platform. See the codes in [Payment methods](/en/meios-de-pagamento#códigos-na-api). Changing the link's configuration does not change the customer, title, amount, due date or charge status. Use the [Charges](/en/api/charges/overview) requests to look up data and make changes allowed for that resource. You can also pause the checkout with `is_active: false` and reactivate it with `is_active: true` in PATCH. For the payer, a paused link without a confirmed payment appears as not found or unavailable without revealing the pause. See [Pause and reactivate](#pausar-e-reativar) for the conditions and effects of this setting. ## Pause and reactivate Use [Update a payment link](/en/api/payment-links/update) with `PATCH /v1/payment_links/{id}` and `is_active: false` to pause the checkout. To reactivate it, send `is_active: true` to the same endpoint. Omitting this field keeps the current state; `null`, numbers and text are invalid. ```json { "is_active": false } ``` Pausing keeps the same identifier and URL. The checkout blocks new payment actions and new email or resend requests while paused. Email requests and payments accepted before the pause can continue normally. You can change its other settings without reactivating it. The charge must be open and within its due date to pause, reactivate or configure the link. After the charge expires, PATCH cannot reactivate its link. Pausing or reactivating keeps the same `id` and `url`; neither action extends the charge's due date. When opening the URL of a paused link without a confirmed payment, the payer receives the same not-found or unavailable message. The page does not reveal the pause. This message alone does not identify the reason; the payer should check the received address and contact the company that issued the charge. The company can check `is_active` through the authenticated API to verify the setting. Receipts for confirmed payments remain accessible. The due date continues to approach while the link is paused. Pix and boleto already issued are not canceled and may still be paid outside checkout. To cancel the charge, use [Revoke a charge](/en/api/charges/revoke) and track confirmation. Pausing the link does not replace revocation. Create, list, lookup and update responses include `is_active`. A `true` value means the link is not paused, but does not guarantee that the charge can accept payment. Check `is_payable` in the individual GET before offering checkout. Repeating the current configuration keeps the same link. ## Look up and share Use `GET /v1/payment_links`, described in [List payment links](/en/api/payment-links/list), to browse the account's links. The `charge_id` filter selects links associated with the specified charge. Keep this filter when moving between pages. Use `GET /v1/payment_links/{id}`, described in [Retrieve a payment link](/en/api/payment-links/retrieve), with the link's `id` to check its URL, configuration and current availability. Link and charge identifiers serve different purposes; use each in the indicated field. In the individual GET, `is_payable` indicates whether the charge can still be paid through the link. When it is paid, revoked or expired, the link remains available for lookup but does not allow a new payment. Other situations, such as a boleto awaiting confirmation, may also prevent a new payment. `payment_method_types` shows the link's custom configuration, or `null` to use the charge and account configuration. In this lookup, the list is empty if the configuration contains neither Pix nor boleto; this does not allow sending an empty list when creating or updating the link. `effective_payment_method_types` shows the methods defined by the charge, link and account settings among those available on the platform. A paid charge or paused link may still show Pix and boleto in this list. Use `is_payable` to check whether checkout can still accept payment. When `is_payable` is false, `unavailable_reason` shows the reason. Use `unavailable_reason.code` in your integration; `message` is an English diagnostic explanation whose text may change. When the charge can be paid through the link, `unavailable_reason` is `null`. When the reason is the charge state, the message shows the current state and the accepted states. If an open charge is past its due date, it also shows `due_date` in Unix UTC seconds. The same explanation appears when this condition prevents configuring the link or requesting an email. | Code | How to interpret it | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BOLETO_AWAITING_SETTLEMENT` | The boleto is awaiting a payment update on the charge. Wait for confirmation before offering another charge. | | `CHARGE_EXPIRED` | The charge's payment period has ended. Check its status before deciding how to collect payment. Checkout expiration does not confirm cancellation of a boleto already issued. | | `CHARGE_NOT_OPEN` | The charge is not open for payment. Check its current status. | | `PIX_CANCELLATION_PENDING` | Pix cancellation is awaiting confirmation. Check the charge before attempting another payment. | | `PIX_CANCELLED` | The Pix QR Code was canceled and the charge cannot be paid through this link. | | `PAYMENT_LINK_PAUSED` | The link was paused. The company can reactivate it if the charge remains open and within its due date. | | `PAYMENT_METHODS_UNAVAILABLE` | No method is enabled for this checkout. Check the charge, link and account settings. | Availability follows the charge's checkout rules and may change after the lookup. These fields do not confirm payment or reserve a method. The lookup does not issue Pix or boleto or extend the due date. Creation, listing and updates continue to return the link's configuration; use the individual GET to check availability. Share the `url` returned by the API. Do not build the address from the `id`. Lookups use the existing link and do not generate another checkout. ## Send by email To send or resend an existing payment link through the API, use `POST /v1/payment_links/{id}/send_email`, described in [Email a payment link](/en/api/payment-links/send-email). Provide the `id` in the path, with no request body. The link must be active and the charge must be open and within its due date. A paused link returns HTTP 409 with `PAYMENT_LINK_PAUSED`; reactivate it before requesting the email. The request does not create another link, change the checkout or issue Pix or boleto. The recipient is the payer's email registered on the boleto, when present. Otherwise, it uses the email registered on the charge and, if that is also missing, the email in the customer's current record. An invalid address prevents sending. This request does not allow another recipient. While the company's registration is pending, sending is restricted to the account holder's email. After a request is accepted by this endpoint, wait 60 seconds before requesting another email for the same charge. This interval is shared with the Dashboard's resend action and all other keys and servers for the same company. If you receive HTTP 429, wait for the `Retry-After` interval before trying again through the API or Dashboard. The success response shows the recipient in `recipient_email` and the resend interval in `retry_after_seconds` and `retry_after_until`, the latter in Unix UTC seconds. HTTP 202 confirms that the email request was registered. It does not prove inbox delivery or that the recipient read it. To track payment, look up the linked charge. Sandbox can also send real emails. When testing this endpoint, use a test address you control. ## Track payment Look up the charge identified by `charge_id` to track its status and obtain available Pix or boleto data. Opening the link, issuing a payment method or returning to the website does not confirm that the charge was paid. The link follows the linked charge's conditions. Checkout expiration does not confirm cancellation of a boleto already issued. To cancel an eligible charge, use [Revoke a charge](/en/api/charges/revoke) and track confirmation; editing the link does not replace this action. ## Environment and access Link management uses `https://api.raims.com` with [API-key or OAuth authentication](/en/integracoes/autenticacao). Access is limited to the authenticated company and environment. Sandbox links and charges are kept separate from Production data. Use Sandbox to test without moving real funds. Anyone who receives the URL can open checkout. Do not share your API key with the payer or include it in the URL. The public address does not allow managing the link or charge settings. # Retrieve a payment link (/en/api/payment-links/retrieve) Looks up a link by the identifier received when creating or listing links. The link must belong to the authenticated company and environment. The `charge_id` field identifies the linked charge. Use this identifier in [Retrieve a charge](/en/api/charges/retrieve) to check the customer, amount, due date, status and available payment data. `is_active` indicates whether the link is active or paused. An active link still depends on the charge's conditions to accept payment. `is_payable` indicates whether the charge can still be paid through this link. A charge that has already been paid, revoked or expired, for example, does not allow another payment through the link. If the value is `false`, check `unavailable_reason.code` to understand why. When the reason is a pause, the code is `PAYMENT_LINK_PAUSED`. The link remains available for lookup and uses the same URL after reactivation. See how to use the returned address in [Payment links](/en/api/payment-links/overview#consultar-e-compartilhar). The lookup does not create or change the charge or issue payment data. GET /v1/payment_links/{id} # Email a payment link (/en/api/payment-links/send-email) Requests that the link be emailed to the charge's recipient without recreating the charge or changing the checkout. Provide the link identifier in the path; this request does not accept a body or allow another email address. The link must be active and the charge must be open and within its due date. A paused link returns HTTP 409 with `PAYMENT_LINK_PAUSED`. Reactivate it through PATCH before requesting the email. Accepted requests follow the same 60-second interval as the Dashboard's resend action. Success confirms the email request, not email delivery. Sandbox can also send real emails. See [Send by email](/en/api/payment-links/overview#enviar-por-e-mail) to understand the recipient, restrictions for pending accounts and when to retry. POST /v1/payment_links/{id}/send_email # Update a payment link (/en/api/payment-links/update) Updates an existing link's configuration. Use `is_active: false` to pause the checkout and `is_active: true` to reactivate it with the same URL. Omitting this field keeps the configuration; `null` is not accepted. Pausing also prevents new requests to email the link. It does not cancel Pix or boleto already issued or extend the charge's due date. You can also send return URLs and the list of methods accepted in the checkout. URLs that are omitted, `null` or empty keep the registered addresses. To remove a destination, send `clear_success_redirect_url: true` or `clear_cancel_redirect_url: true`. Sending `false` or omitting the command does not request removal. Do not send a populated URL together with its clearing command set to `true`. This combination returns HTTP 400, with `MUTUALLY_EXCLUSIVE` in the details of both fields. You can remove one destination and update the other in the same request. The response shows `null` for the removed destination. The linked charge must be open and within its due date, including when pausing or reactivating. Other changes do not reactivate a paused link. Omitting `payment_method_types` keeps the link's configuration. Sending `null` removes this custom configuration and returns to the methods defined by the charge and the account's checkout. The request keeps the link to the charge and does not change the customer, title, amount, due date or status. To look up or edit the allowed charge data, use the [charges reference](/en/api/charges/overview). See [Configure the link](/en/api/payment-links/overview#configurar-o-link) to understand return URLs and payment method restrictions. PATCH /v1/payment_links/{id} # Request a refund (/en/api/refunds) Request a refund of a Pix payment received for the specified charge. The money returns to the account that made the payment. Send the amount you want to refund; the same request supports full and partial refunds. In Production, accepting the request does not yet confirm the refund. In Sandbox, the simulation completes within the request. Keep the returned identifier and check the status of that same request. See [Refunds](/en/api/refunds/overview) for the conditions of use and how to track the result. POST /v1/charges/{id}/refunds # Check refund eligibility (/en/api/refunds/eligibility) Check whether a charge can receive a refund request, its remaining amount, the maximum you can request now and the amounts of requests still pending. The response describes conditions at the time of the query. It does not set aside an amount for a refund or guarantee acceptance of a later request. See [Check the refundable amount](/en/api/refunds/overview#consultar-o-valor-devolvível) to understand restrictions and when to request a refund. GET /v1/charges/{id}/refund_eligibility # List refunds for a charge (/en/api/refunds/list) List refunds requested for a charge belonging to the authenticated company and environment, from newest to oldest. Use the history to track partial refunds or locate a request after losing the creation response. You can filter by the request period. Viewing the list does not issue another refund. See [View the history](/en/api/refunds/overview#consultar-o-histórico) and [Listing and pagination](/en/api/listagem-e-paginacao) to continue browsing. GET /v1/charges/{id}/refunds # List refunds (/en/api/refunds/list-all) List refund requests for charges belonging to the authenticated company and environment, from newest to oldest. Use the list to reconcile refunds across charges or locate a request. You can filter by the period when refunds were requested. Viewing the list does not issue another refund. See [View the history](/en/api/refunds/overview#consultar-o-histórico) and [Listing and pagination](/en/api/listagem-e-paginacao) to continue browsing. GET /v1/refunds # Refunds (/en/api/refunds/overview) Use refunds to return all or part of a received Pix payment. The refund uses the original charge and returns the money to the account that made the payment; you do not need to provide another customer, destination account or Pix key. | Purpose | Method and path | | ------------------------------------------- | ----------------------------------------- | | Request a full or partial refund | `POST /v1/charges/{id}/refunds` | | View a request | `GET /v1/refunds/{id}` | | Download the receipt for a completed refund | `GET /v1/refunds/{id}/receipt` | | List refunds across all charges | `GET /v1/refunds` | | List the history for a charge | `GET /v1/charges/{id}/refunds` | | Check availability and the remaining amount | `GET /v1/charges/{id}/refund_eligibility` | ## When to request a refund The charge must have a received and confirmed Pix payment. In Production, the original transfer must be identified. In Sandbox, use a payment confirmed by Raims simulation. A partially refunded charge can receive another request for the remaining amount after the previous one completes. The amount must be covered by the account available balance. Accepted statuses are `4` (`paid`) and `5` (`partially_refunded`). Being in one of these statuses does not remove the other conditions, such as an identified Pix payment, remaining amount and available balance. A charge accepts only one refund in progress. If a request is already pending or has no confirmed result, track that request before trying another. The eligibility query shows the current restriction. A dispute under review can also prevent a request. In that case, check the charge [disputes](/en/api/disputes/overview); there may be no refund in progress in the history. This resource refunds Pix payments. Unpaid charges use [revocation](/en/api/charges/revoke). The refund endpoint does not refund boleto payments or accept instructions to transfer to another account. ## Check the refundable amount Use [Check refund eligibility](/en/api/refunds/eligibility), with `GET /v1/charges/{id}/refund_eligibility`, before offering a refund. Provide the charge identifier with the `ch_` prefix. `eligible` indicates whether current conditions allow a request. `refundable_amount_cents` shows how much remains to be refunded on the charge. `max_refund_amount_cents` shows the maximum you can request now, considering that remainder and the available balance, and is zero when a restriction applies. `pending_amount_cents` shows the amount of requests awaiting a result. When a restriction applies, `reason` gives its code and an explanation in English. Use `reason.code` to decide how to handle it; `reason.message` is for diagnostics and its wording may improve. Without a restriction, `reason` is `null`. | `reason.code` | How to interpret it | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `PIX_REFUND_NOT_AVAILABLE` | The message identifies whether the restriction is the status or payment method. For a status restriction, it shows the current and accepted statuses. | | `PIX_REFUND_CASHIN_NOT_FOUND` | The original confirmed Pix payment was not identified. Check the charge and payment method before requesting. | | `PIX_REFUND_PROVIDER_ACCOUNT_NOT_READY` | In Production, the account cannot yet make the refund. Contact Raims support to check the account. | | `PIX_REFUND_IN_PROGRESS` | A refund is in progress or a dispute is under review. Check the charge history and disputes. | | `PIX_REFUND_ALREADY_COMPLETED` | There is no remaining amount to refund. | | `PIX_REFUND_INSUFFICIENT_BALANCE` | The available balance does not cover the refund. Check the account balance before trying again. | | `PIX_REFUND_PROVIDER_UNAVAILABLE` | In Production, processing is temporarily unavailable. Check again before requesting. | If R$100.00 remains on the charge and R$40.00 is available for a refund, `refundable_amount_cents` is `10000` and `max_refund_amount_cents` is `4000`. At that point, you can request up to R$40.00. This field does not show the full account balance. Send a positive `amount_cents`, up to the stated maximum. To refund the entire remainder, the available maximum must cover the remaining charge amount. This query does not set aside the money or guarantee acceptance: conditions can change and are checked again when submitting the refund. ## Refund a Pix payment through the API Use [Request a refund](/en/api/refunds), with `POST /v1/charges/{id}/refunds`, and send `amount_cents`. The amount uses whole cents: for example, `2500` represents R$25.00. `description` lets you record an optional description of the request. ```json { "amount_cents": 2500, "description": "Devolução parcial do serviço" } ``` To refund everything, send the remaining amount in `amount_cents`. Omitting this field is invalid. For a partial refund, send the partial amount in the same request. The customer and destination account come from the original payment; do not send banking details or a Pix key. In Production, a `202` response confirms that the request was accepted for tracking. In Sandbox, the simulation completes within the request and returns `200` with `status: completed`. Keep the refund `id`, with the `rf_` prefix, to check its result. It differs from the charge `ch_` identifier. If you lose the response, check the charge history before repeating the request. A new request may represent another partial refund. ## Track the result Use [Retrieve a refund](/en/api/refunds/retrieve), with `GET /v1/refunds/{id}`, to query the same request. The response shows the linked charge, amount, description, current status and available dates. When the status is `failed`, `failure_reason` explains the confirmed failure with a code and a message in English. A pending request does not yet confirm that the money returned to the payer. Consider the refund complete only when the returned status confirms completion. After a failure, check the request and charge eligibility before deciding on a new request. | `status` | How to interpret it | | ----------- | ------------------------------------------------------------------------------ | | `reserved` | The request is being prepared. Track the same refund. | | `accepted` | The request was accepted and awaits confirmation. | | `completed` | The refund completed. | | `failed` | The request failure was confirmed. Check eligibility before another request. | | `unknown` | The result is not yet confirmed. Track the same request before trying another. | `created_at`, `completed_at` and `failed_at` use Unix seconds in UTC. Completion and failure dates are `null` until the corresponding result is confirmed. Repeated queries do not start or speed up a refund. Use `failure_reason.code` to handle the known cause. The message is for diagnostics and may improve without changing the meaning of the code. For other statuses, `failure_reason` is `null`. An older failure with no recorded cause may show an unknown reason; this does not justify assuming bank rejection or automatically creating another request. | `failure_reason.code` | How to interpret it | | ----------------------------------- | ---------------------------------------------------------------------------------------------- | | `REFUND_NOT_SUBMITTED` | The request was not submitted for processing. Check the history and eligibility before trying. | | `REFUND_REJECTED` | The request was rejected. Check the history and eligibility before trying again. | | `REFUND_PROCESSING_UNAVAILABLE` | Processing was unavailable and the request failed. Check the history before trying. | | `REFUND_PROCESSING_FAILED` | The processor confirmed the failure without a detailed cause. Check the history before trying. | | `REFUND_FAILURE_REASON_UNAVAILABLE` | No confirmed cause is available. Check the history and contact support if needed. | ## View the history Use [List refunds](/en/api/refunds/list-all), with `GET /v1/refunds`, to view requests for all charges in the authenticated company and environment. Each item includes `charge_id`, allowing you to associate the refund with the charge in your system. To track partial refunds for a specific charge, use [List refunds for a charge](/en/api/refunds/list), with `GET /v1/charges/{id}/refunds`. Both lists show newest requests first and include pending, completed and failed requests. In both lists, use `created_gte` and `created_lte` to filter the period when the refund was requested. Provide Unix seconds in UTC; boundaries are inclusive. This period considers `created_at`, not the charge payment date or refund completion. You can provide one boundary or both, with the end equal to or later than the start. The response uses `list` and `page`. Start without a cursor, process `list` and copy `page.next_after` to `after` while `page.has_next` is true. Keep the same connection or key, filters and list throughout navigation; for the list by charge, also keep the same `id`. To query another period, start without a cursor. Do not interpret or change the received cursor, or exchange cursors between the two lists. To view a previous page, use `page.previous_before` in `before`. Do not send `after` and `before` together. See [Listing and pagination](/en/api/listagem-e-paginacao) for the general rules. ## Refund receipt Use [Download a refund receipt](/en/api/refunds/receipt), with `GET /v1/refunds/{id}/receipt`, to save the document or make it available to the customer. Provide the refund identifier with the `rf_` prefix, received in the request or history query. The receipt requires `status: completed`, a positive amount and a recorded completion date. Pending, failed or unconfirmed requests do not have a completion receipt. In those cases, track the same refund in [Retrieve a refund](/en/api/refunds/retrieve). The PDF shows the amount of that refund. If a charge has two partial refunds, each request has its own receipt; the document does not total the history or replace the original charge amount. The endpoint returns JSON with `url` and `expires_at`. Call it from your integration server with an API key or OAuth session. Make a GET request to the complete `url` to download the PDF from `files.raims.com`, without sending `Authorization` or the API key in that download. `expires_at` gives the expiration in Unix seconds in UTC. After it expires, query the authenticated endpoint again to get another link. An invalid or expired link may receive HTTP `403` on download, without the API JSON error envelope. The URL can be reused until it expires and grants access to anyone who has it. Share it only with authorized people and do not record it in logs. The document is issued by Raims and does not replace a tax invoice or bank receipt. A Sandbox receipt identifies the refund as a simulation, with no real money movement. ## Pix refunds through the API: Sandbox and Production Sandbox lets you test full and partial refunds using the same endpoint and fields as Production. First, confirm a Pix payment through [Confirm payment](/en/api/simulations/confirm-payment) or the Dashboard simulation. Use a Sandbox key from the same company to check eligibility and request a refund. The simulation considers available balance and the remaining amount, completes within the request and returns `200` with `status: completed`. The Sandbox charge, refund history, balance and statement reflect the simulated refund. No real money moves. This documentation console accepts only Sandbox keys. To test a request awaiting a result, use [Simulate a pending refund](/en/api/simulations/request-refund). Then choose between completing the refund and simulating a failure using the same refund ID. This lets you check tracking, balance and receipt availability. See [Pending and failed Pix refunds](/en/api/simulations/overview#estorno-pix-pendente-e-com-falha). Accepted statuses and other conditions still apply; boleto does not support refunds through this endpoint. Confirmed changes generate events for [Sandbox webhooks](/en/integracoes/webhooks/receber-eventos) registered for those types. In Production, an accepted request can return `202` while awaiting confirmation, which must be tracked by querying the refund. Requests use `https://api.raims.com` with [API-key or OAuth authentication](/en/integracoes/autenticacao). With OAuth, refunds must be among the granted operations and remain allowed for the person who authorized the connection. With an API key, queries require **View refunds**, and requests require **Request a Pix refund**. These actions are selected separately on the key. They are separate from the employee **Refund Pix** permission used in the Dashboard. The company and environment come from authentication; an identifier from another company or environment does not grant access to the charge or refund. # Download a refund receipt (/en/api/refunds/receipt) Get a temporary URL to download the receipt for a completed refund using its refund ID. Call this endpoint with your API key or OAuth session and use the returned `url` to download the PDF from `files.raims.com`, without sending the key in that download. The document shows the amount of that request, including partial refunds. Pending or failed requests do not have a completion receipt. See [Refund receipt](/en/api/refunds/overview#comprovante-de-estorno) for the conditions and how to use the document. GET /v1/refunds/{id}/receipt # Retrieve a refund (/en/api/refunds/retrieve) View a refund using the identifier returned when requesting it or listing the history, within the authenticated company and environment. The response includes the status, dates and available reason when a failure is confirmed. This request does not create another refund or speed up confirmation. See [Track the result](/en/api/refunds/overview#acompanhar-o-resultado) to interpret the response. GET /v1/refunds/{id} # Request identifier (/en/api/request-id) Each response processed by the API includes an identifier for the attempt. Store this value with the status and time when you need to investigate a request. `Request-Id` is a response header. Do not send this name in the request or try to choose its value. ## Where to find it The response contains the main header and an alias with the same value: ```http Request-Id: req_4ZxYp8Q2mV7nR6sT5uW3aB X-Request-Id: req_4ZxYp8Q2mV7nR6sT5uW3aB ``` Use `Request-Id` in new integrations. `X-Request-Id` remains available for compatibility. In the Raims CLI, the field appears as `request_id` in JSON output and as `Request-Id` in text output. This documentation console shows the value on the real response and lets you copy it. Response examples do not have a real ID. ## Provide it to support When asking for help with an API response, provide its `Request-Id`, the approximate time and the endpoint you called. Do not send the API key, webhook secret or a payload containing customer data. The identifier helps locate an attempt when its records are available. Company request logging may be disabled or the history may have expired, so having the ID does not guarantee that the request can still be searched. ## Identifier limits Each HTTP attempt receives another `Request-Id`, including a retry or an idempotent response replay. To retry the same intent safely, use `Idempotency-Key`; do not reuse `Request-Id`. The value with the `req_` prefix is not a resource, payment or pending operation ID. Continue using identifiers returned in the body to query the result. The header identifies responses processed by the API. A failure produced before it, for example at the edge or a proxy, may not contain `Request-Id`. # Simulate boleto clearing (/en/api/simulations/compensate-boleto) Simulates the clearing of an issued boleto to test the wait for settlement. This step does not credit the balance or confirm an incoming payment in the statement. **Sandbox only** Use a key with the `sk_test_` prefix. Clearing is simulated and does not move real money. See how to complete the payment in [Boleto clearing and settlement](/en/api/simulations/overview#compensação-e-liquidação-do-boleto). POST /v1/simulations/charges/{id}/compensate_boleto # Complete a simulated refund (/en/api/simulations/complete-refund) Completes a Pix refund started with [Simulate a pending refund](/en/api/simulations/request-refund). Provide the refund ID to check the completed result and its receipt. **Sandbox only** Use a key with the `sk_test_` prefix. Completion does not move real money and is not available in Production. See [Pending and failed Pix refunds](/en/api/simulations/overview#estorno-pix-pendente-e-com-falha) to prepare the test and track its results. POST /v1/simulations/refunds/{id}/complete # Confirm payment (/en/api/simulations/confirm-payment) Confirms payment of a test charge by ID. Use this request to check the paid status, balance and incoming payment in the Sandbox statement. **Sandbox only** Use a key with the `sk_test_` prefix. This confirmation is simulated, does not move real money and is not available in Production. See [Simulation](/en/api/simulations/overview#confirmar-um-pagamento) to prepare the charge and check the results. Repeating the same confirmation does not credit the amount again. POST /v1/simulations/charges/{id}/confirm_payment # Simulate payment failure (/en/api/simulations/fail-payment) Simulates payment failure for a charge by ID. Use this request to check how your integration handles an unpaid result. **Sandbox only** Use a key with the `sk_test_` prefix. The simulated failure does not affect the balance and is not available in Production. See [Simulation](/en/api/simulations/overview#simular-uma-falha) to prepare the charge and understand the conditions for repeating the test. POST /v1/simulations/charges/{id}/fail_payment # Simulate refund failure (/en/api/simulations/fail-refund) Simulates failure of a pending Pix refund without completing the refund. Use this request to check the failure reason and the release of the amount back to the available balance. **Sandbox only** Use a key with the `sk_test_` prefix. The simulated failure is not available in Production. See [Pending and failed Pix refunds](/en/api/simulations/overview#estorno-pix-pendente-e-com-falha) to prepare the test and track its results. POST /v1/simulations/refunds/{id}/fail # Issue a test payment (/en/api/simulations/issue-payment) Requests Pix or boleto issuance for a test charge. When a scenario has been prepared for this issuance, the request returns the selected pending or failed result. **Sandbox only** Use a key with the `sk_test_` prefix. Issuing payment instructions does not confirm that the charge has been paid. See the conditions and test sequence in [Pending or failed issuance and cancellation](/en/api/simulations/overview#emissão-e-cancelamento-com-pendência-ou-falha). POST /v1/simulations/charges/{id}/issue_payment # Simulation (/en/api/simulations/overview) Use simulation to test Pix and boleto payments, refunds and results awaiting confirmation. The results update Sandbox records so you can check the charge's progress and its effects on the balance, statement and receipts. **Sandbox only** These endpoints use only the Sandbox environment, with an API key or an OAuth session authorized for that environment. Simulations do not move real money and are not available in Production. | Purpose | Method and path | | --------------------------------------------- | ----------------------------------------------------- | | Confirm a test payment | `POST /v1/simulations/charges/{id}/confirm_payment` | | Simulate payment failure | `POST /v1/simulations/charges/{id}/fail_payment` | | Start a pending Pix refund | `POST /v1/simulations/charges/{id}/refunds` | | Complete a pending refund | `POST /v1/simulations/refunds/{id}/complete` | | Simulate refund failure | `POST /v1/simulations/refunds/{id}/fail` | | Simulate boleto clearing | `POST /v1/simulations/charges/{id}/compensate_boleto` | | Prepare issuance or cancellation | `POST /v1/simulations/charges/{id}/scenario` | | Issue test Pix or boleto payment instructions | `POST /v1/simulations/charges/{id}/issue_payment` | | Resolve pending issuance or cancellation | `POST /v1/simulations/charges/{id}/resolve` | ## Use only in the Sandbox Create the customer and charge in your company's Sandbox with [API-key or OAuth authentication](/en/integracoes/autenticacao). Use the same company and environment to simulate the result and retrieve the records. With OAuth, select Sandbox; with API-key authentication, use a Sandbox key. Do not provide the environment in the request body or URL. Provide the charge or refund ID in the path, according to the request. A Production request receives `403 SANDBOX_ENVIRONMENT_REQUIRED`. An ID that does not exist, belongs to another company or belongs to another environment receives the same resource-not-found response. ## Confirm a payment Use [Confirm payment](/en/api/simulations/confirm-payment) to complete payment of a test charge that is still open. The response reports `status: 4`, meaning paid, and `amount_cents` with the charge amount in Brazilian real cents. The amount is credited to the Sandbox balance only once. You can check the balance in [Retrieve balance](/en/api/balances) and track the entry in [Statement](/en/api/statements/overview). The entry may take a few moments to appear; do not repeat the confirmation to try to speed up this update. To test payment details and the receipt, create the charge with the payment method you want: `payment_method: 1` for Pix or `payment_method: 2` for boleto. See the issuance conditions in [Charges](/en/api/charges/overview). After confirmation, use the [payment details](/en/api/charges/payment) and [receipt](/en/api/charges/receipt) endpoints. Test documents identify the payment as simulated. Confirmation does not choose a payment method for the charge. ## Simulate a failure Use [Simulate payment failure](/en/api/simulations/fail-payment) to test how you handle an open charge that was not paid. The response reports `status: 9`, meaning failed. This result does not credit the balance or create an incoming payment entry in the statement. Failure ends this test. To check an approved payment afterward, create another Sandbox charge. ## Pending and failed Pix refunds Create a Pix charge, confirm payment and use [Simulate a pending refund](/en/api/simulations/request-refund). Send the amount in `amount_cents`, as in a normal [refund request](/en/api/refunds/overview). The balance and remaining amount conditions still apply. The `202` response returns the refund ID with `status: accepted`. Keep this ID to [track the request](/en/api/refunds/retrieve). The requested amount leaves the total and available balances while the request awaits a result; the blocked balance field remains unchanged. The receipt is not available yet. Choose a result for the same refund: * [Complete a simulated refund](/en/api/simulations/complete-refund) returns `completed`, updates the refund on the charge and makes the receipt available. The amount is not deducted again. * [Simulate refund failure](/en/api/simulations/fail-refund) returns `failed`, with `REFUND_PROCESSING_FAILED` in `failure_reason.code`, and returns the amount to the available balance. There is no completed refund receipt. Repeating the same final result returns the refund without repeating its effect. Trying to change a completed result to failure, or a failure to completion, returns `409 REFUND_NOT_SIMULATABLE`. For another test, check eligibility before creating a new request. Repeating creation while another request is pending receives `PIX_REFUND_IN_PROGRESS`; use the ID you already received to complete or fail that request. The normal endpoint `POST /v1/charges/{id}/refunds` still completes the refund immediately in the Sandbox. Use the simulation routes when you need to test the wait and the later result. ## Boleto clearing and settlement Create a boleto charge and issue its payment instructions. Use [Simulate boleto clearing](/en/api/simulations/compensate-boleto) to record that the payment has cleared but still awaits settlement. This step does not credit the balance or make a completed payment receipt available. Retrieving the charge reports progress in `payment_information.boleto_payment_status`: `awaiting_payment` before clearing, `compensated` while awaiting settlement and `settled` after confirmation. The field returns `null` when no progress is available. Then use [Confirm payment](/en/api/simulations/confirm-payment) to settle the boleto. Only this confirmation credits the amount and makes payment details and the receipt available. The statement may take a few moments to show the incoming payment. Repeating clearing or confirmation does not repeat the credit. ## Pending or failed issuance and cancellation Use [Prepare a scenario](/en/api/simulations/scenario) before the action you want to test. Send `action` with `pix_issuance`, `boleto_issuance` or `cancellation` and choose `outcome: pending` or `outcome: failed`. The response with `state: configured` confirms preparation; it has not yet issued payment instructions or canceled the charge. For issuance, create the charge with `payment_method_types: [1]` for Pix or `payment_method_types: [2]` for boleto, without issuance during creation. Prepare the scenario and use [Issue a test payment](/en/api/simulations/issue-payment), providing `payment_method: 1` or `2`. Issuance through the charge checkout also uses the prepared scenario. See the creation conditions in [Charges](/en/api/charges/overview). For cancellation, the Sandbox charge must be open and already have Pix or boleto payment instructions issued. If payment instructions are not yet available, issue them through checkout or [Issue a test payment](/en/api/simulations/issue-payment) before preparing the scenario. Do not confirm payment in this flow. After issuance, prepare `action: cancellation` and use [Revoke a charge](/en/api/charges/revoke). The normal request returns the selected pending or failed result. Preparing the scenario does not change the balance or refund a payment already received. With `outcome: pending`, track the charge and use [Resolve a pending scenario](/en/api/simulations/resolve) to choose `completed` or `failed` for the same `action`. This request completes an action that has already started; it does not start issuance or cancellation. Completed issuance makes the Pix or boleto available without confirming payment. Completed cancellation revokes the charge without refunding amounts. With `outcome: failed`, the action returns the failure without going through resolution. Issuance failure appears in `pix_status` or `boleto_status`, and its reason in `pix_error` or `boleto_error`. It differs from [Simulate payment failure](/en/api/simulations/fail-payment), which closes the charge with a payment failure. Each scenario applies to the specified charge. Repeating the same preparation or resolution preserves the result; trying to replace a scenario already defined receives `409 CHARGE_SCENARIO_CONFLICT`. Create another charge to test a different combination. ## Repeat a simulation If the connection is interrupted, retrieve the charge or refund by the same ID. Repeating a confirmation, payment failure, clearing or scenario step already applied reports `duplicate: true` without applying the financial effect again. For refund completion and failure, the response returns the same refund with its final status. A paid charge cannot receive a simulated payment failure, and a failed charge cannot receive confirmation. These two requests also reject canceled charges or charges with another final result, with `409 CHARGE_NOT_SIMULATABLE`. Retrieve the current status and create another charge to test a different result. ## Test other resources Use each resource's endpoints with the Sandbox key. You do not need a simulation endpoint to create customers, create or update charges, manage payment links or revoke a charge. To test a refund, create a Pix charge, confirm its payment and use [Refunds](/en/api/refunds/overview). The balance, remaining amount and charge status conditions still apply. Refunds in the Sandbox are simulated; the refund endpoint does not accept boleto. Balance, statement, statistics, payment details and receipt queries let you check the test results. Withdrawal requests remain restricted to Production; charge simulations do not transfer amounts to a bank account. To test an overdue charge, create one with a short due period and wait for it to expire. Payment simulation can also confirm an overdue charge, provided it is still open to receive the result. Simulation preserves the charge's due date. [Disputes](/en/api/disputes/overview) queries return the cases available in the queried environment. Confirming a test payment does not open a dispute. Changes confirmed by simulation generate the corresponding webhook events for destinations registered in the Sandbox. Requests to your endpoint are real; use a test receiver and see [Receive and validate events](/en/integracoes/webhooks/receber-eventos). Requests in other resources that ask to send email retain their own rules; use only authorized recipients in tests. # Simulate a pending refund (/en/api/simulations/request-refund) Starts a test Pix refund that awaits confirmation. Use the returned ID to complete the refund or simulate a failure in another request. **Sandbox only** Use a key with the `sk_test_` prefix. The refund is simulated and does not move real money. Check the conditions and balance effects in [Pending and failed Pix refunds](/en/api/simulations/overview#estorno-pix-pendente-e-com-falha). POST /v1/simulations/charges/{id}/refunds # Resolve a pending scenario (/en/api/simulations/resolve) Sets the result of issuance or cancellation left pending in the test scenario. The action must already have been started on the charge. **Sandbox only** Use a key with the `sk_test_` prefix. Resolution is simulated and does not move real money. See how to prepare and start the action in [Pending or failed issuance and cancellation](/en/api/simulations/overview#emissão-e-cancelamento-com-pendência-ou-falha). POST /v1/simulations/charges/{id}/resolve # Prepare a scenario (/en/api/simulations/scenario) Prepares the result of Pix or boleto issuance, or of cancellation. After this request, perform the corresponding action on the same charge. For `action: cancellation`, use an open Sandbox charge with Pix or boleto payment instructions already issued. If payment instructions are not yet available, issue them before preparing the scenario. Then use [Revoke a charge](/en/api/charges/revoke). Do not confirm payment in this flow. **Sandbox only** Use a key with the `sk_test_` prefix. The scenario does not move real money or change Production charges. See the sequence in [Pending or failed issuance and cancellation](/en/api/simulations/overview#emissão-e-cancelamento-com-pendência-ou-falha). POST /v1/simulations/charges/{id}/scenario # Retrieve account statement (/en/api/statements) View financial entries for the authenticated company and environment. Use filters to select a period, entry types or a linked reference. A single transaction can generate several entries. This request shows the recorded history without making payments or changing account amounts. See [Account statement](/en/api/statements/overview) to interpret the amounts and navigate through pages. The [types and identifiers guide](/en/tipos-e-identificadores) explains entry codes and the prefixes of references that may appear. GET /v1/statements # Account statement (/en/api/statements/overview) Use the statement to check transactions recorded in the account and reconcile amounts with your system. Each item is a financial entry; a payment can generate an incoming amount and a fee as separate items. | Purpose | Method and path | | ----------------------- | ------------------------- | | View statement entries | `GET /v1/statements` | | Retrieve an entry by ID | `GET /v1/statements/{id}` | ## View transactions Use [Retrieve account statement](/en/api/statements), with `GET /v1/statements`. You can query a period, select entry types or filter by a linked reference. Combine filters according to the query you need. Dates use Unix seconds in UTC. `created_gte` includes entries from the specified instant onward, and `created_lte` includes entries up to that instant. The default order shows newest entries first; `sort_order: asc` shows oldest entries first. The query returns history recorded by Raims. It does not initiate payments, withdrawals, refunds or balance releases. A request still in progress may not have its financial result in the statement; also track the resource that originated the request. ## View a statement entry Use [Retrieve a statement entry](/en/api/statements/retrieve), with `GET /v1/statements/{id}`, to check an item without navigating through statement pages again. Send the complete identifier with the `st_` prefix returned in the list. The response contains the same fields as a list item. An entry that is missing or does not belong to the authenticated company and environment receives the same resource not found response. ## Entry types and amounts `amount_cents` shows the amount in Brazilian real cents, preserving its sign: `10000` represents R$100.00, and `-250` represents a debit of R$2.50. Interpret the amount together with `statement_type`. The [entry types guide](/en/tipos-e-identificadores/financeiro#tipos-de-lançamento-do-extrato) explains all codes, amount signs and considerations for each case. Holds and releases record changes in money availability. A release does not represent a new receipt. The statement does not show the account balance after each entry; adding up a page or only filtered items does not provide the current balance. To view the current balance, use [Balance](/en/api/balances/overview). It distinguishes the account total, the held portion and the available amount. ## Links to other resources `id`, with the `st_` prefix, identifies the entry so your system can recognize it. `reference_id` identifies the source resource when a link is available. `reference_type` shows the category of that reference: charge (`1`), dispute (`2`), withdrawal (`3`), adjustment (`4`) or manual entry (`5`). Fields without an available link are `null`. See the [identifiers and prefixes guide](/en/tipos-e-identificadores/identificadores) to distinguish IDs, including references without their own public endpoint. When the reference is a withdrawal, copy the `wd_` ID to [Retrieve a withdrawal](/en/api/withdrawals/retrieve). The query shows progress and the recorded destination without requesting another transfer. `refund_id` identifies the refund request linked to the entry, when available. `dispute_id` identifies the corresponding dispute, including MED cases. Use these fields to view the source [refund](/en/api/refunds/retrieve) or [dispute](/en/api/disputes/retrieve). These fields are `null` when no link is confirmed. A fee or another entry for the same charge does not automatically receive the refund or dispute ID. Keep the returned IDs, including their prefixes, when querying each resource. Use [Charges](/en/api/charges/overview) and [Disputes](/en/api/disputes/overview) to track the corresponding resources. The entry identifier differs from the charge or dispute identifier. The presence of a reference does not mean that a public endpoint exists to query every category. ## Navigate the history The response contains `list`, with the entries on the page, and `page`, with navigation details. Start without a cursor and process the items in `list`. While `page.has_next` is true, copy the entire `page.next_after` to `after` in the next request. Keep the same connection or key, filters and sorting throughout navigation. To change the query, start again without a cursor. An empty list means that the page has no entries for the specified filters. To go back, use `page.previous_before` in `before`. Do not send populated `after` and `before` together or interpret cursor contents. See [Listing and pagination](/en/api/listagem-e-paginacao) for the general rules. ## Company and environment Queries use [API-key or OAuth authentication](/en/integracoes/autenticacao). The authenticated environment determines the history: Sandbox queries only simulated transactions; Production queries the corresponding financial history. This documentation console accepts only Sandbox keys. Filtering by a reference does not grant access to another company or environment. Handle errors by HTTP status and `error.code`; for validation errors, also check the fields indicated in `error.details`. # Retrieve a statement entry (/en/api/statements/retrieve) View the amount, type and links of an entry for the authenticated company and environment. Use the `id` with the `st_` prefix returned in the list. Links to a refund or dispute appear only when they have been identified for that entry. See [Account statement](/en/api/statements/overview) to interpret the returned amounts and references. Also see the [types and identifiers guide](/en/tipos-e-identificadores) to interpret codes and references to other resources. GET /v1/statements/{id} # List deliveries (/en/api/webhook-deliveries) Query deliveries for the authenticated company and environment. Use the filters to find a delivery and its identifier to query the details. See [Track a delivery](/en/api/webhook-deliveries/overview#acompanhar-uma-entrega) and [Listing and pagination](/en/api/listagem-e-paginacao). GET /v1/webhook_deliveries # Advance an attempt (/en/api/webhook-deliveries/advance) Request an earlier attempt for a pending delivery after fixing your receiver. The webhook must be active, its queue must not be paused and the delivery must still be within its deadline. `webhook.test` events cannot be advanced. To check the receiver again, [request another test](/en/api/webhooks/test). Acceptance of the request does not confirm that the event was sent. Query the same delivery to track the result. See [Advance an attempt](/en/api/webhook-deliveries/overview#antecipar-uma-tentativa) to distinguish this action from a resend. POST /v1/webhook_deliveries/{delivery_id}/advance # Retrieve an attempt (/en/api/webhook-deliveries/attempt-retrieve) Query the recorded attempt data to investigate the receiver response or a connection failure. The record may not include all response data. See [Query attempts and responses](/en/api/webhook-deliveries/overview#consultar-tentativas-e-respostas). GET /v1/webhook_deliveries/{delivery_id}/attempts/{attempt_id} # List attempts (/en/api/webhook-deliveries/attempts) Query each HTTP attempt recorded for the delivery. A failure may be followed by another attempt, within the limits of the environment. See [Query attempts and responses](/en/api/webhook-deliveries/overview#consultar-tentativas-e-respostas). GET /v1/webhook_deliveries/{delivery_id}/attempts # Webhook deliveries (/en/api/webhook-deliveries/overview) Check what happened between event creation and your receiver response. Use the delivery list to track progress and the details of each attempt to investigate failures. To register a destination or change the events it receives, use [Webhooks](/en/api/webhooks/overview). ## Event, delivery and attempt An event describes a change, such as `charge.paid`. A delivery sends that event to a webhook. An attempt is each HTTP call made to complete the delivery. | Identifier | Where to find it | When it changes | | ---------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | Event | `event_id` in a query or `id` in the received body | Stays the same across attempts, destinations for the same event and manual resends. | | Delivery | `id` in a query, `delivery_id` in a test or resend, and the `webhook-id` header | Each destination and resend has its own delivery. | | Attempt | `id` in the attempt list or details | Each recorded HTTP call has its own identifier. | A delivery may have several attempts, all with the same `webhook-id`. Use the identifier returned by the attempt query to retrieve its details; it is different from event and delivery IDs. Use the event to avoid repeating its effect in your system and the delivery to recognize retries. See [Handle redeliveries and ordering](/en/integracoes/webhooks/receber-eventos#tratar-reentregas-e-ordem). ## Track a delivery [List deliveries](/en/api/webhook-deliveries) and use the `id` of a result to [retrieve it](/en/api/webhook-deliveries/retrieve). Progress information may appear with a delay; the absence of a record does not prove that the event was never sent. The list shows the most recent deliveries first. You can filter by webhook, event type, status and delivery creation period. If you already have the event UUID, use `event_id` to group its deliveries, including manual resends. To find the event by resource first, see [Webhook events](/en/api/webhook-events/overview). The `created_gte` and `created_lte` limits are inclusive. The query covers up to [30 days from delivery creation](#histórico-por-30-dias), even if you omit the period. Start listing without a cursor, process `list` and copy `page.next_after` to `after` while `page.has_next` is true. Keep the filters while navigating. To go back, use `page.previous_before` in `before`. Copy the entire cursor and do not send both directions in the same request. See [Listing and pagination](/en/api/listagem-e-paginacao). Tracking dates are returned in UTC Unix seconds. `event_created_at` identifies the original event creation time; `created_at` identifies the delivery creation time. These dates may differ in a resend. `deadline_at` is the deadline for completing the delivery, and `next_attempt_at` gives the next scheduled attempt when available. Queries do not start or speed up deliveries. A paused queue prevents new attempts but keeps the original delivery deadline. Check `is_paused` in the webhook configuration before investigating a delay. See [Pause and resume the queue](/en/api/webhooks/overview#pausar-e-retomar-a-fila). | `status` | Meaning | | ------------ | ------------------------------------------------------------------ | | `pending` | The delivery is waiting for a sending attempt. | | `processing` | An attempt is in progress or awaiting its result. | | `delivered` | The receiver returned a successful HTTP `2xx` response. | | `failed` | The delivery ended unsuccessfully or exceeded its deadline. | | `canceled` | The delivery was ended because of the webhook registration status. | An HTTP `2xx` response confirms that the receiver accepted the delivery. It does not prove subsequent processing in the destination system. Check your application records as well. ## Query attempts and responses To query the HTTP response and body of a webhook attempt through the API, [list attempts](/en/api/webhook-deliveries/attempts) for the delivery and [retrieve one](/en/api/webhook-deliveries/attempt-retrieve) to see the available details. The record includes the HTTP response, duration, error and destination used when those data were captured. The list contains HTTP calls to the receiver. A wait before sending is not an HTTP attempt and may leave the delivery pending with an empty attempt list. Attempts appear from newest to oldest. Use pagination to browse the complete available history. In attempts, `created_at` indicates when the attempt finished. `duration_ms` measures the total attempt time, which may include preparation and waiting before the HTTP call. Do not use this value alone as your receiver response time. `status_code: null` means that no HTTP status is available. In this case, the error may help identify a connection failure or timeout. A failed attempt does not mean that the delivery has ended: check its progress and the next scheduled attempt. `destination_ip` identifies the destination used for that connection. If a proxy sits in front of the receiver, this IP may belong to the proxy. The field does not identify the Raims source IP or the current result of a DNS query. Request and response bodies are in the attempt details. `request_available` and `response_body_available` indicate their availability. An unavailable body differs from an empty body that was recorded. `response_body_truncated: true` means that the capture is partial; the content may not be complete JSON. Response capture is limited to 8 KiB. Binary, compressed or invalid UTF-8 responses may also be unavailable. Older records may not include a body, URL or IP. The presence of metadata does not guarantee that those data were captured. Do not include secrets or unnecessary personal data in receiver responses. ## 30-day history The API keeps the delivery, its attempts and captured bodies available for query for **30 days from delivery creation**, shown in `created_at`. After that period, they no longer appear in queries. A new attempt for the same delivery does not restart the 30 days. A resend creates another delivery with its own query period. The limit for requesting that resend remains **15 days from original event creation**, shown in `event_created_at`. Keeping the history for 30 days does not extend that limit. In the Dashboard, logs for each attempt can be queried for 30 days from that attempt's completion. A record may therefore still appear in logs after the API delivery period has ended. ## Investigate a failure Query the delivery and open the most recent attempt. The attempt HTTP status was returned by the receiver or a layer in front of it; it differs from the status of the request used to query the Raims API. | Attempt result | What to check | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | No HTTP status | Check DNS, HTTPS certificate, connectivity and timeout. The lack of a response does not prove that the receiver did not accept the event. | | `3xx` | Register the final HTTPS URL. Raims does not follow redirects. | | `400`, `401` or `403` | Check the response and receiver records. Verify the original body, signature, environment secret and any login or firewall blocks. | | `404` | Check the registered path and whether the receiver accepts `POST` at that address. | | `429` | Review receiver capacity and limits. `Retry-After` may guide the next attempt within the Raims deadlines. | | `5xx` or timeout | Investigate the receiver error and reduce the work done before acknowledging receipt. | | `2xx`, but without the expected result in your system | Check processing after acceptance, duplicate records and the resource's current state. | If a broad delivery query returns `503`, wait and try a shorter period or more specific filters. Also check the general guidance for [API unavailability](/en/api/codigos-http-das-respostas). Check the URL, certificate, signature and firewall rules before requesting another delivery. Automatic Production and Sandbox deadlines are explained in [Webhook failures and retries](/en/integracoes/webhooks/receber-eventos#falhas-e-novas-tentativas-de-webhook). ## Advance an attempt If the receiver has been fixed and the delivery is still waiting for an attempt, use [Advance an attempt](/en/api/webhook-deliveries/advance). The delivery must be pending, within its deadline, with an active webhook and an unpaused queue. The action requests that the next attempt become eligible to run before its scheduled time, subject to sending limits. It preserves the event and delivery; the `delivery_id` stays the same. It does not create another delivery, extend the deadline or increase the number of attempts allowed in Sandbox. A `202` response confirms receipt of the request. The delivery condition is checked again before advancing the attempt, because it may change in that interval. Query the same delivery to track the result. An attempt in progress or a delivery that has already ended cannot be advanced. For a delivery that has ended, check [resend eligibility](#reenviar-um-evento). The technical event `webhook.test` cannot be advanced. If you need to test the receiver again, use [Send a test event](/en/api/webhooks/test). ## Resend an event [Request a resend](/en/api/webhook-deliveries/resend) from an event delivery. The event must have been created no more than 15 days ago, its body must remain available and its type must still be selected in an active webhook. If you have the event ID and need to choose the destination, use [Send an event to a webhook](/en/api/webhook-events/deliver). This route allows the first delivery to that webhook and follows the same eligibility limits. The request returns `event_id` and `delivery_id`. Query the new delivery to track the result. Acceptance of the request does not confirm receipt or cancel automatic attempts for the previous delivery. The record may take a few moments to appear in the query after acceptance; wait briefly before querying again. If the queue is paused, the new delivery also waits for it to resume while its own attempt deadline continues to run. A resend preserves the original body bytes, including its `id` and `created_at`, and uses the current webhook URL and secret. Prepare the receiver to receive the same event in different deliveries without repeating its effect. Resending does not repeat the financial transaction that created the event. The new delivery has its own attempt deadline. The limit for requesting another resend remains tied to original event creation; resending does not renew the 15 days. See [Manual event resends](/en/integracoes/webhooks/receber-eventos#reenvio-manual-de-eventos). `webhook.test` events cannot be resent. To check the receiver again, [request another test](/en/api/webhooks/test). Deleting a webhook preserves the history available for query. Use its identifier as a filter to find previous deliveries. Deletion prevents resending to that webhook. ## Resend multiple events Use [Resend multiple events](/en/api/webhook-deliveries/resend-batch) to request deliveries for up to 500 IDs in one request. Each item follows the same conditions as an individual resend. You can combine deliveries for different webhooks from the same company and environment. The response keeps the order of the submitted IDs. For each accepted item, it returns the original event and new delivery. A rejected item includes the reason in `error`, without preventing acceptance of the others. HTTP `202` confirms processing of the request; check each result before tracking the new deliveries. If the same ID appears more than once, or several deliveries refer to the same event and webhook, the request creates a single new delivery for that pair. The corresponding results return the same `delivery_id`. Resending does not cancel previous attempts, including those in progress. Fix the receiver before submitting the request and keep deduplication by event ID. If a failure prevents the API response, some items may have been accepted. Query deliveries before repeating the entire request. ## Company and environment Use [API-key or OAuth authentication](/en/integracoes/autenticacao) for the same company and environment as the webhooks. Filters and identifiers do not grant access to another company or environment. The console accepts Sandbox keys only. Queries do not change the delivery or financial resource. Keep keys and secrets in the private integration environment. # Resend an event (/en/api/webhook-deliveries/resend) Request another delivery of the original event to the same webhook. The request preserves the event content and uses the current destination configuration. The `event_id` stays the same, and `delivery_id` identifies the new delivery. Acceptance of the request does not confirm receipt or cancel attempts for the previous delivery. See [Resend an event](/en/api/webhook-deliveries/overview#reenviar-um-evento) to check the conditions and handle duplicates at the receiver. POST /v1/webhook_deliveries/{delivery_id}/resend # Resend multiple events (/en/api/webhook-deliveries/resend-batch) Request event resends for multiple deliveries in one request. Check each item result: a rejected event does not prevent acceptance of the others. Items for the same event and webhook share a single new delivery within the request. Resending preserves the original event and does not cancel previous attempts. See [Resend multiple events](/en/api/webhook-deliveries/overview#reenviar-vários-eventos) to track results and handle failures without duplicating the request. POST /v1/webhook_deliveries/resend # Retrieve a delivery (/en/api/webhook-deliveries/retrieve) Query a delivery result and progress using the identifier returned by the list, test or resend request. See [Track a delivery](/en/api/webhook-deliveries/overview#acompanhar-uma-entrega). GET /v1/webhook_deliveries/{delivery_id} # List events (/en/api/webhook-events) Query events for the authenticated company and environment. Use the resource identifier to find events related to a charge or refund, even if you do not know a delivery ID. See [Find an event](/en/api/webhook-events/overview#localizar-um-evento) to interpret the filters and continue pagination. GET /v1/webhook_events # Send an event to a webhook (/en/api/webhook-events/deliver) Provide the event in the path and the webhook in the body. The destination must be active, select the event type and belong to the same authenticated company and environment. The request allows the first delivery of the event to this webhook. The event must be no more than 15 days old and its original body must still be available. The response returns the `delivery_id` for tracking; acceptance of the request does not confirm receipt by the receiver. If the queue is paused, the delivery waits for it to resume within its own deadline. See [Send to a webhook](/en/api/webhook-events/overview#enviar-para-um-webhook) to check the limits, preserve the event identity and handle duplicates. POST /v1/webhook_events/{event_id}/deliveries # Webhook events (/en/api/webhook-events/overview) An event records a change in Raims, such as a charge payment. It has its own identifier, separate from delivery and attempt IDs. Use this query when you have the ID received in the webhook body or need to find events for a charge. ## Find an event [List events](/en/api/webhook-events) for the company and environment of the key. You can filter by type, resource and creation period. Use `resource_id` with the public resource identifier, such as `ch_` for a charge or `rf_` for a refund. This field does not accept an event or delivery ID. `created_gte` and `created_lte` are UTC Unix seconds with inclusive limits. The list shows the most recent events first. Start without a cursor, process `list` and copy `page.next_after` to `after` while `page.has_next` is true. Keep the same filters. To go back, use `page.previous_before` in `before`, without combining the two cursors. See [Listing and pagination](/en/api/listagem-e-paginacao). Each item includes the event ID, type, creation time and related resource. A manual resend keeps the same event and does not create another occurrence in the list. The `webhook.test` test creates an event for the webhook being tested. ## Query the original content Use [Retrieve an event](/en/api/webhook-events/retrieve) with the event UUID. In addition to the list data, the response includes `payload`, a string containing the original JSON. Parse this string as JSON when you need to read its fields. The query does not send the event to your receiver. The query returns `created_at` in UTC Unix seconds. Inside `payload`, the original `created_at` remains in ISO 8601. The content records the event at that moment; query the corresponding resource to check its current state. The content may include integration data. Restrict access to authorized people and systems, and do not send it to support with sensitive information. To validate notifications received over HTTP, use the [webhook signature](/en/integracoes/webhooks/receber-eventos#validar-a-assinatura). ## Find deliveries for the event Use the `event_id` filter in [List deliveries](/en/api/webhook-deliveries) to find deliveries for the same event, including manual resends still available in the history. Each destination and resend has its own `delivery_id`. The existence of an event does not confirm delivery. It may have no selected destination, or its delivery may still be waiting. An HTTP `2xx` response in an attempt confirms only acceptance by the receiver, not subsequent processing in the destination system. ## Send to a webhook Use [Send an event to a webhook](/en/api/webhook-events/deliver) with `event_id` in the path and `webhook_id` in the body. You can choose a destination from the same company and environment, even if it has no previous delivery for this event. The event must have been created no more than 15 days ago, with its original body available. The webhook must be active and select the event type at the time of the request. The 30-day query period does not extend this eligibility. `webhook.test` events require [another test](/en/api/webhooks/test). The `202` response returns the original event and the new delivery identifier. Query that delivery to track the result. The delivery uses the current webhook URL and secrets and preserves the original body, including `id` and `created_at`. The request does not change the financial resource or cancel other deliveries for the same event. If the queue is paused, the new delivery waits for it to resume, with its own deadline of up to 72 hours in Production or four hours in Sandbox. Your receiver must recognize the same event across different deliveries to avoid repeating its effects. After an uncertain API response, query deliveries by `event_id` before making another request. ## History and environment Events remain available for 30 days from their original creation time. New attempts and resends do not restart this period. A delivery has its own history period, explained in [30-day history](/en/api/webhook-deliveries/overview#histórico-por-30-dias). Queries require [API-key or OAuth authentication](/en/integracoes/autenticacao) for the same company and environment. The console accepts Sandbox only. Records may take a few moments to appear; an empty list does not prove that a financial change did not occur. Query the charge or refund when you need to confirm its state. # Retrieve an event (/en/api/webhook-events/retrieve) Use the event UUID to retrieve its data and original JSON in `payload`. The query does not send another notification or change the financial resource. See [Query the original content](/en/api/webhook-events/overview#consultar-o-conteúdo-original) to interpret the response and find related deliveries. GET /v1/webhook_events/{event_id} # Create a webhook (/en/api/webhooks) Register a receiving URL and select the events your integration needs to follow. Keep the returned secret in a private application environment: configuration queries do not return this value. If the receiver is not ready yet, register it with `is_active: false`. See [Register a destination](/en/api/webhooks/overview#cadastrar-o-destino) and [Receive and validate events](/en/integracoes/webhooks/receber-eventos) before starting to receive notifications. POST /v1/webhooks # Delete a webhook (/en/api/webhooks/delete) Delete the specified registration to prevent new sends. Requests already authorized or in progress may still finish. See [Delete a destination](/en/api/webhooks/overview#excluir-um-destino). DELETE /v1/webhooks/{webhook_id} # List event types (/en/api/webhooks/event-types) Query available types before creating a webhook or changing its selection. Choose the events the integration needs to receive. See [Select events](/en/api/webhooks/overview#selecionar-os-eventos). GET /v1/webhook_event_types # Check webhook health (/en/api/webhooks/health) Query the destination's known health based on sending attempts. Times may appear with a delay; the request does not test the URL or confirm that the receiver is available now. See [Check destination health](/en/api/webhooks/overview#consultar-a-situação-do-destino) to interpret statuses and the duration of failures. GET /v1/webhooks/{webhook_id}/health # List webhooks (/en/api/webhooks/list) Query the registrations available to the credentials used in the request. The listing shows destination settings without returning the signing secret. See [Query and change settings](/en/api/webhooks/overview#consultar-e-alterar-a-configuração) and [Listing and pagination](/en/api/listagem-e-paginacao). GET /v1/webhooks # Webhooks (/en/api/webhooks/overview) Webhooks notify your application when an event happens in Raims, such as a charge payment or a completed refund. Register the address that will receive these notifications and select the events your system uses. The API lets you manage the same registrations shown in the [Dashboard](/en/integracoes/webhooks). Check receipt in your application's records and use destination health to track known failures. ## Complete your first integration 1. Prepare the receiver to [validate the signature and accept the event](/en/integracoes/webhooks/receber-eventos) before processing it. 2. Query the [event types](/en/api/webhooks/event-types) and select those your application will handle. 3. [Register the destination](/en/api/webhooks) in Sandbox with `is_active: false`. Keep the returned `id` and configure `secret_key` on the receiver's server. 4. [Activate the registration](/en/api/webhooks/update) and [request a test](/en/api/webhooks/test). Check receipt in your application's logs. 5. Use [Simulation](/en/api/simulations/overview) to generate the financial events your system needs to handle. Check the expected updates and duplicate handling. The technical event checks the path to the receiver and the signature. Financial tests check your application's response to events such as `charge.paid`. When preparing Production, use that environment's key, registration and secret. ## Register a destination Before [creating a webhook](/en/api/webhooks), prepare an HTTPS URL that accepts `POST` with JSON. Use a domain controlled by your company, with DNS that resolves to a public IPv4 address, on the default port `443`. The address cannot be localhost or a direct IP address, or contain a username or password. Provide a name that identifies the system and its purpose, the URL and the events you want to receive. Keep the `id` to manage the registration and `secret_key` to validate the signature. Later queries do not return the secret. The registration starts active. If the receiver is not ready yet, use `is_active: false` and activate it later with an update. The same URL cannot be registered twice for the key's company and environment. The receiver must validate each signature, recognize repeated deliveries and respond within the sending timeout. Follow [Receive and validate events](/en/integracoes/webhooks/receber-eventos) to implement this handling. If you restrict sources, allow the [official Raims IPs](/en/integracoes/webhooks/ips-oficiais). ## Select events [List event types](/en/api/webhooks/event-types) to get the codes available for registration. Provide these codes in `events` and keep at least one selected. Subscribing to an event does not create an occurrence; the notification depends on the corresponding change. Select only the events your system needs to process. The technical event `webhook.test` is sent by the test command and is not part of the registration's event selection. ## Query and change settings [List webhooks](/en/api/webhooks/list) or [query a registration](/en/api/webhooks/retrieve) by its `id`. Queries return the destination's settings and status, without the signing secret. To [update the registration](/en/api/webhooks/update), send only the fields you want to change, with at least one field in the request. Omitting a field keeps its current value. Changing the name, URL or events keeps the identifier and secret. Submitted fields must keep a valid value: `null`, empty names or URLs and an empty event list do not clear the settings. URL and event changes apply to subsequent event selections and sending attempts. Requests already authorized or in progress may finish with the previous settings. Adding a type may include earlier events that were still waiting to be prepared; the change does not resend deliveries that have ended. Old events that remain selected may be kept or removed, but can only be added again if they are in the current catalog. ## Check destination health [Check webhook health](/en/api/webhooks/health) to find out whether a failure episode is recorded. The response includes the available times for the episode's first and last failures, the last success and the update to this information. | `status` | Meaning | | ---------- | --------------------------------------------------------------------------- | | `healthy` | The known result is an HTTP `2xx` acceptance, with no open failure episode. | | `failing` | Failures have been recorded since the last episode ended. | | `disabled` | The registration is deactivated. | | `unknown` | No information is available to determine the status. | While the status is `failing`, `failure_duration_seconds` reports how long ago the episode started. Failure times refer to the moment their result was recorded; they are not the event's creation date. A delivery accepted with HTTP `2xx` ends the episode. Deactivation also ends it, so a deactivated destination may have no failure times. The information comes from sending attempts and may appear with a delay. `observed_at` reports the latest available update. The query does not test the URL or continuously monitor its availability. Use the [receipt test](/en/api/webhooks/test) when you need to check a new request; its result does not change the recorded health status. ## Pause and resume the queue [Pause the queue](/en/api/webhooks/pause) before maintaining your receiver. Send `is_paused: true` for an active webhook. Raims keeps pending deliveries and includes new selected events, but does not start sending them while the pause is active. An already authorized request may finish. A pause does not freeze or extend deadlines: financial deliveries remain limited to 72 hours in Production and four hours in Sandbox. A delivery whose deadline expires during the pause will not be sent when the queue resumes. After fixing or updating the receiver, send `is_paused: false` to the same endpoint. Resuming releases deliveries that are still valid, according to the existing sending limits. It does not guarantee immediate sending, a specific order or recovery of deliveries that have ended. Configuration queries report `is_paused` and `paused_at`. Pausing or resuming ends the previous failure episode. This does not confirm that the receiver has recovered; check your application's records after resuming. The pause is separate from `is_active`: the registration stays active and keeps its settings. The [technical test](/en/api/webhooks/test) can be requested during the pause to check the receiver before resuming the queue. It keeps one HTTP attempt and a five-minute deadline, without changing the registration's failure status. ## Deactivate and reactivate Use `is_active: false` in the update to deactivate the destination and `is_active: true` to reactivate it. The registration, secret and event selection are preserved. Deactivation prevents new sends. A pending delivery ends if its next attempt finds the destination deactivated. If reactivation happens first, the delivery may continue within the original deadline. Reactivation does not resend the history or recover deliveries that have ended. Failures do not pause or deactivate the destination automatically. Raims keeps trying each delivery within its [environment's limits](/en/integracoes/webhooks/receber-eventos#falhas-e-novas-tentativas-de-webhook). Changing the name, URL, events or secret does not reactivate a manually deactivated registration. For maintenance that preserves deliveries still within their deadlines, use [Pause and resume the queue](#pausar-e-retomar-a-fila). If the queue is paused, reactivating the registration keeps that pause. Resume the queue separately when the receiver is ready. `disabled_reason: manual` identifies manual deactivation. Registrations previously deactivated because of failures may keep `continuous_failure`; check and reactivate them when the receiver is ready. When the webhook is active, this field is `null`. ## Rotate the secret [Request rotation](/en/api/webhooks/rotate-secret) when you need to replace the signing secret. The webhook identifier stays the same. Keep the new `secret_key` and update the receiver. Configuration queries cannot retrieve this value. Prepare secure storage before requesting rotation. The transition period lets you receive signatures from both the new and previous secrets while your application is updated. By default, it lasts 24 hours. Use `grace_period_seconds: 0` if exposure is suspected or if you need to replace the secret immediately. New sends then use only the new secret as soon as rotation is confirmed. If a transition is active, it ends and both previous secrets are replaced. Requests already authorized or in progress may still arrive with a previous signature. Remove the old secrets from the receiver's configuration so they are no longer accepted. During the transition, repeating rotation with a period greater than zero returns the same new secret and the same deadline, without extending it. Check `previous_secret_expires_at` and accept any valid `v1` signature, as described in [signature validation](/en/integracoes/webhooks/receber-eventos#validar-a-assinatura). In the Dashboard, rotation always replaces the secret immediately. Choosing a transition period remains available through the API. ## Test receipt [Send a test event](/en/api/webhooks/test) to an active webhook. The request has no body and returns `event_id` and `delivery_id` to identify the event and its delivery. Acceptance of the request does not confirm that the receiver received it. The event has `type: webhook.test`, `data.object: webhook` and `data.id` containing the registration's identifier. It uses the webhook's URL and signature and makes a real HTTPS request. It does not create or change charges, payments, refunds or balances. The test makes one HTTP attempt, with up to five minutes to send. If it fails, fix the receiver before requesting another test. This test's result does not change the failure count or trigger automatic deactivation of the registration. Each new test request creates another event. To test again, use this same endpoint. To check financial event handling, use [Simulation](/en/api/simulations/overview) with a Sandbox key. Keep the effects of these tests separate from your application's production data. ## Delete a destination [Delete the webhook](/en/api/webhooks/delete) when it is no longer used. Deletion prevents new sends to that registration. Requests already authorized or in progress may still finish. First check whether any system depends on the destination. To stop receipt while keeping the settings, deactivate the registration. Existing records remain subject to the Dashboard query periods, but cannot be resent to a deleted registration. ## Company and environment All requests use [API-key or OAuth authentication](/en/integracoes/autenticacao). Access is limited to the authenticated company and environment. A Sandbox request manages only Sandbox webhooks; a Production request manages only Production webhooks. This documentation's console accepts only Sandbox keys. With OAuth, each request must be among the granted operations and remain allowed for the person who authorized the connection. Identity confirmations requested by the Dashboard belong to actions performed in that interface. Sandbox sends real HTTPS requests. Use a separate test destination and protect the secret on your application's server. Never send it to support or include it in screenshots, URLs or logs. # Pause or resume the queue (/en/api/webhooks/pause) Use `is_paused: true` to pause and `is_paused: false` to resume an active webhook's queue. The pause preserves pending deliveries and new events, but keeps their original deadlines. Already authorized requests may finish. See [Pause and resume the queue](/en/api/webhooks/overview#pausar-e-retomar-a-fila) for expiration during a pause and the behavior when resuming. PATCH /v1/webhooks/{webhook_id}/pause # Retrieve a webhook (/en/api/webhooks/retrieve) Query the webhook's URL, events and status using the identifier received during registration or in the listing. The query does not return the signing secret. See [Query and change settings](/en/api/webhooks/overview#consultar-e-alterar-a-configuração). GET /v1/webhooks/{webhook_id} # Rotate the secret (/en/api/webhooks/rotate-secret) Request a new secret for the same registration and update the receiver. Keep the returned value in a secrets vault; configuration queries cannot retrieve it. The transition period lets you update the receiver before sends start using only the new secret. If exposure is suspected, use `grace_period_seconds: 0` to replace the secret immediately, even while a transition is in progress. See [Rotate the secret](/en/api/webhooks/overview#rotacionar-o-segredo) to choose the transition period and validate signatures during the change. POST /v1/webhooks/{webhook_id}/rotate_secret # Send a test event (/en/api/webhooks/test) Request a technical event for the registered destination. The test makes a real HTTPS request, without creating a charge, payment or refund. Acceptance of the request returns the event and delivery identifiers, but does not confirm receipt or your system's handling of financial events. See [Test receipt](/en/api/webhooks/overview#testar-o-recebimento), then check the receiver records. POST /v1/webhooks/{webhook_id}/test # Update a webhook (/en/api/webhooks/update) Send at least one field to change the registration. Omitted fields keep their current values. Check the URL and events before confirming a change that affects receipt. See [Query and change settings](/en/api/webhooks/overview#consultar-e-alterar-a-configuração) and [Deactivate and reactivate](/en/api/webhooks/overview#desativar-e-reativar). PATCH /v1/webhooks/{webhook_id} # List withdrawals (/en/api/withdrawals) View your company withdrawals to track their progress and reconcile outflows from Raims with the destination account. You can filter by status and request date. This request does not request or cancel withdrawals. See [Withdrawals](/en/api/withdrawals/overview) to interpret the amounts and navigate the history. GET /v1/withdrawals # View automatic withdrawals (/en/api/withdrawals/automatic-settings) View the company daily withdrawal attempt settings. The response shows whether it is enabled, the minimum amount, the time and the next scheduled attempt. This request requires authorized Production access. See the conditions in [Automatic withdrawals](/en/api/withdrawals/overview#saque-automático). GET /v1/withdrawals/automatic_settings # List withdrawal destinations (/en/api/withdrawals/destinations) View the company destinations registered and verified for withdrawals. The list shows the masked Pix key and identifies the company default destination. This request requires authorized Production access. The console accepts only Sandbox. See [Withdrawal destinations](/en/api/withdrawals/overview#consultar-os-destinos-de-saque) to navigate the list and check the destination. GET /v1/withdrawal_destinations # Check withdrawal conditions (/en/api/withdrawals/limits) Check the current account conditions before requesting a withdrawal. The response shows the available balance, minimum amount, fee rule and, in Production, whether a destination is configured and the limits for the period. This request does not reserve balance or limits. See [Withdrawals](/en/api/withdrawals/overview#consultar-condições-e-limites) to interpret these values. GET /v1/withdrawals/limits # Withdrawals (/en/api/withdrawals/overview) Use the withdrawals API to withdraw funds from the Raims account through Pix and track the transfer to the company account. Queries help you plan the withdrawal and check the amount received at the destination. | Purpose | Method and path | | ---------------------------- | ------------------------------------------ | | Check conditions and limits | `GET /v1/withdrawals/limits` | | Request a Pix withdrawal | `POST /v1/withdrawals` | | View automatic withdrawals | `GET /v1/withdrawals/automatic_settings` | | Update automatic withdrawals | `PATCH /v1/withdrawals/automatic_settings` | | List withdrawal history | `GET /v1/withdrawals` | | Retrieve a withdrawal by ID | `GET /v1/withdrawals/{id}` | | List verified destinations | `GET /v1/withdrawal_destinations` | | Retrieve a destination by ID | `GET /v1/withdrawal_destinations/{id}` | ## Check conditions and limits Use [Check withdrawal conditions](/en/api/withdrawals/limits), with `GET /v1/withdrawals/limits`, before requesting a withdrawal. The response shows the available balance, minimum amount per withdrawal and fee for amounts below the stated threshold. The fee is deducted from the requested amount. Monetary values use Brazilian real cents. In Production, `destination_configured` indicates whether a destination is registered. The `limits` object shows the daily and nighttime limits, the current period limit, how much has been used and how much remains. The stated cap for a request considers withdrawal limits; the requested amount must also fit within the available balance and account for the fee. The daily period starts at 06:00 and ends at 06:00 the next day, in São Paulo time. From 20:00 to 06:00, the withdrawal must also fit within the nighttime limit, which is part of the daily limit. `period` identifies the current period and `period_ends_at` gives its end in Unix seconds in UTC. Processing withdrawals use up the limit; a confirmed failure releases the amount. This query does not reserve money or limits, or guarantee that a request will be accepted. Other withdrawals can change the conditions between the query and the request. Limits consider withdrawals recorded by Raims; transfers made through another channel on the same account can also affect the accepted amount. In Sandbox, the response shows the simulated balance and minimum and fee rules. `destination_configured` returns `false`, and `limits` returns `null`. These fields do not show the Production account destination or limits. In Production, `limits` can also return `null` when no limits are available to query. This does not mean the account can withdraw without limits. ## View withdrawal destinations Use [List withdrawal destinations](/en/api/withdrawals/destinations) to check the company own verified Pix keys. Each destination shows the holder name, institution ISPB, key type and masked key. `is_default` identifies the current default destination; `verified_at` gives the verification date in Unix seconds in UTC. The list requires authorized Production access. Sandbox returns `403 DATA_ENVIRONMENT_NOT_SUPPORTED` because it has no banking destinations. This documentation console accepts only Sandbox keys; query from your integration server without entering a Production key in the browser. Start without a cursor, process `list` and copy `page.next_after` to `after` while `page.has_next` is true. A page may have fewer items than `page_size` or be empty and still indicate another page. Continue using the cursor until `has_next` is `false`; do not use the size of `list` to end navigation. To go back, copy `page.previous_before` to `before`, without sending both cursors together. See [Listing and pagination](/en/api/listagem-e-paginacao). To check a specific destination, use [Retrieve a withdrawal destination](/en/api/withdrawals/retrieve-destination) and the complete returned `id`, with the `wdst_` prefix. This identifier belongs to the destination, whereas `wd_` identifies a withdrawal request. A removed destination or one no longer available to the company returns the same resource not found response. Querying a destination does not select it or request a transfer. To register a key, remove it or change the default, use **Account / Settings / Withdrawal Pix key**. The API request uses the default destination available at that time. To require the destination you checked to remain unchanged, send its `id` in `expected_destination_id`. This field does not select a different destination. Also check the conditions and limits before requesting the withdrawal; a destination's presence in the list does not guarantee acceptance. ## Request a Pix withdrawal Use [Request a withdrawal](/en/api/withdrawals/request), with `POST /v1/withdrawals`, and provide `amount_cents` with the total amount you want to withdraw, including the fee. The request requires a Production API key. The destination is the default Pix key registered in **Account / Settings / Withdrawal Pix key**. The key must belong to the same CNPJ as the company. Raims checks ownership when registering the destination and requesting a withdrawal. The API does not accept or change the destination Pix key. To register or change this key, use the Dashboard before requesting. The request depends on account withdrawal availability, available balance, the minimum amount and applicable limits. Having valid credentials does not remove these conditions. The optional `expected_destination_id` field binds the request to the company's own verified destination you queried. Copy the `id` of the item with `is_default: true`. If that destination changes or becomes invalid, the response is `409 WITHDRAWAL_DESTINATION_CHANGED`, without accepting the withdrawal to another destination. Check the default again and review the request before trying again. Omitting the field or sending `null` keeps the current default destination behavior. A `202` response means the withdrawal still needs to be tracked. Keep the returned `id` and query `GET /v1/withdrawals/{id}`. While the withdrawal is pending, processing or has an unknown result, track that same identifier before requesting another withdrawal. A `200` response can show the final result of a repeated request. If the response reports `PIX_WITHDRAWAL_RESULT_UNKNOWN`, use the path returned in the `Location` header to query the withdrawal before requesting another. For insufficient balance or limits, check conditions again. When the error indicates a missing or changed destination, check the default Pix key in the Dashboard. For the Dashboard flow, see [Pix withdrawals](/en/financeiro/saques). ## Automatic withdrawals Use [View automatic withdrawals](/en/api/withdrawals/automatic-settings) to read the settings and [Update automatic withdrawals](/en/api/withdrawals/update-automatic-settings) to enable, disable or adjust the daily attempt. Both endpoints require authorized Production access. The request uses an API key or OAuth session, without a confirmation code (OTP) for each request or a Dashboard cookie. Automatic withdrawals use the company destination selected in the Dashboard. Register and verify the company Pix key before enabling the setting. The API does not accept another Pix key or change the withdrawal destination. Send `enabled: true` to enable and `enabled: false` to disable. `minimum_amount_cents` is the minimum balance that allows an attempt, in Brazilian real cents. This field does not set a fixed amount for each withdrawal: the attempt considers available balance and the remaining Pix limit. If the limit allows only part of the balance to be withdrawn, the remainder stays in the account. `time` sets the daily time in `HH:mm`, in the São Paulo time zone. For example, `18:30` means 18:30 in São Paulo. Omitting a field preserves its current value; `null` is not accepted. Sending the same values again keeps the settings and the next scheduled attempt. Saving the settings does not request an immediate withdrawal. `next_execution_at` gives the next scheduled attempt in Unix seconds in UTC, or `null` when none is scheduled. That time does not confirm a withdrawal. Disabling automatic withdrawals prevents new attempts; track withdrawals already requested in the history. The attempt depends on the account being eligible to withdraw and the destination remaining valid. The available balance must reach the configured minimum, and the remaining limit must allow at least the minimum withdrawal amount. If any condition is unmet, no withdrawal occurs in that attempt. The same fee and limit rules as manual withdrawals apply. Track generated requests in [List withdrawals](/en/api/withdrawals) and check their `status`. Enabled settings or a scheduled next attempt do not prove a completed transfer. For Dashboard steps, see [Automatic withdrawals](/en/financeiro/saques-automaticos). ## View the withdrawal history Use [List withdrawals](/en/api/withdrawals), with `GET /v1/withdrawals`. You can filter by status and request date range. `requested_gte` and `requested_lte` use Unix seconds in UTC and include the specified instants. By default, newest withdrawals appear first. The response uses `list` and `page`. Start without a cursor, process `list` and copy `page.next_after` to `after` while `page.has_next` is true. Keep the filters, sorting and same key throughout navigation. To change the query, start again without a cursor. To go back, use `page.previous_before` in `before`. Copy the entire cursor without interpreting or changing its contents, and do not send both cursors together. See [Listing and pagination](/en/api/listagem-e-paginacao). ## Retrieve a withdrawal by ID Use [Retrieve a withdrawal](/en/api/withdrawals/retrieve), with `GET /v1/withdrawals/{id}`. Provide the complete `id`, with the `wd_` prefix, returned in the list. In the [Account statement](/en/api/statements/overview), an entry with `reference_type: 3` can provide that identifier in `reference_id`. Use it to query the related withdrawal and check its result. The withdrawal ID differs from the entry ID, which uses the `st_` prefix. ## Amounts and destination Amounts use Brazilian real cents: | Field | Meaning | | ------------------ | ---------------------------------------------------- | | `amount_cents` | Amount requested for withdrawal, including the fee. | | `fee_amount_cents` | Expected fee, charged when the withdrawal completes. | | `net_amount_cents` | Amount to transfer after deducting the fee. | For example, a withdrawal with `amount_cents: 10000` and `fee_amount_cents: 100` has `net_amount_cents: 9900`, equivalent to R$99.00 for the destination. These amounts do not confirm the transfer. Consider the withdrawal complete only when `status` is `COMPLETED`; failure or cancellation does not prove receipt or collection of the fee. `pix_destination` identifies the available Pix destination, with a masked key. `bank_account` shows available details of a bank account used in the withdrawal, also with a masked account number. These fields are `null` when details of that destination type are unavailable. Querying the history does not let you change the registered destination. ## Track the withdrawal status Check `status` before considering the withdrawal complete: | `status` | How to interpret it | | ------------ | ---------------------------------------------------------------------------------------------------- | | `PENDING` | The request awaits processing. | | `PROCESSING` | The withdrawal is processing and completion is not yet confirmed. | | `COMPLETED` | The withdrawal completed. | | `FAILED` | Failure was confirmed. Check `failure_reason`, when available. | | `CANCELED` | The request was canceled. | | `UNKNOWN` | No recognized status is available to display. Check the withdrawal before completing reconciliation. | `requested_at` shows when the withdrawal was requested. Completion, failure and cancellation dates are `null` until the corresponding result is recorded. All use Unix seconds in UTC. When a failure occurs, `failure_reason` gives a public code and a message in English. Use the code in integration handling. The message is for diagnostics; you do not need to compare its literal wording. See [Withdrawal failure reasons](/en/tipos-e-identificadores/financeiro#motivos-de-falha-do-saque) to understand each code and the checks indicated before another request. Repeated queries do not start or speed up a withdrawal. A pending or processing record does not prove that money reached the destination account. ## Company and environment Requests use [API-key or OAuth authentication](/en/integracoes/autenticacao) for the authorized company and environment. A Sandbox key does not access Production withdrawals. If there are no withdrawals in the queried environment, the list returns an empty `list`. Withdrawal requests are available only in Production; a Sandbox key lets you query simulated history and test conditions, but does not request a transfer. This documentation console accepts only Sandbox keys. The individual query returns the same resource not found response when the ID does not exist or does not belong to the authenticated company and environment. # Request a withdrawal (/en/api/withdrawals/request) Request a Pix withdrawal by providing the amount you want to withdraw. The destination is the company Pix key registered in the Dashboard. The fee is deducted from the requested amount. To require the default destination you checked, send `expected_destination_id`. The field does not register or select another destination. See [Request a Pix withdrawal](/en/api/withdrawals/overview#solicitar-um-saque-pix). Keep the returned identifier and track the same withdrawal while it is pending or processing. Acceptance does not confirm that the money reached the destination account. See [Withdrawals](/en/api/withdrawals/overview) for the conditions of use and how to track the result. POST /v1/withdrawals # Retrieve a withdrawal (/en/api/withdrawals/retrieve) View a withdrawal using the identifier returned in the list or in the reference of a statement entry. The response shows the amounts, available destination and current status for the authenticated company and environment. This request does not change the withdrawal or speed up completion. See [Withdrawals](/en/api/withdrawals/overview) to track the result. GET /v1/withdrawals/{id} # Retrieve a withdrawal destination (/en/api/withdrawals/retrieve-destination) View a withdrawal destination using the ID returned in the list. The response shows masked details and whether it is the current default. Use a Production key on your integration server. Registering and changing destinations is done in the Dashboard. See [Withdrawal destinations](/en/api/withdrawals/overview#consultar-os-destinos-de-saque). GET /v1/withdrawal_destinations/{id} # View withdrawals in progress (/en/api/withdrawals/summary) View the count and total amount of company withdrawals that are pending or processing. The response requires authorized Production access and does not confirm receipt in the destination account. See [Withdrawals in progress](/en/api/balances/overview#saques-em-processamento) to interpret the amounts. GET /v1/withdrawals/summary # Update automatic withdrawals (/en/api/withdrawals/update-automatic-settings) Configure the daily withdrawal attempt for the company destination selected in the Dashboard. Send only the fields you want to change. The request requires authorized Production access and does not ask for a confirmation code (OTP). Saving the settings does not request an immediate withdrawal. See [Automatic withdrawals](/en/api/withdrawals/overview#saque-automático) for amount, time and tracking rules. PATCH /v1/withdrawals/automatic_settings # Changelog (/en/changelog) # Raims updates in one place (/en/changelog/post/2026-10-28-changelog) The changelog brings together new features, improvements, and fixes across Raims products. Each post includes the date and description of the change, with links to the documentation for the products involved. Check each product's guides for its current conditions of use. In the [changelog](/en/changelog), filter updates by product or product group. Each post has its own link with the date and full description of the change. Use pagination to browse earlier posts. # Public API .NET SDK available on NuGet (/en/changelog/post/2026-10-29-sdk-dotnet) The official public API .NET SDK is available on NuGet as the `Raims` package. It supports x64 applications on .NET Framework 4.8/4.8.1 and .NET 10, with resource services, typed responses, pagination, and webhook verification. ```bash dotnet add package Raims ``` Keep the API key in the integration backend. The validated credential still determines company, environment, and permissions; the API's pending results and idempotency rules remain applicable. See the [.NET SDK guide](/en/integracoes/sdk-dotnet) to install, configure, and start the integration. # Direct installation and licenses for Raims CLI (/en/changelog/post/2026-10-30-raims-cli-direct) Raims CLI 0.1.1 provides installers for Windows x64, Linux (x64 and ARM64), and macOS (x64 and ARM64). Direct installation uses a user directory and lets you run the CLI by its full path without Node.js or npm. The installer shows a plan by default and only applies the installation with `-apply`. The 0.1.1 installer selects the latest stable patch in the 0.1 line. To install through npm, including CI, use `npm install -g @raimshq/cli@latest`. In a direct installation, an update can be downloaded silently and activated on the next eligible invocation. The running command keeps its version. You can disable updates or require an available version; preserve cached versions and backups. `raims licenses` shows the notices and licenses included in the running version without a profile or network access. `raims licenses --output json` returns the text and its SHA-256 hash. See [Direct installation](/en/cli/direct-installation), [CI and automation](/en/cli/automation#controlar-a-versão), and [Notices and licenses](/en/cli#consultar-avisos-e-licencas). # Raims CLI available on npm (/en/changelog/post/2026-10-30-raims-cli-npm) Raims CLI is available on npm as the `@raimshq/cli` package. The initial release is version `0.1.0`. You can also install this package with Yarn Classic, pnpm, or Bun. The [installation guide](/en/cli#instalar-pelo-npm) lists the commands and explains how to run the CLI on demand with Yarn 2 or later. It requires Node.js 22 or later and provides packages for Windows x64, Linux (x64 and ARM64), and macOS (x64 and ARM64). ```bash npm install -g @raimshq/cli@latest raims version ``` Use the commands to query and manage public API resources in your terminal or scripts. Configure a profile with the name of the environment variable that contains your API key. The profile does not store the key's value; the validated credential determines the company, environment, and permissions. Update through the same package manager you used to install it. The CLI does not automatically replace the version maintained by that manager. With npm: ```bash npm install -g @raimshq/cli@latest ``` See the [Raims CLI guide](/en/cli) to install and configure profiles, and the [command reference](/en/cli/reference) to choose the options for your integration. # Public API PHP SDK available on Packagist (/en/changelog/post/2026-10-30-sdk-php) The official public API PHP SDK can be installed through Composer as the `raims/raims-php` package. It requires PHP 8.2 or later on a 64-bit platform and provides resource services, typed responses, cursor pagination, and webhook signature verification. ```bash composer require raims/raims-php ``` Use the API key in the integration backend. The validated credential continues to determine company, environment, and permissions; the API's pending responses and idempotency rules still apply. See the [PHP SDK guide](/en/integracoes/sdk-php) to install, configure, and start the integration. # Browser sign-in for the CLI and MCP connections (/en/changelog/post/2026-10-31-oauth-cli-mcp) Raims CLI 0.1.3 lets you connect your account through the browser with OAuth. API key profiles remain available for scripts and automation. To install or update through npm, run `npm install -g @raimshq/cli@latest`. Then choose a profile and the environment to access: ```bash raims login --profile pessoal --environment sandbox ``` The browser opens the Raims sign-in and consent pages. Check the account, choose the permissions, and complete the security confirmation when prompted. Tokens are encrypted, with protection from your operating system's native vault. [Raims MCP](/en/integracoes/mcp) connects compatible AI applications to your account through `https://mcp.raims.com`, with OAuth and access to authorized operations. You do not need to copy an API key. For each data query or change, the application selects an environment allowed by the connection. In **Integration / Authorized applications**, you can view the connections your profile may see, edit access you are allowed to manage, and revoke access. The person's and account's current permissions continue to limit operations. The connection does not require another authorization screen for every task. See [CLI configuration](/en/cli/configuration), [Connect an MCP application](/en/integracoes/mcp), [Authorized applications](/en/integracoes/aplicativos), and [Account context](/en/api/accounts/context) to check the account and environment before using the granted access. # Raims CLI for Windows ARM64 (/en/changelog/post/2026-10-31-raims-cli-windows-arm64) Raims CLI 0.1.2 includes a native Windows ARM64 executable through npm and direct installation. To install or update through npm, use Node.js 22 or later for ARM64 and run `npm install -g @raimshq/cli@latest`. npm selects the executable using the Node.js architecture. The direct Windows ARM64 installer does not require Node.js and shows a plan before applying the installation with `-apply`. Direct installations keep the selected architecture when running the CLI and updating its versions. See [Install with npm](/en/cli#instalar-pelo-npm), [Direct installation](/en/cli/direct-installation), and [Check the architecture](/en/cli/diagnostics#conferir-a-arquitetura). # Detailed permissions for keys and applications (/en/changelog/post/2026-11-01-permissoes-integracoes) API keys let you select individual actions, such as viewing customers, creating charges, revoking them, and requesting refunds. Granting one action does not select the others automatically. You can edit permissions without replacing the secret, and each item has a description and a **Learn more** link. In **Authorized applications**, consent and permission editing use the same individual choices. Editing lets you remove and restore access from the original authorization; other operations require new consent. Account rules and the current permissions of the person who authorized access still apply. Creating a key requires identity confirmation before opening the form when there is no valid authorization. That authorization is reused when creating the key while it remains accepted. If confirmation is needed again when saving, creation continues with the completed form without another click. Employees can copy a Sandbox secret or rotate a key only when their access covers all actions granted to it. Raims CLI 0.1.4 and the documentation console also align environment selection with the authentication method. With an API key, the key determines the company and environment. With OAuth, the operation must accept the requested environment and the connection must authorize it. In the CLI, `--environment` is exclusive to OAuth; simulations remain restricted to Sandbox. To update the CLI through npm, run `npm install -g @raimshq/cli@latest`. See [API keys](/en/integracoes/chaves-api), [Authorized applications](/en/integracoes/aplicativos), and [Authentication](/en/integracoes/autenticacao) to review your integration's access. # Public API Delphi SDK source available on GitHub (/en/changelog/post/2026-11-01-sdk-delphi) The official public API Delphi SDK is available as [source code on GitHub](https://github.com/raimshq/raims-delphi/releases/latest). It provides services, parameters, and response models for backend use, with pagination and webhook signature verification. The [Delphi SDK guide](/en/integracoes/sdk-delphi) explains adding `src` to Search path or Library path, platform requirements, and ownership of returned objects. Compile the units on your application's target and check its requirements. Keep the API key in your backend, outside binaries distributed to customers. # Public API Elixir SDK available on GitHub (/en/changelog/post/2026-11-01-sdk-elixir) The official public API Elixir SDK is available on [GitHub](https://github.com/raimshq/raims-elixir/releases/latest). Applications using Elixir 1.18 or later and Erlang/OTP 27 or later can add it as a Mix Git dependency, with the selected revision recorded in `mix.lock`. The [Elixir SDK guide](/en/integracoes/sdk-elixir) covers installation, client setup, charge creation, pagination, and webhook verification. Keep the key in your backend; it determines the integration's environment, and financial simulations require a Sandbox key. # Public API Go SDK available (/en/changelog/post/2026-11-01-sdk-go) The official Go SDK connects server applications to the Raims public API through the `github.com/raimshq/raims-go` module. It requires Go 1.26.5 or later and provides typed services and responses, cursor pagination, and webhook authentication. ```bash go get github.com/raimshq/raims-go@latest ``` Keep the API key in the backend. The validated credential continues to determine company, environment, and permissions, with the API idempotency and pending-result rules. See the [Go SDK guide](/en/integracoes/sdk-go) to install, configure, and start the integration. # Public API Java SDK available on GitHub (/en/changelog/post/2026-11-01-sdk-java) The official public API Java SDK is available in [GitHub releases](https://github.com/raimshq/raims-java/releases/latest), with a JAR, POM, sources, and Javadoc. It requires Java 11 or later and provides typed builders and responses, cursor pagination, and webhook authentication. Download the current release artifacts before installing the JAR with its POM: ```bash mvn install:install-file -Dfile=raims-java-release/raims-java.jar -DpomFile=raims-java-release/raims-java.pom ``` Keep the API key in the backend. The validated credential continues to determine company, environment, and permissions, with the API idempotency and pending-result rules. See the [Java SDK guide](/en/integracoes/sdk-java) to install, configure, and start the integration. # Public API Node.js and TypeScript SDK available on GitHub (/en/changelog/post/2026-11-01-sdk-node) The official public API Node.js SDK is available as the `raims` package, with ESM and CommonJS modules and TypeScript declarations. It requires Node.js 22 or later and provides resource services, cursor pagination, and webhook authentication. Download `raims-node.tgz` from the [current stable release](https://github.com/raimshq/raims-node/releases/latest) before installing: ```bash npm install ./raims-node-release/raims-node.tgz ``` Keep the API key in the backend. The validated credential continues to determine company, environment, and permissions, with the API idempotency and pending-result rules. See the [Node.js SDK guide](/en/integracoes/sdk-node) to install, configure, and start the integration. # Public API Python SDK available on GitHub (/en/changelog/post/2026-11-01-sdk-python) The official public API Python SDK is available in [GitHub releases](https://github.com/raimshq/raims-python/releases/latest), with a wheel that can be installed through pip. It requires Python 3.10 or later and provides synchronous and asynchronous clients, typed responses, cursor pagination, and webhook authentication. Keep the API key in the backend. The validated credential continues to determine company, environment, and permissions, with the API idempotency and pending-result rules. See the [Python SDK guide](/en/integracoes/sdk-python) to install, configure, and start the integration. # Public API Ruby SDK available on GitHub (/en/changelog/post/2026-11-01-sdk-ruby) The official public API Ruby SDK is available through [GitHub releases](https://github.com/raimshq/raims-ruby/releases/latest), with a gem for local installation. It requires Ruby 3.3 or later and provides resource services, typed responses, cursor pagination, and webhook verification. See the [Ruby SDK guide](/en/integracoes/sdk-ruby) to download, install, configure credentials, and update the integration. Keep the API key in your backend; the validated credential still determines company, environment, and permissions. # Public API Rust SDK available on GitHub (/en/changelog/post/2026-11-01-sdk-rust) The official public API Rust SDK is available on [GitHub](https://github.com/raimshq/raims-rust/releases/latest), with source and a `.crate` archive. Integrations use Rust 1.90 or later and Tokio; Cargo can resolve the Git dependency and record its revision in `Cargo.lock`. See the [Rust SDK guide](/en/integracoes/sdk-rust) to install, configure the client, and use typed parameters, pagination, and webhooks. Keep the key in your backend. The API's idempotency rules and pending results still apply. # Public API Elixir SDK available on Hex (/en/changelog/post/2026-11-02-sdk-elixir-hex) The official public API Elixir SDK is available on Hex as the [`raims`](https://hex.pm/packages/raims) package. If Hex is not installed yet, install it once: ```bash mix local.hex ``` From your application project, check the current stable version's configuration: ```bash mix hex.info raims ``` Copy the `Config:` line into the dependency list in `deps/0` in `mix.exs`. Then fetch the dependencies and compile: ```bash mix deps.get mix compile ``` The SDK requires Elixir 1.18 or later with Erlang/OTP 27 or later and provides resource modules, response models, cursor pagination, and webhook verification. The `Raims` modules stay the same if you installed the SDK from GitHub. To migrate a Git or local dependency, replace the previous declaration with the current Hex configuration and run `mix deps.update raims`. Review and keep `mix.lock` and test your integration before updating the application. Keep your API key in the backend. The validated credential continues to determine company, environment, and permissions. Read the [Elixir SDK guide](/en/integracoes/sdk-elixir) to install, configure the client, and receive webhooks. # Public API Java SDK available on Maven Central (/en/changelog/post/2026-11-02-sdk-java-maven-central) The official public API Java SDK is available on Maven Central as [`com.raims:raims-java`](https://central.sonatype.com/artifact/com.raims/raims-java). Add the dependency through Maven or Gradle to resolve the SDK and its dependencies when building your application. The SDK requires Java 11 or later and provides typed builders and responses, cursor pagination, and webhook authentication. The coordinates stay the same if you installed the JAR with its POM from GitHub. Update the dependency version to the current stable version on Maven Central and test the flows used by your integration. Keep your API key in the backend. The validated credential continues to determine company, environment, and permissions. Read the [Java SDK guide](/en/integracoes/sdk-java) to install through Maven or Gradle, configure the client, and receive webhooks. # Public API Node.js and TypeScript SDK available on npm (/en/changelog/post/2026-11-02-sdk-node-npm) The official public API Node.js and TypeScript SDK is available on npm as the [`@raimshq/raims`](https://www.npmjs.com/package/@raimshq/raims) package. Install it from your application directory: ```bash npm install @raimshq/raims ``` The SDK requires Node.js 22 or later and includes ESM and CommonJS modules, TypeScript declarations, cursor pagination, and webhook authentication. Keep your API key in the backend. The validated credential continues to determine company, environment, and permissions. To update to the current stable version, use `npm install @raimshq/raims@latest` and test the flows used by your integration. If you used an earlier TGZ, replace the dependency and imports with the new package name. Read the [Node.js SDK guide](/en/integracoes/sdk-node) to configure the client, integrate resources, and receive webhooks. # Public API Python SDK available on PyPI (/en/changelog/post/2026-11-02-sdk-python-pypi) The official public API Python SDK is available on PyPI as the [`raims`](https://pypi.org/project/raims/) package. Install it in your application's virtual environment: ```bash python -m pip install raims ``` The SDK requires Python 3.10 or later and includes synchronous and asynchronous clients, typed parameters, cursor pagination, and webhook authentication. Keep your API key in the backend. The validated credential continues to determine company, environment, and permissions. To update to the current stable version, use `python -m pip install --upgrade raims` and test the flows used by your integration. The `raims` import stays the same if you installed from GitHub; update the dependency source if your application pins a Git URL or local wheel. Read the [Python SDK guide](/en/integracoes/sdk-python) to configure the client, integrate resources, and receive webhooks. # Public API Ruby SDK available on RubyGems (/en/changelog/post/2026-11-02-sdk-ruby-rubygems) The official public API Ruby SDK is available on RubyGems as the [`raims`](https://rubygems.org/gems/raims) gem. Install it in your application's environment: ```bash gem install raims ``` The SDK requires Ruby 3.3 or later and provides resource services, typed responses, cursor pagination, and webhook verification. The `require 'raims'` statement stays the same if you installed the gem from GitHub. For applications using Bundler, add `gem 'raims'` to `Gemfile` and run `bundle install`. To update an existing dependency, use `bundle update raims`; for installations managed directly through RubyGems, use `gem update raims`. Test the flows used by your integration before updating the application. Keep your API key in the backend. The validated credential continues to determine company, environment, and permissions. Read the [Ruby SDK guide](/en/integracoes/sdk-ruby) to install, configure the client, and receive webhooks. # Public API Rust SDK available on crates.io (/en/changelog/post/2026-11-02-sdk-rust-crates) The official public API Rust SDK is available on crates.io as the [`raims`](https://crates.io/crates/raims) crate. From your application project: ```bash cargo add raims cargo add tokio --features macros,rt-multi-thread ``` The SDK requires Rust 1.90 or later and a Tokio runtime. It provides typed services and responses, cursor pagination, and webhook verification for asynchronous backend integrations. Cargo records resolved versions in `Cargo.lock`. Keep that file and run `cargo update -p raims` to update within the declared requirement. Read the guide to refresh that requirement with the current stable version or migrate a Git or local dependency. Test your integration before updating the application. Keep the API key in your backend. The validated credential still determines company, environment, and permissions. Read the [Rust SDK guide](/en/integracoes/sdk-rust) to install, configure the client, and receive webhooks. # Checkout and payment methods (/en/checkout) The **Learn more** link appears in **Account / Settings / Payment checkout**, below the default payment methods. Viewing this section requires **View account settings**. **Edit checkout appearance** and **Edit payment methods** control their respective changes. Options also depend on account availability. ## Payment methods The methods enabled in this section form the account default. Checkout uses this default when the charge and link have no custom payment method configuration. Changing the default also changes the options for those charges. | Item | Type | Description | | --- | --- | --- | | Pix | Account default | Offers Pix when checkout uses the account default. | | Boleto | Account default | Offers boleto when checkout uses the account default. | **Custom link configuration** When a link is created with its own payment method configuration, that choice applies only to the link and does not change the account default. If the charge already has its own list, the link can only reduce its options. ## Charges created through an integration The [Create a charge](/en/api/charges) request accepts a custom list in `payment_method_types`: `[1]` for Pix, `[2]` for boleto, or `[1, 2]` for both. This list overrides the account default for that charge only, subject to platform availability. A custom link configuration can reduce its options. Omitting the list or sending `null` keeps the charge using the configuration applied by checkout. Without a custom list, `payment_method: 0` lets the payer choose, while `1` or `2` restricts the charge to the specified method. With a populated list, omit `payment_method` or send `0`. None of these options changes the account default. Without a custom list, `payment_method: 1` requests Pix and `payment_method: 2` requests boleto during creation, with details available for the integrator to show to the payer. Boleto uses the customer record and can complete missing address fields from the postal code (CEP). A list such as `payment_method_types: [1]` or `[2]` keeps issuance after the selection at checkout. See [Receive Pix details during creation](/en/api/charges/overview#receber-o-pix-na-criação) and [Receive boleto details during creation](/en/api/charges/overview#receber-o-boleto-na-criação). See [Payment methods](/en/meios-de-pagamento#códigos-na-api) for the codes and the difference between the registered method and the checkout selection. For customer registration, amount, due date, and optional email delivery of the link, see [Charges](/en/api/charges/overview). Use `create_checkout: true` when creating the charge to receive its link in `checkout_url`, even without an email request or return URL. The link belongs to that charge. To obtain or configure the link for an existing charge, see [Payment links](/en/api/payment-links/overview). The due date must be at least five minutes ahead of the current time when the API validates the request. Pix keeps the specified time; boleto uses the São Paulo date, including the same day. An expired checkout does not confirm the cancellation of a boleto already issued. ## Change the defaults ### Open the Payment methods tab Go to **Account / Settings / Payment checkout / Payment methods** with **Edit payment methods**. ### Set Pix and boleto Enable or disable Pix and boleto to set the defaults you want. At least one available method must remain enabled. To disable the only active method, enable another one first. ### Save and confirm Select **Save payment method** and wait for the success message before closing the section. **Card** may appear as **Unavailable**. A method shown in the interface should not be considered enabled for your operation when its control is disabled. ## Change the appearance 1. Go to **Account / Settings / Payment checkout / Appearance** with **Edit checkout appearance**. 2. Use **Upload logo** and **Upload icon** for your brand files. Follow the displayed formats, dimensions, and file size, and wait for the upload to finish. 3. Enter a **Customer support email** if you want to display a contact for your company at checkout. 4. Set the **Main color** and **Background color** in hexadecimal format. Use **Restore default colors** to return to the original palette. 5. Check the **Checkout preview** in mobile or desktop mode and select **Save identity**. The preview lets you review the appearance; it does not create or pay a charge. Changes should be considered saved only after confirmation. ## Guide someone who received a link The payer opens the link shared by the company and checks the charge details and available methods. For Pix, they use the QR Code or payment code shown; for boleto, they use the document or payment line provided. Confirmation depends on the status shown at checkout and on the charge. When the link has a valid HTTPS **Cancel URL** accepted by Raims, checkout shows the **Back to website** arrow beside the brand. Selecting this arrow opens the address configured by the company. It does not cancel the charge, Pix, or boleto, and does not confirm payment. Without a valid return address, the arrow does not appear. Closing the tab does not trigger this return automatically. The arrow appears during the checkout details and payment steps; it does not appear on a receipt or an invalid link. With a valid HTTPS **Success URL** accepted by Raims, checkout may try to open that address automatically when it receives confirmation that the charge has been paid. This attempt requires the same open checkout to have been tracking the payment before confirmation and to remain valid for that tracking. Raims allows at most one automatic attempt per charge, even when it is open in multiple tabs or devices. Reloading or reopening a paid charge and viewing the invoice or receipt directly do not start or repeat this return. If the payer chooses **Back to website** or views the invoice or receipt while waiting for the return, automatic navigation does not resume. Generating Pix details, issuing a boleto, or showing a payment as processing does not confirm that the charge has been paid. Failure, cancellation, and refunds do not trigger this return either. Without a valid success URL, checkout does not use the cancel URL as an automatic destination. The return attempt does not guarantee arrival at the website: closing the tab or losing the connection may interrupt navigation. Use the confirmed charge status to check payment; a visit to the success URL does not replace that confirmation. A Sandbox link indicates a test and must not be presented as a real payment. If checkout reports that the link was not found or is unavailable, check that you opened the full address sent by the company without changing any part of it. If the message persists, ask the company that issued the charge to check the link. The message does not explain why the link is unavailable and does not establish whether the link was paused, the charge was cancelled, or payment occurred. # Raims CLI (/en/cli) Use `raims` in your terminal to query and manage public API resources, such as customers, charges, payment links, withdrawals, and webhooks. The commands also work in scripts and pipelines, with JSON output and defined exit codes. Connect your account through your browser with OAuth or use an API key for scripts and integrations. Both modes send requests to `https://api.raims.com`. The API checks the company, environment, permissions, and resource conditions. ## Install **Node.js is required** To use the CLI through a package manager, install [Node.js 22 or later](https://nodejs.org/en/download) and check the version with `node --version`. Without Node.js available in your terminal, the `raims` command cannot start. After installing Node.js, reopen your terminal. Packages are provided for Windows (x64 and ARM64), Linux (x64 and ARM64), and macOS (x64 and ARM64). On Windows ARM64, use ARM64 Node.js to install and run the native CLI. Choose your preferred package manager and install the CLI globally: ### npm ```bash npm install -g @raimshq/cli@latest ``` ### yarn ```bash yarn global add @raimshq/cli@latest ``` ### pnpm ```bash pnpm add -g @raimshq/cli@latest ``` ### bun ```bash bun add -g @raimshq/cli@latest ``` After installing the CLI, run `raims version` to check the version. The yarn tab uses Yarn Classic (1.x). With Yarn 2 or later, run `yarn dlx @raimshq/cli@latest version`; replace `version` with the command you want to run. This runs the CLI on demand without a global installation. npm selects the executable using the Node.js architecture. If needed, check the [installation architecture](/en/cli/diagnostics#conferir-a-arquitetura). Installation and updates need internet access to obtain the package. API commands need access to `api.raims.com`; reading guides needs access to `docs.raims.com`, except when explicitly reading the cache with `--offline`. Help, the command map, local profiles, and `doctor` do not require a network. To update or remove the CLI, use the same package manager you installed it with: ### npm ```bash npm install -g @raimshq/cli@latest npm uninstall -g @raimshq/cli ``` ### yarn ```bash yarn global add @raimshq/cli@latest yarn global remove @raimshq/cli ``` ### pnpm ```bash pnpm add -g @raimshq/cli@latest pnpm remove -g @raimshq/cli ``` ### bun ```bash bun add -g @raimshq/cli@latest bun remove -g @raimshq/cli ``` In pipelines, fetch the current version during installation as described in [CI and automation](/en/cli/automation#controlar-a-versão). Package-manager installations follow their manager's update mechanism and do not enable the direct installer's updater. [Direct installation](/en/cli/direct-installation) provides the native executable with updates managed by the CLI. ## Discover commands Use `raims --map` to see the complete command tree with a description of each command. Specify a group to narrow the result: ```bash raims --map raims charges --map=compact raims --map=paths raims --map=json ``` `compact` omits descriptions, `paths` lists full command paths, and `json` returns the structured tree. The map does not require a profile, key, or body, and it does not execute the displayed commands. To prepare a request, add `--help` to the command. For commands with a JSON body, help shows fields, types, required fields, nullable fields, and accepted values. Invocation examples use `--dry-run`; replace placeholders and review the file before sending it. Body examples, when present, come from the public API reference. Help rearranges its columns to fit the terminal width. Command and JSON examples keep their content so you can copy them; these lines may extend beyond the available width. In files and pipes, help keeps its original layout. ## First commands ### Read the help ```bash raims --help ``` Add `--help` to a command to see its arguments and options. ### Connect your account ```bash raims login --profile pessoal --environment sandbox ``` Complete sign-in and authorization in your browser. Check the account, environments, and permissions before authorizing **Raims CLI**. The profile uses the environment chosen at sign-in. For API-key automation, follow [Configuration and profiles](/en/cli/configuration). ### Check API access ```bash raims --profile pessoal auth check ``` The command reads account fees without changing settings. Success confirms access to this endpoint; other endpoints keep their own permissions and conditions. ### Query a resource ```bash raims --profile pessoal --output json customers list --page-size 20 ``` The result contains the HTTP status in `status_code`, the attempt identifier in `request_id` and the API response in `data`. Use `--help` to look up filters, arguments, and options. ### Check the configuration ```bash raims doctor ``` The diagnostic checks configuration, local permissions, installation, and the update policy. Create and update commands read the JSON body through `--data-file` or the simple field flags listed in `--help`. See [CI and automation](/en/cli/automation) to send files, read multiple pages, and handle pending results or failures. The `simulations` group runs simulations allowed by the API for the credential and resource. ## Read notices and licenses Starting with version `0.1.1`, `raims licenses` reads the third-party notices, licenses, and terms included in the running version: ```bash raims licenses raims licenses --output json ``` This is a local read that does not require a profile, key, or network access. The JSON output contains the text in `text` and its SHA-256 hash in `sha256`. ## Read guides in the terminal Use `raims docs search` to find guidance in the public documentation: ```bash raims docs search "webhooks" raims docs search "API keys" --language en --limit 5 ``` To read a guide, provide its website path. Without a path, `raims docs` shows the CLI guide: ```bash raims docs /br/integracoes/webhooks raims docs /en/cli --language en ``` These commands do not require a profile or key. Search uses public Raims content and supports `--output json`. `--language br|en` selects the language; Portuguese is the default. The path must match the selected language. External URLs and local file paths are not accepted. Content is cached for 24 hours. Use `--refresh` to fetch the latest version or `--offline` to use only cached content, including old content. The result reports the source and age of the content. Without a cache, `--offline` returns an error. The two options cannot be combined; a failed refresh does not silently fall back to an old copy. ## Open official pages `raims open` lists shortcuts for the documentation, API reference, Dashboard, API keys, webhooks, and Raims status. To open the CLI documentation: ```bash raims open docs ``` The destinations are fixed, and the command does not accept another URL. In CI, with `--no-input`, or without a terminal, it prints the address without starting a browser. Use `--output json` to receive `target`, `url`, and `opened`. ## Choose your path - [Direct installation](/en/cli/direct-installation): Choose the installer, review the plan, and control updates. - [Configuration and profiles](/en/cli/configuration): Create profiles and choose which one to use for each invocation. - [CI and automation](/en/cli/automation): Capture JSON results, handle failures, and control the version in scripts. - [Diagnostics](/en/cli/diagnostics): Check your installation and investigate problems with the doctor command. - [Command reference](/en/cli/reference): Look up executable syntax, arguments, and options. ## Profiles and credentials A profile can use an OAuth session or an API key. With OAuth, sign-in happens in your browser and the session is protected by the operating system's secure store. For scripts, associate an environment variable with your API key; the profile file stores only the variable name. See [Configuration and profiles](/en/cli/configuration) to connect, check access, select the environment, and sign out. For integration credentials, see [API keys](/en/integracoes/chaves-api) and [Authentication](/en/integracoes/autenticacao). # CI and automation (/en/cli/automation) In scripts and pipelines, select a profile explicitly and use JSON output to interpret results. Inject credentials through your environment's secret manager and keep their values out of logs. Use API-key profiles in pipelines: set the key variable through your secret manager and associate its name with `raims profile set`. OAuth sign-in needs a person in the browser and an available secure store. A request or `--no-input` does not start sign-in automatically. ## Run without interaction Use `--no-input` to prevent prompts during execution: ```bash raims --no-input --profile sandbox --output json accounts fees ``` The CLI also uses non-interactive execution when it detects a CI environment or when its input is not a terminal. A command that requires missing input returns an error instead of waiting for an answer in the terminal. The profile must exist in the configuration of the user running the process. See [Configuration and profiles](/en/cli/configuration) to prepare that configuration and the variable associated with the key. ## Capture output `--output json`, or `-o json`, selects JSON for commands that return data. Standard output (`stdout`) contains the result; errors and diagnostic output use standard error (`stderr`). Help and completion scripts keep their own formats. ```bash raims --no-input --output json version ``` API commands return an object with `status_code`, `request_id` and `data`. The first two fields preserve the HTTP status and attempt identifier; `data` contains the JSON response. HTTP 204 returns `data: null`. HTTP 202 indicates a pending result: the command does not wait for completion. Query the resource identified in the response before repeating a create, update, cancellation, or refund request. Use `--debug` to investigate an invocation. It adds diagnostic output to `stderr` as one JSON event per line, keeping the result on `stdout`. Events omit free-form arguments and credential values. Before sharing a captured file, review local paths and names that may identify your environment. API responses can contain account data and secrets, such as those returned when creating or rotating a webhook. Protect files and logs that capture `stdout`; hiding credentials in debug events does not remove data from the requested response. ## Inspect response headers Use `--show-headers` on API commands to include the public headers available in the response: ```bash raims --profile sandbox --output json accounts fees --show-headers ``` On success, JSON adds `response_headers`; on failure, it adds `error.response_headers`. Without the option, the default format stays the same. With `--all`, each page keeps its own headers. The property is omitted when no allowed metadata is available. The selection contains `Request-Id`, `X-Request-Id`, `Idempotency-Replayed`, `Retry-After`, and `Raims-Rate-Limited-Reason` when present and valid. This lets you check an idempotent replay or the wait time provided by the API. Credentials, cookies, and other headers are excluded. The option does not change the request result or retry policy. Text errors also show the attempt identifier, field details, wait time, and rate limit reason when available. Exit codes remain the same. ## Control terminal colors In text mode, the CLI uses colors for help, JSON fields, statuses, and error messages. `--color auto` is the default: each output uses colors when connected to a compatible terminal and allowed by the environment. To disable colors for an invocation: ```bash raims --color off doctor ``` `--color on` forces colors in text output, including files and pipes. `on` and `off` take precedence over environment variables. In `auto`, a non-empty `NO_COLOR` disables colors. Next, a non-empty `CLICOLOR_FORCE` other than `0` forces colors. Otherwise, `CLICOLOR=0`, CI, or `TERM=dumb` disable colors. The CLI evaluates stdout and stderr separately. `--output json`, JSONL events from `--debug`, and completion scripts always exclude ANSI codes, even with `--color on`. Colors do not change values, HTTP statuses, or exit codes. ## Send a JSON body Use `--data-file PATH` for commands that accept a body. Prepare a UTF-8 file with the fields described in the API reference. For example, to edit a charge's text fields: ```json title="charge-update.json" { "title": "Pedido de integração", "description": null } ``` ```bash raims --profile sandbox --output json charges update CHARGE_ID --data-file charge-update.json ``` Replace `CHARGE_ID` with a charge ID in the key's company and environment. In this PATCH, `description: null` clears the description, while omitting a field preserves its value. The CLI validates the input and sends the JSON without converting integers or replacing omission with `null`. Each field follows its endpoint's rules. The CLI body limit is 8 MiB. `--data-file -` reads JSON from `stdin`, including in CI and with `--no-input`. This option receives pipeline data without prompting in the terminal. ## Use flags for simple fields Commands with a body offer flags for top-level scalar fields, derived from API names. For example, `tax_id` becomes `--tax-id`: ```bash raims customers create --tax-id 12345678909 --full-name "Cliente de teste" --dry-run ``` Check `--help` for the flags supported by each command. Strings, integers, numbers, and booleans keep their types; `0`, `false`, and empty strings are sent when explicitly supplied. An omitted flag does not send the field or apply the default value shown in help. Use `--body-null FIELD` to send `null` for a field with a flag that accepts it. Supply the JSON field name and repeat the option for additional fields: ```bash raims charges update CHARGE_ID --title "Pedido revisado" --body-null description --dry-run ``` Do not supply both a value and `--body-null` for the same field. Body flags cannot be combined with `--data-file`, including when it reads stdin. Objects without dedicated options, arrays of objects, and fields without a flag still use a JSON file or stdin. Endpoint validation and rules remain the same. ## Send lists with flags Repeat a list flag to send its items in the supplied order. For example, to preview a webhook registration with two event types: ```bash raims webhooks create --name "Pedidos pagos" --url https://webhooks.example.com/raims --events charge.paid --events refund.completed --dry-run ``` The same format supports `--payment-method-types` for charges and payment links and `--identifiers` for batch customer deletion. Each occurrence adds one item; commas do not separate values. Types, accepted values, item counts, and duplicate handling follow the endpoint. Omitting the flag keeps the field omitted. For lists that accept `null`, use the JSON name with `--body-null`, such as `--body-null payment_method_types`. These commands require at least one item in a supplied list; sending `[]` through a file is also invalid. Do not supply both values and `null` for the same list, or combine body flags with `--data-file`. ## Send metadata with flags When creating or updating customers and charges, repeat `--metadata KEY=VALUE` to associate information from your system with the resource: ```bash raims customers update CUSTOMER_ID --metadata pedido=123 --metadata origem=site --dry-run ``` Replace `CUSTOMER_ID` with the customer ID. Values are always strings: `pedido=123` sends `"123"`, and `observacao=null` sends the string `"null"`. The first `=` separates the key from its value; subsequent ones are part of the string. `--metadata observacao=` sends an empty string. Dots in keys are literal and do not create nested objects. | Intent | Option | | ------------------------------------------------------ | ---------------------- | | Add or replace a key | `--metadata key=value` | | Remove a key in a PATCH | `--metadata-null key` | | Send an empty map, preserving existing data in a PATCH | `--metadata-empty` | | Clear the entire map | `--body-null metadata` | Omitting these options keeps `metadata` omitted. Do not repeat a key or combine a value with `--metadata-null` for the same key. Empty-map and clear-map options cannot be combined with values or individual removals. Body flags remain mutually exclusive with `--data-file`. The map accepts up to 32 keys, each with 1 to 40 characters. Use unaccented letters, numbers, dots, hyphens, or underscores. Values accept up to 500 characters, and the entire map has an 8 KiB limit. See the [customer](/en/api/customers/overview) and [charge](/en/api/charges/overview) guides for resource rules. ## Upload a logo and favicon Use `--upload-file PATH` with a logo or favicon preparation command to read the image metadata and upload its contents: ```bash raims --profile sandbox accounts checkout-settings logo-uploads create --upload-file logo.png raims --profile sandbox accounts checkout-settings favicon-uploads create --upload-file favicon.png ``` The file must be PNG or JPEG, up to 512 KiB. Logos accept 128 to 2048 pixels in each dimension. Favicons must be square, with sides of 128 to 512 pixels. The CLI reads a local file; this option does not accept stdin. Do not combine `--upload-file` with `--data-file` or body field flags: the type, size, and dimensions come from the file itself. To check the image and metadata before preparing an upload: ```bash raims accounts checkout-settings logo-uploads create --upload-file logo.png --dry-run ``` The preview reads and validates the image without using a profile, key, or network. A real execution prepares the upload through the API and sends the bytes with PUT to the temporary URL, without sending the Raims key to that destination. The returned `expires_at` limits the upload; `--timeout` also applies to each request. Requests are not retried automatically. The result keeps the API data in `data` and adds `upload.bytes` when the file is uploaded. To change the checkout image, use the returned `data.id` with `--logo-upload-id` or `--favicon-upload-id` on `raims accounts checkout-settings update`. Check the result with `raims accounts checkout-settings get`; application may still be pending. Uploading the file alone does not change the appearance. If sending the bytes fails, the image will not be applied. Prepare a new upload before trying again. Without `--upload-file`, the commands keep accepting JSON metadata and returning instructions for you to send the file. ## Save boletos and receipts Add `--save PATH` to save the PDF returned by a boleto, payment receipt, or refund receipt lookup: ```bash raims --profile sandbox charges boleto CHARGE_ID --save boleto.pdf raims --profile sandbox charges receipt CHARGE_ID --save pagamento.pdf raims --profile sandbox refunds receipt REFUND_ID --save estorno.pdf ``` The destination directory must exist. The CLI does not overwrite an existing file and only makes the destination available after receiving the entire file and checking its format. Without `--save`, the command keeps returning the document's metadata and temporary URL. With the option, the result adds `download`, containing `path` and `bytes`. The limit is 32 MiB. `--timeout` also limits the download request. `--save` cannot be combined with `--dry-run`. Saving a boleto does not confirm payment; Sandbox documents still identify a simulation. ## Preview a request without sending it Add `--dry-run` to an API command to validate and display the request without sending it: ```bash raims --no-input --output json customers list --page-size 20 --dry-run ``` The preview does not read configuration, a profile, or a key. It does not call the API or activate updates. The JSON result contains `dry_run`, `method`, `url`, `headers`, and `body` when present. `Authorization` is not included. For commands with a body, supply a file or the field flags supported by the command. Input goes through the same field and type validation. The preview can contain personal or financial data from the body; protect its output as you would protect the original file. Do not combine `--dry-run` with `--all`, because later pages depend on cursors returned by the API. ## Read multiple pages By default, a list command reads one page. Use `--page-size` to request a size and check `--help` for the command's filters. Query options use hyphens, such as `--page-size`, while responses keep the API's JSON field names. To read the following pages: ```bash raims --no-input --profile sandbox --output json customers list --all --max-pages 100 ``` With `--all --output json`, `stdout` uses JSON Lines: each line is an object with `status_code`, `request_id` and `data`, containing `list` and `page` for that page. The output is not a single array. The CLI preserves filters, sorting, and page size while advancing through the cursors returned by the API. `--max-pages` requires `--all`, accepts 1 to 10,000, and defaults to 100. If the limit is reached with more results available, the command returns `API_PAGE_LIMIT_REACHED`. To continue, copy `data.page.next_after` from the last page into `--after`, keeping the same filters. Copy the whole cursor without calculating or interpreting its content. Do not combine `--after` and `--before`. A query started with `--before` traverses backward and continues through `data.page.previous_before`. A network failure, cancellation, or page limit can occur after pages have been emitted. Check the exit code and treat earlier results as partial when the traversal ends with an error. ## Handle failures Check the process exit code before interpreting the result: | Exit code | Meaning | | --------- | ----------------------------------------------------------------------- | | `0` | Command completed. | | `1` | Internal failure. | | `2` | Invalid argument, option, or usage. | | `3` | Configuration failure, diagnostic error, or unavailable pinned version. | | `4` | Authentication or authorization failure. | | `5` | Network failure or timeout. | | `6` | An API error or an error in the received response. | | `130` | Execution canceled. | With `--output json`, a failure produces one object on a single line in `stderr`: ```json { "error": { "code": "PROFILE_NOT_FOUND", "message": "The selected profile does not exist. Run 'raims profile list'.", "kind": "config" }, "exit_code": 3 } ``` Use `error.code` and the exit code to decide how the automation should proceed. `error.message` is for human diagnosis and its wording may improve. When available, `error.status_code` and `error.request_id` identify the HTTP status and request. Validation errors can include `error.details`, with `field`, `code`, and `message`. Limits can include `error.retry_after_seconds` and `error.rate_limit_reason`. Use codes and fields to decide what to do, respecting the reported wait before trying again. With `--output json` and `--debug` together, each line in `stderr` is a separate JSON object. In text mode, debug events remain JSON lines and the error message uses text formatting. Failures before the first result leave `stdout` empty. `doctor` can print its report and exit with `3`; list commands using `--all` can emit pages before an error. `--timeout` defaults to 60 seconds per request, including retries and waits; for example, `--timeout 30s` reduces that deadline. With `--all`, the deadline applies to each page. Reads can retry transient failures up to three attempts, respecting the deadline and `Retry-After`. Writes are not retried automatically. A local timeout or cancellation does not undo a request accepted by the API; query the resource before sending another write. ## Control the version Fetch the current version through npm during the pipeline's installation step: ```bash npm install -g @raimshq/cli@latest raims --no-input --output json version ``` Run the installation with `@latest` on each run that should use the current published version. The `version` command reports which version will be used. A completed installation stays on the same version until you update through the package manager; the tag does not enable future automatic updates. In CI, that installation step handles updates. If `RAIMS_CLI_PIN_VERSION` is set, it requires the specified version to be already installed or retained by the CLI and can prevent an update from being used. To follow the current version, remove that pin from the automation configuration. The variable does not download versions. ### Select an available direct-installation version The `0.1.2` direct installer selects the latest stable patch in the `0.1` line; its name does not pin the installed version. npm installation examples also use `@latest` to resolve the current version. Automatic updates require a direct installation with a signed package and a configured distribution channel. Run `raims update status` to check your installation's policy. CI environments disable automatic checks and activation. To require the version selected in your direct installation, derive `RAIMS_CLI_PIN_VERSION` from the running version. These examples use the default destination; adjust the path if you installed elsewhere: ### PowerShell ```powershell $cliExecutable = "$env:LOCALAPPDATA\Raims\CLI\raims.exe" $cliBuild = & $cliExecutable --no-input --output json version | ConvertFrom-Json if ($LASTEXITCODE -eq 0 -and $cliBuild.version) { $env:RAIMS_CLI_PIN_VERSION = $cliBuild.version & $cliExecutable --no-input --output json version } ``` ### Bash and Zsh ```bash cli_executable="$HOME/.local/share/raims/cli/raims" installed_version="$("$cli_executable" --no-input --color off version | awk 'NR == 1 { print $2; exit }')" test -n "$installed_version" && export RAIMS_CLI_PIN_VERSION="$installed_version" && "$cli_executable" --no-input --output json version ``` The pin requires a version already installed or retained by the CLI; it does not download another version. If that version is unavailable, execution returns an error. Setting the pin does not install a version or turn `@latest` into a pinned installation for future runs. The pin applies to commands such as `version` and profile commands. To investigate an unavailable pinned version, `doctor`, `update status`, help, completion, `open`, and previews using `--dry-run` remain accessible. These inspection commands preserve the installed version without checking for, downloading, or activating updates. `raims licenses` also remains accessible when the pinned version is unavailable. It only reads the texts included in the executable being used. `RAIMS_CLI_NO_UPDATE=1` disables checks and activation of pending updates, preserving the version already active. Installations maintained by a package manager follow that manager's update mechanism. Inspect your installation's policy with: ```bash raims --output json update status ``` In a [direct installation](/en/cli/direct-installation), an update can be downloaded silently during use and activated on the next eligible invocation. The running command keeps its version. Preserve cached versions, the original installation, and backups; that history is not automatically cleaned up. # raims accounts (/en/cli/commands/accounts) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims accounts` Inspect account details and configure checkout appearance ```bash raims accounts [flags] ``` * `--help`, `-h` bool default: false * help for accounts **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims accounts account-number`](#raims-accounts-account-number), [`raims accounts checkout-settings`](#raims-accounts-checkout-settings), [`raims accounts context`](#raims-accounts-context), [`raims accounts fees`](#raims-accounts-fees). ### `raims accounts account-number` Get the account number ```bash raims accounts account-number [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for account-number * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get the account number. GET /v1/accounts/account_number Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. ``` **Command example** ```bash raims --profile PROFILE --output json accounts account-number --dry-run ``` ### `raims accounts checkout-settings` Manage checkout appearance settings and prepared image uploads ```bash raims accounts checkout-settings [flags] ``` * `--help`, `-h` bool default: false * help for checkout-settings **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims accounts checkout-settings favicon-uploads`](#raims-accounts-checkout-settings-favicon-uploads), [`raims accounts checkout-settings get`](#raims-accounts-checkout-settings-get), [`raims accounts checkout-settings logo-uploads`](#raims-accounts-checkout-settings-logo-uploads), [`raims accounts checkout-settings update`](#raims-accounts-checkout-settings-update), [`raims accounts checkout-settings uploads`](#raims-accounts-checkout-settings-uploads). #### `raims accounts checkout-settings favicon-uploads` Prepare checkout favicon uploads ```bash raims accounts checkout-settings favicon-uploads [flags] ``` * `--help`, `-h` bool default: false * help for favicon-uploads **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims accounts checkout-settings favicon-uploads create`](#raims-accounts-checkout-settings-favicon-uploads-create). ##### `raims accounts checkout-settings favicon-uploads create` Prepare a checkout favicon upload ```bash raims accounts checkout-settings favicon-uploads create [flags] ``` * `--content-type` string default: empty * Set JSON body field content\_type (string, required in the body) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--file-size` integer default: 0 * Set JSON body field file\_size (integer, required in the body) * `--height` integer default: 0 * Set JSON body field height (integer, required in the body) * `--help`, `-h` bool default: false * help for create * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) * `--upload-file` string default: empty * Prepare and upload a local PNG or JPEG; cannot be combined with JSON body options and does not apply the image to checkout * `--width` integer default: 0 * Set JSON body field width (integer, required in the body) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Prepare a checkout favicon upload. POST /v1/accounts/checkout_settings/favicon_uploads Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: content_type string required; allowed: "image/png", "image/jpeg" file_size integer required height integer required width integer required Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "content_type": "image/png", "file_size": 4567, "width": 128, "height": 128 } Example values are illustrative. Replace resource IDs and review the request before sending it. Without --upload-file, this operation prepares an upload using JSON metadata and returns the API's upload instructions. Use --upload-file PATH to read a PNG or JPEG, prepare its metadata and upload its bytes. Do not combine it with --data-file or body options. With --dry-run, the file is validated locally and only the metadata request is previewed. Uploading does not apply the image: update checkout settings with the returned upload ID in a separate request. With --upload-file, image metadata is read from the same bytes that are uploaded. The file must be PNG or JPEG, up to 524288 bytes, with width 128..512 pixels and height 128..512 pixels. The favicon must be square. --dry-run validates the local file and previews only the preparation request; it does not upload bytes. Apply the returned upload ID separately to change the checkout image. ``` **Command example** ```bash raims --profile PROFILE --output json accounts checkout-settings favicon-uploads create --data-file request.json --dry-run raims accounts checkout-settings favicon-uploads create --content-type="image/png" --file-size=4567 --height=128 --width=128 --dry-run raims accounts checkout-settings favicon-uploads create --upload-file image.png --dry-run ``` #### `raims accounts checkout-settings get` Get checkout appearance settings ```bash raims accounts checkout-settings get [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for get * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get checkout appearance settings. GET /v1/accounts/checkout_settings Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json accounts checkout-settings get --dry-run ``` #### `raims accounts checkout-settings logo-uploads` Prepare checkout logo uploads ```bash raims accounts checkout-settings logo-uploads [flags] ``` * `--help`, `-h` bool default: false * help for logo-uploads **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims accounts checkout-settings logo-uploads create`](#raims-accounts-checkout-settings-logo-uploads-create). ##### `raims accounts checkout-settings logo-uploads create` Prepare a checkout logo upload ```bash raims accounts checkout-settings logo-uploads create [flags] ``` * `--content-type` string default: empty * Set JSON body field content\_type (string, required in the body) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--file-size` integer default: 0 * Set JSON body field file\_size (integer, required in the body) * `--height` integer default: 0 * Set JSON body field height (integer, required in the body) * `--help`, `-h` bool default: false * help for create * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) * `--upload-file` string default: empty * Prepare and upload a local PNG or JPEG; cannot be combined with JSON body options and does not apply the image to checkout * `--width` integer default: 0 * Set JSON body field width (integer, required in the body) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Prepare a checkout logo upload. POST /v1/accounts/checkout_settings/logo_uploads Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: content_type string required; allowed: "image/png", "image/jpeg" file_size integer required height integer required width integer required Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "content_type": "image/png", "file_size": 12345, "width": 512, "height": 128 } Example values are illustrative. Replace resource IDs and review the request before sending it. Without --upload-file, this operation prepares an upload using JSON metadata and returns the API's upload instructions. Use --upload-file PATH to read a PNG or JPEG, prepare its metadata and upload its bytes. Do not combine it with --data-file or body options. With --dry-run, the file is validated locally and only the metadata request is previewed. Uploading does not apply the image: update checkout settings with the returned upload ID in a separate request. With --upload-file, image metadata is read from the same bytes that are uploaded. The file must be PNG or JPEG, up to 524288 bytes, with width 128..2048 pixels and height 128..2048 pixels. --dry-run validates the local file and previews only the preparation request; it does not upload bytes. Apply the returned upload ID separately to change the checkout image. ``` **Command example** ```bash raims --profile PROFILE --output json accounts checkout-settings logo-uploads create --data-file request.json --dry-run raims accounts checkout-settings logo-uploads create --content-type="image/png" --file-size=12345 --height=128 --width=512 --dry-run raims accounts checkout-settings logo-uploads create --upload-file image.png --dry-run ``` #### `raims accounts checkout-settings update` Update checkout appearance settings ```bash raims accounts checkout-settings update [flags] ``` * `--body-null` stringArray default: [] * Set a nullable JSON body field to null by its JSON name (repeat for each field; cannot be combined with --data-file) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--favicon-upload-id` string default: empty * Set JSON body field favicon\_upload\_id (string, nullable) * `--help`, `-h` bool default: false * help for update * `--hex-primary-color` string default: empty * Set JSON body field hex\_primary\_color (string) * `--hex-secondary-color` string default: empty * Set JSON body field hex\_secondary\_color (string) * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--logo-upload-id` string default: empty * Set JSON body field logo\_upload\_id (string, nullable) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--support-email` string default: empty * Set JSON body field support\_email (string, nullable) * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Update checkout appearance settings. PATCH /v1/accounts/checkout_settings Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: favicon_upload_id string optional, nullable hex_primary_color string optional hex_secondary_color string optional logo_upload_id string optional, nullable support_email string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "logo_upload_id": "cau_3AbHiWSrsZBoaTg47OcMzC", "favicon_upload_id": "cau_1AbXiWSrsCBoaTg47OcMzC" } Example values are illustrative. Replace resource IDs and review the request before sending it. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Command example** ```bash raims --profile PROFILE --output json accounts checkout-settings update --data-file request.json --dry-run raims accounts checkout-settings update --favicon-upload-id="cau_1AbXiWSrsCBoaTg47OcMzC" --dry-run ``` #### `raims accounts checkout-settings uploads` Manage prepared checkout image uploads ```bash raims accounts checkout-settings uploads [flags] ``` * `--help`, `-h` bool default: false * help for uploads **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims accounts checkout-settings uploads delete`](#raims-accounts-checkout-settings-uploads-delete). ##### `raims accounts checkout-settings uploads delete` Discard a prepared checkout image upload ```bash raims accounts checkout-settings uploads delete ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for delete * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Discard a prepared checkout image upload. DELETE /v1/accounts/checkout_settings/uploads/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json accounts checkout-settings uploads delete ID --dry-run ``` ### `raims accounts context` Get the authenticated account context ```bash raims accounts context [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for context * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get the authenticated account context. GET /v1/accounts/context Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json accounts context --dry-run ``` ### `raims accounts fees` Get account fees ```bash raims accounts fees [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for fees * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get account fees. GET /v1/accounts/fees Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json accounts fees --dry-run ``` # raims balances (/en/cli/commands/balances) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims balances` Inspect balances and expected receivables ```bash raims balances [flags] ``` * `--help`, `-h` bool default: false * help for balances **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims balances forecast`](#raims-balances-forecast), [`raims balances get`](#raims-balances-get). ### `raims balances forecast` Get expected receivables for a period ```bash raims balances forecast [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for forecast * `--period` string default: today * Reporting period: today, last\_7\_days, last\_15\_days or last\_30\_days * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get expected receivables for a period. GET /v1/balances/forecast Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json balances forecast --dry-run ``` ### `raims balances get` Get the current balance ```bash raims balances get [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for get * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get the current balance. GET /v1/balances Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json balances get --dry-run ``` # raims charges (/en/cli/commands/charges) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims charges` Manage charges and their payment details ```bash raims charges [flags] ``` * `--help`, `-h` bool default: false * help for charges **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims charges boleto`](#raims-charges-boleto), [`raims charges create`](#raims-charges-create), [`raims charges get`](#raims-charges-get), [`raims charges list`](#raims-charges-list), [`raims charges payment`](#raims-charges-payment), [`raims charges receipt`](#raims-charges-receipt), [`raims charges refund-eligibility`](#raims-charges-refund-eligibility), [`raims charges refunds`](#raims-charges-refunds), [`raims charges revoke`](#raims-charges-revoke), [`raims charges statistics`](#raims-charges-statistics), [`raims charges update`](#raims-charges-update). ### `raims charges boleto` Get the boleto download information ```bash raims charges boleto ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for boleto * `--save` string default: empty * Save the PDF to PATH (up to 32 MiB); the parent directory must exist and the file must not exist * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get the boleto download information. GET /v1/charges/{id}/boleto Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json charges boleto ID --dry-run ``` ### `raims charges create` Create a charge ```bash raims charges create [flags] ``` * `--amount-cents` integer default: 0 * Set JSON body field amount\_cents (integer, required in the body) * `--body-null` stringArray default: [] * Set a nullable JSON body field to null by its JSON name (repeat for each field; cannot be combined with --data-file) * `--cancel-redirect-url` string default: empty * Set JSON body field cancel\_redirect\_url (string, nullable) * `--create-checkout` bool default: false * Set JSON body field create\_checkout (boolean) * `--customer-id` string default: empty * Set JSON body field customer\_id (string, required in the body) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--description` string default: empty * Set JSON body field description (string, nullable) * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--due-date` integer default: 0 * Set JSON body field due\_date (integer, required in the body) * `--external-reference` string default: empty * Set JSON body field external\_reference (string, nullable) * `--help`, `-h` bool default: false * help for create * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--metadata` stringArray default: empty * Set a metadata text value as KEY=VALUE (repeat for each key; dots in keys are literal) * `--metadata-empty` bool default: false * Send an empty metadata object; an update preserves existing keys * `--metadata-null` stringArray default: [] * Send null for a metadata key (repeat for each key; removes it when updating) * `--payment-method` integer default: 0 * Set JSON body field payment\_method (integer) * `--payment-method-types` integerArray default: empty * Set JSON body field payment\_method\_types (array\, repeat the option for each item, nullable) * `--send-email` bool default: false * Set JSON body field send\_email (boolean) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--success-redirect-url` string default: empty * Set JSON body field success\_redirect\_url (string, nullable) * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) * `--title` string default: empty * Set JSON body field title (string, nullable) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Create a charge. POST /v1/charges Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: amount_cents integer required cancel_redirect_url string optional, nullable create_checkout boolean optional customer_id string required description string optional, nullable due_date integer required external_reference string optional, nullable metadata object optional, nullable payment_method integer optional; allowed: 0, 1, 2 payment_method_types array optional, nullable; allowed: 1, 2 send_email boolean optional success_redirect_url string optional, nullable title string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "customer_id": "cus_1Q2W3E4R5T6Y7U8I9O0P", "amount_cents": 10000, "payment_method": 0, "due_date": 1893456000, "title": "Serviço contratado", "description": "Cobrança do serviço", "send_email": false, "external_reference": "pedido_12345" } Example values are illustrative. Replace resource IDs and review the request before sending it. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. Metadata options send a text map: repeat --metadata KEY=VALUE for values, use --metadata-null KEY for a null value, or --metadata-empty for an empty object. Empty text, numeric-looking values and the text null remain strings. Omitted metadata and an empty object preserve existing keys when updating; null values remove individual keys, and --body-null metadata clears the entire map. Do not combine these options with --data-file, or use multiple values for the same key. ``` **Command example** ```bash raims --profile PROFILE --output json charges create --data-file request.json --dry-run raims charges create --amount-cents=10000 --customer-id="cus_1Q2W3E4R5T6Y7U8I9O0P" --due-date=1893456000 --dry-run ``` ### `raims charges get` Get a charge ```bash raims charges get ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for get * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get a charge. GET /v1/charges/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json charges get ID --dry-run ``` ### `raims charges list` List charges ```bash raims charges list [flags] ``` * `--after` string default: empty * Read after this opaque cursor (cannot be combined with --before) * `--all` bool default: false * Read all pages as separate results (JSON Lines with --output json) * `--before` string default: empty * Read before this opaque cursor (cannot be combined with --after) * `--created-gte` int64 default: 0 * Created at or after this Unix timestamp (seconds) * `--created-lte` int64 default: 0 * Created at or before this Unix timestamp (seconds) * `--customer-id` string default: empty * Filter by customer ID * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--due-gte` int64 default: 0 * Due at or after this Unix timestamp (seconds) * `--due-lte` int64 default: 0 * Due at or before this Unix timestamp (seconds) * `--email` string default: empty * Filter by email address * `--external-reference` string default: empty * Filter by external reference * `--help`, `-h` bool default: false * help for list * `--identifier` string default: empty * Filter by public resource identifier * `--max-pages` int default: 100 * Maximum pages to read with --all (1-10000) * `--page-size` int64 default: 10 * Results per page (the API normalizes the requested size) * `--paid-gte` int64 default: 0 * Paid at or after this Unix timestamp (seconds) * `--paid-lte` int64 default: 0 * Paid at or before this Unix timestamp (seconds) * `--payment-method` string default: empty * Filter by comma-separated payment method codes * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--sort-key` string default: empty * Sort results by this API field * `--sort-order` string default: desc * Sort direction: asc or desc * `--status` string default: empty * Filter by comma-separated charge status codes * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text List charges. GET /v1/charges Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json charges list --dry-run ``` ### `raims charges payment` Get payment details for a charge ```bash raims charges payment ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for payment * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get payment details for a charge. GET /v1/charges/{id}/payment Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json charges payment ID --dry-run ``` ### `raims charges receipt` Get the payment receipt download information ```bash raims charges receipt ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for receipt * `--save` string default: empty * Save the PDF to PATH (up to 32 MiB); the parent directory must exist and the file must not exist * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get the payment receipt download information. GET /v1/charges/{id}/receipt Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json charges receipt ID --dry-run ``` ### `raims charges refund-eligibility` Check whether a charge can be refunded ```bash raims charges refund-eligibility ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for refund-eligibility * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Check whether a charge can be refunded. GET /v1/charges/{id}/refund_eligibility Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json charges refund-eligibility ID --dry-run ``` ### `raims charges refunds` Inspect and request refunds for a charge ```bash raims charges refunds [flags] ``` * `--help`, `-h` bool default: false * help for refunds **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims charges refunds create`](#raims-charges-refunds-create), [`raims charges refunds list`](#raims-charges-refunds-list). #### `raims charges refunds create` Request a refund for a charge ```bash raims charges refunds create ID [flags] ``` * `--amount-cents` integer default: 0 * Set JSON body field amount\_cents (integer, required in the body) * `--body-null` stringArray default: [] * Set a nullable JSON body field to null by its JSON name (repeat for each field; cannot be combined with --data-file) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--description` string default: empty * Set JSON body field description (string, nullable) * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for create * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Request a refund for a charge. POST /v1/charges/{id}/refunds Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: amount_cents integer required description string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "amount_cents": 2500, "description": "Devolução parcial do serviço" } Example values are illustrative. Replace resource IDs and review the request before sending it. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Command example** ```bash raims --profile PROFILE --output json charges refunds create ID --data-file request.json --dry-run raims charges refunds create ID --amount-cents=2500 --dry-run ``` #### `raims charges refunds list` List refunds for a charge ```bash raims charges refunds list ID [flags] ``` * `--after` string default: empty * Read after this opaque cursor (cannot be combined with --before) * `--all` bool default: false * Read all pages as separate results (JSON Lines with --output json) * `--before` string default: empty * Read before this opaque cursor (cannot be combined with --after) * `--created-gte` int64 default: 0 * Created at or after this Unix timestamp (seconds) * `--created-lte` int64 default: 0 * Created at or before this Unix timestamp (seconds) * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for list * `--max-pages` int default: 100 * Maximum pages to read with --all (1-10000) * `--page-size` int64 default: 10 * Results per page (the API normalizes the requested size) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text List refunds for a charge. GET /v1/charges/{id}/refunds Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json charges refunds list ID --dry-run ``` ### `raims charges revoke` Revoke a charge ```bash raims charges revoke ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for revoke * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Revoke a charge. DELETE /v1/charges/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Command example** ```bash raims --profile PROFILE --output json charges revoke ID --dry-run ``` ### `raims charges statistics` Get charge statistics for a period ```bash raims charges statistics [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for statistics * `--period` string default: today * Reporting period: today, last\_7\_days, last\_15\_days or last\_30\_days * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get charge statistics for a period. GET /v1/charges/statistics Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json charges statistics --dry-run ``` ### `raims charges update` Update a charge ```bash raims charges update ID [flags] ``` * `--body-null` stringArray default: [] * Set a nullable JSON body field to null by its JSON name (repeat for each field; cannot be combined with --data-file) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--description` string default: empty * Set JSON body field description (string, nullable) * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--external-reference` string default: empty * Set JSON body field external\_reference (string, nullable) * `--help`, `-h` bool default: false * help for update * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--metadata` stringArray default: empty * Set a metadata text value as KEY=VALUE (repeat for each key; dots in keys are literal) * `--metadata-empty` bool default: false * Send an empty metadata object; an update preserves existing keys * `--metadata-null` stringArray default: [] * Send null for a metadata key (repeat for each key; removes it when updating) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) * `--title` string default: empty * Set JSON body field title (string, nullable) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Update a charge. PATCH /v1/charges/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: description string optional, nullable external_reference string optional, nullable metadata object optional, nullable title string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "title": "Serviço atualizado", "description": "Descrição atualizada da cobrança", "external_reference": "pedido_12345_atualizado" } Example values are illustrative. Replace resource IDs and review the request before sending it. Metadata options send a text map: repeat --metadata KEY=VALUE for values, use --metadata-null KEY for a null value, or --metadata-empty for an empty object. Empty text, numeric-looking values and the text null remain strings. Omitted metadata and an empty object preserve existing keys when updating; null values remove individual keys, and --body-null metadata clears the entire map. Do not combine these options with --data-file, or use multiple values for the same key. ``` **Command example** ```bash raims --profile PROFILE --output json charges update ID --data-file request.json --dry-run raims charges update ID --description="Descrição atualizada da cobrança" --dry-run ``` # raims customers (/en/cli/commands/customers) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims customers` Manage customers ```bash raims customers [flags] ``` * `--help`, `-h` bool default: false * help for customers **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims customers create`](#raims-customers-create), [`raims customers delete`](#raims-customers-delete), [`raims customers delete-batch`](#raims-customers-delete-batch), [`raims customers get`](#raims-customers-get), [`raims customers list`](#raims-customers-list), [`raims customers update`](#raims-customers-update). ### `raims customers create` Create or update a customer by tax ID ```bash raims customers create [flags] ``` * `--body-null` stringArray default: [] * Set a nullable JSON body field to null by its JSON name (repeat for each field; cannot be combined with --data-file) * `--city` string default: empty * Set JSON body field city (string, nullable) * `--complement` string default: empty * Set JSON body field complement (string, nullable) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dial-code` string default: empty * Set JSON body field dial\_code (string, nullable) * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--email` string default: empty * Set JSON body field email (string, nullable) * `--external-reference` string default: empty * Set JSON body field external\_reference (string, nullable) * `--full-name` string default: empty * Set JSON body field full\_name (string, nullable) * `--help`, `-h` bool default: false * help for create * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--metadata` stringArray default: empty * Set a metadata text value as KEY=VALUE (repeat for each key; dots in keys are literal) * `--metadata-empty` bool default: false * Send an empty metadata object; an update preserves existing keys * `--metadata-null` stringArray default: [] * Send null for a metadata key (repeat for each key; removes it when updating) * `--neigh` string default: empty * Set JSON body field neigh (string, nullable) * `--phone-local` string default: empty * Set JSON body field phone\_local (string, nullable) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--street` string default: empty * Set JSON body field street (string, nullable) * `--street-number` string default: empty * Set JSON body field street\_number (string, nullable) * `--tax-id` string default: empty * Set JSON body field tax\_id (string, required in the body) * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) * `--uf` string default: empty * Set JSON body field uf (string, nullable) * `--zip-code` string default: empty * Set JSON body field zip\_code (string, nullable) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Create or update a customer by tax ID. POST /v1/customers Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: city string optional, nullable complement string optional, nullable dial_code string optional, nullable email string optional, nullable external_reference string optional, nullable full_name string optional, nullable metadata object optional, nullable neigh string optional, nullable phone_local string optional, nullable street string optional, nullable street_number string optional, nullable tax_id string required uf string optional, nullable zip_code string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "full_name": "Cliente de teste", "tax_id": "12345678909", "email": "cliente@example.invalid", "dial_code": "55", "phone_local": "11987654321", "zip_code": "01310000", "street": "Avenida de exemplo", "street_number": "100", "complement": "Sala 1", "neigh": "Centro", "city": "São Paulo", "uf": "SP" } Example values are illustrative. Replace resource IDs and review the request before sending it. Metadata options send a text map: repeat --metadata KEY=VALUE for values, use --metadata-null KEY for a null value, or --metadata-empty for an empty object. Empty text, numeric-looking values and the text null remain strings. Omitted metadata and an empty object preserve existing keys when updating; null values remove individual keys, and --body-null metadata clears the entire map. Do not combine these options with --data-file, or use multiple values for the same key. ``` **Command example** ```bash raims --profile PROFILE --output json customers create --data-file request.json --dry-run raims customers create --tax-id="12345678909" --dry-run ``` ### `raims customers delete` Delete a customer ```bash raims customers delete ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for delete * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Delete a customer. DELETE /v1/customers/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json customers delete ID --dry-run ``` ### `raims customers delete-batch` Delete the customers listed in the request body ```bash raims customers delete-batch [flags] ``` * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for delete-batch * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--identifiers` stringArray default: empty * Set JSON body field identifiers (array\, repeat the option for each item, required in the body) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Delete the customers listed in the request body. DELETE /v1/customers Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: identifiers array required Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "identifiers": [ "cus_3AbHiWSrsZBoaTg47OcMzC", "cus_1szWVIyZES2MJoAMUmjwW" ] } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Command example** ```bash raims --profile PROFILE --output json customers delete-batch --data-file request.json --dry-run raims customers delete-batch --identifiers="cus_3AbHiWSrsZBoaTg47OcMzC" --identifiers="cus_1szWVIyZES2MJoAMUmjwW" --dry-run ``` ### `raims customers get` Get a customer ```bash raims customers get ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for get * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get a customer. GET /v1/customers/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json customers get ID --dry-run ``` ### `raims customers list` List customers ```bash raims customers list [flags] ``` * `--after` string default: empty * Read after this opaque cursor (cannot be combined with --before) * `--all` bool default: false * Read all pages as separate results (JSON Lines with --output json) * `--before` string default: empty * Read before this opaque cursor (cannot be combined with --after) * `--document` string default: empty * Filter by customer tax ID * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--email` string default: empty * Filter by email address * `--external-reference` string default: empty * Filter by external reference * `--help`, `-h` bool default: false * help for list * `--identifier` string default: empty * Filter by public resource identifier * `--max-pages` int default: 100 * Maximum pages to read with --all (1-10000) * `--name` string default: empty * Filter by customer name * `--page-size` int64 default: 10 * Results per page (the API normalizes the requested size) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text List customers. GET /v1/customers Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json customers list --dry-run ``` ### `raims customers update` Update a customer ```bash raims customers update ID [flags] ``` * `--body-null` stringArray default: [] * Set a nullable JSON body field to null by its JSON name (repeat for each field; cannot be combined with --data-file) * `--city` string default: empty * Set JSON body field city (string, nullable) * `--complement` string default: empty * Set JSON body field complement (string, nullable) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dial-code` string default: empty * Set JSON body field dial\_code (string, nullable) * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--email` string default: empty * Set JSON body field email (string, nullable) * `--external-reference` string default: empty * Set JSON body field external\_reference (string, nullable) * `--full-name` string default: empty * Set JSON body field full\_name (string, nullable) * `--help`, `-h` bool default: false * help for update * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--metadata` stringArray default: empty * Set a metadata text value as KEY=VALUE (repeat for each key; dots in keys are literal) * `--metadata-empty` bool default: false * Send an empty metadata object; an update preserves existing keys * `--metadata-null` stringArray default: [] * Send null for a metadata key (repeat for each key; removes it when updating) * `--neigh` string default: empty * Set JSON body field neigh (string, nullable) * `--phone-local` string default: empty * Set JSON body field phone\_local (string, nullable) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--street` string default: empty * Set JSON body field street (string, nullable) * `--street-number` string default: empty * Set JSON body field street\_number (string, nullable) * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) * `--uf` string default: empty * Set JSON body field uf (string, nullable) * `--zip-code` string default: empty * Set JSON body field zip\_code (string, nullable) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Update a customer. PATCH /v1/customers/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: city string optional, nullable complement string optional, nullable dial_code string optional, nullable email string optional, nullable external_reference string optional, nullable full_name string optional, nullable metadata object optional, nullable neigh string optional, nullable phone_local string optional, nullable street string optional, nullable street_number string optional, nullable uf string optional, nullable zip_code string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "full_name": "Cliente atualizado", "email": "atualizado@example.invalid" } Example values are illustrative. Replace resource IDs and review the request before sending it. Metadata options send a text map: repeat --metadata KEY=VALUE for values, use --metadata-null KEY for a null value, or --metadata-empty for an empty object. Empty text, numeric-looking values and the text null remain strings. Omitted metadata and an empty object preserve existing keys when updating; null values remove individual keys, and --body-null metadata clears the entire map. Do not combine these options with --data-file, or use multiple values for the same key. ``` **Command example** ```bash raims --profile PROFILE --output json customers update ID --data-file request.json --dry-run raims customers update ID --email="atualizado@example.invalid" --dry-run ``` # raims disputes (/en/cli/commands/disputes) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims disputes` Inspect disputes ```bash raims disputes [flags] ``` * `--help`, `-h` bool default: false * help for disputes **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims disputes get`](#raims-disputes-get), [`raims disputes list`](#raims-disputes-list). ### `raims disputes get` Get a dispute ```bash raims disputes get ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for get * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get a dispute. GET /v1/disputes/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json disputes get ID --dry-run ``` ### `raims disputes list` List disputes ```bash raims disputes list [flags] ``` * `--after` string default: empty * Read after this opaque cursor (cannot be combined with --before) * `--all` bool default: false * Read all pages as separate results (JSON Lines with --output json) * `--before` string default: empty * Read before this opaque cursor (cannot be combined with --after) * `--charge-id` string default: empty * Filter by charge ID * `--created-gte` int64 default: 0 * Created at or after this Unix timestamp (seconds) * `--created-lte` int64 default: 0 * Created at or before this Unix timestamp (seconds) * `--disputed-amount-cents` int64 default: 0 * Filter by disputed amount in cents * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for list * `--max-pages` int default: 100 * Maximum pages to read with --all (1-10000) * `--page-size` int64 default: 10 * Results per page (the API normalizes the requested size) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--sort-key` string default: created_at * Sort results by this API field * `--sort-order` string default: desc * Sort direction: asc or desc * `--stage` string default: empty * Filter by comma-separated dispute stages * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text List disputes. GET /v1/disputes Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json disputes list --dry-run ``` # raims payment-links (/en/cli/commands/payment-links) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims payment-links` Manage payment links ```bash raims payment-links [flags] ``` * `--help`, `-h` bool default: false * help for payment-links **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims payment-links create`](#raims-payment-links-create), [`raims payment-links get`](#raims-payment-links-get), [`raims payment-links list`](#raims-payment-links-list), [`raims payment-links send-email`](#raims-payment-links-send-email), [`raims payment-links update`](#raims-payment-links-update). ### `raims payment-links create` Create or retrieve a payment link ```bash raims payment-links create [flags] ``` * `--body-null` stringArray default: [] * Set a nullable JSON body field to null by its JSON name (repeat for each field; cannot be combined with --data-file) * `--cancel-redirect-url` string default: empty * Set JSON body field cancel\_redirect\_url (string, nullable) * `--charge-id` string default: empty * Set JSON body field charge\_id (string, required in the body) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for create * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--payment-method-types` integerArray default: empty * Set JSON body field payment\_method\_types (array\, repeat the option for each item, nullable) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--success-redirect-url` string default: empty * Set JSON body field success\_redirect\_url (string, nullable) * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Create or retrieve a payment link. POST /v1/payment_links Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: cancel_redirect_url string optional, nullable charge_id string required payment_method_types array optional, nullable; allowed: 1, 2 success_redirect_url string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "charge_id": "ch_4CnJiWSrsZBoaTg47OcMzD", "success_redirect_url": "https://loja.example.com/pedido/concluido", "cancel_redirect_url": "https://loja.example.com/pedido", "payment_method_types": [ 1 ] } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Command example** ```bash raims --profile PROFILE --output json payment-links create --data-file request.json --dry-run raims payment-links create --charge-id="ch_4CnJiWSrsZBoaTg47OcMzD" --dry-run ``` ### `raims payment-links get` Get a payment link ```bash raims payment-links get ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for get * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get a payment link. GET /v1/payment_links/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json payment-links get ID --dry-run ``` ### `raims payment-links list` List payment links ```bash raims payment-links list [flags] ``` * `--after` string default: empty * Read after this opaque cursor (cannot be combined with --before) * `--all` bool default: false * Read all pages as separate results (JSON Lines with --output json) * `--before` string default: empty * Read before this opaque cursor (cannot be combined with --after) * `--charge-id` string default: empty * Filter by charge ID * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for list * `--max-pages` int default: 100 * Maximum pages to read with --all (1-10000) * `--page-size` int64 default: 10 * Results per page (the API normalizes the requested size) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text List payment links. GET /v1/payment_links Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json payment-links list --dry-run ``` ### `raims payment-links send-email` Request delivery of a payment link by email ```bash raims payment-links send-email ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for send-email * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Request delivery of a payment link by email. POST /v1/payment_links/{id}/send_email Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Command example** ```bash raims --profile PROFILE --output json payment-links send-email ID --dry-run ``` ### `raims payment-links update` Update a payment link ```bash raims payment-links update ID [flags] ``` * `--body-null` stringArray default: [] * Set a nullable JSON body field to null by its JSON name (repeat for each field; cannot be combined with --data-file) * `--cancel-redirect-url` string default: empty * Set JSON body field cancel\_redirect\_url (string, nullable) * `--clear-cancel-redirect-url` bool default: false * Set JSON body field clear\_cancel\_redirect\_url (boolean) * `--clear-success-redirect-url` bool default: false * Set JSON body field clear\_success\_redirect\_url (boolean) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for update * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--is-active` bool default: false * Set JSON body field is\_active (boolean) * `--payment-method-types` integerArray default: empty * Set JSON body field payment\_method\_types (array\, repeat the option for each item, nullable) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--success-redirect-url` string default: empty * Set JSON body field success\_redirect\_url (string, nullable) * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Update a payment link. PATCH /v1/payment_links/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: cancel_redirect_url string optional, nullable clear_cancel_redirect_url boolean optional clear_success_redirect_url boolean optional is_active boolean optional payment_method_types array optional, nullable; allowed: 1, 2 success_redirect_url string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "clear_success_redirect_url": true, "cancel_redirect_url": "https://loja.example.com/pedido" } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Command example** ```bash raims --profile PROFILE --output json payment-links update ID --data-file request.json --dry-run raims payment-links update ID --cancel-redirect-url="https://loja.example.com/pedido" --dry-run ``` # raims refunds (/en/cli/commands/refunds) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims refunds` Inspect refunds and receipts ```bash raims refunds [flags] ``` * `--help`, `-h` bool default: false * help for refunds **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims refunds get`](#raims-refunds-get), [`raims refunds list`](#raims-refunds-list), [`raims refunds receipt`](#raims-refunds-receipt). ### `raims refunds get` Get a refund ```bash raims refunds get ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for get * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get a refund. GET /v1/refunds/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json refunds get ID --dry-run ``` ### `raims refunds list` List refunds ```bash raims refunds list [flags] ``` * `--after` string default: empty * Read after this opaque cursor (cannot be combined with --before) * `--all` bool default: false * Read all pages as separate results (JSON Lines with --output json) * `--before` string default: empty * Read before this opaque cursor (cannot be combined with --after) * `--created-gte` int64 default: 0 * Created at or after this Unix timestamp (seconds) * `--created-lte` int64 default: 0 * Created at or before this Unix timestamp (seconds) * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for list * `--max-pages` int default: 100 * Maximum pages to read with --all (1-10000) * `--page-size` int64 default: 10 * Results per page (the API normalizes the requested size) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text List refunds. GET /v1/refunds Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json refunds list --dry-run ``` ### `raims refunds receipt` Get the refund receipt download information ```bash raims refunds receipt ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for receipt * `--save` string default: empty * Save the PDF to PATH (up to 32 MiB); the parent directory must exist and the file must not exist * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get the refund receipt download information. GET /v1/refunds/{id}/receipt Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json refunds receipt ID --dry-run ``` # raims simulations (/en/cli/commands/simulations) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims simulations` Simulate operations allowed by the API for the selected credential ```bash raims simulations [flags] ``` * `--help`, `-h` bool default: false * help for simulations **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims simulations charges`](#raims-simulations-charges), [`raims simulations refunds`](#raims-simulations-refunds). ### `raims simulations charges` Simulate charge and payment operations ```bash raims simulations charges [flags] ``` * `--help`, `-h` bool default: false * help for charges **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims simulations charges compensate-boleto`](#raims-simulations-charges-compensate-boleto), [`raims simulations charges configure-scenario`](#raims-simulations-charges-configure-scenario), [`raims simulations charges confirm-payment`](#raims-simulations-charges-confirm-payment), [`raims simulations charges fail-payment`](#raims-simulations-charges-fail-payment), [`raims simulations charges issue-payment`](#raims-simulations-charges-issue-payment), [`raims simulations charges refunds`](#raims-simulations-charges-refunds), [`raims simulations charges resolve-scenario`](#raims-simulations-charges-resolve-scenario). #### `raims simulations charges compensate-boleto` Simulate boleto clearing ```bash raims simulations charges compensate-boleto ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for compensate-boleto * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Simulate boleto clearing. POST /v1/simulations/charges/{id}/compensate_boleto Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. ``` **Command example** ```bash raims --profile PROFILE --output json simulations charges compensate-boleto ID --dry-run ``` #### `raims simulations charges configure-scenario` Configure the result of the next simulated operation ```bash raims simulations charges configure-scenario ID [flags] ``` * `--action` string default: empty * Set JSON body field action (string, required in the body) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for configure-scenario * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--outcome` string default: empty * Set JSON body field outcome (string, required in the body) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Configure the result of the next simulated operation. POST /v1/simulations/charges/{id}/scenario Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: action string required; allowed: "pix_issuance", "boleto_issuance", "cancellation" outcome string required; allowed: "pending", "failed" Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "action": "boleto_issuance", "outcome": "failed" } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Command example** ```bash raims --profile PROFILE --output json simulations charges configure-scenario ID --data-file request.json --dry-run raims simulations charges configure-scenario ID --action="boleto_issuance" --outcome="failed" --dry-run ``` #### `raims simulations charges confirm-payment` Confirm a simulated payment ```bash raims simulations charges confirm-payment ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for confirm-payment * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Confirm a simulated payment. POST /v1/simulations/charges/{id}/confirm_payment Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. ``` **Command example** ```bash raims --profile PROFILE --output json simulations charges confirm-payment ID --dry-run ``` #### `raims simulations charges fail-payment` Simulate a failed payment ```bash raims simulations charges fail-payment ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for fail-payment * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Simulate a failed payment. POST /v1/simulations/charges/{id}/fail_payment Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. ``` **Command example** ```bash raims --profile PROFILE --output json simulations charges fail-payment ID --dry-run ``` #### `raims simulations charges issue-payment` Issue a simulated payment for a charge ```bash raims simulations charges issue-payment ID [flags] ``` * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for issue-payment * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--payment-method` integer default: 0 * Set JSON body field payment\_method (integer, required in the body) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Issue a simulated payment for a charge. POST /v1/simulations/charges/{id}/issue_payment Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: payment_method integer required Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "payment_method": 2 } Example values are illustrative. Replace resource IDs and review the request before sending it. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Command example** ```bash raims --profile PROFILE --output json simulations charges issue-payment ID --data-file request.json --dry-run raims simulations charges issue-payment ID --payment-method=2 --dry-run ``` #### `raims simulations charges refunds` Simulate pending refunds for a charge ```bash raims simulations charges refunds [flags] ``` * `--help`, `-h` bool default: false * help for refunds **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims simulations charges refunds create`](#raims-simulations-charges-refunds-create). ##### `raims simulations charges refunds create` Create a pending simulated refund ```bash raims simulations charges refunds create ID [flags] ``` * `--amount-cents` integer default: 0 * Set JSON body field amount\_cents (integer, required in the body) * `--body-null` stringArray default: [] * Set a nullable JSON body field to null by its JSON name (repeat for each field; cannot be combined with --data-file) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--description` string default: empty * Set JSON body field description (string, nullable) * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for create * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Create a pending simulated refund. POST /v1/simulations/charges/{id}/refunds Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: amount_cents integer required description string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "amount_cents": 2500, "description": "Devolução parcial do serviço" } Example values are illustrative. Replace resource IDs and review the request before sending it. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Command example** ```bash raims --profile PROFILE --output json simulations charges refunds create ID --data-file request.json --dry-run raims simulations charges refunds create ID --amount-cents=2500 --dry-run ``` #### `raims simulations charges resolve-scenario` Resolve a pending simulated operation ```bash raims simulations charges resolve-scenario ID [flags] ``` * `--action` string default: empty * Set JSON body field action (string, required in the body) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for resolve-scenario * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--outcome` string default: empty * Set JSON body field outcome (string, required in the body) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Resolve a pending simulated operation. POST /v1/simulations/charges/{id}/resolve Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: action string required; allowed: "pix_issuance", "boleto_issuance", "cancellation" outcome string required; allowed: "completed", "failed" Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "action": "boleto_issuance", "outcome": "failed" } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Command example** ```bash raims --profile PROFILE --output json simulations charges resolve-scenario ID --data-file request.json --dry-run raims simulations charges resolve-scenario ID --action="boleto_issuance" --outcome="failed" --dry-run ``` ### `raims simulations refunds` Complete or fail simulated refunds ```bash raims simulations refunds [flags] ``` * `--help`, `-h` bool default: false * help for refunds **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims simulations refunds complete`](#raims-simulations-refunds-complete), [`raims simulations refunds fail`](#raims-simulations-refunds-fail). #### `raims simulations refunds complete` Complete a simulated refund ```bash raims simulations refunds complete ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for complete * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Complete a simulated refund. POST /v1/simulations/refunds/{id}/complete Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. ``` **Command example** ```bash raims --profile PROFILE --output json simulations refunds complete ID --dry-run ``` #### `raims simulations refunds fail` Simulate a failed refund ```bash raims simulations refunds fail ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for fail * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Simulate a failed refund. POST /v1/simulations/refunds/{id}/fail Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox. Simulations require Sandbox credentials and resources. OAuth requests must select Sandbox. Production data cannot be simulated. ``` **Command example** ```bash raims --profile PROFILE --output json simulations refunds fail ID --dry-run ``` # raims statements (/en/cli/commands/statements) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims statements` Inspect account statement entries ```bash raims statements [flags] ``` * `--help`, `-h` bool default: false * help for statements **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims statements get`](#raims-statements-get), [`raims statements list`](#raims-statements-list). ### `raims statements get` Get an account statement entry ```bash raims statements get ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for get * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get an account statement entry. GET /v1/statements/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json statements get ID --dry-run ``` ### `raims statements list` List account statement entries ```bash raims statements list [flags] ``` * `--after` string default: empty * Read after this opaque cursor (cannot be combined with --before) * `--all` bool default: false * Read all pages as separate results (JSON Lines with --output json) * `--before` string default: empty * Read before this opaque cursor (cannot be combined with --after) * `--created-gte` int64 default: 0 * Created at or after this Unix timestamp (seconds) * `--created-lte` int64 default: 0 * Created at or before this Unix timestamp (seconds) * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for list * `--max-pages` int default: 100 * Maximum pages to read with --all (1-10000) * `--page-size` int64 default: 10 * Results per page (the API normalizes the requested size) * `--reference-id` string default: empty * Filter by the referenced resource ID * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--sort-order` string default: desc * Sort direction: asc or desc * `--statement-type` string default: empty * Filter by comma-separated statement type codes * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text List account statement entries. GET /v1/statements Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json statements list --dry-run ``` # raims webhook-event-types (/en/cli/commands/webhook-event-types) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims webhook-event-types` Inspect supported webhook event types ```bash raims webhook-event-types [flags] ``` * `--help`, `-h` bool default: false * help for webhook-event-types **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims webhook-event-types list`](#raims-webhook-event-types-list). ### `raims webhook-event-types list` List supported webhook event types ```bash raims webhook-event-types list [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for list * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text List supported webhook event types. GET /v1/webhook_event_types Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json webhook-event-types list --dry-run ``` # raims webhooks (/en/cli/commands/webhooks) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims webhooks` Manage webhook endpoints ```bash raims webhooks [flags] ``` * `--help`, `-h` bool default: false * help for webhooks **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims webhooks create`](#raims-webhooks-create), [`raims webhooks delete`](#raims-webhooks-delete), [`raims webhooks get`](#raims-webhooks-get), [`raims webhooks health`](#raims-webhooks-health), [`raims webhooks list`](#raims-webhooks-list), [`raims webhooks rotate-secret`](#raims-webhooks-rotate-secret), [`raims webhooks set-pause`](#raims-webhooks-set-pause), [`raims webhooks test`](#raims-webhooks-test), [`raims webhooks update`](#raims-webhooks-update). ### `raims webhooks create` Create a webhook endpoint ```bash raims webhooks create [flags] ``` * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--events` stringArray default: empty * Set JSON body field events (array\, repeat the option for each item, required in the body) * `--help`, `-h` bool default: false * help for create * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--is-active` bool default: false * Set JSON body field is\_active (boolean) * `--name` string default: empty * Set JSON body field name (string, required in the body) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) * `--url` string default: empty * Set JSON body field url (string, required in the body) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Create a webhook endpoint. POST /v1/webhooks Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: events array required; allowed: "charge.created", "charge.paid", "charge.canceled", "charge.failed", "refund.requested", "refund.completed", "refund.failed" is_active boolean optional name string required url string required Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "name": "Pedidos pagos", "url": "https://webhooks.example.com/raims", "events": [ "charge.paid" ], "is_active": true } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Command example** ```bash raims --profile PROFILE --output json webhooks create --data-file request.json --dry-run raims webhooks create --events="charge.paid" --name="Pedidos pagos" --url="https://webhooks.example.com/raims" --dry-run ``` ### `raims webhooks delete` Delete a webhook endpoint ```bash raims webhooks delete WEBHOOK_ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for delete * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Delete a webhook endpoint. DELETE /v1/webhooks/{webhook_id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json webhooks delete WEBHOOK_ID --dry-run ``` ### `raims webhooks get` Get a webhook endpoint ```bash raims webhooks get WEBHOOK_ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for get * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get a webhook endpoint. GET /v1/webhooks/{webhook_id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json webhooks get WEBHOOK_ID --dry-run ``` ### `raims webhooks health` Get webhook delivery failures ```bash raims webhooks health WEBHOOK_ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for health * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get webhook delivery failures. GET /v1/webhooks/{webhook_id}/health Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json webhooks health WEBHOOK_ID --dry-run ``` ### `raims webhooks list` List webhook endpoints ```bash raims webhooks list [flags] ``` * `--after` string default: empty * Read after this opaque cursor (cannot be combined with --before) * `--all` bool default: false * Read all pages as separate results (JSON Lines with --output json) * `--before` string default: empty * Read before this opaque cursor (cannot be combined with --after) * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for list * `--max-pages` int default: 100 * Maximum pages to read with --all (1-10000) * `--page-size` int64 default: 10 * Results per page (the API normalizes the requested size) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text List webhook endpoints. GET /v1/webhooks Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json webhooks list --dry-run ``` ### `raims webhooks rotate-secret` Rotate a webhook signing secret ```bash raims webhooks rotate-secret WEBHOOK_ID [flags] ``` * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--grace-period-seconds` integer default: 0 * Set JSON body field grace\_period\_seconds (integer) * `--help`, `-h` bool default: false * help for rotate-secret * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Rotate a webhook signing secret. POST /v1/webhooks/{webhook_id}/rotate_secret Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: grace_period_seconds integer optional Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "grace_period_seconds": 86400 } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Command example** ```bash raims --profile PROFILE --output json webhooks rotate-secret WEBHOOK_ID --data-file request.json --dry-run raims webhooks rotate-secret WEBHOOK_ID --grace-period-seconds=86400 --dry-run ``` ### `raims webhooks set-pause` Pause or resume webhook deliveries using a JSON request ```bash raims webhooks set-pause WEBHOOK_ID [flags] ``` * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for set-pause * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--is-paused` bool default: false * Set JSON body field is\_paused (boolean, required in the body) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Pause or resume webhook deliveries using a JSON request. PATCH /v1/webhooks/{webhook_id}/pause Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: is_paused boolean required Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "is_paused": true } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Command example** ```bash raims --profile PROFILE --output json webhooks set-pause WEBHOOK_ID --data-file request.json --dry-run raims webhooks set-pause WEBHOOK_ID --is-paused=true --dry-run ``` ### `raims webhooks test` Request a test event for a webhook endpoint ```bash raims webhooks test WEBHOOK_ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for test * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Request a test event for a webhook endpoint. POST /v1/webhooks/{webhook_id}/test Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Command example** ```bash raims --profile PROFILE --output json webhooks test WEBHOOK_ID --dry-run ``` ### `raims webhooks update` Update a webhook endpoint ```bash raims webhooks update WEBHOOK_ID [flags] ``` * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--events` stringArray default: empty * Set JSON body field events (array\, repeat the option for each item) * `--help`, `-h` bool default: false * help for update * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--is-active` bool default: false * Set JSON body field is\_active (boolean) * `--name` string default: empty * Set JSON body field name (string) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) * `--url` string default: empty * Set JSON body field url (string) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Update a webhook endpoint. PATCH /v1/webhooks/{webhook_id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: events array optional is_active boolean optional name string optional url string optional Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "events": [ "charge.paid", "refund.completed" ] } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Command example** ```bash raims --profile PROFILE --output json webhooks update WEBHOOK_ID --data-file request.json --dry-run raims webhooks update WEBHOOK_ID --events="charge.paid" --events="refund.completed" --dry-run ``` # raims withdrawal-destinations (/en/cli/commands/withdrawal-destinations) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims withdrawal-destinations` Inspect withdrawal destinations ```bash raims withdrawal-destinations [flags] ``` * `--help`, `-h` bool default: false * help for withdrawal-destinations **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims withdrawal-destinations get`](#raims-withdrawal-destinations-get), [`raims withdrawal-destinations list`](#raims-withdrawal-destinations-list). ### `raims withdrawal-destinations get` Get a withdrawal destination ```bash raims withdrawal-destinations get ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for get * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get a withdrawal destination. GET /v1/withdrawal_destinations/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. ``` **Command example** ```bash raims --profile PROFILE --output json withdrawal-destinations get ID --dry-run ``` ### `raims withdrawal-destinations list` List withdrawal destinations ```bash raims withdrawal-destinations list [flags] ``` * `--after` string default: empty * Read after this opaque cursor (cannot be combined with --before) * `--all` bool default: false * Read all pages as separate results (JSON Lines with --output json) * `--before` string default: empty * Read before this opaque cursor (cannot be combined with --after) * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for list * `--max-pages` int default: 100 * Maximum pages to read with --all (1-10000) * `--page-size` int64 default: 10 * Results per page (the API normalizes the requested size) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text List withdrawal destinations. GET /v1/withdrawal_destinations Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. ``` **Command example** ```bash raims --profile PROFILE --output json withdrawal-destinations list --dry-run ``` # raims withdrawals (/en/cli/commands/withdrawals) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## `raims withdrawals` Inspect and request withdrawals ```bash raims withdrawals [flags] ``` * `--help`, `-h` bool default: false * help for withdrawals **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims withdrawals automatic-settings`](#raims-withdrawals-automatic-settings), [`raims withdrawals create`](#raims-withdrawals-create), [`raims withdrawals get`](#raims-withdrawals-get), [`raims withdrawals limits`](#raims-withdrawals-limits), [`raims withdrawals list`](#raims-withdrawals-list), [`raims withdrawals summary`](#raims-withdrawals-summary). ### `raims withdrawals automatic-settings` Manage automatic withdrawal settings ```bash raims withdrawals automatic-settings [flags] ``` * `--help`, `-h` bool default: false * help for automatic-settings **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims withdrawals automatic-settings get`](#raims-withdrawals-automatic-settings-get), [`raims withdrawals automatic-settings update`](#raims-withdrawals-automatic-settings-update). #### `raims withdrawals automatic-settings get` Get automatic withdrawal settings ```bash raims withdrawals automatic-settings get [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for get * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get automatic withdrawal settings. GET /v1/withdrawals/automatic_settings Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. ``` **Command example** ```bash raims --profile PROFILE --output json withdrawals automatic-settings get --dry-run ``` #### `raims withdrawals automatic-settings update` Update automatic withdrawal settings ```bash raims withdrawals automatic-settings update [flags] ``` * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--enabled` bool default: false * Set JSON body field enabled (boolean) * `--help`, `-h` bool default: false * help for update * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--minimum-amount-cents` integer default: 0 * Set JSON body field minimum\_amount\_cents (integer) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--time` string default: empty * Set JSON body field time (string) * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Update automatic withdrawal settings. PATCH /v1/withdrawals/automatic_settings Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: enabled boolean optional minimum_amount_cents integer optional time string optional Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "time": "10:00" } Example values are illustrative. Replace resource IDs and review the request before sending it. ``` **Command example** ```bash raims --profile PROFILE --output json withdrawals automatic-settings update --data-file request.json --dry-run raims withdrawals automatic-settings update --time="10:00" --dry-run ``` ### `raims withdrawals create` Request a withdrawal to the company's default Pix key ```bash raims withdrawals create [flags] ``` * `--amount-cents` integer default: 0 * Set JSON body field amount\_cents (integer, required in the body) * `--body-null` stringArray default: [] * Set a nullable JSON body field to null by its JSON name (repeat for each field; cannot be combined with --data-file) * `--data-file` string default: empty * Read the JSON request body from a UTF-8 file, or '-' for stdin * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--expected-destination-id` string default: empty * Set JSON body field expected\_destination\_id (string, nullable) * `--help`, `-h` bool default: false * help for create * `--idempotency-key` string default: empty * Reuse this optional idempotency key when retrying the same request * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Request a withdrawal to the company's default Pix key. POST /v1/withdrawals Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. Read the JSON request body with --data-file PATH, or --data-file - for standard input. You can also provide the body options listed below. Repeat array options for each item. Do not combine file input with body options. Only supplied fields are sent. When listed, --body-null FIELD sends an explicit null for a nullable field. Array size and uniqueness follow the endpoint contract. Objects without dedicated body options and arrays of objects use file input. JSON body fields: amount_cents integer required expected_destination_id string optional, nullable Nested requirements apply when the parent object is present, or for each supplied array item. Omit an optional field to leave it unspecified; null is accepted only for nullable fields. JSON body example (save as request.json): { "amount_cents": 25000 } Example values are illustrative. Replace resource IDs and review the request before sending it. HTTP 202 means the request is pending. Inspect the returned resource before repeating an operation; this command does not wait for completion. ``` **Command example** ```bash raims --profile PROFILE --output json withdrawals create --data-file request.json --dry-run raims withdrawals create --amount-cents=25000 --dry-run ``` ### `raims withdrawals get` Get a withdrawal ```bash raims withdrawals get ID [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for get * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get a withdrawal. GET /v1/withdrawals/{id} Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json withdrawals get ID --dry-run ``` ### `raims withdrawals limits` Get withdrawal conditions and limits ```bash raims withdrawals limits [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for limits * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get withdrawal conditions and limits. GET /v1/withdrawals/limits Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json withdrawals limits --dry-run ``` ### `raims withdrawals list` List withdrawals ```bash raims withdrawals list [flags] ``` * `--after` string default: empty * Read after this opaque cursor (cannot be combined with --before) * `--all` bool default: false * Read all pages as separate results (JSON Lines with --output json) * `--before` string default: empty * Read before this opaque cursor (cannot be combined with --after) * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for list * `--max-pages` int default: 100 * Maximum pages to read with --all (1-10000) * `--page-size` int64 default: 10 * Results per page (the API normalizes the requested size) * `--requested-gte` int64 default: 0 * Requested at or after this Unix timestamp (seconds) * `--requested-lte` int64 default: 0 * Requested at or before this Unix timestamp (seconds) * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--sort-order` string default: desc * Sort direction: asc or desc * `--status` string default: empty * Filter by comma-separated withdrawal status names * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text List withdrawals. GET /v1/withdrawals Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Sandbox, Production. ``` **Command example** ```bash raims --profile PROFILE --output json withdrawals list --dry-run ``` ### `raims withdrawals summary` Get a summary of withdrawals in progress ```bash raims withdrawals summary [flags] ``` * `--dry-run` bool default: false * Validate and preview the request without credentials or network access * `--help`, `-h` bool default: false * help for summary * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Get a summary of withdrawals in progress. GET /v1/withdrawals/summary Uses https://api.raims.com and the credential referenced by the selected profile. The API validates the credential's company, environment and permissions. API keys determine their own environment; --environment is available only with OAuth. Use --dry-run to validate and preview the request without reading a profile, loading credentials or contacting the API. Add --environment to preview an OAuth request; without it, the preview uses API-key authentication and has no environment header. OAuth environments accepted by this operation: Production. ``` **Command example** ```bash raims --profile PROFILE --output json withdrawals summary --dry-run ``` # Configuration and profiles (/en/cli/configuration) Use a profile for each account or integration. You can sign in through your browser with OAuth or associate an API key with an environment variable. The configuration stores the required references; secrets stay outside the profile file. ## Sign in with your browser To use your account in the terminal, choose a profile name and environment: ```bash raims login --profile pessoal --environment sandbox raims profile use pessoal ``` The CLI opens the Raims sign-in page. Check the account and the **Raims CLI** application, choose permissions, review the authorized environments, and complete the security confirmation. Return to the terminal when authorization finishes. You do not need to copy an API key or give the CLI your password. Running login again checks the authorization with the server. If the session is still valid, the CLI reuses the connection. If it has expired or been revoked, the CLI opens a new consent flow. A temporary outage does not create another connection: wait and try again. Choose another profile name to connect a different account. Access remains limited to the granted permissions and the current access of the person who authorized the connection. The session refreshes automatically while the connection remains valid. Credentials are protected by the operating system's secure store. If it is unavailable, restore access or use an API-key profile; the CLI does not save the session as plain text. Before each request, the CLI checks that the token will remain valid for the period set by `--timeout` and refreshes it when needed. If its lifetime is still insufficient, the request is not sent. See the guidance for `OAUTH_TOKEN_LIFETIME_INSUFFICIENT` in [Diagnostics](/en/cli/diagnostics). To inspect local session metadata without a network request: ```bash raims --profile pessoal auth status ``` This inspection does not confirm current server access. Use `auth check` to make an authenticated read. To open the browser yourself, run: ```bash raims login --profile pessoal --environment sandbox --no-browser ``` Open the displayed address and keep the command running until you finish. The browser must be able to reach the local callback on the machine running the CLI. This option does not provide a code-based sign-in flow for another device. Sign-in requires an interactive terminal; use an API key for pipelines. ## Select the environment During OAuth sign-in, `--environment sandbox` or `--environment production` sets the profile's initial environment. Subsequent commands use that choice. To run a command in another authorized environment, supply the option: ```bash raims --profile pessoal --environment sandbox customers list raims --profile pessoal --environment production accounts fees ``` The option only selects an already authorized environment. It does not expand access or change the connection's environments. Check the account and environment before sending a Production write. For API-key profiles, the key determines the environment. Use a key for the environment you need; an environment option does not convert the credential. ## Sign out To revoke the profile's OAuth connection: ```bash raims logout --profile pessoal ``` After revocation succeeds, the CLI removes the local session and profile. If revocation fails, it keeps them so you can try again. You can also revoke access in **Integration / Authorized applications**. Signing out of the Dashboard does not close the CLI connection. To connect again, run `raims login` and review the permissions. ## Create a profile For scripts and integrations that use an API key: ### Associate the environment variable ```bash raims profile set sandbox --api-key-env RAIMS_SANDBOX_API_KEY ``` Pass the variable name in `--api-key-env`. It accepts uppercase letters, digits, and underscores, starting with a letter or underscore. Set the key value separately in your terminal or secret manager. ### Select the default ```bash raims profile use sandbox ``` This command saves the selection used when an invocation does not specify another profile. ### Inspect the profiles ```bash raims profile list raims profile show sandbox ``` The list identifies the default profile. The profile view shows its name and associated variable, without printing the key value. The name `sandbox` does not determine a request's environment. The API determines the environment and company from the validated key, as described in [Authentication](/en/integracoes/autenticacao). For a Production credential, you can create another profile with a separate variable: ```bash raims profile set production --api-key-env RAIMS_PRODUCTION_API_KEY ``` Make the key value available in that variable to the CLI process. Requests from both profiles use `https://api.raims.com`. The CLI does not accept another address through an option, environment variable, or profile setting. ## Check API access ```bash raims --profile sandbox --output json auth check ``` The command reads `GET /v1/accounts/fees` at `https://api.raims.com` with the selected profile's credential, without changing the account. It accepts both OAuth and API-key profiles. On success, it returns: ```json { "status_code": 200, "data": { "authenticated": true, "profile": "sandbox" } } ``` This result confirms access to the account fees endpoint. Every other endpoint validates its own permissions and conditions. A rejection can also mean the key lacks permission for this read; it does not, by itself, prove the credential is invalid. Check the returned HTTP status and `error.code`. For an API-key profile, a missing or empty variable prevents the request. The CLI does not read the key from an argument or store its value in the profile. ## Choose a profile for the invocation The CLI selects the profile in this order: | Priority | Source | When to use it | | -------- | --------------------- | ------------------------------------------------ | | 1 | `--profile NAME` | Choose a profile for one command. | | 2 | `RAIMS_PROFILE` | Choose a profile for the terminal or automation. | | 3 | Saved default profile | Reuse the selection from `raims profile use`. | To select a profile for this invocation only: ```bash raims --profile sandbox profile show ``` The flag does not change the saved default. A profile supplied through `--profile` takes precedence over `RAIMS_PROFILE`. `raims profile show NAME` inspects the profile supplied as an argument even when another profile is selected. The list keeps identifying the saved default and also reports the invocation's selection in JSON output. ### PowerShell ```powershell $env:RAIMS_PROFILE = 'sandbox' raims profile show ``` ### Bash and Zsh ```bash export RAIMS_PROFILE=sandbox raims profile show ``` ## Remove a profile To remove an old profile from local configuration: ```bash raims profile remove old-project ``` OAuth profiles require `raims logout` before removal or replacement with an API-key profile. Supply the exact API-key profile name. Removal does not revoke the API key or change the environment variable containing it. If the removed profile was the saved default, the CLI clears that selection without choosing another profile. Run `raims profile use NAME` to save a new default. Repeating the command for an already absent profile succeeds. With `--output json`, the result contains `name` and `configured: false`. If `RAIMS_PROFILE` still points to the removed profile, update or clear that selection in your terminal before running another command that uses a profile. ## Set up autocompletion Use the assistant to detect your shell and see activation instructions: ```bash raims completion setup ``` Without `--save`, the command shows its plan without creating files. If detection does not identify a supported shell, supply `--shell powershell|bash|zsh|fish`. To preview the write plan and then save the PowerShell script: ```bash raims completion setup --shell powershell --save ./raims-completion.ps1 --dry-run raims completion setup --shell powershell --save ./raims-completion.ps1 ``` The directory must exist and the file must be new. The CLI does not overwrite files or change your shell profile or startup file. After saving, follow the displayed instructions to activate autocompletion in the desired session, following your terminal's policy. The assistant works without a profile, key, or network and does not activate updates. With `--output json`, it returns the selected shell, the source of that choice, the path when supplied, write and preview indicators, and instructions. Existing commands, such as `raims completion powershell`, still write the script to stdout for manual setup. ## Configuration location Check which path the CLI uses: ```bash raims config path ``` By default, the file is in the `raims` folder inside the user's configuration directory. Set `RAIMS_CONFIG_DIR` to an absolute path to use another folder, such as an isolated configuration for an automation. Keep this folder protected by the permissions of the user running the CLI. The profile file contains authentication references and metadata, without plain-text secrets. The OAuth session remains encrypted and requires access to the operating system's secure store. # Diagnostics (/en/cli/diagnostics) Use `raims doctor` to inspect your CLI configuration and identify what needs to be corrected in your installation. ## Run the diagnostic ```bash raims doctor ``` Checks cover configuration and selected profile access, local file permissions, executable identity, and the update policy. Each check reports the condition found and the applicable guidance. | Result | Meaning | | --------- | -------------------------------------------------------------------------------------------------------------------- | | `ok` | The check completed without a problem. | | `warning` | A condition needs attention, such as no selected profile or a missing key variable. | | `error` | A check failed, such as invalid configuration, a requested profile that does not exist, or insufficient permissions. | A check with `error` makes the command exit with code `3`. Warnings allow the diagnostic to complete with code `0`. To select another profile or capture the result in an automation: ```bash raims --profile sandbox --output json doctor ``` The JSON includes `status`, `build`, `interactive`, the selected `profile` when present, and the `checks` list. Each check contains `name`, `status`, and `message`. The names are `configuration`, `profile`, `permissions`, `installation`, and `updates`. The diagnostic does not send API requests or confirm credential validity, company permissions, or service connectivity. See [Authentication](/en/integracoes/autenticacao) and [API keys](/en/integracoes/chaves-api) for those conditions. ## Check the architecture To inspect the operating system and architecture of the executable in use: ```bash raims --output json version ``` For the native Windows ARM64 CLI, the result contains `os: "windows"` and `arch: "arm64"`. This local read does not require a profile, key, or network. If you installed through npm, also check Node.js in the same terminal: ```bash node -p "process.platform + '/' + process.arch" ``` To use the native package on Windows ARM64, have Node.js 22 or later for ARM64. The command above must return `win32/arm64`. x64 Node.js selects the x64 package even when Windows is ARM64. Once ARM64 Node.js is available, install or update with `npm install -g @raimshq/cli@latest` and check the CLI version again. For direct installation, choose the installer for the desired architecture and check the executable by its full path. The installer does not replace an installation of another version or architecture. To keep both, select another user directory with `-directory PATH`, preserve the existing installation, and use the new executable's full path. See [Direct installation](/en/cli/direct-installation). ## Check API access ```bash raims --profile sandbox --output json auth check --timeout 30s ``` This command sends `GET /v1/accounts/fees` to `https://api.raims.com` with the profile's OAuth session or API key. It does not change the account. A successful result contains `data.authenticated: true` and the profile name, confirming access to this read. Other endpoints remain subject to their own permissions and conditions. Sandbox and Production keys use the same address. For an API-key profile, the API determines the environment from the validated key. For an OAuth profile, use the environment chosen at sign-in or supply `--environment sandbox|production`. To check access to another resource, use its read command and inspect the HTTP status and `error.code` if access is rejected. `auth check` does not grant permissions or perform test writes. To inspect only an OAuth session's local metadata without accessing the secure store or network, run `raims --profile pessoal auth status`. This inspection does not replace server-side access verification. ## Sign in again with the same CLI profile Run `raims login --profile pessoal --environment sandbox`. The CLI checks the authorization with the server and reuses a valid session. If it has expired or been revoked, it opens a new consent flow in the browser. Check the profile name, account, and permissions before authorizing. Use another profile for a different account. ## Temporarily unavailable CLI session refresh If you receive `OAUTH_SERVICE_UNAVAILABLE`, wait and run the command again. This temporary rejection of a session refresh preserves the session for another attempt, without requiring new consent. If the error says that the refresh could not be confirmed, follow the displayed guidance before trying again. ## CLI cancellation and exit code Interrupting a command with Ctrl+C returns `CANCELLED` and exit code `130`, including during sign-in or session refresh. Cancelling a request does not undo what the API has already accepted. If the request changed a resource, check its result before repeating it. ## Investigate a failure When you type a name close to a known command, the CLI suggests the correct spelling and shows how to open the group's help. For example, `raims customers creat` may suggest `raims customers create`. The suggestion is not executed. The error keeps the code `UNKNOWN_COMMAND` and exit code `2`. When an option is spelled close to a known option, the CLI may suggest a correction, such as `--full-name` for `--full_name`. If a value is missing or has the wrong format, the message shows the expected type or accepted values and the command's help, such as `raims charges create --help`. Ambiguous suggestions are omitted. For metadata, use `--metadata key=value`; dots are part of the key's name and do not create nested options. Option errors keep `INVALID_ARGUMENT`, the `usage` category, and exit code `2`, without repeating supplied values. These errors do not execute the request. `OAUTH_TOKEN_LIFETIME_INSUFFICIENT` means that the CLI could not obtain a token valid for the entire request deadline, even after trying to refresh it. The API request was not sent. Use a shorter `--timeout` that is still appropriate for the command, or run `raims logout` and `raims login` to renew the authorization. This error uses exit code `4`. ### The secure store is unavailable Check that your operating system session can access its secure store. The CLI needs it to protect and read the OAuth session. In a pipeline without this facility, use an API-key profile and inject the secret through its associated variable. Do not copy session files to bypass the error. ### The profile was not found Run `raims profile list` and check the supplied name. Selection uses `--profile`, then `RAIMS_PROFILE`, then the saved default. Use `raims profile use NAME` to save another default. ### The configuration cannot be read Run `raims config path` and check the permissions of the user running the process. If you use `RAIMS_CONFIG_DIR`, supply an absolute path to the correct folder. Keep a copy of the file before correcting it. ### The key variable is missing Run `raims profile show` to identify the variable associated with the selected profile. Make the key available in that variable to the CLI process through your terminal or secret manager. Do not pass its value through `--api-key-env`: that option accepts only the variable name. ### The API rejected access Check the HTTP status and `error.code`. A valid key may lack access to the requested endpoint. Check the credential, permissions, and access restrictions for that request. Exit code `4` indicates authentication or authorization failure. ### The request ended without a confirmed response Exit code `5` indicates a network failure or timeout. Check connectivity and the deadline supplied through `--timeout`. If the request changed a resource, query its result before repeating it: a local timeout or cancellation does not undo what the API has already accepted. ### The package manager blocked a recently published version Some package managers require a security waiting period after a version is published. If installation reports this restriction, wait for the indicated period and try again. In Yarn, error `YN0016` can indicate this condition; check whether the message mentions version quarantine. ### Updates are disabled Run `raims update status` to see the reason. Check `RAIMS_CLI_NO_UPDATE`, `RAIMS_CLI_PIN_VERSION`, and whether the process is running in CI. Installations maintained by package managers follow their manager's update mechanism. If you installed through npm, update with `npm install -g @raimshq/cli@latest`. In pipelines, use `@latest` during installation and check whether `RAIMS_CLI_PIN_VERSION` requires an older version. The built-in updater stays disabled for this installation. Disabled updates do not prevent use of the installed version. For a direct installation, check the executable by its full path and follow the [update policy](/en/cli/direct-installation#controlar-as-atualizações). The pin requires an available version and does not download files. Keep the cache and backups while investigating a failure. ## Share a diagnostic Add `--debug` to obtain execution details on `stderr`: ```bash raims --debug --output json doctor ``` Diagnostics keep the command result on `stdout` and hide credential values. Review paths, profile names, and other local information before sharing files. Never include API keys, tokens, or the full address of a sign-in in progress in a problem report. For API requests, include the exit code, `error.code`, and, when available, `error.status_code` and `error.request_id`. Also review any response captured from `stdout`, as it can contain account data or secrets from the requested resource. To identify the legal texts included in the running version, use `raims licenses --output json`. This local read does not require a profile or network access; see [Notices and licenses](/en/cli#consultar-avisos-e-licencas). # Direct installation (/en/cli/direct-installation) Direct installation uses the native Raims CLI executable. This channel does not require Node.js or npm. The installer accesses the distribution channel over the internet, verifies the files, and writes the installation to a user directory without requesting an API key. To install through npm in automation, follow [CI and automation](/en/cli/automation#controlar-a-versão), which uses `@latest`. ## Choose the installer Choose the operating system and architecture of the machine that will run the CLI: | Platform | Installer | | ------------- | ------------------------------------------------------------------------------------------------------------------------ | | Windows x64 | [Download for Windows x64](https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-windows-amd64.exe) | | Windows ARM64 | [Download for Windows ARM64](https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-windows-arm64.exe) | | Linux x64 | [Download for Linux x64](https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-linux-amd64) | | Linux ARM64 | [Download for Linux ARM64](https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-linux-arm64) | | macOS x64 | [Download for macOS x64](https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-darwin-amd64) | | macOS ARM64 | [Download for macOS ARM64](https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-darwin-arm64) | `0.1.2` identifies the installer version. When it checks the channel, it selects the latest stable patch in the `0.1` line. The filename does not pin the CLI version that will be installed. Review the version shown in the plan. On Windows ARM64, choose the ARM64 installer to run the CLI natively. This direct installation does not require Node.js. To check the architecture of an existing installation, see [Diagnostics](/en/cli/diagnostics#conferir-a-arquitetura). On Windows, you can inspect the file's digital signature with `Get-AuthenticodeSignature`. If the result is not `Valid`, do not run the file; check the official download. ## Review the plan and install Without `-apply`, the installer checks the channel and shows the version and destination without applying the installation. Run it again with `-apply` after reviewing the plan. The examples below download the installer and use the default destination. ### Windows x64 ```powershell Invoke-WebRequest -Uri 'https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-windows-amd64.exe' -OutFile '.\raims-install-0.1.2-windows-amd64.exe' .\raims-install-0.1.2-windows-amd64.exe .\raims-install-0.1.2-windows-amd64.exe -apply ``` ### Windows ARM64 ```powershell Invoke-WebRequest -Uri 'https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-windows-arm64.exe' -OutFile '.\raims-install-0.1.2-windows-arm64.exe' .\raims-install-0.1.2-windows-arm64.exe .\raims-install-0.1.2-windows-arm64.exe -apply ``` ### Linux x64 ```bash curl --fail --show-error --output ./raims-install 'https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-linux-amd64' chmod u+x ./raims-install ./raims-install ./raims-install -apply ``` ### Linux ARM64 ```bash curl --fail --show-error --output ./raims-install 'https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-linux-arm64' chmod u+x ./raims-install ./raims-install ./raims-install -apply ``` ### macOS x64 ```bash curl --fail --show-error --output ./raims-install 'https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-darwin-amd64' chmod u+x ./raims-install ./raims-install ./raims-install -apply ``` ### macOS ARM64 ```bash curl --fail --show-error --output ./raims-install 'https://static.raims.com/cli/direct/installers/0.1.2/raims-install-0.1.2-darwin-arm64' chmod u+x ./raims-install ./raims-install ./raims-install -apply ``` `-directory PATH` selects another absolute destination within the user's space. The directory must be writable and cannot be accessed through links or junctions. The installer does not elevate permissions or replace unknown files or an installation of another version. An exact retry reuses the installation and preserves additional files. ## Use the installed executable The default destinations are: | System | Executable | | --------------- | ------------------------------------ | | Windows | `%LOCALAPPDATA%\Raims\CLI\raims.exe` | | Linux and macOS | `~/.local/share/raims/cli/raims` | You can use the full path without changing PATH: ### PowerShell ```powershell & "$env:LOCALAPPDATA\Raims\CLI\raims.exe" version & "$env:LOCALAPPDATA\Raims\CLI\raims.exe" update status ``` ### Bash and Zsh ```bash "$HOME/.local/share/raims/cli/raims" version "$HOME/.local/share/raims/cli/raims" update status ``` If you chose another destination, use the executable in that directory. Installation does not create a profile or store an API key. To make requests, follow [Configuration and profiles](/en/cli/configuration). ## Create a command in PATH `-link-user-path` is an explicit choice and requires `-apply` and `-path-directory PATH`. That directory must exist within the user's space and already be in the session's PATH. The installer does not edit shell profiles, the registry, or the PATH value. In the example below, use `~/.local/bin` only if the directory already exists and is in PATH: ```bash ./raims-install -apply -link-user-path -path-directory "$HOME/.local/bin" raims version ``` On Windows, the same options accept a user directory already in PATH. `WindowsApps` is not accepted as a destination for this integration. Resolve conflicts with other installations, shell aliases, or functions before creating the entry. The installer rejects an earlier command in PATH or a conflicting entry in the selected directory. If integration fails, the verified installation is preserved; use the executable's full path. ## Control updates In a direct installation, the CLI can silently check for updates while it is used. A downloaded version remains pending and can be activated on the next eligible invocation without interrupting a command already running. If the check or verification fails, the installed version is preserved. `raims update status` shows the policy and local versions without fetching an update. `RAIMS_CLI_NO_UPDATE=1` disables checks and pending activation; it does not revert a version already active. `RAIMS_CLI_PIN_VERSION` requires a version already installed or retained by the CLI. The pin does not download a version. CI environments disable automatic checks and activation. Use `@latest` in npm installation examples, including CI. See how to derive the direct installation's pin in [CI and automation](/en/cli/automation#controlar-a-versão). ## Keep versions and backups Keep the cached versions, original installation, and CLI backups. These files allow you to select retained versions and recover an installation. This release does not automatically clean up that history. Do not delete versions while commands are running. The CLI does not automatically repeat a command that has already started and then failed. ## Read notices and licenses `raims licenses` reads the texts included in the running version without a profile, key, or network access. Its JSON output contains `text` and `sha256`. See the examples in [Notices and licenses](/en/cli#consultar-avisos-e-licencas). # Command reference (/en/cli/reference) Look up syntax, arguments, and options for each command. Use `raims COMMAND --help` to read the help in your terminal. ## API commands - [raims accounts](/en/cli/commands/accounts): Inspect account details and configure checkout appearance - [raims balances](/en/cli/commands/balances): Inspect balances and expected receivables - [raims charges](/en/cli/commands/charges): Manage charges and their payment details - [raims customers](/en/cli/commands/customers): Manage customers - [raims disputes](/en/cli/commands/disputes): Inspect disputes - [raims payment-links](/en/cli/commands/payment-links): Manage payment links - [raims refunds](/en/cli/commands/refunds): Inspect refunds and receipts - [raims simulations](/en/cli/commands/simulations): Simulate operations allowed by the API for the selected credential - [raims statements](/en/cli/commands/statements): Inspect account statement entries - [raims webhook-event-types](/en/cli/commands/webhook-event-types): Inspect supported webhook event types - [raims webhooks](/en/cli/commands/webhooks): Manage webhook endpoints - [raims withdrawal-destinations](/en/cli/commands/withdrawal-destinations): Inspect withdrawal destinations - [raims withdrawals](/en/cli/commands/withdrawals): Inspect and request withdrawals ## `raims` Raims command-line interface ```bash raims [flags] ``` * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--help`, `-h` bool default: false * help for raims * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) * `--version`, `-v` bool default: false * version for raims **Detailed help description from the executable** ```text Use the Raims public API, manage local profiles and inspect the installed version and automatic updates. ``` **Command example** ```bash raims --map raims charges --map=compact raims --map=json ``` Subcommands: [`raims accounts`](/en/cli/commands/accounts#raims-accounts), [`raims auth`](#raims-auth), [`raims balances`](/en/cli/commands/balances#raims-balances), [`raims charges`](/en/cli/commands/charges#raims-charges), [`raims completion`](#raims-completion), [`raims config`](#raims-config), [`raims customers`](/en/cli/commands/customers#raims-customers), [`raims disputes`](/en/cli/commands/disputes#raims-disputes), [`raims docs`](#raims-docs), [`raims doctor`](#raims-doctor), [`raims help`](#raims-help), [`raims licenses`](#raims-licenses), [`raims login`](#raims-login), [`raims logout`](#raims-logout), [`raims mcp`](#raims-mcp), [`raims open`](#raims-open), [`raims payment-links`](/en/cli/commands/payment-links#raims-payment-links), [`raims profile`](#raims-profile), [`raims refunds`](/en/cli/commands/refunds#raims-refunds), [`raims simulations`](/en/cli/commands/simulations#raims-simulations), [`raims statements`](/en/cli/commands/statements#raims-statements), [`raims update`](#raims-update), [`raims version`](#raims-version), [`raims webhook-event-types`](/en/cli/commands/webhook-event-types#raims-webhook-event-types), [`raims webhooks`](/en/cli/commands/webhooks#raims-webhooks), [`raims withdrawal-destinations`](/en/cli/commands/withdrawal-destinations#raims-withdrawal-destinations), [`raims withdrawals`](/en/cli/commands/withdrawals#raims-withdrawals). ## `raims auth` Check API authentication for the selected profile ```bash raims auth [flags] ``` * `--help`, `-h` bool default: false * help for auth **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims auth check`](#raims-auth-check), [`raims auth status`](#raims-auth-status). ### `raims auth check` Validate the selected credential with a read-only account request ```bash raims auth check [flags] ``` * `--help`, `-h` bool default: false * help for check * `--show-headers` bool default: false * Show public response headers without credentials or cookies * `--timeout` duration default: 1m0s * Total request timeout, including retries and waits **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Validate the selected profile's API key or OAuth session with GET /v1/accounts/fees at https://api.raims.com. A successful check confirms access to this endpoint; other requests retain their own authorization and eligibility rules. ``` ### `raims auth status` Inspect local authentication metadata without reading credentials or using the network ```bash raims auth status [flags] ``` * `--help`, `-h` bool default: false * help for status **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) ## `raims completion` Generate the autocompletion script for the specified shell ```bash raims completion [flags] ``` * `--help`, `-h` bool default: false * help for completion **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Generate the autocompletion script for raims for the specified shell. See each sub-command's help for details on how to use the generated script. ``` Subcommands: [`raims completion bash`](#raims-completion-bash), [`raims completion fish`](#raims-completion-fish), [`raims completion powershell`](#raims-completion-powershell), [`raims completion setup`](#raims-completion-setup), [`raims completion zsh`](#raims-completion-zsh). ### `raims completion bash` Generate the autocompletion script for bash ```bash raims completion bash ``` * `--help`, `-h` bool default: false * help for bash * `--no-descriptions` bool default: false * disable completion descriptions **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Generate the autocompletion script for the bash shell. This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager. To load completions in your current shell session: source <(raims completion bash) To load completions for every new session, execute once: #### Linux: raims completion bash > /etc/bash_completion.d/raims #### macOS: raims completion bash > $(brew --prefix)/etc/bash_completion.d/raims You will need to start a new shell for this setup to take effect. ``` ### `raims completion fish` Generate the autocompletion script for fish ```bash raims completion fish [flags] ``` * `--help`, `-h` bool default: false * help for fish * `--no-descriptions` bool default: false * disable completion descriptions **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Generate the autocompletion script for the fish shell. To load completions in your current shell session: raims completion fish | source To load completions for every new session, execute once: raims completion fish > ~/.config/fish/completions/raims.fish You will need to start a new shell for this setup to take effect. ``` ### `raims completion powershell` Generate the autocompletion script for powershell ```bash raims completion powershell [flags] ``` * `--help`, `-h` bool default: false * help for powershell * `--no-descriptions` bool default: false * disable completion descriptions **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Generate the autocompletion script for powershell. To load completions in your current shell session: raims completion powershell | Out-String | Invoke-Expression To load completions for every new session, add the output of the above command to your powershell profile. ``` ### `raims completion setup` Plan shell completion setup or save a new completion script ```bash raims completion setup [flags] ``` * `--dry-run` bool default: false * Show the completion setup plan without writing a file * `--help`, `-h` bool default: false * help for setup * `--save` string default: empty * Save a new completion script to PATH without changing shell profiles * `--shell` string default: auto * Shell for completion: auto, powershell, bash, zsh or fish **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Detect a supported shell and show completion setup instructions. Use --shell to select one explicitly. Without --save, no file is written. With --save PATH, write a new script generated from the current command tree; the parent directory must exist and the destination must not exist. The command never edits shell profiles or loads the script. --dry-run shows the plan without writing a file. ``` **Command example** ```bash raims completion setup raims completion setup --shell powershell --save raims-completion.ps1 --dry-run raims completion setup --shell bash --save raims-completion.bash raims --output json completion setup --shell zsh ``` ### `raims completion zsh` Generate the autocompletion script for zsh ```bash raims completion zsh [flags] ``` * `--help`, `-h` bool default: false * help for zsh * `--no-descriptions` bool default: false * disable completion descriptions **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Generate the autocompletion script for the zsh shell. If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once: echo "autoload -U compinit; compinit" >> ~/.zshrc To load completions in your current shell session: source <(raims completion zsh) To load completions for every new session, execute once: #### Linux: raims completion zsh > "${fpath[1]}/_raims" #### macOS: raims completion zsh > $(brew --prefix)/share/zsh/site-functions/_raims You will need to start a new shell for this setup to take effect. ``` ## `raims config` Inspect local CLI configuration ```bash raims config [flags] ``` * `--help`, `-h` bool default: false * help for config **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims config path`](#raims-config-path). ### `raims config path` Show the configuration file path without creating it ```bash raims config path [flags] ``` * `--help`, `-h` bool default: false * help for path **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) ## `raims docs` Read public Raims documentation in the terminal ```bash raims docs [PATH] [flags] ``` * `--help`, `-h` bool default: false * help for docs * `--language` string default: br * Documentation language: br or en * `--offline` bool default: false * Read only an existing documentation cache, including an older copy * `--refresh` bool default: false * Download fresh public documentation instead of reading the cache * `--timeout` duration default: 1m0s * Documentation request timeout (for example 30s or 2m) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Read a public Raims documentation page without an API key. Use a path such as cli/configuration or /br/cli/configuration. Without a path, read the CLI guide in the selected language. The public source is cached for 24 hours. --offline reads an existing cache, including an older copy, and reports its age. --refresh downloads a new copy and fails if the download is unavailable. Markdown is printed as plain text; commands and links are not executed. ``` **Command example** ```bash raims docs raims docs cli/configuration raims docs /en/cli --language en raims --output json docs cli/automation --offline raims docs search webhooks ``` Subcommands: [`raims docs search`](#raims-docs-search). ### `raims docs search` Search public Raims documentation ```bash raims docs search QUERY... [flags] ``` * `--help`, `-h` bool default: false * help for search * `--limit` int default: 10 * Maximum documentation search results (1-50) **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--language` string default: br * Documentation language: br or en * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--offline` bool default: false * Read only an existing documentation cache, including an older copy * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) * `--refresh` bool default: false * Download fresh public documentation instead of reading the cache * `--timeout` duration default: 1m0s * Documentation request timeout (for example 30s or 2m) **Detailed help description from the executable** ```text Search public Raims documentation by title, path and content in the selected language. Results include the page URL and a plain text excerpt. Searches ignore case and accents. The search runs locally after reading the public source or its cache; your search terms are not sent to a search service. Use --limit to control how many results are shown. ``` **Command example** ```bash raims docs search webhooks raims docs search "chaves de API" --offline raims --output json docs search checkout --language en --limit 5 ``` ## `raims doctor` Check local configuration, permissions, installation and update policy ```bash raims doctor [flags] ``` * `--help`, `-h` bool default: false * help for doctor **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) ## `raims help` Help about any command ```bash raims help [command] [flags] ``` * `--help`, `-h` bool default: false * help for help **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Help provides help for any command in the application. Simply type raims help [path to command] for full details. ``` ## `raims licenses` Read the third-party notices included in this executable ```bash raims licenses [flags] ``` * `--help`, `-h` bool default: false * help for licenses **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Read the original third-party license, notice and patent texts included in this version. This local command does not require a profile or network access. ``` ## `raims login` Connect a profile through browser sign-in ```bash raims login [flags] ``` * `--help`, `-h` bool default: false * help for login * `--no-browser` bool default: false * Print the sign-in URL instead of launching a browser; keep this terminal open for the local callback **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Sign in through the Raims browser and authorize the CLI. Choose an environment explicitly. OAuth credentials are encrypted with a key held by the system credential store. Requires an interactive terminal; use API-key profiles in CI. Repeating login verifies and reuses an active authorization, or opens a new consent when it has expired or been revoked. A profile backed by an API key is never overwritten. ``` **Command example** ```bash raims login --profile personal --environment sandbox raims login --profile personal --environment sandbox --no-browser ``` ## `raims logout` Revoke an OAuth connection and remove its local profile ```bash raims logout [flags] ``` * `--help`, `-h` bool default: false * help for logout **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Revoke the selected OAuth connection, then remove its encrypted credentials and local profile. A failed revocation preserves the local session so you can retry. API-key profiles remain managed by 'profile remove'. ``` ## `raims mcp` Configure an AI client for the Raims MCP server ```bash raims mcp [flags] ``` * `--help`, `-h` bool default: false * help for mcp **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Show connection instructions and safe configuration snippets for the Raims remote MCP server. Your MCP client handles browser sign-in and consent. This group does not read an API profile, load credentials, contact the server or change an installed client's settings. ``` Subcommands: [`raims mcp setup`](#raims-mcp-setup). ### `raims mcp setup` Show MCP setup instructions or save a new configuration snippet ```bash raims mcp setup [flags] ``` * `--client` string default: all * MCP client: all, codex, claude-code or cursor * `--dry-run` bool default: false * Validate and show the setup plan without writing a file * `--help`, `-h` bool default: false * help for setup * `--save` string default: empty * Save a new standalone configuration snippet to PATH **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Show setup instructions for Codex, Claude Code or Cursor. OAuth uses the Raims browser sign-in and consent flow. Without --save, no file is written. With --save PATH and one --client, save a new standalone snippet; the destination must not exist and its parent directory must already exist. Merge the snippet into your client settings yourself, preserving other servers. The command never runs another client or edits an existing configuration. --dry-run validates the plan without writing a file. ``` **Command example** ```bash raims mcp setup raims mcp setup --client codex raims mcp setup --client cursor --save raims-mcp.json --dry-run raims mcp setup --client claude-code raims --output json mcp setup --client codex ``` ## `raims open` Open Raims documentation and Dashboard pages ```bash raims open [shortcut] [flags] ``` * `--help`, `-h` bool default: false * help for open **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Open a known Raims page in the default browser. Without a shortcut, list the available destinations. Non-interactive execution prints the URL without opening a browser. ``` **Command example** ```bash raims open docs raims open api raims open webhooks raims --no-input --output json open docs ``` ## `raims profile` Manage local profiles without storing API keys ```bash raims profile [flags] ``` * `--help`, `-h` bool default: false * help for profile **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims profile list`](#raims-profile-list), [`raims profile remove`](#raims-profile-remove), [`raims profile set`](#raims-profile-set), [`raims profile show`](#raims-profile-show), [`raims profile use`](#raims-profile-use). ### `raims profile list` List configured profiles ```bash raims profile list [flags] ``` * `--help`, `-h` bool default: false * help for list **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) ### `raims profile remove` Remove a local profile without revoking its API key ```bash raims profile remove NAME [flags] ``` * `--help`, `-h` bool default: false * help for remove **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) **Detailed help description from the executable** ```text Remove a named profile from local configuration. If it is the saved default, clear that selection without choosing another profile. The key and its environment variable remain unchanged. Repeating the command succeeds when the profile is already absent. ``` **Command example** ```bash raims profile remove old-project raims --output json profile remove old-project ``` ### `raims profile set` Save a profile using an API key environment variable name ```bash raims profile set NAME --api-key-env VARIABLE [flags] ``` * `--api-key-env` string required default: empty * API key environment variable name (uppercase letters, digits and underscores) * `--help`, `-h` bool default: false * help for set **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) ### `raims profile show` Show a profile, or the selected profile when no name is given ```bash raims profile show [name] [flags] ``` * `--help`, `-h` bool default: false * help for show **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) ### `raims profile use` Select the default local profile ```bash raims profile use NAME [flags] ``` * `--help`, `-h` bool default: false * help for use **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) ## `raims update` Inspect automatic updates ```bash raims update [flags] ``` * `--help`, `-h` bool default: false * help for update **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) Subcommands: [`raims update status`](#raims-update-status). ### `raims update status` Show the automatic update policy and installed versions ```bash raims update status [flags] ``` * `--help`, `-h` bool default: false * help for status **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) ## `raims version` Show the CLI version and build information ```bash raims version [flags] ``` * `--help`, `-h` bool default: false * help for version **Global options** * `--color` string default: auto * Terminal colors: auto, on or off (JSON and completion stay uncolored) * `--debug` bool default: false * Write diagnostic JSON events to stderr without credentials or command arguments * `--environment` string default: empty * Select sandbox or production for OAuth or an OAuth dry run; API keys determine their own environment * `--map` string default: empty * List the command tree without executing a command: tree, compact, paths or json * `--no-input` bool default: false * Disable interactive prompts (also enforced in CI and without a terminal) * `--output`, `-o` string default: text * Output format: text or json * `--profile` string default: empty * Use a profile for this command (overrides RAIMS\_PROFILE and the saved default) # Withdrawals (/en/financeiro/saques) This guide provides more information for the **Learn more** link in the **Request withdrawal** dialog. Open **My money / Withdrawals** in Production. Viewing withdrawals requires **Withdrawals**. Requesting one also requires **Request withdrawals** and **View Pix keys for withdrawals**. Withdrawals may be blocked on a limited account even when the user has these permissions. ## Available to withdraw The dialog shows three separate amounts: | Item | Type | Description | | --- | --- | --- | | Available balance | Total shown | May include funds that are not yet available for withdrawal. | | Blocked balance | Temporarily held | Funds related to disputes, reserves, or other restrictions. | | Available to withdraw | Usable amount | The maximum balance that can be used for a withdrawal request at that time. | **Use Available to withdraw as your reference** The total account balance may be higher than the amount available for withdrawal. ## Destination Pix key The withdrawal is sent to the Pix key registered under **Account / Settings / Pix key for withdrawals**. The key must belong to the same CNPJ as the company. Raims verifies ownership before saving the destination and again when each withdrawal is requested. Before confirming, review the masked key, bank, and ISPB shown in the dialog. If the destination is incorrect, select **Change Pix key** and register the correct key before requesting a withdrawal. ## Limits and fee These are the default conditions for Pix withdrawals: | Rule | Default amount | | ----------------------------------------------------------------------------- | -------------: | | Minimum amount per withdrawal | R$ 2,00 | | Daily account limit, from 06:00 to 06:00 the following day | R$ 50.000,00 | | Nighttime limit within the daily total, from 20:00 to 06:00 the following day | R$ 10.000,00 | | Fee for withdrawals below R$ 500,00 | R$ 1,00 | Times use the São Paulo time zone. The nighttime period runs from **20:00 to 06:00 the following day**. Manual and automatic withdrawals requested since **06:00** count toward the daily limit. During the nighttime period, they must also fit within the nighttime limit, which is part of the daily total. The daily limit resets at **06:00**. If you withdraw R$ 45.000,00 during the day, you can request up to R$ 5.000,00 at night, provided you have enough balance. Withdrawals being processed count toward the limit; a confirmed failure releases that amount. The dialog shows how much you can request at that time. The remaining amount accounts for withdrawals registered with Raims. A transfer made through another channel on the same account may reduce the limit accepted by the partner institution. Company-specific conditions may change the default amounts. In that case, the dashboard shows the limits registered for the account before confirmation. **The fee is deducted from the requested amount** The result shows the requested amount, the fee, and the net amount sent to the Pix key separately. ## Request and track ### Open the request Go to **My money / Withdrawals / Request withdrawal** and check the destination Pix key. Register a key first if the screen says there is no destination yet. ### Enter the amount Select **Use maximum available** to fill in the highest amount allowed at that time. ### Confirm the destination, fee, and your identity Review the details before selecting **Request withdrawal**. Confirm the action using your account's security method. ### Keep the identifier The screen shows the identifier used to find the request. Acceptance of the request does not yet confirm that the money has reached its destination. ### Track the status Check the list until the withdrawal completes or shows a failure. If the result is being checked, track the same identifier before requesting another withdrawal. ### Pending The request has been registered and is waiting for processing. ### Processing The transfer is still in progress. The balance remains reserved while the partner institution confirms the result. ### Completed The details show the amount sent by Pix, the fee, and the completion date. ### Failure or cancellation Open the details to read the guidance and make any necessary corrections before trying again. ## View withdrawal details 1. Go to **My money / Withdrawals** in the environment where the request was made. 2. Use the date, identifier, amount, or status filters to find the withdrawal. 3. Open the record and check the destination, requested amount, fee, net amount, and reported status. Track the same identifier while the result is being processed or checked. The request acceptance message does not confirm that the destination institution has credited the funds. # Automatic withdrawals (/en/financeiro/saques-automaticos) Automatic withdrawals use the company's verified withdrawal Pix key. An attempt takes place at the configured time when the available balance reaches the minimum amount. This setting is available in Production and requires **Withdrawals**, **Configure withdrawals**, and **View Pix keys for withdrawals**. Use the default key already verified under **Account / Settings / Pix key for withdrawals**. **Scheduling does not guarantee execution** A withdrawal is requested only when there is eligible balance and the Pix key still belongs to the company's CNPJ. Track the result under Withdrawals; the next scheduled execution is not proof of a transfer. **Configured time** Automatic withdrawals are enabled in Production and the selected time has arrived, using São Paulo time. **Account and Pix key** The account is eligible for withdrawals and is not limited. The default Pix key is still verified and belongs to the same CNPJ as the company. **Balance and limit** The eligible balance reaches the configured minimum. The remaining Pix limit allows a withdrawal of at least R$ 2,00. **Request the withdrawal** The attempt uses up to the remaining limit. Track the result under Withdrawals; the request does not confirm the transfer. **Skip this attempt** The balance stays in the account. Check the settings, account, Pix key, balance, and limit before waiting for another attempt. ## Configure ### Open withdrawal settings Go to **Account / Settings / Withdrawals** and select **Edit**. ### Enable automatic withdrawals First, register a withdrawal Pix key under the same CNPJ as the company. When saving activation or changing the amount and time while automatic withdrawals are enabled, confirm the action using your account's security method. The control may be unavailable to users without permission or when the company is limited. ### Set the minimum amount The dashboard accepts amounts between **R$ 2,00** and **R$ 1.000.000,00**. The attempt is skipped when the eligible balance does not reach the minimum. It is also skipped when the remaining Pix limit is below the minimum withdrawal amount of R$ 2,00. Each attempt requests up to the Pix limit available at that time. If the balance is higher, the remainder stays in the account for future attempts. ### Choose the time Choose the time for the daily attempt in 24-hour format. You can choose a daytime or nighttime hour; the applicable Pix limits depend on the time of the attempt. The Dashboard uses the São Paulo time zone and shows the next scheduled execution after the setting is saved. ## How the amount is handled The nighttime period starts at **20:00** and ends at **06:00 the following day**, using São Paulo time. During this period, the withdrawal must fit within both the nighttime limit and the remaining daily limit. | Limit | Period in São Paulo time | Default amount | | -------------------------------------- | ------------------------------------- | -------------: | | Daily, including nighttime withdrawals | From 06:00 to 06:00 the following day | R$ 50.000,00 | | Nighttime, within the daily limit | From 20:00 to 06:00 the following day | R$ 10.000,00 | The daily limit resets at **06:00**, when the daytime period begins. Manual and automatic withdrawals from the account share the same limit. For example, if R$ 45.000,00 has already been used in the daily cycle, up to R$ 5.000,00 remains for nighttime withdrawals, provided there is available balance. These are the default amounts. Company-specific conditions may change the account limits; the attempt uses the amounts applicable at that time. | Item | Type | Description | | --- | --- | --- | | Below the minimum | Does not run | The balance stays in the account for a future attempt. | | Between the minimum and R$ 499,99 | R$ 1,00 fee | The same fee rule for withdrawals below R$ 500,00 applies. | | R$ 500,00 or more | Fee does not apply | The R$ 1,00 deduction specified for amounts below the threshold does not apply. | | Limited account | Temporarily disabled | Manual and automatic withdrawals remain blocked while the account is limited. | ## Safe operation ### The next scheduled execution is missing Confirm that the setting was saved, the control is enabled, and the account is not limited. Reload the section to read the confirmed state. ### The scheduled time passed without a withdrawal Check the eligible balance, minimum amount, withdrawal Pix key, and withdrawal history. A scheduled attempt may be skipped when a condition is not met. ### I need to disable it temporarily Edit the setting, switch off the control, and save. Confirm that the interface now shows **Automatic withdrawal disabled**. - [Withdrawals](/en/financeiro/saques): Track generated requests and their final statuses. # Authorized applications (/en/integracoes/aplicativos) The **Integration / Authorized applications** page lists applications granted access to your account through the Raims authorization flow. The same authorization supports [MCP clients](/en/integracoes/mcp) and other compatible applications, including platform and service integrations. Each connection identifies the application, who authorized it, its environments, and its granted permissions. The application remains subject to the current permissions of the person who authorized it and to the account's rules. The **Authorized by** column shows the identifier of the person who granted access. Check this identifier to distinguish connections to the same application. Installing an application on another platform and authorizing access to Raims are separate steps. Complete the flow presented by the application and check the account on the Raims page before granting access. ## Authorize an application 1. Start the Raims connection in the compatible application. 2. Sign in on the Raims page opened in your browser. 3. Check the application and select its access under **Permissions**. 4. Select **Review** to check the application, account, environments, return destination, and permissions. 5. Choose **Authorize access** and complete the security confirmation when requested. 6. Return to the application to continue. Sign-in preserves the account's security controls, including MFA when requested. You do not need to share your Raims password with the application. The connection uses OAuth, so you do not need to create or enter an API key for the application. The name and icon help identify who is requesting access, but they are not a verification or partnership badge. If you do not recognize the request or do not want to grant the permissions, close the page without authorizing it. ## Permissions and environments Each operation has its own selection. Allowing charge creation does not grant viewing, updating, revoking, or refunding. Groups organize the matrix; they do not replace the individual operation choices. Suggested profiles fill a selection that you can review before authorizing. Use **Learn more** below an operation to check what it allows, its effects, and supported environments. For example, customer registration by tax ID can update an existing customer with the same tax ID. A new connection includes the environments permitted for your account and access. The selected permissions apply to those environments. Changing the Dashboard environment does not change an existing connection's scope. Renewing authorization does not expand its permissions or environments either. Editing lets you restore access included in the original authorization; other access requires a new connection started by the application. Consent authorizes the connection once. Granted operations can run without another approval screen for each task, while remaining subject to current permissions, limits, and Raims validation. If access or environments change while connecting, check the summary again before completing it. Authorization is not repeated automatically. ## View access Open **Integration / Authorized applications** to view applications, who authorized them, their environments, and their expiration. Members can view their own connections. **View company applications** extends the list to connections authorized by the owner and team. **Revoke team connections** also allows this viewing and revocation of other employees' connections, but not the owner's connections. To review a connection's permissions, select **Edit permissions** in its action menu, when available. Opening the editor, searching, and expanding groups does not change access. The application's row remains highlighted while the editor is open. Viewing company connections does not allow editing or revoking other people's access. Session and device permissions do not grant application management. An authorized administrator must grant these permissions; existing members do not receive them automatically. [API keys](/en/integracoes/chaves-api) have their own management page under **Integration / API keys**. ## Edit permissions Select **Edit permissions** in the connection's action menu, when available. Use **Search permissions...** to find access. Choose one of the **Suggested profiles** or expand the groups to adjust individual permissions. Select **Save changes** and complete the security confirmation. The profiles shown depend on the access already authorized for the application. **Current profile** reflects your selection, and each group shows how many permissions are selected. Searching filters the display without changing the selection. Check the groups before saving. Each item shows the operation's name and a description. **Learn more** opens its full explanation in this documentation without changing the selection. The person who authorized the connection and the account owner can edit its access, subject to both people's current permissions. Permission to view or revoke team connections does not automatically allow editing them. Editing lets you remove and restore permissions from the original authorization. Access that is no longer available can remain selected or be removed, but it can only be restored once it becomes available again. The selection does not override current permissions. To grant other access, start a new connection in the application. The environments, expiration, and credential stay the same. Removing a permission prevents its use in subsequent calls without undoing completed operations or deleting data the application already received. If another change makes the edit outdated, select **Discard changes and reload** and check the access before saving again. If saving fails, your selection is kept so you can check the message and try again. ## Revoke a connection 1. Find the application under **Authorized applications** and check the identifier in **Authorized by** and its environments. 2. Select **Revoke access** in its action menu. 3. Check the application and the authorizing person's identifier in the confirmation, then complete the action. Revocation prevents new calls authorized by that connection. It does not undo completed operations or delete data the external application already received. Signing out of the Dashboard does not replace revocation. To use a revoked application again, start a new connection in that application and review its permissions again. ## Track activity Open **Account / Activity log** to track accepted or declined authorizations, permission changes, revocations, and expirations. A security revocation caused by credential reuse also appears in the history. Automatic events are identified as **System**. Members can view their own activity. **View full audit log** allows viewing activity across the company. Recorded actions performed by an employee through an application preserve that employee's identity in the history. Viewing a connection or opening the editor without saving does not change its permissions. ## When a connection cannot be completed * If the request expired, was already used, or is unavailable, return to the application and start another connection. Reopening the same link does not renew the request. * If a temporary failure prevents loading the request, wait for the page's automatic retries. Only the query is repeated; authorization still requires your confirmation. * If access is denied, check the account and your current permissions. * If the application requests authentication again, start the connection and check the consent page presented by Raims. * If an operation's result is uncertain, check the resource before requesting another creation. ## Authorized operations The operations below can be selected individually when available for the account and the person authorizing access. The connection allows only those included in consent, and editing cannot add operations outside the original authorization. Selecting an environment does not replace this authorization. The descriptions preserve each public operation's rules; the OAuth connection supplies its credential. You do not need to create or enter an API key. | Item | Description | | --- | --- | | Retrieve account number | Get your company's financial account branch and account number in Raims. The request requires access to the Production environment and an approved, enabled account. Environments that can be authorized: Production. | | Get checkout customization | Check the company's checkout images, colors, support email and default payment methods in the authenticated environment. Environments that can be authorized: Sandbox and Production. | | Update checkout customization | Change checkout images, colors and support email. Omitted fields keep their current values. Uploading a new image may require checking its status until it is applied. Environments that can be authorized: Sandbox and Production. | | Prepare icon upload | Get a temporary URL to upload the image. After uploading the bytes, associate the returned ID with the checkout customization. Preparing the upload does not change the current image. Environments that can be authorized: Sandbox and Production. | | Prepare logo upload | Get a temporary URL to upload the image. After uploading the bytes, associate the returned ID with the checkout customization. Preparing the upload does not change the current image. Environments that can be authorized: Sandbox and Production. | | Discard image upload | Discard a logo or icon upload that has not yet been associated with the checkout. An expired upload can also be discarded. To remove an image that has already been applied, use the customization PATCH request. Environments that can be authorized: Sandbox and Production. | | Retrieve account context | Retrieve the public identity, business name, registration status, and environment of the account identified by the key. Use the response timestamp and revision to recognize outdated information. This request does not identify the person who created the key or confirm that a financial operation can be executed. Environments that can be authorized: Sandbox and Production. | | Get account fees | Check your company's current commercial terms for receiving Pix and boleto payments. Environments that can be authorized: Sandbox and Production. | | Retrieve current balance | Retrieves the total, blocked and available amounts for the authenticated company and environment. Amounts are in Brazilian real cents. The available balance accounts for blocks and does not confirm authorization for a withdrawal or refund. Environments that can be authorized: Sandbox and Production. | | Get expected receipts | Check the estimated pending receipts for the period and the projected total balance. These amounts are estimates and do not indicate availability for withdrawal. Environments that can be authorized: Sandbox and Production. | | List charges | Lists charges for the authenticated company and environment, with filters and cursor pagination. To move forward, use page.next_after in after while page.has_next is true, keeping the filters and sorting unchanged. Status changes can take a few seconds to appear in filters; wait before requesting again. Environments that can be authorized: Sandbox and Production. | | Create a new charge | Creates a charge for an existing customer. Send the amount in cents. Without a custom payment method list, payment_method 1 requests Pix and 2 requests boleto, with the details available in payment_information. Boleto uses the customer's name, valid email, CPF/CNPJ, and address. Missing street, neighborhood, city, and state details may be filled from the postal code (CEP) when available; the number and address complement come from the customer's record. With a custom list, issuance takes place after a method is chosen in the checkout. Use create_checkout true to get the link without requesting an email. A return URL or send_email true also generates the link; only send_email true requests an email to be sent. Environments that can be authorized: Sandbox and Production. | | Revoke a charge | Revokes an open charge for the authenticated company and environment, preserving its history. In Sandbox, cancellation is simulated. In Production, revocation may await confirmation. Environments that can be authorized: Sandbox and Production. | | Retrieve a single charge | Retrieves a charge's details, status, and available payment instructions for the authenticated company and environment. Environments that can be authorized: Sandbox and Production. | | Update an existing charge | Updates a charge's title, description, external reference, and integration data for the authenticated company and environment. You can update metadata alone even after payment or refund. Changes to other fields remain subject to the charge's state; if any field cannot be changed, none of the changes in the request are applied. Environments that can be authorized: Sandbox and Production. | | Download boleto | Get a temporary URL to download the PDF of an issued boleto, including before payment. The request requires a key for the same company and environment and does not issue or renew the boleto. The document is not proof of payment. In Sandbox, the PDF identifies the simulation and must not be used for payment. Environments that can be authorized: Sandbox and Production. | | Get payment details | Get the amount, date and confirmed payment method for a charge. For Pix receipts, end_to_end_id provides the bank transaction ID when available. The charge must be paid, partially refunded or have a won dispute, with the payment date recorded. The request uses the authenticated company and environment. Environments that can be authorized: Sandbox and Production. | | Download payment receipt | Get a temporary URL to download a confirmed payment receipt as a PDF. The charge must be paid, partially refunded or have a won dispute, with the payment date recorded. The receipt shows the original amount of the paid charge; refunds have their own receipts. The document is issued by Raims and does not replace a tax invoice or bank receipt. The request uses the company and environment authorized for the connection. Environments that can be authorized: Sandbox and Production. | | Check refund eligibility | Check whether a charge accepts a refund request, the remaining amount, the maximum available to request now and pending amounts. Conditions are checked again when requesting the refund. Environments that can be authorized: Sandbox and Production. | | List refunds for a charge | List refund requests for a charge, from newest to oldest, with cursor pagination. The query does not initiate or repeat refunds. Environments that can be authorized: Sandbox and Production. | | Request a refund | Request a full or partial refund of a received Pix payment. In Production, the amount returns to the source account and an accepted request still requires confirmation. In Sandbox, the simulation completes within the request, without moving real money. Environments that can be authorized: Sandbox and Production. | | Get charge statistics | Check charge counts, amounts and payment rates to track receipts in your ERP or management system. The request uses the authenticated company and environment. It may take a few seconds for the data to reflect changes to charges. Environments that can be authorized: Sandbox and Production. | | Delete customers in bulk | Deletes up to 100 customers for the authenticated company and environment in one request. Check each identifier's result in removed, blocked, or invalid. Charges that have not been deleted prevent customer deletion, including paid charges. Repeated identifiers are processed once; customers already deleted appear in removed. Deleting customers does not delete charges or refund amounts. Environments that can be authorized: Sandbox and Production. | | List customers | Lists customers for the authenticated company and environment using the provided filters, with cursor pagination. Send the parameters in the URL, without a request body. Environments that can be authorized: Sandbox and Production. | | Create a customer | Creates a customer in the authenticated company and environment. If the CPF or CNPJ is already registered, updates that customer and keeps its identifier. When only the postal code (CEP) is provided as the address, street, neighborhood, city, and state may be filled automatically. Returns 201 when creating and 200 when updating. Environments that can be authorized: Sandbox and Production. | | Delete a customer | Deletes a customer by public ID for the authenticated company and environment. Deletion is allowed only when no linked charges remain undeleted, including paid charges. It does not delete charges or refund amounts. Repeating the request for the same customer after deletion returns the same ID with deleted: true. The request has no body. Environments that can be authorized: Sandbox and Production. | | Retrieve a single customer | Retrieves a customer's registration details by public ID for the authenticated company and environment. The request has no body. Environments that can be authorized: Sandbox and Production. | | Update an existing customer | Updates the submitted registration fields and the customer's integration data. Omitted fields keep their current values. For text fields, null or an empty string clears the content; metadata follows the rules described for that field. CPF/CNPJ, ID and creation date remain unchanged. The postal code (CEP) does not populate other address fields in this request. Sending {} returns the current customer record. Environments that can be authorized: Sandbox and Production. | | List disputes | View disputes for the authenticated company and environment, with filters and cursor pagination. Environments that can be authorized: Sandbox and Production. | | Retrieve a dispute | View the stage, reasons and available results of a dispute in the authenticated company and environment. Environments that can be authorized: Sandbox and Production. | | List payment links | Lists links in the authenticated company and environment, in descending order of their linked charges. Use charge_id to find a charge's link and page.next_after to continue. Environments that can be authorized: Sandbox and Production. | | Create or retrieve a payment link | Creates the link for an existing charge or returns the same link when one already exists. Provide charge_id. A new link starts active; reusing a paused link keeps it paused. Title, amount, due date and customer come from the charge. This request does not create another charge, issue payments or request an email. Environments that can be authorized: Sandbox and Production. | | Retrieve a payment link | Looks up the URL, configuration and current availability of the link. is_active indicates whether the link is active; is_payable indicates whether checkout can accept payment at this time. The link must belong to the authenticated company and environment. For amount, due date, customer and financial status, use GET /v1/charges/{charge_id}. Environments that can be authorized: Sandbox and Production. | | Update a payment link | Updates return URLs, payment methods and the link's pause setting. Send is_active false to pause and true to reactivate the same URL; omitting it keeps the state. Pausing blocks new checkout actions and new email requests without canceling issued Pix or boleto or extending the due date. The charge must be open and within its due date. Use clear_success_redirect_url or clear_cancel_redirect_url with true to remove the corresponding destination. Environments that can be authorized: Sandbox and Production. | | Email a payment link | Requests that the link be sent or resent to the charge's recipient without creating another charge or changing checkout. The charge must be open and within its due date. The minimum 60-second interval between accepted requests is shared with the Dashboard's resend action. The response confirms the email request, not email delivery. Sandbox can also send real emails. The link must be active; pausing prevents emails. Environments that can be authorized: Sandbox and Production. | | List refunds | List refund requests for charges in the authenticated company and environment, from newest to oldest. Use pagination to reconcile refunds without querying each charge. The query does not initiate or repeat refunds. Environments that can be authorized: Sandbox and Production. | | Retrieve a refund | View the status, amount, dates and available reason for a confirmed refund failure. The query does not initiate or repeat the refund. Environments that can be authorized: Sandbox and Production. | | Download a refund receipt | Get a temporary URL to download the PDF receipt for a completed refund. The document shows the ID, amount and completion date of that refund. For charges with more than one refund, query each desired ID. The request must be in completed, with a recorded completion date. The request uses the company and environment authorized for the connection. The document is issued by Raims and does not replace a tax invoice or bank receipt. Environments that can be authorized: Sandbox and Production. | | Simulate boleto clearing | Record a boleto as cleared, still awaiting settlement. This step does not credit the balance or make a completed payment receipt available. Environments that can be authorized: Sandbox. | | Confirm payment | Confirm payment of a test charge and check the credit in the Sandbox balance. Environments that can be authorized: Sandbox. | | Simulate payment failure | Simulate failure of an open charge to test how this result is handled in Sandbox. Environments that can be authorized: Sandbox. | | Issue a test payment | Issue Pix or boleto for an existing charge in Sandbox. A scenario prepared for this issuance determines whether it remains pending or fails. Environments that can be authorized: Sandbox. | | Simulate a pending refund | Start a test Pix refund that awaits confirmation. Use the returned ID to complete the refund or simulate a failure. Environments that can be authorized: Sandbox. | | Resolve a pending scenario | Complete or fail issuance or cancellation left pending in the test scenario. The action must have been started on the charge. Environments that can be authorized: Sandbox. | | Prepare a scenario | Choose a pending result or failure for Pix or boleto issuance, or for canceling a charge in Sandbox. Then execute the action on the same charge. Environments that can be authorized: Sandbox. | | Complete a simulated refund | Complete a pending Pix refund in Sandbox. The amount is not deducted from the balance again. Environments that can be authorized: Sandbox. | | Simulate refund failure | Simulate failure of a pending Pix refund in Sandbox and check the return of the amount to the available balance. Environments that can be authorized: Sandbox. | | Retrieve statement | Retrieve statement entries for the authenticated company and environment. Filter by period, entry type or reference and browse the results using the returned cursors. Positive amounts represent incoming funds or releases; negative amounts represent outgoing funds, fees or holds. A financial confirmation may take a few moments to appear in the statement. Environments that can be authorized: Sandbox and Production. | | Retrieve a statement entry | View a statement entry by ID, with its amounts and available links, in the authenticated company and environment. Environments that can be authorized: Sandbox and Production. | | List available events | Query the codes that can be selected when creating or updating a webhook. The technical test webhook.test is requested through the test endpoint and is not included in the webhook's event list. Environments that can be authorized: Sandbox and Production. | | List webhooks | Query destinations registered in the authenticated company and environment, including disabled ones. To move forward, copy page.next_after to after. The list does not return signing secrets. Environments that can be authorized: Sandbox and Production. | | Create a webhook | Register the HTTPS address that will receive the selected events for the authenticated company and environment. Store the id to manage the destination and the secret_key to validate signatures. Queries of the webhook configuration do not return the secret. Environments that can be authorized: Sandbox and Production. | | Delete a webhook | Delete a destination that will no longer be used. Deletion prevents new deliveries, but a request already authorized or in progress may finish. Available history remains queryable, including by the deleted webhook_id. Environments that can be authorized: Sandbox and Production. | | Retrieve a webhook | Query a webhook's URL, subscribed events and status. The signing secret is not returned in this query. Environments that can be authorized: Sandbox and Production. | | Update a webhook | Change a webhook's name, URL, event selection or activation. Send only the fields you want to change; omitting a field preserves its value. The submitted event selection replaces the previous one. Fields do not accept null or empty values. Environments that can be authorized: Sandbox and Production. | | Query webhook failures | Query the known destination status and how long its deliveries have been failing. The data reflects available sending results and may take some time to appear after an attempt. The query does not call the destination. The healthy state indicates a known success; it does not guarantee that the address is still available. The unknown state indicates that there is not yet enough data to report the status. Environments that can be authorized: Sandbox and Production. | | Pause or resume deliveries | Pauses deliveries for an active webhook without deactivating it. New events and pending deliveries wait for deliveries to resume while they remain within their original deadline. Pausing does not extend that deadline: 72 hours in Production and 4 hours in Sandbox. Send is_paused false to resume deliveries that are still valid. Resuming follows sending limits, without guaranteeing an order or time. Explicitly sending a test event remains available while paused. Environments that can be authorized: Sandbox and Production. | | Rotate the signing secret | Replace the secret used to sign events, keeping the webhook identifier and configuration. Store the returned secret_key and update the receiver during the transition period. Repeating a rotation with a positive period while the transition is active returns the same secret and expiry time. To revoke previous secrets, send grace_period_seconds equal to zero: a new signature is generated, including during an active transition. Requests already authorized or in progress may arrive with the previous signature. Environments that can be authorized: Sandbox and Production. | | Send a test event | Send webhook.test to check receipt and signature validation for an active webhook. The request does not accept a body. The test makes one HTTP attempt within five minutes and does not change charges, balance or the destination failure count. Acceptance of the request does not confirm delivery. Check receipt in the receiver's logs. Environments that can be authorized: Sandbox and Production. | | List withdrawal destinations | Retrieve verified Pix destinations owned by the company and identify the default before requesting a withdrawal. The query requires access to the Production environment. Environments that can be authorized: Production. | | Retrieve a withdrawal destination | Retrieve a Pix destination owned by the company using the ID received in the listing. The response shows the masked key and indicates whether it is the current default. Use the Production environment. Environments that can be authorized: Production. | | List withdrawals | Retrieve your company's withdrawal history. Use status and period filters to track transfers and check outgoing statement entries. The query uses the authenticated environment. Environments that can be authorized: Sandbox and Production. | | Request a withdrawal | Request a Pix withdrawal to the company's default key registered in the Dashboard. The requested amount includes the fee. To require the default destination you checked, provide expected_destination_id. Keep the identifier and track the same withdrawal while its result is pending. Environments that can be authorized: Production. | | Retrieve a withdrawal | Retrieve a withdrawal's status, amounts and destination by ID. Use the same ID shown in the withdrawal history or statement reference. Environments that can be authorized: Sandbox and Production. | | View automatic withdrawals | View whether company withdrawals are enabled, the minimum amount, daily time and next scheduled attempt. The query requires access to the Production environment. Environments that can be authorized: Production. | | Update automatic withdrawals | Enable, disable or adjust the daily withdrawal attempt for the selected company destination. Use the Production environment. Omitted fields preserve their current values; saving does not request an immediate withdrawal. Environments that can be authorized: Production. | | Retrieve withdrawal conditions | Retrieve the available balance, minimum amount, fee and withdrawal limits to plan a withdrawal. The query does not reserve funds or limit capacity and does not guarantee that a request will be accepted. Environments that can be authorized: Sandbox and Production. | | Retrieve withdrawals in progress | Retrieve the count and total amount of the company's pending or processing withdrawals. The query requires access to the Production environment and does not change the progress of requests. Environments that can be authorized: Production. | # Authentication (/en/integracoes/autenticacao) The Raims API accepts API keys and OAuth access from authorized applications. Use an API key in your integration's backend. To work in the terminal, you can also connect Raims CLI through your browser. Both modes use the `Authorization` header with the **Bearer** scheme. The credential and current access determine which requests can be executed. ## Before you start Create an API key for the environment your application will use. See [API keys](/en/integracoes/chaves-api) to obtain and manage the credential. To integrate with a client for your language, see the [official SDKs](/en/integracoes/sdks). Each guide explains the installation channel and how to configure the credential on your backend. Store the secret in a secrets vault or a protected environment variable, accessible only to the backend responsible for the integration. **Protect your API key** Do not expose the key in frontend applications, distributed apps, images, logs, or repositories. Send the secret only in the authentication header, never in the URL or request body. ## OAuth in the CLI Run `raims login --profile pessoal --environment sandbox` and complete authorization in your browser. Check the account, environments, and permissions before authorizing. The CLI protects the session through the operating system and refreshes access while the connection remains valid. See [Configuration and profiles](/en/cli/configuration#conectar-pelo-navegador). OAuth requests use an access token issued for the public API and set `X-Raims-Environment` to `Sandbox` or `Production`. The CLI fills this header from the selected environment. Selecting an environment does not grant access: the environment and request must be authorized for the connection and the person who approved it. A token from an MCP connection does not authenticate direct public API calls. Each connection uses access issued for its destination. To end the CLI's OAuth access, run `raims logout --profile pessoal`. ## Authentication header When using an API key, configure your backend HTTP client with the following headers when sending a JSON body: ```json { "Authorization": "Bearer SUA_CHAVE_API", "Content-Type": "application/json" } ``` | Header | Usage | | --------------- | ------------------------------------------------------------------------------------------- | | `Authorization` | Required for authenticated requests. Use `Bearer` followed by a space and the complete key. | | `Content-Type` | Send `application/json` when the request has a JSON body. | `GET` requests must use the parameters defined by the endpoint and have no body. The key identifier, a masked secret, or a Dashboard login credential cannot replace the API key. Use HTTPS for API calls. Send the secret exactly as generated, without changing letters or adding characters. ## Sandbox and Production The base URL is the same in both environments: ```text https://api.raims.com ``` With an API key, the key sent in the `Authorization` header determines the environment and company. Do not send another header or a field in the URL or body to choose the environment. `X-Raims-Environment` is used only with OAuth; sending it with an API key does not change the request's environment. | Environment | Key prefix | Usage | | ----------- | ---------- | ---------------------------------------------------------------------------------- | | Sandbox | `sk_test_` | Development and integration testing, with test data separate from Production data. | | Production | `sk_live_` | Requests with real effects on the account, sent by your backend. | Validate the integration in Sandbox before using Production. To change environments, update the key configured in your backend and check the data and identifiers being sent. Changing the credential does not move a resource created in Sandbox into Production. ## Key permissions An API key must include the requested action in its permissions. Viewing, creating, updating, deleting, and other actions are selected separately. For example, allowing charge creation does not allow revoking charges or requesting refunds. Company and environment rules still apply. `403 API_KEY_PERMISSION_DENIED` means the key does not authorize the operation. Ask someone with **Edit API keys** to review access in **Integration / API keys / Edit permissions**. Resending the same request or changing the environment header does not add permissions. See [Key permissions](/en/integracoes/chaves-api#permissões-da-chave) to configure the integration's access. ## IP restrictions If the key has IP restrictions, requests must originate from an authorized address. Configure the public outbound IP of the server or infrastructure running your backend, including the authorized ranges when using CIDR. See [IP restrictions](/en/integracoes/chaves-api#restrições-de-ip) to configure the allowed ranges. ## Authentication errors A `401 Unauthorized` response means the request could not be authenticated. Check that: * `Authorization` contains `Bearer`, a space, and the complete key; * the key is correct, with no extra characters or missing parts; * the credential belongs to the intended company and environment; * the key remains valid and has not been revoked or replaced through rotation. After rotating a key, update your backend configuration with the new secret. The previous key no longer authenticates requests. For an expired or revoked OAuth session, sign in again through the CLI. Also check that the request and environment are among the granted permissions. Refreshing the session does not add permissions to the original authorization. A `403 Forbidden` response may indicate a missing key permission, an IP restriction, an account condition, or another authorization rule. A valid key does not allow a request blocked by those conditions. `COMPANY_STATUS_RESTRICTED` means the company's status prevents access. Suspended companies or companies with a closed account cannot use the API in either environment. A pending registration allows Sandbox only. The message identifies the condition and directs you to Customer Service or to check the registration in the Dashboard. See [HTTP response codes](/en/api/codigos-http-das-respostas) to interpret the status, code, and message returned by the API. # API keys (/en/integracoes/chaves-api) The **Integration / API keys** area manages the credentials used to connect your company's system to Raims. Sandbox and Production keys belong to separate environments and must not be reused between them. Viewing keys requires **API keys**. Creating, rotating, renaming, editing access, revoking, and managing IPs have their own permissions. These actions may also be blocked when the account is in view-only mode. Use these credentials to [authenticate requests to the Raims API](/en/integracoes/autenticacao). The key's access is always defined by its saved selection. An empty selection does not authorize any API operation. Viewing logs also requires **View request logs**. This access allows you to read the details and request and response bodies available in the history. Access to keys does not automatically grant access to logs. See [how to grant this permission to your team](/en/usuarios-e-permissoes#integracao-api_keys_view_logs). **Keep the key secret** Never put a Raims key in a browser, distributed apps, repositories, screenshots, or logs. Keep the credential in the private part of the system responsible for the integration. ## Create a key ### Open API keys Go to **Integration / API keys / Create new API key** with **Create API keys**. Check the selected environment before creating the key. If prompted, confirm your identity to open the form. Accounts without access to Production can create Sandbox keys only. ### Give it an operational name Enter the **Key name** and check the **Key type**. Use a name that identifies the system and environment, such as **ERP - Sandbox** or **Main integration - Production**. ### Choose access In **API permissions**, select only the actions the integration needs. Viewing, creating, updating, deleting, and other actions have independent selections. Use **Learn more** to check what each action allows. The selection starts empty. ### Restrict the source when possible If the system uses fixed outbound addresses, allow only those IPv4 addresses or CIDR ranges. ### Copy and store it immediately After completing the form, select **Create**. Complete identity confirmation when requested; creation continues automatically without another click on **Create**. Copy the displayed secret and save it in a secrets vault before closing the dialog. ## Separate environments ### Sandbox Test keys use placeholders such as `sk_test_...` and are for development and integration testing. They do not process real money. ### Production Production keys use placeholders such as `sk_live_...` and can authorize requests with real effects on the account. Use them only after the integration has been approved and is ready for Production. The [API reference](/en/api) presents authentication, fields, and examples for each request. The console accepts Sandbox keys for testing the integration. ## Secure storage Use a secrets manager or a protected variable in the environment where the integration runs. Example files must contain only the variable name: ```dotenv title=".env.example" RAIMS_API_KEY=sk_test_... ``` Do not commit a real `.env` file. Limit access to the people and systems that need to use the integration. ## Key permissions Each key has a selection of API actions. You can allow creating a charge without allowing queries, updates, revocations, or refunds. Selecting an action does not automatically grant the other actions for that resource. Account and environment rules still apply. Key permissions are separate from an employee's permissions to manage the key in the Dashboard. The tables below explain each action offered in the matrix and its **Learn more** link. To copy a Sandbox key's secret or rotate a key, an employee must have access to every resource and action it allows. When a key grants access beyond their own, it remains in the list with its secret hidden, and copying and rotation are unavailable. Ask an authorized person to review the key; viewing its metadata does not grant access to the secret. ## Edit permissions 1. Go to **Integration / API keys** and open the actions for the key. 2. Select **Edit permissions** and review the current access. 3. Adjust the action selection and choose **Save permissions**. 4. Complete the security confirmation when prompted. This action requires **Edit API keys**. Editing preserves the key's secret; you do not need to replace the token in the integration. Grant only the access required. Your own access also limits which permissions you can grant. If someone else changes the key while you edit it, load the current selection, review the differences, and save again. Do not confirm an old selection without checking the change. A request without the required access receives `403 API_KEY_PERMISSION_DENIED`. Check the key's permissions before retrying. See [Authentication](/en/integracoes/autenticacao#permissões-da-chave). ## IP restrictions The Dashboard accepts an individual IPv4 address, such as `203.0.113.10`, or a CIDR range, such as `203.0.113.0/24`. Use only stable outbound addresses confirmed by your infrastructure. Enter the four decimal IPv4 numbers separated by periods, without leading zeros. Each number must be between `0` and `255`. For a CIDR range, add `/` and an integer prefix from `0` to `32`, with no sign or leading zeros. The range includes the entire network indicated by the prefix. For example, `203.0.113.7/24` appears as `203.0.113.0/24` and covers `203.0.113.0` through `203.0.113.255`. The `/32` prefix appears as an individual IP. Entries that represent the same range appear only once. Check the list before saving, especially when entering a shorter prefix, which allows a larger range of addresses. | Item | Type | Description | | --- | --- | --- | | No restriction | Larger risk surface | Any source that obtains the secret can try to use it. | | Individual IPv4 | Specific source | Suitable when the system always connects from the same address. | | CIDR | Controlled range | Useful for a known set of outbound addresses; avoid broad networks. | ## Rename a key 1. Go to **Integration / API keys** and open the actions for the key. 2. Select **Rename key**, enter the new name, and confirm **Rename key**. 3. Wait for confirmation and check the name in the list. This action requires **Edit API keys**. It changes only the displayed name; existing integrations continue using the same secret. ## Rotate a key 1. Go to **Integration / API keys** and open the actions for the correct key. 2. Select **Rotate key token**, check the notice, and confirm **Rotate token**. 3. Copy and store the new secret before closing the dialog. 4. Update the systems that used the previous token. This action requires **Rotate API keys**. Employees must also have access to every resource and action granted by the key. Rotation replaces the previous secret; the key keeps the settings shown. ## Manage IP restrictions 1. Go to **Integration / API keys** and open the key's actions. 2. Select **Manage IP restrictions**. 3. Add, edit, or remove only the IPv4 addresses and CIDR ranges used by your system. Check the confirmation for each change. 4. Use **Download list** if you need to save the configured addresses. Changes require **Manage API IPs**. Read **IP restrictions** in this guide before defining a network range. An empty list leaves the key without source restrictions. ## Revoke a key 1. Go to **Integration / API keys** and open the actions for the key you want to disable. 2. Select **Revoke API key**, check the identified token, and confirm **Revoke key**. 3. Wait for **Key revoked**. This action requires **Delete API keys** and revokes the key. Systems that still depend on that token must be updated with another valid credential. ## Account and checkout actions | Item | Description | | --- | --- | | View account information | Views the company's identity, status, fees, and financial account details when available. It does not change registration data. Bank account details remain subject to environment and account eligibility rules. | | View checkout settings | Views checkout images, colors, support email, and default payment methods. It does not change settings or create a charge. | | Update checkout settings | Updates the checkout fields accepted by the API, such as images, colors, and support email. To upload a new image, also select Prepare image uploads. Changing checkout settings does not confirm payments. | | Prepare image uploads | Obtains temporary authorization to upload a checkout logo or icon. Uploading an image does not apply it automatically; applying it requires Update checkout settings. | | Discard an image upload | Discards a logo or icon upload that has not been applied, including an expired upload. It does not remove the current checkout image. Use Update checkout settings for that action. | ## Balance queries | Item | Description | | --- | --- | | View balances and forecasts | Views total, blocked, and available balances, plus expected receipts. It does not request withdrawals or set aside funds. A forecast does not guarantee that funds are available. | ## Statement queries | Item | Description | | --- | --- | | View statements | Lists statement entries and retrieves an entry by its identifier, including available amounts and references. It does not create entries or change balances. | ## Customer actions | Item | Description | | --- | --- | | View customers | Lists customers using the API's filters and pagination and retrieves a customer by identifier. It does not allow creating, updating, or deleting customers. | | Create a customer by tax ID | Creates a customer or updates an existing customer with the same tax ID. The tax ID registration request has this behavior even when the separate update action is not selected. An existing customer's identifier is preserved. | | Update a customer by identifier | Updates allowed fields on the customer identified in the request, preserving omitted fields. It does not change the tax ID or create another customer. Integration data follows the metadata field rules. | | Delete customers | Deletes one customer or requests a batch deletion. Linked charges that have not been removed can block the action. This permission does not delete charges or refund payments. | ## Charge actions | Item | Description | | --- | --- | | View charges | Lists and retrieves charges, statistics, payment details, and available documents such as boletos and receipts. Queries do not issue another payment or confirm receipt. Creating, updating, revoking, and refunding are separate actions. | | Create charges | Creates a charge for a registered customer using the payment methods and options accepted by the API. Depending on the request, it can issue Pix or a boleto, create a link, and request an email. It does not allow retrieving, updating, revoking, or refunding charges. | | Update charges | Changes the charge fields accepted by the update endpoint, subject to its current status. It does not change a payment or request a cancellation or refund. | | Revoke charges | Requests cancellation of a charge that can be revoked. History remains available, and completion may require confirmation. Revoking does not return a received payment; that requires Request a Pix refund. | ## Refund actions | Item | Description | | --- | --- | | View refunds | Views refund eligibility, refundable amounts, requests, history, and receipts. It does not initiate or repeat a refund. Eligibility can change before a request is submitted. | | Request a Pix refund | Requests a full or partial refund of a received Pix payment. Remaining refundable amount, balance, status, and other API conditions still apply. To track the result or download its receipt, also select View refunds. | ## Payment link actions | Item | Description | | --- | --- | | View payment links | Lists and retrieves payment link URLs, settings, and availability. It does not create or update links. Financial charge details require View charges. | | Create payment links | Creates or retrieves a link for an existing charge. An existing link and its paused state are preserved. It does not create another charge or request an email. | | Update payment links | Updates allowed link fields, including return URLs, accepted methods, and pause or resume settings. Pausing does not cancel an issued Pix or boleto or extend the charge due date. | | Send payment links by email | Requests an email or resend to the charge recipient, subject to link conditions and the interval between requests. It does not create another charge. Acceptance confirms the request, not email delivery. Sandbox can also send real emails. | ## Withdrawal actions | Item | Description | | --- | --- | | View withdrawals and destinations | Views withdrawals, amounts in progress, limits, and available company-owned Pix destinations. It does not request a withdrawal or change the default destination. Some details and destinations require Production. | | Request Pix withdrawals | Requests a withdrawal to the company's default destination, subject to balance, fees, limits, and account rules. It does not register another destination. To track the request, also select View withdrawals and destinations. | | View automatic withdrawal settings | Views whether automatic withdrawals are enabled, the minimum amount, schedule, and next planned attempt. The query requires Production and does not start a withdrawal. | | Configure automatic withdrawals | Enables, disables, or changes automatic withdrawal settings accepted by the API in Production. Saving does not request an immediate withdrawal or register another destination. | ## Dispute queries | Item | Description | | --- | --- | | View disputes | Lists and retrieves disputes, including their stage, reason, and available results. It does not submit evidence, accept a refund, or close a dispute. | ## Webhook actions | Item | Description | | --- | --- | | View webhooks | Views destinations, settings, event types available for subscription, and known failure status. It does not return the signing secret or modify a webhook. Creating, updating, deleting, pausing, testing, and rotating are separate actions. | | Create webhooks | Registers an HTTPS destination and its subscribed event types. The creation response provides the secret used to verify signatures; store it securely. It does not allow updating or deleting other destinations. | | Update webhooks | Updates accepted destination fields, such as name, URL, subscribed event types, and activation. A submitted event list replaces the previous selection. Pausing deliveries and rotating the secret have separate permissions. | | Delete webhooks | Deletes an unused destination and prevents new deliveries. An already authorized or in-progress attempt may finish. It does not change financial resources related to the events. | | Rotate a webhook signing secret | Replaces the signing secret and returns the new value so the receiver can be updated. Destination settings and identity are preserved. The transition period and immediate revocation follow the API options. | | Pause or resume webhook deliveries | Pauses deliveries for an active webhook or resumes deliveries that are still valid. Pausing does not extend their deadline, and resuming does not guarantee order or timing. An explicit test requires Test webhooks. | | Test webhooks | Requests a technical test event for an active destination. Acceptance does not prove receipt; check the receiver's logs. The test does not confirm payments or change balances. | ## Simulation actions | Item | Description | | --- | --- | | Confirm a test payment | Confirms a test charge payment and applies the corresponding Sandbox effects. It does not move real money and cannot be used with a Production key. | | Simulate a payment failure | Marks an open Sandbox charge as failed to test how that result is handled. It does not fail or cancel a real payment. | | Prepare a test scenario | Prepares a pending or failed Pix or boleto issuance, or a cancellation scenario, for a Sandbox charge. The corresponding normal action must still be executed and requires its own permission. | | Resolve a pending test scenario | Completes or fails an issuance or cancellation that was started and left pending by a Sandbox scenario. It does not create another charge or resolve real operations. | | Issue a test payment | Issues a test Pix or boleto for an existing Sandbox charge. Its configured issuance scenario can produce a pending or failed result. Issuance does not confirm payment. | | Simulate boleto compensation | Records a Sandbox boleto as compensated while it still awaits settlement. This step does not credit the balance or provide a completed payment receipt. Confirming payment is a separate action. | | Start a pending test refund | Starts a Sandbox Pix refund that awaits confirmation. Use the returned identifier to complete the refund or simulate its failure with the corresponding permissions. | | Complete a test refund | Completes a pending Sandbox Pix refund without deducting the amount again. It does not complete a real refund or create another refund request. | | Simulate a refund failure | Fails a pending Sandbox Pix refund and returns its amount to the available test balance. It does not affect Production refunds or balances. | - [Webhooks](/en/integracoes/webhooks): Configure notifications and secrets separately from API keys. - [Users and permissions](/en/usuarios-e-permissoes#integracao): Separate access to keys and logs, creation, rotation, revocation, and IP management. - [Start here](/en/api): Prepare your Sandbox credential and learn how to use the API console. # Raims MCP (/en/integracoes/mcp) Raims MCP lets an AI application read data and request operations in the account you authorize. One connection covers the company's permitted environments and the access defined during consent. ```text https://mcp.raims.com ``` Signing in to the AI application and signing in to Raims are separate steps. The application does not need your Raims password or a Public API key. The current permissions of the person who authorized the connection continue to limit access. MCP uses the general [Authorized applications](/en/integracoes/aplicativos) authorization flow. The same permission page and list support other compatible applications that connect your account to Raims. In authenticated applications, `search_raims_documentation` searches public documentation for instructions and examples, returning excerpts and links. The search does not require a separate permission during consent. Account queries and operations use the access you authorize. ## Connect your account 1. Add the MCP URL to the compatible application's settings. 2. Connect and complete sign-in on the Raims page opened in your browser. 3. Under **Permissions**, check the application and select the operations it can perform. Use a suggested profile or adjust each item. 4. Select **Review** to check the application, account, environments, return destination and permissions in the summary. 5. Choose **Authorize access** and complete the security confirmation when requested. 6. Return to the AI application to continue. Operations are independent and organized by resource, such as Customers, Charges, and Webhooks. Selecting creation does not select queries, updates, revocations, or refunds. Use search to find an operation and **Learn more** to check its explanation and accepted environments. Use **Back** from the review to adjust permissions. Your selection is preserved. Sign-in keeps the account's security controls, including MFA when requested. If you do not recognize the request or do not want to grant the permissions, close the page without authorizing. Access is granted only after confirmation. Consent authorizes the connection once. The AI can then run granted operations without opening a Dashboard approval for each task. Current account permissions and the rules for each resource still apply. If access, permitted environments or account status change while connecting, the page asks you to review the updated account details and access before completing consent. Authorization is not retried automatically. A compatible application can renew authorization without asking for your password again. If the connection expires, is revoked or cannot be renewed, connect the account again and review consent. Sandbox and Production use the same URL. A new connection includes all environments permitted for the account and your access, without choosing an environment during consent. The selected permissions apply to those environments. Switching the Dashboard environment does not change the connection's scope. Unavailable environments, resources and permissions remain blocked. If a connection is limited to one environment, reconnect to authorize the environments currently permitted. Renewing authorization preserves its scope. ## Configure your application With the [Raims CLI](/en/cli) installed, view the instructions for your client: ```bash raims mcp setup --client codex raims mcp setup --client claude-code raims mcp setup --client cursor ``` The command shows configuration without credentials and does not run the application. `--save PATH` saves a snippet to a new file; it does not overwrite or merge existing settings. Review the plan with `--dry-run`. ### Codex ```bash codex mcp add raims --url https://mcp.raims.com codex mcp login raims ``` ### Claude Code ```bash claude mcp add --transport http raims https://mcp.raims.com ``` Then open Claude Code, run `/mcp` and complete Raims authentication. ### Cursor Add this entry to `.cursor/mcp.json` or your personal Cursor MCP settings, preserving other servers: ```json { "mcpServers": { "raims": { "url": "https://mcp.raims.com" } } } ``` Connect the server in Cursor and complete consent in your browser. ## Check the account context Ask the assistant to call `get_raims_account_context` before guiding an action that depends on your account. The assistant sets `data_environment` to `Sandbox` or `Production` from the authorized environments. The tool reports the company, queried environment, current status, available capabilities and observation time. The context also describes currency, units and the reference time zone. Financial amounts use integer cents. A receivables forecast is not available balance, and an accepted request does not confirm payment or completion. Read the context again after an account or access change. Unavailable information must not be treated as zero. Permission to start a request does not replace Raims operation validation. ## Run authorized operations After authorizing the connection, ask the application to perform the actions you want. For example, it can create, update or delete webhooks when those permissions have been granted. You do not need to approve each task on a separate Raims page. The connection remains limited to the company, authorized environments, granted access and current permissions of the person who authorized it. In each call to `raims_api_read`, `raims_api_write` or `get_raims_account_context`, the assistant sets `data_environment` to match the request. The result identifies the environment queried or changed. Raims checks limits, balance, eligibility and resource rules for each request. Before running a request, call `raims_api_details`: the `data_environments` field lists the environments the endpoint accepts. The selected environment must be accepted by the endpoint and authorized for the connection. Simulations accept only `Sandbox` and do not change Production data. If a write result is uncertain, inspect the resource before requesting another creation. An accepted request does not confirm that a withdrawal reached its destination or that an email was delivered. ## Manage and revoke access In the Dashboard, open **Integration / Authorized applications**. Members can view their own connections. **View company applications** includes connections authorized by the owner and team. **Revoke team connections** also allows viewing them and revoking other employees' connections, but not the owner's. Device permissions do not grant this access. From the actions menu, use **Edit permissions** to review granted access or **Revoke access** to end a connection, according to your permissions. Opening the editor does not change access. **Edit permissions** lets you remove or restore access from the original authorization, with security confirmation, without changing environments or expiration. See [Edit permissions](/en/integracoes/aplicativos#editar-permissões) for who can edit access and when a new authorization is required. Integration keys are under **Integration / API keys** and require the corresponding permissions. Signing out of the Dashboard does not replace revoking the application. Use **Revoke access** to end that authorization. Revocation prevents new calls authorized by the connection. It does not undo completed operations or erase data already received by the external application. Current account and team-member permissions remain enforced. Recorded actions performed by an employee through MCP preserve that employee's identity under **Account / Activity log**. Members see their own activity; **View full audit log** extends access across the company. The history also shows connection authorizations, permission changes, revocations, and expirations. Automatic events are identified as **System**. ## Resolve connection issues If a network failure or temporary unavailability prevents the connection request from loading, the page keeps loading and retries automatically while the failure remains temporary. Wait for the result. Only the request lookup is retried; authorizing access still requires your confirmation. * If the request has expired or is no longer available, return to the application that started the connection and request new access. Reopening the same link does not renew the request. * If the request lookup is denied, check the account and your current access. An access denial ends automatic retries. * If the application asks for authentication again, connect and review the consent shown by Raims. * If an operation is not allowed, check the environment, granted permissions and the operator's current access. The connection does not expand that access. * If you receive `DATA_ENVIRONMENT_NOT_ALLOWED`, adjust the request to use one of the environments listed in `raims_api_details.data_environments`. New authorization does not enable an environment the endpoint does not accept or allow simulations in Production. * If the account is not the expected one, stop the action and connect the correct account. If the environment is incorrect, adjust the request to the assistant before continuing. An environment outside the connection's scope needs new consent. * If a request result is uncertain, inspect the resource state before asking for another creation or repeating the action. ## Application documentation * [MCP in Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) * [MCP in Claude Code](https://code.claude.com/docs/en/mcp) * [MCP in Cursor](https://cursor.com/docs/mcp) # Rate limiting (/en/integracoes/rate-limiting) The API limits how often you send calls and how many requests remain in progress. Your integration should control both, handle `429 Too Many Requests` and spread work over time. Use this guide when preparing an integration, investigating refusals due to excess traffic or planning higher volume. The limits listed here apply to the Raims API; endpoint-specific rules must also be respected. ## Shared limits The allowance belongs to the company and environment identified by the API key. All keys for the same company share the limits in that environment, even when calls come from different servers, processes or applications. Creating or rotating a key does not increase the allowance. Production and Sandbox have separate allowances. Each endpoint has an additional rate limit. Its HTTP method and path in the reference identify the endpoint: `GET /v1/charges/{id}` shares the same allowance across all IDs. `GET /v1/charges` and `POST /v1/charges` have separate endpoint allowances and share the company's total allowance in the environment. Coordinate usage across your integration's components. Local control in each process alone does not control their combined traffic. ### API limits by company and environment The values below are the default limits. They may vary according to your company's configured limits. | Limit | Production | Sandbox | | ------------------------------------- | ---------- | ------- | | Total requests per second | 100 | 25 | | Requests per second for each endpoint | 25 | 25 | | Total requests in progress | 50 | 50 | The limits apply together. In Production, for example, the total limit of 100 requests per second does not allow that volume to be concentrated on an endpoint limited to 25. In Sandbox, calls to different endpoints also share the total limit of 25. Treat them as usage ceilings, rather than a permanent sending target. An HTTP call may query or change a resource; the allowance does not represent a number of payments processed per second. ## Rate and concurrency Rate is how many calls are sent over time. Concurrency is how many have not finished. A slow query continues to occupy capacity even when no new calls are sent. For example, sending ten calls per second that each take five seconds can keep about fifty calls in progress. Reducing the rate alone does not immediately release calls that are already running. Spread out call start times and limit how many can remain in progress. Avoid sending an entire batch at once. Short bursts can receive `429` even when the observed average is below the limit; do not use the transition between seconds to concentrate two batches. ## Understand the 429 response `429 RATE_LIMITED` means the request was refused due to excess traffic and was not executed. The response tells you how long to wait and which control to adjust: ```http HTTP/1.1 429 Too Many Requests Content-Type: application/json Cache-Control: no-store Retry-After: 1 Raims-Rate-Limited-Reason: endpoint-rate { "error": { "code": "RATE_LIMITED", "message": "The API request limit was exceeded. Wait for Retry-After and reduce the request rate or the number of concurrent requests." } } ``` `Retry-After` is a positive integer number of seconds. Wait at least that long before retrying. The value `1` above is an example; always use the value received in the response. | `Raims-Rate-Limited-Reason` | What to adjust | | --------------------------- | ----------------------------------------------------------------------------- | | `global-rate` | Reduce the company's total call rate in the environment. | | `endpoint-rate` | Reduce calls to the same endpoint, including different IDs. | | `global-concurrency` | Reduce the company's total simultaneous calls in the environment. | | `endpoint-concurrency` | When enabled for the company, reduce simultaneous calls to the same endpoint. | | `resource-specific` | Follow the resource's own interval identified by `error.code`. | Some endpoints have their own limits and waiting intervals in addition to the API's general limits. See each endpoint's reference for the applicable rules. Make decisions using the status, `error.code` and the header reason. The text in `error.message` helps with diagnosis and must not be compared in your system's logic. General errors do not need `error.details`. ## Wait before retrying When you receive `429`, preserve pending work and reschedule the attempt: 1. Read `Retry-After` and the reason for the limit. 2. Reduce the rate or concurrency according to the reason. 3. Wait at least the received interval. After further refusals, increase the delay and add a small random variation, called *jitter*. 4. Set a maximum number of attempts and an overall deadline. If either is reached, stop the current attempt and preserve the work for later handling. One possible rule is to use the greater of `Retry-After` and an increasing delay, then add jitter. Never shorten the server's waiting interval to fit a local deadline: if it exceeds that deadline, defer the work instead of retrying early. Do not restart all refused calls together when the waiting interval ends. Use a queue and maintain the outgoing rate during retries as well. Keep retry handling in one place so that different application layers do not repeat the same call simultaneously. For calls that create or change data, or when a connection ends without a response, check the result before submitting again. Losing a response does not prove that the request was not processed. Do not recreate a charge to resolve uncertainty about the previous one. ## Queued query example This Node.js example retrieves a customer using `GET`. It keeps one call in progress per process, waits 100 ms between items and makes at most four attempts when it receives `429`. Each attempt has a timeout of up to 30 seconds; an item's execution deadline is two minutes, starting when it leaves the queue. These values are example choices, not additional API limits. Store the key in `RAIMS_API_KEY` on your integration's backend. Pass a customer ID from the same company and environment as the key. Do not run the code in a browser or write the key to logs. ```javascript const apiKey = process.env.RAIMS_API_KEY; const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); let queue = Promise.resolve(); function retrieveCustomer(id) { const task = queue.then(() => retrieveWithRetry(id)); queue = task.catch(() => {}).then(() => sleep(100)); return task; } async function retrieveWithRetry(id) { if (!apiKey) throw new Error('RAIMS_API_KEY is required.'); const deadline = Date.now() + 120_000; for (let attempt = 0; attempt < 4; attempt += 1) { const remaining = deadline - Date.now(); if (remaining <= 0) throw new Error('Request deadline exceeded.'); const response = await fetch( `https://api.raims.com/v1/customers/${encodeURIComponent(id)}`, { method: 'GET', headers: { Authorization: `Bearer ${apiKey}`, Accept: 'application/json', }, redirect: 'error', signal: AbortSignal.timeout(Math.min(30_000, remaining)), }, ); if (response.ok) return response.json(); const retryAfter = response.headers.get('Retry-After'); await response.body?.cancel(); if (response.status !== 429) throw new Error(`HTTP ${response.status}`); const seconds = /^[1-9]\d*$/.test(retryAfter ?? '') ? Number(retryAfter) : NaN; if (attempt === 3 || !Number.isSafeInteger(seconds)) { throw new Error('Rate limit: stop and reschedule the request.'); } const delay = Math.max(seconds * 1000, 500 * 2 ** attempt) + Math.floor(Math.random() * 250); if (delay >= deadline - Date.now()) { throw new Error('Retry-After exceeds the remaining request deadline.'); } await sleep(delay); } } ``` The function returns an error to its caller when the deadline expires, the header cannot be interpreted or another failure occurs. It does not automatically retry timeouts, connection errors or HTTP responses other than `429`. Handle those results in your application and preserve work that needs to be rescheduled. This queue is local. When running multiple instances, coordinate their combined usage and limit pending item counts and time spent in the queue. The example does not replace that shared control or provide a complete API client. ## Avoid unnecessary calls Use [webhooks](/en/integracoes/webhooks/receber-eventos) to receive supported changes instead of continuously querying the same resource. Validate the signature and handle redeliveries without repeating the effect. Query the resource when you need to retrieve its current state; do not depend on event order. For lists, apply available filters, process each page and advance only while `page.has_next` is true. Copy `page.next_after` to `after`, keeping the filters. Do not restart the entire list on each attempt. See [Listing and pagination](/en/api/listagem-e-paginacao). Separate batch query tasks from calls needed for payment. Reserve capacity for interactive use and avoid repeating queries whose results your application can still use. ## Diagnose and request a review Measure the total and per-endpoint call rate, simultaneous calls, response duration and refusals by reason. Record the method, endpoint template, environment, time, HTTP status, `error.code`, reason for the limit, `Retry-After` and number of attempts. Use aggregate metrics. Do not record API keys, authentication headers, bodies containing personal data or sensitive links. For diagnosis, using the `/v1/charges/{id}` template avoids recording each charge's identifier in the metric. If refusals persist, check usage across all applications for the same company and environment. To discuss higher limits for your integration's needs, contact your account manager through the Raims Dashboard chat or email [integracoes@raims.com](mailto:integracoes@raims.com). Include the endpoints, expected volume, bursts, concurrency, latency and busiest times. Do not send your key. The request will be reviewed; contacting us does not confirm an increase. # Delphi SDK (/en/integracoes/sdk-delphi) The Delphi SDK connects a backend to the Raims public API through source units with typed services, parameters, and responses. The distribution is source code to compile on your application's target. Check the platform requirements when setting up the installation. Do not embed API keys in distributed desktop or mobile binaries. The [SDK reference](https://github.com/raimshq/raims-delphi/blob/main/docs/reference.md) lists each resource's methods and parameters. ## Install the SDK Download source from the [current GitHub release](https://github.com/raimshq/raims-delphi/releases/latest) and preserve the complete `src` directory. The base source requires Delphi 10.4; some targets require later versions. Check the [platform requirements](https://github.com/raimshq/raims-delphi/blob/main/docs/installation.md#platform-requirements) and use an edition that includes your compiler and required native SDKs. In the IDE, open **Project**, **Options**, and **Delphi Compiler**. Add the `src` location to the project's **Search path** for each target and configuration you use. For global configuration, the Delphi **Library** options let you add it to the selected platform's **Library path**. The [IDE library documentation](https://docwiki.embarcadero.com/RADStudio/Sydney/en/Library) explains this selection. Keep compiled files in your application's output directory, separate from the source. Use `Raims.Client`, `Raims.Core`, `Raims.Params`, and `Raims.Models`; add `Raims.Webhooks` for events. The SDK uses the standard `System.JSON` and `System.Net.HttpClient` libraries without a UI framework. Examples are Delphi procedure snippets; also import `System.SysUtils` and `System.JSON`. ## Configure the client Obtain a credential through [API keys](/en/integracoes/chaves-api) and keep it in your backend. Company, environment, and permissions come from the validated key. Sandbox and Production use `https://api.raims.com`. ```pascal uses System.SysUtils, Raims.Client, Raims.Core, Raims.Models; var Client: TRaimsClient; Options: TRaimsClientOptions; begin Options := TRaimsClientOptions.Default; Options.TimeoutMilliseconds := 80000; Options.MaxNetworkRetries := 0; Client := TRaimsClient.Create(GetEnvironmentVariable('RAIMS_API_KEY'), Options); try // Use Client here. finally Client.Free; end; end; ``` Initialize options through `Default`. Timeouts use milliseconds and apply to native transport phases rather than a total operation deadline. Calls are synchronous; visual applications should run network work outside the UI thread. The next snippets use an open `Client`. It owns its services; your application frees the client, parameters, and returned resources using `try/finally`. ## Create a customer and a charge `CustomerTaxId` is the authorized customer's valid CPF or CNPJ. `CustomerKey` and `ChargeKey` are separate strings persisted before sending. `DueDateUnix` is an `Int64` due date in UTC Unix seconds; `RequestId` is an application string. The types below are in `Raims.Params`, `Raims.Models`, and `Raims.Core`. ```pascal var CustomerParams: TCreateCustomerParams; ChargeParams: TCreateChargeParams; Customer: TCustomerCreated; Charge: TChargeCreated; RequestOptions: TRaimsRequestOptions; CustomerId: string; begin CustomerParams := TCreateCustomerParams.Create; try CustomerParams.SetTaxId(CustomerTaxId); RequestOptions := TRaimsRequestOptions.Default; RequestOptions.IdempotencyKey := CustomerKey; Customer := Client.Customers.Create(CustomerParams, RequestOptions); try CustomerId := Customer.Id; finally Customer.Free; end; finally CustomerParams.Free; end; ChargeParams := TCreateChargeParams.Create; try ChargeParams.SetCustomerId(CustomerId).SetAmountCents(15000); ChargeParams.SetDueDate(DueDateUnix).SetTitle('Order 1234'); RequestOptions := TRaimsRequestOptions.Default; RequestOptions.IdempotencyKey := ChargeKey; Charge := Client.Charges.Create(ChargeParams, RequestOptions); try RequestId := Charge.LastResponse.RequestId; finally Charge.Free; end; finally ChargeParams.Free; end; end; ``` `15000` represents BRL 150.00. Not calling a setter leaves a field absent; `SetExternalReferenceNull` on `TUpdateCustomerParams` sends null where the contract permits clearing that reference. `UnsetExternalReference` removes the input field. In responses, `HasField` and `IsNull` distinguish presence and null before interpreting a getter that returns zero or an empty string. ## Pagination and pending results List customers and visit up to one hundred items: ```pascal var Page: TCustomerListResponse; begin Page := Client.Customers.List; try Page.AutoPagingEach( procedure(CustomerJson: TJSONObject) begin ProcessCustomer(CustomerJson); end, 100); finally Page.Free; end; end; ``` `ProcessCustomer` is your handler. The callback receives a borrowed `TJSONObject`: do not free or mutate it, and copy it before retaining it after the callback. `AutoPagingEach` frees additional pages; your application frees the first one. `NextPage` and `PreviousPage` return new pages or `nil`; the caller owns those pages. Filters and options are preserved. HTTP `202` accepts an operation with a pending result. Retrieve the resource or follow its webhook before confirming a financial effect. Preserve `LastResponse.StatusCode` and `RequestId` to identify the attempt. ## Idempotency and errors ```pascal var Current: TCustomerListItem; begin try Current := Client.Customers.Retrieve(CustomerId); try RequestId := Current.LastResponse.RequestId; finally Current.Free; end; except on E: ERaimsApiError do HandleApiFailure(E.LastResponse.StatusCode, E.Code, E.LastResponse.RequestId); on E: ERaimsConnectionError do HandleConnectionFailure; end; end; ``` The handlers belong to your application. `ERaimsApiError` exposes `Code`, `ErrorType`, `ApiMessage`, and `LastResponse`; `ERaimsConnectionError` represents transport failures. Log only necessary metadata without credentials or full bodies. If you access `ApiError`, retain and free the returned copy. The SDK does not generate keys or retry writes automatically. After a lost response, reconcile the operation and keep its key and parameters if the endpoint permits another attempt. `MaxNetworkRetries` enables eligible read retries only; the default is zero. `Retry-After` follows the SDK's bounded wait policy. See [Idempotency](/en/api/idempotencia). ## Use Sandbox Use a Sandbox key and a charge created in that environment: ```pascal var SandboxClient: TRaimsClient; Simulation: TChargeSimulation; begin SandboxClient := TRaimsClient.Create(GetEnvironmentVariable('RAIMS_SANDBOX_API_KEY')); try Simulation := SandboxClient.Simulations.Charges.ConfirmPayment(SandboxChargeId); try RequestId := Simulation.LastResponse.RequestId; finally Simulation.Free; end; finally SandboxClient.Free; end; end; ``` `SandboxChargeId` and `RequestId` are application strings. The key determines the environment; the SDK does not change it through headers or operating system selection. Financial simulations require Sandbox. See [Simulations](/en/api/simulations/overview). Email requests and webhooks may reach external destinations; use authorized ones. ## Receive webhooks Preserve `RawBody` as the original `TBytes` received by your server. Set `WebhookSecret` to the webhook's `secret_key`; the three `Received...` values come from the original headers. Before building the array below, reject duplicate signing-header occurrences instead of choosing one of them. ```pascal var Headers: TArray; Event: TJSONObject; begin SetLength(Headers, 3); Headers[0] := TRaimsHeader.Create('webhook-id', ReceivedDeliveryId); Headers[1] := TRaimsHeader.Create('webhook-timestamp', ReceivedTimestamp); Headers[2] := TRaimsHeader.Create('webhook-signature', ReceivedSignature); Event := TRaimsWebhook.ConstructEvent(RawBody, Headers, WebhookSecret); try PersistEvent(Event); finally Event.Free; end; end; ``` The types are in `System.JSON`, `Raims.Core`, and `Raims.Webhooks`. `PersistEvent` is your handler and the caller owns `Event`. `ERaimsSignatureError` identifies verification failure: do not process the event in that case. Do not reserialize the body before verification. The default tolerance is 300 seconds; keep the server clock synchronized. After verification, check type and environment, deduplicate the event `id`, and store the work durably before returning success. `webhook-id` identifies the delivery. See [Receive events](/en/integracoes/webhooks/receber-eventos). ## Update the SDK Review [release notes](https://github.com/raimshq/raims-delphi/releases/latest) and replace all units with source from the same revision. Preserve the selected Search path or Library path, remove old compiled units from your application's output, and rebuild every target in use. Do not mix a new unit with the rest of an older version. Check your integration with its compiler, operating system, and configuration before making the application available. # .NET SDK (/en/integracoes/sdk-dotnet) Use the `Raims` package to integrate a server application written in C# with the public API. The SDK provides resource services, typed inputs and responses, cursor pagination, and webhook signature verification. Methods have synchronous and asynchronous variants, with the `Async` suffix. The integration requires an x64 application running .NET Framework 4.8/4.8.1 or .NET 10. Do not distribute the API key in browser, desktop, or mobile apps provided to your customers. Keep it in the integration backend. ## Install the package From your application directory: ```bash dotnet add package Raims ``` Without a version argument, NuGet installs the latest stable version compatible with the project and records the reference in your application. The package targets `netstandard2.0` and `net10.0`. NuGet selects the appropriate target; supported consumers are validated on x64 .NET Framework 4.8 and .NET 10. ## Configure the client Obtain a key through [API keys](/en/integracoes/chaves-api) and store it in a protected environment variable or your application's secret store. The validated credential determines the company, environment, and permissions in the API. Sandbox and Production use `https://api.raims.com`. This example is a snippet for an `async` method: ```csharp using System; using Raims; string apiKey = Environment.GetEnvironmentVariable("RAIMS_API_KEY") ?? throw new InvalidOperationException("Configure RAIMS_API_KEY."); using (var raims = new RaimsClient(apiKey)) { var customers = await raims.Customers.ListAsync(new ListCustomersOptions { PageSize = 20, }); foreach (var customer in customers) { Console.WriteLine(customer.Id); } } ``` Reuse the client for the integration's lifetime to reuse HTTP connections, and dispose it when no longer needed. The following snippets assume a `raims` instance configured by your application. ## Create a customer and a charge `customerTaxId` is the valid CPF or CNPJ of a customer authorized by your application. `customerIdempotencyKey` and `chargeIdempotencyKey` are separate keys created and persisted before the requests. `chargeDueDate` is the due date chosen and persisted for the order, expressed as UTC Unix seconds. ```csharp var customer = await raims.Customers.CreateAsync(new CreateCustomerOptions { TaxId = customerTaxId, }, new RequestOptions { IdempotencyKey = customerIdempotencyKey }); var charge = await raims.Charges.CreateAsync(new CreateChargeOptions { CustomerId = customer.Id, AmountCents = 15000, DueDate = chargeDueDate, Title = "Order 1234", }, new RequestOptions { IdempotencyKey = chargeIdempotencyKey }); int? httpStatus = charge.LastResponse?.StatusCode; var requestId = charge.LastResponse?.RequestId; ``` If the CPF or CNPJ already exists in the same company and environment, the customer record is updated and retains its identifier. `15000` represents BRL 150.00. Review the fields and conditions in [Create a charge](/en/api/charges). To retry the same intent after a lost response, keep the key and every parameter, including the due date. An external order reference does not replace idempotency. ## Pagination and pending results Enumerating one page does not make additional requests. Use `NextPageAsync()` and `PreviousPageAsync()` to follow cursors; the SDK retains the query filters. `GetAutoPagingEnumerable()` and `GetAutoPagingAsyncEnumerable()` load following pages during enumeration and may make several requests. Bound your application work and use cancellation when needed. An HTTP `202` response still means a pending result. It does not confirm payment or a completed financial effect, and it does not start automatic polling. Read the resource or follow the appropriate event before confirming the result in your application. ## Idempotency and errors The SDK sends `Idempotency-Key` only when the application supplies it to an endpoint that accepts that header. It does not generate keys or automatically retry POST, PATCH, or DELETE requests. Read retries are optional and default to zero. Use the HTTP status and `ApiErrorException.ErrorCode` to decide how to handle a failure. `RequestId` helps identify the attempt. `ErrorMessage` is a human explanation and must not be compared as a control code. Do not log complete responses, credentials, personal documents, or temporary links. Review [Idempotency](/en/api/idempotencia) and the [SDK reference](https://github.com/raimshq/raims-dotnet/blob/main/docs/reference.md). Options use `Optional` to distinguish an omitted field from an explicit value. For updates, omission retains the current value; `null` clears only fields whose contract allows it. Review each endpoint's conditions. ## Use Sandbox Use a Sandbox key with the simulation services `raims.Simulations.Charges` and `raims.Simulations.Refunds`. A Production key does not become a Sandbox key by using these services. Conditions for each simulation are described in the [Simulations reference](/en/api/simulations/overview). Requests that ask for email or webhook delivery can reach external destinations even in Sandbox. Use only destinations authorized for the integration. ## Receive webhooks Read the original body bytes and signing headers received by your server: ```csharp using System.Collections.Generic; using Raims; var headers = new Dictionary { ["webhook-id"] = receivedDeliveryId, ["webhook-timestamp"] = receivedTimestamp, ["webhook-signature"] = receivedSignature, }; var webhookEvent = WebhookUtility.ConstructEvent(rawBodyBytes, headers, webhookSecret); ``` `webhookSecret` is the `secret_key` returned when creating or rotating the webhook, not the API Bearer key. Do not reserialize the JSON before verification. A failure throws `SignatureVerificationException`; do not process the body then. A valid signature does not prevent duplicate processing. Check type and environment, deduplicate by the event's `id`, and durably record the work before returning success. The `webhook-id` header identifies the delivery and does not replace the event identifier. Review [Receive events](/en/integracoes/webhooks/receber-eventos). ## Update the SDK To get the latest stable version from NuGet, run the command again without a version argument: ```bash dotnet add package Raims ``` NuGet updates the project reference. Review [releases](https://github.com/raimshq/raims-dotnet/releases) and test the flows used by your integration. The SDK version is independent of the API's HTTP `/v1` version. The complete configuration, pagination, error, and webhook guides are available in the [SDK repository](https://github.com/raimshq/raims-dotnet). # Elixir SDK (/en/integracoes/sdk-elixir) The official Elixir SDK connects server applications to the Raims public API. Use resource modules, response models, pagination, and webhook verification. Keep the API key in your backend, outside applications distributed to customers and routine logs. The [SDK reference](https://github.com/raimshq/raims-elixir/blob/main/docs/reference.md) lists each resource's methods and parameters. ## Install the SDK Use Elixir 1.18 or later with Erlang/OTP 27 or later. The official [`raims`](https://hex.pm/packages/raims) package is available on Hex. If Hex is not installed yet, install it once: ```bash mix local.hex ``` From your project directory, check the current stable version and configuration: ```bash mix hex.info raims ``` Copy the `Config:` line into the list returned by `deps/0` in your application's `mix.exs`. Then fetch the dependencies and compile: ```bash mix deps.get mix compile ``` Mix resolves dependencies according to the configuration and records their versions in `mix.lock`. Keep that file for repeatable installation. [GitHub releases](https://github.com/raimshq/raims-elixir/releases/latest) continue to provide source code and the distribution archive. For a Git or local path installation, read the [repository instructions](https://github.com/raimshq/raims-elixir/blob/main/docs/installation.md). ## Configure the client Obtain a key through [API keys](/en/integracoes/chaves-api) and store it in a protected variable or your application's secret store. It determines company, environment, and permissions. Sandbox and Production use `https://api.raims.com`. ```elixir client = Raims.Client.new(System.fetch_env!("RAIMS_API_KEY"), timeout: 30_000, max_network_retries: 0 ) {:ok, balance} = Raims.Balances.retrieve(client) request_id = balance.request_id ``` Timeouts use milliseconds. The client is immutable and reusable; it does not own a process that needs stopping. Each HTTP attempt closes its connection when finished. The following examples use this `client`. ## Create a customer and a charge `customer_tax_id` contains the authorized customer's valid CPF or CNPJ. `customer_key` and `charge_key` are separate keys, persisted before requests. Also persist `due_date_unix`, the due date in UTC Unix seconds. ```elixir with {:ok, customer} <- Raims.Customers.create(client, %{tax_id: customer_tax_id}, idempotency_key: customer_key ), {:ok, charge} <- Raims.Charges.create( client, %{ customer_id: customer.data["id"], amount_cents: 15000, due_date: due_date_unix, title: "Order 1234" }, idempotency_key: charge_key ) do {:ok, charge.data["id"], charge.status_code} else {:error, error} -> {:error, error.kind, error.request_id} end ``` `15000` represents BRL 150.00. Maps accept atom or string keys with JSON names. Omission keeps a field absent; `nil` sends null where allowed. During an update, `%{external_reference: nil}` can clear the reference; omission preserves it. Responses use `response.data`; `Access.fetch/2` distinguishes an absent field from one containing `nil`. ## Pagination and pending results ```elixir {:ok, first_page} = Raims.Customers.list(client, %{page_size: 50}) first_page |> Raims.Page.stream() |> Stream.map(fn customer -> customer["id"] end) |> Enum.take(100) ``` A response list contains only the received page. `Raims.Page.stream/1` fetches further pages on demand; `Enum.take/2` bounds collection. The stream raises `Raims.Error` if a page fails. `next_page/1` and `previous_page/1` return `{:ok, response}`, `{:ok, nil}`, or `{:error, error}`, preserving filters and options. Do not send `after` and `before` together. HTTP `202` accepts work with a pending result. Retrieve the resource or follow the appropriate event before confirming its financial effect. ## Idempotency and errors ```elixir case Raims.Customers.retrieve(client, customer_id) do {:ok, response} -> MyApp.process_customer(response.data) {:error, error} -> MyApp.handle_failure(error.kind, error.status_code, error.code, error.request_id) end ``` `MyApp` represents your business handling. Functions return `{:ok, response}` or `{:error, %Raims.Error{}}` tuples; `!` variants raise the exception. Invalid local arguments raise `ArgumentError`. Use category, status, code, and Request-Id without logging bodies or credentials. The SDK does not generate idempotency keys or retry writes. After a lost response, retrieve the operation; when retrying is permitted, use the same key and parameters. `max_network_retries` enables eligible GET/HEAD read retries only, with a default of zero. Waits, `Retry-After`, and attempts share the timeout budget. See [Idempotency](/en/api/idempotencia). ## Use Sandbox Use a Sandbox key and a resource from that environment: ```elixir sandbox = Raims.Client.new(System.fetch_env!("RAIMS_SANDBOX_API_KEY")) {:ok, result} = Raims.Simulations.Charges.confirm_payment(sandbox, sandbox_charge_id) ``` The SDK does not select or change a credential's environment. Financial simulations accept Sandbox only; a Production key remains Production on a local host. See [Simulations](/en/api/simulations/overview). Email requests and webhooks may reach external destinations even in Sandbox; use authorized destinations only. ## Receive webhooks Use the original `raw_body` binary and a list of received header pairs containing `webhook-id`, `webhook-timestamp`, and `webhook-signature`. The list preserves duplicates so the verifier can reject ambiguity. ```elixir case Raims.Webhook.construct_event(raw_body, signing_headers, webhook_secret) do {:ok, event} -> MyApp.persist_event(event) {:error, error} -> MyApp.reject_delivery(error) end ``` `webhook_secret` is the webhook's `secret_key` held in your secret store; the `MyApp` handlers belong to your application. Do not parse and rebuild JSON before verifying its signature. The default tolerance is 300 seconds, with a synchronized clock. `verify_signature/4` verifies without decoding JSON. After verification, check type and environment, deduplicate the event `id`, and store the work durably before returning success. A valid signature does not prevent redelivery; `webhook-id` identifies the delivery. See [Receive events](/en/integracoes/webhooks/receber-eventos). ## Update the SDK Check the current stable version and configuration: ```bash mix hex.info raims ``` If needed, adjust the declaration in `deps/0` using the `Config:` line shown by Hex. Then update the SDK within the declared constraints: ```bash mix deps.update raims mix compile ``` If the dependency used `github:`, `git:`, or `path:`, replace that declaration with the current Hex configuration and run the same commands. Also remove Git-only options such as `ref:`, `branch:`, and `tag:`. The `Raims` modules stay the same. Review and keep the updated `mix.lock`. Read the [release notes](https://github.com/raimshq/raims-elixir/releases/latest) and test the flows used by your integration before updating the application. Installation does not apply future updates automatically. # Go SDK (/en/integracoes/sdk-go) Use the `github.com/raimshq/raims-go` module in your integration backend. The SDK provides resource services, typed parameters and responses, cursor pagination, and webhook authentication. ## Install the package The SDK requires Go 1.26.5 or later. From the project containing `go.mod`: ```bash go get github.com/raimshq/raims-go@latest ``` Go resolves the latest stable module version and records the dependency in your application. Keep `go.mod` and `go.sum` with the project. ## Configure the client Get a key from [API keys](/en/integracoes/chaves-api) and store it in a vault or protected application environment variable. Keep the credential in the backend, out of browsers, applications distributed to customers, and logs. The validated API key determines company, environment, and permissions. Sandbox and Production use `https://api.raims.com`. ```go package main import ( "context" "fmt" "log" "os" raims "github.com/raimshq/raims-go" ) func main() { client, err := raims.NewClient(os.Getenv("RAIMS_API_KEY"), raims.WithMaxNetworkRetries(0), ) if err != nil { log.Fatal(err) } defer client.CloseIdleConnections() page, err := client.Customers.List(context.Background(), &raims.ListCustomersParams{ PageSize: raims.Set[int64](20), }) if err != nil { log.Fatal(err) } for _, customer := range page.List { fmt.Println(customer.ID) } } ``` Reuse the client across requests and goroutines. `context.Context` lets you cancel calls and limit their duration. Close idle connections when finished. The following snippets assume a configured `client` and an application context named `ctx`. ## Create a customer and a charge `customerTaxID` is the valid CPF or CNPJ of the authorized customer. `customerIdempotencyKey` and `chargeIdempotencyKey` are separate keys created and persisted before the requests. `chargeDueDate` is an `int64` containing the chosen, persisted due date in UTC Unix seconds. This snippet belongs in a function that returns `error`. ```go customer, err := client.Customers.Create(ctx, &raims.CreateCustomerParams{ TaxID: raims.Set(customerTaxID), }, raims.WithIdempotencyKey(customerIdempotencyKey)) if err != nil { return err } charge, err := client.Charges.Create(ctx, &raims.CreateChargeParams{ CustomerID: raims.Set(customer.ID), AmountCents: raims.Set[int64](15000), DueDate: raims.Set(chargeDueDate), Title: raims.Set("Order 1234"), }, raims.WithIdempotencyKey(chargeIdempotencyKey)) if err != nil { return err } fmt.Println(charge.LastResponse.StatusCode, charge.LastResponse.RequestID) ``` If the CPF or CNPJ already exists in the same company and environment, the customer is updated and keeps its identifier. `15000` represents BRL 150.00. Keep the key and every parameter, including the due date, when recovering the same intent after losing a response. See [Create a charge](/en/api/charges). `Optional[T]` preserves the difference between omitting a field, sending a value with `Set`, and sending null with `Null[T]()`. Check the field contract before clearing a value. ## Pagination and pending results `List` fetches one page, available in `page.List`. `NextPage(ctx)` and `PreviousPage(ctx)` preserve filters and return `nil` when there is no continuation. `ListAll` advances as you consume it; leaving the loop stops further fetches. `processCustomer` represents your application logic. ```go for customer, err := range client.Customers.ListAll(ctx, nil).All() { if err != nil { return err } processCustomer(customer.ID) } ``` Copy the received cursors and keep the filters; do not send `after` and `before` together. See [Listing and pagination](/en/api/listagem-e-paginacao). An HTTP `202` response indicates a pending result. It does not confirm payment or financial completion and does not start automatic polling. Retrieve the resource or follow the appropriate event before confirming the effect in your application. ## Idempotency and errors Use `errors.As` to identify `*raims.APIError` and make decisions using `StatusCode` and `Code`. `Response.RequestID` identifies the attempt when a response exists. `ConnectionError` indicates a transport failure and can leave a write inconclusive. `WithMaxNetworkRetries` configures retries for GET only; the default is zero. The SDK sends an idempotency key only when your application supplies it to an endpoint that accepts `Idempotency-Key`. It does not generate keys or retry writes automatically. A timeout does not prove that a write was rejected. Make decisions using the HTTP status and structured code; `error.message` is a human diagnostic that can change. Do not log complete responses, credentials, personal documents, or temporary URLs. See [Idempotency](/en/api/idempotencia) and the [SDK error guide](https://github.com/raimshq/raims-go/blob/main/docs/errors-and-retries.md). ## Use Sandbox Use a Sandbox key for simulations in `client.Simulations.Charges` and `client.Simulations.Refunds`. A Production key does not become a Sandbox key when these services are used. Check the conditions in the [Simulations reference](/en/api/simulations/overview). Requests that ask for email or webhook deliveries can reach external destinations even in Sandbox. Use only destinations authorized for the integration. ## Receive webhooks `rawBody` contains the received bytes and `headers` contains the original HTTP headers. The helper returns the authenticated event or an error; do not process the body when authentication fails. ```go import ( "encoding/json" "net/http" "time" raims "github.com/raimshq/raims-go" ) func authenticateDelivery(rawBody []byte, headers http.Header, webhookSecret string) (map[string]json.RawMessage, error) { return raims.ConstructWebhookEvent(rawBody, headers, webhookSecret, raims.DefaultWebhookTolerance, time.Now()) } ``` Use the `secret_key` returned when creating or rotating the webhook, which differs from the API Bearer key. Read the body before the JSON parser and preserve its bytes: do not reserialize the content before authentication. After authentication, check the type and environment, deduplicate by the event `id`, and store the work durably before responding with success. The `webhook-id` header identifies the delivery, not the event. See [Receive events](/en/integracoes/webhooks/receber-eventos). ## Update the SDK Run `go get github.com/raimshq/raims-go@latest` again in the project. Review the releases and changes to `go.mod` and `go.sum`, and test your application flows before deploying the update. The SDK version is independent of the API HTTP version `/v1`. Full guides and the method reference are in the [SDK repository](https://github.com/raimshq/raims-go). # Java SDK (/en/integracoes/sdk-java) Use `com.raims:raims-java` to connect your Java backend to the public API. The SDK provides resource services, typed builders and responses, cursor pagination, and webhook authentication. ## Install the package The SDK requires Java 11 or later and is available on Maven Central as [`com.raims:raims-java`](https://central.sonatype.com/artifact/com.raims/raims-java). Find the current stable version at that link and replace `SDK_VERSION` in the examples below with that version. Keep your selected version in the application's configuration. ### Maven Add the dependency to `pom.xml`: ```xml com.raims raims-java SDK_VERSION ``` ### Gradle In `build.gradle`, use the Maven Central repository and declare the dependency: ```groovy repositories { mavenCentral() } dependencies { implementation 'com.raims:raims-java:SDK_VERSION' } ``` For Kotlin DSL, in `build.gradle.kts`: ```kotlin repositories { mavenCentral() } dependencies { implementation("com.raims:raims-java:SDK_VERSION") } ``` Maven and Gradle resolve the SDK and its transitive dependencies through Maven Central. [GitHub releases](https://github.com/raimshq/raims-java/releases/latest) also provide the JAR, POM, sources, Javadoc, and `SHA256SUMS`. To use those files, see [installation from GitHub](https://github.com/raimshq/raims-java/blob/main/docs/installation.md#github-release-downloads). ## Configure the client Get a key from [API keys](/en/integracoes/chaves-api) and store it in a vault or protected application environment variable. Keep the credential in the backend, out of browsers, applications distributed to customers, and logs. The validated API key determines company, environment, and permissions. Sandbox and Production use `https://api.raims.com`. ```java import com.raims.RaimsClient; import com.raims.param.ListCustomersParams; try (RaimsClient raims = RaimsClient.builder() .setApiKey(System.getenv("RAIMS_API_KEY")) .setMaxNetworkRetries(0) .build()) { var customers = raims.customers().list( ListCustomersParams.builder().setPageSize(20).build()); customers.getList().forEach(customer -> System.out.println(customer.getId())); } ``` Reuse a `RaimsClient` instance across calls and threads. The client implements `AutoCloseable`; use try-with-resources for a short scope or call `close()` when shutting down a shared client. The following snippets assume an application-managed `raims` instance that remains open. ## Create a customer and a charge `customerTaxId` is the valid CPF or CNPJ of the authorized customer. `customerIdempotencyKey` and `chargeIdempotencyKey` are separate keys created and persisted before the requests. `chargeDueDate` is a `long` containing the chosen, persisted due date in UTC Unix seconds. ```java import com.raims.RequestOptions; import com.raims.param.CreateCustomerParams; import com.raims.param.CreateChargeParams; var customer = raims.customers().create( CreateCustomerParams.builder().setTaxId(customerTaxId).build(), RequestOptions.builder().setIdempotencyKey(customerIdempotencyKey).build()); var charge = raims.charges().create( CreateChargeParams.builder() .setCustomerId(customer.getId()) .setAmountCents(15000) .setDueDate(chargeDueDate) .setTitle("Order 1234") .build(), RequestOptions.builder().setIdempotencyKey(chargeIdempotencyKey).build()); int httpStatus = charge.getLastResponse().getStatusCode(); String requestId = charge.getLastResponse().getRequestId(); ``` If the CPF or CNPJ already exists in the same company and environment, the customer is updated and keeps its identifier. `15000` represents BRL 150.00. Keep the key and every parameter, including the due date, when recovering the same intent after losing a response. See [Create a charge](/en/api/charges). Omitting a setter keeps the field absent. Setters ending in `Null` send null for fields that allow it. Check the contract before clearing a value. ## Pagination and pending results `list()` fetches a typed page with `getList()`. `nextPage()` and `previousPage()` preserve filters and return `null` when there is no continuation. `autoPagingIterable()` advances as you consume it; keep the client open during iteration. `processCustomer` represents your application logic. ```java for (var customer : raims.customers().list().autoPagingIterable()) { processCustomer(customer.getId()); } ``` Copy the received cursors and keep the filters; do not send `after` and `before` together. See [Listing and pagination](/en/api/listagem-e-paginacao). An HTTP `202` response indicates a pending result. It does not confirm payment or financial completion and does not start automatic polling. Retrieve the resource or follow the appropriate event before confirming the effect in your application. ## Idempotency and errors Failures use exceptions in `com.raims.exception`. Use `getStatusCode()`, `getCode()`, and `getRequestId()` to handle HTTP errors. A connection failure can leave a write inconclusive. `setMaxNetworkRetries` configures read retries; the default is zero. The SDK sends an idempotency key only when your application supplies it to an endpoint that accepts `Idempotency-Key`. It does not generate keys or retry writes automatically. A timeout does not prove that a write was rejected. Make decisions using the HTTP status and structured code; `error.message` is a human diagnostic that can change. Do not log complete responses, credentials, personal documents, or temporary URLs. See [Idempotency](/en/api/idempotencia) and the [SDK error guide](https://github.com/raimshq/raims-java/blob/main/docs/errors-and-retries.md). ## Use Sandbox Use a Sandbox key for simulations in `raims.simulations().charges()` and `raims.simulations().refunds()`. A Production key does not become a Sandbox key when these services are used. Check the conditions in the [Simulations reference](/en/api/simulations/overview). Requests that ask for email or webhook deliveries can reach external destinations even in Sandbox. Use only destinations authorized for the integration. ## Receive webhooks `rawBodyBytes` contains the received bytes. `receivedDeliveryId`, `receivedTimestamp`, and `receivedSignature` are the header values read by your server. Reject the delivery if `constructEvent` throws a signature verification exception. ```java import com.raims.WebhookUtility; import com.google.gson.JsonObject; import java.util.Map; Map headers = Map.of( "webhook-id", receivedDeliveryId, "webhook-timestamp", receivedTimestamp, "webhook-signature", receivedSignature); JsonObject event = WebhookUtility.constructEvent(rawBodyBytes, headers, webhookSecret); ``` Use the `secret_key` returned when creating or rotating the webhook, which differs from the API Bearer key. Read the body before the JSON parser and preserve its bytes: do not reserialize the content before authentication. After authentication, check the type and environment, deduplicate by the event `id`, and store the work durably before responding with success. The `webhook-id` header identifies the delivery, not the event. See [Receive events](/en/integracoes/webhooks/receber-eventos). ## Update the SDK Find the current stable version of [`com.raims:raims-java` on Maven Central](https://central.sonatype.com/artifact/com.raims/raims-java), update the dependency version in `pom.xml`, `build.gradle`, or `build.gradle.kts`, and run your integration tests. If your application installed the JAR from GitHub, the `com.raims:raims-java` coordinates stay the same. Use the version available on Maven Central in your application dependency. The SDK version is independent of the API HTTP version `/v1`. Full guides and the method reference are in the [SDK repository](https://github.com/raimshq/raims-java). # Node.js SDK (/en/integracoes/sdk-node) Use the `@raimshq/raims` package in your Node.js backend. The SDK includes ESM and CommonJS modules, TypeScript declarations, resource services, cursor pagination, and webhook authentication. ## Install the package The SDK requires Node.js 22 or later and includes ESM and CommonJS modules and TypeScript types. From your application directory: ```bash npm install @raimshq/raims ``` The [`@raimshq/raims`](https://www.npmjs.com/package/@raimshq/raims) package includes the runtime and type declarations. Keep your application's lockfile to reproduce the installed versions. [GitHub releases](https://github.com/raimshq/raims-node/releases/latest) also provide `raims-node.tgz` and `SHA256SUMS`. To install the archive, download both to a `raims-node-release` directory, verify the hash, and run: ```bash npm install ./raims-node-release/raims-node.tgz ``` ## Configure the client Get a key from [API keys](/en/integracoes/chaves-api) and store it in a vault or protected application environment variable. Keep the credential in the backend, out of browsers, applications distributed to customers, and logs. The validated API key determines company, environment, and permissions. Sandbox and Production use `https://api.raims.com`. ```js import Raims from '@raimshq/raims'; const apiKey = process.env.RAIMS_API_KEY; if (!apiKey) throw new Error('Set RAIMS_API_KEY on the server.'); const raims = new Raims(apiKey, { maxNetworkRetries: 0 }); const customers = await raims.customers.list({ page_size: 20 }); for (const customer of customers.list) { console.log(customer.id); } ``` Reuse the instance to reuse HTTP connections. In CommonJS, import it with `const Raims = require('@raimshq/raims')`. The following snippets assume an application-configured `raims` instance. ## Create a customer and a charge `customerTaxId` is the valid CPF or CNPJ of the authorized customer. `customerIdempotencyKey` and `chargeIdempotencyKey` are separate keys created and persisted before the requests. `chargeDueDate` is the chosen, persisted due date in UTC Unix seconds. ```js const customer = await raims.customers.create( { tax_id: customerTaxId, }, { idempotencyKey: customerIdempotencyKey }, ); const charge = await raims.charges.create( { customer_id: customer.id, amount_cents: 15000, due_date: chargeDueDate, title: 'Order 1234', }, { idempotencyKey: chargeIdempotencyKey }, ); const { statusCode, requestId } = charge.lastResponse; ``` If the CPF or CNPJ already exists in the same company and environment, the customer is updated and keeps its identifier. `15000` represents BRL 150.00. Keep the key and every parameter, including the due date, when recovering the same intent after losing a response. See [Create a charge](/en/api/charges). `undefined` omits a property; `null` is sent as null. Check the contract before clearing a field. Integers must fit within `Number.MAX_SAFE_INTEGER`, without conversion through fractional numbers. ## Pagination and pending results `await list()` fetches one page in `list`; `nextPage()` and `previousPage()` preserve filters and return `null` when there is no continuation. `for await` loads subsequent pages as you consume them; leaving the loop prevents further fetches. `processCustomer` represents your application logic. ```js for await (const customer of raims.customers.list({ page_size: 50 })) { await processCustomer(customer.id); } ``` Copy the received cursors and keep the filters; do not send `after` and `before` together. See [Listing and pagination](/en/api/listagem-e-paginacao). An HTTP `202` response indicates a pending result. It does not confirm payment or financial completion and does not start automatic polling. Retrieve the resource or follow the appropriate event before confirming the effect in your application. ## Idempotency and errors HTTP errors expose `statusCode`, `code`, and `requestId`. `ConnectionError` indicates a transport failure and can leave a write inconclusive. `maxNetworkRetries` configures retries for GET only; the default is zero. The SDK sends an idempotency key only when your application supplies it to an endpoint that accepts `Idempotency-Key`. It does not generate keys or retry writes automatically. A timeout does not prove that a write was rejected. Make decisions using the HTTP status and structured code; `error.message` is a human diagnostic that can change. Do not log complete responses, credentials, personal documents, or temporary URLs. See [Idempotency](/en/api/idempotencia) and the [SDK error guide](https://github.com/raimshq/raims-node/blob/main/docs/usage.md). ## Use Sandbox Use a Sandbox key for simulations in `raims.simulations.charges` and `raims.simulations.refunds`. A Production key does not become a Sandbox key when these services are used. Check the conditions in the [Simulations reference](/en/api/simulations/overview). Requests that ask for email or webhook deliveries can reach external destinations even in Sandbox. Use only destinations authorized for the integration. ## Receive webhooks `rawBody` contains the original bytes, such as a `Buffer` or `Uint8Array`. `receivedHeaders` contains the received headers. `persistEvent` and `rejectDelivery` represent your application logic; a persistence failure must return an HTTP error to allow redelivery. ```js import { SignatureVerificationError, Webhook } from '@raimshq/raims'; try { const event = Webhook.constructEvent(rawBody, receivedHeaders, webhookSecret); await persistEvent(event); } catch (error) { if (error instanceof SignatureVerificationError) rejectDelivery(); else throw error; } ``` Use the `secret_key` returned when creating or rotating the webhook, which differs from the API Bearer key. Read the body before the JSON parser and preserve its bytes: do not reserialize the content before authentication. After authentication, check the type and environment, deduplicate by the event `id`, and store the work durably before responding with success. The `webhook-id` header identifies the delivery, not the event. See [Receive events](/en/integracoes/webhooks/receber-eventos). ## Update the SDK To install the current stable version, run from your application directory: ```bash npm install @raimshq/raims@latest ``` Review the [release notes](https://github.com/raimshq/raims-node/releases) and test the flows used by your integration. Future updates are not installed automatically. If you use the TGZ, download the files from the current stable release again, verify the hash, and install the new archive. When migrating from an earlier TGZ, replace the `raims` dependency with `@raimshq/raims` and update your imports and `require` calls. The SDK version is independent of the API HTTP version `/v1`. Full guides and the method reference are in the [SDK repository](https://github.com/raimshq/raims-node). # PHP SDK (/en/integracoes/sdk-php) Use the `raims/raims-php` package to integrate a server application written in PHP with the public API. The SDK organizes resources into services, with typed responses, cursor pagination, and webhook signature verification. Keep the API key in the integration backend. Do not distribute credentials in code delivered to a browser or in your customers' applications. ## Install the package The SDK requires PHP 8.2 or later on a 64-bit platform, Composer 2, and the `curl`, `json`, and `hash` extensions. From your application directory: ```bash composer require raims/raims-php ``` The package is available on [Packagist](https://packagist.org/packages/raims/raims-php). Without a version argument, Composer installs the latest stable version compatible with the project and records the constraint in `composer.json`. Keep your application's `composer.lock` to repeat installation of the same version. Check extensions and platform requirements with `composer check-platform-reqs` after installing. The SDK does not require third-party production libraries. ## Configure the client Obtain a key through [API keys](/en/integracoes/chaves-api) and store it in a protected environment variable or your application's secret store. The validated credential determines the company, environment, and permissions in the API. Sandbox and Production use `https://api.raims.com`. ```php customers->all(['page_size' => 20]); foreach ($customers as $customer) { echo $customer->id, PHP_EOL; } ``` Reuse the instance to benefit from HTTP connections. The following snippets assume that the application has configured `$raims`. ## Create a customer and a charge `$customerTaxId` is a valid CPF or CNPJ belonging to the customer authorized by your application. `$customerIdempotencyKey` and `$chargeIdempotencyKey` are distinct keys, created and persisted before sending the requests. `$chargeDueDate` is the due date selected and persisted for the order, in Unix seconds UTC. ```php $customer = $raims->customers->create([ 'tax_id' => $customerTaxId, ], [ 'idempotency_key' => $customerIdempotencyKey, ]); $charge = $raims->charges->create([ 'customer_id' => $customer->id, 'amount_cents' => 15000, 'due_date' => $chargeDueDate, 'title' => 'Order 1234', ], [ 'idempotency_key' => $chargeIdempotencyKey, ]); $httpStatus = $charge->getLastResponse()->statusCode; $requestId = $charge->getLastResponse()->getRequestId(); ``` If the CPF or CNPJ already exists within the same company and environment, the customer is updated and keeps its identifier. `15000` represents BRL 150.00. See the fields and conditions in [Create charge](/en/api/charges). When repeating the same intent after losing a response, keep the key and every parameter, including the due date. An order's external reference does not replace idempotency. ## Pagination and pending results `all()` fetches one page. Enumerating that page does not send further requests. Use `nextPage()` and `previousPage()` to navigate; the SDK preserves filters and returns `null` when no page exists in the selected direction. `autoPagingIterator()` loads subsequent pages during enumeration and can send multiple requests. Leaving the `foreach` stops further fetches. Copy the returned cursors and keep the filters; do not send `after` and `before` together. See [Listing and pagination](/en/api/listagem-e-paginacao). An HTTP `202` response preserves its meaning as a pending result. It does not confirm payment or a completed financial result and does not start automatic polling. Retrieve the resource or monitor the appropriate event before confirming the effect in your application. ## Idempotency and errors Pass `idempotency_key` in request options only for endpoints that accept `Idempotency-Key`. The SDK does not generate keys or automatically retry POST, PATCH, or DELETE. Read retries are optional; the default is zero. Handle HTTP failures through `ApiErrorException`, using `getHttpStatus()` and `getErrorCode()`. `getRequestId()` helps identify the attempt. The text in `error.message` is a human diagnostic and must not be compared as a control code. Do not log complete responses, credentials, personal documents, or temporary links. See [Idempotency](/en/api/idempotencia) and the [SDK error guide](https://github.com/raimshq/raims-php/blob/main/docs/errors-and-retries.md). In updates, omitting a field preserves its value. Sending `null` clears only fields whose contract permits that action. Use `(object) []` for an empty object in an input; an empty PHP array represents a list. Check each endpoint's conditions. ## Use Sandbox Use a Sandbox key for simulations in `$raims->simulations->charges` and `$raims->simulations->refunds`. A Production key does not become a Sandbox key when these services are used. See the rules and conditions in the [Simulations reference](/en/api/simulations/overview). Requests that ask for email or webhook deliveries can reach external destinations even in Sandbox. Use only destinations authorized for your integration. ## Receive webhooks Read the original body and the headers received by your server: ```php use Raims\Exception\SignatureVerificationException; use Raims\Webhook; $payload = file_get_contents('php://input'); if ($payload === false) { throw new RuntimeException('Unable to read the request body.'); } $headers = [ 'webhook-id' => $_SERVER['HTTP_WEBHOOK_ID'] ?? '', 'webhook-timestamp' => $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '', 'webhook-signature' => $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '', ]; try { $event = Webhook::constructEvent($payload, $headers, $webhookSecret); } catch (SignatureVerificationException $error) { http_response_code(400); exit; } ``` `$webhookSecret` is the `secret_key` returned when creating or rotating a webhook, not the API Bearer key. Preserve the original body bytes and do not reserialize the JSON before authentication. A failure raises `SignatureVerificationException`; do not process the body in that case. A valid signature does not eliminate duplicates. Check type and environment, deduplicate by the event `id`, and store the work durably before responding with success. The `webhook-id` header identifies the delivery and does not replace the event identifier. See [Receive events](/en/integracoes/webhooks/receber-eventos). ## Update the SDK To get the latest stable version, run the command again without a version argument: ```bash composer require raims/raims-php ``` Composer chooses a constraint based on the available versions and updates `composer.json` and `composer.lock`. Check the [releases](https://github.com/raimshq/raims-php/releases) and test the flows used by your integration. The SDK version is independent of the API HTTP version `/v1`. Full guides and the service reference are available in the [SDK repository](https://github.com/raimshq/raims-php). # Python SDK (/en/integracoes/sdk-python) Use the `raims` package in your integration backend, with synchronous and asynchronous clients, typed parameters, read-only responses, cursor pagination, and webhook authentication. ## Install the package The SDK requires Python 3.10 or later. In your application's virtual environment: ```bash python -m pip install raims ``` The [`raims`](https://pypi.org/project/raims/) package is on PyPI and keeps the same import name. Pip resolves its dependencies. Check the [release history](https://pypi.org/project/raims/#history) and pin the version you choose in your application's `requirements.txt` or lockfile. [GitHub releases](https://github.com/raimshq/raims-python/releases/latest) also provide wheel and source archives. To install the wheel, download the `.whl` file and `SHA256SUMS` into a `raims-python-release` directory, keep its original filename, and verify the hash. In a Bash shell, with only that wheel in the directory: ```bash python -m pip install ./raims-python-release/raims-*.whl ``` In PowerShell, select the downloaded file: ```powershell $wheels = @([System.IO.Directory]::GetFiles((Resolve-Path ./raims-python-release).Path, '*.whl')) if ($wheels.Count -ne 1) { throw 'Keep exactly one downloaded wheel in this directory.' } python -m pip install $wheels[0] ``` ## Configure the client Get a key from [API keys](/en/integracoes/chaves-api) and store it in a vault or protected application environment variable. Keep the credential in the backend, out of browsers, applications distributed to customers, and logs. The validated API key determines company, environment, and permissions. Sandbox and Production use `https://api.raims.com`. ```python import os from raims import RaimsClient api_key = os.environ["RAIMS_API_KEY"] with RaimsClient(api_key, max_network_retries=0) as raims: customers = raims.customers.list({"page_size": 20}) for customer in customers: print(customer.id) ``` Reuse the client for its intended lifecycle. `with` closes the synchronous client; for asynchronous use, choose `AsyncRaimsClient` with `async with` and `await` on calls. Keep one asynchronous instance per event loop lifecycle. ## Create a customer and a charge `customer_tax_id` is the valid CPF or CNPJ of the authorized customer. `customer_idempotency_key` and `charge_idempotency_key` are separate keys created and persisted before the requests. `charge_due_date` is the chosen, persisted due date in UTC Unix seconds. ```python from raims import RequestOptions with RaimsClient(api_key) as raims: customer = raims.customers.create( {"tax_id": customer_tax_id}, options=RequestOptions(idempotency_key=customer_idempotency_key), ) charge = raims.charges.create( { "customer_id": customer.id, "amount_cents": 15000, "due_date": charge_due_date, "title": "Order 1234", }, options=RequestOptions(idempotency_key=charge_idempotency_key), ) response = charge.last_response if response is not None: print(response.status_code, response.request_id) ``` If the CPF or CNPJ already exists in the same company and environment, the customer is updated and keeps its identifier. `15000` represents BRL 150.00. Keep the key and every parameter, including the due date, when recovering the same intent after losing a response. See [Create a charge](/en/api/charges). Inputs retain the API JSON names. Omitting a key leaves the field absent; `None` sends null. Check the contract before clearing a value. Responses preserve future fields and should not be changed directly. ## Pagination and pending results `list()` fetches one page. Normal iteration reads only the received items; `next_page()` and `previous_page()` preserve filters. `auto_paging_iter()` loads subsequent pages as you consume it. With the asynchronous client, use `await` for the query and `async for` for the iterator. `process_customer` represents your application logic. ```python with RaimsClient(api_key) as raims: page = raims.customers.list({"page_size": 50}) for customer in page.auto_paging_iter(): process_customer(customer.id) ``` Copy the received cursors and keep the filters; do not send `after` and `before` together. See [Listing and pagination](/en/api/listagem-e-paginacao). An HTTP `202` response indicates a pending result. It does not confirm payment or financial completion and does not start automatic polling. Retrieve the resource or follow the appropriate event before confirming the effect in your application. ## Idempotency and errors Handle HTTP failures through `ApiError`, using `status_code`, `code`, and `request_id`. `ConnectionError` indicates a transport failure and can leave a write inconclusive. `max_network_retries` configures retries for reads only; the default is zero. The SDK sends an idempotency key only when your application supplies it to an endpoint that accepts `Idempotency-Key`. It does not generate keys or retry writes automatically. A timeout does not prove that a write was rejected. Make decisions using the HTTP status and structured code; `error.message` is a human diagnostic that can change. Do not log complete responses, credentials, personal documents, or temporary URLs. See [Idempotency](/en/api/idempotencia) and the [SDK error guide](https://github.com/raimshq/raims-python/blob/main/docs/errors-and-retries.md). ## Use Sandbox Use a Sandbox key for simulations in `raims.simulations.charges` and `raims.simulations.refunds`. A Production key does not become a Sandbox key when these services are used. Check the conditions in the [Simulations reference](/en/api/simulations/overview). Requests that ask for email or webhook deliveries can reach external destinations even in Sandbox. Use only destinations authorized for the integration. ## Receive webhooks `raw_body` contains the received bytes and `received_headers` contains `webhook-id`, `webhook-timestamp`, and `webhook-signature`. `reject_delivery` and `persist_event` represent your application logic. Do not process a delivery whose signature failed. ```python from raims import SignatureVerificationError, Webhook try: event = Webhook.construct_event(raw_body, received_headers, webhook_secret) except SignatureVerificationError: reject_delivery() else: persist_event(event) ``` Use the `secret_key` returned when creating or rotating the webhook, which differs from the API Bearer key. Read the body before the JSON parser and preserve its bytes: do not reserialize the content before authentication. After authentication, check the type and environment, deduplicate by the event `id`, and store the work durably before responding with success. The `webhook-id` header identifies the delivery, not the event. See [Receive events](/en/integracoes/webhooks/receber-eventos). ## Update the SDK To install the current stable version, run in your application environment: ```bash python -m pip install --upgrade raims ``` Review the [release notes](https://github.com/raimshq/raims-python/releases) and test the flows used by your integration. Pin the version and dependencies in your application's dependency configuration to reproduce the installation. Future updates are not installed automatically. If you installed from GitHub, the `raims` import stays the same. Update the dependency source in your application configuration if it pins a Git URL or local file. To keep using the GitHub wheel, download the files from the new release, verify the hash, and install the new wheel with `--upgrade`. The SDK version is independent of the API HTTP version `/v1`. Full guides and the method reference are in the [SDK repository](https://github.com/raimshq/raims-python). # Ruby SDK (/en/integracoes/sdk-ruby) The official Ruby SDK connects server applications to the Raims public API. It provides resource services, typed responses, cursor pagination, and webhook verification. Keep the API key in your backend, outside code distributed to customers and routine logs. The [SDK reference](https://github.com/raimshq/raims-ruby/blob/main/docs/reference.md) lists each resource's methods and parameters. ## Install the SDK Use Ruby 3.3 or later. The [`raims`](https://rubygems.org/gems/raims) gem is available on RubyGems. Install it in your application's environment: ```bash gem install raims ``` For Bundler, add the dependency to `Gemfile`, using RubyGems as the source: ```ruby source 'https://rubygems.org' gem 'raims' ``` Install the dependencies: ```bash bundle install ``` RubyGems and Bundler resolve the gem's declared dependencies. Keep your application's `Gemfile.lock` to preserve the selected versions. Load the SDK with `require 'raims'`. [Stable GitHub releases](https://github.com/raimshq/raims-ruby/releases/latest) also provide `raims.gem` and `SHA256SUMS`. To install from a file, download both into a new directory through the release page or GitHub CLI: ```bash gh release download --repo raimshq/raims-ruby --pattern raims.gem --pattern SHA256SUMS --dir raims-ruby-release ``` Check the download source and compare the SHA-256 of `raims.gem` with its entry in `SHA256SUMS`. Install the local file: ```bash gem install ./raims-ruby-release/raims.gem ``` ## Configure the client Obtain a credential through [API keys](/en/integracoes/chaves-api) and store it in `RAIMS_API_KEY` or your application's secret store. The key determines company, environment, and permissions. Sandbox and Production use `https://api.raims.com`. ```ruby require 'raims' raims = Raims::RaimsClient.new(ENV.fetch('RAIMS_API_KEY')) begin balance = raims.balances.retrieve request_id = balance.last_response.request_id ensure raims.close end ``` Reuse the client and close it when finished. `RaimsClient.open` with a block also guarantees closure. The following snippets assume an open `raims` instance. Timeouts use seconds; read retries are disabled by default. ## Create a customer and a charge Set `customer_tax_id` to the authorized customer's valid CPF or CNPJ. Create and persist separate `customer_key` and `charge_key` values for each intent before sending. `due_date_unix` is the charge's chosen due date in UTC Unix seconds; keep it when retrying the same intent. ```ruby customer = raims.customers.create( {tax_id: customer_tax_id}, {idempotency_key: customer_key} ) charge = raims.charges.create( {customer_id: customer.id, amount_cents: 15000, due_date: due_date_unix, title: 'Order 1234'}, {idempotency_key: charge_key} ) pending = charge.last_response.status_code == 202 ``` `15000` represents BRL 150.00. Inputs use hashes with JSON field names; omitted fields remain absent and `nil` sends JSON `null` where allowed. For example, `raims.customers.update(customer.id, {external_reference: nil})` clears that reference; omission preserves its value. Responses expose readers such as `customer.id`; use `key?` to distinguish absence from null. ## Pagination and pending results ```ruby page = raims.customers.list({page_size: 50}) page.auto_paging_each do |customer| process_customer(customer) end ``` `process_customer` belongs to the application. `each` visits only the received page; `auto_paging_each` fetches subsequent pages and preserves filters and options. `next_page` and `previous_page` return another page or `nil`. Do not combine `after` and `before` or interpret cursor contents. HTTP `202` indicates a pending result. Retrieve the resource or process the appropriate webhook before confirming a payment, refund, or cancellation. ## Idempotency and errors ```ruby begin customer = raims.customers.retrieve(customer_id) rescue Raims::RaimsError => error handle_failure(error.http_status, error.code, error.request_id) end ``` `handle_failure` represents your failure handling. Use status, code, and Request-Id; human messages are not control codes. `ArgumentError` identifies invalid local arguments. Do not log credentials, complete bodies, or temporary access links. The SDK does not generate idempotency keys or retry writes automatically. After a lost response, retrieve the resource and, when the endpoint permits retrying the request, reuse the original key and parameters. Configure `max_network_retries` on the client or request options for eligible GET/HEAD read retries only. The default is zero; `Retry-After` follows the SDK's bounded wait policy. See [Idempotency](/en/api/idempotencia). ## Use Sandbox Use a Sandbox key and a charge belonging to that environment: ```ruby Raims::RaimsClient.open(ENV.fetch('RAIMS_SANDBOX_API_KEY')) do |sandbox| result = sandbox.simulations.charges.confirm_payment(sandbox_charge_id) end ``` The SDK does not turn a Production key into Sandbox or offer an environment selector. See the conditions under [Simulations](/en/api/simulations/overview). Email requests and webhook deliveries may reach external destinations even in Sandbox; use authorized destinations. ## Receive webhooks Preserve `raw_body`, the string containing the original bytes received by your server, and `signing_headers`, the hash containing `webhook-id`, `webhook-timestamp`, and `webhook-signature`. Preserve repeated occurrences so ambiguity can be rejected. ```ruby begin event = Raims::Webhook.construct_event( raw_body, signing_headers, ENV.fetch('RAIMS_WEBHOOK_SECRET') ) persist_event(event) rescue Raims::SignatureVerificationError reject_delivery end ``` `persist_event` and `reject_delivery` belong to your application. `RAIMS_WEBHOOK_SECRET` contains the webhook's `secret_key`, not the API key. Do not reserialize JSON before verification. Do not process an invalid event. The default tolerance is 300 seconds; keep the server clock synchronized. A valid signature does not prevent redelivery: check type and environment, deduplicate the event `id`, and store the work durably before returning success. `webhook-id` identifies the delivery. See [Receive events](/en/integracoes/webhooks/receber-eventos). ## Update the SDK For applications using Bundler, update the gem and its dependencies within the constraints declared in `Gemfile`: ```bash bundle update raims ``` Review and keep the updated `Gemfile.lock`. For an installation managed directly through RubyGems, use: ```bash gem update raims ``` If `Gemfile` used source downloaded from GitHub, replace its `path:` or `git:` declaration with `gem 'raims'`, using `https://rubygems.org` as the source, and run `bundle update raims`. The `require 'raims'` statement stays the same. Read the [version history](https://rubygems.org/gems/raims/versions) and test the flows used by your integration before updating the application. Installation does not enable automatic future updates. # Rust SDK (/en/integracoes/sdk-rust) The official Rust SDK provides typed services, pagination, and webhook verification for server integrations with the public API. Keep the API key in your backend instead of distributing it in customer applications. The [SDK reference](https://github.com/raimshq/raims-rust/blob/main/docs/reference.md) lists each resource's methods and parameters. ## Install the SDK Use Rust 1.90 or later and a Tokio runtime. The official [`raims`](https://crates.io/crates/raims) crate is available on crates.io. From your application directory: ```bash cargo add raims cargo add tokio --features macros,rt-multi-thread ``` Cargo fetches from crates.io, selects the compatible stable version, and records resolved versions in `Cargo.lock`. Keep the lockfile for repeatable installation. [GitHub releases](https://github.com/raimshq/raims-rust/releases/latest) continue to provide source code and the `.crate` archive. For a Git or local path installation, read the [repository instructions](https://github.com/raimshq/raims-rust/blob/main/docs/installation.md). ## Configure the client Obtain a key through [API keys](/en/integracoes/chaves-api) and keep it in `RAIMS_API_KEY` or your secret store. It determines company, environment, and permissions. Sandbox and Production use `https://api.raims.com`. ```rust use raims::RaimsClient; #[tokio::main] async fn main() -> Result<(), Box> { let client = RaimsClient::new(std::env::var("RAIMS_API_KEY")?)?; let balance = client.balances().retrieve().await?; println!("HTTP status: {}", balance.last_response.status_code); Ok(()) } ``` Reuse the client; clones share its HTTP pool. Other snippets using `await` belong inside asynchronous functions returning `Result`. Use `RaimsClient::builder` with `timeout`, accepting `std::time::Duration`, and `max_read_retries` to configure timeout and read retries. The timeout covers attempts and waits; retries default to zero. ## Create a customer and a charge `customer_tax_id`, `customer_key`, and `charge_key` are application `String` values. The first is a valid, authorized CPF or CNPJ; the keys are separate and persisted before sending. `due_date_unix` is an `i64` in UTC Unix seconds, chosen and persisted for this charge. ```rust use raims::{params::{CreateCustomerParams, CreateChargeParams}, Optional, RequestOptions}; let customer_params = CreateCustomerParams { tax_id: Optional::Value(customer_tax_id), ..Default::default() }; let customer_options = RequestOptions { idempotency_key: Some(customer_key), ..Default::default() }; let customer = client.customers() .create_with_options(&customer_params, &customer_options).await?; let charge_params = CreateChargeParams { customer_id: Optional::Value(customer.data.id), amount_cents: Optional::Value(15000), due_date: Optional::Value(due_date_unix), title: Optional::Value("Order 1234".to_owned()), ..Default::default() }; let charge_options = RequestOptions { idempotency_key: Some(charge_key), ..Default::default() }; let charge = client.charges() .create_with_options(&charge_params, &charge_options).await?; let pending = charge.last_response.status_code == 202; ``` `15000` represents BRL 150.00. `Optional::Unset` leaves a field absent, `Optional::Null` sends null where permitted, and `Optional::Value(...)` sets a value. For updates, omission preserves a field and null may clear it under the contract. `ApiResponse` contains `data`, `last_response`, and `raw`; use `raw` when response absence and null must be distinguished. ## Pagination and pending results ```rust use raims::{params::ListCustomersParams, Optional}; let filters = ListCustomersParams { page_size: Optional::Value(50), ..Default::default() }; let mut pages = client.customers().list_pages(&filters)?; while let Some(response) = pages.next_page().await? { for customer in response.data.list { process_customer(customer); } } ``` `process_customer` represents your application. Creating a pager sends no HTTP; `next_page().await` fetches the first page and follows its cursors. Reading a response list does not fetch pages itself. The pager preserves filters and options; a failed fetch does not advance its cursor. Use `previous_page().await` to move backward. Cursors are opaque; do not combine `after` and `before`. HTTP `202` remains pending. Retrieve the resource or follow its appropriate webhook before confirming payment, refund, or cancellation. ## Idempotency and errors ```rust match client.customers().retrieve(&customer_id).await { Ok(response) => process_customer(response.data), Err(error) => handle_failure( error.kind(), error.status_code(), error.code(), error.request_id() ), } ``` The handlers belong to your application. Requests return `Result, Error>`; `kind()`, `status_code()`, `code()`, and `request_id()` help decide the next action. Do not treat human messages as codes or log complete bodies or secrets. The SDK does not generate keys or retry writes automatically. After a lost response, reconcile the operation and preserve the original key and parameters if the endpoint permits another attempt. `max_read_retries` enables eligible read retries only. `Retry-After` and attempts share the timeout budget; local cancellation does not reverse work accepted by the API. See [Idempotency](/en/api/idempotencia). ## Use Sandbox Use a Sandbox credential and a charge from that environment: ```rust let sandbox = RaimsClient::new(std::env::var("RAIMS_SANDBOX_API_KEY")?)?; let result = sandbox.simulations().charges() .confirm_payment(&sandbox_charge_id).await?; ``` `sandbox_charge_id` is a `String` obtained in your Sandbox integration. The SDK does not select an environment by header or convert a Production credential. See [Simulations](/en/api/simulations/overview). Email requests and webhooks may still reach external destinations; use authorized ones only. ## Receive webhooks Preserve `raw_body` as `&[u8]`, `signing_headers` as a list of `(&str, &str)` pairs, and `webhook_secret` as the webhook's `secret_key` string. Include all occurrences of `webhook-id`, `webhook-timestamp`, and `webhook-signature`; do not collapse them before verification. ```rust use std::time::SystemTime; use raims::{construct_webhook_event, DEFAULT_WEBHOOK_TOLERANCE}; let event = construct_webhook_event( raw_body, &signing_headers, &webhook_secret, DEFAULT_WEBHOOK_TOLERANCE, SystemTime::now(), )?; persist_event(event); ``` `persist_event` belongs to your application. The signature is checked before JSON decoding; do not reserialize the body. The default tolerance is five minutes in either direction; keep the server clock synchronized. `verify_webhook_signature` authenticates without decoding the event. Check type and environment, deduplicate the event `id`, and persist the work before returning success. `webhook-id` identifies the delivery and does not replace the event ID. See [Receive events](/en/integracoes/webhooks/receber-eventos). ## Update the SDK Read the [release notes](https://github.com/raimshq/raims-rust/releases/latest) and update the SDK within the requirement declared in `Cargo.toml`: ```bash cargo update -p raims ``` This command preserves the existing requirement. To select the current stable version outside that requirement or migrate from Git or a local directory, record the dependency options your application uses. Remove only the `raims` entry from the manifest that declares it and keep `Cargo.lock`. For an inherited workspace dependency, change its `[workspace.dependencies]` entry. If it is optional, preserve and temporarily remove dependency references in `[features]`, such as `dep:raims`, to keep the manifest valid. After adding the dependency, restore those declarations together with its `optional` and feature options. From your application directory: ```bash cargo add raims ``` Reapply the dependency options, such as features, and review the entry in `Cargo.toml`: it must use the registry version requirement selected by Cargo, without `git`, `path`, `branch`, `tag`, or `rev`. Review and keep the updated `Cargo.lock`, and test the flows used by your integration before updating the application. Installation does not apply future updates automatically. # Official SDKs (/en/integracoes/sdks) The official SDKs connect your application's backend to the Raims public API. Each guide covers requirements, installation, configuration, creating charges, pagination, errors, and webhook verification. ## Choose an SDK Use the guide for your backend language. Installation channels vary by SDK: | Language | Guide | Distribution | | ---------------------- | ---------------------------------------- | ------------------------------------- | | C# and .NET | [.NET SDK](/en/integracoes/sdk-dotnet) | NuGet, `Raims` package | | PHP | [PHP SDK](/en/integracoes/sdk-php) | Packagist, `raims/raims-php` package | | Go | [Go SDK](/en/integracoes/sdk-go) | Go module on GitHub | | Java | [Java SDK](/en/integracoes/sdk-java) | Maven Central, `com.raims:raims-java` | | Python | [Python SDK](/en/integracoes/sdk-python) | PyPI, `raims` package | | Node.js and TypeScript | [Node.js SDK](/en/integracoes/sdk-node) | npm, `@raimshq/raims` package | | Ruby | [Ruby SDK](/en/integracoes/sdk-ruby) | RubyGems, `raims` gem | | Elixir | [Elixir SDK](/en/integracoes/sdk-elixir) | Hex, `raims` package | | Rust | [Rust SDK](/en/integracoes/sdk-rust) | crates.io, `raims` crate | | Delphi | [Delphi SDK](/en/integracoes/sdk-delphi) | Source code in GitHub releases | Read the guide before installing to check language versions, dependencies, and platform requirements. To update, follow the same guide and review the release notes for the version you choose. ## Prepare your integration Keep your API key on the server. Do not include it in code delivered to browsers, mobile apps, or your customers' desktop applications. Obtain the credential in [API keys](/en/integracoes/chaves-api). The validated credential determines the company, environment, and permissions. Sandbox and Production use `https://api.raims.com`; the SDK does not change the key's environment. Start with a Sandbox key and review the conditions in [Authentication](/en/integracoes/autenticacao). The SDKs preserve the API rules: monetary amounts in cents, dates in UTC Unix seconds, pending HTTP `202` results, and application-supplied idempotency. Check the [API reference](/en/api) for each operation's fields and conditions. # CPF and CNPJ validation (/en/integracoes/validacao-cpf-cnpj) Before calling the Raims API with `tax_id`, your integration must validate the CPF or CNPJ format and check digits in your own system. Run this check as your customer enters the document number so you can show what needs correcting in the field itself. This avoids requests with an invalid `tax_id` and validation errors in the application consuming our API, improving the experience for your end customers. The `tax_id` field accepts CPF, numeric CNPJ, and alphanumeric CNPJ. Validation checks the format and the two check digits, which are calculated from the preceding characters. In API responses, `tax_id_type` identifies the document returned in `tax_id`: `cpf` for CPF and `cnpj` for CNPJ, whether numeric or alphanumeric. ## Before sending tax\_id Complete these steps in your system before sending the request to Raims servers: **Receive the document** Read it as text. Preserve leading zeros and letters in alphanumeric CNPJ. **Normalize and validate** Normalize formatting and check length, characters, and check digits in the backend. **Send to the API** Send `tax_id` as a JSON string and handle the API response, which also validates the document. **Request a correction** Highlight the field and keep the entered value. Ask for a correction before sending, without replacing the digits. Form validation does not replace validation in the integration backend. Use a message such as "Check the TaxId you entered". Keep the entered value so your customer can correct it. The integration must send the document provided by the customer, without replacing its check digits with others that make the calculation pass. ### JavaScript example The JavaScript code is a reference for implementing validation in your integration's language. Apply the same rules in the backend and, when there is a form, also in the interface to guide users as they enter the data. In this example, the function returns the normalized document when it is valid, or `null` when it needs correcting. It accepts CPF, numeric CNPJ, and alphanumeric CNPJ. ```js title="validacao-cpf-cnpj.js" function normalizeAndValidateTaxId(value) { if (typeof value !== 'string') return null; const input = value.replace(/[\p{White_Space}./-]/gu, ''); if (!/^[0-9A-Za-z]+$/.test(input)) return null; const taxId = input.toUpperCase(); const isCpf = /^[0-9]{11}$/.test(taxId); const isCnpj = /^[0-9A-Z]{12}[0-9]{2}$/.test(taxId); if (!isCpf && !isCnpj) return null; if (isCpf && /^([0-9])\1{10}$/.test(taxId)) return null; const base = taxId.slice(0, -2); if (isCnpj && base === '000000000000') return null; const weights = isCpf ? [11, 10, 9, 8, 7, 6, 5, 4, 3, 2] : [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2]; const first = calculateCheckDigit(base, weights.slice(1)); const second = calculateCheckDigit(`${base}${first}`, weights); return taxId.endsWith(`${first}${second}`) ? taxId : null; } function calculateCheckDigit(base, weights) { const sum = [...base].reduce( (total, character, index) => total + (character.charCodeAt(0) - 48) * weights[index], 0, ); const remainder = sum % 11; return remainder < 2 ? 0 : 11 - remainder; } // Illustrative TaxId used in the Receita Federal check digit manual. const taxId = normalizeAndValidateTaxId('12.abc.345/01de-35'); if (taxId === null) { throw new Error('Check the TaxId you entered'); } const body = { tax_id: taxId }; // { tax_id: '12ABC34501DE35' } // Add the other fields required by the endpoint before sending. ``` For a CPF such as `123.456.789-09`, the function returns `12345678909`. Inputs such as `00000000000`, `12ABC34501DE34`, or a value received as a number return `null`. Handle this result in the form or backend flow before building the request. ### Normalize the document Remove spaces, periods (`.`), slashes (`/`), and hyphens (`-`), and convert letters to uppercase. Raims accepts this formatting and applies normalization before checking the document. | Illustrative input | Normalized value | | -------------------- | ---------------- | | `123.456.789-09` | `12345678909` | | `12.abc.345/01de-35` | `12ABC34501DE35` | Keep the document as text at every step. Converting it to a number removes leading zeros; extracting only numbers removes the letters from an alphanumeric CNPJ. Characters outside the allowed sets must produce a validation message rather than being silently removed. Numeric CNPJs remain valid and coexist with the alphanumeric format. Prepare fields, masks, and libraries for both, as described in the [Receita Federal questions and answers about alphanumeric CNPJ](https://www.gov.br/receitafederal/pt-br/centrais-de-conteudo/publicacoes/perguntas-e-respostas/cnpj/cnpj-alfanumerico.pdf). ### How to validate a CPF After normalization, a CPF must have exactly 11 characters, all from `0` to `9`. Raims rejects sequences with the same repeated digit, such as `00000000000` and `11111111111`. The first nine digits form the base; the last two are check digits. Calculate each check digit using modulo 11: 1. Multiply the nine base digits, from left to right, by the weights `10, 9, 8, 7, 6, 5, 4, 3, 2` and add the products. 2. Find the remainder when dividing the sum by `11`. If it is `0` or `1`, the check digit is `0`; otherwise, it is `11 - remainder`. 3. Append the first calculated check digit to the base. Repeat with the weights `11, 10, 9, 8, 7, 6, 5, 4, 3, 2` to obtain the second. 4. Compare the two results with the last two digits received. The procedure is documented in the [National Treasury GRU collection protocol, section IV](https://cdn.tesouro.gov.br/sistemas-internos/apex/producao/sistemas/thot/arquivos/publicacoes/31906_1049829/Protocolo_arrecadacao_GRU.pdf?v=7014). In the illustrative example `12345678909`, the first sum is `210`, with remainder `1`, producing `0`. The second sum is `255`, with remainder `2`, producing `9`. The calculated check digits match `09`. ### How to validate a CNPJ After normalization, check these conditions: | Part | Format | | ------------------- | --------------------------------------------------------- | | First 12 characters | Numbers from `0` to `9` or letters from `A` to `Z`. | | Last 2 characters | Numbers from `0` to `9` only, which are the check digits. | | Total | Exactly 14 characters. | Raims also rejects a CNPJ whose 12 base characters are all zero, including `00000000000000`. The calculation is the same for numeric and alphanumeric CNPJ: 1. Convert each base character to `ASCII code - 48`. Numbers keep their value; `A` is `17`, `B` is `18`, and `Z` is `42`. 2. Multiply the 12 values by the weights `5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2` and add the products. 3. Divide the sum by `11`. A remainder of `0` or `1` produces check digit `0`; otherwise, use `11 - remainder`. 4. Append the first check digit and repeat with the weights `6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2`. 5. Compare the two calculated check digits with those received. The [check digit calculation manual published by Receita Federal](https://www.gov.br/receitafederal/pt-br/centrais-de-conteudo/publicacoes/documentos-tecnicos/cnpj/manual-dv-cnpj.pdf) uses `12ABC34501DE35`: the sums `459` and `424` produce check digits `3` and `5`. This is a calculation example and does not identify a Raims customer. ## How to handle INVALID\_TAXID When the API returns HTTP `400` with `error.code` equal to `INVALID_FIELDS`, look for the item with `field: "tax_id"` and `code: "INVALID_TAXID"` in `error.details`. This detail means the provided value did not pass CPF or CNPJ validation. Check its length after normalization, allowed characters, and both check digits. A CPF with all identical digits or a CNPJ with all 12 base characters equal to zero is also rejected. | Code in `error.details` for `tax_id` | What to correct | | ------------------------------------ | ------------------------------------------------------------------------------------ | | `REQUIRED` | Enter the document. The field is missing, null, or empty after normalization. | | `INVALID_TYPE` | Send a quoted JSON string instead of a number, object, or another incompatible type. | | `INVALID_TAXID` | Correct the format or check digits of the document provided. | Associate the error with the CPF/CNPJ field in your system's interface and keep the other entered data. Ask for a correction before trying again; resending the same invalid value does not resolve the issue. The API continues validating the document in every request, even if your application has already checked it. See the endpoint reference for the request fields and requirements, and [HTTP response codes](/en/api/codigos-http-das-respostas) for the general error format. ## What this validation confirms Passing the calculation confirms only that the format and check digits are consistent. It does not prove that a registration exists, that its status is regular, or that the document belongs to the person providing it. The examples in this guide explain the calculation; do not use them as real customer documents. When your flow requires registration or identity verification, perform the corresponding check. See the official Receita Federal services for [CPF registration status](https://www.gov.br/pt-br/servicos/consultar-cadastro-de-pessoas-fisicas) and [CNPJ lookup](https://www.gov.br/pt-br/servicos/consultar-cadastro-nacional-de-pessoas-juridicas). # Webhooks (/en/integracoes/webhooks) The Webhooks area lists the addresses registered by the company to receive notifications and the events selected for each destination. Go to **Integration / Webhooks**. Each registration belongs to the selected environment. **Sandbox and Production** events are sent to destinations registered in their respective environments. Sandbox uses test data but makes a real HTTPS request to your endpoint. Use a separate test destination to prevent a simulation from changing your Production system. See [Receive and validate events](/en/integracoes/webhooks/receber-eventos) to implement the receiver, validate the signature, and handle redeliveries. To manage the same registrations from your system, use the [Webhooks API](/en/api/webhooks/overview). Viewing requires **Webhooks**. Creating, renaming, editing the URL and events, pausing the queue, disabling, re-enabling, rotating, and deleting have their own permissions and may be blocked when the account is in view-only mode. If your endpoint restricts request sources, add the [official Raims IPs](/en/integracoes/webhooks/ips-oficiais) to the allowlist before receiving webhooks. ## Register a webhook ### Prepare the receiving address Go to **Integration / Webhooks / Webhook registration** with **Create webhooks**. Enter an HTTPS URL on the default port `443`, controlled by your company, with DNS resolving to a public IPv4 address. The address cannot use localhost, a direct IP, or include a username or password. ### Give it a clear name Identify the system, purpose, and environment, for example **ERP - Sandbox payments**. ### Select at least one event Choose only the groups your system needs to follow. ### Store the secret Select **Create** and save the displayed secret in a secrets vault. Do not expose it in the browser, URLs, repositories, or logs. ## Events available in the Dashboard The form organizes events into charges and refunds. The names below identify the categories selected during registration. Selecting a type does not create an occurrence. Delivery depends on confirmation of the corresponding event. | Item | Type | Description | | --- | --- | --- | | charge.created | Charges | A charge was created. | | charge.paid | Charges | Payment of a charge was confirmed. | | charge.canceled | Charges | A charge was canceled. | | charge.failed | Charges | Payment failed. | | refund.requested | Refunds | A refund was requested. | | refund.completed | Refunds | A refund was completed. | | refund.failed | Refunds | A refund failed. | ## Latest webhook activity **Last activity** shows the time of the latest recorded delivery attempt, including failed attempts. This time does not confirm that the endpoint received or processed the event and may take a while to appear. **No record** means there is no confirmed attempt available to display. It does not prove that no deliveries have ever been sent. **Unavailable** means the information could not be retrieved at that moment; try again later. Older activity may remain visible even when that attempt's logs are outside the available lookup period. Access to this information requires only **Webhooks**; viewing logs has its own permission. To investigate a failure episode through the API, use [Check webhook health](/en/api/webhooks/health). This query shows the available times and duration of recorded failures without testing the receiver URL. ## Protect the secret The complete secret is authentication data. Store it in your application's private environment and limit access to those who manage the integration. The webhook identifier does not replace this secret. To check the authenticity of each request, follow [signature validation](/en/integracoes/webhooks/receber-eventos#validar-a-assinatura) using the original received body. Do not send the secret to support or include it in screenshots. If you suspect exposure, rotate the secret and update the configuration using it. Query the current charge or refund state through the API before making a financial decision. ## Rename a webhook 1. Go to **Integration / Webhooks** and open the destination's actions. 2. Select **Rename webhook**, enter the new name, and confirm the change. 3. Check the updated name in the list. This action requires **Edit webhooks**. Renaming does not change the URL or events. ## Edit URL and events The **Edit URL and events** action changes the receiving address and event selection for the same registration. It requires **Webhooks** and **Edit webhook URLs and events**, plus the identity confirmation requested by the Dashboard. The URL follows the [registration rules](#cadastrar-um-webhook), and at least one event must remain selected. The name, identifier, secret, and status are preserved. Editing the configuration does not re-enable a disabled webhook, reset the failure count, or extend retry deadlines. Changes apply to subsequent selections and delivery attempts. Removing an event type stops authorizing it for new sends. Requests already authorized or in progress may finish with the previous configuration. Adding a type may also send earlier events that were still waiting to be prepared. Editing does not resend completed deliveries. Previously selected events may be kept or removed even when they are no longer available for new registrations. If you remove one of these events and save, it cannot be selected again while it remains outside the current catalog. ## Pause and resume the queue Use **Pause queue** in the webhook menu before maintenance on the receiver. Check the notice and complete identity confirmation. This action requires **Webhooks** and **Edit webhook URLs and events** and is available for an active registration. The **Queue paused** indicator confirms the setting. Pending deliveries and newly selected events wait, but their deadlines continue counting down: up to 72 hours in Production and four hours in Sandbox. Requests already authorized may finish. If a delivery expires during the pause, it will not be sent when the queue resumes. After maintenance, choose **Resume queue** from the same menu and confirm. Deliveries that remain valid become eligible to be sent again, subject to delivery limits. Resuming does not guarantee immediate delivery or a specific order. Pausing and resuming close the previous failure episode without proving that the receiver has recovered. Check the results in the logs. To control the pause from your integration, use [Pause or resume the queue](/en/api/webhooks/pause). You can request a [technical test](/en/api/webhooks/test) during the pause to check the receiver before resuming. ## Disable and re-enable a webhook The **Disable webhook** and **Re-enable webhook** actions require **Edit webhooks** and the identity confirmation requested by the Dashboard. They preserve the registration, secret, and selected events. A disabled webhook receives no new sends. If a pending attempt finds the registration disabled, that delivery is closed. Re-enabling it before that attempt allows delivery to continue within its original deadline. The action does not resend history or automatically recover closed deliveries. [Manual resend](/en/integracoes/webhooks/receber-eventos#reenvio-manual-de-eventos) lets you request another delivery for an eligible event. For maintenance that preserves deliveries that remain valid, use [Pause and resume the queue](#pausar-e-retomar-a-fila). If a registration is disabled while the queue is paused, re-enabling it preserves the pause; use **Resume queue** to allow sends. Failures do not automatically pause or disable the registration. Fix the receiver and follow new attempts, which continue within each delivery's limits. See [Webhook failures and retries](/en/integracoes/webhooks/receber-eventos#falhas-e-novas-tentativas-de-webhook) and [failure alerts](/en/integracoes/webhooks/receber-eventos#alertas-de-falhas). ## Rotate the signature 1. Go to **Integration / Webhooks** and open the correct destination's actions. 2. Select **Rotate signature**. 3. Check the notice, confirm the rotation, and store the new secret. 4. Update the receiver and check that it accepts events signed with the new secret. This action requires **Rotate webhooks** and keeps the registration identifier. In the Dashboard, replacement is immediate: new sends use only the new secret as soon as rotation is confirmed. If a transition was started through the API, rotating in the Dashboard also ends that transition and replaces both previous secrets. Update the receiver to avoid rejections. Requests already authorized or in progress may still arrive with a previous signature. If a secret was exposed, also remove the old secrets from the receiver's configuration. Rotation does not re-enable a disabled webhook or reset the failure count. The API lets you choose a [transition period](/en/api/webhooks/overview#rotacionar-o-segredo) for a planned change. The Dashboard does not use this option. ## Delete a webhook 1. Go to **Integration / Webhooks** and open the actions for the destination you want to remove. 2. Select **Delete webhook**, check the destination, and confirm deletion. 3. Wait for the result and check the list. This action requires **Delete webhooks** and permanently removes the destination. First check whether a system depends on it. Deletion prevents new sends to that registration. Requests already authorized or in progress may still finish. - [Receive and validate events](/en/integracoes/webhooks/receber-eventos): Validate the signature, identify the resource, and handle retries. - [Official Raims IPs](/en/integracoes/webhooks/ips-oficiais): Configure allowed sources in the firewall, WAF, or proxy. - [API keys](/en/integracoes/chaves-api): Protect the credentials used by your integration. # Official Raims webhook IPs (/en/integracoes/webhooks/ips-oficiais) All webhooks sent by Raims use the IPv4 addresses listed on this page. Add all five addresses to the allowlist of the infrastructure protecting your receiving endpoint. ## Webhook source IPs ```text 18.230.162.249 54.94.189.157 54.21.10.37 54.233.100.88 54.232.137.193 ``` Allow all addresses: a delivery may come from any of them. If the tool requires CIDR notation, add `/32` to each IPv4 address to allow only that address. ### Production and Sandbox **Production and Sandbox** webhooks use the same five IPs. Allow this list through the firewall during Sandbox integration tests as well; there is no additional address list for that environment. ## When to configure the allowlist Configure the list when endpoint access depends on a source rule, such as a firewall, WAF, Security Group, reverse proxy, or load balancer. If your infrastructure already accepts public requests, check whether another rule could block webhooks. ## Configure endpoint access 1. Locate the layer controlling access to the address registered to receive webhooks. 2. Add the five official IPv4 addresses as allowed sources. 3. Restrict the rule to the webhook endpoint's domain and path when the tool permits. Allow `POST` requests received over HTTPS. 4. Check whether other security rules still block the request after the IP has been allowed. If the endpoint is dedicated to Raims webhooks, you can restrict its sources to this list. Preserve the access required by other application routes; do not apply this restriction to the entire site. **Webhooks cannot complete browser challenges** The endpoint must accept requests between systems without CAPTCHA, JavaScript challenges, or interactive login. If one of these checks blocks delivery, configure an exception only for the webhook endpoint and official IPs, keeping the other protections in place. ### Cloudflare and other proxies If the domain uses the Cloudflare proxy, configure the Raims IP list in Cloudflare's incoming rules. The origin server receives the connection from Cloudflare, so its firewall must continue allowing the proxy addresses. Restricting that firewall directly to the five Raims IPs may block forwarded requests. The same care applies to other proxies and load balancers. When using a header such as `CF-Connecting-IP` or `X-Forwarded-For` to identify the source, accept that information only from trusted proxies. A header sent directly by a client does not prove the source IP. See the Cloudflare documentation on [IP addresses](https://developers.cloudflare.com/fundamentals/concepts/cloudflare-ip-addresses/) and [WAF exceptions](https://developers.cloudflare.com/waf/managed-rules/waf-exceptions/) to configure your infrastructure. ## Validate the configuration After saving the rules, follow a webhook delivery: 1. Check the firewall, WAF, or proxy logs to see whether the request was allowed. 2. Confirm in the application logs that the `POST` reached the correct endpoint. 3. If there is a `403 Forbidden` response, identify which layer generated it and review the corresponding rule. Other WAF or application rules may reject the request even when the IP is already allowed. If there is no record of the request in the application, also check the registered address, DNS resolution, HTTPS certificate, and rules in the layers before the server. **The IP list complements authentication** Allowing the source on the network does not replace verifying the webhook's authenticity. Keep HTTPS and signature validation in the receiver. Protect the [webhook secret](/en/integracoes/webhooks#proteger-o-segredo) and do not include it in URLs, logs, or support messages. # Receive and validate webhooks (/en/integracoes/webhooks/receber-eventos) Prepare an HTTPS endpoint that accepts `POST` with `Content-Type: application/json`. Use the default port `443` and a domain whose DNS resolves to a public IPv4 address. It must receive calls between systems without interactive login, CAPTCHA, or redirects. Configure the destination and events in [Webhooks](/en/integracoes/webhooks), and allow the [five official IPs](/en/integracoes/webhooks/ips-oficiais) when sources are restricted. ## Event body Each request identifies the event, environment, and changed resource: ```json { "id": "d377b4c5-5678-4c42-8ea3-8f823156948e", "type": "charge.paid", "created_at": "2026-10-15T12:30:00.000Z", "environment": "sandbox", "data": { "object": "charge", "id": "ch_4ZxYp8Q2mV7nR6sT5uW3aB" } } ``` | Field | Meaning | | ------------- | --------------------------------------------------------------------------------------- | | `id` | Event UUID, preserved in redeliveries and across destinations receiving the same event. | | `type` | Event name, such as `charge.paid`, `refund.completed`, or `webhook.test`. | | `created_at` | Event date in UTC, in ISO 8601 format. It does not represent the time of each attempt. | | `environment` | `sandbox` or `production`, according to the resource's environment. | | `data.object` | Resource type: `charge` for a charge, `refund` for a refund, or `webhook` for a test. | | `data.id` | Public resource identifier: charge `ch_`, refund `rf_`, or webhook `whk_`. | The body keeps the same bytes in every attempt. Use `data.id` to query the current state in [Charges](/en/api/charges/overview) or [Refunds](/en/api/refunds/overview) with a key from the same company and environment. The event reports a change; processing it must not assume this is still the resource's latest state. `data` identifies the resource and does not contain the complete charge or refund record. `created_at` uses ISO 8601 in this body; dates returned by delivery and attempt queries use Unix seconds in UTC. ## Signature headers | Header | Meaning | | ------------------- | --------------------------------------------------------------------------------------- | | `webhook-id` | Delivery UUID for that destination. It remains the same in retries. | | `webhook-timestamp` | Attempt time in Unix seconds in UTC. | | `webhook-signature` | One or more `v1=` signatures, each with 64 hexadecimal characters, separated by commas. | The `webhook-id` differs from the body's `id`: an event may be delivered to more than one destination or manually resent. Each delivery has its own `webhook-id`. Retries of the same delivery preserve that ID and the original body but may have a different timestamp and signature. During a [transition period chosen through the API](/en/api/webhooks/overview#rotacionar-o-segredo), the same header contains the new secret's signature first, followed by the previous secret's: `v1=,v1=`. The receiver must accept the request when any `v1` signature matches the configured secret. When the deadline passes or an immediate rotation ends the transition, new sends include only the current secret's signature. ## Validate the signature 1. Capture the HTTP body as bytes before parsing the JSON. 2. Read the three signature headers. 3. Remove the `whsec_` prefix from the registration's secret and decode the remaining part as Base62, in this order: digits from `0` to `9`, letters from `A` to `Z`, and letters from `a` to `z`. Represent the number in **32 little-endian bytes**, padding with zeros on the right when needed. These bytes are the HMAC key. 4. Build the message from the UTF-8 bytes of `webhook-id + "." + webhook-timestamp + "."`, followed by the exact bytes of the received body. 5. Split the header's signatures by comma and select the `v1` values. Calculate HMAC-SHA256 and compare the result with each signature using a constant-time comparison. Accept the request if one matches. Do not use the `whsec_...` text directly as the HMAC key. Do not serialize the JSON again: spaces, line breaks, and property order are part of the signature. Configure the framework to preserve the original body on this route. An object already converted from JSON to the application's language cannot be used to check the signature. Reject the request without applying its effects if the signature or timestamp is invalid. We recommend accepting timestamps within five minutes of the receiver's clock and keeping that clock synchronized. This check reduces the reuse of old requests. Delivery deduplication remains necessary within that window. The tolerance applies to the attempt's `webhook-timestamp`, not to the body's `created_at`. Retries and resends receive a current timestamp and signature, while the original event date remains in the body. ### Node.js example The example receives the private secret, headers, and a `Buffer` containing the original body. It accepts either a single `v1` or the transition period's signatures, regardless of the valid signature's position. It does not log these values or parse the JSON before validation. ```js import { createHmac, timingSafeEqual } from 'node:crypto'; const alphabet = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'; function decodeWebhookSecret(secret) { if (!/^whsec_[0-9A-Za-z]{1,43}$/.test(secret)) { throw new Error('Invalid webhook secret'); } const encoded = secret.slice('whsec_'.length); if (encoded.length > 1 && encoded.startsWith('0')) { throw new Error('Invalid webhook secret'); } let value = 0n; for (const character of encoded) { value = value * 62n + BigInt(alphabet.indexOf(character)); } const key = Buffer.alloc(32); for (let index = 0; index < key.length; index += 1) { key[index] = Number(value & 255n); value >>= 8n; } if (value !== 0n) throw new Error('Invalid webhook secret'); return key; } export function verifyWebhook( secret, headers, rawBody, nowSeconds = Date.now() / 1000, ) { const id = headers['webhook-id']; const timestamp = headers['webhook-timestamp']; const signature = headers['webhook-signature']; if ( !Buffer.isBuffer(rawBody) || typeof id !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test( id, ) || typeof timestamp !== 'string' || !/^\d{1,12}$/.test(timestamp) || !Number.isFinite(nowSeconds) || Math.abs(nowSeconds - Number(timestamp)) > 300 || typeof signature !== 'string' ) { return false; } const signatures = signature .split(',') .map((entry) => entry.trim()) .filter((entry) => /^v1=[0-9a-f]{64}$/i.test(entry)); if (signatures.length === 0) return false; const key = decodeWebhookSecret(secret); try { const expected = createHmac('sha256', key) .update(`${id}.${timestamp}.`, 'utf8') .update(rawBody) .digest(); return signatures.some((entry) => { const received = Buffer.from(entry.slice('v1='.length), 'hex'); return timingSafeEqual(expected, received); }); } finally { key.fill(0); } } ``` After a valid signature, parse the JSON, check the environment, and record the delivery before responding. Store the secret on the integration server with restricted access. Never include it in URLs, browser code, screenshots, or support messages. ## Acknowledge receipt Respond with an HTTP `2xx` status only after accepting the event into durable storage in your system. Send lengthy processing to a queue and run it asynchronously. A successful response confirms that the receiver accepted the delivery; it does not confirm a new financial transaction. The receiver must follow this sequence: 1. Validate the signature using the original body and check the event environment. 2. Durably record the event `id` and the work to be processed. Ensure this acceptance prevents duplicates even when two requests arrive at the same time. 3. If the event has already been accepted, return `2xx` without recording the same work again. Otherwise, acknowledge receipt after saving. 4. Process the accepted work and track its completion separately. If that processing fails after the response, your system must recover it: Raims has already received the delivery acknowledgement. If you cannot store the event, do not acknowledge it with `2xx`. Subsequent processing must also tolerate repetitions without duplicating their effects. The timeout for each webhook HTTP send is **5 seconds in total**. Validate the signature, record the event safely, and return `2xx` within that time, without waiting for lengthy processing to finish. The up to 72 hours in Production is the retry window; a request does not stay open for that period. Raims does not follow redirects; register the final HTTPS URL directly, including a trailing slash when it is part of the receiver's path. The registration preserves that slash. Configure the certificate with a valid public chain. Each attempt's details in the logs may show the endpoint response body, limited to 8 KiB, and the destination IP used for that connection. Partially captured responses carry a notice. Content that was not recorded differs from a confirmed empty body; older records may lack this information. The body helps explain errors returned by the integration but must not contain secrets or unnecessary personal data. Use the Dashboard logs and receiver records to relate the result to the required correction. ## Handle redeliveries and ordering A delivery may arrive more than once, including when the receiver already accepted the event but the response was lost. Record `webhook-id` to recognize retries of the same delivery and use the body's `id` to prevent a manual resend of the same event from repeating its effect. Acknowledge previously accepted duplicates with `2xx` as well. Do not depend on arrival order. Events for different resources or retries may arrive in another sequence. Query the resource through the API when you need to decide based on its current state. If different destinations feed the same routine, the body's `id` identifies the same event across them. ## Manually resend events The Dashboard allows you to request a resend for up to **15 days after the event was created**, when the payload is available, the webhook is active, and the event type remains selected in the registration. The action requires **Webhooks**, **View event logs**, and **Resend webhook events**. To recover multiple events, use **Resend selected** in the Dashboard logs. Each item remains subject to the individual resend conditions. Check the accepted and rejected results before repeating the request. Technical `webhook.test` events cannot be resent; request another test. A resend creates a delivery with a new `webhook-id` and preserves the original body bytes, including `id` and `created_at`. It uses the webhook's current URL and secret. If a secret transition is active, the same signature rules as other sends apply. The request does not cancel automatic retries for the previous delivery. When the queue is paused, the new delivery also waits for it to resume, and its own deadline continues counting down. Prepare the receiver to recognize the same body `id` across different deliveries. Requesting a resend does not repeat the financial action that generated the event or confirm receipt by the endpoint. The retry window for this delivery starts when the resend request is accepted: up to 72 hours in Production or up to four hours in Sandbox, with a maximum of three retries after the initial attempt in Sandbox. In Production, intervals increase exponentially and vary between attempts, without a fixed count within the deadline. The limit for requesting another resend remains fifteen days after the original event was created; resending does not renew that limit or change the body's `created_at`. ## Pause and resume the queue Before maintenance, [pause the webhook queue](/en/api/webhooks/overview#pausar-e-retomar-a-fila). Pending deliveries and newly selected events wait for the queue to resume within their original deadlines. Pausing does not interrupt an already authorized HTTP call or freeze the 72-hour Production or four-hour Sandbox window. You can request a [technical test](/en/api/webhooks/test) while the queue is paused. After checking the receiver, resume the queue to allow sends that remain valid. Resuming does not recover expired deliveries. ## Webhook failures and retries An HTTP `2xx` response completes the delivery. Connection failures, timeouts, and other HTTP codes allow retries within the environment's limits. This includes `3xx`, `400`, `401`, `403`, `404`, `429`, and `5xx`. Raims does not follow redirects: configure the final HTTPS URL directly. The technical `webhook.test` event has one HTTP attempt and a deadline of up to five minutes to be sent. The retry rules below apply to charge and refund events. In **Production**, Raims retries delivery for up to **72 hours from the event**. Calculated intervals increase exponentially and vary between attempts, up to a one-hour limit. There is no fixed number of attempts within that deadline. In **Sandbox**, there are up to **three retries after the first attempt**, spread over a few hours, within a window of up to **four hours from the event**. Use this environment to check how your receiver handles duplicates and failures. `Retry-After` may specify a minimum wait in seconds or an HTTP date. A valid value may increase the interval beyond one hour. If that wait places the next attempt at or after the end of the delivery window, Raims does not schedule another attempt. The header does not extend the window or increase the number of Sandbox attempts. Check the address, signature, and firewall rules when investigating a failure; do not depend on an exact time for the next attempt. ## Failure alerts Failures do not automatically pause the queue or disable the webhook. Each delivery continues following its retry policy and deadline. After a delivery exhausts its limits, new events continue generating their own deliveries while the registration is active. Raims notifies you in the Dashboard when the fifth and tenth failures of the same episode are confirmed. Each alert is sent once per episode. An HTTP `2xx` response ends that episode; new failures may start another. Alerts do not stop retries or extend their deadlines. Sending these alerts by email depends on the **Webhook failure** preference. Recipients are verified email addresses belonging to the account. Alerts may be grouped into email summaries, with a link to view the notices in the Dashboard. Individual notices remain available in the Dashboard. Check the current registration state and logs to investigate a failure; an email summary may include alerts from before the endpoint recovered. Fix the receiver and follow subsequent attempts. If you disabled the webhook manually, re-enable it to allow new sends. Re-enabling starts a new failure episode and preserves the registration, secret, and selected events. Rotating the secret does not reset the count or re-enable a disabled webhook. Editing the URL or events also preserves the registration state, failure count, and retry deadlines. Disabling the registration prevents new sends. If a pending delivery's next attempt finds the webhook disabled, that delivery is closed. Re-enabling it before that attempt allows it to continue within the original limits. Re-enabling does not resend earlier events or automatically recover closed deliveries. When eligible, an event can receive a new delivery through [manual resend](#reenvio-manual-de-eventos). Requests in progress may still finish. ## Test receipt through the API After preparing the receiver, use [Send a test event](/en/api/webhooks/test) for the active webhook. The event arrives at the same URL and uses the same signature validation as other sends, with `type: webhook.test`, `data.object: webhook`, and the registration identifier in `data.id`. The test checks connectivity and signature validation. It does not change charges, payments, refunds, balance, or the webhook's failure count. Check the result in the receiver records. The up-to-five-minute deadline includes waiting until the test can be sent. The HTTP call to the receiver remains limited to five seconds. A `2xx` response to the test does not prove that your application handles financial events; check that flow with Sandbox simulations. Every new request creates a test. If it fails, fix the integration before requesting another; the technical event has no automatic retry after its HTTP attempt. ## Test webhooks in Sandbox Register a destination in Sandbox and select the events you want. Create a charge and use [Simulation](/en/api/simulations/overview) to confirm a payment or test failures and refunds. Confirmed changes generate the corresponding Sandbox events for that destination without moving real money. Webhook requests are real and use the same official IPs as Production. The body reports `environment: sandbox`. Keep the receiver and effects of this test separate from your system's Production data. # Payment methods (/en/meios-de-pagamento) Raims offers Pix and boleto. Checkout shows the options allowed for the charge, subject to platform availability and the charge, link, and account settings. Credit and debit cards are disabled and are not offered for payment. ## Pix and boleto For Pix, the payer uses the QR Code or Pix copy-and-paste code shown at checkout. For boleto, they use the document or payment line provided. Issuing payment details does not confirm that the charge has been paid. Check the charge status to track confirmation. To adjust the account defaults, see [Checkout and payment methods](/en/checkout#formas-de-pagamento). ## API codes When [creating a charge](/en/api/charges), use `payment_method_types` to set a custom list of accepted methods. Send the codes as numbers, without duplicates: `[1]` accepts Pix, `[2]` accepts boleto, and `[1, 2]` accepts both. A populated list overrides the account default for that charge only. It still respects the methods available on the platform, and a custom link configuration can reduce the options in that list. Omitting `payment_method_types` or sending `null` keeps the charge using the configuration applied by checkout. When the link has no custom configuration, the current account default applies, including later changes to it. An empty list does not mean that the charge should use this configuration. `payment_method` is a separate, optional field that defaults to `0` when omitted. Without a custom list, it has the following behavior: | Code | Payment method | Behavior | | ---- | -------------- | ---------------------------------------------------------------- | | `0` | Undefined | The payer chooses from the methods enabled for the charge. | | `1` | Pix | Requests Pix issuance during creation and allows only Pix. | | `2` | Boleto | Requests boleto issuance during creation and allows only boleto. | Without `payment_method_types`, choosing `payment_method: 1` or `payment_method: 2` restricts the charge to that method. It does not enable an option disabled in the configuration used by checkout. If that method is disabled, no other method is offered as an alternative. With a custom list in `payment_method_types`, omit `payment_method` or send `0`. Do not combine the list with `payment_method: 1` or `payment_method: 2`. The charge starts with an undefined method, even if the list allows only Pix or only boleto. The list accepts only `1` and `2`. Do not send `0`, other codes, strings, booleans, or `null` items. None of these settings changes the account default or confirms payment. With `payment_method: 1`, available Pix details appear in `payment_information.pix`; with `payment_method: 2`, boleto details appear in `payment_information.boleto`. Pending issuance preserves the charge ID so you can track it through the individual retrieval endpoint. See [Receive Pix details during creation](/en/api/charges/overview#receber-o-pix-na-criação) and [Receive boleto details during creation](/en/api/charges/overview#receber-o-boleto-na-criação), including customer data and address completion by postal code (CEP). ## Registered method and checkout selection In API queries, `payment_method` reports the method currently registered for the charge. When Pix or boleto generation is recorded, an undefined charge changes from `0` to `1` or `2`, according to the method used. `payment_method_types` reports the custom list configured during creation, or `null` when the charge uses the inherited configuration. This list does not change to reflect the selected method and does not represent the options available at that moment. `checkout_payment_method` reports the method recorded at checkout and returns `null` until that record exists. For example, after Pix generation is recorded for a charge created with `payment_method: 0`, retrieval reports `payment_method: 1` and `checkout_payment_method: 1`. Setting `payment_method: 1` during creation requests direct Pix issuance. Selecting an option on the screen alone does not confirm generation or payment. If the charge was created with `payment_method_types: [1, 2]`, recording Pix generation makes retrieval report `payment_method: 1`, while preserving `payment_method_types: [1, 2]`. The `payment_method` filter in [List charges](/en/api/charges/list) considers the currently registered method. Clicking an option at checkout without recording generation does not make an undefined charge match the Pix or boleto filter. # Types and identifiers (/en/tipos-e-identificadores) Use this map to understand a value returned by the API or an identifier shown in the Dashboard. Each page explains what the value represents, where it appears, and what you can conclude from it. ## How to find the meaning | What you found | Where to look | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | An ID such as `st_`, `ch_`, `wd_`, or `med_` | [Identifiers and prefixes](/en/tipos-e-identificadores/identificadores) | | `statement_type`, `reference_type`, or a payment method | [Financial types](/en/tipos-e-identificadores/financeiro) | | A charge or refund status, dispute stage or reason | [Statuses and results](/en/tipos-e-identificadores/estados) | | Sandbox, Production, or an API key | [Authentication](/en/integracoes/autenticacao) and [API keys](/en/integracoes/chaves-api) | | A request error such as `INVALID_FIELDS` | [HTTP response codes](/en/api/codigos-http-das-respostas) | | An event name or team member permission | [Webhooks](/en/integracoes/webhooks) and [Users and permissions](/en/usuarios-e-permissoes) | For `pix_status`, see [Receive Pix details during creation](/en/api/charges/overview#receber-o-pix-na-criação). Reasons that prevent a refund are described in [Check the refundable amount](/en/api/refunds/overview#consultar-o-valor-devolvível). [Retrieving links](/en/api/payment-links/overview#consultar-e-compartilhar) explains their availability for payment. For `tax_id` and `tax_id_type`, see [CPF and CNPJ validation](/en/integracoes/validacao-cpf-cnpj). Response codes help you interpret the resource you retrieved. Each endpoint's parameters explain which values can be sent in a request. For example, recognizing a payment method in a response does not mean you can select it when creating a charge. ## The same value in different fields The meaning depends on the field name and the resource retrieved. In a statement: * `statement_type: 2` indicates a fee. * `reference_type: 2` indicates that the reference is a dispute. These fields can appear in the same entry. One describes the movement; the other identifies the category of the related resource. See [Statement entry types](/en/tipos-e-identificadores/financeiro#tipos-de-lançamento-do-extrato) and [Reference categories](/en/tipos-e-identificadores/financeiro#categorias-de-referência-do-extrato). An identifier is not a status either. `rf_` identifies a refund but does not tell you whether it has been completed. Check the request status to track the result. Similarly, a closed dispute does not prove that money was returned. ## When a code is not in the guide Do not assign meaning based only on a number, prefix, or similarity to another field. Keep the original value and check the resource, field name, and query environment. An unknown value should not automatically be treated as success, failure, confirmed payment, or permission to repeat a request. Check the endpoint reference and the current version of this map. If you still have questions, give support the field name and resource identifier without sending API keys, webhook secrets, or other authentication data. `null` indicates the absence of a value in that field. It does not equal zero or prove that a transaction never existed. Fields such as `refund_id` and `dispute_id` are null when there is no confirmed association to show. # Statuses and results (/en/tipos-e-identificadores/estados) A status reports a resource's progress. A reason explains a recorded condition, and a result describes the conclusion of an analysis. Check which field is being shown: these fields are not interchangeable. ## Charge statuses In the API, a charge's `status` uses the codes below. The history may also contain statuses for methods that are not available for new charges. | Code or value | Meaning | How to interpret | | ------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Created | Charge registered without confirmed payment. Whether it can be paid depends on its due date, enabled methods, and available payment details. | | `1` | Awaiting payment | Charge awaiting payment confirmation. Opening checkout or issuing Pix details or a boleto does not confirm receipt. | | `2` | Authorized | Payment authorized without confirmation of completion. Do not deliver the product or consider the amount received based only on this status. | | `3` | Processing | Payment processing without a final result yet. Track the existing charge before requesting another payment. | | `4` | Paid | Charge payment confirmed. Fees, holds, and refunds are separate information and may affect the amount available for use. | | `5` | Partially refunded | Part of the amount received has been returned. Check the history and refund eligibility to determine the remaining amount that can be requested. | | `6` | Refunded | The amount received has been returned in full. The refund may involve more than one entry; check the links and history to reconcile it. | | `7` | Cancelled | Charge cancelled for new payments. Cancelling a charge is different from returning a payment received. | | `8` | Expired | The payment deadline has passed. This status does not prove bank cancellation: check the charge and boleto before concluding that cancellation occurred. | | `9` | Failed | The charge or its payment ended in failure. Check the available details before requesting another charge; this status does not confirm receipt. | | `10` | Disputed | The payment is associated with a dispute. Check the case for its stage, amounts, and available information. | | `11` | Dispute under review | The dispute is under review. The result and any financial effect still need to be checked in the case and statement. | | `12` | Dispute lost | The dispute outcome was unfavorable to the company. Check the amounts reported in the case and related entries to determine the financial effect. | | `13` | Dispute won | The decision was in the company's favor. Check the balance and entries: this status does not indicate when the held amount became available. | Authorization, issuance of payment details, and processing do not confirm that a charge has been paid. An expired charge does not prove that an issued boleto has been cancelled. See [Charges](/en/api/charges/overview) for the available actions and the conditions for each request. ## Refund statuses A refund's `status` in the API is a string. It does not use charge status numbers. Track the same `rf_` identifier to check the result. | Code or value | Meaning | How to interpret | | ------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `reserved` | Requested | The refund request was registered, but the refund has not been confirmed yet. Track this same refund before making another request. | | `accepted` | Accepted for processing | The request was accepted and awaits the final result. Acceptance does not confirm that the money has returned to the payer. | | `completed` | Completed | The refund was confirmed. Check the refund amount and related entries to reconcile it. | | `failed` | Failed | The refund failure was confirmed. Check the reason, other refunds for the charge, and eligibility before making a new request. | | `unknown` | Awaiting confirmation | The refund result has not been confirmed yet. Continue checking the same request; do not treat this status as failure or a completed refund. | A connection failure does not mean the request failed. Check the request and charge history before trying again. In Sandbox, a confirmed refund belongs to the simulation; it does not move real money. ## Refund failure reasons `failure_reason.code` reports a public cause of a confirmed failure. In other statuses, `failure_reason` is `null`. | Code or value | Meaning | How to interpret | | ----------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `REFUND_NOT_SUBMITTED` | Request not submitted | This refund was not submitted for processing. Check the charge history and eligibility before requesting again. | | `REFUND_REJECTED` | Request rejected | The refund request was rejected. Check the charge refunds before making another attempt. | | `REFUND_PROCESSING_UNAVAILABLE` | Processing unavailable | Processing was unavailable and this refund ended in failure. Check the charge and its eligibility before another request. | | `REFUND_PROCESSING_FAILED` | Processing failure confirmed | The refund failure was confirmed without a more detailed reason. Check the charge refunds before trying again. | | `REFUND_FAILURE_REASON_UNAVAILABLE` | Reason not provided | No confirmed reason is available for this refund failure. Check the history and contact support if you need to clarify the result. | Use the code to handle the response. The message explains the problem and can be improved without changing the code's meaning. The absence of a detailed cause does not justify assuming bank rejection or automatically requesting another refund. ## Dispute types You need the `kind` field to interpret reasons and results. | Code or value | Meaning | How to interpret | | ------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chargeback` | Payment dispute | Identifies dispute history classified as chargeback. Interpret the reason using that category's catalog; the name does not confirm that cards are enabled for new charges. | | `med` | Pix dispute (MED) | Identifies a case under the Pix Mecanismo Especial de Devolução. Check the stage, reason, and analysis results; the existence of the case does not confirm a refund or fraud. | The name `chargeback` does not prove that cards are available for new charges in Raims. It identifies the category of the record retrieved. ## Dispute stages The public `stage` field reports dispute progress: | Code or value | Meaning | How to interpret | | -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `open` | Open | The dispute was registered and does not yet have a confirmed analysis. Check the information and deadlines shown in the case. | | `in_analysis` | Under analysis | The dispute is under analysis. This stage does not yet confirm a result or refund. | | `refund_in_analysis` | Refund under analysis | Analysis of a possible refund is in progress. Check the result and refunded amount when provided; this stage does not prove that money has left the account. | | `closed` | Closed | Tracking of the analysis has ended. Read the results and amounts reported in the case: closure alone does not mean a win, loss, or refund. | | `cancelled` | Cancelled | The dispute was cancelled. This stage does not confirm a refund or balance release; check the amounts and statement. | | `rejected` | Opening rejected | The request to open the dispute was rejected. Check the available details; this result is not a refund to the payer. | | `failed` | Failed | Dispute processing was not completed because of a failure. Check the case and contact support if you need to clarify the result. | `closed` reports that the analysis has ended. On its own, it does not mean a decision in the company's favor or a refund. Check the results and amounts available in the [dispute details](/en/api/disputes/retrieve). ## Reasons reported in MED When `kind` is `med`, interpret `reason_code` using this table. The reason is the allegation reported in the dispute, not a finding of fraud. | Code or value | Meaning | How to interpret | | ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `1` | Scam reported | The complainant reported that the payment is linked to a scam. This category records the dispute reason and does not confirm that fraud occurred. | | `2` | Account takeover reported | The complainant reported that another person used the account without authorization. The conclusion depends on case analysis. | | `3` | Coercion reported | The complainant stated that they made the payment under coercion. Check the analysis results for the case conclusion. | | `4` | Fraudulent access reported | The dispute reports suspected fraudulent access related to the payment. The reported reason does not amount to proven fraud. | | `5` | Other reason | The reason was classified outside the other categories. Check the complaint details when available. | | `6` | Unrecognized reason | The reason received does not match a recognized category in this catalog. Do not infer the cause from the code; check the available case details. | ## Reasons for other disputes When `kind` is `chargeback`, `reason_code` uses this other table. The same number can have a different meaning in a MED case. | Code or value | Meaning | How to interpret | | ------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `1` | Fraud alleged | The dispute was registered with an allegation of fraud. The reason does not replace the analysis result. | | `2` | Unrecognized purchase | The complainant stated that they do not recognize the purchase. Check the case details and result. | | `3` | Unrecognized service | The complainant stated that they do not recognize the service charged. This category records the allegation and does not determine the dispute result. | | `4` | Product or service mismatch | The complainant reported a mismatch in the product or service. Check the case details to understand the complaint. | | `5` | Improper charge | The complainant alleged an improper charge. The conclusion and any financial effect depend on the result reported in the case. | | `6` | Other reason | The dispute uses a reason outside the other categories. Check the available details; do not interpret this value as the equivalent reason in a MED case. | A `null` reason is not available to show. Do not fill this field with a cause inferred from the amount, date, or payment type. ## MED analysis results `infraction_result` reports the result of the infraction analysis: | Code or value | Meaning | How to interpret | | ------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agreed` | Infraction recognized | The analysis recognized the reported infraction. This result does not confirm a refund; check the refund analysis result and the amount actually returned. | | `disagreed` | Infraction not recognized | The analysis did not recognize the reported infraction. Check the other available results and amounts to understand the case outcome. | `refund_result` reports the result of the refund request analysis: | Code or value | Meaning | How to interpret | | -------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `partially_accepted` | Refund partially accepted | The analysis accepted returning part of the amount requested. Check the amount actually returned; acceptance alone does not prove a money movement. | | `totally_accepted` | Refund fully accepted | The analysis accepted the full refund requested. Check the refunded amount and statement to confirm the financial effect. | | `rejected` | Refund rejected | The analysis rejected the refund requested. Check the case and related entries to reconcile the amounts, including any holds or releases. | Recognizing an infraction and accepting a request do not, on their own, confirm that money has been returned. `refunded_amount_cents` reports the case's total confirmed refunds when that information is available. A `null` result remains different from a rejection or a confirmed zero amount. ## Dispute loss reasons `loss_reason_code`, when provided, describes the recorded reason for the unfavorable decision. A note may add context to this code. | Code or value | Meaning | How to interpret | | ------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `1` | Response deadline expired | The recorded reason for the loss was expiry of the response deadline. Check the case dates and result. | | `2` | Insufficient evidence | The evidence submitted was considered insufficient for the dispute. Check the available case details. | | `3` | Invalid documentation | The documentation submitted was not accepted in the analysis. Check the case details to understand the reported result. | | `4` | Final decision | The loss was recorded based on the final analysis decision. Check the case amounts and statement to identify the financial effect. | | `5` | Other loss reason | The loss has a reason outside the other categories. Check the reason note when available; the absence of a note does not justify inferring a cause. | These reasons do not replace checking the case's stage and result. See [Disputes](/en/api/disputes/overview) to track the available data while distinguishing analysis, decisions, and money movements. # Statement types and financial codes (/en/tipos-e-identificadores/financeiro) The fields on this page describe different facts. Always check the resource and field name before interpreting a code. A fee and a payment method do not share a universal numbering system. In a statement, `statement_type: 2` means a fee, while `reference_type: 2` means a reference to a dispute. The first classifies the movement; the second classifies the related resource. ## Statement entry types `statement_type` describes the nature of an entry in the [Statement](/en/api/statements/overview). `amount_cents` keeps the sign of the amount in Brazilian real cents. | Code or value | Meaning | How to interpret | | ------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `1` | Funds received | Confirmed incoming amount in the statement, shown with a positive sign. Check the entry reference to identify its source; a receipt does not always need to refer to a charge. | | `2` | Fee | Fee charged, shown as a negative amount. When a charge is related, the incoming amount and fee appear as separate entries. | | `3` | Service fee | Amount charged for a service, with a negative sign. The available reference helps identify the source of the charge; the type alone does not indicate which service was used. | | `4` | Withdrawal | Outgoing withdrawal amount, with a negative sign. Use the withdrawal reference to check its identifier and result. | | `5` | Refund | Confirmed outgoing refunded amount, with a negative sign. This may be the entry that completes a charge refund after earlier refunds; check the history for the total returned. | | `6` | Partial refund | Confirmed outgoing portion of an amount received, with a negative sign. The remaining refundable amount also depends on other refunds and disputes linked to the charge. | | `7` | Credit adjustment | Adjustment that adds to the balance, shown with a positive sign. Check the reference and available details to understand the reason; this type does not identify a customer payment. | | `8` | Debit adjustment | Adjustment that subtracts from the balance, shown with a negative sign. Check the reference and available details to understand the reason; this type does not necessarily identify a withdrawal or refund. | | `9` | Balance hold | Amount that became unavailable for use, shown with a negative sign. A hold does not confirm an expense or refund; check the held balance and related case, when provided. | | `10` | Balance release | Previously held amount that became available again, shown with a positive sign. A release is not new revenue and does not represent another customer payment. | A payment can generate more than one entry, such as a receipt and a fee. A hold reduces the availability of money without being an expense in itself. Releasing it is not new revenue. The current balance has a [separate query](/en/api/balances/overview), with total, held, and available amounts. Adding up one page of the statement does not replace that query or provide the balance after each entry. ## Statement reference categories `reference_type` explains the category of `reference_id`. It does not indicate whether the entry is a credit, debit, fee, or hold. | Code or value | Meaning | How to interpret | | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `1` | Charge | The reference identifier points to a charge. Several entries, such as incoming funds, a fee, and a refund, can relate to the same charge; also check the entry type and any refund or dispute links. | | `2` | Dispute | The reference identifier points to a dispute. Check the case to interpret the association; the reference alone does not prove a loss, win, or refund. | | `3` | Withdrawal | The reference identifier points to a withdrawal. This classification indicates the entry source and should be read together with its amount and type. | | `4` | Adjustment | The reference identifier points to a financial adjustment. The entry type and amount sign indicate the direction of the adjustment. | | `5` | Manual entry | The reference identifies a manual entry and may have no prefix. Do not treat it as a charge identifier or assume that a public endpoint exists to retrieve it. | `reference_id` and `reference_type` can be `null`. The `refund_id` and `dispute_id` fields provide additional links when an association is confirmed. A fee is not automatically assigned another entry's refund just because both belong to the same charge. ## Payment methods These codes identify payment methods in the API's `payment_method` field. A code appearing in a response does not mean that method is enabled for creating a charge or paying at checkout. | Code or value | Meaning | How to interpret | | ------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Undefined | The charge does not yet have a defined payment method. Allowed options come from the charge and checkout configuration; this value does not indicate confirmed payment. | | `1` | Pix | Identifies payment by Pix. Issuing a Pix code enables payment of the charge, but confirmation depends on receiving the payment. | | `2` | Boleto | Identifies payment by boleto. Registration, clearing, and settlement are different stages; check the boleto status and charge payment. | | `3` | Credit card | Identifies a credit card in data using this code. The presence of this value in the catalog does not enable the method at checkout; use only methods accepted by the endpoint when creating a charge. | | `4` | Debit | Identifies debit payment in data using this code. The presence of this value in the catalog does not enable the method at checkout; use only methods accepted by the endpoint when creating a charge. | For new charges, see [Payment methods](/en/meios-de-pagamento). The guide distinguishes `payment_method`, `payment_method_types`, and `checkout_payment_method`. The list accepted during creation follows the endpoint's options, and a link configuration can restrict the charge's options. Issuing Pix details or a boleto does not confirm payment. ## Withdrawal failure reasons When a withdrawal's `status` is `FAILED`, `failure_reason.code` reports the recorded reason. In other statuses, `failure_reason` is `null`. These codes come from [retrieving a withdrawal](/en/api/withdrawals/retrieve) and are different from the request's HTTP status. | Code or value | Meaning | How to interpret | | --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------- | | `INVALID_BANK_ACCOUNT` | Invalid account | The destination account details were not accepted. | | `BANK_ACCOUNT_UNAVAILABLE` | Account unavailable | The destination account was unavailable. | | `BANK_UNSUPPORTED` | Institution not accepted | The destination institution was not accepted for the withdrawal. | | `INVALID_ACCOUNT_TYPE` | Invalid account type | The destination account type was not accepted. | | `INSUFFICIENT_BALANCE` | Insufficient balance | There was not enough balance to complete the withdrawal. | | `BLOCKED_BALANCE` | Balance held | Held amounts prevented the withdrawal. | | `BELOW_MINIMUM_WITHDRAWAL` | Below the minimum | The requested amount was below the allowed minimum. | | `ABOVE_MAXIMUM_WITHDRAWAL` | Above the maximum | The requested amount exceeded the allowed maximum. | | `WITHDRAWAL_LIMIT_REACHED` | Limit reached | A withdrawal limit prevented the request. | | `DUPLICATED_REQUEST` | Duplicate request | Check the history before requesting another transfer. | | `RISK_POLICY_REJECTED` | Withdrawal not authorized | Check the account notices or contact support. | | `WITHDRAWAL_TEMPORARILY_UNAVAILABLE` | Withdrawal unavailable | The request could not be completed at that time. | | `BANK_PROCESSING_FAILURE` | Transfer failure | Check the history and contact support if needed. | | `BANK_TIMEOUT` | Time limit exceeded | No final result was available within the expected time. Check the history before repeating the request. | | `INTERNAL_ERROR` | Processing failure | Check the history and contact support if needed. | | `WITHDRAWAL_FAILURE_REASON_UNAVAILABLE` | Reason unavailable | No confirmed reason is available to show. Contact support if needed. | Use the code to handle the response in your system. The English message adds diagnostic information and can change without changing the code. Check the withdrawal and history before making another request; retrieval does not repeat the transfer or confirm that another attempt will be accepted. # Identifiers and prefixes (/en/tipos-e-identificadores/identificadores) A prefix is the initial part of an identifier, before the rest of the code. It helps you recognize the resource. You need the full identifier to retrieve that record; the prefix alone does not identify a transaction. ## Financial identifiers | Code or value | Meaning | How to interpret | | ------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ch_` | Charge | Identifies a charge in API responses, links, and the Dashboard. Use the full value when retrieving the charge; it remains distinct from customer, payment link, and refund IDs. | | `rf_` | Pix refund | Identifies a request to return a Pix payment. It can appear in refund history and the statement refund\_id field; check the refund status to know whether the money has been returned. | | `pl_` | Payment link | Identifies the payment link record. The checkout URL may use another token without a prefix; copy the returned URL instead of constructing it from this ID. | | `cus_` | Customer | Identifies the customer registered by the company and linked to a charge. This is the value used in customer\_id; it is not the CPF, CNPJ, or customer reference in your system. | | `st_` | Statement entry | Identifies an individual statement entry. A single charge can generate several entries, each with its own ID, such as incoming funds, a fee, and a refund. | | `dp_` | Dispute | Identifies a payment dispute and can appear in the dispute\_id field or as a statement reference. Keep the ID you received; MED cases use a different format. | | `wd_` | Withdrawal | Identifies a withdrawal in the Dashboard and API responses. It can appear in the statement reference\_id field; use the full value to retrieve the withdrawal and track its result. | | `wdst_` | Withdrawal destination | Identifies a verified Pix destination owned by the company, returned by the Production destination query. Use the full value to retrieve its masked details; it does not identify a withdrawal or change the default destination. | | `adj_` | Financial adjustment | Identifies the adjustment related to a statement entry. Check the entry type and amount to distinguish a credit from a debit; the ID does not indicate the adjustment direction or define a separate public endpoint. | | `med_` | MED case | Identifies a case under the Pix Mecanismo Especial de Devolução, with a decimal numeric suffix. It can appear as a dispute ID and in the statement dispute\_id field; closing the case alone does not prove that money has been returned. | A MED case ID uses a decimal number after the prefix. Keep the format you received when [retrieving a dispute](/en/api/disputes/retrieve). The other IDs in this group use a case-sensitive combination of letters and numbers. Copy the full value as received, without removing zeros, changing letters, or converting the code to a number. ## Account and Dashboard identifiers These identifiers appear in account, key, and webhook settings, dispute files, and checkout image uploads. Copy the full value when you need to identify the resource. They do not replace authentication credentials. | Code or value | Meaning | How to interpret | | ------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mk_` | API key record | Identifies the key managed in the Dashboard, including configuration and rotation actions. It is not the secret used in the Authorization header and does not authenticate a request. | | `cau_` | Checkout image upload | Identifies an authorized logo or icon upload. After uploading the file, use the ID in the corresponding checkout customization field. The ID is not the image URL and does not prove that the image has been applied. | | `co_` | Company | Identifies the business account in Dashboard information and activity records. Knowing this ID does not grant access to company data; the session or API key still defines the permitted access. | | `whk_` | Webhook record | Identifies the destination configured in the Dashboard Webhooks area. It is different from the secret used to verify notification origin. | | `emp_` | Team member | Identifies a person with account access through the team. It can appear in their record, invitations, and activities; their permissions are still defined by the access granted to them. | | `df_` | Dispute file | Identifies a file linked to a dispute, such as an evidence document. Access to its contents depends on account permissions; the ID is not the download address. | ## Credentials and secrets These prefixes identify authentication data rather than a resource record: | Code or value | Meaning | How to interpret | | ------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sk_test_` | Sandbox API key | Prefix of the secret used to authenticate requests with test data. Send the full key in the Authorization header with the Bearer scheme and keep the secret protected in your application backend. | | `sk_live_` | Production API key | Prefix of the secret used to authenticate requests in the environment for real transactions. The prefix does not prove that the key is valid: access, environment, and restrictions are checked on every request. | | Code or value | Meaning | How to interpret | | ------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `whsec_` | Webhook secret | Prefix of the signing secret shown when managing a webhook. Protect the full value and follow the webhook validation guidance; it is not the record ID or an API Bearer key. | A key's `mk_` ID does not authenticate requests. A webhook's `whk_` ID does not let you verify a message signature. Use the appropriate credential or secret for these purposes, as described in [Authentication](/en/integracoes/autenticacao) and [Webhooks](/en/integracoes/webhooks). Do not publish credentials, include them in URLs, or send them to support. Documentation examples abbreviate secrets; they are not valid credentials. ## References without a prefix In a statement, a manual reference may appear without a prefix. In that case, `reference_type` identifies its category. The absence of a prefix does not justify treating the value as a charge, refund, or dispute ID. The token in a payment URL is also different from the link's `pl_` ID. Keep the URL provided by Raims; do not construct a checkout URL by changing or adding prefixes. ## How to use an identifier A prefix does not indicate the company, environment, amount, or resource status. Sandbox and Production IDs use the same resource prefixes. Access depends on the credential and its association with the correct company and environment. A `st_` identifies an entry. Its `reference_id`, `refund_id`, and `dispute_id` fields, when populated, identify other related resources. Use the right field for each query; a charge and its entries do not have the same identifier. # Users and permissions (/en/usuarios-e-permissoes) The **Learn more** link appears below each item in the matrix at **Account / Users and permissions**. Each link opens the corresponding permission on this page. ## Invite members 1. Go to **Account / Users and permissions / Add team member**. 2. Enter the email addresses and press Enter to confirm each one. The form accepts up to ten email addresses per submission. 3. Choose a suggested profile and review the selected permissions. Adjust the matrix to match the tasks these people need to perform. 4. Select **Send invitation** and confirm your identity when prompted. 5. Check the result for each address. A partial submission may leave some invitations requiring a correction. This action requires **Team** and **Add team members**. The member can access the account only after accepting the invitation sent by email. Do not use the main account's email address as another member. ## View permissions 1. Go to **Account / Users and permissions** and find the person using the available filters. 2. Open **View permissions** in the row's actions menu. 3. Review the current permissions in the matrix. Viewing permissions requires **Team**. You can view your own access in this area, but you cannot change it. ## Update permissions 1. Go to **Account / Users and permissions** and open **View permissions** in the actions for the member. 2. Adjust the matrix and select **Save changes**. 3. Confirm your identity when prompted and wait for **Permissions updated**. Saving requires **Update permissions**. The limits for granting permissions or managing another person are in **Rules for managing access** below. Review the current permissions, including after another administrator has made a change. ## Resend an invitation 1. Go to **Account / Users and permissions** and find the member who still needs to complete their access. 2. Use **Resend invitation** in the actions menu when the option is available. 3. Wait for the required interval and complete the requested identity confirmation. This action requires **Add team members** and does not restore removed access. The recipient must use the invitation to complete registration. ## Remove a member 1. Go to **Account / Users and permissions** and open the actions for the correct person. 2. Select **Remove member**, check who will lose access, and confirm. 3. Complete the requested identity confirmation and check the result in the list. This action requires **Remove team members**. A member cannot remove their own access or manage someone whose permissions exceed their own. To end connected sessions only, go to **Account / Connected Devices**. ## How permissions work View permissions grant access to an area or a set of information. Action permissions allow specific tasks, such as creating, editing, removing, or managing other users. Access to a module does not automatically grant all of its actions. The lists below use the same permission names shown in the Dashboard. **Grant only the access needed** Start with a suggested profile and remove anything the person does not need for their daily work. Changing the selection makes the profile **Custom**. ## Rules for managing access * The **Owner** has full access to the account and is not a suggested member profile. **Super administrator** is a member profile and remains subject to the matrix rules. * A member cannot change their own permissions or remove their own access through this area. * A member can grant only permissions they hold themselves. * A member cannot edit or remove someone with permissions beyond their own. The Owner can manage the entire catalog. * Adding members, updating permissions, resending invitations, or removing access may require another identity confirmation. * Profile, security, notifications, personal activity, and personal sessions are personal features. The audit and session permissions listed below extend viewing or management to the entire company. **Creating charges also depends on customers** To select an existing customer, enable **Customers**. To add a customer while creating a charge, also enable **Create customers**. **Withdrawals require access to Pix keys** To request or configure withdrawals and to edit Pix keys for withdrawals, also grant **View Pix keys for withdrawals**. When you select one of these actions, the Dashboard selects the view permission automatically. ## Business operations Eight permissions control charges and customers. | Item | Description | | --- | --- | | Charges | Views charges, orders, and payment links. Also grants access to details and related queries. | | Create charges | Creates new charges and payment links for company customers. | | Revoke charges | Cancels or revokes charges that still allow this action. | | Refund Pix payments | Requests full or partial refunds of paid Pix charges. Each request requires confirmation through the security method configured for the user. | | Customers | Accesses the customer module and views existing records. | | Create customers | Creates new customers in the Dashboard, including while creating a charge. | | Edit customers | Updates registered customer details. | | Remove customers | Removes customers who should no longer remain active. | ## Finance Ten permissions control disputes, balance, statement, withdrawals, Pix keys for withdrawals, and plans. | Item | Description | | --- | --- | | Disputes | Views disputes, details, and files already attached. | | Balance | Views the company balance and wallet. | | Statement | Accesses the financial history and opens entry details. Exporting this history and accessing its files also requires Exports. | | Withdrawals | Accesses the withdrawals module, history, and details of each request. | | Configure withdrawals | Changes withdrawal rules and settings, including automatic withdrawals. Requires access to view Pix keys for withdrawals. | | Request withdrawals | Requests new company withdrawals. Requires access to view Pix keys for withdrawals. | | View Pix keys for withdrawals | Views the Pix keys registered to receive withdrawals, including the selected destination. | | Edit Pix keys for withdrawals | Adds, selects, and removes Pix keys for withdrawals. Requires view permission and identity confirmation for each change. | | Plans | Views the plans and pricing area and the current account conditions. | | Change plan | Changes the commercial plan for the account. | ## Integration and API The permissions below separate viewing and administration of applications, API keys, and webhooks. Members retain access to their own application connections. Session and device permissions do not extend this access. | Item | Description | | --- | --- | | View company applications | Views application connections authorized by the owner and team. Does not allow editing permissions or revoking other people's connections. | | Revoke team connections | Views company applications and allows revoking other employees' connections. Does not allow revoking the owner's connections or editing other people's permissions. | | API keys | Views the list, details, and IP restrictions of private keys. | | View request logs | Views the API request history, its details, and the available request and response bodies. Also requires API keys. Grant this only to people who need to view this information. | | Create API keys | Generates new private keys for integration. | | Delete API keys | Revokes and deletes existing private keys. | | Rotate API keys | Rotates the secret and generates a new credential for the key. | | Manage API IPs | Adds, changes, or removes IPv4 and CIDR restrictions on private keys. | | Edit API keys | Changes key metadata, such as the display name. | | Webhooks | Views the list, details, and selected events of webhooks. | | View event logs | Views the webhook attempt history, its details, and the available payload. Also requires Webhooks. Grant this only to people who need to view this information. | | Resend webhook events | Requests another delivery of an eligible event from the history. Requires Webhooks and View event logs, as well as identity confirmation. | | Create webhooks | Registers new webhook destinations and selects their events. | | Delete webhooks | Removes existing webhook destinations. | | Rotate webhooks | Rotates the secret used by the webhook. | | Edit webhooks | Changes the webhook name and allows disabling or re-enabling it. Enabling or disabling a webhook requires identity confirmation. | | Edit webhook URLs and events | Changes the webhook URL and selected events, preserving its name, identifier, secret, and status. Also requires Webhooks and identity confirmation. | ## Account and security The permissions below control account settings, checkout, bank details, compliance, documents, exports, and activity viewing. To view other members' activity, use **View full audit log**. **Exports** grants access to the export center at **Reports / Exports**. To request, view, and download a file, members also need the permission for its source resource, such as **Statement**. The export center shows only the user's own requests for the selected company and environment. Without access to an exportable resource, the export center opens with no requests. | Item | Description | | --- | --- | | View account settings | Views account settings, status, operational limits, and checkout. | | Edit checkout appearance | Changes the payment checkout visual identity, logo, and icon. | | Edit payment methods | Enables or disables the default payment methods used in payment links. | | Bank details | Views company bank details. | | Edit bank details | Changes company bank details. | | Compliance | Views company registration details and the name of the legal representative. | | Terms and documents | Views account terms and documents and allows downloading the files available in the reader. Does not grant editing or access to company registration details. | | Exports | Accesses the export center and allows requesting, tracking, and downloading your own files. Each file also requires the permission for its source resource. | | View full audit log | Extends the activity log to include actions by all company members. Without this permission, members continue to see only their own actions. | | Export audit log | Exports the company activity log. Also requires Exports and View full audit log. | ## Team and devices Six permissions control the team and extend access to sessions across the company. | Item | Description | | --- | --- | | Team | Accesses the members area, roles, and current permissions. | | Add team members | Sends invitations to add new members to the account. | | Remove team members | Removes members and revokes their account access. | | Update permissions | Edits other members' permissions within the permitted scope. | | View company sessions | Extends the connected devices screen to include the Owner and other members. Without this permission, each member sees only their own sessions. | | Manage company sessions | Ends connected sessions belonging to other company users. Managing your own sessions remains available as a personal feature. | ## Suggested profiles Profiles preselect permissions in the matrix. You can adjust the selection before inviting or saving a member. Application permissions are not granted automatically to existing members. An authorized administrator must select **View company applications** or **Revoke team connections** when that access is needed. An authorized administrator must grant **Exports** to existing members. **Statement** alone does not include this permission. The **Super administrator**, **Administrator**, **Finance**, and **View only** profiles include it when applied. Files still require the permission for their source resource. Existing permission selections do not automatically include access to API logs, webhook logs, or resending. An authorized administrator must enable **View request logs** or **View event logs** in the member's matrix, together with the corresponding view permission, or reapply a profile that includes this access. The Owner retains access to logs. **Resend webhook events** requires **Webhooks** and **View event logs**. When resending is selected, the matrix includes these dependencies if the administrator can grant them. Removing either dependency also removes the resend selection. Log access alone allows viewing, but not requesting another delivery. The same applies to **Edit webhook URLs and events**: existing members need an authorized administrator to grant this permission. The **Super administrator**, **Administrator**, and **Developer** profiles include it when applied. Saving a configuration does not extend other members' permissions. Selecting **View event logs** or **Edit webhook URLs and events** also selects **Webhooks** when you can grant that access. If you cannot, ask an authorized administrator to grant both permissions. Removing **Webhooks** also removes these two dependent selections. ### Super administrator Selects all permissions in the matrix. Use this profile only for someone who manages the entire account. ### Administrator - 40 permissions Broad access to account operations, including viewing Pix keys for withdrawals and API and webhook logs. Does not include changing these keys, bank details, plans, payment methods, Pix refunds, the full audit log, or company-wide sessions. ### Developer - 15 permissions Includes all API key and webhook permissions. ### Finance - 10 permissions Includes viewing disputes, balance, statement, and withdrawals, configuring and requesting withdrawals, viewing Pix keys for withdrawals, viewing plans, and changing plans, as well as access to the export center. Does not allow changing the keys. ### Support - 6 permissions Includes viewing and creating charges, viewing, creating, and editing customers, and viewing disputes. ### View only - 16 permissions Includes module view permissions and Exports, with access to files for permitted resources. Does not grant creating records, editing, removal, API and webhook logs, the full audit log, or company-wide sessions.