Apoio

Perguntas frequentes

As dúvidas mais comuns de quem integra.

#Posso testar sem afectar a minha empresa?

Não há um ambiente de ensaio separado. Peça-nos uma empresa de demonstração: tem os seus próprios dados e chaves, e ninguém é afectado.

#Posso apagar ou alterar um documento emitido?

Não, e é por desenho: a lei exige que os documentos fiscais sejam imutáveis. Corrige-se com uma nota de crédito, que a API oferece.

#A API avisa-me quando alguma coisa muda?

Sim, por webhooks: regista um endereço seu em Definições › Webhooks e o Mucanda faz-lhe um POST assinado (HMAC-SHA256) quando um documento é emitido, a AGT o valida ou recusa, um pagamento é registado e noutros casos. Para o que não tem aviso, ou para recuperar avisos perdidos, use GET /api/eventos e a sincronização incremental (alteradoDesde). Use sempre Idempotency-Key ao escrever.

#Posso usar a chave no meu site ou numa aplicação de telemóvel?

Não. A chave dá poderes sobre a empresa e tudo o que corre no dispositivo do utilizador pode ser lido. Faça os pedidos a partir do seu servidor e exponha à aplicação só o que ela precisa.

#Porque recebo 403 numa operação que a aplicação deixa fazer?

Veja o codigo: SEM_PERMISSAO quer dizer que o perfil da chave não tem a permissão (o detail diz qual); RECURSO_FORA_DO_ALCANCE_DA_CHAVE quer dizer que a operação não faz parte da API de integração.

#Qual é o limite de pedidos?

Por omissão, 20 por segundo por chave e 100 por empresa. Em 429, espere o Retry-After. Ver Limites.

#O que faço se um pedido deu timeout?

Repita o mesmo pedido com a mesma Idempotency-Key. Se o primeiro chegou ao servidor, recebe o resultado dele; se não, é executado agora. Nunca repita uma emissão sem a chave.

#Como sei que documentos foram emitidos pela minha chave?

Cada documento traz o chaveApiId da chave que o emitiu (vazio nos emitidos por uma pessoa). A coluna «Último uso» da lista de chaves mostra quando cada uma foi usada.

#Posso emitir em moeda estrangeira?

Não: os documentos são sempre em Kwanzas (AOA).

#Posso emitir com uma data passada?

Não. A data de um documento é a do servidor no momento da emissão, para que a numeração e a cadeia de assinaturas nunca dependam de um relógio de cliente.

#Dois sistemas podem emitir na mesma série ao mesmo tempo?

Sim. O servidor serializa a numeração; cada emissão recebe o número seguinte, sem lacunas e sem repetições.

#Quanto tempo vale uma chave?

O que definir: até à data de validade (se a pôs) ou até ser revogada. Recomendamos uma validade e a rotação regular.

#Um colaborador saiu. A chave dele deixa de funcionar?

Sim, quando a pessoa deixa de estar activa: CHAVE_SEM_TITULAR_ACTIVO. Um administrador assume a titularidade e a mesma chave volta a funcionar, sem tocar na integração.