Totum Cobrança — Documentação da API v2

POST /v2/Auth

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.

Requisição

{
  "ClientId": "seu_client_id",
  "SecretId": "sua_senha"
}

Resposta 200

{
  "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)

// Pessoa Física — CPF 123.123.123-87
"IdCliente": "18cb0064-bbf4-63e8-6bfa-c8e55d768635"

// Pessoa Jurídica — CNPJ 29.737.630/0001-25
"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.

GET /Status

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.

Resposta 200

{
  "Mensagem": "OnLine"
}

POST /ConsultaAcessos

Consulta Acessos

Retorna os 1000 últimos acessos realizados na plataforma.

Não requer body. Apenas o header Authorization.

Resposta 200

{
  "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
    }
  ]
}

POST /ConsultaDebitos

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.

Exemplo de requisição

// Por IdCliente (UUID)
{
  "IdCliente": "18cb0064-bbf4-63e8-6bfa-c8e55d768635"
}

// Por contrato específico (UUID)
{
  "IdContrato": "89ee95b0-fee1-cfaa-f974-4f34083c3b04"
}

// Por CPF ou CNPJ
{
  "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"
  },
  // Débitos: títulos em aberto, ainda não negociados
  "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"
        }
        // ... demais títulos
      ],
      "ValorHonorarios": 120.00 // opcional
    }
    // ... demais débitos
  ],

  // Acordos: débitos já negociados, com parcelas e status
  "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"  // negativo = pagamento já realizado
        }
        // ... demais títulos
      ],
      "TotalDebito": "55,79"
    }
  ]
}

POST /ConsultaCondicoesAcordo

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). Cada opção pode ter seu próprio FormasPagamento — quando as formas variam por opção, o campo aparece dentro de cada item de Opcoes. 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.

Exemplo de requisição

{
  "IdOferta":     "89ee95b0-fee1-cfaa-f974-4f34083c3b04",
  "ValorEntrada": "1.000,00"  // opcional
}

Resposta 200

{
  "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" ],

  // Opcoes: cada item representa uma opção de parcelamento disponível
  // IdNegociacao "1" = à vista | "2"..."N" = parcelado em N vezes
  // FormasPagamento: presente em cada opção individualmente OU ausente (quando igual para todas)
  "Opcoes": [
    {
      "IdNegociacao":        "1",
      "PercentualDesconto":  13.17,
      "ValorTotalDesconto":  475.59,
      "ValorPrincipal":      3015.03,
      "ValorAcordo":         3135.54,
      "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,
      "ValorEntrada":        1686.76,
      "ValorParcela":        1686.76,
      "ValorUltimaParcela":  1686.76,
      "Parcelas": [
        { "Parcela": 1, "Valor": 1686.76 },
        { "Parcela": 2, "Valor": 1686.76 }
      ],
      "FormasPagamento": [ "PIX", "BOLETO" ]
    },
    // ... opções de 3 a N parcelas seguem o mesmo padrão
    {
      "IdNegociacao":        "6",
      "PercentualDesconto":  6.58,
      "ValorTotalDesconto":  237.61,
      "ValorPrincipal":      3015.03,
      "ValorAcordo":         3373.52,
      "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" ]
    }
  ]
}

POST /ConsultaClienteTelefone

Consulta Cliente por Telefone

Retorna uma lista de IdCliente (UUID) de clientes com o DDD e telefone informado.

Body

Campo	Tipo	Descrição
DDDTelefoneobrigatório	string	DDD + número. Ex: `21972923945`.

Exemplo de requisição

{
  "DDDTelefone": "21972923945"
}

Resposta 200

{
  "IdCliente": [ "18cb0064-bbf4-63e8-6bfa-c8e55d768635" ]
}

POST /ConsultaTermoAcordo

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.

Exemplo de requisição

{
  "IdContrato": "ee6f854f-0bb9-5786-f661-3b085485bca0",
  "IdAcordo":   "b88dfd82-faf8-ad2d-5ac3-88677109f3cb"
}

Resposta 200

{
  "IdContrato":   "ee6f854f-0bb9-5786-f661-3b085485bca0",
  "IdAcordo":     "b88dfd82-faf8-ad2d-5ac3-88677109f3cb",
  "ArquivoTermo": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIK..."
  // PDF do Termo de Acordo codificado em base64
  // Para exibir: data:application/pdf;base64,{ArquivoTermo}
  // Para download: decodifique e salve como .pdf
}

POST /DetalheTitulos

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.

Exemplo de requisição

{
  "IdContrato": "ee6f854f-0bb9-5786-f661-3b085485bca0"
}

Resposta 200

{
  "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"
    }
  ]
}

POST /StatusAcordo

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.

Exemplo de requisição

{
  "IdAcordo": "b88dfd82-faf8-ad2d-5ac3-88677109f3cb"
}

Resposta 200

{
  "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"  // negativo = pagamento realizado
      },
      {
        "Parcela":        "40",
        "Titulo":         "PARCELA PAGA 001005",
        "Documento":      "PAGAMENTO",
        "DataEmissao":    "16/05/2026",
        "DataVencimento": "16/05/2026",
        "ValorDebito":    "-95,21"  // negativo = pagamento realizado
      },
      {
        "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"
      }
    ]
  }
}

GET /ListarCarteiras

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.

Resposta 200

{
  "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"
    }
    // ... demais carteiras
  ]
}

GET /ListarFilas

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.

Resposta 200

