Documentação da API de facturação

1. Começar a integrar a facturação

A API REST v1 permite ligar a sua loja, aplicação ou sistema de gestão ao DS Facto: criar clientes e artigos, emitir documentos, consultar pagamentos registados através dos recibos e descarregar PDFs.

1. Crie a empresa no DS Facto e active um plano. A API está incluída nos três planos, respeitando os limites de documentos e funcionalidades de cada um. A avaliação gratuita é exclusiva do Essencial.
2. Configure os dados fiscais e as séries em utilização. Confirme o estabelecimento e, quando precisar de movimentar produtos, o armazém.
3. No painel, abra Integrações → API REST e crie uma chave com as permissões necessárias e uma data de validade.
4. Faça os primeiros testes numa empresa configurada em modo de teste. Confira clientes, valores, documentos e PDFs antes da utilização fiscal.

O modo de teste ou de produção depende da configuração fiscal da empresa. Não existe um parâmetro sandbox para mudar esse modo por pedido. Documentos de teste não têm validade fiscal. A certificação AGT permanece pendente; a emissão em produção está sujeita às aprovações e configurações fiscais exigidas pelo sistema.

2. Autenticação e permissões

Envie a chave em todos os pedidos. Ela começa por ds_ e só é apresentada integralmente no momento da criação.

Authorization: Bearer ds_SUA_CHAVE
Content-Type: application/json

Guarde a chave no servidor da sua integração. Não a coloque no código público do site, aplicações distribuídas ou repositórios. Se for exposta, revogue-a no painel e crie outra.

A chave fica limitada à empresa, às permissões do utilizador que a criou e, se definido, a um estabelecimento. Uma subscrição inactiva, chave expirada ou revogada impede o acesso. Não envie identificadores de outra empresa para tentar mudar o âmbito do pedido.

Para emitir facturas, autorize documents.create e documents.read. Para recibos, autorize receipts.create e documents.read. As restantes permissões estão indicadas em cada operação.

3. Primeiro pedido e exemplo em JavaScript

Defina DS_API_KEY com a sua chave no ambiente privado onde executa os exemplos. Comece por uma consulta que não cria documentos:

curl 'https://dsfacto.com/api/v1/customers?page=1&pageSize=50' \
  -H "Authorization: Bearer $DS_API_KEY"

Exemplo de criação de cliente em JavaScript, executado no servidor:

const response = await fetch('https://dsfacto.com/api/v1/customers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.DS_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "nome": "Cliente de Exemplo",
  "nif": "5000000001",
  "email": "cliente@example.com",
  "telefone": "923456789",
  "morada": "Luanda, Angola"
})
});
const result = await response.json();
if (!response.ok) throw new Error(result.error || 'Não foi possível criar o cliente.');
const clienteId = result.data.id;

Guarde o id devolvido em data e utilize-o em clienteId na factura. Os identificadores e números mostrados nesta página são ilustrativos. As respostas de exemplo são extractos; os registos podem incluir outros campos gerados pelo sistema.

4. Referência das operações

Estão disponíveis as operações abaixo. A versão actual disponibiliza consultas e criação/emissão; não oferece alterações, anulações ou eliminação por PUT, PATCH ou DELETE nestes endereços.

curl 'https://dsfacto.com/api/v1/customers' \
  -H "Authorization: Bearer $DS_API_KEY"

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "nome": "Cliente de Exemplo",
      "nif": "5000000001"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 50
}

curl -X POST 'https://dsfacto.com/api/v1/customers' \
  -H "Authorization: Bearer $DS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "nome": "Cliente de Exemplo",
  "nif": "5000000001",
  "email": "cliente@example.com",
  "telefone": "923456789",
  "morada": "Luanda, Angola"
}'

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "nome": "Cliente de Exemplo",
    "nif": "5000000001"
  }
}

curl 'https://dsfacto.com/api/v1/products' \
  -H "Authorization: Bearer $DS_API_KEY"

{
  "data": [],
  "total": 0,
  "page": 1,
  "pageSize": 50
}

curl -X POST 'https://dsfacto.com/api/v1/products' \
  -H "Authorization: Bearer $DS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "codigo": "SERV-001",
  "descricao": "Serviço de consultoria",
  "preco_unitario": 1000,
  "taxa_iva": 14,
  "tipo": "servico",
  "unidade": "Hora"
}'

