Programadores

Integre faturação certificada no seu sistema

Ligue o seu produto ao NexaInvoice com OAuth 2.0 — sem o seu cliente copiar chaves. Ele carrega num botão, autoriza a empresa, e o seu sistema passa a emitir faturas certificadas pela AT através da API.

Como funciona (OAuth 2.0)

1 · Autorizar

O seu sistema envia o utilizador para a página de autorização do NexaInvoice. Ele inicia sessão, escolhe a empresa e autoriza.

2 · Receber o código

O NexaInvoice devolve o utilizador ao seu redirect_uri com um ?code=… de uso único.

3 · Trocar por um token

O seu servidor troca o code (POST /api/oauth/token) por um access_token associado àquela empresa.

4 · Emitir

Usa o token como Bearer na API v1 para emitir faturas certificadas dessa empresa.

O access_token não expira (é uma chave de API). Cada empresa que liga recebe o seu — guarde-o associado a esse cliente no seu sistema.

Código pronto

Os 3 passos (iniciar · callback · emitir) na sua linguagem. Troque o REDIRECT_URI pelo seu e ligue o client_id/secret que receber.

// Config (do seu .env)
const BASE = "https://nexainvoice.nexamakers.pt";
const CLIENT_ID = process.env.NEXAINVOICE_CLIENT_ID;
const CLIENT_SECRET = process.env.NEXAINVOICE_CLIENT_SECRET;
const REDIRECT_URI = "https://oseusistema.pt/oauth/nexainvoice/callback";

// 1) Iniciar a ligacao — redirecionar o utilizador para autorizar
app.get("/ligar-nexainvoice", (req, res) => {
  const state = crypto.randomBytes(16).toString("hex");
  req.session.nxiState = state;                 // guardar p/ validar no callback
  const url = new URL(BASE + "/oauth/authorize");
  url.searchParams.set("response_type", "code");
  url.searchParams.set("client_id", CLIENT_ID);
  url.searchParams.set("redirect_uri", REDIRECT_URI);
  url.searchParams.set("state", state);
  res.redirect(url.toString());
});

// 2) Callback — trocar o code por um access_token
app.get("/oauth/nexainvoice/callback", async (req, res) => {
  if (req.query.state !== req.session.nxiState) return res.status(400).send("state invalido");
  const r = await fetch(BASE + "/api/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "authorization_code",
      code: req.query.code,
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      redirect_uri: REDIRECT_URI,
    }),
  });
  const { access_token, company } = await r.json();
  // guardar access_token associado a esta empresa/cliente
  res.redirect("/definicoes?ligado=1");
});

// 3) Emitir uma fatura
async function emitirFatura(accessToken) {
  const r = await fetch(BASE + "/api/v1/invoices", {
    method: "POST",
    headers: { "Authorization": "Bearer " + accessToken, "Content-Type": "application/json" },
    body: JSON.stringify({
      type: "FT",
      customer: { name: "Cliente Lda", nif: "509112233" },
      lines: [{ description: "Servico", quantity: 1, unitPrice: 100, vatRate: 23 }],
    }),
  });
  return (await r.json()).invoice;   // { docNo, atcud, ... }
}

Referência da API

Base: https://nexainvoice.nexamakers.pt/api/v1 · Autenticação: Authorization: Bearer <access_token>

GET/api/v1/pingTestar o token
GET/api/v1/seriesListar séries
POST/api/v1/invoicesEmitir documento (FT/FS/FR/NC)
GET/api/v1/invoices/{id}Obter documento
GET/api/v1/invoices/{id}/pdfDescarregar o PDF

Como obter as credenciais

Não precisa de criar conta para integrar. Implemente o seu callback seguindo os exemplos acima e depois contacte-nos com:

  • • O nome do seu sistema.
  • • O(s) redirect URI(s) que implementou (ex.: https://oseusistema.pt/oauth/nexainvoice/callback).

Enviamos-lhe o client_id e o client_secret da sua aplicação. Os seus clientes só precisam, depois, de ter conta NexaInvoice (é lá que está a faturação certificada).

suporte@nexamakers.pt