Documentação da API - Saneamento

1. Visão Geral

API REST para integração com o sistema de saneamento municipal (água e esgoto). Permite consultar débitos, emitir e registrar a baixa de guias de arrecadação (DAM), abrir ordens de serviço de hidrômetro e consultar as faturas de uma unidade consumidora.

1.1. Convenções gerais

• Campos sem valor são omitidos do JSON de resposta. Trate a ausência de uma propriedade como valor nulo. A exceção é o módulo Leitura, em que todos os campos vêm sempre presentes.
• Datas no corpo JSON das respostas usam o formato ISO yyyy-MM-dd.
• Datas enviadas em parâmetros de URL usam dd-MM-yyyy (a barra é separador de caminho e não pode ser usada na URL).
• Datas enviadas dentro do corpo JSON das ordens de serviço de hidrômetro usam dd/MM/yyyy.
• Valores monetários trafegam como número decimal, com ponto como separador (ex.: 87.45). Não use separador de milhar.
• Não há paginação, filtros ou ordenação por parâmetro em nenhum endpoint.
• Algumas rotas terminam com barra final (/). Ela faz parte da URL e deve ser mantida exatamente como documentado.

1.2. Endpoints disponíveis

• Autenticação
  • GET /auth/login-token/{cpfcnpj}/{senha}
• Débitos e guias de arrecadação
  • GET /api/debito/saneamento-pessoa/{cpf}
  • GET /api/debito/saneamento-unidade/{numeroUnidade}
  • GET /api/debito/saneamento-parcela/{idParcela}
  • POST /api/debito/gerar
  • POST /api/debito/imprimir
  • GET /api/debito/consultar-parcela-por-dam/{idDam}
  • POST /api/debito/baixar-pagamento/...
• Hidrômetro
  • POST /api/hidrometro/ordem-servico-trocahd-completa/
  • POST /api/hidrometro/ordem-servico-abertura-completa/
  • GET /api/hidrometro/has-remessa-leitura-andamento/{numeroUnidade}/
  • GET /api/hidrometro/rotas-em-remessa-nao-concluida/
• Ordem de serviço
  • GET /api/ordem-servico/unidades-por-cpf/{cpfCnpj}/
  • GET /api/ordem-servico/servicos-disponivel/
  • POST /api/ordem-servico/ordem-servico-por-servico/
• Pessoa
  • GET /api/pessoa/{cpf-cnpj}
• Leitura e faturas
  • GET /api/leitura/ultima-leitura
  • GET /api/leitura/historico-ultimas-faturas
• 4. Modelos de dados
• 5. Códigos HTTP e erros
• 6. Exemplos de integração

2. Autenticação

Todos os endpoints, exceto o de autenticação, exigem um token de acesso enviado no header Authorization:

Authorization: Bearer <token>

O token é obtido em GET /auth/login-token/{cpfcnpj}/{senha}, com as credenciais fornecidas pela contratante. A resposta informa, no campo duration, a validade do token em segundos. Após esse prazo é necessário autenticar novamente — não existe endpoint de renovação.

2.1. Permissões

Cada credencial recebe um conjunto de permissões que define quais grupos de endpoints ela pode consumir. A resposta da autenticação informa as permissões concedidas:

Consumir um endpoint sem a permissão correspondente resulta em 403 Forbidden. Solicite à contratante a liberação das permissões necessárias à sua integração.

3. Endpoints

GET /auth/login-token/{cpfcnpj}/{senha} SEM AUTENTICAÇÃO

Finalidade: autenticar a credencial e obter o token de acesso usado nos demais endpoints.

Headers: nenhum obrigatório.

Parâmetros de path:

Exemplo de requisição:

GET /auth/login-token/12345678909/S3nh4%40Exemplo
Host: {host-da-api}
Accept: application/json

Resposta de sucesso (200): Autenticacao

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "duration": 1200,
  "user": {
    "nome": "INTEGRADOR EXEMPLO",
    "acessarResourceDebitoApi": true,
    "acessarResourceHidrometroApi": false,
    "acessarResourceLeituraApi": false
  }
}

Resposta de erro (401):

{
  "status": 401,
  "message": "usuário ou senha inválidos"
}

Códigos HTTP:

Consulta de parcelas em aberto, emissão da guia de arrecadação (DAM) e registro da baixa de pagamento. Requer a permissão acessarResourceDebitoApi e o header Authorization em todas as requisições.

