Faturas → AT

Tire uma foto de uma fatura. A API valida, o contabilista aprova, e é enviada directamente para a Autoridade Tributária.

Como funciona

Tire uma foto da fatura Utilizador

No chat com o seu assistente de IA (Claude, ChatGPT, Gemini), envie a foto. A IA lê a imagem e extrai: NIF do fornecedor, valores, taxa de IVA, data, número da fatura.

A API valida automaticamente Automático

O NIF é verificado com o algoritmo oficial de checksum. A taxa de IVA é confirmada para a região (Continente, Açores ou Madeira). O cálculo do IVA e o total são recalculados e comparados com os valores na fatura.

A fatura vai para o contabilista Automático

A fatura validada entra na fila do contabilista da empresa. Se o contabilista tiver regras de aprovação automática (ex: faturas abaixo de 100€ de fornecedores conhecidos), a fatura pode ser aprovada instantaneamente.

O contabilista revê e aprova Contabilista

O contabilista recebe as faturas no seu assistente de IA — sem emails, sem WhatsApp. Revê os dados, aprova ou rejeita com uma mensagem no chat.

Envio automático para a AT Automático

A fatura aprovada é enviada directamente para o Portal das Finanças via o webservice oficial da AT (e-Fatura). O contabilista configura as credenciais AT uma vez — nunca mais precisa de as inserir.

Quem faz o quê

Empresário / Utilizador

Tira foto da fatura e envia no chat
Pronto. Não precisa de credenciais da AT, não precisa de software de facturação, não precisa de saber o que é IVA

Contabilista

Regista-se na plataforma (uma vez)
Configura as credenciais do webservice da AT (uma vez)
Define regras de aprovação automática (opcional)
Revê e aprova faturas no chat — ou deixa as regras fazerem o trabalho

A API (api.ptdata.org)

Valida NIFs, IVA, e totais
Encaminha faturas para o contabilista certo
Aplica regras de aprovação automática
Submete para a AT via SOAP (WS-Security com AES-ECB + RSA)
Guarda credenciais AT encriptadas com AES-256-GCM

Registo passo a passo

Para o contabilista

Registar na plataforma — Envie o seu NIF, nome e email. Recebe uma API key (guardar em segurança — só aparece uma vez).
Obter credenciais AT para webservice — No Portal das Finanças (faturas.portaldasfinancas.gov.pt), entre como Produtor de Software e clique em "Aderir ao serviço". Isto dá-lhe um par NIF/sub-utilizador/password específico para o webservice (diferente da password normal do Portal).
Configurar credenciais AT na plataforma — Use a API key para guardar as credenciais AT. Ficam encriptadas e nunca são visíveis depois.
Definir regras de aprovação (opcional) — Configure limites para aprovação automática (ex: faturas abaixo de 100€, fornecedores conhecidos).

Para a empresa

Registar na plataforma — Envie o NIF da empresa, nome e email. Recebe uma API key.
Associar contabilista — Indique o NIF do contabilista para receber as faturas.
Começar a enviar faturas — Tire fotos e envie via o assistente de IA. Pronto.

Configuração técnica (API)

Tudo é feito via chat ou API — sem portais web.

# 1. Registar como contabilista
curl -X POST https://api.ptdata.org/v1/fiscal/accountants \
  -H "Content-Type: application/json" \
  -d '{"nif":"500000000","name":"Exemplo Contabilidade","email":"contabilidade@exemplo.pt"}'
# → Devolve uma API key (guardar — só aparece uma vez)

# 2. Configurar credenciais AT (uma vez)
curl -X PUT https://api.ptdata.org/v1/fiscal/accountants/500000000/at-credentials \
  -H "Authorization: Bearer ptdata_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"nif":"500000000","sub_user":"0","password":"****"}'
# → Credenciais encriptadas e guardadas em segurança

# 3. Definir regras de aprovação automática
curl -X PUT https://api.ptdata.org/v1/fiscal/accountants/500000000/rules \
  -H "Authorization: Bearer ptdata_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"auto_approve_below":100,"auto_approve_known_suppliers":true,"auto_submit_to_at":true}'

Envio de uma fatura

# A empresa envia a fatura (após a IA extrair os dados da foto)
curl -X POST https://api.ptdata.org/v1/fiscal/platform/invoices \
  -H "Authorization: Bearer ptdata_empresa_key..." \
  -H "Content-Type: application/json" \
  -d '{
    "supplier_nif": "500000018",
    "invoice_number": "FT 2026/123",
    "invoice_date": "2026-04-09",
    "description": "Fornecimento de material de escritório",
    "net_total": 81.30,
    "vat_rate": 23,
    "vat_amount": 18.70,
    "total": 100.00
  }'
# → Se regra auto_approve_below=100 está activa:
#   status: "approved" + submetida para a AT automaticamente

Via MCP (assistentes de IA)

Qualquer assistente de IA com MCP pode fazer tudo isto automaticamente:

# Configuração do MCP no Claude Code / Claude Desktop
{
  "mcpServers": {
    "ptdata": {
      "type": "url",
      "url": "https://api.ptdata.org/mcp"
    }
  }
}

Ferramentas MCP disponíveis para faturas:

validate_invoice — valida dados extraídos de uma foto
submit_platform_invoice — envia fatura para fila do contabilista
list_platform_invoices — lista faturas (pendentes, aprovadas, rejeitadas)
review_invoice — contabilista aprova ou rejeita
configure_at_credentials — contabilista configura credenciais AT
format_invoice_for_accountant — formata dados para email

Segurança

Dados de faturas encriptados — Todos os campos sensíveis (NIFs, valores, descrições) são encriptados antes de serem guardados. Nunca em texto simples.
Credenciais AT encriptadas — As credenciais do contabilista são encriptadas com chaves aleatórias. Nunca guardadas em texto simples.
Passwords nunca expostas — A password nunca aparece em logs, respostas da API, ou na base de dados.
Autenticação obrigatória — Todas as operações sensíveis requerem API key.
Certificado AT assinado — Comunicação segura com a Autoridade Tributária via certificado digital oficial.
Rate limiting — Limites por endpoint e por IP para prevenir abuso.

Precisa de ajuda?

Contacte hello@ptdata.org — ou pergunte ao seu assistente de IA usando o MCP.