Sunne Api Gateway (1.0.0)

Download OpenAPI specification:

Contato Sunne: contato@sunne.com.br URL: https://sunne.com.br License: Proprietary

Sunne API Gateway

API para gerenciamento de clientes, unidades consumidoras, usinas de energia solar e faturas.

Autenticação

Esta API utiliza autenticação via API Key. Inclua o header apikey em todas as requisições.

Base URL

https://client-api.sunne.com.br/

Status Codes

200 - Sucesso
400 - Dados inválidos
404 - Recurso não encontrado
500 - Erro interno do servidor

Client

List Clients

Authorizations:

apiKey

query Parameters

page	string Example: page=3
limit	string Example: limit=100
name	string Example: name=Sunne
cpfCnpj	string Example: cpfCnpj=00.000.000/0001-00

Get Client by code

Authorizations:

apiKey

path Parameters

ClientCode

required

string

Example: a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6

Código do cliente

Responses

Response samples

200
404

Content type

application/json

{"address": {"cep": "40020-000",
"city": "Salvador",
"complement": null,
"district": "Centro Histórico",
"latitude": -12.9718,
"logradouro": null,
"longitude": -38.5011,
"number": "s/n",
"state": "BA",
"street": "Praça Thomé de Souza"
},
"code": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6",
"corporateName": "EMPRESA EXEMPLO LTDA",
"cpfCnpj": "00.000.000/0001-00",
"email": "cliente@exemplo.com.br",
"inclusionDate": "2022-05-27T15:49:22",
"modifyDate": "2022-05-27T21:49:23.000+00:00",
"name": "Maria da Silva"
}

Update Client

Authorizations:

apiKey

path Parameters

ClientCode

required

string

Example: a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6

Código do cliente

Request Body schema: application/json

corporateName	string
cpfCnpj	string
email	string
name	string

Responses

Request samples

Payload

Content type

application/json

{"corporateName": "EMPRESA EXEMPLO LTDA",
"cpfCnpj": "00.000.000/0001-00",
"email": "cliente@exemplo.com.br",
"name": "Maria da Silva"
}

Add Clients

Authorizations:

apiKey

Request Body schema: application/json

	object
corporateName	string
cpfCnpj	string
email	string
name	string

Responses

Request samples

Payload

Content type

application/json

{"address": {"cep": "30140-010",
"city": "Belo Horizonte",
"complement": null,
"district": "Funcionários",
"number": "s/n",
"state": "MG",
"street": "Praça da Liberdade"
},
"corporateName": "EMPRESA EXEMPLO LTDA",
"cpfCnpj": "00.000.000/0001-00",
"email": "cliente@exemplo.com.br",
"name": "João da Silva"
}

Consumer Unit

List recently consumer unit

list recently registered or updated consumer units

Authorizations:

apiKey

query Parameters

startDate

string

Example: startDate=2023-11-01T00:39:46

List consumer unit

Authorizations:

apiKey

query Parameters

page	string Example: page=3
limit	string Example: limit=100
name	string Example: name=Sunne
cpfCnpj	string Example: cpfCnpj=00.000.000/0001-00
numeroDeConcessao	string Example: numeroDeConcessao=
powerPlantId	string Example: powerPlantId=165

Add consumer unit

Authorizations:

apiKey

Request Body schema: application/json

accountNumber	string
	object
clientCode	string
connectedAt	string
cpfCnpj	string
createInvoiceSunneAutomatically	boolean
createPayment	boolean
discountRate	number
downloadDealership	boolean
instalationType	string
name	string
nameAccountOwner	string
observations	string
payDealershipBill	boolean
percentage	number
phone	string
plan	string
powerPlantCode	string
responsable	string
unifiedInvoice	boolean

Responses

Request samples

Payload

Content type

application/json

{"accountNumber": "123456789",
"address": {"cep": "01001-000",
"city": "São Paulo",
"complement": null,
"district": "Sé",
"number": "s/n",
"state": "SP",
"street": "Praça da Sé"
},
"clientCode": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6",
"connectedAt": "2023-12-01",
"cpfCnpj": "00.000.000/0001-00",
"createInvoiceSunneAutomatically": false,
"createPayment": false,
"discountRate": 0.1,
"downloadDealership": false,
"instalationType": "BIFASICO",
"name": "João da Silva UC2",
"nameAccountOwner": "João da Silva",
"observations": "Observações",
"payDealershipBill": false,
"percentage": 0.01,
"phone": "(11) 99999-9999",
"plan": "BASIC",
"powerPlantCode": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6",
"responsable": "Maria do Rosário",
"unifiedInvoice": false
}

