1. Visão geral

Esta documentação foi criada para simplificar a integração com a API Ulemo. Aqui encontrará tudo o que precisa para começar a emitir documentos fiscais e não fiscais de forma rápida e eficiente.

A integração permite que o seu aplicativo se comunique directamente com o Sistema de Gestão & Facturação Electrónica - Ulemo, eliminando a necessidade de intervenção manual. Com alguns endpoints simples, poderá emitir facturas, recibos, notas de crédito e muito mais.

Validação de NIF – Atenção!

Os documentos fiscais emitidos com NIF inválido de clientes serão automaticamente anulados após validação da AGT (que ocorre minutos após a emissão).

⚠️ Para evitar transtornos e garantir que o seu cliente receba um documento fiscal válido, informe sempre NIFs verdadeiros e correctos ou emita com NIF de consumidor final em situações que não haja certeza da validade do nif.

Número do Estabelecimento

O campo numeroEstabelecimento nas requisições deste API, identifica a agência ou filial a partir da qual o documento está a ser emitido.

Procedimento obrigatório (Para empresas com mais de uma Filial)

Cadastrar o estabelecimento na AGT – através do Portal do Contribuinte
Cadastrar o estabelecimento no Ulemo – no backoffice da plataforma
Utilizar o número nas requisições – após os passos anteriores

Valor padrão para uma Filial ou Testes de integração

Em embiente Development ou para comerciantes com apenas uma localização, pode utilizar:

{ "numeroEstabelecimento": "SEDE" }

2. Autenticação

Para iniciar a integração, precisa de uma Chave de API (API KEY) disponível na conta de todos clientes do Ulemo que possuem uma subscrição premium independentemente do plano/pacote pago. Esta chave identifica a sua conta e autoriza as requisições. Além disso, deve indicar em que ambiente está a trabalhar (Produção ou Teste).

1.1. Cabeçalho

Base URL

https://app.ulemo.ao/api/integration/v1

Headers obrigatórios

Header	Valor	Descrição
API-Key	{sua_chave_aqui}	Chave única fornecida pela Ulemo
Environment	Development ou Production	Define se os dados são de teste ou reais

Ambientes de requisições

Ambiente	Finalidade	Validade dos documentos	Persistência dos dados
Development	Testes e integração	❌ Sem validade fiscal/comercial	⚠️ Podem ser apagados sem aviso
Production	Operações reais	✅ Válidos perante a AGT	🔒 Permanentes e irreversíveis

Atenção: No ambiente Development, os documentos emitidos não têm validade jurídica e os dados podem ser eliminados a qualquer momento sem aviso prévio. Utilize este ambiente apenas para testar a integração e tenha atenção para evitar engano, pois, todas operações de cada ambiente são irreversíveis.

3. Dados constantes

Nesta secção, listamos informações pré-definidos e necessários para diversas situações nos parâmetros/campos para emissão de documento.

2.2. Tipos de Documentos

A tabela abaixo apresenta os tipos de documentos disponíveis para emissão via integração de API.

Tipo	Designação
FT	Factura
FR	Factura/Recibo
FA	Factura de Adiantamento
AF	Autofacturação
NC	Nota de Crédito
RC	Recibo
PP	Factura Pró-forma
OR	Orçamento

3.3. Taxas & Imposto (IVA)

A tabela abaixo apresenta os impostos disponíveis para utilização nos artigos durante a emissão de documentos através da API. Cada imposto deve ser identificado pelo respectivo código no momento da integração.

Código	Imposto	Taxa (%)
ISE	Isento	0.00
NOR	IVA	14.00
INT	IVA	7.00
RED	IVA	5.00

4.4. Isenções

A tabela abaixo apresenta os códigos de motivo de isenção aplicáveis a artigos sem cobrança de IVA durante a emissão de documentos através da API. Estes códigos devem ser utilizados sempre que o imposto do artigo estiver definido como ISE (Isento).

