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
-
Ter o SolarZ Pay ativo na conta.
-
Ter um Usuário de API gerado no painel (veja o Passo 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.
-
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.
-
No menu lateral, clique em Configurações.
-
Role até o fim da lista e selecione Usuário de API.
-
Clique em + Gerar Usuário de API.
-
Na janela que abrir, clique em Copiar ao lado do Usuário e da Senha e guarde os dois.
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_.
4. Passo 2: Conecte-se à API
-
Consulte a documentação da API
A documentação da API do SolarZ Pay descreve todos os endpoints, filtros e exemplos de resposta.
-
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.
-
Importe a coleção no Postman
-
No Postman, clique em Import e cole o link do schema: https://app.solarz.com.br/v3/api-docs/pay-open-api
-
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.
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.