Referência

Documentos

Emitir e consultar facturas, facturas/recibo, pró-formas, orçamentos, notas de crédito, recibos e guias. Um documento emitido nunca se altera nem se apaga: corrige-se com uma nota de crédito.

Operação	O que faz
GET `/api/documentos`	Lista os documentos emitidos, do mais recente para o mais antigo.
GET `/api/documentos/pendentes`	As facturas a crédito de um cliente que ainda têm valor por liquidar, da mais antiga para a mais recente.
GET `/api/documentos/{id}`	Um documento emitido, com as linhas, os pagamentos e (nos recibos) as liquidações.
GET `/api/documentos/{id}/impressao`	O modelo de impressão do documento: os dados da empresa e do cliente, as linhas, o resumo de impostos e as frases legais, prontos a desenhar.
GET `/api/documentos/{id}/pdf`	O PDF A4 do documento, igual ao que a aplicação imprime.
GET `/api/documentos/{id}/envios`	O histórico de envios do documento por e-mail: para quem, quando e com que resultado.
POST `/api/documentos`	Emite um documento: factura, factura/recibo, pró-forma, orçamento ou guia.
POST `/api/documentos/pre-calculo`	Calcula, sem emitir nada, o total que a emissão deste mesmo pedido cobraria.
POST `/api/documentos/notas-credito`	Emite uma nota de crédito sobre uma factura ou factura/recibo: devolução ou correcção, total ou parcial.
POST `/api/documentos/recibos`	Emite um recibo: o cliente liquida, total ou parcialmente, uma ou várias facturas a crédito de uma só vez.
POST `/api/documentos/{id}/enviar-email`	Envia o documento por e-mail ao destinatário indicado.
POST `/api/documentos/rascunhos`	Guarda um rascunho de documento.
PUT `/api/documentos/rascunhos/{id}`	Actualiza um rascunho de documento.
GET `/api/documentos/rascunhos`	Lista os rascunhos de documento.
GET `/api/documentos/rascunhos/{id}`	Um rascunho de documento, com as linhas.
DELETE `/api/documentos/rascunhos/{id}`	Elimina um rascunho.
POST `/api/documentos/rascunhos/{id}/emitir`	Emite o documento que o rascunho descreve: passa a ter número e assinatura.
POST `/api/documentos/recibos/{id}/anular`	Anula um recibo, com o motivo.
POST `/api/documentos/{id}/enviar-lembrete-pagamento`	Envia ao cliente, por e-mail, um lembrete de pagamento de uma factura a crédito por receber.
POST `/api/documentos/{id}/impressoes`	Regista que o documento vai ser impresso e diz se é o «Original» ou uma reimpressão («2.ª via, em conformidade com a original»).

GET/api/documentos#

Lista os documentos emitidos, do mais recente para o mais antigo.

Permissão DocumentosEmitidos.Ler

Filtre por tipoDocumentoId, clienteId, lojaId e por intervalo: dataInicio e dataFim são instantes ISO 8601 com fuso (por exemplo 2026-10-01T00:00:00+01:00), ambos inclusivos. Para um dia inteiro, dataFim tem de ser o fim desse dia.

Cada linha traz o chaveApiId da chave que a emitiu (vazio nos documentos emitidos por uma pessoa). É a forma de reconhecer os seus documentos.

A resposta é uma página: itens e proximoCursor. Ver Paginação.

Parâmetros

Nome	Onde	Tipo
`tipoDocumentoId`	na pesquisa	identificador (UUID)
`clienteId`	na pesquisa	identificador (UUID)
`lojaId`	na pesquisa	identificador (UUID)
`dataInicio`	na pesquisa	data e hora (ISO 8601)
`dataFim`	na pesquisa	data e hora (ISO 8601)
`cursor`	na pesquisa	texto
`tamanho`	na pesquisa	número inteiro

Resposta (200 · JSON)

Campo	Tipo	Significado
`itens`	lista de objectos	Os registos desta página.
`itens[].id`	identificador (UUID)	Identificador único (UUID).
`itens[].tipoDocumentoId`	identificador (UUID)	O tipo do documento (ver /api/documentos/tipos).
`itens[].numero`	texto	O número legível, atribuído pelo servidor («FR LC2026/25»).
`itens[].data`	data e hora (ISO 8601)	A data e hora (UTC).
`itens[].clienteId`	identificador (UUID)	O cliente do documento.
`itens[].clienteNome`	texto ou nulo	O nome do cliente tal como estava na emissão.
`itens[].caixaId`	identificador (UUID) ou nulo	A sessão de caixa que recebeu o documento; vazio nos emitidos por chave de API.
`itens[].armazemId`	identificador (UUID) ou nulo	O armazém de onde saiu (ou para onde voltou) o stock.
`itens[].referenciaExternaId`	identificador (UUID) ou nulo	O documento de referência: a factura que uma nota de crédito corrige, ou a guia ou cotação que uma factura cumpre.
`itens[].estado`	texto	O estado actual.
`itens[].motivoAnulacao`	texto ou nulo	O motivo, quando o documento foi anulado.
`itens[].observacao`	texto ou nulo	O texto livre.
`itens[].hash`	texto ou nulo	A assinatura digital do documento (em Base64).
`itens[].hashControlo`	texto ou nulo	Os 4 caracteres da assinatura que se imprimem no documento.
`itens[].versaoChavePrivada`	texto ou nulo	A versão da chave de assinatura usada.
`itens[].dataHoraAssinatura`	data e hora (ISO 8601) ou nulo	Quando o documento foi assinado (UTC).
`itens[].subtotal`	número	A soma das linhas, já com desconto e sem imposto.
`itens[].valorImposto`	número	O IVA.
`itens[].totalValorRetencao`	número	A retenção na fonte, que se subtrai ao total.
`itens[].valorLiquidado`	número	O que já foi liquidado por recibos.
`itens[].valorCreditado`	número	O que já foi creditado por notas de crédito.
`itens[].vendedorOriginadorId`	identificador (UUID) ou nulo
`itens[].vendedorFaturadorId`	identificador (UUID) ou nulo
`itens[].outrosEncargos`	número	Encargos somados ao total, sem imposto (portes, taxas).
`itens[].referenciaCliente`	texto ou nulo	A referência do cliente («V/Referência»).
`itens[].montantePago`	número	O que foi pago no acto.
`itens[].totalDesconto`	número	O total dos descontos.
`itens[].operadorNome`	texto ou nulo	Quem emitiu (vazio nos emitidos por chave de API).
`itens[].dataVencimento`	data (AAAA-MM-DD) ou nulo	O dia do vencimento (facturas a crédito) ou da validade (cotações).
`itens[].registadoOfflineEmUtc`	data e hora (ISO 8601) ou nulo	Quando a venda foi feita sem rede, se foi (só no ponto de venda).
`itens[].chaveApiId`	identificador (UUID) ou nulo	A chave de API que emitiu o documento; vazio nos emitidos por uma pessoa.
`itens[].importadoOfflineOperador`	texto ou nulo
`itens[].importadoOfflineDispositivo`	texto ou nulo
`itens[].importadoOfflinePorNome`	texto ou nulo
`itens[].totalGeral`	número	O total do documento: subtotal + imposto − retenção + outros encargos.
`itens[].totalRecebido`	número	O total recebido (num recibo).
`itens[].totalDocumento`	número	O total do documento.
`itens[].valorPendente`	número	O que ainda falta liquidar.
`itens[].totalGeralPorExtenso`	texto ou nulo	O total por extenso, em português.
`itens[].itens`	lista de objectos
`itens[].itens[].id`	identificador (UUID)	Identificador único (UUID).
`itens[].itens[].produtoId`	identificador (UUID)	O artigo.
`itens[].itens[].loteId`	identificador (UUID) ou nulo	O lote, quando o artigo controla validade.
`itens[].itens[].descricao`	texto	A descrição.
`itens[].itens[].precoUnitario`	número	O preço de uma unidade, sem imposto.
`itens[].itens[].quantidade`	número	A quantidade.
`itens[].itens[].descontoPercentual`	número	O desconto da linha, em percentagem (0 a 99).
`itens[].itens[].descontoFinanceiroPercentual`	número	O desconto financeiro do documento aplicado a esta linha, em percentagem.
`itens[].itens[].impostoPercentual`	número	A taxa de IVA aplicada, em percentagem.
`itens[].itens[].taxaRetencaoPercentual`	número	A taxa de retenção aplicada, em percentagem.
`itens[].itens[].referenciaItemOrigemId`	identificador (UUID) ou nulo
`itens[].itens[].creditadaEmDocumentoId`	identificador (UUID) ou nulo
`itens[].itens[].motivoAnulacaoItem`	texto ou nulo
`itens[].itens[].descontoPromocao`	número
`itens[].itens[].promocaoId`	identificador (UUID) ou nulo
`itens[].itens[].promocaoNome`	texto ou nulo
`itens[].itens[].oferta`	verdadeiro/falso
`itens[].itens[].precoTotal`	número	Preço × quantidade, antes do desconto.
`itens[].itens[].valorDesconto`	número	O valor do desconto.
`itens[].itens[].subtotal`	número	A soma das linhas, já com desconto e sem imposto.
`itens[].itens[].valorImposto`	número	O IVA.
`itens[].itens[].totalValorRetencao`	número	A retenção na fonte, que se subtrai ao total.
`itens[].itens[].valorPagar`	número	O total da linha: subtotal + imposto − retenção.
`itens[].pagamentos`	lista de objectos
`itens[].pagamentos[].id`	identificador (UUID)	Identificador único (UUID).
`itens[].pagamentos[].metodoPagamentoId`	identificador (UUID)	O método de pagamento.
`itens[].pagamentos[].valor`	número	O valor.
`itens[].pagamentos[].tipoLancamento`	texto	`Credito` (dinheiro a entrar) ou `Debito`.
`itens[].pagamentos[].data`	data e hora (ISO 8601)	A data e hora (UTC).
`itens[].pagamentos[].numeroOperacaoBancaria`	texto ou nulo	O número da operação bancária (opcional).
`itens[].pagamentos[].dataOperacaoBancaria`	data e hora (ISO 8601) ou nulo	A data da operação bancária (opcional).
`itens[].pagamentos[].metodoDescricao`	texto ou nulo	O nome do método de pagamento.
`itens[].liquidacoes`	lista de objectos
`itens[].liquidacoes[].id`	identificador (UUID)	Identificador único (UUID).
`itens[].liquidacoes[].documentoLiquidadoId`	identificador (UUID)
`itens[].liquidacoes[].numeroDocumentoLiquidado`	texto
`itens[].liquidacoes[].valor`	número	O valor.
`itens[].liquidacoes[].dataDocumentoLiquidado`	data e hora (ISO 8601)
`itens[].liquidacoes[].totalDocumentoLiquidado`	número
`itens[].liquidacoes[].totalRetencaoDocumentoLiquidado`	número
`itens[].liquidacoes[].totalImpostoDocumentoLiquidado`	número
`itens[].liquidacoes[].totalPagoAposEsta`	número
`itens[].liquidacoes[].totalEmFaltaAposEsta`	número
`itens[].pagamentosRecebidos`	lista de objectos
`itens[].pagamentosRecebidos[].documentoId`	identificador (UUID)
`itens[].pagamentosRecebidos[].documentoNumero`	texto
`itens[].pagamentosRecebidos[].data`	data e hora (ISO 8601)	A data e hora (UTC).
`itens[].pagamentosRecebidos[].valor`	número	O valor.
`itens[].pagamentosRecebidos[].metodo`	texto
`itens[].pagamentosRecebidos[].operador`	texto ou nulo
`itens[].pagamentosRecebidos[].observacao`	texto ou nulo	O texto livre.
`proximoCursor`	texto ou nulo	O cursor da página seguinte; nulo quando não há mais. Ver Paginação.