Update consumer unit

Authorizations:

apiKey

path Parameters

Code

required

string

Example: a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6

Código da unidade consumidora

Request Body schema: application/json

accountNumber	string
	object
clientCode	string
connectedAt	string
cpfCnpj	string
createInvoiceSunneAutomatically	boolean
createPayment	boolean
discountRate	number
downloadDealership	boolean
instalationType	string
name	string
nameAccountOwner	string
observations	string
payDealershipBill	boolean
percentage	number
phone	string
plan	string
powerPlantCode	string
responsable	string
unifiedInvoice	boolean

Responses

Request samples

Payload

Content type

application/json

{"accountNumber": "123456789",
"address": {"cep": "70150-903",
"city": "Brasília",
"complement": null,
"district": "Zona Cívico-Administrativa",
"number": "Lote 2",
"state": "DF",
"street": "Praça dos Três Poderes"
},
"clientCode": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6",
"connectedAt": "2023-12-01",
"cpfCnpj": "00.000.000/0001-00",
"createInvoiceSunneAutomatically": false,
"createPayment": false,
"discountRate": 0.1,
"downloadDealership": false,
"instalationType": "BIFASICO",
"name": "João da Silva UC2",
"nameAccountOwner": "João da Silva",
"observations": "Observações",
"payDealershipBill": false,
"percentage": 0.01,
"phone": "(54) 99999-9999",
"plan": "BASIC",
"powerPlantCode": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6",
"responsable": "Ricardo da Silva",
"unifiedInvoice": false
}

PowerPlant

List PowerPlant

Authorizations:

apiKey

Responses

Response samples

200

Content type

application/json

[{"address": {"cep": "20021-140",
"city": "Rio de Janeiro",
"complement": null,
"district": "Centro",
"latitude": -22.9068,
"logradouro": null,
"longitude": -43.1729,
"number": "s/n",
"state": "RJ",
"street": "Praça Quinze de Novembro"
},
"code": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6",
"connectionModel": "SHARED",
"dealerShip": "CONCESSIONARIA_EXEMPLO",
"documents": [ ],
"generatedEnergy": 16000,
"inclusionDate": null,
"initialOperationDate": "2020-10-01",
"name": "Usina Exemplo",
"potency": 133,
"ratedPotency": 108
},
{"address": {"cep": "70150-903",
"city": "Brasília",
"complement": null,
"district": "Zona Cívico-Administrativa",
"latitude": -15.7989,
"logradouro": null,
"longitude": -47.8645,
"number": "Lote 2",
"state": "DF",
"street": "Praça dos Três Poderes"
},
"code": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6",
"connectionModel": "SHARED",
"dealerShip": "CONCESSIONARIA_EXEMPLO",
"documents": [ ],
"generatedEnergy": 11000,
"inclusionDate": null,
"initialOperationDate": null,
"name": "Usina Exemplo 2",
"potency": 96,
"ratedPotency": 75
}
]

Invoices

List Invoices

Authorizations:

apiKey

query Parameters

page	string Example: page=1
limit	string Example: limit=15
numeroDoCliente	string Example: numeroDoCliente=123456789 Filtro para busca pelo código da UC
dataCompetencia	string Example: dataCompetencia=12/2023 Filtro para busca pela data de competência

Responses

Response samples

200

Content type

application/json

{"data": [{"_id": "6585de7bb181e300320b2882",
"codigoBoleto": "12345678901234567890123456789012345679801234567",
"codigoPix": "*BR.GOV.BCB.PIX2564api.rendimento.com.br/q/v2/cobv/*******",
"creditosCompensados": -24.98399999999984,
"dataCompetencia": "12/2023",
"dataEmissaoConcessionaria": "22/12/2023",
"dataEmissaoSunne": "22/12/2023",
"dataVencimento": "12/01/2024",
"economiaMes": 62.70297355761602,
"economiaTotal": 453.005382142616,
"numeroDoCliente": "12345678",
"status": "pending",
"tarifakWh": 0.8823185,
"tarifakWhCompensavel": 2.37500468,
"titularDaConta": "SUNNE SISTEMA DE WEB LTDA",
"totalAPagar": 355.316850159824
}
],
"limit": 15,
"page": 1,
"total": 1
}

