Totum Cobrança — Documentação da API

Autenticação

Todos os endpoints exigem autenticação via Bearer Token no header HTTP. Solicite seu token com a equipe 3C Sistemas.

Header de autenticação

Authorization: Bearer seu_token_aqui
Content-Type: application/json

200 OK

Processado com sucesso.

400 Bad Request

Processado, porém com erro ou observação.

401 Unauthorized

Token inválido ou ausente.

Base URL

Servidor de Homologação

https://app4.sistematotum.com.br/Homologacao/cobranca/Api

Todos os endpoints são acessados a partir desta Base URL. Exemplo: POST /Api/ConsultaDebitos → https://app4.sistematotum.com.br/Homologacao/cobranca/Api/ConsultaDebitos

Ambientes de Teste

Use os clientes abaixo para testar os endpoints de consulta e negociação em homologação.

CPFs / CNPJs de teste

// Pessoa Física
"CPFouCNPJ": "12312312387"

// Pessoa Jurídica
"CPFouCNPJ": "29737630000125"

Você também pode incluir seus próprios clientes de teste usando o endpoint IncluirCliente.

Token de teste — Homologação

Header Authorization

Authorization: Bearer L_Vv3PRWzGaISsNVKrYYZXHokz7w3HIAZn7D5jQbHdE=

Use este token para testar todos os endpoints em homologação.

Fluxo de Negociação

Para realizar um acordo completo via API, siga a sequência abaixo:

PASSO 1

Consultar Débitos

/ConsultaDebitos

PASSO 2

Ver Condições

/ConsultaCondicoesAcordo

PASSO 3

Cadastrar Acordo

/CadastroAcordo

PASSO 4

Obter Pagamento

/ConsultaParcela

ConsultaDebitos retorna IdContrato e IdOferta por débito. Use o IdOferta em ConsultaCondicoesAcordo para obter o IdNegociacao e datas disponíveis. Em seguida, chame CadastroAcordo para criar o acordo 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":  3,
      "IdCliente":   3,
      "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":  4,
      "IdCliente":   4,
      "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
CPFouCNPJcondicional	string	CPF ou CNPJ do devedor. Aceita formatado ou apenas números. Obrigatório se `IdContrato` não for informado.
IdContratocondicional	integer	Retornado em consultas anteriores. Obrigatório se `CPFouCNPJ` não for informado.
DataSimulacaoopcional	string	Formato `AAAA-MM-DD`. Se informado, atualiza os valores dos débitos até a data indicada.

Exemplo de requisição

// Por CPF ou CNPJ
{
  "CPFouCNPJ": "12312312387"
}

// Por contrato específico
{
  "IdContrato": 3
}

Resposta 200 — cliente com Débitos e Acordos

{
  "Cliente": {
    "CPFouCNPJ":       "12312312387",
    "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"
  },
  "FormasPagamento": [ "BOLETO", "PIX", "CARTÃO DE CRÉDITO" ],

  // Débitos: títulos em aberto, ainda não negociados
  "Debitos": [
    {
      "IdOferta":                    "e9799edb-0003-0003-9edb-c6a19e9799ed",
      "IdContrato":                  3,
      "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":       11,
          "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":             "41",
      "IdContrato":           6,
      "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":       21,
          "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, opções de parcelamento (IdNegociacao) e formas de pagamento aceitas. 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":     "e9799edb-0003-0003-9edb-c6a19e9799ed",
  "ValorEntrada": "1.000,00"  // opcional
}

Resposta 200

{
  "IdOferta":         "e9799edb-0003-0003-9edb-c6a19e9799ed",
  "IdContrato":       3,
  "NomeCredor":       "CONDOMINIO MONTELO LOBATO",
  "NumeroContrato":   "ALFA1",
  "DataEntrada":      [ "2025-06-02" ],
  "FormasPagamento":  [ "BOLETO", "PIX", "CARTÃO DE CRÉDITO" ],

  // Opcoes: cada item representa uma opção de parcelamento disponível
  // IdNegociacao "1" = à vista | "2"..."6" = parcelado em N vezes
  "Opcoes": [
    {
      "IdNegociacao":        "1",
      "PercentualDesconto":  13.17,
      "ValorTotalDesconto":  475.59,
      "ValorPrincipal":      3015.03,
      "ValorAcordo":         3135.54,
      "Parcelas": [
        { "Parcela": 1, "Valor": 3135.54 }
      ]
    },
    {
      "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 }
      ]
    },
    // ... opções de 3 a 6 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 }
      ]
    }
  ]
}

POST /ConsultaClienteTelefone

Consulta Cliente por Telefone

Retorna uma lista de CPF ou CNPJ 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

{
  "CPFouCNPJ": [ "12312312387" ]
}

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	number	Retornado pelos métodos CadastroAcordo e StatusAcordo.
IdAcordoobrigatório	number	Retornado pelos métodos CadastroAcordo e StatusAcordo.