Pedido

curl

curl 'https://<endereço-da-API>/api/documentos' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/documentos/pendentes#

As facturas a crédito de um cliente que ainda têm valor por liquidar, da mais antiga para a mais recente.

Permissão DocumentosEmitidos.Ler

É a lista a partir da qual se emite um Recibo. Um Recibo tem de liquidar as mais antigas primeiro.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`clienteId`	na pesquisa	identificador (UUID)	sim

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].id`	identificador (UUID)	Identificador único (UUID).
`[].numero`	texto	O número legível, atribuído pelo servidor («FR LC2026/25»).
`[].data`	data e hora (ISO 8601)	A data e hora (UTC).
`[].tipoDocumentoId`	identificador (UUID)	O tipo do documento (ver /api/documentos/tipos).
`[].siglaDocumento`	texto	A sigla do tipo («FT», «FR», «NC»…).
`[].totalGeral`	número	O total do documento: subtotal + imposto − retenção + outros encargos.
`[].valorLiquidado`	número	O que já foi liquidado por recibos.
`[].valorCreditado`	número	O que já foi creditado por notas de crédito.
`[].valorPendente`	número	O que ainda falta liquidar.

Exemplo

As facturas por liquidar de um cliente

Pedido

curl 'https://<endereço-da-API>/api/documentos/pendentes?clienteId=01a12201-fa0a-7aac-93c4-f2d42f3c31cd' \
  -H 'X-Api-Key: assw_v1_<chave>'

Pedido

const resposta = await fetch('https://<endereço-da-API>/api/documentos/pendentes?clienteId=01a12201-fa0a-7aac-93c4-f2d42f3c31cd', {
  method: 'GET',
  headers: {
    "X-Api-Key": "assw_v1_<chave>"
  },
})
const dados = await resposta.json()

Pedido

import requests

resposta = requests.get(
    'https://<endereço-da-API>/api/documentos/pendentes?clienteId=01a12201-fa0a-7aac-93c4-f2d42f3c31cd',
    headers={
        'X-Api-Key': 'assw_v1_<chave>'
    },
)
dados = resposta.json()

Pedido

using var cliente = new HttpClient { BaseAddress = new Uri("https://<endereço-da-API>") };
using var pedido = new HttpRequestMessage(HttpMethod.Get, "/api/documentos/pendentes?clienteId=01a12201-fa0a-7aac-93c4-f2d42f3c31cd");
pedido.Headers.Add("X-Api-Key", "assw_v1_<chave>");
using var resposta = await cliente.SendAsync(pedido);
var texto = await resposta.Content.ReadAsStringAsync();

200 OK Resposta

Resposta

content-type: application/json; charset=utf-8
x-mucanda-api-version: 1

[
  {
    "id": "01a12f22-0dd0-7906-98a2-607105acccc1",
    "numero": "FT LC2026/9",
    "data": "2026-10-12T08:02:04.430629Z",
    "tipoDocumentoId": "2a6a1e94-6e0d-4b8e-9f42-8f6a2f0c7b41",
    "siglaDocumento": "FT",
    "totalGeral": 2850,
    "valorLiquidado": 0,
    "valorCreditado": 0,
    "valorPendente": 2850
  },
  {
    "id": "01a12f68-fb42-7bb7-b7e7-e451a26e5d66",
    "numero": "FT LC2026/10",
    "data": "2026-10-12T09:19:31.690877Z",
    "tipoDocumentoId": "2a6a1e94-6e0d-4b8e-9f42-8f6a2f0c7b41",
    "siglaDocumento": "FT",
    "totalGeral": 7410,
    "valorLiquidado": 0,
    "valorCreditado": 0,
    "valorPendente": 7410
  },
  {
    "id": "01a12f69-873b-73f9-8fb4-120df044e6a5",
    "numero": "FT LC2026/11",
    "data": "2026-10-12T09:20:07.506771Z",
    "tipoDocumentoId": "2a6a1e94-6e0d-4b8e-9f42-8f6a2f0c7b41",
    "siglaDocumento": "FT",
    "totalGeral": 7410,
    "valorLiquidado": 0,
    "valorCreditado": 0,
    "valorPendente": 7410
  },
  {
    "id": "01a12f69-9b31-7bbb-9089-d3f4b0f4f194",
    "numero": "FT LC2026/12",
    "data": "2026-10-12T09:20:12.613133Z",
    "tipoDocumentoId": "2a6a1e94-6e0d-4b8e-9f42-8f6a2f0c7b41",
    "siglaDocumento": "FT",
    "totalGeral": 7410,
    "valorLiquidado": 0,
    "valorCreditado": 0,
    "valorPendente": 7410
  }
]

GET/api/documentos/{id}#

Um documento emitido, com as linhas, os pagamentos e (nos recibos) as liquidações.

Permissão Documentos.Ler

hash e hashControlo são a assinatura digital do documento; numero é o número legível («FR LC2026/25»).

Os totais (subtotal, valorImposto, totalGeral…) são calculados a partir das linhas.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Resposta (200 · JSON)

Campo	Tipo	Significado
`id`	identificador (UUID)	Identificador único (UUID).
`tipoDocumentoId`	identificador (UUID)	O tipo do documento (ver /api/documentos/tipos).
`numero`	texto	O número legível, atribuído pelo servidor («FR LC2026/25»).
`data`	data e hora (ISO 8601)	A data e hora (UTC).
`clienteId`	identificador (UUID)	O cliente do documento.
`clienteNome`	texto ou nulo	O nome do cliente tal como estava na emissão.
`caixaId`	identificador (UUID) ou nulo	A sessão de caixa que recebeu o documento; vazio nos emitidos por chave de API.
`armazemId`	identificador (UUID) ou nulo	O armazém de onde saiu (ou para onde voltou) o stock.
`referenciaExternaId`	identificador (UUID) ou nulo	O documento de referência: a factura que uma nota de crédito corrige, ou a guia ou cotação que uma factura cumpre.
`estado`	texto	O estado actual.
`motivoAnulacao`	texto ou nulo	O motivo, quando o documento foi anulado.
`observacao`	texto ou nulo	O texto livre.
`hash`	texto ou nulo	A assinatura digital do documento (em Base64).
`hashControlo`	texto ou nulo	Os 4 caracteres da assinatura que se imprimem no documento.
`versaoChavePrivada`	texto ou nulo	A versão da chave de assinatura usada.
`dataHoraAssinatura`	data e hora (ISO 8601) ou nulo	Quando o documento foi assinado (UTC).
`subtotal`	número	A soma das linhas, já com desconto e sem imposto.
`valorImposto`	número	O IVA.
`totalValorRetencao`	número	A retenção na fonte, que se subtrai ao total.
`valorLiquidado`	número	O que já foi liquidado por recibos.
`valorCreditado`	número	O que já foi creditado por notas de crédito.
`vendedorOriginadorId`	identificador (UUID) ou nulo
`vendedorFaturadorId`	identificador (UUID) ou nulo
`outrosEncargos`	número	Encargos somados ao total, sem imposto (portes, taxas).
`referenciaCliente`	texto ou nulo	A referência do cliente («V/Referência»).
`montantePago`	número	O que foi pago no acto.
`totalDesconto`	número	O total dos descontos.
`operadorNome`	texto ou nulo	Quem emitiu (vazio nos emitidos por chave de API).
`dataVencimento`	data (AAAA-MM-DD) ou nulo	O dia do vencimento (facturas a crédito) ou da validade (cotações).
`registadoOfflineEmUtc`	data e hora (ISO 8601) ou nulo	Quando a venda foi feita sem rede, se foi (só no ponto de venda).
`chaveApiId`	identificador (UUID) ou nulo	A chave de API que emitiu o documento; vazio nos emitidos por uma pessoa.
`importadoOfflineOperador`	texto ou nulo
`importadoOfflineDispositivo`	texto ou nulo
`importadoOfflinePorNome`	texto ou nulo
`totalGeral`	número	O total do documento: subtotal + imposto − retenção + outros encargos.
`totalRecebido`	número	O total recebido (num recibo).
`totalDocumento`	número	O total do documento.
`valorPendente`	número	O que ainda falta liquidar.
`totalGeralPorExtenso`	texto ou nulo	O total por extenso, em português.
`itens`	lista de objectos
`itens[].id`	identificador (UUID)	Identificador único (UUID).
`itens[].produtoId`	identificador (UUID)	O artigo.
`itens[].loteId`	identificador (UUID) ou nulo	O lote, quando o artigo controla validade.
`itens[].descricao`	texto	A descrição.
`itens[].precoUnitario`	número	O preço de uma unidade, sem imposto.
`itens[].quantidade`	número	A quantidade.
`itens[].descontoPercentual`	número	O desconto da linha, em percentagem (0 a 99).
`itens[].descontoFinanceiroPercentual`	número	O desconto financeiro do documento aplicado a esta linha, em percentagem.
`itens[].impostoPercentual`	número	A taxa de IVA aplicada, em percentagem.
`itens[].taxaRetencaoPercentual`	número	A taxa de retenção aplicada, em percentagem.
`itens[].referenciaItemOrigemId`	identificador (UUID) ou nulo
`itens[].creditadaEmDocumentoId`	identificador (UUID) ou nulo
`itens[].motivoAnulacaoItem`	texto ou nulo
`itens[].descontoPromocao`	número
`itens[].promocaoId`	identificador (UUID) ou nulo
`itens[].promocaoNome`	texto ou nulo
`itens[].oferta`	verdadeiro/falso
`itens[].precoTotal`	número	Preço × quantidade, antes do desconto.
`itens[].valorDesconto`	número	O valor do desconto.
`itens[].subtotal`	número	A soma das linhas, já com desconto e sem imposto.
`itens[].valorImposto`	número	O IVA.
`itens[].totalValorRetencao`	número	A retenção na fonte, que se subtrai ao total.
`itens[].valorPagar`	número	O total da linha: subtotal + imposto − retenção.
`pagamentos`	lista de objectos
`pagamentos[].id`	identificador (UUID)	Identificador único (UUID).
`pagamentos[].metodoPagamentoId`	identificador (UUID)	O método de pagamento.
`pagamentos[].valor`	número	O valor.
`pagamentos[].tipoLancamento`	texto	`Credito` (dinheiro a entrar) ou `Debito`.
`pagamentos[].data`	data e hora (ISO 8601)	A data e hora (UTC).
`pagamentos[].numeroOperacaoBancaria`	texto ou nulo	O número da operação bancária (opcional).
`pagamentos[].dataOperacaoBancaria`	data e hora (ISO 8601) ou nulo	A data da operação bancária (opcional).
`pagamentos[].metodoDescricao`	texto ou nulo	O nome do método de pagamento.
`liquidacoes`	lista de objectos
`liquidacoes[].id`	identificador (UUID)	Identificador único (UUID).
`liquidacoes[].documentoLiquidadoId`	identificador (UUID)
`liquidacoes[].numeroDocumentoLiquidado`	texto
`liquidacoes[].valor`	número	O valor.
`liquidacoes[].dataDocumentoLiquidado`	data e hora (ISO 8601)
`liquidacoes[].totalDocumentoLiquidado`	número
`liquidacoes[].totalRetencaoDocumentoLiquidado`	número
`liquidacoes[].totalImpostoDocumentoLiquidado`	número
`liquidacoes[].totalPagoAposEsta`	número
`liquidacoes[].totalEmFaltaAposEsta`	número
`pagamentosRecebidos`	lista de objectos
`pagamentosRecebidos[].documentoId`	identificador (UUID)
`pagamentosRecebidos[].documentoNumero`	texto
`pagamentosRecebidos[].data`	data e hora (ISO 8601)	A data e hora (UTC).
`pagamentosRecebidos[].valor`	número	O valor.
`pagamentosRecebidos[].metodo`	texto
`pagamentosRecebidos[].operador`	texto ou nulo
`pagamentosRecebidos[].observacao`	texto ou nulo	O texto livre.

Erros específicos

NAO_ENCONTRADO — além dos gerais.

Exemplo

Consultar o documento emitido

Pedido

curl 'https://<endereço-da-API>/api/documentos/01a12f69-9a59-714a-9d67-10d65ba202cf' \
  -H 'X-Api-Key: assw_v1_<chave>'

Pedido

const resposta = await fetch('https://<endereço-da-API>/api/documentos/01a12f69-9a59-714a-9d67-10d65ba202cf', {
  method: 'GET',
  headers: {
    "X-Api-Key": "assw_v1_<chave>"
  },
})
const dados = await resposta.json()

Pedido

import requests

resposta = requests.get(
    'https://<endereço-da-API>/api/documentos/01a12f69-9a59-714a-9d67-10d65ba202cf',
    headers={
        'X-Api-Key': 'assw_v1_<chave>'
    },
)
dados = resposta.json()

Pedido

using var cliente = new HttpClient { BaseAddress = new Uri("https://<endereço-da-API>") };
using var pedido = new HttpRequestMessage(HttpMethod.Get, "/api/documentos/01a12f69-9a59-714a-9d67-10d65ba202cf");
pedido.Headers.Add("X-Api-Key", "assw_v1_<chave>");
using var resposta = await cliente.SendAsync(pedido);
var texto = await resposta.Content.ReadAsStringAsync();

200 OK Resposta

Resposta

content-type: application/json; charset=utf-8
x-mucanda-api-version: 1

{
  "id": "01a12f69-9a59-714a-9d67-10d65ba202cf",
  "tipoDocumentoId": "6d3f9c9b-6d0a-4e4d-9a9a-2c9f8b1e4d52",
  "numero": "FR LC2026/29",
  "data": "2026-10-12T09:20:12.399987Z",
  "clienteId": "01a12f69-98f8-7688-85b9-8d829c101c8b",
  "clienteNome": "Mercearia Cazenga Nova",
  "caixaId": null,
  "armazemId": "01a12201-f4d4-78a0-8dde-1efc41b94776",
  "referenciaExternaId": null,
  "estado": "Novo",
  "motivoAnulacao": null,
  "observacao": "Pedido #4821 da loja online",
  "hash": "a17i27DU2J53A1VG+U4XkfLa8muGqAxJaKe1TxIb9CmC06j9AipBsYPafR0N/1ifG7G9tPy/ScVnEVpENAp3D+2a2lOcL7z3VGd++57xznZRepA+uJMEjEy9NIpFMK1VWHXmca/4FVTzG2leahl18S/mgKYN50LKdRz1gK39oCA=",
  "hashControlo": "a5kx",
  "versaoChavePrivada": "1",
  "dataHoraAssinatura": "2026-10-12T09:20:12.410197Z",
  "subtotal": 13000,
  "valorImposto": 1820,
  "totalValorRetencao": 0,
  "valorLiquidado": 0,
  "valorCreditado": 0,
  "vendedorOriginadorId": null,
  "vendedorFaturadorId": null,
  "outrosEncargos": 0,
  "referenciaCliente": null,
  "montantePago": 14820,
  "totalDesconto": 0,
  "operadorNome": null,
  "dataVencimento": null,
  "registadoOfflineEmUtc": null,
  "chaveApiId": "01a12f69-9867-79c2-ad0c-811c6899737a",
  "totalGeral": 14820,
  "totalRecebido": 14820,
  "totalDocumento": 14820,
  "valorPendente": 0,
  "totalGeralPorExtenso": "catorze mil oitocentos e vinte kwanzas",
  "itens": [
    {
      "id": "01a12f69-9a75-71ff-8c4f-163cce92fd02",
      "produtoId": "01a12201-fa97-7f9b-8eec-2f731b91a53b",
      "loteId": null,
      "descricao": "Arroz agulha 5 kg",
      "precoUnitario": 6500,
      "quantidade": 2,
      "descontoPercentual": 0,
      "descontoFinanceiroPercentual": 0,
      "impostoPercentual": 14,
      "taxaRetencaoPercentual": 0,
      "referenciaItemOrigemId": null,
      "creditadaEmDocumentoId": null,
      "motivoAnulacaoItem": null,
      "descontoPromocao": 0,
      "promocaoId": null,
      "promocaoNome": null,
      "oferta": false,
      "precoTotal": 13000,
      "valorDesconto": 0,
      "subtotal": 13000,
      "valorImposto": 1820,
  …

GET/api/documentos/{id}/impressao#

O modelo de impressão do documento: os dados da empresa e do cliente, as linhas, o resumo de impostos e as frases legais, prontos a desenhar.

Permissão Documentos.Ler

É o que um programa de impressão ou uma aplicação usa para desenhar o documento à sua maneira. Para o PDF já desenhado, use /pdf.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Resposta (200 · JSON)

Campo	Tipo	Significado
`empresa`	objecto
`empresa.nome`	texto	O nome.
`empresa.numeroContribuinte`	texto ou nulo	O número de contribuinte (NIF).
`empresa.endereco`	texto ou nulo	A morada.
`empresa.telefone`	texto ou nulo	O telefone.
`empresa.email`	texto	O endereço de e-mail.
`empresa.website`	texto ou nulo
`empresa.temLogotipo`	verdadeiro/falso
`empresa.informacaoFactura`	texto ou nulo
`empresa.contasBancarias`	lista de objectos
`empresa.contasBancarias[].banco`	texto
`empresa.contasBancarias[].numeroConta`	texto ou nulo
`empresa.contasBancarias[].iban`	texto ou nulo
`empresa.numeroCertificadoAgt`	texto ou nulo
`cliente`	objecto
`cliente.id`	identificador (UUID)	Identificador único (UUID).
`cliente.nome`	texto	O nome.
`cliente.numeroContribuinte`	texto ou nulo	O número de contribuinte (NIF).
`cliente.endereco`	texto	A morada.
`cliente.telefone`	texto ou nulo	O telefone.
`cliente.email`	texto ou nulo	O endereço de e-mail.
`cliente.isConsumidorFinal`	verdadeiro/falso	Verdadeiro no cliente sem identificação fiscal.
`tipoDescricao`	texto
`siglaDocumento`	texto	A sigla do tipo («FT», «FR», «NC»…).
`numero`	texto	O número legível, atribuído pelo servidor («FR LC2026/25»).
`data`	data e hora (ISO 8601)	A data e hora (UTC).
`estado`	texto	O estado actual.
`motivoAnulacao`	texto ou nulo	O motivo, quando o documento foi anulado.
`observacao`	texto ou nulo	O texto livre.
`numeroDocumentoReferencia`	texto ou nulo
`referenciaCliente`	texto ou nulo	A referência do cliente («V/Referência»).
`itens`	lista de objectos
`itens[].codigoInterno`	texto ou nulo	O código interno do artigo.
`itens[].descricao`	texto	A descrição.
`itens[].unidade`	texto ou nulo
`itens[].lote`	texto ou nulo
`itens[].quantidade`	número	A quantidade.
`itens[].precoUnitario`	número	O preço de uma unidade, sem imposto.
`itens[].descontoPercentual`	número	O desconto da linha, em percentagem (0 a 99).
`itens[].valorDesconto`	número	O valor do desconto.
`itens[].subtotal`	número	A soma das linhas, já com desconto e sem imposto.
`itens[].impostoPercentual`	número	A taxa de IVA aplicada, em percentagem.
`itens[].valorImposto`	número	O IVA.
`itens[].taxaRetencaoPercentual`	número	A taxa de retenção aplicada, em percentagem.
`itens[].valorRetencao`	número
`itens[].valorPagar`	número	O total da linha: subtotal + imposto − retenção.
`itens[].motivoIsencao`	texto ou nulo
`itens[].codigoIsencao`	texto ou nulo
`itens[].unidadeVendida`	texto ou nulo
`itens[].promocaoNome`	texto ou nulo
`itens[].descontoPromocao`	número
`itens[].oferta`	verdadeiro/falso
`resumoImpostos`	lista de objectos
`resumoImpostos[].taxa`	número	A taxa, em percentagem.
`resumoImpostos[].incidencia`	número
`resumoImpostos[].imposto`	número
`resumoImpostos[].motivoIsencao`	texto ou nulo
`totalDesconto`	número	O total dos descontos.
`subtotal`	número	A soma das linhas, já com desconto e sem imposto.
`totalImposto`	número
`totalRetencao`	número
`totalGeral`	número	O total do documento: subtotal + imposto − retenção + outros encargos.
`totalPorExtenso`	texto
`pagamentos`	lista de objectos
`pagamentos[].metodo`	texto
`pagamentos[].valor`	número	O valor.
`pagamentos[].numeroOperacaoBancaria`	texto ou nulo	O número da operação bancária (opcional).
`pagamentos[].dataOperacaoBancaria`	data e hora (ISO 8601) ou nulo	A data da operação bancária (opcional).
`liquidacoes`	lista de objectos
`liquidacoes[].id`	identificador (UUID)	Identificador único (UUID).
`liquidacoes[].documentoLiquidadoId`	identificador (UUID)
`liquidacoes[].numeroDocumentoLiquidado`	texto
`liquidacoes[].valor`	número	O valor.
`liquidacoes[].dataDocumentoLiquidado`	data e hora (ISO 8601)
`liquidacoes[].totalDocumentoLiquidado`	número
`liquidacoes[].totalRetencaoDocumentoLiquidado`	número
`liquidacoes[].totalImpostoDocumentoLiquidado`	número
`liquidacoes[].totalPagoAposEsta`	número
`liquidacoes[].totalEmFaltaAposEsta`	número
`montantePago`	número	O que foi pago no acto.
`hash`	texto ou nulo	A assinatura digital do documento (em Base64).
`hashControlo`	texto ou nulo	Os 4 caracteres da assinatura que se imprimem no documento.
`linhaAssinatura`	texto ou nulo
`naoServeDeFactura`	verdadeiro/falso
`ehRecibo`	verdadeiro/falso
`empresaGestora`	verdadeiro/falso
`rodapeDaMarca`	objecto ou nulo
`rodapeDaMarca.titulo`	texto
`rodapeDaMarca.mensagem`	texto
`rodapeDaMarca.site`	texto
`rodapeDaMarca.email`	texto	O endereço de e-mail.
`rodapeDaMarca.telefone`	texto	O telefone.
`rodapeDaMarca.pilares`	lista de texto
`rodapeDaMarca.comLogotipo`	verdadeiro/falso
`mostraRodapeDoPlano`	verdadeiro/falso
`dataVencimento`	data (AAAA-MM-DD) ou nulo	O dia do vencimento (facturas a crédito) ou da validade (cotações).
`transporte`	objecto ou nulo
`transporte.inicioTransporte`	data e hora (ISO 8601)
`transporte.fimTransporte`	data e hora (ISO 8601) ou nulo
`transporte.matricula`	texto ou nulo
`transporte.origem`	objecto
`transporte.origem.detalhe`	texto
`transporte.origem.cidade`	texto
`transporte.origem.codigoPostal`	texto ou nulo
`transporte.origem.pais`	texto
`transporte.destino`	objecto
`transporte.destino.detalhe`	texto
`transporte.destino.cidade`	texto
`transporte.destino.codigoPostal`	texto ou nulo
`transporte.destino.pais`	texto
`qrCode`	objecto ou nulo
`qrCode.url`	texto
`qrCode.versao`	número inteiro
`qrCode.lado`	número inteiro
`qrCode.modulos`	lista de texto
`documentoId`	identificador (UUID)
`localDaOperacao`	texto ou nulo
`naturezaDaCorreccao`	texto ou nulo

Pedido

curl

curl 'https://<endereço-da-API>/api/documentos/<id>/impressao' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/documentos/{id}/pdf#

O PDF A4 do documento, igual ao que a aplicação imprime.

Permissão Documentos.Ler

vias (1 a 4) repete o documento em várias vias, com a marcação de cada uma («Original», «Duplicado»…). Conta como um pedido pesado.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim
`vias`	na pesquisa	número inteiro

Resposta

Devolve 200 com o ficheiro (application/pdf) e Content-Disposition com o nome do ficheiro.

Pedido

curl

curl 'https://<endereço-da-API>/api/documentos/<id>/pdf' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/documentos/{id}/envios#

O histórico de envios do documento por e-mail: para quem, quando e com que resultado.

Permissão Documentos.Ler

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].id`	identificador (UUID)	Identificador único (UUID).
`[].destinatario`	texto
`[].origem`	texto
`[].tipo`	texto
`[].estado`	texto	O estado actual.
`[].tentativas`	número inteiro
`[].ultimoErro`	texto ou nulo
`[].criadoEmUtc`	data e hora (ISO 8601)	Quando o evento aconteceu (UTC).
`[].proximaTentativaEmUtc`	data e hora (ISO 8601) ou nulo
`[].enviadoEmUtc`	data e hora (ISO 8601) ou nulo
`[].solicitadoPor`	texto ou nulo