{
  "data": {
    "id": "33333333-3333-4333-8333-333333333333",
    "codigo": "SERV-001",
    "descricao": "Serviço de consultoria",
    "preco_unitario": 1000,
    "taxa_iva": 14,
    "tipo": "servico",
    "unidade": "Hora"
  }
}

curl 'https://dsfacto.com/api/v1/invoices' \
  -H "Authorization: Bearer $DS_API_KEY"

{
  "data": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "tipo": "FT",
      "numero": "FT A/1",
      "total_pagar": 1140
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 50
}

curl -X POST 'https://dsfacto.com/api/v1/invoices' \
  -H "Authorization: Bearer $DS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: factura-pedido-0001' \
  --data '{
  "tipo": "FT",
  "clienteId": "11111111-1111-4111-8111-111111111111",
  "linhas": [
    {
      "descricao": "Serviço de consultoria",
      "tipo": "servico",
      "quantidade": 1,
      "precoUnitario": 1000,
      "taxaIva": 14
    }
  ]
}'

{
  "data": {
    "id": "22222222-2222-4222-8222-222222222222",
    "tipo": "FT",
    "numero": "FT A/1",
    "total_pagar": 1140
  }
}

curl 'https://dsfacto.com/api/v1/invoices/22222222-2222-4222-8222-222222222222' \
  -H "Authorization: Bearer $DS_API_KEY"

{
  "data": {
    "id": "22222222-2222-4222-8222-222222222222",
    "tipo": "FT",
    "numero": "FT A/1",
    "total_pagar": 1140,
    "linhas": [
      {
        "descricao": "Serviço de consultoria",
        "quantidade": 1,
        "preco_unitario": 1000,
        "taxa_iva": 14
      }
    ]
  }
}

curl 'https://dsfacto.com/api/v1/invoices/22222222-2222-4222-8222-222222222222/pdf' \
  -H "Authorization: Bearer $DS_API_KEY" \
  --output documento.pdf

Content-Type: application/pdf
Content-Disposition: attachment; filename="documento.pdf"

curl -X POST 'https://dsfacto.com/api/v1/receipts' \
  -H "Authorization: Bearer $DS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: recibo-pedido-0001' \
  --data '{
  "clienteId": "11111111-1111-4111-8111-111111111111",
  "meioPagamento": "Transferência bancária",
  "alocacoes": [
    {
      "facturaId": "22222222-2222-4222-8222-222222222222",
      "montante": 1140
    }
  ]
}'

{
  "data": {
    "id": "44444444-4444-4444-8444-444444444444",
    "tipo": "RC",
    "numero": "RC A/1",
    "total_pagar": 1140
  }
}

curl 'https://dsfacto.com/api/v1/stock' \
  -H "Authorization: Bearer $DS_API_KEY"