GET /api/debito/saneamento-pessoa/{cpf} DÉBITO

Finalidade: listar as parcelas em aberto de todas as unidades consumidoras vinculadas a um CPF/CNPJ.

Headers:

Parâmetros de path:

Observações para integração:

• Parcelas de cota única já vencidas não são retornadas.
• Guarde os objetos recebidos sem alterá-los: eles são o corpo esperado por /api/debito/gerar e /api/debito/imprimir.

Exemplo de requisição:

GET /api/debito/saneamento-pessoa/12345678909
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

Resposta de sucesso (200): Array<Parcela>

[
  {
    "idPessoa": 45871,
    "idCadastro": 10233,
    "idParcela": 998877,
    "idDivida": 12,
    "idCalculo": 776655,
    "idValorDivida": 554433,
    "idOpcaoPagamento": 3,
    "idConfiguracaoAcrescimo": 7,
    "cadastro": "123456",
    "enderecoCadastro": "RUA DAS FLORES, 100 - CENTRO",
    "nomeOrRazaoSocial": "MARIA DA SILVA",
    "tipoCadastro": "UNIDADE_CONSUMIDORA",
    "divida": "FATURA DE SANEAMENTO",
    "parcela": "1/1",
    "referencia": "08/2026",
    "exercicio": 2026,
    "vencimento": "2026-09-10",
    "situacao": "EM_ABERTO",
    "tipoCalculo": "FATURA_SANEAMENTO",
    "ordemApresentacao": 1,
    "cotaUnica": false,
    "dividaAtiva": false,
    "dividaAtivaAjuizada": false,
    "bloqueiaImpressao": false,
    "quantidadeDamImpresso": 1,
    "sd": 0,
    "valorOriginal": 87.45,
    "valorCorrecao": 0.00,
    "valorJuros": 0.00,
    "valorMulta": 0.00,
    "valorHonorarios": 0.00,
    "valorDesconto": 0.00,
    "valorImposto": 0.00,
    "valorTaxa": 0.00,
    "valorPago": 0.00,
    "total": 87.45
  }
]

Códigos HTTP:

GET /api/debito/saneamento-unidade/{numeroUnidade} DÉBITO

Finalidade: listar as parcelas em aberto de uma unidade consumidora específica.

Headers: Authorization: Bearer <token>

Parâmetros de path:

Observações para integração:

• Parcelas de cota única já vencidas não são retornadas.
• O campo nomeOrRazaoSocial não é preenchido neste endpoint. Para obter o nome do titular, use GET /api/pessoa/{cpf-cnpj}.

Exemplo de requisição:

GET /api/debito/saneamento-unidade/123456
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

Resposta de sucesso (200): Array<Parcela> — mesma estrutura de /saneamento-pessoa.

Códigos HTTP:

GET /api/debito/saneamento-parcela/{idParcela} DÉBITO

Finalidade: consultar os dados atualizados de uma única parcela.

Headers: Authorization: Bearer <token>

Parâmetros de path:

Exemplo de requisição:

GET /api/debito/saneamento-parcela/998877
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

Resposta de sucesso (200): Parcela (objeto único). O campo nomeOrRazaoSocial vem vazio.

Códigos HTTP:

POST /api/debito/gerar DÉBITO

Finalidade: emitir a guia de arrecadação (DAM) das parcelas informadas e retornar seus dados em JSON — código de barras, PIX copia-e-cola, valores e vencimento.

Headers:

Body: SolicitacaoGuia

Campos da parcela considerados na emissão: idPessoa, idCadastro, idParcela, idDivida, idCalculo, vencimento, ordemApresentacao, tipoCalculo, referencia, sd, valorImposto, valorJuros, valorMulta, valorOriginal, valorPago, valorTaxa, valorCorrecao, valorHonorarios, valorDesconto, cadastro, enderecoCadastro, divida, parcela, situacao e cotaUnica.

Observações para integração:

• Com uma única parcela, é emitida uma guia individual.
• Com mais de uma parcela, é emitida uma guia agrupada e as parcelas marcadas com cotaUnica = true são desconsideradas. Por isso o campo cotaUnica deve sempre ser enviado.
• Enviar o corpo vazio, sem parcelas ou com a lista vazia retorna 204 No Content.

Exemplo de requisição:

