Billing Core API

Autenticacao de utilizador por email e password. Retorna access token (15 min) e refresh token (7 dias).

Parametros

curl -X POST https://api.billingcore.pt/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@empresa.pt",
    "password": "senha-segura"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 900
}

Renovar access token usando refresh token. O refresh token tem validade de 7 dias.

Autenticacao de app por client_id e client_secret. Retorna access token com validade de 1 hora.

curl -X POST https://api.billingcore.pt/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "uuid-da-app",
    "client_secret": "secret-da-app"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600
}

Criar documento fiscal em estado DRAFT. O documento fica em DRAFT ate ser committed via POST /documents/{id}/commit. Header Idempotency-Key obrigatorio.

Objeto linha

curl -X POST https://api.billingcore.pt/api/v1/documents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{
    "type": "FT",
    "series_id": "uuid-da-serie",
    "customer_id": "uuid-do-cliente",
    "invoice_date": "2026-04-09",
    "lines": [
      {
        "product_id": "uuid-do-produto",
        "description": "Servico de Consultoria",
        "quantity": "2.000",
        "unit_price": "100.00",
        "tax_rate": "23.00"
      }
    ]
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "FT",
  "status": "DRAFT",
  "document_no": null,
  "invoice_date": "2026-04-09",
  "gross_total": null,
  "hash": null,
  "atcud": null,
  "lines": [...]
}

Listar documentos do tenant com filtros e paginacao.

Retorna documento com todas as linhas. Filtrado pelo tenant autenticado.

Atualizar documento em estado DRAFT. Documentos COMMITTED ou CANCELLED sao imutaveis.

Eliminar documento em DRAFT. Documentos COMMITTED ou CANCELLED nao podem ser eliminados.

Transforma documento DRAFT em COMMITTED. Processo irreversivel que inclui: calculo de totais, numeracao sequencial, assinatura RSA-SHA1, ATCUD e QR Code.

Sequencia atomica

1. Lock pessimista na serie (SELECT FOR UPDATE)
2. Calcular totais (net, tax, gross)
3. Atribuir numero sequencial
4. Buscar previous_hash (cadeia de hash)
5. Assinar com RSA-SHA1 (PKCS1v15)
6. Gerar ATCUD e QR Code
7. Marcar COMMITTED

curl -X POST https://api.billingcore.pt/api/v1/documents/{id}/commit \
  -H "Authorization: Bearer <token>" \
  -H "Idempotency-Key: commit-unique-key"

{
  "message": "Document committed successfully",
  "document": {
    "id": "550e8400-...",
    "type": "FT",
    "status": "COMMITTED",
    "document_no": 1,
    "gross_total": "246.00",
    "tax_total": "46.00",
    "net_total": "200.00",
    "hash": "base64-rsa-sha1-signature...",
    "atcud": "ABCD1234-1",
    "qr_payload": "A:500000001*B:999999990*..."
  }
}

Cancelar documento COMMITTED. O cancelamento e irreversivel. O campo reason e obrigatorio. Campos fiscais permanecem imutaveis.

Criar nota de credito (NC) referenciando fatura original. Criada em DRAFT, deve ser committed separadamente. So pode referenciar faturas (FT) COMMITTED.

Obter URL publico de download do PDF. Retorna JSON com download_url.

Descarregar ficheiro PDF com QR code embebido. Inclui dados do emitente, cliente, linhas, totais, ATCUD e hash. So documentos COMMITTED ou CANCELLED.

Criar cliente. O NIF e validado pelo algoritmo mod 11 portugues.

curl -X POST https://api.billingcore.pt/api/v1/customers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Empresa XYZ Lda.",
    "nif": "999999990",
    "address": {
      "street": "Rua da Liberdade 100",
      "city": "Lisboa",
      "postal_code": "1250-096",
      "country": "PT"
    }
  }'

Listar clientes com paginacao. Filtros: nif, search (pesquisa por nome).

Obter cliente por ID.

Atualizar campos do cliente. Todos os campos sao opcionais.

Remover cliente. Falha com 409 se tiver documentos associados.

Criar produto/servico.

Listar produtos. Filtros: code, is_active, search.

Obter produto por ID.

Atualizar campos do produto.

Desativar produto (soft delete). O produto nao e eliminado, apenas marcado como inativo.

Criar serie de documentos.

Listar series. Filtro: status (active, suspended, closed).

Obter serie por ID.

Atualizar serie (status, validation_code). Transicoes: active → suspended → closed. Serie fechada nao pode ser reaberta.

Criar utilizador. Email deve ser unico dentro do tenant.

Listar utilizadores. Filtros: role, is_active.

Obter utilizador por ID.

Atualizar role ou estado do utilizador.

Desativar utilizador (soft delete).

Criar app OAuth2. O client_secret so e retornado nesta resposta — guardar de imediato.

Listar apps do tenant.

Obter app por ID.

Atualizar nome, webhook_url ou scopes.

Remover app permanentemente.

Solicitar exportacao SAF-T PT (assincrona). Conforme Portaria 321-A/2007 (v1.04_01). O ficheiro XML e gerado em background.

{
  "id": "uuid-do-export",
  "status": "pending",
  "start_date": "2026-01-01",
  "end_date": "2026-12-31"
}

Verificar estado: pending, processing, completed, failed.

Obter URL de download do ficheiro XML. So disponivel apos status completed.

Estatisticas agregadas do tenant. Revenue so conta documentos COMMITTED (subtrai NC). DRAFT excluido por default.

curl "https://api.billingcore.pt/api/v1/stats?start_date=2026-01-01&end_date=2026-12-31" \
  -H "Authorization: Bearer <token>"

{
  "period": { "start": "2026-01-01", "end": "2026-12-31" },
  "documents": {
    "total": 150,
    "by_type": { "FT": 100, "FR": 20, "NC": 5 },
    "by_status": { "COMMITTED": 140, "CANCELLED": 10 }
  },
  "revenue": {
    "gross_total": "18500.00",
    "net_total": "15041.46",
    "tax_total": "3458.54",
    "currency": "EUR"
  },
  "top_customers": [
    {
      "customer_id": "uuid",
      "name": "Cliente X",
      "gross_total": "5000.00",
      "document_count": 10
    }
  ],
  "series": [
    {
      "series_id": "uuid",
      "code": "FT2026",
      "last_document_no": 100,
      "status": "active"
    }
  ]
}