Código	Motivo de Isenção
M00	Regime Transitório
M02	Transmissão de bens e serviços não sujeita
M04	IVA — Regime de Não Sujeição
M11	Isento ao abrigo do Artigo 12.º, alínea b) do CIVA
M12	Isento ao abrigo do Artigo 12.º, alínea c) do CIVA
M13	Isento ao abrigo do Artigo 12.º, alínea d) do CIVA
M14	Isento ao abrigo do Artigo 12.º, alínea e) do CIVA
M15	Isento ao abrigo do Artigo 12.º, alínea f) do CIVA
M17	Isento ao abrigo do Artigo 12.º, alínea h) do CIVA
M18	Isento ao abrigo do Artigo 12.º, alínea i) do CIVA
M19	Isento ao abrigo do Artigo 12.º, alínea j) do CIVA
M20	Isento ao abrigo do Artigo 12.º, alínea k) do CIVA
M30	Isento ao abrigo do Artigo 15.º, n.º 1, alínea a) do CIVA
M31	Isento ao abrigo do Artigo 15.º, n.º 1, alínea b) do CIVA
M32	Isento ao abrigo do Artigo 15.º, n.º 1, alínea c) do CIVA
M33	Isento ao abrigo do Artigo 15.º, n.º 1, alínea d) do CIVA
M34	Isento ao abrigo do Artigo 15.º, n.º 1, alínea e) do CIVA
M35	Isento ao abrigo do Artigo 15.º, n.º 1, alínea f) do CIVA
M36	Isento ao abrigo do Artigo 15.º, n.º 1, alínea g) do CIVA
M37	Isento ao abrigo do Artigo 15.º, n.º 1, alínea h) do CIVA
M38	Isento ao abrigo do Artigo 15.º, n.º 1, alínea i) do CIVA

5.5. Grupos de Artigos

A tabela abaixo apresenta os tipos de incidência aplicáveis aos artigos durante a emissão de documentos. Para artigos do tipo P (Produto), deve ser utilizado obrigatoriamente o código TB (Transmissão de Bens).

Sigla	Tipo de Incidência
SE	Prestação de Serviços de Educação
SS	Prestação de Serviços de Saúde
STP	Serviços de Transporte de Passageiros
SR	Serviços sujeitos a Royalties
SIF	Intermediação Financeira / Seguros
SHS	Hotelaria e Similares
ST	Telecomunicações
SG	Serviço Geral (Outros)
TB	Transmissão de Bens
AS	Arrendamento e Subarrendamento
QT	Quotas
RD	Repasse de Despesas

6.6. Tipos de Desconto

A tabela abaixo apresenta os tipos de descontos suportados pela API para aplicação em artigos ou no total do documento. O valor informado deve corresponder ao tipo de desconto seleccionado.

Tipo	Descrição
Percentagem	Desconto aplicado em percentagem (%)
Akz	Desconto aplicado em valor monetário (Kz)

7.7. Motivo Nota de Crédito

Para a emissão de Nota de Crédito (NC), é obrigatório informar o motivo da anulação ou rectificação, bem como a respectiva causa, descrita em texto livre conforme a necessidade da operação.

Exemplo de causa: Cliente efectuou a compra por engano, Foi uma falha técnica,...

Motivo	Descrição
ANL	Anulação total ou parcial da factura
RTF	Rectificação de valores ou devolução

8.8. Retenção na Fonte

A retenção na fonte, na emissão de documentos, segue regras estritas de validação e apenas admite os valores pré-definidos abaixo. Qualquer tentativa de envio de outras taxas será ignorada pelo sistema.

Taxa de Retenção (%)	Descrição
0.00	Sem retenção
6.5	Retenção de IRS/IRPC aplicável a serviços

Regras de aplicação

