Atura
Atura

API Atura

Emissão de Documentos

Oficial

Emite documentos oficiais conformes com a Autoridade Tributária. Converte rascunhos em faturas, notas de crédito e outros documentos fiscais válidos.

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 é a Emissão de Documentos?

A emissão de documentos converte rascunhos em documentos fiscais oficiais com numeração sequencial, conformes com as normas da Autoridade Tributária e SAF-T.

Oficial

Documentos com validade fiscal

Conforme AT

Totalmente compatível com SAF-T

Numeração

Sequencial e automática

Emitir Documento

POST/v1/documents/issue

Emite um documento oficial a partir de um rascunho existente ou criando um novo documento diretamente.

Exemplo: Emitir a partir de Rascunho

JSON
POST /v1/documents/issue
Content-Type: application/json
Authorization: Bearer atura_live_1234...

{
  "draft_id": "draft_abc123def456",
  "issue_date": "2025-01-15",
  "due_date": "2025-02-15",
  "auto_send": true,
  "send_options": {
    "email": true,
    "pdf_attachment": true
  }
}

Resposta

JSON
{
  "id": "doc_xyz789abc123",
  "type": "invoice",
  "series": "FA",
  "number": "FA/2025/00001",
  "status": "issued",
  "hash": "mJizdWTv6+5+u2sXXhk2eMxkCz9L5nKlMKNlhqLkWTc=",
  "customer": {
    "id": "cust_xyz789uvw012",
    "name": "Empresa Exemplo, Lda.",
    "email": "contabilidade@exemplo.com",
    "tax_id": "123456789"
  },
  "items": [
    {
      "id": "item_111222333444",
      "description": "Serviços de consultoria",
      "quantity": 10,
      "unit": "hora",
      "unit_price": 50.00,
      "tax_rate": 23,
      "tax_amount": 115.00,
      "total": 615.00
    }
  ],
  "subtotal": 575.50,
  "tax_total": 120.87,
  "total": 646.37,
  "currency": "EUR",
  "issue_date": "2025-01-15",
  "due_date": "2025-02-15",
  "pdf_url": "https://api.atura.pt/documents/doc_xyz789abc123/pdf",
  "xml_url": "https://api.atura.pt/documents/doc_xyz789abc123/xml",
  "created_at": "2025-01-15T14:30:00Z",
  "issued_at": "2025-01-15T14:30:00Z"
}

Emissão Direta

Podes emitir um documento diretamente sem criar um rascunho primeiro, ideal para integrações automáticas.

Exemplo: Emissão Direta

JSON
POST /v1/documents/issue
Content-Type: application/json
Authorization: Bearer atura_live_1234...

{
  "type": "invoice",
  "series": "FA",
  "customer": {
    "name": "Cliente Direto, Lda.",
    "email": "financeiro@cliente.com",
    "tax_id": "987654321",
    "address": {
      "street": "Av. da República, 456",
      "city": "Porto",
      "postal_code": "4000-001",
      "country": "PT"
    }
  },
  "items": [
    {
      "description": "Licença de Software Anual",
      "quantity": 1,
      "unit": "licença",
      "unit_price": 1200.00,
      "tax_rate": 23
    }
  ],
  "issue_date": "2025-01-15",
  "due_date": "2025-01-30",
  "notes": "Licença válida de Janeiro 2025 a Janeiro 2026",
  "auto_send": true
}

Estados do Documento

Estados Possíveis

  • issued - Documento emitido com sucesso
  • sent - Enviado ao cliente por email
  • pending - Aguarda processamento
  • cancelled - Documento cancelado

Verificações AT

  • • Hash SHA-256 gerado automaticamente
  • • Numeração sequencial garantida
  • • Validação de dados fiscais
  • • Conformidade SAF-T automática

Consultar Documento

GET/v1/documents/{id}

Obtém os detalhes completos de um documento emitido, incluindo URLs para PDF e XML.

Exemplo

JSON
GET /v1/documents/doc_xyz789abc123

{
  "id": "doc_xyz789abc123",
  "type": "invoice",
  "series": "FA",
  "number": "FA/2025/00001",
  "status": "sent",
  "hash": "mJizdWTv6+5+u2sXXhk2eMxkCz9L5nKlMKNlhqLkWTc=",
  "customer": {
    "name": "Empresa Exemplo, Lda.",
    "tax_id": "123456789"
  },
  "total": 646.37,
  "currency": "EUR",
  "issue_date": "2025-01-15",
  "due_date": "2025-02-15",
  "pdf_url": "https://api.atura.pt/documents/doc_xyz789abc123/pdf",
  "xml_url": "https://api.atura.pt/documents/doc_xyz789abc123/xml",
  "sent_at": "2025-01-15T14:35:00Z",
  "created_at": "2025-01-15T14:30:00Z",
  "issued_at": "2025-01-15T14:30:00Z"
}

Tratamento de Erros

400 Bad Request

Dados inválidos ou em falta no pedido.

JSON
{
  "error": {
    "type": "validation_error",
    "code": "missing_required_field",
    "message": "O campo 'customer.tax_id' é obrigatório",
    "field": "customer.tax_id"
  }
}

422 Unprocessable Entity

Erro de validação fiscal ou compliance.

JSON
{
  "error": {
    "type": "compliance_error",
    "code": "invalid_tax_id",
    "message": "O NIF fornecido não é válido para Portugal",
    "details": {
      "tax_id": "123456789",
      "validation": "checksum_failed"
    }
  }
}

Importante

Uma vez emitido, um documento não pode ser editado. Para correções, deves emitir uma nota de crédito e um novo documento.