Pedido

curl

curl 'https://<endereço-da-API>/api/documentos/<id>/envios' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/documentos#

Emite um documento: factura, factura/recibo, pró-forma, orçamento ou guia.

Permissão Documentos.Emitir
Idempotência aceita Idempotency-Key

Sempre com Idempotency-Key. Uma emissão é fiscal: se a rede falhar antes da resposta, repetir sem a chave poderia emitir dois documentos.

O imposto e a retenção nunca se enviam: o servidor deriva-os do artigo e do cliente. Envia-se o preço, a quantidade e o desconto.

pagamentos tem de somar exactamente o total do documento numa factura/recibo, e fica vazio numa factura a crédito, numa pró-forma ou num orçamento. Para saber esse total ao cêntimo, peça-o antes a POST /api/documentos/pre-calculo.

armazemId é obrigatório quando o documento movimenta stock; lojaId quando a empresa tem mais do que um estabelecimento.

A emissão é tudo ou nada: se faltar stock numa linha, nada é emitido e nenhum número é consumido.

Um documento emitido por uma chave não passa por uma sessão de caixa: o dinheiro entra directamente na conta financeira do método de pagamento e o documento fica com o chaveApiId.

Para guias (GR, GT, GD) envie transporte com a origem, o destino, a matrícula e o início do transporte.