POST /api/debito/gerar
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{
  "parcelas": [
    {
      "idPessoa": 45871,
      "idCadastro": 10233,
      "idParcela": 998877,
      "idDivida": 12,
      "idCalculo": 776655,
      "vencimento": "2026-09-10",
      "ordemApresentacao": 1,
      "tipoCalculo": "FATURA_SANEAMENTO",
      "referencia": "08/2026",
      "sd": 0,
      "valorImposto": 0.00,
      "valorJuros": 0.00,
      "valorMulta": 0.00,
      "valorOriginal": 87.45,
      "valorPago": 0.00,
      "valorTaxa": 0.00,
      "valorCorrecao": 0.00,
      "valorHonorarios": 0.00,
      "valorDesconto": 0.00,
      "cadastro": "123456",
      "enderecoCadastro": "RUA DAS FLORES, 100 - CENTRO",
      "divida": "FATURA DE SANEAMENTO",
      "parcela": "1/1",
      "situacao": "EM_ABERTO",
      "cotaUnica": false
    }
  ]
}

Resposta de sucesso (200): Array<DAM>

[
  {
    "id": 445566,
    "numeroDAM": "2026000445566",
    "numero": 445566,
    "exercicio": 2026,
    "codigoBarras": "81660000000-8 87450012026-1 09100000123-4 45600000001-2",
    "qrCodePIX": "00020126580014BR.GOV.BCB.PIX...6304ABCD",
    "emissao": "2026-09-03",
    "vencimento": "2026-09-10",
    "valorOriginal": 87.45,
    "juros": 0.00,
    "multa": 0.00,
    "honorarios": 0.00,
    "correcaoMonetaria": 0.00,
    "desconto": 0.00,
    "total": 87.45,
    "situacao": "EM_ABERTO",
    "tipo": "NORMAL"
  }
]

Resposta de erro (403):

{
  "status": 403,
  "message": "Foram encontrado(s) débito(s) com a situação Paga!"
}

Códigos HTTP:

POST /api/debito/imprimir DÉBITO

Finalidade: emitir a guia de arrecadação (DAM) das parcelas informadas e retornar o PDF pronto para impressão.

Headers:

Body: SolicitacaoGuia — idêntico ao de /api/debito/gerar.

Observações para integração:

• Com mais de uma parcela, é impressa uma guia agrupada e as parcelas de cota única são desconsideradas.
• Enviar o corpo vazio, sem parcelas ou com a lista vazia retorna 204 No Content.
• A resposta de sucesso é binária. Não tente interpretá-la como JSON quando o código for 200.

Exemplo de requisição:

POST /api/debito/imprimir
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{ "parcelas": [ { ...mesma estrutura de /api/debito/gerar... } ] }

Resposta de sucesso (200):

O corpo da resposta é o binário do PDF.

Códigos HTTP:

GET /api/debito/consultar-parcela-por-dam/{idDam} DÉBITO

Finalidade: consultar as parcelas vinculadas a uma guia e a situação atual de cada uma. Use para confirmar, após o registro da baixa, se o pagamento foi efetivado.

Headers: Authorization: Bearer <token>

Parâmetros de path:

Exemplo de requisição:

GET /api/debito/consultar-parcela-por-dam/445566
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

Resposta de sucesso (200): Array<SituacaoParcela>

[
  {
    "id": 998877,
    "situacaoAtual": "PAGO"
  }
]

Códigos HTTP:

POST /api/debito/baixar-pagamento/{codigoBarras}/{dataPagamento}/{valorPago}/{cnpjArrecadador}/{tipoPagamento} DÉBITO

Finalidade: registrar a baixa (pagamento) de uma guia de arrecadação.

Headers: Authorization: Bearer <token>

Parâmetros de path:

Exemplo de requisição:

POST /api/debito/baixar-pagamento/816600000008874500120261091000001234456000000012/03-09-2026/87.45/11222333000181/1
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Resposta de sucesso: 200 OK, sem corpo.

Respostas de erro (403):

{
  "status": 403,
  "message": "Débito não encontrado!"
}

{
  "status": 403,
  "message": "Padrão dataPagamento inválido, deve ser informado com padrão: dd-MM-yyyy"
}

Códigos HTTP:

Registro de instalação e troca de hidrômetro e consultas de apoio. Requer a permissão acessarResourceHidrometroApi.

Formato de resposta: todos os endpoints deste módulo respondem com o envelope RespostaHidrometro. Quando a lista erros vem preenchida, o código HTTP é 400. Os valores de errosCodigo estão descritos em Códigos de erro do módulo Hidrômetro.

