Autenticação | Documentação da Raims

A API da Raims usa uma chave de API para identificar a empresa responsável pela requisição. O backend da sua aplicação deve enviar essa chave no header Authorization, com o esquema Bearer, em todas as requisições autenticadas.

Antes de começar

Crie uma chave de API para o ambiente que sua aplicação vai utilizar. Consulte Chaves de API para obter e gerenciar a credencial.

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.

Header de autenticação

Configure o cliente HTTP do seu backend com os seguintes headers ao enviar um corpo 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:

https://api.raims.com

O ambiente e a empresa são definidos pela chave enviada no header Authorization. Não envie um campo adicional na URL ou no corpo para escolher o ambiente.

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.

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 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.

Uma resposta 403 Forbidden pode indicar 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 para interpretar o status, o código e a mensagem retornados pela API.