Corpo do pedido (JSON · CreateDocumentoCommand)

Campo	Tipo	Obrigatório	Significado
`tipoDocumentoId`	identificador (UUID)	sim	O tipo do documento (ver /api/documentos/tipos).
`clienteId`	identificador (UUID) ou nulo		O cliente do documento.
`armazemId`	identificador (UUID) ou nulo		O armazém de onde saiu (ou para onde voltou) o stock.
`referenciaExternaId`	identificador (UUID) ou nulo		O documento de referência: a factura que uma nota de crédito corrige, ou a guia ou cotação que uma factura cumpre.
`observacao`	texto ou nulo		O texto livre.
`itens`	lista de objectos	sim
`itens[].produtoId`	identificador (UUID)	sim	O artigo.
`itens[].quantidade`	número	sim	A quantidade.
`itens[].precoUnitario`	número	sim	O preço de uma unidade, sem imposto.
`itens[].descontoPercentual`	número	sim	O desconto da linha, em percentagem (0 a 99).
`itens[].descricao`	texto ou nulo		A descrição.
`itens[].unidadeVendaId`	identificador (UUID) ou nulo
`pagamentos`	lista de objectos	sim
`pagamentos[].metodoPagamentoId`	identificador (UUID)	sim	O método de pagamento.
`pagamentos[].valor`	número	sim	O valor.
`pagamentos[].numeroOperacaoBancaria`	texto ou nulo		O número da operação bancária (opcional).
`pagamentos[].dataOperacaoBancaria`	data e hora (ISO 8601) ou nulo		A data da operação bancária (opcional).
`transporte`	objecto ou nulo
`transporte.inicioTransporte`	data e hora (ISO 8601)	sim
`transporte.fimTransporte`	data e hora (ISO 8601) ou nulo
`transporte.matricula`	texto ou nulo
`transporte.origem`	objecto	sim
`transporte.origem.detalhe`	texto	sim
`transporte.origem.cidade`	texto	sim
`transporte.origem.codigoPostal`	texto ou nulo
`transporte.origem.pais`	texto
`transporte.destino`	objecto	sim
`transporte.destino.detalhe`	texto	sim
`transporte.destino.cidade`	texto	sim
`transporte.destino.codigoPostal`	texto ou nulo
`transporte.destino.pais`	texto
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`vendedorOriginadorId`	identificador (UUID) ou nulo
`vendedorFaturadorId`	identificador (UUID) ou nulo
`descontoFinanceiroPercentual`	número		O desconto financeiro do documento aplicado a esta linha, em percentagem.
`outrosEncargos`	número		Encargos somados ao total, sem imposto (portes, taxas).
`referenciaCliente`	texto ou nulo		A referência do cliente («V/Referência»).
`dataVencimento`	data (AAAA-MM-DD) ou nulo		O dia do vencimento (facturas a crédito) ou da validade (cotações).
`cumpreReservaLinhaIds`	lista de identificador (UUID) ou nulo
`autorizacaoSupervisorId`	identificador (UUID) ou nulo
`aplicarPromocoes`	verdadeiro/falso
`promocoesPermitidas`	lista de identificador (UUID) ou nulo
`nomeClienteAvulso`	texto ou nulo