List recently invoices

list recently registered or updated invoices

Authorizations:

apiKey

query Parameters

startDate	string Example: startDate=2023-11-01T00:39:46 Data para inicio da busca dos registros (valor padrão 24 horas)
date	string Example: date=2023-12-20 Data para inicio da busca dos registros (valor padrão 24 horas)

Responses

Response samples

200

Content type

application/json

{"data": [{"_id": "6585de7bb181e300320b2882",
"codigoBoleto": "12345678901234567890123456789012345679801234567",
"codigoPix": "*BR.GOV.BCB.PIX2564api.rendimento.com.br/q/v2/cobv/*******",
"creditosCompensados": -24.98399999999984,
"dataCompetencia": "12/2023",
"dataEmissaoConcessionaria": "22/12/2023",
"dataEmissaoSunne": "22/12/2023",
"dataVencimento": "12/01/2024",
"economiaMes": 62.70297355761602,
"economiaTotal": 453.005382142616,
"numeroDoCliente": "12345678",
"status": "pending",
"tarifakWh": 0.8823185,
"tarifakWhCompensavel": 2.37500468,
"titularDaConta": "SUNNE SISTEMA DE WEB LTDA",
"totalAPagar": 355.316850159824
},
{"_id": "6585cbffb181e300320b2874",
"codigoBoleto": "12345678901234567890123456789012345679801234567",
"codigoPix": "*BR.GOV.BCB.PIX2564api.rendimento.com.br/q/v2/cobv/*******",
"creditosCompensados": 7632.188,
"dataCompetencia": "12/2023",
"dataEmissaoConcessionaria": "20/12/2023",
"dataEmissaoSunne": "22/12/2023",
"dataVencimento": "10/01/2024",
"economiaMes": 1765.5860540954836,
"economiaTotal": 6311.724091283003,
"numeroDoCliente": "12345678",
"status": "pending",
"tarifakWh": 0.88230469,
"tarifakWhCompensavel": 4.75025722,
"titularDaConta": "SUNNE SISTEMA DE WEB LTDA",
"totalAPagar": 15890.274486859356
}
]
}

Get invoice PDF link by id

Authorizations:

apiKey

path Parameters

InvoiceCode

required

string

Example: 6585de7bb181e300320b2882

Código da fatura

Responses

Response samples

200

Content type

application/json

{"url": "https://sunnesaas.s3.us-east-2.amazonaws.com/faturasSunne/12312312313123/current/UC-123123123-DEZEMBRO-2023.pdf"
}

Discount and Charges

Create discount

Creates a new discount for a consumer unit

Authorizations:

apiKey

Request Body schema: application/json

consumerUnitId required	number ID da unidade consumidora
value required	number Valor do desconto em centavos ou em porcentagem (1-100), dependendo do valor de isValueCategoryPercentage
cumulative	boolean Indica se o desconto é cumulativo. Se true, o valor restante será aplicado na próxima fatura. Se false, o desconto será aplicado apenas na fatura atual.
realDiscount	boolean Se true, o desconto é aplicado na cobrança da fatura atual e o valor da economia será acrescido com o valor do desconto. Se false, o desconto é aplicado mas o valor da economia não será acrescido.
description required	string [ 1 .. 50 ] characters
competence required	string^(0[1-9]\|1[0-2])/[0-9]{4}$ Formato MM/YYYY (ex: 07/2025)
isValueCategoryPercentage	boolean Se true, o desconto é aplicado de forma percentual (1-100). Se false, o valor é monetário em centavos.

Responses

Request samples

Payload

Content type

application/json

{"consumerUnitId": 123456,
"value": 10000,
"cumulative": true,
"realDiscount": true,
"description": "Desconto de 10%",
"competence": "07/2025",
"isValueCategoryPercentage": true
}

Response samples

200
400

Content type

application/json

Example

Success

{"success": true,
"id": "64a57acc67208c00130d7c42"
}

Delete discount

Deletes a discount by ID

Authorizations:

apiKey

Request Body schema: application/json

id

required

string

ID do desconto

Responses

Request samples

Payload

Content type

application/json

{"id": "64a57acc67208c00130d7c42"
}

Response samples

200

Content type

application/json

{"deleted": true
}

Create charge

Creates a new charge for a consumer unit

Authorizations:

apiKey

Request Body schema: application/json