POST /api/hidrometro/ordem-servico-trocahd-completa/ HIDRÔMETRO

Finalidade: registrar, em uma única chamada, a troca de hidrômetro de uma unidade consumidora: retirada do hidrômetro atual, instalação do novo e leituras de ambos.

Headers:

Body: TrocaHidrometro

Exemplo de requisição:

POST /api/hidrometro/ordem-servico-trocahd-completa/
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{
  "numeroUnidadeConsumidora": 123456,
  "matriculaFuncionarioAbertura": "1234",
  "observacaoTexto": "Troca para telemetria",
  "matriculaFuncionarioExecucao": "311",
  "dataRetiradaHD": "05/06/2026",
  "dataInstalacaoHD": "05/06/2026",
  "leituraAtualRetirada": 1,
  "leituraAtualInstalacao": 2,
  "numeroHidrometroRetirada": "Y15L890783",
  "parecerTexto": "Substituição necessária",
  "hidrometroInstalado": {
    "numero": "Y15L8907831",
    "diametro": null,
    "vazao": null,
    "codigoRadioTelemetria": null,
    "leituraPorTelemetria": true
  }
}

Resposta de sucesso (200): RespostaHidrometro com result do tipo Integer (número da ordem de serviço gerada).

{
  "result": 1001,
  "mensagem": "Processado com sucesso",
  "erros": [],
  "errosCodigo": []
}

Resposta de erro (400) — erros possíveis neste endpoint:

{
  "result": null,
  "mensagem": "Erro ao processar a requisição",
  "erros": [
    "Já existe uma ordem de serviço com os seguintes filtros: unidade consumidora e hidrômetro instalação",
    "Não é permitida a troca de hidrômetro. A unidade consumidora está vinculada a uma remessa de leitura não concluída",
    "Funcionário não encontrado para a matrícula informada",
    "Leitura anterior não encontrada com os seguintes filtros: unidade consumidora e data de retirada",
    "Não é permitida a conclusão da troca de hidrômetro, pois a última leitura indica que o hidrômetro atual é igual ao novo",
    "Unidade consumidora não encontrada para o número informado",
    "Serviço de troca de hidrômetro não encontrado",
    "Padrão data inválido, deve ser informado com padrão: dd/MM/yyyy",
    "Já existe uma ordem de serviço aberta com os seguintes filtros: unidade consumidora e serviço",
    "JSON inválido, verifique se todos os campos obrigatórios estão informados",
    "Leitura de retirada inválida, leitura de retirada deve ser maior que a leitura anterior"
  ],
  "errosCodigo": [2, 3, 4, 5, 6, 7, 8, 9, 11, 13, 14]
}

Resposta de erro (400) — requisição malformada:

{
  "result": null,
  "mensagem": "Erro ao processar a requisição",
  "erros": [
    "Erro inesperado ao processar a requisição, verifique se todos os campos obrigatórios estão informados"
  ],
  "errosCodigo": []
}

Códigos HTTP:

POST /api/hidrometro/ordem-servico-abertura-completa/ HIDRÔMETRO

Finalidade: registrar a instalação de hidrômetro em uma unidade consumidora que ainda não possui hidrômetro. Não há dados de retirada.

Headers:

Body: InstalacaoHidrometro

Exemplo de requisição:

POST /api/hidrometro/ordem-servico-abertura-completa/
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{
  "numeroUnidadeConsumidora": 123456,
  "matriculaFuncionarioAbertura": "1234",
  "observacaoTexto": "Instalação de hidrômetro",
  "matriculaFuncionarioExecucao": "311",
  "dataInstalacaoHD": "05/06/2026",
  "leituraAtualInstalacao": 2,
  "parecerTexto": "Instalação concluída",
  "hidrometroInstalado": {
    "numero": "Y15L8907831",
    "diametro": null,
    "vazao": null,
    "codigoRadioTelemetria": null,
    "leituraPorTelemetria": true
  }
}

Resposta de sucesso (200): RespostaHidrometro com result do tipo Integer (número da ordem de serviço gerada).

{
  "result": 1001,
  "mensagem": "Processado com sucesso",
  "erros": [],
  "errosCodigo": []
}

Resposta de erro (400) — erros possíveis neste endpoint:

{
  "result": null,
  "mensagem": "Erro ao processar a requisição",
  "erros": [
    "Já existe uma ordem de serviço com os seguintes filtros: unidade consumidora e hidrômetro instalação",
    "Não é permitida a troca de hidrômetro. A unidade consumidora está vinculada a uma remessa de leitura não concluída",
    "Funcionário não encontrado para a matrícula informada",
    "Não é permitida a conclusão da troca de hidrômetro, pois a última leitura indica que o hidrômetro atual é igual ao novo",
    "Unidade consumidora não encontrada para o número informado",
    "Padrão data inválido, deve ser informado com padrão: dd/MM/yyyy",
    "Serviço de abertura não encontrado no sistema",
    "Já existe uma ordem de serviço aberta com os seguintes filtros: unidade consumidora e serviço",
    "JSON inválido, verifique se todos os campos obrigatórios estão informados"
  ],
  "errosCodigo": [2, 3, 4, 6, 7, 9, 10, 11, 13]
}

Códigos HTTP:

GET /api/hidrometro/has-remessa-leitura-andamento/{numeroUnidade}/ HIDRÔMETRO

Finalidade: verificar se a unidade consumidora está em processo de leitura em andamento. Nessa condição a troca de hidrômetro é recusada (erro 3), portanto use esta consulta como verificação prévia.

Headers: Authorization: Bearer <token>

Parâmetros de path:

Exemplo de requisição:

GET /api/hidrometro/has-remessa-leitura-andamento/123456/
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

Resposta de sucesso (200): RespostaHidrometro com result do tipo Boolean. true indica que há leitura em andamento e a troca não pode ser realizada.

{
  "result": true,
  "mensagem": "Processado com sucesso",
  "erros": [],
  "errosCodigo": []
}

Resposta de erro (400):

{
  "result": null,
  "mensagem": "Erro ao processar a requisição",
  "erros": [
    "Unidade consumidora não encontrada para o número informado"
  ],
  "errosCodigo": [7]
}

Códigos HTTP:

GET /api/hidrometro/rotas-em-remessa-nao-concluida/ HIDRÔMETRO

Finalidade: listar as rotas de leitura que estão em andamento (não concluídas).

Headers: Authorization: Bearer <token>

Parâmetros: nenhum.

Exemplo de requisição:

GET /api/hidrometro/rotas-em-remessa-nao-concluida/
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

Resposta de sucesso (200): RespostaHidrometro com result do tipo Array<Rota>.

{
  "result": [
    {
      "codigo": 10,
      "descricao": "ROTA 10"
    },
    {
      "codigo": 90,
      "descricao": "ROTA 90"
    }
  ],
  "mensagem": "Processado com sucesso",
  "erros": [],
  "errosCodigo": []
}

Códigos HTTP:

Abertura de ordens de serviço por tipo de serviço e consultas de apoio. Requer a permissão acessarResourceHidrometroApi. As rotas deste módulo também terminam com /.

GET /api/ordem-servico/unidades-por-cpf/{cpfCnpj}/ HIDRÔMETRO

Finalidade: listar as unidades consumidoras vinculadas a um CPF/CNPJ, com o endereço de cada uma.

Headers: Authorization: Bearer <token>

Parâmetros de path:

Exemplo de requisição:

GET /api/ordem-servico/unidades-por-cpf/12345678909/
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

Resposta de sucesso (200): Array<UnidadeConsumidora>

[
  {
    "numero": 123456,
    "enderecoCompleto": "RUA DAS FLORES, 100 - CENTRO"
  },
  {
    "numero": 123457,
    "enderecoCompleto": "AVENIDA PRINCIPAL, 2500 - JARDIM ALVORADA"
  }
]

Códigos HTTP:

GET /api/ordem-servico/servicos-disponivel/ HIDRÔMETRO

Finalidade: listar os serviços disponíveis para abertura de ordem de serviço. O campo id retornado é o valor a informar em servicoId na abertura da ordem de serviço.

Headers: Authorization: Bearer <token>

Parâmetros: nenhum.

Exemplo de requisição:

GET /api/ordem-servico/servicos-disponivel/
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

Resposta de sucesso (200): Array<Servico>

[
  {
    "id": 5,
    "descricao": "RELIGAÇÃO DE ÁGUA"
  },
  {
    "id": 8,
    "descricao": "VERIFICAÇÃO DE VAZAMENTO"
  }
]

Códigos HTTP:

