Atura
Atura

API Atura

Gerar SAF-T

Conformidade AT

Gera ficheiros SAF-T (PT) conformes com a Autoridade Tributária para auditoria fiscal e submissão obrigatória.

Documentação em Desenvolvimento

Esta documentação está ainda em desenvolvimento ativo. Algumas secções podem estar incompletas ou sujeitas a alterações. Para questões específicas, contacta o nosso suporte técnico.

O que é o SAF-T?

O Standard Audit File for Tax (SAF-T) é um ficheiro XML padronizado que contém informação contabilística e fiscal de uma empresa, exigido pela Autoridade Tributária portuguesa.

Automático

Geração automática XML

Conforme AT

Validado segundo portaria

Período

Mensal ou por intervalo

Gerar Ficheiro SAF-T

POST/v1/saft/generate

Inicia a geração de um ficheiro SAF-T para o período especificado. O processo é assíncrono.

Exemplo de Pedido

JSON
POST /v1/saft/generate
Content-Type: application/json
Authorization: Bearer atura_live_1234...

{
  "period": {
    "start_date": "2025-01-01",
    "end_date": "2025-01-31"
  },
  "type": "monthly",
  "include_customers": true,
  "include_suppliers": true,
  "include_products": true,
  "include_tax_table": true,
  "company_info": {
    "tax_registration_number": "123456789",
    "company_id": "12345",
    "tax_accounting_basis": "F",
    "tax_entity": "Global"
  },
  "audit_file_version": "1.04_01"
}

Resposta

JSON
{
  "id": "saft_gen_abc123def456",
  "status": "processing",
  "period": {
    "start_date": "2025-01-01",
    "end_date": "2025-01-31"
  },
  "type": "monthly",
  "estimated_completion": "2025-01-15T14:35:00Z",
  "progress": {
    "current_step": "extracting_documents",
    "completed_steps": ["validating_period", "preparing_data"],
    "total_steps": 6,
    "percentage": 33
  },
  "created_at": "2025-01-15T14:30:00Z"
}

Verificar Estado

GET/v1/saft/generate/{id}

Verifica o estado da geração do SAF-T e obtém informações sobre o progresso.

Exemplo: Concluído

JSON
{
  "id": "saft_gen_abc123def456",
  "status": "completed",
  "period": {
    "start_date": "2025-01-01",
    "end_date": "2025-01-31"
  },
  "progress": {
    "current_step": "completed",
    "percentage": 100
  },
  "file": {
    "filename": "SAFT_PT_123456789_2025_01.xml",
    "size": 2456789,
    "hash": "sha256:a1b2c3d4e5f6...",
    "download_url": "https://api.atura.pt/saft/download/saft_gen_abc123def456",
    "expires_at": "2025-01-22T14:35:00Z"
  },
  "statistics": {
    "documents_included": 1247,
    "customers_included": 89,
    "suppliers_included": 23,
    "products_included": 156,
    "total_gross_amount": 156789.45,
    "total_tax_amount": 32456.78
  },
  "validation": {
    "schema_valid": true,
    "at_compliant": true,
    "warnings": []
  },
  "created_at": "2025-01-15T14:30:00Z",
  "completed_at": "2025-01-15T14:35:12Z"
}

Exemplo: Em Processamento

JSON
GET /v1/saft/generate/saft_gen_abc123def456

{
  "id": "saft_gen_abc123def456",
  "status": "processing",
  "period": {
    "start_date": "2025-01-01",
    "end_date": "2025-01-31"
  },
  "progress": {
    "current_step": "generating_xml",
    "completed_steps": [
      "validating_period",
      "preparing_data",
      "extracting_documents",
      "extracting_customers",
      "extracting_products"
    ],
    "total_steps": 6,
    "percentage": 83
  },
  "statistics": {
    "documents_processed": 1247,
    "customers_processed": 89,
    "products_processed": 156,
    "estimated_file_size": "2.3MB"
  },
  "created_at": "2025-01-15T14:30:00Z",
  "updated_at": "2025-01-15T14:33:42Z"
}

Tipos de SAF-T

Diferentes tipos de SAF-T podem ser gerados conforme a necessidade:

Tipos Disponíveis

  • monthlySAF-T mensal (recomendado)
  • quarterlySAF-T trimestral
  • annualSAF-T anual
  • customPeríodo personalizado

Conteúdo Incluído

  • • Dados da empresa (Header)
  • • Tabela de clientes (MasterFiles)
  • • Tabela de produtos (MasterFiles)
  • • Tabela de impostos (MasterFiles)
  • • Documentos de venda (SourceDocuments)
  • • Movimentos contabilísticos (se aplicável)

Opções de Configuração

Dados da Empresa

JSON
"company_info": {
  "tax_registration_number": "123456789", // NIF obrigatório
  "company_id": "12345", // Conservatória ou similar
  "tax_accounting_basis": "F", // F=Faturação, C=Caixa, I=Contabilidade
  "tax_entity": "Global", // Sede global ou estabelecimento
  "currency_code": "EUR" // Código ISO da moeda
}

Filtros de Dados

JSON
"filters": {
  "include_customers": true, // Incluir tabela de clientes
  "include_suppliers": true, // Incluir tabela de fornecedores
  "include_products": true, // Incluir tabela de produtos
  "include_tax_table": true, // Incluir tabela de impostos
  "document_types": ["FT", "FS", "NC", "ND"], // Tipos a incluir
  "min_amount": 0, // Valor mínimo de documento
  "customer_ids": [] // Clientes específicos (vazio = todos)
}

Versão do Schema

Especifica a versão do schema SAF-T a usar:

  • • 1.04_01 - Versão atual recomendada
  • • 1.03_01 - Versão anterior (compatibilidade)

Estados do Processo

Estados Possíveis

  • queued - Na fila de processamento
  • processing - A processar dados
  • completed - Concluído com sucesso
  • failed - Falhou com erro
  • expired - Ficheiro expirou

Etapas de Processamento

  1. 1. Validação do período
  2. 2. Preparação de dados
  3. 3. Extração de documentos
  4. 4. Extração de clientes
  5. 5. Extração de produtos
  6. 6. Geração do XML

Listar Gerações

GET/v1/saft/generate

Lista todas as gerações de SAF-T, incluindo estado atual e histórico.

Exemplo

JSON
GET /v1/saft/generate?limit=10&status=completed

{
  "generations": [
    {
      "id": "saft_gen_abc123def456",
      "status": "completed",
      "type": "monthly",
      "period": {
        "start_date": "2025-01-01",
        "end_date": "2025-01-31"
      },
      "file": {
        "filename": "SAFT_PT_123456789_2025_01.xml",
        "size": 2456789,
        "expires_at": "2025-01-22T14:35:00Z"
      },
      "created_at": "2025-01-15T14:30:00Z",
      "completed_at": "2025-01-15T14:35:12Z"
    },
    {
      "id": "saft_gen_xyz789uvw012",
      "status": "completed",
      "type": "monthly",
      "period": {
        "start_date": "2024-12-01",
        "end_date": "2024-12-31"
      },
      "file": {
        "filename": "SAFT_PT_123456789_2024_12.xml",
        "size": 1987654,
        "expires_at": "2025-01-07T10:15:30Z"
      },
      "created_at": "2025-01-07T10:10:15Z",
      "completed_at": "2025-01-07T10:15:30Z"
    }
  ],
  "total": 24,
  "page": 1,
  "per_page": 10
}

Tratamento de Erros

400 Bad Request

Período inválido ou parâmetros em falta.

JSON
{
  "error": {
    "type": "validation_error",
    "code": "invalid_period",
    "message": "Data de início deve ser anterior à data de fim",
    "details": {
      "start_date": "2025-02-01",
      "end_date": "2025-01-31"
    }
  }
}

422 Unprocessable Entity

Erro durante a geração do SAF-T.

JSON
{
  "error": {
    "type": "generation_error",
    "code": "data_integrity_error",
    "message": "Foram encontrados documentos com dados inconsistentes",
    "details": {
      "invalid_documents": ["doc_123", "doc_456"],
      "issues": ["missing_tax_rate", "invalid_customer_data"]
    }
  }
}

Retenção de Ficheiros

Os ficheiros SAF-T gerados são mantidos durante 7 dias após a geração. Depois desse período, devem ser gerados novamente se necessário.