consumerUnitId required	number ID da unidade consumidora
value required	number Valor da cobrança em centavos ou em porcentagem (1-100), dependendo do valor de isValueCategoryPercentage
realDiscount	boolean Se true, a cobrança é aplicada na fatura atual e o valor da economia será reduzido. Se false, a cobrança é aplicada mas o valor da economia não será reduzido.
description required	string [ 1 .. 50 ] characters
competence required	string^(0[1-9]\|1[0-2])/[0-9]{4}$ Formato MM/YYYY (ex: 07/2025)
isValueCategoryPercentage	boolean Se true, a cobrança é aplicada de forma percentual (1-100). Se false, o valor é monetário em centavos.

Responses

Request samples

Payload

Content type

application/json

{"consumerUnitId": 123456,
"value": 5000,
"realDiscount": false,
"description": "Taxa administrativa",
"competence": "07/2025",
"isValueCategoryPercentage": false
}

Response samples

200
400

Content type

application/json

Example

Success

{"success": true,
"id": "64a57acc67208c00130d7c42"
}

Delete charge

Deletes a charge by ID

Authorizations:

apiKey

Request Body schema: application/json

id

required

string

ID da cobrança

Responses

Request samples

Payload

Content type

application/json

{"id": "64a57acc67208c00130d7c42"
}

Response samples

200
400

Content type

application/json

Example

Success

{"deleted": true
}

reports

billing report

Authorizations:

apiKey

Request Body schema: application/json

firstDate	string
powerPlants	Array of strings
secondDate	string

Responses

Request samples

Payload

Content type

application/json

{"firstDate": "03-2024",
"powerPlants": ["79fb3d5e-2c90-4713-bd5d-1223132"
],
"secondDate": "04-2024"
}

Response samples

200

Content type

text/plain

