Autenticar
Obtém o token JWT necessário para chamar os demais endpoints. O token expira em 30 minutos; renove-o chamando este endpoint novamente.
Body
| Campo | Tipo | Descrição |
| ClientIdobrigatório | string | Identificador do cliente. Fornecido pela equipe 3C Sistemas. |
| SecretIdobrigatório | string | Senha de acesso. Fornecida pela equipe 3C Sistemas. |
{
"ClientId": "seu_client_id",
"SecretId": "sua_senha"
}
{
"Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEsImlhdCI6MTc4MjQ3OTM1OSwiZXhwIjoxNzgyNDgxMTU5fQ.YXMs9Y7BBEkx70W8f6f_rhcWWRQXurHlg1npLviRzhg",
"ExpiresIn": 1800
}
Uso do Token JWT
Todos os endpoints exigem o token JWT no header Authorization. O token tem validade de 30 minutos — ao receber 401, chame /v2/Auth novamente.
Header obrigatório em todos os endpoints
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
O token expira em 30 minutos. Implemente renovação automática ao receber 401 Unauthorized.
200 OK
Processado com sucesso.
400 Bad Request
Processado, porém com erro ou observação.
401 Unauthorized
Token inválido, ausente ou expirado.
Base URL
Servidor de Homologação
https://app4.sistematotum.com.br/Homologacao/cobranca/Api/v2
Todos os endpoints são acessados a partir desta Base URL. Exemplo: POST /v2/ConsultaDebitos → https://app4.sistematotum.com.br/Homologacao/cobranca/Api/v2/ConsultaDebitos
Ambientes de Teste
Na v2, CPF/CNPJ nunca é enviado na requisição. Use o IdCliente (UUID) retornado pelo endpoint que populou o cliente. Os UUIDs abaixo correspondem aos clientes de homologação.
IdCliente de teste (UUID)
"IdCliente": "18cb0064-bbf4-63e8-6bfa-c8e55d768635"
"IdCliente": "c469c433-7d12-074e-bc6b-b2cd3fc03d04"
Para obter o IdCliente de um novo cliente de teste, inclua-o via IncluirCliente e use o IdContrato retornado em ConsultaDebitos — o campo Cliente.IdCliente virá na resposta.
Credenciais de teste — /v2/Auth
Requisição de autenticação
{
"ClientId": "3csistemas",
"SecretId": "2oomBZpYeh8U3zGP"
}
Use estas credenciais para obter o JWT e testar todos os endpoints em homologação. O token expira em 30 minutos — renove chamando /v2/Auth novamente.
Fluxo de Negociação
Para realizar um acordo completo via API, siga a sequência abaixo:
PASSO 1
Autenticar
/v2/Auth
PASSO 2
Consultar Débitos
/ConsultaDebitos
PASSO 3
Ver Condições
/ConsultaCondicoesAcordo
PASSO 4
Cadastrar Acordo
/CadastroAcordo
PASSO 5
Obter Pagamento
/ConsultaParcela
Primeiro, obtenha o JWT via /v2/Auth. Em seguida, ConsultaDebitos retorna IdContrato (UUID) e IdOferta por débito — use IdOferta em ConsultaCondicoesAcordo para obter o IdNegociacao e datas. Depois, chame CadastroAcordo e ConsultaParcela para obter o QR Code Pix ou boleto.
Geral
Status do servidor
Verifica se o serviço está online e valida o token de autenticação.
Não requer body. Apenas o header Authorization.
200 OK
Servidor online e token válido.
401 Unauthorized
Token inválido ou ausente.
Consulta Acessos
Retorna os 1000 últimos acessos realizados na plataforma.
Não requer body. Apenas o header Authorization.
{
"Acesso": [
{
"Id": 1779139462,
"DataHora": "18/05/2026 18:24:22",
"Carteira": "CONDOMINIO MONTELO LOBATO",
"IdContrato": "89ee95b0-fee1-cfaa-f974-4f34083c3b04",
"IdCliente": "18cb0064-bbf4-63e8-6bfa-c8e55d768635",
"CPFouCNPJ": "12312312387",
"ContratoCon": "ALFA1",
"Nome": "JOSELITO DA SILVA E SOUZA",
"ValorDebito": "3.015,03",
"FezAcordo": 0,
"Simulou": 1
},
{
"Id": 1777060619,
"DataHora": "24/04/2026 16:56:59",
"Carteira": "CONDOMINIO MONTELO LOBATO",
"IdContrato": "fa602407-d193-a9da-596c-7fda0b02ae36",
"IdCliente": "c469c433-7d12-074e-bc6b-b2cd3fc03d04",
"CPFouCNPJ": "29737630000125",
"ContratoCon": "00001",
"Nome": "3C SISTEMAS LTDA",
"ValorDebito": "1.350,00",
"FezAcordo": 0,
"Simulou": 1
}
]
}
Consultas
Consulta Débitos
Ponto de entrada principal da negociação. Retorna todos os débitos e acordos vigentes do CPF ou CNPJ informado, com as condições iniciais de negociação e o IdOferta necessário para avançar no fluxo.
Método obrigatório antes de qualquer atendimento. Sempre execute ConsultaDebitos no início da interação — ele reflete a situação real e atualizada do cliente em tempo real, incluindo débitos em aberto e acordos já negociados.
O retorno é dividido em dois grupos:
Débitos — títulos em aberto ainda não negociados. Use o IdOferta de cada débito para avançar no fluxo de negociação.
Acordos — débitos que já foram negociados, com detalhamento das parcelas e seus respectivos status.
Body
| Campo | Tipo | Descrição |
| IdClientecondicional | string (UUID) | UUID do cliente. Use um dos três campos. |
| IdContratocondicional | string (UUID) | UUID do contrato. Use um dos três campos. |
| CPFouCNPJcondicional | string | CPF ou CNPJ, com ou sem formatação. Use um dos três campos. |
| DataSimulacaoopcional | string | Formato AAAA-MM-DD. Se informado, atualiza os valores dos débitos até a data indicada. |
{
"IdCliente": "18cb0064-bbf4-63e8-6bfa-c8e55d768635"
}
{
"IdContrato": "89ee95b0-fee1-cfaa-f974-4f34083c3b04"
}
{
"CPFouCNPJ": "123.123.123-87"
}
Resposta 200 — cliente com Débitos e Acordos
{
"Cliente": {
"IdCliente": "18cb0064-bbf4-63e8-6bfa-c8e55d768635",
"Nome": "JOSELITO DA SILVA E SOUZA",
"DataNascimento": "1985-04-12"
},
"Telefones": [
{
"DDD": "21",
"Telefone": "972923945",
"Preferencial": true,
"WhatsApp": true,
"Tipo": "CELULAR",
"Observacao": "",
"QtdeLigacoes": 0,
"Data": "2025-01-10 14:32:00"
}
],
"Emails": [
{ "Email": "joselito@teste.com.br", "Data": "2024-03-01 09:00:00" },
{ "Email": "joselitopuro@teste.com", "Data": "2024-03-01 09:00:00" }
],
"Endereco": {
"Logradouro": "RUA MARECHAL RONDON",
"Numero": "120",
"Complemento": "APTO 301",
"Bairro": "CENTRO",
"Cidade": "RIO DE JANEIRO",
"UF": "RJ",
"CEP": "20040020",
"Data": "2024-06-15 10:00:00"
},
"Debitos": [
{
"IdOferta": "89ee95b0-fee1-cfaa-f974-4f34083c3b04",
"IdContrato": "89ee95b0-fee1-cfaa-f974-4f34083c3b04",
"CNPJCredor": "29737630000125",
"RazaoSocialCredor": "CONDOMINIO MONTE LOBATO LTDA",
"IdCarteira": 1,
"NomeCredor": "CONDOMINIO MONTE LOBATO",
"SubCarteira": "LOJA CENTRO",
"Situacao": "EM COBRANÇA",
"Operador": "CARLOS SILVA",
"Agendamento": "2026-06-20 10:00",
"UltimaOcorrencia": "SEM CONTATO",
"Regra": "PADRAO 90 DIAS",
"PercentualQuebra": 0,
"NumeroContrato": "ALFA1",
"TipoContrato": "FINANCIAMENTO",
"DataSimulacao": "2025-06-02",
"QuantidadeDebitos": 3,
"DataAtraso": "2024-01-05",
"ValorDebitoOriginal": 3015.03,
"ValorDebitoAtualizado": 3611.13,
"ValorAVista": 3135.63,
"ValorParcelado": 3373.38,
"PercentualDescontoAVista": 13.17,
"PercentualDescontoParcelado": 6.58,
"ValorDescontoAVista": 475.50,
"ValorDescontoParcelado": 237.75,
"MaximoParcelas": 6,
"ValorMinimoParcela": 45,
"Titulos": [
{
"IdTitulo": "696f3998-7eca-77a9-c266-8cb7a7d3fc84",
"Parcela": "01/03",
"Titulo": "FAT-00012024",
"Documento": "CONDOMANIO",
"DataEmissao": "01/01/2024",
"DataVencimento": "05/01/2024",
"ValorDebito": "1.005,01",
"ValorAtualizado": "1.203,71"
}
],
"ValorHonorarios": 120.00
}
],
"Acordos": [
{
"IdAcordo": "b88dfd82-faf8-ad2d-5ac3-88677109f3cb",
"IdContrato": "ee6f854f-0bb9-5786-f661-3b085485bca0",
"NomeCredor": "3C SISTEMAS LTDA",
"NumeroContrato": "111222333444",
"PrevisaoCancelamento": false,
"Parcelas": [
{
"Parcela": 1,
"Status": "Em Atraso",
"Cor": "red",
"DataVencimento": "2026-05-29",
"ValorVencimento":120.65,
"Boleto": true
}
],
"Titulos": [
{
"IdTitulo": "fa8aa895-941e-8018-b715-f59eccd87f3f",
"Parcela": "001",
"Titulo": "0001",
"Documento": "PAGAMENTO",
"DataEmissao": "02/02/2024",
"DataVencimento": "02/02/2024",
"ValorDebito": "-50,00"
}
],
"TotalDebito": "55,79"
}
]
}
Consulta Condições do Acordo
Retorna as condições de negociação para a oferta informada: datas de entrada disponíveis e opções de parcelamento (IdNegociacao). O FormasPagamento aparece na raiz quando as formas são iguais para todas as opções, ou dentro de cada item de Opcoes quando variam por opção. Nas carteiras internas é possível negociar o valor do acordo (ValorAcordoAVista/ValorAcordoParcelado) dentro da faixa retornada em ValorAcordoMinimo e ValorAcordoMaximo. Use o IdNegociacao e a DataEntrada escolhidos pelo cliente em CadastroAcordo.
Body
| Campo | Tipo | Descrição |
| IdOfertaobrigatório | string (UUID) | Retornado pelo endpoint ConsultaDebitos. |
| ValorEntradaopcional | number ou string | Valor de entrada desejado para o parcelamento. Aceita formato brasileiro ("1.000,00") ou numérico (1000). Se não informado, o sistema calcula o valor mínimo de entrada conforme a regra configurada. Retorna 400 se o valor for inferior ao mínimo permitido. |
| ValorAcordoAVistaopcional | number ou string | Valor negociado para o acordo à vista. Somente carteiras internas (nas carteiras integradas a regra vem do credor e o campo é ignorado). Deve estar dentro da faixa da opção — entre ValorAcordoMinimo (valor com o desconto máximo da regra) e ValorAcordoMaximo (valor atualizado sem desconto); fora da faixa retorna 400 com os limites na mensagem. Quando aceito, o desconto da opção à vista é recalculado pelo valor informado. |
| ValorAcordoParceladoopcional | number ou string | Valor negociado para o acordo parcelado — mesmas regras e faixa do campo acima, aplicado às opções de 2 a N parcelas. |
Contrato com novação de dívida (carteiras internas, sem desconto de novação liberado no credor) retorna as condições acompanhadas do campo Mensagem: "Esse contrato possui novação de dívida, não é permitido descontos !"
{
"IdOferta": "89ee95b0-fee1-cfaa-f974-4f34083c3b04",
"ValorEntrada": "1.000,00",
"ValorAcordoAVista": "3.200,00",
"ValorAcordoParcelado": "3.450,00"
}
{
"IdOferta": "89ee95b0-fee1-cfaa-f974-4f34083c3b04",
"IdContrato": "89ee95b0-fee1-cfaa-f974-4f34083c3b04",
"CNPJCredor": "29.737.630/0001-25",
"RazaoSocialCredor": "CONDOMINIO MONTE LOBATO LTDA",
"NomeCredor": "CONDOMINIO MONTE LOBATO",
"NumeroContrato": "ALFA1",
"DataEntrada": [ "2026-07-04", "2026-07-06", "2026-07-07" ],
"PercentualMinimoEntrada": 20,
"FormasPagamento": [ "PIX", "BOLETO", "CARTÃO DE CRÉDITO" ],
"Opcoes": [
{
"IdNegociacao": "1",
"PercentualDesconto": 13.17,
"ValorTotalDesconto": 475.59,
"ValorPrincipal": 3015.03,
"ValorAcordo": 3135.54,
"ValorAcordoMinimo": 3135.54,
"ValorAcordoMaximo": 3611.13,
"Parcelas": [
{ "Parcela": 1, "Valor": 3135.54 }
],
"FormasPagamento": [ "PIX", "BOLETO", "CARTÃO DE CRÉDITO" ]
},
{
"IdNegociacao": "2",
"PercentualDesconto": 6.58,
"ValorTotalDesconto": 237.61,
"ValorPrincipal": 3015.03,
"ValorAcordo": 3373.52,
"ValorAcordoMinimo": 3373.52,
"ValorAcordoMaximo": 3611.13,
"ValorEntrada": 1686.76,
"ValorParcela": 1686.76,
"ValorUltimaParcela": 1686.76,
"Parcelas": [
{ "Parcela": 1, "Valor": 1686.76 },
{ "Parcela": 2, "Valor": 1686.76 }
],
"FormasPagamento": [ "PIX", "BOLETO" ]
},
{
"IdNegociacao": "6",
"PercentualDesconto": 6.58,
"ValorTotalDesconto": 237.61,
"ValorPrincipal": 3015.03,
"ValorAcordo": 3373.52,
"ValorAcordoMinimo": 3373.52,
"ValorAcordoMaximo": 3611.13,
"ValorEntrada": 674.70,
"ValorParcela": 539.76,
"ValorUltimaParcela": 539.78,
"Parcelas": [
{ "Parcela": 1, "Valor": 674.70 },
{ "Parcela": 2, "Valor": 539.76 },
{ "Parcela": 3, "Valor": 539.76 },
{ "Parcela": 4, "Valor": 539.76 },
{ "Parcela": 5, "Valor": 539.76 },
{ "Parcela": 6, "Valor": 539.78 }
],
"FormasPagamento": [ "PIX", "BOLETO" ]
}
]
}
Consulta Cliente por Telefone
Retorna uma lista de IdCliente (UUID) de clientes com o DDD e telefone informado. O campo Digitos traz os 3 primeiros dígitos do CPF ou CNPJ de cada cliente, na mesma posição do IdCliente — use-o para confirmar a identidade sem expor o documento completo.
Body
| Campo | Tipo | Descrição |
| DDDTelefoneobrigatório | string | DDD + número. Ex: 21972923945. |
{
"DDDTelefone": "21972923945"
}
{
"IdCliente": [ "18cb0064-bbf4-63e8-6bfa-c8e55d768635" ],
"Digitos": [ "123" ]
}
Consulta Termo de Acordo
Retorna o documento do Termo de Acordo. O campo ArquivoTermo está em base64 e representa um PDF — decodifique para exibir ou fazer download.
Body
| Campo | Tipo | Descrição |
| IdContratoobrigatório | string (UUID) | Retornado pelos métodos CadastroAcordo e StatusAcordo. |
| IdAcordoobrigatório | string (UUID) | Retornado pelos métodos CadastroAcordo e StatusAcordo. |
{
"IdContrato": "ee6f854f-0bb9-5786-f661-3b085485bca0",
"IdAcordo": "b88dfd82-faf8-ad2d-5ac3-88677109f3cb"
}
{
"IdContrato": "ee6f854f-0bb9-5786-f661-3b085485bca0",
"IdAcordo": "b88dfd82-faf8-ad2d-5ac3-88677109f3cb",
"ArquivoTermo": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIK..."
}
Detalhe Títulos
Retorna o detalhamento dos títulos relacionados aos débitos do contrato informado. O contrato precisa estar enquadrado em alguma regra de negociação.
Apenas os títulos em aberto (débitos) são retornados. Títulos já pagos ou baixados não aparecem neste método.
Body
| Campo | Tipo | Descrição |
| IdContratoobrigatório | string (UUID) | UUID do contrato retornado em ConsultaDebitos. |
{
"IdContrato": "ee6f854f-0bb9-5786-f661-3b085485bca0"
}
{
"IdCliente": "18cb0064-bbf4-63e8-6bfa-c8e55d768635",
"Nome": "JOSELITO DA SILVA E SOUZA",
"TotalDebito": "201,00",
"TotalAtualizado": "261,85",
"Titulos": [
{
"IdTitulo": "06450746-b7cf-8a21-7a15-6f8df3811fc4",
"Parcela": "03/03",
"Titulo": "FAT-00012024",
"Documento": "FATURA",
"DataEmissao": "01/01/2024",
"DataVencimento": "05/03/2024",
"ValorDebito": "100,50",
"ValorAtualizado": "131,43"
},
{
"IdTitulo": "16c14c2e-863f-06c0-2bca-e81e28ffc04e",
"Parcela": "04/04",
"Titulo": "FAT-00012024",
"Documento": "FATURA",
"DataEmissao": "01/02/2024",
"DataVencimento": "05/04/2024",
"ValorDebito": "100,50",
"ValorAtualizado": "130,42"
}
]
}
Status do Acordo
Retorna informações detalhadas do acordo: parcelas com status e vencimento, títulos originais e pagamentos já realizados (valores negativos em ValorDebito).
Body
| Campo | Tipo | Descrição |
| IdAcordoobrigatório | string (UUID) | UUID do acordo retornado em CadastroAcordo. |
{
"IdAcordo": "b88dfd82-faf8-ad2d-5ac3-88677109f3cb"
}
{
"RetornoAcordos": {
"IdAcordo": "b88dfd82-faf8-ad2d-5ac3-88677109f3cb",
"PrevisaoCancelamento": "2026-06-03",
"DataAcordo": "2026-05-29 16:21:48",
"NumeroContrato": "111222333444",
"NomeCredor": "3C SISTEMAS LTDA",
"Plano": 1,
"Parcelas": [
{
"Parcela": 1,
"Status": "Em Aberto",
"DataVencimento": "2026-05-29",
"ValorVencimento": 120.65
}
],
"Titulos": [
{
"Parcela": "001",
"Titulo": "0001",
"Documento": "PAGAMENTO",
"DataEmissao": "02/02/2024",
"DataVencimento": "02/02/2024",
"ValorDebito": "-50,00"
},
{
"Parcela": "40",
"Titulo": "PARCELA PAGA 001005",
"Documento": "PAGAMENTO",
"DataEmissao": "16/05/2026",
"DataVencimento": "16/05/2026",
"ValorDebito": "-95,21"
},
{
"Parcela": "01/03",
"Titulo": "FAT-00012024",
"Documento": "FATURA",
"DataEmissao": "01/01/2024",
"DataVencimento": "05/01/2024",
"ValorDebito": "100,50"
},
{
"Parcela": "02/03",
"Titulo": "FAT-00012024",
"Documento": "FATURA",
"DataEmissao": "01/01/2024",
"DataVencimento": "05/02/2024",
"ValorDebito": "100,50"
}
]
}
}
Listar
Listar Carteiras
Lista as carteiras ativas disponíveis para o token autenticado.
Não requer body. O IdCarteira retornado é usado em IncluirCliente e nos relatórios de Prestação de Contas.
{
"Carteiras": [
{
"IdCarteira": 1,
"CNPJ": "29737630000125",
"RazaoSocial":"3C SISTEMAS LTDA",
"Descricao": "3C SISTEMAS LTDA",
"Codigo": "1234"
},
{
"IdCarteira": 2,
"CNPJ": "29737630000125",
"RazaoSocial":"CONDOMINIO MONTELO LOBATO",
"Descricao": "CONDOMINIO MONTELO LOBATO",
"Codigo": "1234"
}
]
}
Listar Filas
Lista as filas de acionamento disponíveis. Retorna IdFila, descrição, quantidade de clientes e ticket médio.
Não requer body. Use o IdFila retornado no endpoint ListarClientesFila.
{
"Filas": [
{
"IdFila": 1,
"Descricao": "FILA DE TESTE",
"Quantidade": 4,
"Valor": "4967.03",
"TicketMedio": "1241.76"
}
]
}
Listar Clientes por Fila
Lista os clientes de uma fila de acionamento. Retorna IdContrato de cada cliente — use-o em ConsultaDebitos para obter a situação completa de cada devedor.
Body
| Campo | Tipo | Descrição |
| IdFilaobrigatório | number | ID da fila. Obtido via ListarFilas. |
| Acordosopcional | boolean | Se true, inclui clientes com acordos ativos. |
| Agendadosopcional | boolean | Se true, inclui clientes com retorno agendado. |
{
"IdFila": 1,
"Acordos": false,
"Agendados": false
}
{
"ClienteFila": [
{ "IdFila": 1, "IdContrato": "89ee95b0-fee1-cfaa-f974-4f34083c3b04" },
{ "IdFila": 1, "IdContrato": "ee6f854f-0bb9-5786-f661-3b085485bca0" },
{ "IdFila": 1, "IdContrato": ... },
]
}
Listar Documentos
Lista os tipos de documentos já cadastrados na plataforma. Use o campo Descricao no campo Documento ao incluir títulos via IncluirCliente.
{
"Documentos": [
{
"IdDocumento": 1,
"Descricao": "Fatura",
"PossiuAtualizacao": true,
"AmortizaJurosFuturo":false,
"Codigo": ""
},
{
"IdDocumento": 2,
"Descricao": "Pagamento",
"PossiuAtualizacao": false,
"AmortizaJurosFuturo":false,
"Codigo": ""
}
]
}
Listar Ocorrências
Lista as ocorrências disponíveis para registro no histórico do cliente. Use o IdOcorrencia retornado no endpoint IncluirOcorrencia.
Não requer body. A lista de ocorrências é configurada por ambiente — execute este endpoint para obter os IdOcorrencia válidos do seu contrato.
Resposta 200 — exemplos por tipo de retorno
{
"Ocorrencias": [
{ "IdOcorrencia": 6, "Descricao": "PAGAMENTO CONFIRMADO", "TipoRetorno": "CONTATO - COM NEGOCIAÇÃO", "SituacaoDestino": "0" },
{ "IdOcorrencia": 7, "Descricao": "PROMESSA", "TipoRetorno": "CONTATO - COM NEGOCIAÇÃO", "SituacaoDestino": "PROMESSA DE ACORDO" },
{ "IdOcorrencia": 40, "Descricao": "CONTATO COM O CLIENTE", "TipoRetorno": "CONTATO - COM NEGOCIAÇÃO", "SituacaoDestino": "EM COBRANÇA" },
{ "IdOcorrencia": 98, "Descricao": "BOLETO ENVIADO POR WHATSAPP", "TipoRetorno": "CONTATO - COM NEGOCIAÇÃO", "SituacaoDestino": "EM COBRANÇA" },
{ "IdOcorrencia": 21, "Descricao": "AÇÃO JUDICIAL", "TipoRetorno": "CONTATO - SEM NEGOCIAÇÃO", "SituacaoDestino": "CLIENTE COM AÇÃO NA JUSTIÇA" },
{ "IdOcorrencia": 134, "Descricao": "CLIENTE ACESSOU A PLATAFORMA", "TipoRetorno": "CONTATO - SEM NEGOCIAÇÃO", "SituacaoDestino": "EM COBRANÇA" },
{ "IdOcorrencia": 37, "Descricao": "NÃO ATENDE", "TipoRetorno": "SEM CONTATO", "SituacaoDestino": "EM COBRANÇA" },
{ "IdOcorrencia": 113, "Descricao": "CAIXA POSTAL", "TipoRetorno": "SEM CONTATO", "SituacaoDestino": "EM COBRANÇA" },
{ "IdOcorrencia": 19, "Descricao": "RECADO", "TipoRetorno": "CONTATO COM TERCEIROS", "SituacaoDestino": "EM COBRANÇA" },
{ "IdOcorrencia": 107, "Descricao": "DESCONHECIDO NO TELEFONE", "TipoRetorno": "CONTATO COM TERCEIROS", "SituacaoDestino": "EM COBRANÇA" },
{ "IdOcorrencia": 17, "Descricao": "ACORDO REALIZADO", "TipoRetorno": "OPERACIONAL", "SituacaoDestino": "ACORDO" },
{ "IdOcorrencia": 52, "Descricao": "ACORDO CANCELADO", "TipoRetorno": "OPERACIONAL", "SituacaoDestino": "EM COBRANÇA" },
{ "IdOcorrencia": 34, "Descricao": "ESTORNO DE PAGAMENTO", "TipoRetorno": "OPERACIONAL", "SituacaoDestino": "0" }
]
}
Listar Regras de Negociação
Lista as regras de negociação configuradas para o credor. As regras definem os critérios de enquadramento dos débitos e o período de vigência das ofertas.
Não requer body. Um débito só aparece em ConsultaDebitos se estiver enquadrado em alguma regra ativa.
{
"Regras": [
{
"IdRegra": 3,
"Descricao": "ATRASO DE 0181 A 99999 DIAS",
"TipoRegra": "Regra por Contrato",
"TipoEnquadramento": "Dias do Atraso do Débito",
"DataInicial": "2024-07-18",
"DataFinal": "2027-04-14"
},
{
"IdRegra": 4,
"Descricao": "ATRASO DE 0181 A 99999 DIAS",
"TipoRegra": "Regra por Contrato",
"TipoEnquadramento": "Dias do Atraso do Débito",
"DataInicial": "2024-07-18",
"DataFinal": "2027-04-14"
}
]
}
Negociação
Cadastro do Acordo
Efetiva o acordo para a oferta informada. Use os dados retornados por ConsultaCondicoesAcordo para preencher os campos. Retorna IdAcordo e IdContrato.
Body
| Campo | Tipo | Descrição |
| IdOfertaobrigatório | string (UUID) | Retornado por ConsultaDebitos. |
| IdNegociacaoobrigatório | number | Opção de parcelamento retornada por ConsultaCondicoesAcordo. |
| DataEntradaobrigatório | string | Data de entrada disponível, retornada por ConsultaCondicoesAcordo. Formato AAAA-MM-DD. |
| FormaPagamentoopcional | string | Se disponibilizada em ConsultaCondicoesAcordo. Ex: "PIX", "BOLETO", "CARTÃO DE CRÉDITO". |
{
"IdOferta": "89ee95b0-fee1-cfaa-f974-4f34083c3b04",
"IdNegociacao": 3,
"DataEntrada": "2026-05-06",
"FormaPagamento": "PIX"
}
200 OK
Acordo cadastrado. Retorna IdAcordo, IdContrato e parcelas.
400
Oferta expirada, condições inválidas ou data indisponível.
{
"IdContrato": "fa602407-d193-a9da-596c-7fda0b02ae36",
"IdOferta": "fa602407-d193-a9da-596c-7fda0b02ae36",
"IdAcordo": "f4ce3fc0-25f8-e4c8-8e34-74ad3e642b8e",
"ValorAcordo": 1504.54,
"PercentualDesconto":6.27,
"ValorDesconto": 100.65,
"Parcelas": [
{ "Parcela": 1, "DataVencimento": "2026-06-03", "ValorVencimento": 501.51 },
{ "Parcela": 2, "DataVencimento": "2026-07-03", "ValorVencimento": 501.52 },
{ "Parcela": 3, "DataVencimento": "2026-08-03", "ValorVencimento": 501.51 }
]
}
Consulta Parcela
Retorna os dados da parcela e os meios de recebimento disponíveis: Chave Pix, Link de Cartão de Crédito, Linha Digitável, Código de Barras e Link do Boleto. O campo Arquivo está em base64.
Body
| Campo | Tipo | Descrição |
| IdAcordoobrigatório | string (UUID) | UUID do acordo retornado por CadastroAcordo. |
| Parcelaobrigatório | number | Número da parcela (inicia em 1). |
{
"IdAcordo": "f4ce3fc0-25f8-e4c8-8e34-74ad3e642b8e",
"Parcela": 1
}
O campo Mensagem indica se o acordo ainda está em processamento. Quando preenchido, os campos de pagamento (ChavePIX, QRCode, LinhaDigitavel, etc.) retornam vazios — aguarde a liberação e consulte novamente.
Resposta 200 — parcela liberada para pagamento
{
"IdAcordo": "f4ce3fc0-25f8-e4c8-8e34-74ad3e642b8e",
"DataVencimento": "2026-06-03",
"ValorVencimento": "501.51",
"IdParcela": "0ccc9508-1e18-5f4d-f603-a51600582a47",
"Parcela": 1,
"Plano": 3,
"ChavePIX": "00020126580014br.gov.bcb.pix...",
"QRCode": "data:image/png;base64,iVBORw0KGgo...",
"LinhaDigitavel": "34191.09008 12345.678901 23456.789012 1 93450000050151",
"CodigoBarras": "34191930000050151000090001234567890123456789012",
"Link": "https://boleto.sistematotum.com.br/boleto/42-1.pdf",
"Arquivo": "JVBERi0xLjQ...",
"Mensagem": ""
}
Resposta 200 — acordo ainda em processamento
{
"IdAcordo": "f4ce3fc0-25f8-e4c8-8e34-74ad3e642b8e",
"DataVencimento": "2026-06-03",
"ValorVencimento": "501.51",
"IdParcela": "0ccc9508-1e18-5f4d-f603-a51600582a47",
"Parcela": 1,
"Plano": 3,
"ChavePIX": "",
"QRCode": "",
"LinhaDigitavel": "",
"CodigoBarras": "",
"Link": "",
"Arquivo": "",
"Mensagem": "Aguarde o processamento do seu acordo, assim que o mesmo for liberado para pagamento entraremos em contato !"
}
Upload Parcela Boleto
Envia o boleto de uma parcela emitido fora do sistema (anexado pela assessoria). O arquivo passa a ser o boleto da parcela: é retornado no ConsultaParcela (Link e Arquivo) e o sistema não gera outro boleto por cima. Enviar ArquivoBase64 vazio remove o boleto anexado.
Body
| Campo | Tipo | Descrição |
| IdAcordoobrigatório | string (UUID) | UUID do acordo retornado por CadastroAcordo. |
| Parcelaobrigatório | number | Número da parcela (inicia em 1). |
| ArquivoBase64obrigatório | string (base64) | PDF do boleto em base64. Vazio ("") remove o boleto anexado anteriormente. |
Aceito somente para parcela em aberto de acordo ativo, e quando a carteira não emite o boleto pelo sistema (meio de recebimento, integração ou CNAB). A remoção afeta apenas o boleto anexado — o boleto gerado pelo sistema não é alterado.
Exemplo de requisição — anexar
{
"IdAcordo": "f4ce3fc0-25f8-e4c8-8e34-74ad3e642b8e",
"Parcela": 1,
"ArquivoBase64": "JVBERi0xLjQK..."
}
Exemplo de requisição — remover
{
"IdAcordo": "f4ce3fc0-25f8-e4c8-8e34-74ad3e642b8e",
"Parcela": 1,
"ArquivoBase64": ""
}
200 OK
Boleto anexado (ou removido). Sucesso = true.
400
Acordo inexistente/inativo, parcela não encontrada ou paga, carteira que emite boleto ou arquivo que não é PDF. Sucesso = false.
{
"Sucesso": true,
"Mensagem": "Boleto anexado com sucesso !"
}
{
"Sucesso": false,
"Mensagem": "Arquivo inválido, envie o boleto em PDF !"
}
Cancelar Acordo
Cancela o acordo se estiver com status Ativo.
Body
| Campo | Tipo | Descrição |
| IdAcordoobrigatório | string (UUID) | UUID do acordo a ser cancelado. |
{
"IdAcordo": "b88dfd82-faf8-ad2d-5ac3-88677109f3cb"
}
{
"Mensagem": "Acordo Cancelado com Sucesso"
}
Processos
Incluir Cliente
Inclui o cliente no sistema de cobrança. Permite a criação da carteira e inclusão de títulos e baixas (pagamentos). Se o cliente já existir, atualiza o cadastro. Retorno: IdContrato e indicação se foi incluído ou atualizado.
- Em ListaTitulos, valores negativos representam baixas (pagamentos).
- Para agrupar títulos no mesmo contrato, repita o número do contrato. Números diferentes criam contratos separados.
IdCarteira e Numero (contrato) são obrigatórios.
Body — estrutura completa
| Objeto / Campo | Tipo | Descrição |
| Cliente (obrigatório) |
| CPFouCNPJobrigatório | string | CPF ou CNPJ (apenas números). |
| Nomeobrigatório | string | Nome completo ou razão social. |
| Documentoopcional | string | RG ou outro documento. Ex: "0001 SSP/RJ". |
| DataNascimentoopcional | string | Formato AAAA-MM-DD. |
| Sexoopcional | string | "M" ou "F". |
| ListaEnderecos › Endereco (array, opcional) |
| Logradouro, Numero, Complemento, Bairro, Cidade, UF, CEP | string | Campos de endereço. |
| ListaEmails › Emails (array, opcional) |
| Email | string | E-mail do cliente. |
| ListaTelefones › Telefones (array, opcional) |
| DDDTelefone | string | DDD + número. |
| Tipo | string | Residencial · Comercial · Referencia/Recado · Celular · WhatsApp · Avalista |
| Preferecial | boolean | Se é o telefone preferencial. |
| Observacao | string | Observação sobre o telefone. Ex: horário disponível. |
| Contrato (obrigatório) |
| IdCarteiraobrigatório | number | ID da carteira. Obtido via ListarCarteiras. |
| Numeroobrigatório | string | Número do contrato no sistema de origem. |
| DataContratoopcional | string | Formato AAAA-MM-DD. |
| Codigoopcional | string | Código interno de referência. |
| ListaTitulos › Titulos (array, todos os campos obrigatórios) |
| Parcelaobrigatório | string | Identificação da parcela. Ex: "01/03". |
| Documentoobrigatório | string | Tipo do documento. Ex: "Fatura". |
| Numeroobrigatório | string | Número do documento. |
| Emissaoobrigatório | string | Data de emissão. Formato AAAA-MM-DD. |
| Vencimentoobrigatório | string | Data de vencimento. Formato AAAA-MM-DD. |
| Valorobrigatório | number | Valor do título. Negativo para baixa (pagamento). |
200 OK
Retorna IdContrato e confirmação de inclusão ou atualização.
400
Dados obrigatórios ausentes ou carteira inválida.
{
"IdContrato": "bf7fee5c-0512-0f06-293c-af41158addbc",
"Mensagem": "Cliente Incluído com Sucesso"
}
{
"Cliente": {
"CPFouCNPJ": "12312312387",
"Nome": "JOSELITO DA SILVA E SOUZA",
"DataNascimento": "1975-05-02",
"Sexo": "M"
},
"ListaTelefones": {
"Telefones": [
{ "DDDTelefone": "21972923945", "Tipo": "WhatsApp", "Preferecial": true }
]
},
"Contrato": {
"IdCarteira": 1,
"Numero": "FAT-2024-0001",
"DataContrato": "2024-01-04"
},
"ListaTitulos": {
"Titulos": [
{
"Parcela": "01/03",
"Documento": "Fatura",
"Numero": "FAT-00012024",
"Emissao": "2024-01-01",
"Vencimento":"2024-01-05",
"Valor": 100.50
},
{
"Parcela": "001",
"Documento": "Pagamento",
"Numero": "0001",
"Emissao": "2024-02-02",
"Vencimento":"2024-02-02",
"Valor": -50
}
]
}
}
Incluir Ocorrência
Registra uma ocorrência no histórico do cliente. Use ListarOcorrencias para obter os IdOcorrencia disponíveis.
Body
| Campo | Tipo | Descrição |
| IdContratoobrigatório | string (UUID) | UUID retornado em ConsultaDebitos. Se usar IdCliente (UUID) no lugar, inclui em todos os contratos do cliente. |
| IdOcorrenciaobrigatório | string | ID da ocorrência. Obtido via ListarOcorrencias. |
| DataHoraopcional | string | Formato AAAA-MM-DD HH:MM:SS. Padrão: data/hora atual. |
| DDDTelefoneopcional | string | Telefone usado na ocorrência. |
| ObservacaoTelefoneopcional | string | Informação adicional do telefone. |
| Observacaoopcional | string | Texto livre em UTF-8. |
| ConfirmarPagamentoopcional | string | Comprovação de pagamento: informe a linha digitável/código de barras do boleto ou a Chave Pix (copia e cola). Quando informado, ativa o fluxo de comprovação descrito abaixo. |
| ValorPagocondicional | string ou number | Valor pago pelo cliente. Aceita formato brasileiro ("505,95") ou numérico. Obrigatório quando ConfirmarPagamento for informado. |
| DataPagamentocondicional | string | Data do pagamento. Formato AAAA-MM-DD. Obrigatória quando ConfirmarPagamento for informado. |
| Arquivoopcional | string (base64) | Comprovante de pagamento em base64 (PDF, JPG ou PNG). É anexado à ficha do cliente em todos os cenários da comprovação. |
Comprovação de Pagamento — comportamento
Com ConfirmarPagamento informado, o sistema localiza a parcela pelo boleto ou pela Chave Pix e o retorno traz o campo adicional ConfirmacaoPagamento:
Parcela identificada, em aberto e ValorPago ≥ valor da parcela → a parcela é baixada → "Parcela identificada e baixa realizada com sucesso !"
Parcela não identificada, dados incompletos ou comprovante de outro contrato → inclui a ocorrência automática "PAGAMENTO NÃO REALIZADO - ERRO DA IDENTIFICAÇÃO DA PARCELA" e a parcela não é baixada → "Parcela não identificada, verifique !"
ValorPago inferior ao valor da parcela → inclui a ocorrência automática "PAGAMENTO NÃO REALIZADO - DIVERGÊNCIA DE VALOR" e a parcela não é baixada → "Pagamento não realizado - Divergência de valor !"
Parcela já baixada → "Parcela já estava baixada."
Em todos os cenários a ocorrência enviada na chamada é registrada normalmente e o comprovante (Arquivo) é anexado à ficha do cliente.
{
"IdContrato": "89ee95b0-fee1-cfaa-f974-4f34083c3b04",
"IdOcorrencia": "0011",
"DataHora": "2025-08-14 14:00:00",
"DDDTelefone": "21972923945",
"ObservacaoTelefone": "Texto complementar",
"Observacao": "Cliente solicitou retorno em 2 dias"
}
{
"Mensagem": "Ocorrência incluída com Sucesso"
}
Exemplo de requisição — com Comprovação de Pagamento
{
"IdContrato": "89ee95b0-fee1-cfaa-f974-4f34083c3b04",
"IdOcorrencia": "0011",
"ConfirmarPagamento": "34191.09990 00754.130631.72123 170002 4 15660000030000",
"ValorPago": "300,00",
"DataPagamento": "2026-10-02",
"Arquivo": "JVBERi0xLjQKJeLjz9MK...",
"Observacao": "Cliente enviou o comprovante de pagamento"
}
Resposta 200 — com Comprovação de Pagamento
{
"Mensagem": "Ocorrência incluída com Sucesso",
"ConfirmacaoPagamento": "Parcela identificada e baixa realizada com sucesso !"
}
Atualizar E-mail
Inclui ou atualiza como ativo o e-mail do cliente.
Body
| Campo | Tipo | Descrição |
| IdClienteobrigatório | string (UUID) | UUID do cliente. |
| Emailobrigatório | string | Endereço de e-mail. |
{
"IdCliente": "18cb0064-bbf4-63e8-6bfa-c8e55d768635",
"Email": "joselito@exemplo.com.br"
}
{
"Mensagem": "E-mail Incluído com sucesso"
}
Atualizar Telefone
Inclui ou atualiza como ativo o telefone do cliente.
Body
| Campo | Tipo | Descrição |
| IdClienteobrigatório | string (UUID) | UUID do cliente. |
| DDDTelefoneobrigatório | string | DDD + número. Ex: 21972923945. |
| Tipoopcional | string | Residencial · Comercial · Referencia/Recado · Celular · WhatsApp · Avalista |
| Observacaoopcional | string | Informações adicionais. Ex: horário de contato. |
{
"IdCliente": "18cb0064-bbf4-63e8-6bfa-c8e55d768635",
"DDDTelefone": "21972923945",
"Tipo": "WhatsApp",
"Observacao": "Entre 08:00 e 18:00"
}
{
"Mensagem": "Telefone Incluído com sucesso"
}
Baixa Contrato
Retira o contrato da cobrança.
Body
| Campo | Tipo | Descrição |
| IdContratoobrigatório | string (UUID) | UUID retornado em ConsultaDebitos. |
| IdMotivoopcional | string | 2 Solicitada pelo Credor · 3 Decisão Judicial |
| DataHoraopcional | string | Formato AAAA-MM-DD HH:MM:SS. |
{
"IdContrato": "89ee95b0-fee1-cfaa-f974-4f34083c3b04",
"IdMotivo": "2"
}
{
"Mensagem": "O Contrato baixado com sucesso"
}
Baixa Título
Retira um título específico da cobrança.
Body
| Campo | Tipo | Descrição |
| IdTituloobrigatório | string (UUID) | UUID retornado em ConsultaDebitos e DetalheTitulos. |
| IdMotivoobrigatório | number | 2 Pagamento · 3 Exclusão |
{
"IdTitulo": "11b19d49-fd75-132e-6fdf-1f25ebd21501",
"IdMotivo": 2
}
{
"Mensagem": "O Título baixado com sucesso"
}
Retorno de Ligação — Discador Ativo
Registra a abertura da ficha do cliente na tela do agente quando o discador ativo conecta uma chamada. Na v2, o contrato é identificado pelo IdContrato (UUID) em vez do ID numérico interno.
Parâmetros passados diretamente na URL (não há body). O token de autenticação é o token específico do discador, cadastrado em integracao_discador. Não utiliza JWT.
Parâmetros de URL
| Parâmetro | Tipo | Obrigatório | Descrição |
id_agente | string | Sim | Ramal do agente (campo ramal_usu em Usuários) |
id_contato | UUID | Sim | IdContrato do cliente (UUID v4 retornado por ConsultaDebitos) |
id_ligacao | string | Não | ID da ligação no discador (para rastreamento) |
GET /Api/v2/RetornoLigacao/id_agente=1001/id_contato=89ee95b0-fee1-cfaa-f974-4f34083c3b04/id_ligacao=LIG-9999
Authorization: Bearer {token_discador}
{
"Mensagem": "Processado com Sucesso !"
}
Retorno de Ligação — Discador Receptivo
Registra a abertura da ficha quando o cliente entra em contato por ligação receptiva. Idêntico ao v1 — o número de telefone não é um dado sensível com ID exposto, portanto não há mudança de parâmetro.
O número deve ser enviado com DDD sem separadores (ex: 21987654321). O token do discador é obrigatório na v2. O sistema localiza o contrato pelo telefone cadastrado.
Parâmetros de URL
| Parâmetro | Tipo | Obrigatório | Descrição |
id_agente | string | Sim | Ramal do agente |
ddd_telefone | string | Sim | DDD + número completo do cliente (11 dígitos) |
id_ligacao | string | Não | ID da ligação no discador (para rastreamento) |
GET /Api/v2/RetornoLigacaoReceptiva/id_agente=1001/ddd_telefone=21987654321/id_ligacao=LIG-9999
Authorization: Bearer {token_discador}
{
"Mensagem": "Processado com Sucesso !"
}
Precisa de ajuda para integrar?
Nossa equipe técnica pode ajudar na integração do Totum Cobrança ao seu sistema.