A retenção na fonte é aplicável exclusivamente a artigos do tipo S (Serviço);
O artigo deve ter o campo de retenção definido como Sujeito para que a retenção seja considerada no cálculo do documento;
Caso o campo esteja definido como NA (Não Aplicado), a retenção não será aplicada, independentemente da taxa informada e do artigo se do tipo S (Serviço);
O sistema não permite configuração livre de percentagens — apenas os valores definidos nesta tabela são aceites.

4. Documentos

Esta secção destina-se às operações relacionadas com documentos, incluindo emissão, anulação, consulta e listagem.

Antes de executar qualquer operação, deve garantir que está a utilizar o ambiente correcto da requisição — Produção ou Desenvolvimento — de forma a evitar impacto em dados reais ou inconsistências entre ambientes.

9.9. Parâmetros de entrada

Abaixo encontra a descrição detalhada de cada campo utilizado nas requisições da API Ulemo. Esta secção foi organizada para que o programador compreenda rapidamente a finalidade e as regras de cada parâmetro.

infoDocument (objecto principal)

Objecto que contém todas as informações gerais do documento a ser emitido, incluindo tipo, valores, datas e referência interna se necessário.

Campo	Tipo	Obrigatório	Descrição
tipoDoc	String	✅	Tipo de documento (FT, FR, AF, FA, NC, RC, PP, OR)
dataVencimento	Date	⚠️	Obrigatório para FT, PP e OR (yyyy-MM-dd)
numeroEstabelecimento	String	✅	Identificador do estabelecimento (SEDE, FILIAL-001)
referenciaInterna	String	⚠️	Referência interna do sistema
obs	String	⚠️	Observações (máx. 60 caracteres)
totalFinal	BigDecimal	✅	Total final do documento
descontoGlobal	BigDecimal	⚠️	Desconto global aplicado
tipoDescontoGlobal	String	⚠️	Percentagem ou Akz
retencaoFonte	BigDecimal	⚠️	0 ou 6.5 (%)
numeroDocOrigem	String	⚠️	Obrigatório para NC e RC
motivo	String	⚠️	ANL ou RTF - Obrigatório para Nota de crédito (NC)
causa	String	⚠️	Descrição do motivo (máx. 60 caracteres) - Obrigatório para Nota de crédito (NC)

infoCliente (objecto do cliente)

Objecto que contém os dados do comprador ou destinatário do documento. O sistema cria ou reutiliza clientes automaticamente com base no NIF.

artigosDoc (lista de artigos)

Lista de artigos incluídos no documento. Obrigatório para todos os documentos excepto Recibo (RC).

Campo	Tipo	Obrigatório	Descrição
nome	String	✅	Nome do artigo
codigoArtigo	String	✅	Código único
codigoImposto	String	✅	NOR ou ISE
codigoMotivoIsencao	String	⚠️	Obrigatório se ISE
retencaoFonte	String	⚠️	NA ou Sujeito
taxaImposto	BigDecimal	✅	0, 7 ou 14
tipo	String	✅	P ou S
grupoArtigo	String	✅	TB, SG, SE...
precoVendaUnitario	BigDecimal	✅	Preço unitário
precoCompraUnitario	BigDecimal	✅	Custo
qtd	BigDecimal	✅	Quantidade
descontoArtigo	BigDecimal	✅	Desconto
tipoDescontoArtigo	String	✅	Percentagem ou Akz
nomeCategoria	String	✅	Categoria

10.10. Criar factura

A abordagem utilizada para a emissão de Factura (FT) aplica-se igualmente aos restantes documentos primários, seguindo a mesma estrutura e regras de validação da API.

No entanto, os documentos secundários — nomeadamente Nota de Crédito (NC) e Recibo (RC) — possuem regras adicionais, uma vez que dependem de um documento de origem e podem exigir parâmetros específicos associados à operação.

Endpoint

POST /documento/emitir

Headers

Header	Valor
API-Key	{sua_chave_aqui}
Environment	Production / Development
Content-Type	application/json

Parâmetros de entrada

