Atura
Atura

API Atura

Rascunhos de Documentos

Gestão

Cria, edita e gere rascunhos de documentos antes de os emitir oficialmente. Os rascunhos permitem-te preparar faturas, notas de crédito e outros documentos sem os oficializar.

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 são Rascunhos?

Os rascunhos são versões preliminares de documentos fiscais que podes criar, modificar e eliminar livremente. Quando estiveres satisfeito com o conteúdo, podes converter o rascunho num documento oficial.

Flexibilidade

Edita quantas vezes precisares

Sem Limites

Cria tantos rascunhos quanto necessário

Validação

Valida antes de oficializar

Criar Rascunho

POST/v1/documents/drafts

Cria um novo rascunho de documento. Podes especificar o tipo de documento, cliente, e itens.

Exemplo de Pedido

JSON
POST /v1/documents/drafts
Content-Type: application/json
Authorization: Bearer atura_test_1234...

{
  "type": "invoice",
  "series": "FA",
  "customer": {
    "name": "Empresa Exemplo, Lda.",
    "email": "contabilidade@exemplo.com",
    "tax_id": "123456789",
    "address": {
      "street": "Rua da Liberdade, 123",
      "city": "Lisboa",
      "postal_code": "1250-146",
      "country": "PT"
    }
  },
  "items": [
    {
      "description": "Serviços de consultoria",
      "quantity": 10,
      "unit": "hora",
      "unit_price": 50.00,
      "tax_rate": 23,
      "tax_exemption": null
    },
    {
      "description": "Despesas de deslocação",
      "quantity": 1,
      "unit": "un",
      "unit_price": 25.50,
      "tax_rate": 23,
      "tax_exemption": null
    }
  ],
  "notes": "Serviços prestados durante o mês de Janeiro",
  "due_date": "2025-02-15"
}

Resposta

JSON
{
  "id": "draft_abc123def456",
  "type": "invoice",
  "series": "FA",
  "status": "draft",
  "number": null,
  "customer": {
    "id": "cust_xyz789uvw012",
    "name": "Empresa Exemplo, Lda.",
    "email": "contabilidade@exemplo.com",
    "tax_id": "123456789",
    "address": {
      "street": "Rua da Liberdade, 123",
      "city": "Lisboa",
      "postal_code": "1250-146",
      "country": "PT"
    }
  },
  "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
    },
    {
      "id": "item_555666777888",
      "description": "Despesas de deslocação",
      "quantity": 1,
      "unit": "un",
      "unit_price": 25.50,
      "tax_rate": 23,
      "tax_amount": 5.87,
      "total": 31.37
    }
  ],
  "subtotal": 575.50,
  "tax_total": 120.87,
  "total": 646.37,
  "currency": "EUR",
  "notes": "Serviços prestados durante o mês de Janeiro",
  "due_date": "2025-02-15",
  "created_at": "2025-01-15T14:30:00Z",
  "updated_at": "2025-01-15T14:30:00Z"
}

Listar Rascunhos

GET/v1/documents/drafts

Obtém uma lista paginada de todos os rascunhos. Podes filtrar por tipo, cliente, ou período.

Parâmetros de Query

ParâmetroTipoDescrição
limitintegerNúmero de resultados por página (máx: 100, padrão: 20)
offsetintegerNúmero de resultados a saltar (padrão: 0)
typestringFiltrar por tipo: invoice, credit_note, debit_note
customer_idstringFiltrar por ID do cliente
created_afterstringFiltrar por data de criação (formato ISO 8601)

Exemplo

JSON
GET /v1/documents/drafts?type=invoice&limit=10&offset=0

{
  "data": [
    {
      "id": "draft_abc123def456",
      "type": "invoice",
      "status": "draft",
      "customer": {
        "id": "cust_xyz789uvw012",
        "name": "Empresa Exemplo, Lda."
      },
      "total": 646.37,
      "currency": "EUR",
      "created_at": "2025-01-15T14:30:00Z",
      "updated_at": "2025-01-15T14:30:00Z"
    }
  ],
  "has_more": false,
  "total_count": 1
}

Atualizar Rascunho

PATCH/v1/documents/drafts/{id}

Atualiza um rascunho existente. Podes modificar qualquer campo, adicionar/remover itens, ou alterar dados do cliente.

Exemplo: Adicionar Item

JSON
PATCH /v1/documents/drafts/draft_abc123def456

{
  "items": [
    {
      "id": "item_111222333444"
    },
    {
      "id": "item_555666777888"
    },
    {
      "description": "Taxa de urgência",
      "quantity": 1,
      "unit": "un",
      "unit_price": 15.00,
      "tax_rate": 23
    }
  ]
}

Eliminar Rascunho

DELETE/v1/documents/drafts/{id}

Elimina permanentemente um rascunho. Esta ação não pode ser desfeita.

Atenção

A eliminação de um rascunho é permanente e irreversível. Certifica-te de que não precisarás mais desta informação.

Exemplo

Bash
DELETE /v1/documents/drafts/draft_abc123def456

HTTP/1.1 204 No Content

Códigos de Estado

Sucesso

  • 200 - Rascunho obtido/atualizado com sucesso
  • 201 - Rascunho criado com sucesso
  • 204 - Rascunho eliminado com sucesso

Erro

  • 400 - Dados inválidos no pedido
  • 404 - Rascunho não encontrado
  • 422 - Erro de validação