Artigo: Atualizações e Alterações nas Rotas da API Pública

Nos últimos dias, nossa API pública passou por diversas mudanças que afetam diretamente o consumo e a estrutura das rotas disponíveis. Embora a documentação já atualizada reflita as novas práticas, algumas diferenças significativas entre o ambiente de produção e o novo padrão implementado foram observadas.

Essas mudanças visam adequar a API às melhores práticas e aprimorar a experiência dos desenvolvedores.

Aqui está uma análise detalhada das mudanças, destacando o antes e o depois das rotas da API.

1. Padronização dos Métodos HTTP

No ambiente anterior de produção, todas as rotas de acesso aos dados utilizavam o método POST, independentemente da operação realizada. Agora, com a atualização, as rotas utilizam o método correto para cada tipo de operação, alinhando-se às práticas RESTful.

Mudança Geral

• Antes (Produção): Todas as rotas utilizavam POST, inclusive para acessos simples.
• Agora (Atualização):
• Rotas de leitura utilizam o método GET.
• Rotas de criação/manipulação permanecem com o método POST.

2. Nova Rota para Payments (Cobranças)

Uma das mudanças mais significativas foi a transição do recurso Billing para Payments/Charges. Com isso, o endpoint ficou mais claro e a rota principal foi simplificada para facilitar o consumo.

Visão geral

• Recurso antigo: Billing
• Recurso novo: Payments/Charges
• Mudança de método/rota:

POST /api/v1/solar/billings → GET /api/v1/solar/payments/charges (listagem)

Endpoints principais

• Listagem (paginada e filtrável)

GET /api/v1/solar/payments/charges

• Verificar / Detalhar cobrança por ID (novo endpoint)

GET /api/v1/solar/payments/charges/{charge_id}

Parâmetro: charge_id (string, obrigatório) — ID único da cobrança

Exemplo de requisição de detalhe:

GET /api/v1/solar/payments/charges/6DKqgxpQEzLPxZVmlzrRa?apikey=12321dadasdasdda

Paginação (cursor-based)

• Paginação baseada em cursor utilizando o campo createdAt como referência.
• Parâmetros de paginação:
• limit — número máximo de registros por requisição (default: 10, máx: 100).
• cursor — valor retornado em nextCursor para buscar a próxima página.
• A resposta inclui nextCursor (string). Use esse valor no parâmetro cursor para a próxima página.
• Quando nextCursor for null, não há mais registros.

Exemplo:

GET /api/v1/solar/payments/charges?limit=10
GET /api/v1/solar/payments/charges?limit=10&cursor=<nextCursor>

Filtros suportados (query params)

Status:

• status (ex.: PAID, PENDING, FAILED)

Datas (exata ou intervalo):

• due_date, due_date_from, due_date_to
• paid_date, paid_date_from, paid_date_to
• created_at, created_at_from, created_at_to

Referência mensal:

• month_reference

Valores (exato ou intervalo):

• value, value_from, value_to

* Outros filtros:

• consumer_unit_number
• utility (ex.: CEMIG)
• city

Paginação:

• limit, cursor

Exemplo de uso:

GET /api/v1/solar/payments/charges?status=PAID&created_at_from=2024-01-01&created_at_to=2024-01-31&limit=100

Campos renomeados

• value → amount
• billing_url → billing_document_url

Campos adicionados (principais)

• customer.id — ID do cliente
• currency — moeda da cobrança (ex.: BRL)
• payment_method_type — tipo do método de pagamento (ex.: BOLETO, CARD)
• billing_document_ref — referência do documento
• description — descrição da cobrança
• providerData — dados do provedor (objeto)
• barCode — código de barras (aplicável a faturas CEMIG via XML)

Exemplo de resposta (listagem simplificada)

