Clientes

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 da chave usada 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, 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 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. 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:

{
  "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, com GET /v1/customers, consulta os cadastros da empresa e do ambiente da chave. 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 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.

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, 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 da chave. Se não estiver disponível para essa chave, confira o identificador e a credencial usados.

Atualizar cliente existente

Use Atualizar cliente existente 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.

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

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