O que significa cada código de erro da API

A API de faturação deixa outro programa criar faturas e notas de crédito, publicá-las, ler o estado e o PDF, e validar um NIF. Todas as respostas têm a mesma forma, sem erros técnicos do servidor. Este artigo é para quem faz ou mantém essa ligação: quem usa o fiscaldoo no ecrã não vê estes códigos, só as mensagens do sistema.

Como é uma resposta

{"ok": false, "code": "VAT_INVALID", "message": "O NIF não é válido: tem de ter exatamente 9 dígitos (0-9) e o dígito de controlo correto. Corrija o NIF e envie-o de novo.", "data": {}}

• ok: true se a operação foi feita. Quando é false, nada ficou gravado.
• code: OK ou um dos códigos abaixo. É este campo que o programa deve testar.
• message: a explicação em português, para mostrar a uma pessoa. Pode mudar de texto: não a compare no programa.
• data: os dados do documento, quando o há.

Os códigos

As mensagens abaixo são respostas reais da API, obtidas com chamadas à base de demonstração. As partes em itálico mudam de caso para caso.

Código	O que significa	Mensagem	O que corrigir
ACCESS_DENIED	O utilizador da ligação não tem a permissão.	«O seu utilizador não tem permissão para usar a API de faturação: é preciso a permissão «Integração API». Peça a um administrador fiscal que a dê ao utilizador de integração.»	Dê a permissão: veja abaixo.
NOT_FOUND	O documento não existe na empresa em que a chamada corre. Um documento de outra empresa dá a mesma resposta.	«O documento não foi encontrado na empresa atual. Verifique o identificador e a empresa.»	Confirme o identificador e a empresa da chamada.
INVALID_INPUT	Um dado enviado não se pode usar. A mensagem diz qual.	«Campos desconhecidos ou não permitidos: cor.»; ««quantity» tem de ser um número.»; ««lines» tem de ser uma lista de 1 a 200 linhas.»	Corrija o dado e envie de novo.
VAT_INVALID	O NIF enviado não é válido.	«O NIF não é válido: tem de ter exatamente 9 dígitos (0-9) e o dígito de controlo correto. Corrija o NIF e envie-o de novo.»	Corrija o NIF.
PARTNER_NOT_FOUND	O cliente não existe na empresa da chamada ou o NIF não aponta para um único cliente.	«O cliente não foi encontrado na empresa atual.»; «Não foi encontrado um único cliente com este NIF na empresa atual. Crie primeiro o cliente ou envie «partner_id».»	Confirme a empresa. Crie o cliente ou envie o identificador dele.
NOT_PUBLISHABLE	O documento já não está em rascunho.	«Só um documento em rascunho pode ser publicado. O que aconteceu: este já está no estado «Lançado». Como resolver: envie um documento que ainda esteja em rascunho.»	Não publique outra vez. Leia o estado do documento.
NOT_POSTED	Pediu o PDF de um rascunho.	«Só um documento publicado tem PDF; publique primeiro este.»	Publique o documento e peça o PDF depois.
BUSINESS_RULE	A operação vai contra uma regra do produto ou da lei. O texto vem da regra que recusou e pode listar várias faltas.	«Faltam 3 coisas para confirmar esta fatura: …», com Porquê e O que fazer em cada falta.	Leia a lista e corrija cada ponto. Uma série em falta resolve-se no fiscaldoo, não no programa.
VALIDATION_ERROR	Um valor não cumpre uma regra de validação. O texto vem da regra.	Sem frase fixa.	Leia a mensagem: diz a regra e o valor.
PDF_UNAVAILABLE	O PDF não se conseguiu produzir nesse momento.	Sem frase copiada.	Tente mais tarde. Se continuar, contacte o suporte.
INTERNAL_ERROR	Falha inesperada do lado do servidor. Nada foi gravado.	Sem frase copiada: a mensagem traz uma referência.	Tente de novo. Se continuar, dê a referência ao suporte.

Pendente de validação no ecrã: VALIDATION_ERROR, PDF_UNAVAILABLE e INTERNAL_ERROR não se provocaram na demonstração. Os valores errados que enviámos foram recusados antes, com INVALID_INPUT, e os outros dois exigem uma falha do servidor. Por isso não citamos aqui as suas frases.

A permissão da integração

Quem faz: um Administrador.

1. Abra Definições › Utilizadores e empresas › Utilizadores e abra o utilizador da integração.
2. No separador Ajustes avançados, em Localização PT — Integração por API (faturas), escolha Integração API.
3. Carregue em Guardar.

Use um utilizador próprio para a ligação: esta permissão inclui a faturação. Na chamada seguinte, o ACCESS_DENIED deixa de aparecer.

A empresa da chamada

Cada chamada corre numa só empresa, a do utilizador. Um documento ou um cliente de outra empresa responde NOT_FOUND ou PARTNER_NOT_FOUND, como se não existisse: o programa nunca fica a saber o que há nas outras empresas. Se um identificador que vê no ecrã dá NOT_FOUND, confirme primeiro a empresa.

Nas descargas de ficheiros

Um relatório ou um mapa aberto por um endereço direto responde de outra forma, com uma página de texto simples e o código no fim:

«Não encontrámos o registo. Pode ter sido apagado ou pertencer a outra empresa. Volte a carregar o ecrã e confirme a empresa escolhida no topo.

(NOT_FOUND)»

Tem o mesmo sentido do NOT_FOUND da API.

Quando contactar o suporte

• INTERNAL_ERROR repetido, ou PDF_UNAVAILABLE que não passa.

Siga Como pedir ajuda ao suporte e que informação enviar, com o código, o método chamado e a referência, se existir. Nunca envie a palavra-passe do utilizador da integração.