SOLARZ-MONITORAMENTO

💰 Como usar a API do SolarZ Pay

A API do SolarZ Pay permite consultar os dados de cobrança da sua conta a partir de outro sistema, como seu ERP, BI, planilha ou automação. Você acompanha cobranças, assinaturas, saldo e saques sem precisar entrar no painel. Abaixo está o passo a passo para gerar seu acesso, conectar e fazer as primeiras consultas.

1. O que Você Consegue Consultar pela API

  • Vendas e Cobranças: vendas avulsas e cobranças de assinatura, com parcelas de repasse, tentativas de cobrança automática e mensagens enviadas ao cliente.

  • Assinaturas: assinaturas recorrentes dos seus clientes e os ciclos de cada uma.

  • Régua de Cobrança: as regras de geração e cancelamento das cobranças e as mensagens configuradas.

  • Financeiro: saldo da conta SolarZ Pay e saques.

  • Catálogo: planos e produtos cadastrados.

  • Chargebacks: contestações de compras feitas no cartão.

Importante: a API é somente de consulta. Criar, editar ou cancelar cobranças e contestar chargebacks continua sendo feito pelo painel da SolarZ.

2. Pré-requisitos

  1. Ter o SolarZ Pay ativo na conta.

  1. Ter um Usuário de API gerado no painel (veja o Passo 1).

  1. Se o acesso for de um colaborador, o dono da conta precisa liberar para ele o privilégio de acesso à API do SolarZ Pay e os privilégios de cada tela que ele vai consultar. O dono da conta já tem todos os acessos.

  1. Ter uma ferramenta para fazer as requisições, como o Postman, ou o próprio sistema que vai receber os dados.

3. Passo 1: Gere o Usuário de API

O Usuário de API é a credencial que autentica as chamadas. É o mesmo usuário da API do monitoramento: se você já gerou um, pode usar as mesmas credenciais e pular para o Passo 2.

  1. No menu lateral, clique em Configurações.

  1. Role até o fim da lista e selecione Usuário de API.

  1. Clique em + Gerar Usuário de API.

  1. Na janela que abrir, clique em Copiar ao lado do Usuário e da Senha e guarde os dois.

image-20261113-104216.png


Importante: a senha aparece uma única vez. Guarde-a em local seguro. Se perder, será preciso gerar um novo Usuário de API.

Observação: o login e a senha que você usa para entrar no painel não funcionam na API. Use sempre o Usuário de API, que começa com oa_.

image-20261113-104232.png



4. Passo 2: Conecte-se à API

  1. Consulte a documentação da API

A documentação da API do SolarZ Pay descreve todos os endpoints, filtros e exemplos de resposta.

  1. Autenticação

O método é Basic Authentication (Basic Auth). Em toda requisição, informe o Usuário e a Senha gerados no Passo 1. Não há token para gerar ou renovar.

  1. Importe a coleção no Postman

  1. No Postman, clique em Import e cole o link do schema: https://app.solarz.com.br/v3/api-docs/pay-open-api

  1. Na coleção criada, abra a aba Authorization, escolha Basic Auth e preencha Username e Password com o Usuário de API.

Endereço base de todas as chamadas: https://app.solarz.com.br/openApi/seller/pay/v1

Dica: para testar se está tudo certo, chame GET /balance. Se voltar o saldo, a conexão funcionou. Se voltar erro 401, confira o Usuário e a Senha.

5. Passo 3: Faça suas Primeiras Consultas

Todas as chamadas são do tipo GET e começam com o endereço base do Passo 2.

  • Cobranças de um período: /sales?dueDateFrom=2026-10-01&dueDateTo=2026-10-31 traz as cobranças que vencem em outubro. Essa consulta exige um intervalo de datas de até 12 meses. Escolha um tipo de data: vencimento (dueDateFrom/dueDateTo), pagamento (paidAtFrom/paidAtTo) ou criação (createdAtFrom/createdAtTo).

  • Cobranças vencidas: acrescente &stage=EXPIRED à consulta acima. Para filtrar pela forma de pagamento, use &paymentMethod=BOLETO,PIX.

  • Detalhe de uma cobrança: /sales/{id}, usando o id que veio na listagem. Para a mesma cobrança, /sales/{id}/installments mostra quando e quanto cai na conta; /sales/{id}/charges mostra por que um cartão foi recusado; /sales/{id}/messages mostra os avisos enviados ao cliente.

  • Assinaturas inadimplentes: /subscriptions?status=OVERDUE. Use status=ACTIVE para todas as ativas.

  • Saldo: /balance.

  • Saques do mês: /withdrawals?createdAtFrom=2026-10-01&createdAtTo=2026-10-31.

