Documentação para programadores

API da Fiscolify

Faturação certificada pela AT, como uma API. Emita faturas, comunique séries, gere o SAF-T e receba webhooks — tudo numa REST API com paridade entre sandbox e produção.

Começar Criar chave de API

URL base /v1Especificação OpenAPI 3.0

Introdução

A Fiscolify é uma infraestrutura de conformidade fiscal certificada pela AT — pense nela como o «Stripe da faturação portuguesa». Todos os pedidos partem do prefixo /v1.

A API permite emitir documentos fiscais (FT, FS, NC, ND, RC, GT), registar séries junto da AT, despoletar exportações SAF-T (PT) e subscrever webhooks para cada mudança de estado.

A Fiscolify é software certificado pela AT. Cada documento emitido em produção leva ATCUD, hash de assinatura, código QR e o número de certificação no PDF — assumimos a responsabilidade fiscal para que a sua integração não tenha de o fazer.

Produção

Documentos com validade fiscal real, comunicados à AT. Use uma chave sem sandbox_mode.

Sandbox

Paridade total com produção para testes, mas SEM validade fiscal. Os documentos de sandbox nunca são comunicados à AT.

URL base

bash

# Production
https://api.certifica.pt/v1

# Sandbox (test keys, no fiscal validity)
https://api.certifica.pt/v1  # with a sandbox_mode API key

Autenticação

Os consumidores REST autenticam-se com uma chave de API; a interface web usa uma sessão. As chaves têm âmbitos (scopes) e um ambiente fixo.

Chave de API (REST)

Envie a sua chave no cabeçalho Authorization como um Bearer token. As chaves são secretas, mostradas uma única vez e podem ser revogadas a qualquer momento.

bash

curl https://api.certifica.pt/v1/documents \
  -H "Authorization: Bearer sk_live_••••••••••••"

Sessão web (interface web)

A aplicação web autentica os utilizadores com uma sessão do lado do servidor. As sessões não servem para integração servidor-a-servidor — para isso, crie uma chave de API.

Âmbitos (scopes)

documents:write: Emitir, anular e gerir documentos e séries.
documents:read: Ler documentos, séries e entidades.
exports:read: Despoletar e ler exportações SAF-T.

O sandbox_mode tem de corresponder ao ambiente da série

Uma chave de sandbox só pode operar sobre séries de sandbox e vice-versa. Uma incompatibilidade devolve 409 ENVIRONMENT_MISMATCH — confirme sempre que o ambiente da chave coincide com o da série.

Crie e faça a gestão das suas chaves na área de chaves de API.

Referência de endpoints

Todos os endpoints de escrita exigem o âmbito adequado e correspondência de ambiente (BR-103). As respostas usam JSON; os montantes são em EUR com 2 casas decimais.

POST/v1/documents

Emitir um documento fiscal

Cria e assina um documento (FT, FS, NC, ND, RC, GT). Devolve o ATCUD, o hash, os dados do QR e a ligação para o PDF/A-3.

Corpo do pedido

type: Tipo de documento: FT, FS, NC, ND, RC ou GT.
series_id: ID da série registada onde o documento é numerado.
party: Entidade (cliente): NIF, nome e morada.
lines[]: Linhas do documento: descrição, quantidade, preço, código e taxa de IVA.
tax_info: Informação de imposto agregada por taxa e região.

bash

curl -X POST https://api.certifica.pt/v1/documents \
  -H "Authorization: Bearer sk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "FT",
    "series_id": "ser_2026_ft_a",
    "party": { "nif": "501234567", "name": "Cliente Lda" },
    "lines": [
      { "description": "Consultoria", "quantity": 1,
        "unit_price": 1000.00, "tax_code": "NOR", "tax_rate": 23 }
    ]
  }'

json

{
  "id": "doc_a1b2c3",
  "number": "FT A/2026/1",
  "atcud": "AJ7K2P9QX-1",
  "hash": "kF3a",
  "qr_code_data": "A:501234567*B:599999999*C:PT*...",
  "pdf_url": "https://files.certifica.pt/doc_a1b2c3.pdf",
  "at_status": "N",
  "at_communication_status": null
}

A resposta inclui sempre atcud, hash e qr_code_data. Para uma Guia de Transporte (GT), o at_communication_status pode vir como «deferred» quando a comunicação à AT é diferida (BR-105).

POST/v1/documents/{id}/void

Anular um documento

Emite uma nota de crédito (NC) ou de débito (ND) que referencia o documento original. Os documentos são imutáveis — não há edição, apenas anulação.

bash

curl -X POST https://api.certifica.pt/v1/documents/doc_a1b2c3/void \
  -H "Authorization: Bearer sk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "NC", "scope": "full" }'

GET/v1/documents

Listar e obter documentos

Lista documentos com filtros e paginação, ou obtém um documento único pelo seu ID. Requer o âmbito documents:read.

bash

curl "https://api.certifica.pt/v1/documents?type=FT&page=1" \
  -H "Authorization: Bearer sk_live_••••"