Campo	Tipo	Obrigatório	Descrição
infoDocument.tipoDoc	String	✅	Deve ser FT
infoDocument.dataVencimento	Date	✅	yyyy-MM-dd
infoDocument.numeroEstabelecimento	String	✅	Ex: SEDE
infoDocument.totalFinal	BigDecimal	✅	Total da factura
infoDocument.descontoGlobal	BigDecimal	✅	Desconto global
infoDocument.tipoDescontoGlobal	String	✅	Percentagem ou Akz
infoDocument.retencaoFonte	BigDecimal	✅	0 ou 6.5
infoCliente.nome	String	✅	Nome do cliente
infoCliente.nif	String	✅	NIF do cliente
infoCliente.pais	String	✅	País do cliente
artigosDoc	Array	✅	Lista de artigos

Exemplo prático

{ 

"infoDocument":

 { "tipoDoc": "FT",
 "dataVencimento": "2026-06-30".,
 "numeroEstabelecimento": "SEDE",
 "referenciaInterna": "FT-2026-001",
 "obs": "Venda de equipamentos informáticos",
 "totalFinal": 162450.00,
 "descontoGlobal": 5,
 "tipoDescontoGlobal": "Percentagem",
 "retencaoFonte": 0 },
 "infoCliente":
 {
 "nome": "Empresa ABC, LDA",
 "pais": "Angola",
 "nif": "5001234567",
 "tipo": "Empresa",
 "endereco": "Luanda, Maianga, Rua X",
 "telefone": "+244923456789",
 "email": "contato@empresaabc.ao" },

 "artigosDoc": [
 {
 "nome": "Computador Desktop",
 "codigoArtigo": "PC-001",
 "codigoImposto": "NOR", "taxaImposto": 14,
 "grupoArtigo": "TB",
 "precoVendaUnitario": 150000.00,
 "qtd": 1,
 "descontoArtigo": 0,
 "tipoDescontoArtigo": "Akz",
 "nomeCategoria": "Informática",
 "retencaoFonte": "NA"
 } ] }

Resposta de sucesso

{ 
"success": true,
 "message": "Factura emitida com sucesso",
 "data": {
 "id": 12345,
 "numero": "FT/00123",
 "estado_fe_Agt": "SUBMETIDO",
 "environment": "Production"
 } }

Resposta de erro

{
 "success": false,
 "error": "Estabelecimento com número 'SEDE' não encontrado",
 "field": "infoDocument.numeroEstabelecimento"
 }

11.11. Criar Recibo

O Recibo é utilizado para comprovar o pagamento de uma Factura. Pode ser parcial (pagamento de parte do valor) ou total (liquidação completa da dívida).

Endpoint

POST /documento/emitir-recibo

Headers

Header	Valor
API-Key	{sua_chave_aqui}
Environment	Production (apenas)
Content-Type	application/json

Parâmetros de entrada

Campo	Tipo	Obrigatório	Descrição
infoDocument.tipoDoc	String	✅	Deve ser RC
infoDocument.numeroEstabelecimento	String	✅	Número do estabelecimento
infoDocument.totalFinal	BigDecimal	✅	Valor a pagar neste recibo
infoDocument.numeroDocOrigem	String	✅	Número da Factura original (ex: FT/00123)
infoDocument.valorEntregueDinheiro	BigDecimal	⚠️	Valor pago em dinheiro
infoDocument.valorEntregueBanco	BigDecimal	⚠️	Valor pago por transferência
infoCliente.nif	String	✅	NIF do cliente (mesmo da Factura)
artigosDoc	Array	❌	Deve ser null

Nota: A soma de valorEntregueDinheiro + valorEntregueBanco deve ser igual ou superior ao totalFinal.

Exemplo prático

 { "infoDocument": {
 "tipoDoc": "RC",
 "numeroEstabelecimento": "SEDE",
 "referenciaInterna": "RC-2026-001",
 "obs": "Pagamento parcial da factura",
 "totalFinal": 50000.00,
 "numeroDocOrigem": "FT/00123",
 "valorEntregueDinheiro": 30000.00,
 "valorEntregueBanco": 20000.00
 },
 "infoCliente": { "nif": "5001234567" },
 "artigosDoc": null }

