SolaCount API Financeira
A API Finance do SolaCount permite ler e escrever dados contabilísticos por programação: clientes, fornecedores, faturas de clientes e fornecedores, pagamentos, lançamentos contabilísticos e relatórios financeiros. Todos os pontos de acesso devolvem JSON. Criar uma chave API →
Autenticação
Cada endpoint protegido exige três cabeçalhos:
X-API-Key: solabooks_<prefix>.<secret> X-Organization-Id: 1 X-Client-Id: 4
- X-API-Key — a chave completa exibida uma vez na criação em Configurações → Acesso à API
- X-Organization-Id — o ID inteiro da sua organização (visível na página Acesso à API)
- X-Client-Id — o ID do seu cliente (visível na página Acesso à API)
O endpoint GET /api/v1/health não exige autenticação e pode ser usado para verificar a conectividade.
Formato de resposta
Todas as respostas usam um envelope JSON consistente.
Objeto único
{
"success": true,
"data": { ... }
}
Lista paginada
{
"success": true,
"data": [ ... ],
"meta": {
"current_page": 1,
"per_page": 25,
"total": 100,
"last_page": 4
}
}
Erro
{
"success": false,
"error": {
"code": "error_code",
"message": "Human readable message."
}
}
Teste rápido
Substitua your_key, 1 e 4 pela sua chave de API, ID da organização e ID do cliente reais.
Verificação de integridade (sem autenticação necessária)
curl https://solacount.com/api/v1/health
Listar faturas
curl https://solacount.com/api/v1/invoices \ -H "X-API-Key: your_key" \ -H "X-Organization-Id: 1" \ -H "X-Client-Id: 4"
Criar um cliente
curl -X POST https://solacount.com/api/v1/customers \
-H "X-API-Key: your_key" \
-H "X-Organization-Id: 1" \
-H "X-Client-Id: 4" \
-H "Content-Type: application/json" \
-d '{"name":"Demo Customer","email":"billing@example.com"}'
Criar um lançamento contabilístico
curl -X POST https://solacount.com/api/v1/journal-entries \
-H "X-API-Key: your_key" \
-H "X-Organization-Id: 1" \
-H "X-Client-Id: 4" \
-H "Content-Type: application/json" \
-d '{
"date": "2026-06-07",
"reference": "JE-001",
"description": "Manual accrual",
"lines": [
{"account_id": 101, "debit": 1000, "credit": 0},
{"account_id": 202, "debit": 0, "credit": 1000}
]
}'
Todos os endpoints
Clique em qualquer endpoint para expandir seus detalhes. 33 endpoints no total em 8 grupos de recursos.
Integridade
/api/v1/health
sem autenticação
Confirme se a API está online e respondendo. Nenhuma autenticação necessária.
Resposta HTTP 200
{"success":true,"data":{"service":"finance-api","status":"ok","timestamp":"2026-06-07T12:00:00+00:00"}}
Clientes
/api/v1/customers
escopo: customers.get
Lista todos os clientes. Oferece suporte a pesquisa e paginação.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
search |
string |
opcional | Filtrar por nome, e-mail ou telefone (correspondência parcial) |
page |
integer |
opcional | Número da página (padrão: 1) |
per_page |
integer |
opcional | Resultados por página (padrão: 25, máx: 100) |
Resposta HTTP 200
{"success":true,"data":[{"id":1,"name":"Demo Customer","email":"billing@example.com","phone":"+1-555-0100","is_active":true}],"meta":{"current_page":1,"per_page":25,"total":3,"last_page":1}}
/api/v1/customers/{id}
escopo: customers.get
Recuperar um único cliente por ID.
Resposta HTTP 200
{"success":true,"data":{"id":1,"name":"Demo Customer","email":"billing@example.com","phone":"+1-555-0100","is_active":true}}
/api/v1/customers
escopo: customers.post
Criar um novo cliente.
Corpo da solicitação (JSON)
| Campo | Tipo | Descrição | |
|---|---|---|---|
name |
string |
obrigatório | Nome do cliente |
email |
string |
opcional | Endereço de e-mail (deve ser um e-mail válido) |
phone |
string |
opcional | Número de telefone (máx. 50 caracteres) |
is_active |
boolean |
opcional | Status ativo (padrão: verdadeiro) |
Resposta HTTP 201
{"success":true,"data":{"id":42,"name":"Demo Customer","email":"billing@example.com","phone":null,"is_active":true}}
Fornecedores
/api/v1/suppliers
escopo: suppliers.get
Lista todos os fornecedores. Oferece suporte a pesquisa e paginação.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
search |
string |
opcional | Filtrar por nome (correspondência parcial) |
page |
integer |
opcional | Número da página |
per_page |
integer |
opcional | Resultados por página (máx 100) |
Resposta HTTP 200
{"success":true,"data":[{"id":1,"name":"Demo Supplier","email":"ap@example.com","tax_id":"GB123456789","is_vat_registered":true}],"meta":{"current_page":1,"per_page":25,"total":1,"last_page":1}}
/api/v1/suppliers/{id}
escopo: suppliers.get
Recupera um único fornecedor pelo ID.
Resposta HTTP 200
{"success":true,"data":{"id":1,"name":"Demo Supplier","email":"ap@example.com","phone":null,"tax_id":"GB123456789","is_overseas":false,"is_vat_registered":true,"reverse_charge":false}}
/api/v1/suppliers
escopo: suppliers.post
Criar um novo fornecedor.
Corpo da solicitação (JSON)
| Campo | Tipo | Descrição | |
|---|---|---|---|
name |
string |
obrigatório | Nome do fornecedor |
email |
string |
opcional | Endereço de e-mail |
phone |
string |
opcional | Número de telefone |
tax_id |
string |
opcional | Número de registro de IVA / imposto |
is_overseas |
boolean |
opcional | Se o fornecedor é do exterior (padrão: falso) |
is_vat_registered |
boolean |
opcional | IVA registrado (padrão: verdadeiro) |
reverse_charge |
boolean |
opcional | Aplica-se o IVA de reverse charge (padrão: falso) |
Resposta HTTP 201
{"success":true,"data":{"id":15,"name":"Demo Supplier","email":"ap@example.com","tax_id":"GB123456789","is_vat_registered":true}}
Faturas
/api/v1/invoices
escopo: invoices.get
Listar todas as faturas com relação ao cliente. Suporta filtro de status e paginação.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
status |
string |
opcional | Filtro: draft | unpaid | paid | void | overdue
|
page |
integer |
opcional | Número da página |
per_page |
integer |
opcional | Resultados por página (máx 100) |
Resposta HTTP 200
{"success":true,"data":[{"id":101,"number":"INV-00101","date":"2026-06-01","due_date":"2026-07-01","status":"unpaid","total":5000.00,"customer":{"id":1,"name":"Demo Customer"}}],"meta":{"current_page":1,"per_page":25,"total":48,"last_page":2}}
/api/v1/invoices/{id}
escopo: invoices.get
Recupere uma única fatura com cliente e itens de linha.
Resposta HTTP 200
{"success":true,"data":{"id":101,"number":"INV-00101","date":"2026-06-01","due_date":"2026-07-01","status":"unpaid","subtotal":4347.83,"tax_total":652.17,"total":5000.00,"customer":{"id":1,"name":"Demo Customer"},"lines":[{"id":1,"description":"Consulting services","qty":10,"unit_price":434.78,"total":4347.83}]}}
/api/v1/invoices
escopo: invoices.post
Crie uma nova fatura. Criada com status=rascunho e número gerado automaticamente.
Corpo da solicitação (JSON)
| Campo | Tipo | Descrição | |
|---|---|---|---|
customer_id |
integer |
obrigatório | ID de um cliente existente |
date |
date |
obrigatório | Data da fatura (AAAA-MM-DD) |
due_date |
date |
opcional | Data de vencimento do pagamento (AAAA-MM-DD) |
notes |
string |
opcional | Notas internas ou voltadas ao cliente |
subtotal |
decimal |
opcional | Total antes do imposto (padrão: 0) |
tax_total |
decimal |
opcional | Valor do imposto (padrão: 0) |
discount_total |
decimal |
opcional | Valor do desconto (padrão: 0) |
total |
decimal |
opcional | Total geral (padrão: 0) |
Resposta HTTP 201
{"success":true,"data":{"id":102,"number":"INV-00102","status":"draft","date":"2026-06-07","due_date":"2026-07-07","total":5000.00,"customer_id":1}}
/api/v1/invoices/{id}
escopo: invoices.update
Atualize uma fatura em rascunho existente. Todos os campos são opcionais.
Corpo da solicitação (JSON)
| Campo | Tipo | Descrição | |
|---|---|---|---|
customer_id |
integer |
opcional | ID do novo cliente |
date |
date |
opcional | Data da fatura (AAAA-MM-DD) |
due_date |
date |
opcional | Data de vencimento do pagamento |
notes |
string |
opcional | Notas |
subtotal |
decimal |
opcional | Total antes dos impostos |
tax_total |
decimal |
opcional | Valor do imposto |
total |
decimal |
opcional | Total geral |
Resposta HTTP 200
{"success":true,"data":{"id":102,"status":"draft","total":6000.00,"customer":{"id":1,"name":"Demo Customer"},"lines":[]}}
/api/v1/invoices/{id}/post
escopo: invoices.post
Lançar uma fatura de rascunho no razão geral. Requer total > 0 e uma data. Altera o status para não pago.
Resposta HTTP 200
{"success":true,"data":{"id":102,"status":"unpaid","posted_at":"2026-06-07T12:00:00Z","total":5000.00}}
Possíveis erros:
invoice_already_posted,
invoice_total_required,
invoice_date_required
/api/v1/invoices/{id}/void
escopo: invoices.void
Anular uma fatura lançada. Reverte todos os lançamentos contábeis e marca a fatura como anulada.
Resposta HTTP 200
{"success":true,"data":{"id":102,"status":"void"}}
/api/v1/invoices/{id}/mark-sent
escopo: invoices.send
Marcar uma fatura de rascunho como enviada ao cliente (altera o status de rascunho para não pago). Idempotente.
Resposta HTTP 200
{"success":true,"data":{"id":102,"status":"unpaid"}}
/api/v1/invoices/{id}
escopo: invoices.delete
Excluir permanentemente uma fatura de rascunho e todas as suas linhas. Não é possível excluir faturas lançadas ou faturas com alocações de pagamento.
Resposta HTTP 200
{"success":true,"data":{"message":"Invoice deleted."}}
Possíveis erros:
posted_invoice_not_deletable,
invoice_has_allocations
Faturas
/api/v1/bills
escopo: bills.get
Lista todas as contas a pagar de fornecedores. Oferece suporte a filtro por status e paginação.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
status |
string |
opcional | Filtro: draft | unpaid | paid | void
|
page |
integer |
opcional | Número da página |
per_page |
integer |
opcional | Resultados por página (máx 100) |
Resposta HTTP 200
{"success":true,"data":[{"id":55,"number":"BILL-00055","date":"2026-06-01","status":"draft","total":2000.00,"supplier":{"id":3,"name":"Demo Supplier"}}],"meta":{"current_page":1,"per_page":25,"total":12,"last_page":1}}
/api/v1/bills/{id}
escopo: bills.get
Recuperar uma única fatura de fornecedor com itens de linha.
Resposta HTTP 200
{"success":true,"data":{"id":55,"number":"BILL-00055","date":"2026-06-01","due_date":"2026-07-01","status":"draft","reference":"PO-001","total":2000.00,"supplier":{"id":3,"name":"Demo Supplier"},"lines":[]}}
/api/v1/bills
escopo: bills.post
Crie uma nova conta de fornecedor. Criada com status=rascunho e número BILL-XXXXX gerado automaticamente.
Corpo da solicitação (JSON)
| Campo | Tipo | Descrição | |
|---|---|---|---|
supplier_id |
integer |
obrigatório | ID de um fornecedor existente |
date |
date |
obrigatório | Data da fatura (AAAA-MM-DD) |
due_date |
date |
opcional | Data de vencimento do pagamento |
reference |
string |
opcional | Referência do fornecedor / número do pedido de compra (máx. 120) |
notes |
string |
opcional | Notas internas |
subtotal |
decimal |
opcional | Total antes do imposto (padrão: 0) |
tax_total |
decimal |
opcional | Valor do imposto (padrão: 0) |
discount_total |
decimal |
opcional | Desconto (padrão: 0) |
total |
decimal |
opcional | Total geral (padrão: 0) |
Resposta HTTP 201
{"success":true,"data":{"id":56,"number":"BILL-00056","status":"draft","date":"2026-06-07","total":2000.00,"supplier_id":3}}
/api/v1/bills/{id}
escopo: bills.update
Atualize uma fatura em rascunho existente. Todos os campos são opcionais.
Corpo da solicitação (JSON)
| Campo | Tipo | Descrição | |
|---|---|---|---|
supplier_id |
integer |
opcional | Novo ID do fornecedor |
date |
date |
opcional | Data da fatura |
due_date |
date |
opcional | Data de vencimento do pagamento |
reference |
string |
opcional | Referência do fornecedor |
total |
decimal |
opcional | Total geral |
Resposta HTTP 200
{"success":true,"data":{"id":56,"status":"draft","total":2500.00,"supplier":{"id":3,"name":"Demo Supplier"}}}
/api/v1/bills/{id}/post
escopo: bills.post
Lance uma conta a pagar em rascunho no razão geral, registrando o valor a pagar.
Resposta HTTP 200
{"success":true,"data":{"id":56,"status":"unpaid","posted_at":"2026-06-07T12:00:00Z"}}
Possíveis erros:
bill_post_failed
/api/v1/bills/{id}
escopo: bills.delete
Excluir permanentemente uma fatura de rascunho. A fatura deve estar no status de rascunho sem alocações de pagamento.
Resposta HTTP 200
{"success":true,"data":{"message":"Bill deleted."}}
Possíveis erros:
posted_bill_not_deletable,
bill_has_allocations
Pagamentos
/api/v1/payments
escopo: payments.get
Listar todos os pagamentos (recebimentos e desembolsos).
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
type |
string |
opcional | Filtro: receipt | disbursement
|
status |
string |
opcional | Filtro: draft | posted
|
page |
integer |
opcional | Número da página |
per_page |
integer |
opcional | Resultados por página (máx 100) |
Resposta HTTP 200
{"success":true,"data":[{"id":20,"type":"receipt","payment_date":"2026-06-07","amount_total":5000.00,"status":"draft","customer_id":1}],"meta":{"current_page":1,"per_page":25,"total":8,"last_page":1}}
/api/v1/payments
escopo: payments.post
Registre um recebimento de pagamento (cliente pagou) ou um desembolso (você pagou ao fornecedor). Opcionalmente, aloque contra uma fatura ou conta.
Corpo da solicitação (JSON)
| Campo | Tipo | Descrição | |
|---|---|---|---|
type |
string |
obrigatório | receipt (pagamento de cliente) ou disbursement (pagamento a fornecedor)
|
payment_date |
date |
obrigatório | Data do pagamento (AAAA-MM-DD) |
amount_total |
decimal |
obrigatório | Valor total pago (deve ser > 0) |
method |
string |
opcional | Método de pagamento, por exemplo, transferência_bancária, dinheiro, cartão |
reference |
string |
opcional | Referência bancária ou número do cheque (máx 120) |
description |
string |
opcional | Descrição ou memorando |
customer_id |
integer |
cond. | Obrigatório para pagamentos de recebimento (inferido da fatura se document_type=ar_invoice) |
supplier_id |
integer |
cond. | Obrigatório para pagamentos de desembolso (inferido da conta se document_type=ap_bill) |
document_type |
string |
opcional | "ar_invoice" ou "ap_bill" — aciona a alocação automática |
document_id |
integer |
opcional | ID da fatura ou conta a ser alocada (obrigatório quando document_type é definido) |
allocated_amount |
decimal |
opcional | Valor a ratear (padrão: amount_total) |
Resposta HTTP 201
{"success":true,"data":{"id":21,"type":"receipt","payment_date":"2026-06-07","amount_total":5000.00,"status":"draft","allocations":[{"document_type":"ar_invoice","document_id":101,"allocated_amount":5000.00}]}}
Erros possíveis:
document_required,
document_type_mismatch,
invoice_not_found,
bill_not_found,
client_required,
supplier_required
Lançamentos contábeis
/api/v1/journal-entries
escopo: journal_entries.get
Listar lançamentos contábeis com linhas e contas. Suporta filtragem por intervalo de datas.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
status |
string |
opcional | Filtro: draft | posted
|
from |
date |
opcional | Data de início (AAAA-MM-DD) |
to |
date |
opcional | Data de término (AAAA-MM-DD) |
page |
integer |
opcional | Número da página |
per_page |
integer |
opcional | Resultados por página (máx 100) |
Resposta HTTP 200
{"success":true,"data":[{"id":5,"entry_date":"2026-06-07","reference":"JE-001","status":"posted","lines_count":2}],"meta":{"current_page":1,"per_page":25,"total":5,"last_page":1}}
/api/v1/journal-entries
escopo: journal_entries.post
Crie e lance imediatamente um lançamento contábil equilibrado. O total de débitos deve ser igual ao total de créditos (tolerância de ±0,01).
Corpo da solicitação (JSON)
| Campo | Tipo | Descrição | |
|---|---|---|---|
date |
date |
obrigatório | Data do lançamento (AAAA-MM-DD) |
reference |
string |
opcional | Código de referência, ex.: JE-001 (máx. 120) |
description |
string |
opcional | Memorando / descrição (máx 2000) |
lines |
array |
obrigatório | Mínimo de 2 linhas. Cada linha: account_id (obrigatório), debit (decimal), credit (decimal), description (texto) |
Resposta HTTP 201
{"success":true,"data":{"id":6,"entry_date":"2026-06-07","reference":"JE-001","status":"posted","posted_at":"2026-06-07T12:00:00Z","lines":[{"account_id":101,"account":{"code":"1100","name":"Cash"},"debit":1000,"credit":0},{"account_id":202,"account":{"code":"3000","name":"Equity"},"debit":0,"credit":1000}]}}
Possíveis erros:
journal_not_balanced
/api/v1/journal-entries/{id}
escopo: journal_entries.delete
Excluir um lançamento contábil não lançado. Lançamentos contábeis lançados não podem ser excluídos através da API.
Resposta HTTP 200
{"success":true,"data":{"message":"Journal entry deleted."}}
Possíveis erros:
posted_journal_not_deletable
Relatórios
Todos os endpoints de relatório aceitam ?from=YYYY-MM-DD&to=YYYY-MM-DD. Os relatórios de balanço patrimonial, balancete e envelhecimento também aceitam ?as_of=YYYY-MM-DD (equivalente a to).
/api/v1/reports/income-statement
escopo: reports.income_statement
Relatório de lucros e perdas. Mostra receita, despesas e lucro líquido do período especificado.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
from |
date |
opcional | Início do período (AAAA-MM-DD) |
to |
date |
opcional | Fim do período (AAAA-MM-DD) |
Resposta HTTP 200
{"success":true,"data":{"revenue":150000,"expenses":85000,"net_income":65000}}
/api/v1/reports/balance-sheet
escopo: reports.balance_sheet
Instantâneo do balanço patrimonial. Retorna ativos, passivos e patrimônio líquido na data especificada.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
to |
date |
opcional | Data de referência (AAAA-MM-DD). Também aceito como ?as_of= |
Resposta HTTP 200
{"success":true,"data":{"assets":{"total":250000},"liabilities":{"total":80000},"equity":{"total":170000}}}
/api/v1/reports/cash-flow
escopo: reports.cash_flow
Demonstração de fluxo de caixa para o período especificado (método direto).
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
from |
date |
opcional | Início do período |
to |
date |
opcional | Fim do período |
Resposta HTTP 200
{"success":true,"data":{"operating":45000,"investing":-12000,"financing":-8000,"net_change":25000}}
/api/v1/reports/trial-balance
escopo: reports.trial_balance
Balancete mostrando todas as contas com os totais de débito e crédito em uma data.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
to |
date |
opcional | Data de referência (AAAA-MM-DD) |
Resposta HTTP 200
{"success":true,"data":[{"account_code":"1100","account_name":"Cash","debit":50000,"credit":0},{"account_code":"2000","account_name":"Accounts Payable","debit":0,"credit":15000}]}
/api/v1/reports/ar-aging
escopo: reports.ar_aging
Envelhecimento de contas a receber. Faturas de clientes em aberto agrupadas pelo tempo de atraso.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
to |
date |
opcional | Data de referência de vencimento (AAAA-MM-DD) |
Resposta HTTP 200
{"success":true,"data":{"current":12000,"1_30":3500,"31_60":800,"61_90":0,"over_90":500,"total":16800}}
/api/v1/reports/ap-aging
escopo: reports.ap_aging
Vencimento de contas a pagar. Faturas de fornecedores pendentes agrupadas por tempo de atraso.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
to |
date |
opcional | Data de referência de vencimento (AAAA-MM-DD) |
Resposta HTTP 200
{"success":true,"data":{"current":8000,"1_30":1200,"31_60":0,"61_90":0,"over_90":0,"total":9200}}
/api/v1/reports/tax
escopo: reports.tax
Resumo de IVA / impostos. Retorna o imposto cobrado sobre vendas e o imposto pago sobre compras no período.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
from |
date |
opcional | Início do período |
to |
date |
opcional | Fim do período |
Resposta HTTP 200
{"success":true,"data":{"tax_collected":15000,"tax_paid":4200,"net_vat_payable":10800}}
Referência de erro
| Código de erro | HTTP | Significado |
|---|---|---|
invoice_already_posted |
422 | A fatura já está lançada no razão |
invoice_total_required |
422 | Não é possível lançar uma fatura com total zero ou negativo |
invoice_date_required |
422 | A data do documento é necessária antes do lançamento |
posted_invoice_not_deletable |
422 | Anule ou desfaça a contabilização da fatura antes de excluir |
invoice_has_allocations |
422 | Remova as alocações de pagamento antes de excluir |
posted_bill_not_deletable |
422 | Não é possível excluir uma fatura lançada ou que não seja rascunho |
bill_has_allocations |
422 | Remova as alocações de pagamento antes de excluir |
bill_post_failed |
422 | A fatura falhou na validação interna de lançamento |
journal_not_balanced |
422 | O total de débitos não é igual ao total de créditos |
posted_journal_not_deletable |
422 | Somente lançamentos em rascunho (não lançados) podem ser excluídos |
document_required |
422 | document_id é obrigatório quando document_type está definido
|
document_type_mismatch |
422 | ar_invoice requer receipt; ap_bill requer disbursement
|
invoice_not_found |
404 | Não existe fatura com esse ID |
bill_not_found |
404 | A fatura com esse ID não existe |
client_required |
422 | customer_id é obrigatório para pagamentos receipt
|
supplier_required |
422 | supplier_id é obrigatório para pagamentos disbursement
|
Paginação
Todos os endpoints de lista retornam resultados paginados. Controle a paginação com parâmetros de consulta:
| Parâmetro | Padrão | Máx. | Descrição |
|---|---|---|---|
page | 1 | — | Número da página a ser recuperada |
per_page | 25 | 100 | Número de resultados por página |
O objeto meta em cada resposta de lista contém current_page, per_page, total e last_page.