Conceitos
Convenções
Como os dados se escrevem: JSON, identificadores, datas, valores monetários, enumerações e campos nulos.
| Assunto | Convenção |
|---|---|
| Formato | JSON em UTF-8, nos pedidos (Content-Type: application/json) e nas respostas. Um corpo noutro formato dá 415. |
| Nomes dos campos | camelCase («numeroContribuinte»). Os campos desconhecidos de um pedido são ignorados. |
| Identificadores | UUID («01a12f68-f692-7d4d-8f54-377d674d730a»). São opacos: não os interprete nem os ordene. |
| Datas e horas | ISO 8601, em UTC nas respostas («2026-10-12T09:09:56.005Z»). Nos pedidos aceita-se um fuso («2026-10-12T10:09:56+01:00»). |
| Dias | AAAA-MM-DD, sem hora, para vencimentos, períodos de relatório e datas de documento fiscal. |
| Valores monetários | Números decimais em Kwanzas (AOA), sem símbolo nem separador de milhares («14820.00» é 14 820 Kz). Aceita-se um número ou um texto numérico («"14820.00"»). |
| Percentagens | De 0 a 100 («14» é 14 %). O desconto de uma linha vai de 0 a 99. |
| Quantidades | Números decimais; podem ter casas decimais nos artigos vendidos a peso ou a volume. |
| Enumerações | Texto, nunca números («"FacturaRecibo"», «"Pvp1"»). Cada pedido documenta os valores aceites. |
| Campos nulos | Presentes e null nas respostas, nunca omitidos. Nos pedidos, um campo opcional pode omitir-se ou ir null. |
| Texto | Em português de Portugal. As mensagens de erro podem mudar; o codigo é a parte estável. |
| Compressão | As respostas vão comprimidas (gzip ou brotli) se o cabeçalho Accept-Encoding o pedir. |
| Cache | Todas as respostas levam Cache-Control: no-store: são dados da empresa e não se guardam em caches intermédios. |
#Tamanhos
- Corpo de um pedido: até 2 MB.
- Um documento: até 500 linhas e 10 pagamentos.
- Uma página de uma listagem: de 1 a 200 itens (ver Paginação).
- Mais limites em Limites.
#Cabeçalhos úteis
| Cabeçalho | Sentido | Para que serve |
|---|---|---|
X-Api-Key | pedido | A chave de API. |
Idempotency-Key | pedido | Torna um pedido que cria algo seguro de repetir. Idempotência. |
Idempotency-Replayed | resposta | true quando a resposta é a de um pedido anterior com a mesma Idempotency-Key. |
X-Mucanda-Api-Version | resposta | A versão da API que respondeu (1). Versões. |
Retry-After | resposta | Em 429, os segundos a esperar antes de repetir. |
Location | resposta | Em 201, o endereço do recurso criado (quando existe). |
ETag / If-None-Match | resposta / pedido | Só em GET /api/catalogos: a versão do pacote e a pergunta «mudou?» (resposta 304). |