Resposta

Devolve 201 com { "id": "…" } e o cabeçalho Location. Um pedido repetido com a mesma Idempotency-Key devolve o mesmo id, com o cabeçalho Idempotency-Replayed: true.

Erros específicos

STOCK_INSUFICIENTE · PAGAMENTO_NAO_COBRE_TOTAL · ESTABELECIMENTO_OBRIGATORIO · ARMAZEM_OBRIGATORIO · LIMITE_CREDITO_EXCEDIDO · CLIENTE_SEM_CONTA_CORRENTE · METODO_PAGAMENTO_INACTIVO · REFERENCIA_NAO_ENCONTRADA · IDEMPOTENCIA_CONFLITO — além dos gerais.

Exemplo

Emitir uma Factura/Recibo paga em numerário

Pedido

curl -X POST 'https://<endereço-da-API>/api/documentos' \
  -H 'Idempotency-Key: 4756676e-a135-4e46-9ce8-3a5502ea85f0' \
  -H 'X-Api-Key: assw_v1_<chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "tipoDocumentoId": "6d3f9c9b-6d0a-4e4d-9a9a-2c9f8b1e4d52",
  "clienteId": "01a12f69-98f8-7688-85b9-8d829c101c8b",
  "armazemId": "01a12201-f4d4-78a0-8dde-1efc41b94776",
  "lojaId": "01a12201-f4d4-7c07-86b7-e5b24035993e",
  "observacao": "Pedido #4821 da loja online",
  "itens": [
    {
      "produtoId": "01a12201-fa97-7f9b-8eec-2f731b91a53b",
      "quantidade": 2,
      "precoUnitario": 6500,
      "descontoPercentual": 0
    }
  ],
  "pagamentos": [
    {
      "metodoPagamentoId": "9dde532b-0092-4a68-b2dc-18649f0c97c4",
      "valor": 14820
    }
  ]
}'

Pedido

const resposta = await fetch('https://<endereço-da-API>/api/documentos', {
  method: 'POST',
  headers: {
    "Idempotency-Key": "4756676e-a135-4e46-9ce8-3a5502ea85f0",
    "X-Api-Key": "assw_v1_<chave>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "tipoDocumentoId": "6d3f9c9b-6d0a-4e4d-9a9a-2c9f8b1e4d52",
    "clienteId": "01a12f69-98f8-7688-85b9-8d829c101c8b",
    "armazemId": "01a12201-f4d4-78a0-8dde-1efc41b94776",
    "lojaId": "01a12201-f4d4-7c07-86b7-e5b24035993e",
    "observacao": "Pedido #4821 da loja online",
    "itens": [
      {
        "produtoId": "01a12201-fa97-7f9b-8eec-2f731b91a53b",
        "quantidade": 2,
        "precoUnitario": 6500,
        "descontoPercentual": 0
      }
    ],
    "pagamentos": [
      {
        "metodoPagamentoId": "9dde532b-0092-4a68-b2dc-18649f0c97c4",
        "valor": 14820
      }
    ]
  }),
})
const dados = await resposta.json()

Pedido

import requests

resposta = requests.post(
    'https://<endereço-da-API>/api/documentos',
    headers={
        'Idempotency-Key': '4756676e-a135-4e46-9ce8-3a5502ea85f0',
        'X-Api-Key': 'assw_v1_<chave>',
        'Content-Type': 'application/json'
    },
    json={
        'tipoDocumentoId': '6d3f9c9b-6d0a-4e4d-9a9a-2c9f8b1e4d52',
        'clienteId': '01a12f69-98f8-7688-85b9-8d829c101c8b',
        'armazemId': '01a12201-f4d4-78a0-8dde-1efc41b94776',
        'lojaId': '01a12201-f4d4-7c07-86b7-e5b24035993e',
        'observacao': 'Pedido #4821 da loja online',
        'itens': [
            {
                'produtoId': '01a12201-fa97-7f9b-8eec-2f731b91a53b',
                'quantidade': 2,
                'precoUnitario': 6500,
                'descontoPercentual': 0
            }
        ],
        'pagamentos': [
            {
                'metodoPagamentoId': '9dde532b-0092-4a68-b2dc-18649f0c97c4',
                'valor': 14820
            }
        ]
    },
)
dados = resposta.json()

Pedido

using var cliente = new HttpClient { BaseAddress = new Uri("https://<endereço-da-API>") };
using var pedido = new HttpRequestMessage(HttpMethod.Post, "/api/documentos");
pedido.Headers.Add("Idempotency-Key", "4756676e-a135-4e46-9ce8-3a5502ea85f0");
pedido.Headers.Add("X-Api-Key", "assw_v1_<chave>");
pedido.Content = new StringContent("""
{
  "tipoDocumentoId": "6d3f9c9b-6d0a-4e4d-9a9a-2c9f8b1e4d52",
  "clienteId": "01a12f69-98f8-7688-85b9-8d829c101c8b",
  "armazemId": "01a12201-f4d4-78a0-8dde-1efc41b94776",
  "lojaId": "01a12201-f4d4-7c07-86b7-e5b24035993e",
  "observacao": "Pedido #4821 da loja online",
  "itens": [
    {
      "produtoId": "01a12201-fa97-7f9b-8eec-2f731b91a53b",
      "quantidade": 2,
      "precoUnitario": 6500,
      "descontoPercentual": 0
    }
  ],
  "pagamentos": [
    {
      "metodoPagamentoId": "9dde532b-0092-4a68-b2dc-18649f0c97c4",
      "valor": 14820
    }
  ]
}
""", Encoding.UTF8, "application/json");
using var resposta = await cliente.SendAsync(pedido);
var texto = await resposta.Content.ReadAsStringAsync();

201 Created Resposta

Resposta

content-type: application/json; charset=utf-8
x-mucanda-api-version: 1
location: /api/documentos/01a12f69-9a59-714a-9d67-10d65ba202cf

{
  "id": "01a12f69-9a59-714a-9d67-10d65ba202cf"
}

POST/api/documentos/pre-calculo#

Calcula, sem emitir nada, o total que a emissão deste mesmo pedido cobraria.

Permissão Documentos.Emitir
Idempotência aceita Idempotency-Key

Envia-se o mesmo corpo da emissão (POST /api/documentos), sem pagamentos. Nada é emitido, nenhum número é consumido e o stock não se mexe.