Resposta de sucesso

 {
 "success": true,
 "message": "Recibo emitido com sucesso",
 "data": {
 "id": 12346,
 "numero": "RC/00123",
 "estado_fe_Agt": "NA",
 "environment": "Production",
 "link_pdf_A4": "...",
 "link_pdf_58mm": "...",
 "link_pdf_80mm": "..."
 } }

Resposta de erro

 {
 "success": false,
 "error": "A Factura que pretende emitir RECIBO já foi Anulada",
 "field": "infoDocument.numeroDocOrigem"
 }

12.12. Criar Nota de Crédito

A Nota de Crédito é utilizada para anular ou rectificar uma Factura já emitida. Pode ser total (anulação completa) ou parcial (devolução de alguns artigos).

Endpoint

POST /documento/emitir-nota-credito

Headers

Header	Valor
API-Key	{sua_chave_aqui}
Environment	Production (apenas)
Content-Type	application/json

Parâmetros de entrada

Campo	Tipo	Obrigatório	Descrição
infoDocument.tipoDoc	String	✅	Deve ser NC
infoDocument.numeroEstabelecimento	String	✅	Número do estabelecimento
infoDocument.totalFinal	BigDecimal	✅	Valor a ser creditado
infoDocument.numeroDocOrigem	String	✅	Número da Factura original
infoDocument.motivo	String	✅	ANL (anulação) ou RTF (rectificação)
infoDocument.causa	String	✅	Descrição do motivo (máx. 60 caracteres)
infoCliente.nif	String	✅	NIF do cliente (mesmo da Factura)
artigosDoc	Array	✅	Lista de artigos a creditar

Exemplo prático


{

  "infoDocument":
 {

    "tipoDoc": "NC",

    "numeroEstabelecimento": "SEDE",

    "referenciaInterna": "NC-2026-001",

    "obs": "Devolução de produto com defeito",

    "totalFinal": 500.00,

    "numeroDocOrigem": "FT/00123",

    "motivo": "ANL",

    "causa": "Cliente enganou-se na compra"

  },

  "infoCliente": {
    "nif": "5001234567"
  },

  "artigosDoc": [

    {

      "nome": "Mouse Óptico",

      "codigoArtigo": "MOU-001",

      "codigoImposto": "NOR",

      "taxaImposto": 14,

      "grupoArtigo": "TB",

      "precoVendaUnitario": 500.00,

      "qtd": 1,

      "nomeCategoria": "Informática"

    }
  ]
}

Regras importantes

- O valor da Nota de Crédito não pode exceder o valor pendente da factura original.
- A quantidade devolvida não pode ser superior à quantidade original.
- Se devolver todos os artigos, a Nota de Crédito é considerada "Completa".
- A Nota de Crédito só pode ser emitida para Facturas (FT), Facturas/Recibo (FR) ou Autofacturas (AF).

Resposta de sucesso


{

  "success": true,

  "message": "Nota de Crédito nº #NC/00123 emitida com sucesso.",

  "data": {

    "id": 12347,

    "numero": "NC/00123",

    "tipoNota": "Parcial",

    "motivo": "ANL",

    "estado_fe_Agt": "SUBMETIDO",

    "environment": "Production",

    "link_pdf_A4": "..."

  }
}

Resposta de erro


{

  "success": false,

  "error": "O valor total da Nota de Crédito não deve ser superior ao valor pendente do documento original (Kz 1000.00)",

  "field": "infoDocument.totalFinal"

}

13.13. Consultar por ID

Este endpoint permite obter os detalhes de um documento específico, identificado pelo seu ID e estabelecimento onde foi emitido.

A resposta inclui informações do documento, incluindo dados do cliente, valores calculados, estado fiscal e links para download do PDF.