{
  "data": [
    {
      "id": "6DKqgxpQEzLPxZVmlzrRa",
      "amount": 123.45,
      "currency": "BRL",
      "status": "PAID",
      "createdAt": "2024-01-15T10:20:30Z",
      "due_date": "2024-01-10",
      "paid_date": "2024-01-12",
      "consumer_unit_number": "1234567890",
      "utility": "CEMIG",
      "city": "Belo Horizonte",
      "customer": {
        "id": "cust_abc123",
        "name": "TESTE REGRAS ENEL",
        "document": "",
        "number": "123123",
        "street": "DT SAO JOSE 00",
        "district": "c",
        "city": "DISTRITO DE SAO JOSE JAGUARUANA",
        "state": "CE",
        "email": null,
        "phone": null
      },
      "billing_document_url": "https://.../document.pdf",
      "payment_method_type": "BOLETO"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTE1VDEwOjIwOjMwWiJ9"
}

Notas rápidas para migração

• Atualize chamadas que usavam POST /api/v1/solar/billings para a nova listagem GET /api/v1/solar/payments/charges.
• Faça o mapeamento dos campos renomeados (value → amount, billing_url → billing_document_url).
• Implemente paginação por pela lógica de cursor (nextCursor).
• Verifique e padronize formato de datas aceitos (RFC3339 vs YYYY-MM-DD) nos seus clientes.

3. Alteração nas Rotas de CRM

Os endpoints de CRM também foram atualizados com a introdução dos métodos corretos. As consultas foram alteradas para GET, alinhando-se à diferenciação entre leitura e criação.

Tabelas Resumo

Rotas de Criação

As rotas responsáveis por criação não sofreram alterações:

• POST /api/v1/crm/people/create
• POST /api/v1/crm/company/create

4. Mudanças nos Endpoints Solares

Os módulos solares (como Usinas e Clientes) também receberam ajustes. As rotas de consulta foram alteradas para GET, mantendo o padrão de acesso RESTful.

Rotas Ajustadas

A rota de criação de clientes permaneceu inalterada:

• POST /api/v1/solar/customers/create

Novo: busca de customers com filtros

Foi adicionada uma rota de consulta com filtros para clientes, pensada para permitir buscas parciais e por campos específicos.

Endpoint:

GET /api/v1/solar/customers/search

Parâmetros de query:

• apikey (string, obrigatório) — API key da organização
• cpf (string, opcional) — busca parcial, case-insensitive
• cnpj (string, opcional) — busca parcial, case-insensitive
• name (string, opcional) — busca parcial, case-insensitive
• email (string, opcional) — busca parcial, case-insensitive
• provider (string, opcional) — match exato (ex.: CEMIG, ENEL)
• customer_number (string, opcional) — match exato

Comportamento:

• O endpoint aceita filtros combinados e retorna apenas os campos/itens que atendem aos critérios.
• Parâmetros textuais realizam busca parcial e case-insensitive conforme o DTO de validação.
• apikey é obrigatório em todas as chamadas (autorização/organização).

Exemplo de uso:

GET /api/v1/solar/customers/search?apikey=ORG_API_KEY&cpf=123456&name=Silva

5. Nova rota solar para faturas (energy-billing)

Adicionada rota para recuperar energy-billings / invoices da organização com paginação.

Endpoint:

GET /api/v1/solar/energy-billing

Parâmetros de query:

• apikey (string, obrigatório)
• cursor (string, opcional) — cursor de paginação
• limit (number, opcional) — limite por página

Exemplo:

GET /api/v1/solar/energy-billing?apikey=ORG_API_KEY&limit=100
GET /api/v1/solar/energy-billing?apikey=ORG_API_KEY&limit=100&cursor=<nextCursor>

6. Endpoint de Tickets

Para os Tickets, houve uma mudança no método de consulta. A rota agora utiliza GET para recuperar chamados ou tickets registrados na organização.

• Antes (Produção):

POST /api/v1/ticket

• Agora (Atualização):

GET /api/v1/ticket

7. Vantagens das Atualizações

• Consistência:

Agora, há uma diferença clara entre rotas de leitura (GET) e rotas de alteração/criação (POST), alinhando a API às melhores práticas RESTful.

• Clareza:

O renomeamento de Billing para Payments/Charges fornece maior contexto.

• Facilidade:

Ajustes estruturais permitem uma integração mais padronizada e intuitiva, especialmente se novos endpoints forem adicionados no futuro.

8. Resumo Final

Explore todas as mudanças diretamente na Documentação da API.

Conclusão

As atualizações na API marcam um progresso importante, alinhando-a com as melhores práticas do mercado. Recomendamos que os desenvolvedores revisem suas integrações existentes e realizem as alterações necessárias para garantir compatibilidade.

Atualizado em: 24/03/2026