Objetivo do Manual

Este manual tem como objetivo orientar o processo de integração entre agentes virtuais/chatbots e o CRM CobCloud utilizando a API Partner.

Ao final da leitura, será possível:

• Gerar credenciais de acesso da API

• Consultar devedores disponíveis para negociação

• Listar propostas e condições de pagamento

• Registrar acordos automaticamente

• Alterar status e cadastrar ocorrências

• Consultar boletos e parcelas geradas

Introdução à API

A API de Agentes Virtuais foi desenvolvida para permitir integrações entre plataformas externas e o CRM CobCloud, possibilitando que chatbots, assistentes virtuais e automações realizem negociações diretamente no sistema.

O fluxo da integração segue a seguinte sequência:

1. Gerar credenciais

2. Consultar devedor/processo

3. Consultar propostas disponíveis

4. Registrar acordo

5. Cadastrar ocorrência e alterar status

6. Consultar parcelas/boletos

1. Gerando Credenciais

O primeiro passo para utilização da API é gerar as credenciais de autenticação no CRM CobCloud.

Caminho no sistema

APPS > Configurações > Gerais > Tokens API (Partners).

Nesta tela:

• O campo token_company já estará gerado automaticamente.

• Será necessário gerar o token_partner clicando no botão ‘CADASTRAR’.

  

Após o cadastro dos token, a integração já poderá iniciar as consultas na API.

Tokens utilizados

Importante: mantenha os tokens armazenados em ambiente seguro e nunca compartilhe as credenciais publicamente.

2. Consulta de Devedor / Processo

A primeira consulta da integração deve verificar:

• Se o devedor existe na base da assessoria.

• Se o processo está disponível para negociação.

• Se o processo atende aos filtros parametrizados no CRM.

Endpoint

GET https://api-v3.cob.cloud/ptr/propostas/processos/listar

Caso o devedor esteja disponível para negociação, ele será retornado na resposta da API.

Informação importante

Durante esta etapa, é necessário armazenar o número do ‘PROCESSO’ pois ele será utilizado nas próximas consultas.

Fluxo esperado

1. A integração realiza a consulta.

2. A API valida os filtros configurados no CRM.

3. O processo elegível é retornado.

4. O número do processo é armazenado.

3. Consulta de Propostas / Condições de Pagamento

Após localizar o processo do devedor, o próximo passo é consultar as condições de negociação disponíveis.

Esta consulta retorna:

• Opções de parcelamento.

• Valores negociados.

• Quantidade de parcelas.

• Entradas.

• Condições disponíveis para acordo.

Endpoint

GET https://api-v3.cob.cloud/ptr/propostas/listar

Parâmetro obrigatório

Exemplo

PROCESSO : 1/160822

Estrutura das propostas

Cada condição retornada possui um identificador chamado ‘Item’.

Este campo representa a proposta escolhida pelo devedor e deverá ser armazenado, pois será utilizado no cadastro do acordo.

Fluxo esperado

1. Enviar o número do processo.

2. Receber lista de propostas disponíveis.

3. Exibir condições para o devedor.

4. Armazenar o item selecionado.

4. Cadastro de Acordo / Proposta

Após o devedor selecionar a condição desejada, a integração poderá registrar o acordo diretamente no CRM.

Endpoint

POST https://api-v3.cob.cloud/ptr/propostas/cadastrar

Estrutura do Body

O body da requisição deve conter:

Exemplo de Body

{

"processo": "1/160828",

"item": "1",

"operador": "Agente Virtual",

"gerar_faturas": true

}

Retorno esperado

Se o acordo for gravado corretamente, a API retornará:

Status: ‘200’

Mensagem: ‘OK’

Observações importantes

• Recomendamos utilizar sempre um operador padrão para integrações.

• O parâmetro gerar_faturas deve ser enviado com o valor booleano TRUE, para emissão automática dos boletos.

• Após o retorno de sucesso, o acordo já estará registrado no CRM.

5. Cadastro de Ocorrência e Alteração de Status

Após a gravação do acordo, recomendamos fortemente realizar:

• Alteração do status do processo.

• Cadastro de uma ocorrência/histórico.

Essas ações são essenciais para impedir que o mesmo processo continue disponível para novas negociações via API.

Endpoint

POST https://api-v3.cob.cloud/ptr/ocorrencias/cadastrar

Informações obrigatórias

O body da requisição deverá conter:

Fluxo recomendado

1. Registrar acordo.

2. Alterar status do processo.

3. Registrar ocorrência automática.

4. Bloquear novas negociações indevidas.

Resultado esperado

Após o cadastro da ocorrência, o processo já estará atualizado dentro do CRM.

6. Consulta de Boletos / Parcelas

Após concluir o registro do acordo, a integração poderá consultar as parcelas e boletos gerados para envio ao devedor.

Endpoint

GET https://api-v3.cob.cloud/ptr/propostas/parcelas/listar

Parâmetro obrigatório

Fluxo esperado

1. Informar o número do processo

2. Consultar parcelas geradas

3. Receber links de pagamento

4. Enviar boletos/faturas ao devedor

Observações importantes

• Em ambiente de homologação/testes, o campo de URL da fatura pode não ser retornado.

• Em produção, o retorno conterá os links válidos para pagamento.

• Os links podem ser utilizados em chatbots, WhatsApp, SMS ou e-mail.

Fluxo Completo da Integração

Etapas da operação

Boas Práticas de Integração

Segurança

• Nunca exponha tokens no frontend.

• Utilize HTTPS em todas as requisições.

• Restrinja acesso aos ambientes de integração.

• Armazene logs de requisições e respostas.

Operação

• Sempre valide o retorno HTTP da API.

• Trate exceções e timeouts.

• Armazene o número do processo durante todo o fluxo.

• Registre logs de acordos realizados.

Controle operacional

• Sempre altere o status após acordos.

• Cadastre ocorrências automáticas.

• Evite permitir múltiplos acordos simultâneos.

• Monitore acordos gravados pela integração.

Conclusão

A API de Agentes Virtuais do CobCloud permite automatizar negociações e integrar plataformas externas de cobrança de forma prática e segura.

Com a utilização correta dos endpoints e do fluxo operacional recomendado, é possível:

• Automatizar negociações.

• Registrar acordos em tempo real.

• Gerar boletos automaticamente.

• Integrar chatbots e assistentes virtuais.

• Melhorar a eficiência operacional da cobrança.

Recomendamos validar toda a integração inicialmente em ambiente controlado antes da utilização em produção.

✅ Checklist Rápido da Integração

☐ Tokens gerados

☐ Consulta de processos funcionando

☐ Consulta de propostas funcionando

☐ Item da proposta armazenado

☐ Cadastro de acordo validado

☐ Alteração de status implementada

☐ Cadastro de ocorrência implementado

☐ Consulta de parcelas funcionando

☐ Links de pagamento sendo enviados

☐ Logs e validações implementados

✅ Concluído: integração pronta para operar negociações automatizadas no CRM CobCloud.