Numa factura/recibo, cobre este valor. O IVA arredonda-se linha a linha e uma venda de um artigo com lotes divide-se numa linha por lote consumido: somar o total do seu lado pode dar 1 cêntimo a menos ou a mais, e a emissão seria recusada (PAGAMENTO_NAO_COBRE_TOTAL).

A resposta traz o total (totalGeral), os totais parciais e as linhas tal como a emissão as produziria, uma por lote, com o lote de cada uma.

É um cálculo sobre o stock de agora: se o stock mudar entre este pedido e a emissão, o lote a consumir pode mudar e o total também. Emita logo a seguir e, se a emissão recusar o total, peça-o de novo.

Aceita os mesmos erros de validação da emissão (artigo inexistente, stock insuficiente, estabelecimento em falta).

Corpo do pedido (JSON · CreateDocumentoCommand)

Campo	Tipo	Obrigatório	Significado
`tipoDocumentoId`	identificador (UUID)	sim	O tipo do documento (ver /api/documentos/tipos).
`clienteId`	identificador (UUID) ou nulo		O cliente do documento.
`armazemId`	identificador (UUID) ou nulo		O armazém de onde saiu (ou para onde voltou) o stock.
`referenciaExternaId`	identificador (UUID) ou nulo		O documento de referência: a factura que uma nota de crédito corrige, ou a guia ou cotação que uma factura cumpre.
`observacao`	texto ou nulo		O texto livre.
`itens`	lista de objectos	sim
`itens[].produtoId`	identificador (UUID)	sim	O artigo.
`itens[].quantidade`	número	sim	A quantidade.
`itens[].precoUnitario`	número	sim	O preço de uma unidade, sem imposto.
`itens[].descontoPercentual`	número	sim	O desconto da linha, em percentagem (0 a 99).
`itens[].descricao`	texto ou nulo		A descrição.
`itens[].unidadeVendaId`	identificador (UUID) ou nulo
`pagamentos`	lista de objectos	sim
`pagamentos[].metodoPagamentoId`	identificador (UUID)	sim	O método de pagamento.
`pagamentos[].valor`	número	sim	O valor.
`pagamentos[].numeroOperacaoBancaria`	texto ou nulo		O número da operação bancária (opcional).
`pagamentos[].dataOperacaoBancaria`	data e hora (ISO 8601) ou nulo		A data da operação bancária (opcional).
`transporte`	objecto ou nulo
`transporte.inicioTransporte`	data e hora (ISO 8601)	sim
`transporte.fimTransporte`	data e hora (ISO 8601) ou nulo
`transporte.matricula`	texto ou nulo
`transporte.origem`	objecto	sim
`transporte.origem.detalhe`	texto	sim
`transporte.origem.cidade`	texto	sim
`transporte.origem.codigoPostal`	texto ou nulo
`transporte.origem.pais`	texto
`transporte.destino`	objecto	sim
`transporte.destino.detalhe`	texto	sim
`transporte.destino.cidade`	texto	sim
`transporte.destino.codigoPostal`	texto ou nulo
`transporte.destino.pais`	texto
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`vendedorOriginadorId`	identificador (UUID) ou nulo
`vendedorFaturadorId`	identificador (UUID) ou nulo
`descontoFinanceiroPercentual`	número		O desconto financeiro do documento aplicado a esta linha, em percentagem.
`outrosEncargos`	número		Encargos somados ao total, sem imposto (portes, taxas).
`referenciaCliente`	texto ou nulo		A referência do cliente («V/Referência»).
`dataVencimento`	data (AAAA-MM-DD) ou nulo		O dia do vencimento (facturas a crédito) ou da validade (cotações).
`cumpreReservaLinhaIds`	lista de identificador (UUID) ou nulo
`autorizacaoSupervisorId`	identificador (UUID) ou nulo
`aplicarPromocoes`	verdadeiro/falso
`promocoesPermitidas`	lista de identificador (UUID) ou nulo
`nomeClienteAvulso`	texto ou nulo

Resposta

Devolve 200 com subtotal, valorImposto, totalRetencao, outrosEncargos, totalGeral e a lista linhas.

Erros específicos

STOCK_INSUFICIENTE · ESTABELECIMENTO_OBRIGATORIO · ARMAZEM_OBRIGATORIO · REFERENCIA_NAO_ENCONTRADA — além dos gerais.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/documentos/pre-calculo' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "tipoDocumentoId": "00000000-0000-0000-0000-000000000000",
  "itens": [
    {
      "produtoId": "00000000-0000-0000-0000-000000000000",
      "quantidade": 0,
      "precoUnitario": 0,
      "descontoPercentual": 0
    }
  ],
  "pagamentos": [
    {
      "metodoPagamentoId": "00000000-0000-0000-0000-000000000000",
      "valor": 0
    }
  ]
}'

POST/api/documentos/notas-credito#

Emite uma nota de crédito sobre uma factura ou factura/recibo: devolução ou correcção, total ou parcial.

Permissão Documentos.Anular
Idempotência aceita Idempotency-Key

Indique o documento original, o motivo e as linhas (documentoItemId) com a quantidade a creditar (omitida = a linha inteira).

Creditar todas as linhas anula a factura; creditar algumas rectifica-a. O stock volta ao armazém.

Numa factura/recibo paga no acto, metodoReembolsoId diz por onde o dinheiro volta; numa factura a crédito, o valor abate à conta corrente do cliente.

Uma linha que já foi creditada não pode ser creditada outra vez (DOCUMENTO_JA_CREDITADO).

Aceita Idempotency-Key; envie sempre.

Corpo do pedido (JSON · CreateNotaCreditoCommand)

Campo	Tipo	Obrigatório	Significado
`documentoOriginalId`	identificador (UUID)	sim
`motivo`	texto	sim
`metodoReembolsoId`	identificador (UUID) ou nulo
`numeroOperacaoBancaria`	texto ou nulo		O número da operação bancária (opcional).
`dataOperacaoBancaria`	data e hora (ISO 8601) ou nulo		A data da operação bancária (opcional).
`itens`	lista de objectos	sim
`itens[].documentoItemId`	identificador (UUID)	sim
`itens[].quantidade`	número ou nulo		A quantidade.
`autorizacaoSupervisorId`	identificador (UUID) ou nulo

Resposta

Devolve 201 com { "id": "…" } da nota de crédito.

Erros específicos

DOCUMENTO_JA_CREDITADO · METODO_PAGAMENTO_INACTIVO · REFERENCIA_NAO_ENCONTRADA — além dos gerais.

Exemplo

Creditar uma linha (devolução): repõe o stock e reembolsa pelo método indicado

Pedido

curl -X POST 'https://<endereço-da-API>/api/documentos/notas-credito' \
  -H 'Idempotency-Key: 1a2be5c9-50c6-4b73-a8df-9a4c010b7624' \
  -H 'X-Api-Key: assw_v1_<chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "documentoOriginalId": "01a12f69-9a59-714a-9d67-10d65ba202cf",
  "motivo": "Devolução do cliente",
  "metodoReembolsoId": "9dde532b-0092-4a68-b2dc-18649f0c97c4",
  "itens": [
    {
      "documentoItemId": "01a12f69-9a75-71ff-8c4f-163cce92fd02",
      "quantidade": 1
    }
  ]
}'

Pedido

const resposta = await fetch('https://<endereço-da-API>/api/documentos/notas-credito', {
  method: 'POST',
  headers: {
    "Idempotency-Key": "1a2be5c9-50c6-4b73-a8df-9a4c010b7624",
    "X-Api-Key": "assw_v1_<chave>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "documentoOriginalId": "01a12f69-9a59-714a-9d67-10d65ba202cf",
    "motivo": "Devolução do cliente",
    "metodoReembolsoId": "9dde532b-0092-4a68-b2dc-18649f0c97c4",
    "itens": [
      {
        "documentoItemId": "01a12f69-9a75-71ff-8c4f-163cce92fd02",
        "quantidade": 1
      }
    ]
  }),
})
const dados = await resposta.json()

Pedido

import requests

resposta = requests.post(
    'https://<endereço-da-API>/api/documentos/notas-credito',
    headers={
        'Idempotency-Key': '1a2be5c9-50c6-4b73-a8df-9a4c010b7624',
        'X-Api-Key': 'assw_v1_<chave>',
        'Content-Type': 'application/json'
    },
    json={
        'documentoOriginalId': '01a12f69-9a59-714a-9d67-10d65ba202cf',
        'motivo': 'Devolução do cliente',
        'metodoReembolsoId': '9dde532b-0092-4a68-b2dc-18649f0c97c4',
        'itens': [
            {
                'documentoItemId': '01a12f69-9a75-71ff-8c4f-163cce92fd02',
                'quantidade': 1
            }
        ]
    },
)
dados = resposta.json()

Pedido

using var cliente = new HttpClient { BaseAddress = new Uri("https://<endereço-da-API>") };
using var pedido = new HttpRequestMessage(HttpMethod.Post, "/api/documentos/notas-credito");
pedido.Headers.Add("Idempotency-Key", "1a2be5c9-50c6-4b73-a8df-9a4c010b7624");
pedido.Headers.Add("X-Api-Key", "assw_v1_<chave>");
pedido.Content = new StringContent("""
{
  "documentoOriginalId": "01a12f69-9a59-714a-9d67-10d65ba202cf",
  "motivo": "Devolução do cliente",
  "metodoReembolsoId": "9dde532b-0092-4a68-b2dc-18649f0c97c4",
  "itens": [
    {
      "documentoItemId": "01a12f69-9a75-71ff-8c4f-163cce92fd02",
      "quantidade": 1
    }
  ]
}
""", Encoding.UTF8, "application/json");
using var resposta = await cliente.SendAsync(pedido);
var texto = await resposta.Content.ReadAsStringAsync();