{
  "Filas": [
    {
      "IdFila":      1,
      "Descricao":   "FILA DE TESTE",
      "Quantidade":  4,
      "Valor":       "4967.03",
      "TicketMedio": "1241.76"
    }
  ]
}

POST /ListarClientesFila

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.

Exemplo de requisição

{
  "IdFila":    1,
  "Acordos":   false,
  "Agendados": false
}

Resposta 200

{
  "ClienteFila": [
    { "IdFila": 1, "IdContrato": "89ee95b0-fee1-cfaa-f974-4f34083c3b04" },
    { "IdFila": 1, "IdContrato": "ee6f854f-0bb9-5786-f661-3b085485bca0" },
    { "IdFila": 1, "IdContrato": ... },
  ]
}

GET /ListarDocumentos

Listar Documentos

Lista os tipos de documentos já cadastrados na plataforma. Use o campo Descricao no campo Documento ao incluir títulos via IncluirCliente.

Não requer body.

Resposta 200

{
  "Documentos": [
    {
      "IdDocumento":        1,
      "Descricao":          "Fatura",
      "PossiuAtualizacao":  true,   // aplica juros/correção
      "AmortizaJurosFuturo":false,
      "Codigo":             ""
    },
    {
      "IdDocumento":        2,
      "Descricao":          "Pagamento",
      "PossiuAtualizacao":  false,  // não aplica juros (baixa)
      "AmortizaJurosFuturo":false,
      "Codigo":             ""
    }
    // ... demais tipos
  ]
}

GET /ListarOcorrencias

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": [

    // Tipo: CONTATO - COM NEGOCIAÇÃO
    { "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" },

    // Tipo: CONTATO - SEM NEGOCIAÇÃO
    { "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" },

    // Tipo: SEM CONTATO
    { "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" },

    // Tipo: CONTATO COM TERCEIROS
    { "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" },

    // Tipo: OPERACIONAL
    { "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" }

    // ... demais ocorrências (lista completa via API)
  ]
}

GET /ListarRegras

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.

Resposta 200

{
  "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"
    }
    // ... demais regras
  ]
}

POST /CadastroAcordo

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

Exemplo de requisição

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

Resposta 200

{
  "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 }
  ]
}

POST /ConsultaParcela

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

Exemplo de requisição

{
  "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...",  // PDF do boleto em base64
  "Mensagem":        ""  // vazio = pagamento liberado
}

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 !"
}

POST /CancelarAcordo

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.

Exemplo de requisição

{
  "IdAcordo": "b88dfd82-faf8-ad2d-5ac3-88677109f3cb"
}

Resposta 200

{
  "Mensagem": "Acordo Cancelado com Sucesso"
}

POST /IncluirCliente

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.

Resposta 200

{
  "IdContrato": "bf7fee5c-0512-0f06-293c-af41158addbc",
  "Mensagem":   "Cliente Incluído com Sucesso"
}

Exemplo completo

{
  "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  // negativo = baixa
      }
    ]
  }
}

POST /IncluirOcorrencia

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.

Exemplo de requisição

{
  "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"
}

Resposta 200

{
  "Mensagem": "Ocorrência incluída com Sucesso"
}

POST /AtualizaEmail

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.

Exemplo de requisição

{
  "IdCliente": "18cb0064-bbf4-63e8-6bfa-c8e55d768635",
  "Email":     "joselito@exemplo.com.br"
}

Resposta 200

{
  "Mensagem": "E-mail Incluído com sucesso"
}

POST /AtualizaTelefone

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.

Exemplo de requisição

{
  "IdCliente":  "18cb0064-bbf4-63e8-6bfa-c8e55d768635",
  "DDDTelefone": "21972923945",
  "Tipo":        "WhatsApp",
  "Observacao":  "Entre 08:00 e 18:00"
}

Resposta 200

{
  "Mensagem": "Telefone Incluído com sucesso"
}

POST /BaixaContrato

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

Exemplo de requisição

{
  "IdContrato": "89ee95b0-fee1-cfaa-f974-4f34083c3b04",
  "IdMotivo":   "2"  // 2 = Solicitada pelo Credor | 3 = Decisão Judicial
}

Resposta 200

{
  "Mensagem": "O Contrato baixado com sucesso"
}

POST /BaixaTitulo

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

Exemplo de requisição

{
  "IdTitulo": "11b19d49-fd75-132e-6fdf-1f25ebd21501",
  "IdMotivo": 2  // 2 = Pagamento | 3 = Exclusão
}

Resposta 200

{
  "Mensagem": "O Título baixado com sucesso"
}

GET /v2/RetornoLigacao/id_agente={ramal}/id_contato={IdContrato}

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)

Exemplo de requisição

GET /Api/v2/RetornoLigacao/id_agente=1001/id_contato=89ee95b0-fee1-cfaa-f974-4f34083c3b04/id_ligacao=LIG-9999
Authorization: Bearer {token_discador}

Resposta 200

{
  "Mensagem": "Processado com Sucesso !"
}

GET /v2/RetornoLigacaoReceptiva/id_agente={ramal}/ddd_telefone={numero}

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)

Exemplo de requisição

GET /Api/v2/RetornoLigacaoReceptiva/id_agente=1001/ddd_telefone=21987654321/id_ligacao=LIG-9999
Authorization: Bearer {token_discador}

Resposta 200

{
  "Mensagem": "Processado com Sucesso !"
}

Totum Cobrança
API v2

Precisa de ajuda para integrar?

Totum CobrançaAPI v2

Precisa de ajuda para integrar?

Totum Cobrança
API v2