{
  "data": [
    {
      "artigo_id": "33333333-3333-4333-8333-333333333333",
      "armazem_id": "55555555-5555-4555-8555-555555555555",
      "quantidade": 25,
      "artigo": {
        "codigo": "PROD-001",
        "descricao": "Produto de exemplo"
      },
      "armazem": {
        "nome": "Principal",
        "estabelecimento_id": "66666666-6666-4666-8666-666666666666"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 50
}

curl 'https://dsfacto.com/api/v1/openapi' \
  -H "Authorization: Bearer $DS_API_KEY"

{
  "openapi": "3.1.0",
  "info": {
    "title": "DS Facto API",
    "version": "1.0.0"
  }
}

5. Linhas e nomes dos campos

Na emissão, envie linhas com os itens facturados. Cada linha deve conter descrição, quantidade positiva, preço unitário não negativo e taxa de IVA. Uma emissão normal exige pelo menos uma linha e aceita até 500.

As taxas de IVA aceites são 0, 5, 7 e 14. A taxa 0 exige um motivoIsencao válido. O desconto é uma percentagem entre 0 e 100. O sistema calcula os impostos e os totais; não envie um total final para substituir esse cálculo.

Os pedidos de artigos usam preco_unitario e taxa_iva. As linhas de documentos usam precoUnitario e taxaIva. As respostas dos registos podem voltar a usar nomes com sublinhado. Campos não reconhecidos nos pedidos de criação são rejeitados.

6. Regras de facturação e casos especiais

Cliente: utilize o identificador de um cliente da empresa. Para os documentos em que seja permitido, pode usar CONSUMIDOR_FINAL. O recibo exige um cliente registado. clienteManual permite indicar nome, NIF e morada quando aplicável.

Datas: use AAAA-MM-DD. Na emissão definitiva, dataEmissao tem de corresponder ao dia actual em Angola; ao omitir o campo, o sistema escolhe essa data. O início do transporte usa data e hora com fuso horário, como 2026-10-27T10:00:00+01:00, substituindo pela data efectiva da operação.

Série e estabelecimento: pode enviar serieId e estabelecimentoId obtidos no painel. Quando omitidos, o sistema procura as opções adequadas à empresa e ao documento. Confirme-as antes de automatizar emissões. A chave não permite aceder a estabelecimentos fora do seu âmbito.

Produtos e stock: artigos com controlo de stock precisam de armazém autorizado e de quantidade disponível quando a operação implica saída de mercadoria. Serviços não movimentam stock. Não envie um armazém quando a operação não o exige.

Retenção: retencaoTaxa: 0 desactiva-a; 6.5 aplica a retenção apenas aos serviços líquidos. Identifique as linhas como tipo: "servico", ou use um artigo registado como serviço. Indique fundamentoRetencao e um tipoRetencao válido ou previamente configurado. Outras taxas e alterações do tipo configurado exigem o Profissional. O enquadramento fiscal deve ser confirmado com a contabilidade.

Moeda: a facturação e os preços das linhas são calculados em AOA. Para apresentar contravalor, são aceites AOA, USD, EUR, GBP, ZAR e MZN em moeda, com taxaCambio positiva em AOA por unidade de divisa e fonteCambio documentada. Recibos liquidam em AOA.

Rascunhos: rascunho: true guarda um documento sem emissão definitiva. Não o apresente como factura emitida. No pedido de recibo, as linhas de quitação são preparadas pelo sistema a partir das alocações.

7. Paginação, pesquisa e filtros

https://dsfacto.com/api/v1/invoices?page=1&pageSize=50&tipo=FT&start=2026-10-01&end=2026-10-31

As listas devolvem data, total, page e pageSize. Continue até recolher o número de registos indicado em total. Consultas de um documento, PDFs e a especificação OpenAPI não usam paginação.

O limite é de 120 pedidos por minuto por chave. Se receber 429, respeite Retry-After antes de voltar a pedir. Distribua as consultas ao longo do tempo em vez de executar todos os pedidos em simultâneo.

8. Repetir uma emissão sem duplicar documentos

Em POST /invoices e POST /receipts, envie Idempotency-Key com 8 a 150 caracteres. São permitidos letras, números, dois pontos, sublinhado e hífen.

Idempotency-Key: factura-encomenda-0001

1. Crie uma chave estável para cada emissão da sua encomenda ou pagamento.
2. Se houver uma falha de ligação ou não receber resposta, repita com a mesma chave e exactamente os mesmos dados.
3. O sistema devolve a emissão já registada em vez de criar outra. Reutilizar a chave com dados diferentes causa conflito.
4. Use uma chave nova apenas para uma operação realmente nova. Clientes e artigos não têm esta garantia de repetição.

9. Respostas, erros e recuperação

Criações devolvem 201, com o registo em data; consultas devolvem 200. O PDF devolve o ficheiro directamente. Um erro é devolvido em JSON, com error e, quando aplicável, code ou details.

{
  "sucesso": false,
  "error": "A subscrição da empresa está inactiva. Consulte a área de subscrição.",
  "code": "SUBSCRIPTION_INACTIVE"
}

Os corpos dos pedidos aceitam até 2 MB. Pedidos que ultrapassem esse limite devolvem 413. Não repita automaticamente um erro de dados ou de permissão sem corrigir a causa.

10. Preparar a integração para utilização

• Confirme o plano activo, as permissões e a validade da chave.
• Teste a emissão, os valores de IVA e retenção, as correcções, os recibos parciais e os PDFs que vai utilizar.
• Teste a repetição do mesmo pedido e os erros de autenticação, dados e limite de pedidos.
• Guarde a ligação entre cada encomenda da sua aplicação, a chave de idempotência e o documento devolvido.
• Confirme com a contabilidade os dados da empresa, séries, isenções e restantes requisitos fiscais antes da utilização em produção.

Precisa de ajuda? Contacte suporte@dsfacto.com com o endereço da operação, data, estado HTTP e mensagem de erro. Não envie a chave secreta nem dados desnecessários dos seus clientes.