consulta_sales_solarz_pay-20261113-111618.png


Como ler a resposta

  • Valores em centavos: 152035 = R$ 1.520,35. Divida por 100. A exceção é o preço dos planos, que vem em reais.

  • Páginas: as listas trazem 50 itens por página (até 200 com pageSize=200). Enquanto hasNext for true, peça a próxima com page=2, page=3 e assim por diante, até a página 100.

  • Status da cobrança (stage): WAITING_PAYMENT aguardando pagamento · DONE paga · EXPIRED vencida, mas ainda pode ser paga · LAPSED não pode mais ser paga · PAYMENT_FAILED pagamento recusado · CANCELED cancelada · REFUNDED estornada · IN_DISPUTE em chargeback.

  • Status da assinatura (status): ACTIVATING em ativação · REGULAR em dia · OVERDUE em atraso · IRREGULAR com pendência em algum ciclo · CANCELED cancelada · FINISHED encerrada.

Observação: o saldo da API não é em tempo real. Ele é atualizado uma vez por dia, e o campo asOf mostra a data da leitura. Recebimentos e saques feitos depois dela ainda não aparecem.

6. Endpoints Disponíveis

Endpoint

O que traz

Precisa de data?

/sales

Lista de cobranças (avulsas e de assinatura)

Sim, até 12 meses

/sales/{id}

Detalhe de uma cobrança

Não

/sales/{id}/installments

Parcelas de repasse e taxa do gateway

Não

/sales/{id}/charges

Tentativas de cobrança automática

Não

/sales/{id}/messages

Mensagens enviadas ao cliente

Não

/subscriptions

Lista de assinaturas

Não

/subscriptions/{id}

Detalhe de uma assinatura

Não

/subscriptions/{id}/cycles

Ciclos da assinatura

Não

/billing-ruler

Configuração da régua de cobrança

Não

/billing-ruler/messages

Mensagens da régua

Não

/balance

Saldo da conta (atualizado 1x por dia)

Não

/withdrawals

Saques

Não

/plans

Planos de assinatura

Não

/products

Produtos

Não

/chargebacks

Chargebacks

Não

Os filtros de cada endpoint estão na documentação da API (https://app.solarz.com.br/v3/api-docs/pay-open-api/swagger-ui/index.html ). Use somente os nomes de filtro documentados: um nome diferente gera erro.

7. Erros Comuns e Como Resolver

Erro

O que significa

Como resolver

401

Usuário ou senha incorretos, ou uso do login do painel

Use o Usuário de API (oa_...) e confira a senha

403 PAY_NOT_ENABLED

A conta não tem SolarZ Pay

Ative o SolarZ Pay na conta

403 PAY_API_ACCESS_DENIED

O colaborador não tem acesso à API do SolarZ Pay

O dono da conta libera o privilégio de acesso à API

403 FORBIDDEN

Falta o privilégio da tela consultada

O dono da conta libera o privilégio informado no erro

400 MISSING_DATE_RANGE

Faltou o período na consulta de cobranças

Informe um par de datas, ex.: dueDateFrom e dueDateTo

400 DATE_RANGE_TOO_LARGE

Período maior que 12 meses

Divida a consulta em períodos menores

400 PAGE_TOO_DEEP

Página acima de 100

Use um período menor ou mais filtros

400 INVALID_PARAMETER

Filtro com nome ou valor inválido

Corrija conforme a mensagem do erro

404

ID inexistente ou de outra conta

Confira o ID

429

Muitas consultas seguidas ou cota diária esgotada

Aguarde o tempo indicado; a cota diária volta à meia-noite

Dica: faça as consultas uma de cada vez, e não todas ao mesmo tempo. Assim você evita o erro 429.

8. Dúvidas Frequentes

  • Posso usar o mesmo Usuário de API do monitoramento? Sim. O mesmo Usuário de API funciona nas duas APIs.

  • Consigo criar ou cancelar cobranças pela API? Não. A API é somente de consulta.

  • Preciso de dados de mais de 12 meses. Como faço? Faça uma consulta por período (por exemplo, um ano de cada vez) e junte os resultados.

Se ficar alguma dúvida ou um erro continuar acontecendo, fale com o nosso suporte.