API Atura

Séries Documentais

Configuração

Gere as séries documentais da tua empresa, define numeração sequencial e configura prefixos personalizados para diferentes tipos de documento.

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.

Sistema de Séries Documentais

As séries documentais definem como os teus documentos são numerados e organizados. Cada série tem um prefixo único e numeração sequencial automática.

Automática

Numeração sequencial garantida

Organizadas

Diferentes séries por tipo

Personalizáveis

Prefixos e formatos à medida

Listar Séries

GET/v1/documents/series

Lista todas as séries documentais configuradas para a tua empresa.

Resposta

JSON

{
  "series": [
    {
      "id": "series_fa_001",
      "code": "FA",
      "name": "Faturas",
      "description": "Série principal de faturas",
      "prefix": "FA",
      "format": "FA/{year}/{number}",
      "document_type": "invoice",
      "current_number": 142,
      "next_number": 143,
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "series_ft_001",
      "code": "FT",
      "name": "Faturas-Recibo",
      "description": "Faturas com função de recibo",
      "prefix": "FT",
      "format": "FT/{year}/{number}",
      "document_type": "invoice_receipt",
      "current_number": 87,
      "next_number": 88,
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "series_nc_001",
      "code": "NC",
      "name": "Notas de Crédito",
      "description": "Série para devoluções e correções",
      "prefix": "NC",
      "format": "NC/{year}/{number}",
      "document_type": "credit_note",
      "current_number": 12,
      "next_number": 13,
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 3,
  "page": 1,
  "per_page": 50
}

Criar Série

POST/v1/documents/series

Cria uma nova série documental com configurações personalizadas.

Exemplo de Pedido

JSON

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

{
  "code": "VD",
  "name": "Vendas Online",
  "description": "Série dedicada a vendas do website",
  "prefix": "VD",
  "format": "VD/{year}/{number:04d}",
  "document_type": "invoice",
  "starting_number": 1,
  "year_reset": true,
  "status": "active"
}

Resposta

JSON

{
  "id": "series_vd_001",
  "code": "VD",
  "name": "Vendas Online",
  "description": "Série dedicada a vendas do website",
  "prefix": "VD",
  "format": "VD/{year}/{number:04d}",
  "document_type": "invoice",
  "current_number": 0,
  "next_number": 1,
  "year_reset": true,
  "status": "active",
  "created_at": "2025-01-15T14:30:00Z"
}

Atualizar Série

PUT/v1/documents/series/{id}

Atualiza as configurações de uma série existente. Apenas campos de metadata podem ser alterados.

Exemplo

JSON

PUT /v1/documents/series/series_vd_001
Content-Type: application/json
Authorization: Bearer atura_live_1234...

{
  "name": "E-commerce",
  "description": "Série para todas as vendas online",
  "status": "active"
}

Tipos de Documento

Cada série é associada a um tipo específico de documento fiscal:

Tipo	Código SAF-T	Série Comum	Descrição
invoice	FT	FA, FT	Faturas normais
invoice_receipt	FR	FT	Faturas-recibo
credit_note	NC	NC	Notas de crédito
debit_note	ND	ND	Notas de débito
receipt	RC	RC	Recibos
transport	GT	GT	Guias de transporte

Padrões de Formato

Define o formato da numeração usando os seguintes padrões:

Variáveis Disponíveis

{prefix} - Prefixo da série (ex: FA)
{year} - Ano atual (ex: 2025)
{year:2d} - Ano com 2 dígitos (ex: 25)
{number} - Número sequencial
{number:04d} - Número com zeros à esquerda
{month} - Mês atual (ex: 01)

Exemplos

FA/{year}/{number:04d}
→ FA/2025/0001

{prefix}-{year:2d}{month}-{number}
→ FT-2501-142

{number:06d}
→ 000001

Estado das Séries

PATCH/v1/documents/series/{id}/status

Altera o estado de uma série para ativar, desativar ou arquivar.

Estados Possíveis

active - Série ativa, aceita novos documentos
inactive - Inativa, não aceita novos documentos
archived - Arquivada permanentemente

Exemplo

JSON

PATCH /v1/documents/series/series_vd_001/status

{
  "status": "inactive",
  "reason": "Série temporariamente suspensa"
}

Boas Práticas

✅ Recomendado

• Usar códigos de série únicos e descritivos
• Definir formatos consistentes para toda a empresa
• Separar séries por canal de venda ou departamento
• Configurar reset anual para controlo simples
• Documentar o propósito de cada série
• Testar numeração antes de usar em produção

❌ Evitar

• Alterar formato após emitir documentos
• Usar caracteres especiais nos prefixos
• Criar séries em excesso sem necessidade
• Definir numeração inicial muito alta
• Misturar tipos de documento numa série
• Arquivar séries com documentos pendentes

Numeração Sequencial

A numeração é gerida automaticamente pela API. Nunca haverá saltos ou duplicações, garantindo conformidade total com os requisitos da Autoridade Tributária.

Séries Documentais

Configuração

Gere as séries documentais da tua empresa, define numeração sequencial e configura prefixos personalizados para diferentes tipos de documento.

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.

Sistema de Séries Documentais

As séries documentais definem como os teus documentos são numerados e organizados. Cada série tem um prefixo único e numeração sequencial automática.

Automática

Numeração sequencial garantida

Organizadas

Diferentes séries por tipo

Personalizáveis

Prefixos e formatos à medida

Listar Séries

GET/v1/documents/series

Lista todas as séries documentais configuradas para a tua empresa.

Resposta

JSON

{
  "series": [
    {
      "id": "series_fa_001",
      "code": "FA",
      "name": "Faturas",
      "description": "Série principal de faturas",
      "prefix": "FA",
      "format": "FA/{year}/{number}",
      "document_type": "invoice",
      "current_number": 142,
      "next_number": 143,
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "series_ft_001",
      "code": "FT",
      "name": "Faturas-Recibo",
      "description": "Faturas com função de recibo",
      "prefix": "FT",
      "format": "FT/{year}/{number}",
      "document_type": "invoice_receipt",
      "current_number": 87,
      "next_number": 88,
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "series_nc_001",
      "code": "NC",
      "name": "Notas de Crédito",
      "description": "Série para devoluções e correções",
      "prefix": "NC",
      "format": "NC/{year}/{number}",
      "document_type": "credit_note",
      "current_number": 12,
      "next_number": 13,
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 3,
  "page": 1,
  "per_page": 50
}

Criar Série

POST/v1/documents/series

Cria uma nova série documental com configurações personalizadas.

Exemplo de Pedido

JSON

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

{
  "code": "VD",
  "name": "Vendas Online",
  "description": "Série dedicada a vendas do website",
  "prefix": "VD",
  "format": "VD/{year}/{number:04d}",
  "document_type": "invoice",
  "starting_number": 1,
  "year_reset": true,
  "status": "active"
}

Resposta

JSON

{
  "id": "series_vd_001",
  "code": "VD",
  "name": "Vendas Online",
  "description": "Série dedicada a vendas do website",
  "prefix": "VD",
  "format": "VD/{year}/{number:04d}",
  "document_type": "invoice",
  "current_number": 0,
  "next_number": 1,
  "year_reset": true,
  "status": "active",
  "created_at": "2025-01-15T14:30:00Z"
}

Atualizar Série

PUT/v1/documents/series/{id}

Atualiza as configurações de uma série existente. Apenas campos de metadata podem ser alterados.

Exemplo

JSON

PUT /v1/documents/series/series_vd_001
Content-Type: application/json
Authorization: Bearer atura_live_1234...

{
  "name": "E-commerce",
  "description": "Série para todas as vendas online",
  "status": "active"
}

Tipos de Documento

Cada série é associada a um tipo específico de documento fiscal:

Tipo	Código SAF-T	Série Comum	Descrição
invoice	FT	FA, FT	Faturas normais
invoice_receipt	FR	FT	Faturas-recibo
credit_note	NC	NC	Notas de crédito
debit_note	ND	ND	Notas de débito
receipt	RC	RC	Recibos
transport	GT	GT	Guias de transporte

Padrões de Formato

Define o formato da numeração usando os seguintes padrões:

Variáveis Disponíveis

{prefix} - Prefixo da série (ex: FA)
{year} - Ano atual (ex: 2025)
{year:2d} - Ano com 2 dígitos (ex: 25)
{number} - Número sequencial
{number:04d} - Número com zeros à esquerda
{month} - Mês atual (ex: 01)

Exemplos

FA/{year}/{number:04d}
→ FA/2025/0001

{prefix}-{year:2d}{month}-{number}
→ FT-2501-142

{number:06d}
→ 000001

Estado das Séries

PATCH/v1/documents/series/{id}/status

Altera o estado de uma série para ativar, desativar ou arquivar.

Estados Possíveis

active - Série ativa, aceita novos documentos
inactive - Inativa, não aceita novos documentos
archived - Arquivada permanentemente

Exemplo

JSON

PATCH /v1/documents/series/series_vd_001/status

{
  "status": "inactive",
  "reason": "Série temporariamente suspensa"
}

Boas Práticas

✅ Recomendado

• Usar códigos de série únicos e descritivos
• Definir formatos consistentes para toda a empresa
• Separar séries por canal de venda ou departamento
• Configurar reset anual para controlo simples
• Documentar o propósito de cada série
• Testar numeração antes de usar em produção

❌ Evitar

• Alterar formato após emitir documentos
• Usar caracteres especiais nos prefixos
• Criar séries em excesso sem necessidade
• Definir numeração inicial muito alta
• Misturar tipos de documento numa série
• Arquivar séries com documentos pendentes

Numeração Sequencial

A numeração é gerida automaticamente pela API. Nunca haverá saltos ou duplicações, garantindo conformidade total com os requisitos da Autoridade Tributária.