POST /api/ordem-servico/ordem-servico-por-servico/ HIDRÔMETRO

Finalidade: abrir uma ordem de serviço para a unidade consumidora e o serviço informados.

Headers:

Body: SolicitacaoOrdemServico

Exemplo de requisição:

POST /api/ordem-servico/ordem-servico-por-servico/
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{
  "servicoId": 5,
  "unidade": 123456,
  "observacao": "Solicitação de religação feita pelo titular"
}

Resposta de sucesso (200): RespostaOrdemServico

{
  "numeroOS": 1042
}

Códigos HTTP:

GET /api/pessoa/{cpf-cnpj} DÉBITOHIDRÔMETRO

Finalidade: consultar os dados cadastrais de uma pessoa física ou jurídica pelo CPF/CNPJ. Disponível para credenciais com a permissão de débito ou de hidrômetro.

Headers: Authorization: Bearer <token>

Parâmetros de path:

Exemplo de requisição:

GET /api/pessoa/12345678909
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

Resposta de sucesso (200) — pessoa física: Pessoa

{
  "id": 45871,
  "fisica": {
    "cpf": "12345678909",
    "nome": "MARIA DA SILVA",
    "sexo": "FEMININO",
    "email": "maria@exemplo.com.br",
    "estadoCivil": "CASADO",
    "racaCor": "BRANCA",
    "doadorSanguineo": false,
    "mae": "JOANA DA SILVA",
    "pai": "JOSE DA SILVA",
    "nacionalidade": "BRASILEIRA",
    "nivelEsolaridade": {
      "descricao": "ENSINO MÉDIO COMPLETO"
    },
    "profissao": {
      "descricao": "COMERCIANTE"
    },
    "naturalidade": {
      "nome": "NOME DA CIDADE",
      "uf": {
        "nome": "NOME DO ESTADO"
      }
    }
  }
}

Resposta de sucesso (200) — pessoa jurídica:

{
  "id": 45872,
  "juridica": {
    "cnpj": "11222333000181",
    "razaoSocial": "EMPRESA EXEMPLO LTDA",
    "nomeFantasia": "EXEMPLO",
    "inscricaoEstadual": "1234567890",
    "tipoEmpresa": "LTDA"
  }
}

Códigos HTTP:

Consulta da fatura corrente e do histórico de faturas de uma unidade consumidora. Requer a permissão acessarResourceLeituraApi. Os parâmetros são enviados por query string.

Parâmetros de query (comuns aos dois endpoints)

Validações (iguais nos dois endpoints):

Observações para integração:

• A matricula e o documento devem pertencer à mesma unidade consumidora. Se o documento não corresponder ao titular da matrícula informada, a resposta é 204 No Content.
• O código de barras é retornado somente com dígitos, sem máscara.
• Os resultados são ordenados da competência mais recente para a mais antiga.

Valores de StatusPagamento

GET /api/leitura/ultima-leitura LEITURA

Finalidade: obter o resumo da última fatura da unidade consumidora.

Headers: Authorization: Bearer <token>

Parâmetros de query: matricula e documento — ver Parâmetros de query.

Exemplo de requisição:

GET /api/leitura/ultima-leitura?matricula=123456&documento=12345678909
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

Resposta de sucesso (200): UltimaLeitura (objeto único)

{
  "MesAnoReferencial": "08/2026",
  "StatusPagamento": 1,
  "ValorTotal": 87.45,
  "CodigoDeBarras": "816600000008874500120261091000001234456000000012",
  "CopiaEColaQRCode": "00020126580014BR.GOV.BCB.PIX...6304ABCD",
  "Vencimento": "2026-09-10T23:59:59",
  "Consumo": 14
}

Resposta de erro (400):

{
  "status": 400,
  "message": "matricula é obrigatória"
}

Códigos HTTP:

GET /api/leitura/historico-ultimas-faturas LEITURA

Finalidade: obter as até 8 últimas faturas da unidade consumidora (incluindo a corrente), da mais recente para a mais antiga.

Headers: Authorization: Bearer <token>

Parâmetros de query: matricula e documento — ver Parâmetros de query.

Exemplo de requisição:

GET /api/leitura/historico-ultimas-faturas?matricula=123456&documento=12345678909
Host: {host-da-api}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Accept: application/json

Resposta de sucesso (200): Array<FaturaHistorico>