Exemplo de requisição

{
  "IdContrato": 6,
  "IdAcordo":   41
}

Resposta 200

{
  "IdContrato":   6,
  "IdAcordo":     41,
  "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	ID do contrato.

Exemplo de requisição

{
  "IdContrato": "6"
}

Resposta 200

{
  "CPFouCNPJ":       "12312312387",
  "Nome":            "JOSELITO DA SILVA E SOUZA",
  "TotalDebito":     "201,00",
  "TotalAtualizado": "261,85",
  "Titulos": [
    {
      "IdTitulo":        20,
      "Parcela":         "03/03",
      "Titulo":          "FAT-00012024",
      "Documento":       "FATURA",
      "DataEmissao":     "01/01/2024",
      "DataVencimento":  "05/03/2024",
      "ValorDebito":     "100,50",
      "ValorAtualizado": "131,43"
    },
    {
      "IdTitulo":        22,
      "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	number	ID do acordo.

Exemplo de requisição

{
  "IdAcordo": 41
}

Resposta 200

{
  "RetornoAcordos": {
    "IdAcordo":              41,
    "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": 3 },
    { "IdFila": 1, "IdContrato": 4 },
    { "IdFila": 1, "IdContrato": 5 },
    { "IdFila": 1, "IdContrato": 6 }
  ]
}

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

Exemplo de requisição

{
  "IdOferta":       "0a989bca-0003-0003-9bca-569f90a989bc",
  "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":        4,
  "IdOferta":          "ecda6056-0004-0004-6056-f6a19ecda605",
  "IdAcordo":          "42",
  "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	ID do acordo retornado por CadastroAcordo.
Parcelaobrigatório	number	Número da parcela (inicia em 1).

Exemplo de requisição

{
  "IdAcordo": "40",
  "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":        42,
  "DataVencimento":  "2026-06-03",
  "ValorVencimento": "501.51",
  "IdParcela":       99,
  "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":        42,
  "DataVencimento":  "2026-06-03",
  "ValorVencimento": "501.51",
  "IdParcela":       99,
  "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	number	ID do acordo a ser cancelado.

Exemplo de requisição

{
  "IdAcordo": 41
}

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": "7",
  "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	Retornado em ConsultaDebitos. Se usar `CPFouCNPJ` 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":          "4822",
  "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
CPFouCNPJobrigatório	string	CPF ou CNPJ do cliente.
Emailobrigatório	string	Endereço de e-mail.

Exemplo de requisição

{
  "CPFouCNPJ": "12312312387",
  "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
CPFouCNPJobrigatório	string	CPF ou CNPJ do cliente.
DDDTelefoneobrigatório	string	DDD + número. Ex: `21972923945`.
Tipoopcional	number	`1` Residencial · `2` Comercial · `3` Referência/Recado · `4` Celular · `5` WhatsApp
Observacaoopcional	string	Informações adicionais. Ex: horário de contato.

Exemplo de requisição

{
  "CPFouCNPJ":  "12312312387",
  "DDDTelefone": "21972923945",
  "Tipo":        5,
  "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	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": "6224",
  "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	number	Retornado em ConsultaDebitos (se em acordo) e DetalheTitulos.
IdMotivoobrigatório	number	`2` Pagamento · `3` Exclusão

Exemplo de requisição

{
  "IdTitulo": 12805,
  "IdMotivo": 2  // 2 = Pagamento | 3 = Exclusão
}

Resposta 200

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

GET /RetornoLigacao/id_agente={ramal}/id_contato={id}

Retorno de Ligação — Discador Ativo

Registra a abertura da ficha do cliente na tela do agente quando o discador ativo conecta uma chamada. Vincula o ramal do agente ao contrato do cliente para que o sistema exiba as informações de cobrança.

Parâmetros passados diretamente na URL (não há body). O token de autenticação é o token específico do discador, cadastrado na tabela integracao_discador.

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`	integer	Sim	ID do contrato do cliente (`idcontrato_con`)
`id_ligacao`	string	Não	ID da ligação no discador (para rastreamento)

Exemplo de requisição

GET /Api/RetornoLigacao/id_agente=1001/id_contato=4567/id_ligacao=LIG-9999
Authorization: Bearer {token_discador}

Resposta 200

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

GET /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. O sistema localiza o contrato pelo número de telefone informado e vincula ao ramal do agente que atendeu.

O número deve ser enviado com DDD sem separadores (ex: 21987654321). O sistema busca na tabela de telefones e localiza o contrato ativo do cliente.

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/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 Reference

Precisa de ajuda para integrar?

Totum CobrançaAPI Reference

Precisa de ajuda para integrar?

Totum Cobrança
API Reference