Endpoint

GET /find-by-estabeleciment-and-id/{STB}/{ID}

Parâmetros de caminho (Path Variables)

Parâmetro	Tipo	Descrição	Exemplo
STB	String	Número do estabelecimento onde o documento foi emitido	SEDE, 001
ID	Long	ID interno do documento	12345

Headers

Header	Valor	Obrigatório
API-Key	{sua_chave_aqui}	✅
Environment	Production / Development	✅

Funcionamento

O sistema valida se o documento existe e se pertence ao estabelecimento informado. Caso exista, retorna os dados do documento, incluindo cliente, valores, impostos e links de PDF.

O ID utilizado no link do PDF é automaticamente codificado por razões de segurança.

Exemplo de requisição

GET /api/integration/v1/documento/find-by-estabeleciment-and-id/SEDE/12345

Resposta de sucesso (Factura)

{

  "success": true,

  "message": "Documento obtido com sucesso",

  "data": {

    "id": 12345,

    "codigo": "FAC-2026-00123",

    "numero": "FT/00123",

    "tipo": "FT",

    "data": "24/05/2026",

    "hora": "10:15",

    "dataVencimento": "30/06/2026",

    "nomeCliente": "Empresa ABC, LDA",

    "nifCliente": "5001234567",

    "enderecoCliente": "Luanda, Maianga, Rua X",

    "telefoneCliente": "+244923456789",

    "emailCliente": "contato@empresaabc.ao",

    "valorSubtotal": 150000.00,

    "valorTotal": 162450.00,

    "valorTotalImposto": 19950.00,

    "valorTotalDesconto": 7500.00,

    "descontoGlobal": 5,

    "tipoDescontoGlobal": "Percentagem",

    "retencaoFonte": 0,

    "estado_fe_Agt": "SUBMETIDO",

    "environment": "Production",

    "link_pdf_A4": "https://api.ulemo.ao/api/integration/pre-viwer-doc-api/facturacao/documento/Production/XYZ791/4/abc123"

  }
}

Resposta de sucesso (Nota de Crédito)

{

  "success": true,

  "message": "Documento obtido com sucesso",

  "data": {

    "id": 12347,

    "codigo": "NCD-2026-00123",

    "numero": "NC/00123",
    "tipo": "NC",

    "data": "24/05/2026",

    "hora": "15:30",

    "nomeCliente": "Empresa ABC, LDA",

    "nifCliente": "5001234567",

    "valorTotal": 500.00,

    "motivo": "ANL",

    "estado_fe_Agt": "SUBMETIDO",

    "numeroDocPai": "FT/00123",

    "environment": "Production",

    "link_pdf_A4": "https://api.ulemo.ao/api/integration/pre-viwer-doc-api/facturacao/documento/Production/XYZ789/4/abc123"

  }
}

Resposta de sucesso (Recibo)

{

  "success": true,

  "message": "Documento obtido com sucesso",

  "data": {

    "id": 12346,

    "codigo": "RCB-2026-00123",

    "numero": "RC/00123",

    "tipo": "RC",

    "data": "24/05/2026",

    "hora": "14:20",

    "nomeCliente": "Empresa ABC, LDA",

    "nifCliente": "5001234567",

    "valorTotal": 50000.00,

    "valorEntregueDinheiro": 30000.00,

    "valorEntregueBanco": 20000.00,

    "numeroDocPai": "FT/00123",

    "estado_fe_Agt": "NA",

    "environment": "Production",

    "link_pdf_A4": "https://api.ulemo.ao/api/integration/pre-viwer-doc-api/facturacao/documento/Production/XYZ790/4/abc123"

  }
}

Resposta quando documento não encontrado

{

  "success": false,

  "message": "Documento não encontrado"

}

Resposta de erro (validação)

{

  "success": false,

  "error": "Estabelecimento com número 'SEDE' não encontrado",

  "field": "infoDocument.numeroEstabelecimento"

}