201 Created Resposta

Resposta

content-type: application/json; charset=utf-8
x-mucanda-api-version: 1
location: /api/documentos/01a12f69-9ae0-786d-b5e9-b0aad1e5ab09

{
  "id": "01a12f69-9ae0-786d-b5e9-b0aad1e5ab09"
}

POST/api/documentos/recibos#

Emite um recibo: o cliente liquida, total ou parcialmente, uma ou várias facturas a crédito de uma só vez.

Permissão Documentos.Emitir
Idempotência aceita Idempotency-Key

liquidacoes lista as facturas e o valor a liquidar de cada uma (nunca mais do que o pendente). Use GET /api/documentos/pendentes.

Mais antigas primeiro: não se liquida uma factura recente deixando uma mais antiga por cobrir (mesmo parcialmente).

Um só método de pagamento por recibo. «Conta Corrente» não liquida dívida.

Corpo do pedido (JSON · CreateReciboCommand)

Campo	Tipo	Obrigatório	Significado
`clienteId`	identificador (UUID)	sim	O cliente do documento.
`metodoPagamentoId`	identificador (UUID)	sim	O método de pagamento.
`numeroOperacaoBancaria`	texto ou nulo		O número da operação bancária (opcional).
`dataOperacaoBancaria`	data e hora (ISO 8601) ou nulo		A data da operação bancária (opcional).
`observacao`	texto ou nulo		O texto livre.
`liquidacoes`	lista de objectos	sim
`liquidacoes[].documentoId`	identificador (UUID)	sim
`liquidacoes[].valor`	número	sim	O valor.
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.

Resposta

Devolve 201 com { "id": "…" } do recibo.

Erros específicos

METODO_PAGAMENTO_INACTIVO · REFERENCIA_NAO_ENCONTRADA · ESTABELECIMENTO_OBRIGATORIO — além dos gerais.

Exemplo

Emitir um Recibo que liquida a factura mais antiga do cliente

Pedido

curl -X POST 'https://<endereço-da-API>/api/documentos/recibos' \
  -H 'Idempotency-Key: 4b293f87-4473-4cf1-b647-a4f1dd78ed76' \
  -H 'X-Api-Key: assw_v1_<chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "clienteId": "01a12201-fa0a-7aac-93c4-f2d42f3c31cd",
  "metodoPagamentoId": "9dde532b-0092-4a68-b2dc-18649f0c97c4",
  "lojaId": "01a12201-f4d4-7c07-86b7-e5b24035993e",
  "observacao": "Pagamento recebido por transferência",
  "liquidacoes": [
    {
      "documentoId": "01a12f22-0dd0-7906-98a2-607105acccc1",
      "valor": 2850
    }
  ]
}'

Pedido

const resposta = await fetch('https://<endereço-da-API>/api/documentos/recibos', {
  method: 'POST',
  headers: {
    "Idempotency-Key": "4b293f87-4473-4cf1-b647-a4f1dd78ed76",
    "X-Api-Key": "assw_v1_<chave>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "clienteId": "01a12201-fa0a-7aac-93c4-f2d42f3c31cd",
    "metodoPagamentoId": "9dde532b-0092-4a68-b2dc-18649f0c97c4",
    "lojaId": "01a12201-f4d4-7c07-86b7-e5b24035993e",
    "observacao": "Pagamento recebido por transferência",
    "liquidacoes": [
      {
        "documentoId": "01a12f22-0dd0-7906-98a2-607105acccc1",
        "valor": 2850
      }
    ]
  }),
})
const dados = await resposta.json()

Pedido

import requests

resposta = requests.post(
    'https://<endereço-da-API>/api/documentos/recibos',
    headers={
        'Idempotency-Key': '4b293f87-4473-4cf1-b647-a4f1dd78ed76',
        'X-Api-Key': 'assw_v1_<chave>',
        'Content-Type': 'application/json'
    },
    json={
        'clienteId': '01a12201-fa0a-7aac-93c4-f2d42f3c31cd',
        'metodoPagamentoId': '9dde532b-0092-4a68-b2dc-18649f0c97c4',
        'lojaId': '01a12201-f4d4-7c07-86b7-e5b24035993e',
        'observacao': 'Pagamento recebido por transferência',
        'liquidacoes': [
            {
                'documentoId': '01a12f22-0dd0-7906-98a2-607105acccc1',
                'valor': 2850
            }
        ]
    },
)
dados = resposta.json()

Pedido

using var cliente = new HttpClient { BaseAddress = new Uri("https://<endereço-da-API>") };
using var pedido = new HttpRequestMessage(HttpMethod.Post, "/api/documentos/recibos");
pedido.Headers.Add("Idempotency-Key", "4b293f87-4473-4cf1-b647-a4f1dd78ed76");
pedido.Headers.Add("X-Api-Key", "assw_v1_<chave>");
pedido.Content = new StringContent("""
{
  "clienteId": "01a12201-fa0a-7aac-93c4-f2d42f3c31cd",
  "metodoPagamentoId": "9dde532b-0092-4a68-b2dc-18649f0c97c4",
  "lojaId": "01a12201-f4d4-7c07-86b7-e5b24035993e",
  "observacao": "Pagamento recebido por transferência",
  "liquidacoes": [
    {
      "documentoId": "01a12f22-0dd0-7906-98a2-607105acccc1",
      "valor": 2850
    }
  ]
}
""", Encoding.UTF8, "application/json");
using var resposta = await cliente.SendAsync(pedido);
var texto = await resposta.Content.ReadAsStringAsync();

201 Created Resposta

Resposta

content-type: application/json; charset=utf-8
x-mucanda-api-version: 1
location: /api/documentos/01a12f69-9b9e-7ca9-9b4b-f4b060a860a3

{
  "id": "01a12f69-9b9e-7ca9-9b4b-f4b060a860a3"
}

POST/api/documentos/{id}/enviar-email#

Envia o documento por e-mail ao destinatário indicado.

Permissão Documentos.Emitir

O envio é registado em GET /api/documentos/{id}/envios.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON)

Campo	Tipo	Obrigatório
`destinatario`	texto ou nulo

Resposta

Devolve 204 sem corpo.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/documentos/<id>/enviar-email' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/documentos/rascunhos#

Guarda um rascunho de documento.

Permissão Documentos.Emitir
Idempotência aceita Idempotency-Key

Um rascunho não tem número nem efeito fiscal: só se emite quando se pede (ver «Emitir um rascunho»). Devolve o id.

Corpo do pedido (JSON · SalvarRascunhoCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`tipoDocumentoId`	identificador (UUID)	sim	O tipo do documento (ver /api/documentos/tipos).
`clienteId`	identificador (UUID)	sim	O cliente do documento.
`armazemId`	identificador (UUID) ou nulo		O armazém de onde saiu (ou para onde voltou) o stock.
`referenciaExternaId`	identificador (UUID) ou nulo		O documento de referência: a factura que uma nota de crédito corrige, ou a guia ou cotação que uma factura cumpre.
`descricao`	texto ou nulo		A descrição.
`observacao`	texto ou nulo		O texto livre.
`itens`	lista de objectos	sim
`itens[].produtoId`	identificador (UUID)	sim	O artigo.
`itens[].quantidade`	número	sim	A quantidade.
`itens[].precoUnitario`	número	sim	O preço de uma unidade, sem imposto.
`itens[].descontoPercentual`	número	sim	O desconto da linha, em percentagem (0 a 99).
`itens[].descricao`	texto ou nulo		A descrição.
`itens[].unidadeVendaId`	identificador (UUID) ou nulo
`pagamentos`	lista de objectos	sim
`pagamentos[].metodoPagamentoId`	identificador (UUID)	sim	O método de pagamento.
`pagamentos[].valor`	número	sim	O valor.
`pagamentos[].numeroOperacaoBancaria`	texto ou nulo		O número da operação bancária (opcional).
`pagamentos[].dataOperacaoBancaria`	data e hora (ISO 8601) ou nulo		A data da operação bancária (opcional).
`transporte`	objecto ou nulo
`transporte.inicioTransporte`	data e hora (ISO 8601)	sim
`transporte.fimTransporte`	data e hora (ISO 8601) ou nulo
`transporte.matricula`	texto ou nulo
`transporte.origem`	objecto	sim
`transporte.origem.detalhe`	texto	sim
`transporte.origem.cidade`	texto	sim
`transporte.origem.codigoPostal`	texto ou nulo
`transporte.origem.pais`	texto
`transporte.destino`	objecto	sim
`transporte.destino.detalhe`	texto	sim
`transporte.destino.cidade`	texto	sim
`transporte.destino.codigoPostal`	texto ou nulo
`transporte.destino.pais`	texto
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`descontoFinanceiroPercentual`	número		O desconto financeiro do documento aplicado a esta linha, em percentagem.
`outrosEncargos`	número		Encargos somados ao total, sem imposto (portes, taxas).
`referenciaCliente`	texto ou nulo		A referência do cliente («V/Referência»).
`dataVencimento`	data (AAAA-MM-DD) ou nulo		O dia do vencimento (facturas a crédito) ou da validade (cotações).

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/documentos/rascunhos' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "tipoDocumentoId": "00000000-0000-0000-0000-000000000000",
  "clienteId": "00000000-0000-0000-0000-000000000000",
  "itens": [
    {
      "produtoId": "00000000-0000-0000-0000-000000000000",
      "quantidade": 0,
      "precoUnitario": 0,
      "descontoPercentual": 0
    }
  ],
  "pagamentos": [
    {
      "metodoPagamentoId": "00000000-0000-0000-0000-000000000000",
      "valor": 0
    }
  ]
}'