# Single document
curl https://api.certifica.pt/v1/documents/doc_a1b2c3 \
  -H "Authorization: Bearer sk_live_••••"

POST/v1/series

Registar e listar séries

Regista uma série junto da AT (RegistarSeriesDocumentos), devolvendo o código de validação. Liste as séries existentes do tenant.

bash

# Register a series with the AT (RegistarSeriesDocumentos)
curl -X POST https://api.certifica.pt/v1/series \
  -H "Authorization: Bearer sk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{ "series_code": "A", "document_type": "FT",
        "fiscal_year": 2026, "environment": "production" }'

# List series
curl https://api.certifica.pt/v1/series \
  -H "Authorization: Bearer sk_live_••••"

POST/v1/saft/exports

Exportações SAF-T (PT)

Despoleta uma exportação SAF-T para um período e sonda o estado até obter a ligação de descarregamento. Requer o âmbito exports:read.

bash

# Trigger a SAF-T (PT) export
curl -X POST https://api.certifica.pt/v1/saft/exports \
  -H "Authorization: Bearer sk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{ "period_start": "2026-01-01", "period_end": "2026-01-31" }'

# Poll status + download link
curl https://api.certifica.pt/v1/saft/exports/exp_99 \
  -H "Authorization: Bearer sk_live_••••"

A exportação fica bloqueada enquanto existirem Guias de Transporte por comunicar à AT (BR-100).

GET/v1/parties

Entidades

Pesquisa e obtém entidades (clientes/fornecedores) por NIF para reutilizar na emissão.

bash

curl "https://api.certifica.pt/v1/parties?nif=501234567" \
  -H "Authorization: Bearer sk_live_••••"

POST/v1/webhooks

Subscrever webhooks

Regista um endpoint para receber eventos assinados. O segredo HMAC é devolvido uma única vez — guarde-o de imediato.

bash

curl -X POST https://api.certifica.pt/v1/webhooks \
  -H "Authorization: Bearer sk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/certifica",
    "events": ["document.issued", "document.voided"]
  }'

json

{
  "id": "whk_77",
  "url": "https://example.com/hooks/certifica",
  "events": ["document.issued", "document.voided"],
  "secret": "whsec_a1b2c3d4e5f6"  // shown once — store it now
}

Webhooks

A Fiscolify emite webhooks assinados por HMAC em cada mudança de estado. Verifique sempre a assinatura antes de confiar no payload.

Catálogo de eventos

document.issued: Um documento foi emitido e assinado com sucesso.
document.voided: Um documento foi anulado por uma NC/ND.
gt.communication_result: Resultado da comunicação de uma Guia de Transporte à AT (comunicada, diferida ou falhada).
saft.ready: Uma exportação SAF-T concluiu e está disponível para descarregamento.
b2g.status_changed: O estado de entrega de um documento B2G (CIUS-PT / FE-AP) mudou.
apikey.expiring: Uma chave de API está prestes a expirar (T-7 dias e T-1 dia).
apikey.expired: Uma chave de API expirou e deixou de autenticar.

Assinatura HMAC

Cada pedido inclui o cabeçalho X-Fiscolify-Signature com um timestamp e um HMAC-SHA256 do corpo, calculado com o segredo da subscrição. Recalcule-o do seu lado e compare antes de processar o evento.

bash

X-Certifica-Signature: t=1718000000,
  v1=5257a869e7ec...   # HMAC-SHA256(secret, "{t}.{raw_body}")

Repetições e backoff

As entregas falhadas são repetidas com backoff exponencial. Após esgotar as tentativas, o evento passa a «dead-letter» e pode ser reenviado manualmente. Responda 2xx em poucos segundos para confirmar a receção.

Erros

Os erros usam códigos 4xx tipados com um corpo JSON consistente. Use sempre o campo code para ramificar a sua lógica, não a mensagem.

Forma do erro

json

{
  "code": "VALIDATION_ERROR",
  "message": "NIF checksum is invalid.",
  "field": "party.nif"
}

422VALIDATION_ERROR: Falha de validação: campos em falta, NIF inválido, taxa/região de IVA incorreta ou montante mal formatado. O campo field indica a origem.
409ENVIRONMENT_MISMATCH: O sandbox_mode da chave não corresponde ao ambiente da série.
409SEQUENCE_CONFLICT: Conflito de sequência na numeração da série — repita o pedido.
422FS_NOT_ALLOWED_FOR_PUBLIC_BODY: Não é permitido emitir uma Fatura Simplificada (FS) a uma entidade pública. Emita antes uma FT para CIUS-PT (BR-109).
401API_KEY_EXPIRED: A chave de API expirou (distinto de revogada). Crie uma nova chave.
401API_KEY_REVOKED: A chave de API foi revogada e já não é válida.

Pronto para integrar?

Crie uma chave de API de sandbox e emita o seu primeiro documento de teste em minutos. Quando estiver pronto, mude para uma chave de produção.

Criar chave de API