14.14. Listagem por Posto

Este endpoint permite listar documentos emitidos num determinado estabelecimento, organizados por grupo, com suporte a paginação. Os resultados são ordenados do mais recente para o mais antigo, garantindo acesso rápido aos documentos mais recentes.

É possível consultar documentos fiscais (FT, FR, FA, AF, NC, RC) ou documentos de propostas (PP, OR), conforme o grupo seleccionado.

Endpoint

GET /list-by-estabeleciment-and-group/{STB}/{group}/{PAGE}

Parâmetros de caminho (Path Variables)

Parâmetro	Tipo	Descrição	Exemplo
STB	String	Número do estabelecimento registado no sistema	SEDE, 001, FILIAL-A
group	String	Grupo de documentos a listar (fiscais ou propostas)	fiscais
PAGE	Integer	Número da página (começa em 0). Máx. 50 documentos por página	0, 1, 2

Headers

Header	Valor	Obrigatório
API-Key	{sua_chave_aqui}	✅
Environment	Production / Development	✅

Funcionamento

Os documentos são ordenados do mais recente para o mais antigo (por ID decrescente). Cada página retorna no máximo 50 documentos. Se não existirem dados para a página solicitada, será retornada uma lista vazia.

O grupo fiscais inclui: FT, FR, FA, AF, NC, RC. O grupo propostas inclui: PP, OR.

Exemplo de requisição

GET /api/integration/v1/documento/list-by-estabeleciment-and-group/SEDE/fiscais/0

Resposta de sucesso

{

  "success": true,

  "message": "Documentos listados com sucesso",

  "data": {

    "page": 0,
    "total": 3,

    "documentos": [

      {

        "id": 12347,

        "numero": "NC/00123",

        "data": "24/05/2026",

        "hora": "15:30",

        "tipo": "NC",

        "nomeCliente": "Empresa ABC, LDA",

        "nifCliente": "5001234567",

        "valorTotal": 500.00,

        "estado_fe_Agt": "SUBMETIDO",

        "link_pdf_A4": "https://api.ulemo.ao/api/integration/pre-viwer-doc-api/facturacao/documento/Production/XYZ789/4/abc123"

      }
    ],
    "environment": "Production"
  }
}

Resposta de erro

{

  "success": false,

  "error": "O grupo deve ser 'fiscais' ou 'propostas'",

  "field": "group"

}

5. Erros & soluções

Esta secção reúne os principais erros de validação relacionados com clientes, artigos, Nota de Crédito (NC) e Recibo (RC), bem como as respectivas soluções recomendadas.

Resumo rápido dos erros mais comuns

Situação	Provável erro	Solução
Não consigo autenticar	API_KEY_INVALIDA	Verifique a chave e headers
Estabelecimento não existe	ESTABELECIMENTO_NAO_ENCONTRADO	Verifique o número do estabelecimento
NIF inválido	NIF_INVALIDO	Use 9 ou 14 dígitos
Data inválida	DATA_VENCIMENTO_PASSADA	Use data presente ou futura
Totais incorrectos	PROBLEMA_DE_CÁLCULOS	Verifique soma dos artigos e descontos
Nota de Crédito recusada	VALOR_NC_EXCEDE_LIMITE	Verifique valor pendente da factura
Recibo recusado	TOTAL_RECIBO_EXCEDEU	Verifique valor remanescente

Erros de Validação de Cliente

Código	Campo	Mensagem	O que fazer
NIF_CONSUMIDOR_FINAL_INVALIDO	infoCliente.nif	O NIF '999999999' é reservado para 'Consumidor final'	Altere o nome para 'Consumidor final'
INFO_CLIENTE_CONSUMIDOR_FINAL_OBRIGATORIO	infoCliente.nif	Para cliente com nome 'Consumidor final', o NIF deve ser '999999999'	Utilize o NIF reservado
PAÍS_DO_CLIENTE_INVÁLIDO	infoCliente.pais	Não foi encontrado país com o nome informado	Verifique o nome do país

