Solavel Documentos
Português
Referência do desenvolvedor

SolaCount API Financeira

Versão: v1 URL base: https://solavel.com/api/v1 (substitua pelo seu domínio) Formato: JSON 33 pontos de extremidade

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)
Gere uma chave: Vá para Configurações → Acesso à API no SolaCount. A chave completa é mostrada exatamente uma vez. Cada chave tem escopos — conceda apenas os escopos de que precisar.

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

GET /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

GET /api/v1/customers escopo: customers.get

Lista todos os clientes. Oferece suporte a pesquisa e paginação.

Parâmetros de consulta

ParâmetroTipoDescriçã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}}
GET /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}}
POST /api/v1/customers escopo: customers.post

Criar um novo cliente.

Corpo da solicitação (JSON)

CampoTipoDescriçã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

GET /api/v1/suppliers escopo: suppliers.get

Lista todos os fornecedores. Oferece suporte a pesquisa e paginação.

Parâmetros de consulta

ParâmetroTipoDescriçã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}}
GET /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}}
POST /api/v1/suppliers escopo: suppliers.post

Criar um novo fornecedor.

Corpo da solicitação (JSON)

CampoTipoDescriçã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

GET /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âmetroTipoDescriçã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}}
GET /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}]}}
POST /api/v1/invoices escopo: invoices.post

Crie uma nova fatura. Criada com status=rascunho e número gerado automaticamente.

Corpo da solicitação (JSON)

CampoTipoDescriçã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}}
PUT /api/v1/invoices/{id} escopo: invoices.update

Atualize uma fatura em rascunho existente. Todos os campos são opcionais.

Corpo da solicitação (JSON)

CampoTipoDescriçã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":[]}}
POST /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

POST /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"}}
POST /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"}}
DELETE /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

GET /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âmetroTipoDescriçã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}}
GET /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":[]}}
POST /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)

CampoTipoDescriçã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}}
PUT /api/v1/bills/{id} escopo: bills.update

Atualize uma fatura em rascunho existente. Todos os campos são opcionais.

Corpo da solicitação (JSON)

CampoTipoDescriçã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"}}}
POST /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

DELETE /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

GET /api/v1/payments escopo: payments.get

Listar todos os pagamentos (recebimentos e desembolsos).

Parâmetros de consulta

ParâmetroTipoDescriçã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}}
POST /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)

CampoTipoDescriçã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

GET /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âmetroTipoDescriçã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}}
POST /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)

CampoTipoDescriçã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

DELETE /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).

GET /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âmetroTipoDescriçã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}}
GET /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âmetroTipoDescriçã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}}}
GET /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âmetroTipoDescriçã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}}
GET /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âmetroTipoDescriçã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}]}
GET /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âmetroTipoDescriçã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}}
GET /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âmetroTipoDescriçã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}}
GET /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âmetroTipoDescriçã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âmetroPadrãoMáx.Descrição
page1—Número da página a ser recuperada
per_page25100Número de resultados por página

O objeto meta em cada resposta de lista contém current_page, per_page, total e last_page.