PUT/api/documentos/rascunhos/{id}#

Actualiza um rascunho de documento.

Permissão Documentos.Emitir

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · SalvarRascunhoCommand)

Campo	Tipo	Obrigatório	Significado
`id`	identificador (UUID) ou nulo		Identificador único (UUID).
`tipoDocumentoId`	identificador (UUID)	sim	O tipo do documento (ver /api/documentos/tipos).
`clienteId`	identificador (UUID)	sim	O cliente do documento.
`armazemId`	identificador (UUID) ou nulo		O armazém de onde saiu (ou para onde voltou) o stock.
`referenciaExternaId`	identificador (UUID) ou nulo		O documento de referência: a factura que uma nota de crédito corrige, ou a guia ou cotação que uma factura cumpre.
`descricao`	texto ou nulo		A descrição.
`observacao`	texto ou nulo		O texto livre.
`itens`	lista de objectos	sim
`itens[].produtoId`	identificador (UUID)	sim	O artigo.
`itens[].quantidade`	número	sim	A quantidade.
`itens[].precoUnitario`	número	sim	O preço de uma unidade, sem imposto.
`itens[].descontoPercentual`	número	sim	O desconto da linha, em percentagem (0 a 99).
`itens[].descricao`	texto ou nulo		A descrição.
`itens[].unidadeVendaId`	identificador (UUID) ou nulo
`pagamentos`	lista de objectos	sim
`pagamentos[].metodoPagamentoId`	identificador (UUID)	sim	O método de pagamento.
`pagamentos[].valor`	número	sim	O valor.
`pagamentos[].numeroOperacaoBancaria`	texto ou nulo		O número da operação bancária (opcional).
`pagamentos[].dataOperacaoBancaria`	data e hora (ISO 8601) ou nulo		A data da operação bancária (opcional).
`transporte`	objecto ou nulo
`transporte.inicioTransporte`	data e hora (ISO 8601)	sim
`transporte.fimTransporte`	data e hora (ISO 8601) ou nulo
`transporte.matricula`	texto ou nulo
`transporte.origem`	objecto	sim
`transporte.origem.detalhe`	texto	sim
`transporte.origem.cidade`	texto	sim
`transporte.origem.codigoPostal`	texto ou nulo
`transporte.origem.pais`	texto
`transporte.destino`	objecto	sim
`transporte.destino.detalhe`	texto	sim
`transporte.destino.cidade`	texto	sim
`transporte.destino.codigoPostal`	texto ou nulo
`transporte.destino.pais`	texto
`lojaId`	identificador (UUID) ou nulo		O estabelecimento.
`descontoFinanceiroPercentual`	número		O desconto financeiro do documento aplicado a esta linha, em percentagem.
`outrosEncargos`	número		Encargos somados ao total, sem imposto (portes, taxas).
`referenciaCliente`	texto ou nulo		A referência do cliente («V/Referência»).
`dataVencimento`	data (AAAA-MM-DD) ou nulo		O dia do vencimento (facturas a crédito) ou da validade (cotações).

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/documentos/rascunhos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "tipoDocumentoId": "00000000-0000-0000-0000-000000000000",
  "clienteId": "00000000-0000-0000-0000-000000000000",
  "itens": [
    {
      "produtoId": "00000000-0000-0000-0000-000000000000",
      "quantidade": 0,
      "precoUnitario": 0,
      "descontoPercentual": 0
    }
  ],
  "pagamentos": [
    {
      "metodoPagamentoId": "00000000-0000-0000-0000-000000000000",
      "valor": 0
    }
  ]
}'

GET/api/documentos/rascunhos#

Lista os rascunhos de documento.

Permissão Documentos.Emitir

tipoDocumentoId filtra por tipo de documento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`tipoDocumentoId`	na pesquisa	identificador (UUID)

Resposta (200 · JSON)

Campo	Tipo	Significado
`[].id`	identificador (UUID)	Identificador único (UUID).
`[].usuarioId`	identificador (UUID)
`[].tipoDocumentoId`	identificador (UUID)	O tipo do documento (ver /api/documentos/tipos).
`[].siglaDocumento`	texto	A sigla do tipo («FT», «FR», «NC»…).
`[].clienteId`	identificador (UUID)	O cliente do documento.
`[].clienteNome`	texto	O nome do cliente tal como estava na emissão.
`[].descricao`	texto ou nulo	A descrição.
`[].numeroLinhas`	número inteiro
`[].totalEstimado`	número
`[].criadoEm`	data e hora (ISO 8601)
`[].actualizadoEm`	data e hora (ISO 8601)

Pedido

curl

curl 'https://<endereço-da-API>/api/documentos/rascunhos' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/documentos/rascunhos/{id}#

Um rascunho de documento, com as linhas.

Permissão Documentos.Emitir

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Resposta (200 · JSON)

Campo	Tipo	Significado
`id`	identificador (UUID)	Identificador único (UUID).
`usuarioId`	identificador (UUID)
`tipoDocumentoId`	identificador (UUID)	O tipo do documento (ver /api/documentos/tipos).
`clienteId`	identificador (UUID)	O cliente do documento.
`armazemId`	identificador (UUID) ou nulo	O armazém de onde saiu (ou para onde voltou) o stock.
`referenciaExternaId`	identificador (UUID) ou nulo	O documento de referência: a factura que uma nota de crédito corrige, ou a guia ou cotação que uma factura cumpre.
`descricao`	texto ou nulo	A descrição.
`observacao`	texto ou nulo	O texto livre.
`criadoEm`	data e hora (ISO 8601)
`actualizadoEm`	data e hora (ISO 8601)
`descontoFinanceiroPercentual`	número	O desconto financeiro do documento aplicado a esta linha, em percentagem.
`outrosEncargos`	número	Encargos somados ao total, sem imposto (portes, taxas).
`referenciaCliente`	texto ou nulo	A referência do cliente («V/Referência»).
`dataVencimento`	data (AAAA-MM-DD) ou nulo	O dia do vencimento (facturas a crédito) ou da validade (cotações).
`itens`	lista de objectos
`itens[].id`	identificador (UUID)	Identificador único (UUID).
`itens[].produtoId`	identificador (UUID)	O artigo.
`itens[].produtoNome`	texto
`itens[].quantidade`	número	A quantidade.
`itens[].precoUnitario`	número	O preço de uma unidade, sem imposto.
`itens[].descontoPercentual`	número	O desconto da linha, em percentagem (0 a 99).
`pagamentos`	lista de objectos
`pagamentos[].id`	identificador (UUID)	Identificador único (UUID).
`pagamentos[].metodoPagamentoId`	identificador (UUID)	O método de pagamento.
`pagamentos[].valor`	número	O valor.
`pagamentos[].numeroOperacaoBancaria`	texto ou nulo	O número da operação bancária (opcional).
`pagamentos[].dataOperacaoBancaria`	data e hora (ISO 8601) ou nulo	A data da operação bancária (opcional).

Pedido

curl

curl 'https://<endereço-da-API>/api/documentos/rascunhos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>'

DELETE/api/documentos/rascunhos/{id}#

Elimina um rascunho.

Permissão Documentos.Emitir

Só os rascunhos se eliminam: um documento emitido nunca se apaga.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X DELETE 'https://<endereço-da-API>/api/documentos/rascunhos/<id>' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/documentos/rascunhos/{id}/emitir#

Emite o documento que o rascunho descreve: passa a ter número e assinatura.

Permissão Documentos.Emitir

É uma emissão fiscal, com as mesmas regras de POST /api/documentos.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/documentos/rascunhos/<id>/emitir' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/documentos/recibos/{id}/anular#

Anula um recibo, com o motivo.

Permissão Documentos.Anular
Idempotência aceita Idempotency-Key

O recibo é o único documento que se anula desta forma; os outros corrigem-se com uma nota de crédito. O dinheiro é estornado por método de pagamento.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · AnularReciboRequest)

Campo	Tipo	Obrigatório
`motivo`	texto	sim

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/documentos/recibos/<id>/anular' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "motivo": "texto"
}'

POST/api/documentos/{id}/enviar-lembrete-pagamento#

Envia ao cliente, por e-mail, um lembrete de pagamento de uma factura a crédito por receber.

Permissão Documentos.Emitir
Idempotência aceita Idempotency-Key

Sem destinatário, usa o e-mail do cliente. O texto («vence em breve» ou «venceu») decide-se no dia em que sai. Não é idempotente.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON)

Campo	Tipo	Obrigatório
`destinatario`	texto ou nulo

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/documentos/<id>/enviar-lembrete-pagamento' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST/api/documentos/{id}/impressoes#

Regista que o documento vai ser impresso e diz se é o «Original» ou uma reimpressão («2.ª via, em conformidade com a original»).

Permissão Documentos.Ler

A distinção vem do DP 71/25, art. 7.º n.º 4 e 5. Cada chamada conta uma impressão.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Resposta (200 · JSON)

Campo	Tipo
`sequencia`	número inteiro
`original`	verdadeiro/falso
`mencao`	texto

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/documentos/<id>/impressoes' \
  -H 'X-Api-Key: <a-sua-chave>'