[
  {
    "MesAnoReferencia": "08/2026",
    "StatusPagamento": 1,
    "Vencimento": "2026-09-10",
    "Valor": 87.45,
    "CodigoBarras": "816600000008874500120261091000001234456000000012",
    "DataPagamento": "",
    "QrCode": "00020126580014BR.GOV.BCB.PIX...6304ABCD"
  },
  {
    "MesAnoReferencia": "07/2026",
    "StatusPagamento": 3,
    "Vencimento": "2026-08-10",
    "Valor": 79.90,
    "CodigoBarras": "816600000007990000120261081000001234456000000012",
    "DataPagamento": "2026-08-08",
    "QrCode": ""
  }
]

Resposta de erro (400):

{
  "status": 400,
  "message": "documento é obrigatório"
}

Códigos HTTP:

4. Modelos de dados

Autenticacao

Usuario

SolicitacaoGuia

Parcela

DAM (guia de arrecadação)

SituacaoParcela

TrocaHidrometro

InstalacaoHidrometro

Hidrometro

RespostaHidrometro

Rota

UnidadeConsumidora

Servico

SolicitacaoOrdemServico

RespostaOrdemServico

UltimaLeitura

FaturaHistorico

Pessoa

DadosPessoaFisica

DadosPessoaJuridica

5. Códigos HTTP e erros

5.1. Códigos HTTP utilizados

5.2. Formato padrão de erro

Usado pelos módulos Autenticação, Débitos e Leitura:

{
  "status": 403,
  "message": "Débito não encontrado!"
}

5.3. Formato de erro do módulo Hidrômetro

Os endpoints de Hidrômetro usam o envelope RespostaHidrometro, com as mensagens em erros e os códigos correspondentes em errosCodigo:

{
  "result": null,
  "mensagem": "Erro ao processar a requisição",
  "erros": [
    "Unidade consumidora não encontrada para o número informado"
  ],
  "errosCodigo": [7]
}

5.4. Erros do módulo Ordem de serviço

Os endpoints de Ordem de serviço retornam 400 Bad Request sem corpo. Não há detalhamento do erro na resposta; valide os dados antes do envio e confira os identificadores obtidos nas consultas de apoio.

5.5. Códigos de erro do módulo Hidrômetro

Valores possíveis no campo errosCodigo:

6. Exemplos de integração

6.1. Consulta e pagamento de débito

1. GET /auth/login-token/{cpfcnpj}/{senha} — obtenha o token.
2. GET /api/debito/saneamento-pessoa/{cpf} ou GET /api/debito/saneamento-unidade/{numeroUnidade} — liste as parcelas em aberto.
3. Envie as parcelas escolhidas, sem alterá-las, em POST /api/debito/gerar (dados da guia em JSON) ou POST /api/debito/imprimir (PDF).
4. Após a arrecadação, registre a baixa em POST /api/debito/baixar-pagamento/..., usando o codigoBarras retornado.
5. Confirme o resultado em GET /api/debito/consultar-parcela-por-dam/{idDam}, usando o id da guia.

6.2. Troca de hidrômetro

1. GET /auth/login-token/{cpfcnpj}/{senha} — obtenha o token.
2. GET /api/ordem-servico/unidades-por-cpf/{cpfCnpj}/ — localize a unidade consumidora do titular.
3. GET /api/hidrometro/has-remessa-leitura-andamento/{numeroUnidade}/ — confirme que não há leitura em andamento (result = true impede a troca).
4. POST /api/hidrometro/ordem-servico-trocahd-completa/ — registre a troca. Para uma primeira instalação, use /ordem-servico-abertura-completa/.

6.3. Abertura de ordem de serviço

1. GET /auth/login-token/{cpfcnpj}/{senha} — obtenha o token.
2. GET /api/ordem-servico/unidades-por-cpf/{cpfCnpj}/ — obtenha o numero da unidade.
3. GET /api/ordem-servico/servicos-disponivel/ — obtenha o id do serviço desejado.
4. POST /api/ordem-servico/ordem-servico-por-servico/ — abra a ordem de serviço informando servicoId e unidade.

6.4. Consulta de faturas

1. GET /auth/login-token/{cpfcnpj}/{senha} — obtenha o token.
2. GET /api/leitura/ultima-leitura — resumo da fatura mais recente, com código de barras e PIX copia-e-cola.
3. GET /api/leitura/historico-ultimas-faturas — histórico das últimas faturas, com a data de pagamento das já quitadas.