FatureAqui
Obter Chave API
Documentação para Programadores

FatureAqui API REST

Ligue a sua loja online, aplicação mobile, sistema de faturação externo ou POS diretamente à sua conta FatureAqui de forma rápida, segura e automatizada.

Base URL

Todos os pedidos devem ser feitos para o endpoint principal do projeto alojado na Supabase.

https://sesbyfhonbigmtfyavck.supabase.co/functions/v1/

Autenticação

A API do FatureAqui utiliza Bearer Tokens para autenticar pedidos. Apenas contas com plano Pro podem gerar chaves de API.

  1. Vá ao seu Painel > API e Integrações.
  2. Clique em "Gerar Chave" e copie a chave fornecida (Ex: fat_live_...).
  3. Envie essa chave no cabeçalho (Header) de todos os pedidos HTTP.
Authorization: Bearer fat_live_SUA_CHAVE_SECRETA_AQUI

As chaves fat_live_ dão acesso direto à sua conta e criam documentos válidos. Nunca exponha esta chave no código frontend (lado do cliente). Faça os pedidos sempre a partir do seu servidor (backend).

Criar Cliente

POST/api-customers

Cria um novo cliente na sua conta FatureAqui. É recomendável criar o cliente primeiro antes de lhe emitir uma fatura.

Parâmetros (Body JSON)

CampoTipoObrigatórioDescrição
namestringNome completo ou designação da empresa.
emailstring-Email do cliente para envio automático.
nuitstring-NUIT (Número de Identificação Tributária).
phonestring-Contacto telefónico.
addressstring-Endereço completo (Ex: Av. 24 de Julho).
citystring-Cidade (Ex: Maputo).
bash
curl -X POST "https://sesbyfhonbigmtfyavck.supabase.co/functions/v1/api-customers" \
  -H "Authorization: Bearer fat_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joao@email.com",
    "nuit": "123456789",
    "city": "Maputo"
  }'

Resposta de Sucesso (201 Created)

json
{
  "success": true,
  "data": {
    "id": "e838b0fc-1234-4567-8901-abcdef123456",
    "name": "João Silva",
    "nuit": "123456789",
    "email": "joao@email.com"
  }
}

Criar Fatura

POST/api-invoices

Gera um novo documento fiscal (Fatura ou Fatura-Recibo) atribuído a um cliente existente.

Parâmetros (Body JSON)

CampoTipoObrigatórioDescrição
customer_idstringID do cliente (UUID retornado ao criar).
typestring-Fatura ou Fatura-Recibo. Padrão: Fatura.
currencystring-Moeda (Ex: MT, USD). Padrão: MT.
itemsarrayArray de objetos contendo os produtos/serviços.

Estrutura do Array items

Cada item no array deve conter:

  • description (string): Nome do produto/serviço.
  • quantity (número): Quantidade (pode ser decimal).
  • unit_price (número): Preço unitário antes de impostos.
  • tax_rate (número, opcional): Percentagem do IVA (Ex: 16). Padrão: 0.
bash
curl -X POST "https://sesbyfhonbigmtfyavck.supabase.co/functions/v1/api-invoices" \
  -H "Authorization: Bearer fat_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "e838b0fc-1234-4567-8901-abcdef123456",
    "type": "Fatura",
    "currency": "MT",
    "items": [
      {
        "description": "Desenvolvimento de Website",
        "quantity": 1,
        "unit_price": 50000.00,
        "tax_rate": 16
      },
      {
        "description": "Alojamento Mensal",
        "quantity": 1,
        "unit_price": 1500.00,
        "tax_rate": 16
      }
    ]
  }'

Resposta de Sucesso (201 Created)

json
{
  "success": true,
  "data": {
    "id": "f949c1ec-9876-5432-1098-fedcba654321",
    "number": "FT 2026/42",
    "type": "Fatura",
    "status": "rascunho",
    "subtotal": 51500.00,
    "total_tax": 8240.00,
    "total": 59740.00,
    "issue_date": "2026-08-25"
  }
}

Webhooks (Eventos)

Os Webhooks permitem que a sua aplicação receba notificações em tempo real sempre que ocorre um evento na sua conta FatureAqui (por exemplo, quando uma fatura é criada ou o seu estado é alterado para Paga). Isto elimina a necessidade de fazer consultas (polling) constantes à nossa API.

Configuração no Painel

Pode registar o URL do seu servidor para receber Webhooks diretamente no seu Painel de Integrações. Quando criar um webhook, receberá um Secret. Esse segredo é vital para validar a autenticidade dos pedidos recebidos.

Estrutura do Payload (POST)

Sempre que um evento ocorrer, o FatureAqui enviará um pedido HTTP POST para o seu URL com a seguinte estrutura:

json
{
  "event": "fatura.atualizada",
  "created_at": "2026-08-25T15:30:00Z",
  "data": {
    "id": "f949c1ec-9876-5432-1098-fedcba654321",
    "status": "pago",
    "type": "Fatura",
    "total": 59740.00,
    ...
  }
}

Validação de Segurança (HMAC)

Para garantir que o pedido foi enviado genuinamente pelo FatureAqui, incluímos um cabeçalho X-FatureAqui-Signature em cada webhook. Esta assinatura é um hash HMAC SHA-256 gerado usando o Secret do seu Webhook e o corpo do pedido (raw body).

Exemplo em PHP para validar a assinatura:

php
<?php
// O Secret que recebeu no Painel do FatureAqui
$secret = 'whsec_seusegredo12345';

// O corpo exato do pedido (Raw Payload)
$payload = file_get_contents('php://input');

// A assinatura enviada pelo FatureAqui nos Cabeçalhos
$signatureHeader = $_SERVER['HTTP_X_FATUREAQUI_SIGNATURE'];

// Calcule a assinatura localmente
$expectedSignature = hash_hmac('sha256', $payload, $secret);

// Compare as assinaturas (usando hash_equals para evitar ataques de timing)
if (hash_equals($expectedSignature, $signatureHeader)) {
    // É autêntico! Pode processar
    $data = json_decode($payload, true);
    http_response_code(200);
    echo "Sucesso";
} else {
    // A assinatura não coincide, rejeite!
    http_response_code(401);
    echo "Assinatura inválida";
}

Tratamento de Erros

O FatureAqui utiliza códigos HTTP convencionais para indicar o sucesso ou falha de uma requisição API.

201Created

O pedido foi bem sucedido e o recurso foi criado.

400Bad Request

Falta um parâmetro obrigatório ou há um erro de formatação (Ex: string em vez de número).

401Unauthorized

Chave de API inválida, revogada ou não enviada no formato Bearer correto.

405Method Not Allowed

Foi utilizado um método incorreto (Ex: GET em vez de POST).