Erros de Validação de Artigos

Código	Campo	Mensagem	O que fazer
ARTIGOS_OBRIGATORIOS	artigosDoc	O campo 'artigosDoc' é obrigatório	Adicione pelo menos um artigo
ARTIGO_NOME_OBRIGATORIO	artigosDoc[X].nome	O campo 'nome' do artigo é obrigatório	Informe o nome do produto/serviço
ARTIGO_CODIGO_OBRIGATORIO	artigosDoc[X].codigoArtigo	O campo 'codigoArtigo' é obrigatório	Informe o código do artigo
ARTIGO_QUANTIDADE_INVALIDA	artigosDoc[X].qtd	A quantidade deve ser maior que zero	Corrija a quantidade
ARTIGO_PRECO_INVALIDO	artigosDoc[X].precoVendaUnitario	O preço de venda unitário deve ser maior ou igual a zero	Corrija o preço
IMPOSTO_INVALIDO	artigosDoc[X].codigoImposto	Nenhum imposto foi encontrado com o código e taxa informada	Utilize NOR (14) ou ISE (0)
GRUPO_DE_INVALIDO	artigosDoc[X].grupoArtigo	A sigla do grupo do artigo é inválida	Use siglas válidas (TB, SG, SE, etc.)
ARTIGOS_DO_DOCUMENTO_NÃO_VALIDADOS	artigosDoc	Não foi possível validar os artigos do documento	Verifique os dados de cada artigo

Erros Específicos para Nota de Crédito (NC)

Código	Campo	Mensagem	O que fazer
FACTURA_ORIGEM_OBRIGATORIO	infoDocument.numeroDocOrigem	O campo 'numeroDocOrigem' é obrigatório	Informe o número da Factura original
MOTIVO_OBRIGATORIO	infoDocument.motivo	O campo 'motivo' é obrigatório (ANL ou RTF)	Utilize ANL ou RTF
CAUSA_OBRIGATORIA	infoDocument.causa	O campo 'causa' é obrigatório (máx. 60 caracteres)	Informe a causa da emissão
TIPO_DOC_ORIGEM_INVALIDO	infoDocument.numeroDocOrigem	Não foi encontrada factura para Nota de Crédito	Verifique o número da factura
DOC_ORIGEM_SEM_ARTIGOS	artigosDoc	O documento original não possui artigos	Verifique o documento de origem
ARTIGOS_NC_EXCEDE_LIMITE	artigosDoc	Quantidade de artigos excede o documento original	Reduza os artigos
VALOR_NC_EXCEDE_LIMITE	infoDocument.totalFinal	O valor da Nota de Crédito excede o pendente	Reduza o valor
DOCUMENTO_ORIGEM_NAO_API	infoDocument.numeroDocOrigem	Documento de origem não emitido via API	Use o sistema Ulemo

Erros Específicos para Recibo (RC)

Código	Campo	Mensagem	O que fazer
FACTURA_ORIGEM_OBRIGATORIO	infoDocument.numeroDocOrigem	O campo 'numeroDocOrigem' é obrigatório	Informe o número da Factura original
DOC_ORIGEM_INVALIDO	infoDocument.numeroDocOrigem	Factura não encontrada	Verifique o número da factura
DOC_ORIGEM_NAO_AUTORIZADO	infoDocument.numeroDocOrigem	Documento não permite Recibo	Use apenas Facturas (FT)
DOC_ORIGEM_ANULADO	infoDocument.numeroDocOrigem	Factura já foi anulada	Não é possível emitir Recibo
TOTAL_RECIBO_EXCEDEU	infoDocument.totalFinal	Valor do Recibo excede remanescente	Reduza o valor
DOCUMENTO_ORIGEM_NAO_API	infoDocument.numeroDocOrigem	Documento de origem não emitido via API	Use o sistema Ulemo