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.
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.
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, ... }
}Base: https://nexainvoice.nexamakers.pt/api/v1 · Autenticação: Authorization: Bearer <access_token>
| GET | /api/v1/ping | Testar o token |
| GET | /api/v1/series | Listar séries |
| POST | /api/v1/invoices | Emitir documento (FT/FS/FR/NC) |
| GET | /api/v1/invoices/{id} | Obter documento |
| GET | /api/v1/invoices/{id}/pdf | Descarregar o PDF |
Não precisa de criar conta para integrar. Implemente o seu callback seguindo os exemplos acima e depois contacte-nos com:
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