[
  {
    "_id": "65f301b5a8d3fc0033aa1050",
    "nomeTipoInstalacao": "TRIFÁSICO",
    "titularDaConta": "SUNNE SISTEMA DE WEB LTDA",
    "numeroDoCliente": "132456798",
    "cpfCnpj": "00.000.000/0001-00",
    "endereco": "Rua Exemplo, 123 - Centro - São Paulo SP 01234-567",
    "mesCompetencia": "Março",
    "dataCompetencia": "03/2024",
    "dataCompetenciaExtenso": "Março 2024",
    "dataLeituraAtualExtenso": "Mar 2024",
    "dataLeituraAtual": "06/03/2024",
    "dataLeituraAnteriorExtenso": "Fev 2024",
    "dataLeituraAnterior": "02/02/2024",
    "dataLeituraFutura": "05/04/2024",
    "dataLeituraFuturaExtenso": "Abr 2024",
    "dataEmissaoConcessionaria": "06/03/2024",
    "dataEmissaoSunne": "14/03/2024",
    "dataVencimento": "22/03/2024",
    "dataVencimentoConcessionaria": "22/03/2024",
    "creditosCompensados": 1342.27,
    "creditoSolarSaldoTotal": 3188.9700000000003,
    "consumoTotalMes": 1496,
    "creditosUtilizados": 1396,
    "totalEncargos": 1627.58,
    "custoDisponibilidade": 0,
    "fixedInstallmentValue": null,
    "tarifakWh": 0.95863974,
    "tarifakWhCompensavel": 0.9345519599999998,
    "tarifaPisCofins": 0.02408778000000006,
    "dealershipBoleto": "12345678901234567890123456789012345679801234567",
    "urlFatura": null,
    "totalAPagar": 1043.7076289279998,
    "valorComPlano": 2671.287628928,
    "valorSemPlano": 2932.2145361599996,
    "economiaMes": 260.92690723199985,
    "economiaTotal": 4801.266234674,
    "porcentagemEconomiaMesAtual": 20,
    "valorCreditoSemDesconto": 1304.6345361599997,
    "valorCreditoComDesconto": 1043.7076289279998,
    "payDealershipBill": false,
    "codigoPagamento": "2aPL13",
    "codigoBoleto": "12345678901234567890123456789012345679801234567",
    "status": "paid",
    "qrcodeId": "p7vg73dasd",
    "qrcodeValue": "*BR.GOV.BCB.PIX2564api.rendimento.com.br/q/v2/cobv/*******",
    "numberPagcerto": "123465789",
    "urlUpdatedFatura": "https://sunnesaas.s3.us-east-2.amazonaws.com/current/UC-123456-MARÇO-2024.pdf",
    "urlFaturaSunne": "https://sunnesaas.s3.us-east-2.amazonaws.com/UC-123456-MARÇO-22.03.2024.pdf",
    "dataGeracao": "03-2024",
    "timestamp": 1710424501733,
    "emailHistory": [
      {
        "subject": "Sua Fatura chegou!",
        "date": "2024-03-14T18:07:09.865Z",
        "to": "to@test.com.br",
        "from": "from@test.com.br",
        "flag": "fatura_disponivel",
        "scheduledEmailId": "65f301b640073d1a10946bd0"
      }
    ],
    "dataPagamento": "02/04/2024",
    "totalPago": 1043.71
  },
  {
    "_id": "65f301bca8d3fc0033aa1051",
    "nomeTipoInstalacao": "TRIFÁSICO",
    "titularDaConta": "SUNNE SISTEMA DE WEB LTDA",
    "numeroDoCliente": "123456789",
    "cpfCnpj": "00.000.000/0001-00",
    "endereco": "Av. Exemplo, 456 - Centro - Rio de Janeiro RJ 20000-000",
    "mesCompetencia": "Março",
    "dataCompetencia": "03/2024",
    "dataCompetenciaExtenso": "Março 2024",
    "dataLeituraAtualExtenso": "Mar 2024",
    "dataLeituraAtual": "06/03/2024",
    "dataLeituraAnteriorExtenso": "Fev 2024",
    "dataLeituraAnterior": "02/02/2024",
    "dataLeituraFutura": "03/04/2024",
    "dataLeituraFuturaExtenso": "Abr 2024",
    "dataEmissaoConcessionaria": "06/03/2024",
    "dataEmissaoSunne": "14/03/2024",
    "dataVencimento": "27/03/2024",
    "dataVencimentoConcessionaria": "27/03/2024",
    "creditosCompensados": 1789.6800000000003,
    "creditoSolarSaldoTotal": 4277.26,
    "consumoTotalMes": 2060,
    "creditosUtilizados": 1960,
    "totalEncargos": 186.43,
    "custoDisponibilidade": 0,
    "fixedInstallmentValue": null,
    "tarifakWh": 0.95863974,
    "tarifakWhCompensavel": 0.9345519599999998,
    "tarifaPisCofins": 0.02408778000000006,
    "dealershipBoleto": "12345678901234567890123456789012345679801234567",
    "urlFatura": null,
    "totalAPagar": 1465.3774732799998,
    "valorComPlano": 1651.8074732799998,
    "valorSemPlano": 2018.1518415999997,
    "economiaMes": 366.34436831999983,
    "economiaTotal": 5908.6462538219985,
    "porcentagemEconomiaMesAtual": 20,
    "valorCreditoSemDesconto": 1831.7218415999996,
    "valorCreditoComDesconto": 1465.3774732799998,
    "payDealershipBill": false,
    "codigoPagamento": "8yAkyl",
    "codigoBoleto": "12345678901234567890123456789012345679801234567",
    "status": "paid",
    "qrcodeId": "plkdv11",
    "qrcodeValue": "*BR.GOV.BCB.PIX2564api.rendimento.com.br/q/v2/cobv/*******",
    "numberPagcerto": "12345679",
    "urlUpdatedFatura": "https://sunnesaas.s3.us-east-2.amazonaws.com/current/UC-123-MARÇO-2024.pdf",
    "urlFaturaSunne": "https://sunnesaas.s3.us-east-2.amazonaws.com//UC-123-MARÇO-27.03.2024.pdf",
    "dataGeracao": "03-2024",
    "timestamp": 1710424508870,
    "emailHistory": [
      {
        "subject": "Sua Fatura chegou!",
        "date": "2024-03-14T18:03:32.265Z",
        "to": "to@test.com.br",
        "from": "from@test.com.br",
        "flag": "fatura_disponivel",
        "scheduledEmailId": "65f301be40073d1a10946bd1"
      },
      {
        "subject": "COMUNICADO IMPORTANTE",
        "date": "2024-04-01T18:01:37.075Z",
        "to": "to@test.com.br",
        "from": "from@test.com.br",
        "flag": "fatura_vencida",
        "scheduledEmailId": "6607d502c39654df59670f99"
      }
    ],
    "dataPagamento": "02/04/2024",
    "totalPago": 1465.38
  }
]