Documentação

API de integração

Ligue o seu sistema ao Mucanda: leia e registe os dados da sua empresa por API, com uma chave sua, só com as permissões que decidir.

A API de integração dá a outro programa o mesmo acesso aos dados da empresa que uma pessoa teria na aplicação: emitir documentos, consultar clientes e artigos, ver o stock, lançar despesas, tirar relatórios e ficheiros fiscais. As operações são as do próprio sistema, com as mesmas regras e as mesmas validações: um documento emitido por API segue a mesma numeração, a mesma assinatura e as mesmas regras fiscais que um emitido no balcão.

#O que pode fazer

#Em cinco minutos

1. 1
   Crie uma chave

   Na aplicação, em Definições › Chaves de API. O segredo mostra-se uma única vez: guarde-o num sítio seguro.

2. 2
   Faça a primeira chamada

   Envie a chave no cabeçalho X-Api-Key e peça GET /api/empresa. Se vier a sua empresa, está ligado.

3. 3
   Emita o primeiro documento

   Siga os Primeiros passos: obtém os identificadores de que precisa e emite uma factura/recibo.

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

const resposta = await fetch('https://<endereço-da-API>/api/empresa', {
  method: 'GET',
  headers: {
    "X-Api-Key": "assw_v1_<chave>"
  },
})
const dados = await resposta.json()

import requests

resposta = requests.get(
    'https://<endereço-da-API>/api/empresa',
    headers={
        'X-Api-Key': 'assw_v1_<chave>'
    },
)
dados = resposta.json()

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

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

{
  "nome": "Mutamba Comercial, Lda.",
  "slug": "mutamba-comercial",
  "email": "geral@mutambacomercial.co.ao",
  "numeroContribuinte": "5417000987",
  "endereco": "Rua da Missão, n.º 45, Luanda",
  "municipioId": "c8a4df25-a9c1-d51f-9223-367545fbcb49",
  "regimeFiscalId": "01a0ee03-0fe7-7d63-aca7-e189893867d9",
  "informacaoFactura": "Mercadoria entregue e conferida pelo cliente. Mutamba Comercial, Lda. — comércio a retalho e a grosso.",
  "contasBancarias": [
    {
      "banco": "Banco BAI",
      "numeroConta": "0040.0000.1234.5678.1013.1",
      "iban": "AO06.0040.0000.1234.5678.1013.1"
    },
    {
      "banco": "Banco BFA",
      "numeroConta": "0006.0000.9876.5432.1011.2",
      "iban": "AO06.0006.0000.9876.5432.1011.2"
    }
  ],
  "telefone": "+244 923 456 789",
  "website": "www.mutamba-demo.example",
  "temLogotipo": false,
  "observacao": null,
  "temChaveAssinatura": true,
  "numeroCertificadoAgt": "0001",
  "versaoChaveAssinatura": "1",
  "dadosFiscaisBloqueados": true
}

#Como a API se comporta

• Seguro de repetir. Todo o pedido que cria algo aceita um cabeçalho Idempotency-Key: se a rede falhar e repetir o pedido, o resultado é o do primeiro e nunca o efeito duas vezes. Idempotência.
• Erros que uma máquina entende. Cada erro traz um codigo estável e um traceId para o suporte. Erros.
• Fiscal por construção. Um documento emitido não se altera nem se apaga; corrige-se com uma nota de crédito. Documentos fiscais.
• Mínimo de poderes. Uma chave tem as permissões de um perfil e só alcança uma lista fechada de operações; pode ainda ser presa a um estabelecimento e a endereços de rede. Permissões e alcance.
• Estável. A API só cresce: campos e endereços novos aparecem sem aviso; o que quebra um cliente faz-se numa versão nova, com pré-aviso. Versões.

#O endereço da API

Nos exemplos desta documentação, https://<endereço-da-API> é o endereço da sua instalação do Mucanda. A equipa indica-o quando a empresa é activada. Todos os pedidos são por HTTPS.