Documentação da API

Versão v1 — actualizada em 28 de Julho de 2026

---

A API REST permite integrar o Pardal com ERP, loja online ou aplicações próprias. O acesso está disponível para empresas cujo plano inclui API e para administradores ou proprietários da empresa.

URL base

https://facturas.pardal.app

Autenticação

Crie uma chave em Integrações > Chaves da API. O token é mostrado apenas uma vez. Envie-o em todos os pedidos autenticados e use sempre HTTPS.

Authorization: Bearer SEU_TOKEN
Accept: application/json

Permissões disponíveis

Scope	Permissão
account:read	Consultar a identidade da integração e a empresa
customers:read	Consultar clientes
customers:write	Criar, actualizar ou desactivar clientes
products:read	Consultar produtos e serviços
products:write	Criar, actualizar ou desactivar produtos e serviços
invoices:read	Consultar facturas e descarregar PDFs
invoices:write	Emitir facturas
invoices:send	Enviar facturas por email
invoices:mark-paid	Registar pagamentos totais ou parciais e gerar recibos

Endpoints

Method	Path	Descrição
GET	/api/health	Verificação pública de disponibilidade.
GET	/api/v1/me	Dados do utilizador e da empresa associados ao token. (account:read)
GET	/api/v1/customers	Lista clientes. Aceita search e per_page. (customers:read)
GET	/api/v1/customers/{id}	Obtém um cliente. (customers:read)
POST	/api/v1/customers	Cria um cliente. (customers:write)
PATCH	/api/v1/customers/{id}	Actualiza um cliente. (customers:write)
DELETE	/api/v1/customers/{id}	Desactiva ou elimina um cliente sem documentos. (customers:write)
GET	/api/v1/products	Lista produtos e serviços. Aceita search, type e per_page. (products:read)
POST	/api/v1/products	Cria um produto ou serviço. (products:write)
PATCH	/api/v1/products/{id}	Actualiza um produto ou serviço. (products:write)
DELETE	/api/v1/products/{id}	Desactiva um produto ou serviço. (products:write)
GET	/api/v1/invoices	Lista facturas. Aceita status, customer_id, from, to, document_type e per_page. (invoices:read)
GET	/api/v1/invoices/{id}	Obtém uma factura. (invoices:read)
POST	/api/v1/invoices	Emite uma factura. (invoices:write)
GET	/api/v1/invoices/{id}/pdf	Descarrega o PDF. (invoices:read)
POST	/api/v1/invoices/{id}/send	Envia a factura por email. (invoices:send)
POST	/api/v1/invoices/{id}/payments	Regista um pagamento total ou parcial. Aceita amount, method, paid_at, reference, notes e receipt_series_id. O endpoint /mark-paid continua disponível para compatibilidade. (invoices:mark-paid)

Exemplo: emitir factura

customer_id e invoice_series_id devem pertencer à empresa da chave. O campo document_type aceita invoice, invoice_receipt, receipt ou credit_note. Cada item exige description, quantity e unit_price; vat_rate e discount_percent são opcionais.

{
  "customer_id": 42,
  "invoice_series_id": 3,
  "document_type": "invoice",
  "issue_date": "2026-07-23",
  "due_date": "2026-08-22",
  "items": [
    {
      "description": "Serviço de consultoria",
      "quantity": 1,
      "unit_price": 50000,
      "vat_rate": 16
    }
  ]
}

Exemplo: registar pagamento parcial

method aceita cash, bank_transfer, cheque, mpesa, mkesh, emola, izi, card ou other. Se amount for omitido, o Pardal regista o saldo total em dívida.

{
  "amount": 25000,
  "method": "bank_transfer",
  "paid_at": "2026-07-28",
  "reference": "TRX-20260728-001",
  "notes": "Primeiro pagamento do projecto"
}

Respostas e limites

• Use Accept: application/json e Content-Type: application/json em pedidos com corpo.
• Pedidos autenticados têm um limite de 120 por minuto por token. Uma resposta 429 indica que o limite foi excedido.
• 401 indica token ausente, inválido ou expirado; 403 indica permissão ou plano insuficiente; 422 indica erro de validação; 404 indica recurso inexistente ou fora da empresa associada ao token.
• Revogue imediatamente uma chave comprometida em Integrações > Chaves da API.