Autenticação na API 4invoices

Troque client_id e client_secret por um token Bearer válido uma hora, apenas servidor a servidor.

Troque client_id e client_secret por um token Bearer válido uma hora, apenas servidor a servidor.

← Voltar à documentação da API

A primeira fatura em 6 passos

  1. Crie a credencial no painel, em Faturamento → Definições → Acesso API, e copie imediatamente o client_secret — só é mostrado uma vez.
  2. Envie POST /v1/auth/token com grant_type client_credentials, client_id e client_secret.
  3. Recebe access_token, token_type Bearer, expires_in 3600 e a lista de scopes atribuídos.
  4. Coloque o token num cabeçalho Authorization: Bearer <access_token> em todas as outras chamadas.
  5. Verifique o que obteve de fato com GET /v1/me: tenant, scopes e os limites de pedidos atuais.

Todos os endpoints

MétodoEndpointScopeIdempotency-KeyPedidos / minuto
POST/auth/token
Trocar as credenciais por um token de acesso
——120
GET/me
Tenant, scopes e limites atuais
invoices:read—120

O que é a API 4invoices

bash
curl -sS -X POST https://api.4invoices.net/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cli_XXXXXXXXXXXX",
    "client_secret": "sec_XXXXXXXXXXXXXXXXXXXX"
  }'

# → {"access_token":"eyJ...","token_type":"Bearer","expires_in":3600,
#    "scope":"invoices:read invoices:write efactura:submit"}
bash
curl -sS https://api.4invoices.net/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → tenant, scopes concedidos e limites de pedidos atuais
javascript
// Guarde o token em cache; não gere um por pedido.
let cached = { token: "", expiresAt: 0 };

async function getToken() {
  if (cached.token && Date.now() < cached.expiresAt - 60_000) return cached.token;

  const res = await fetch("https://api.4invoices.net/v1/auth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.FOURINVOICES_CLIENT_ID,
      client_secret: process.env.FOURINVOICES_CLIENT_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`token ${res.status}`);

  const data = await res.json();
  cached = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return cached.token;
}

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

Scopes

  • invoices:read
  • invoices:write
  • clients:read
  • clients:write
  • efactura:read
  • efactura:submit
Apenas servidor a servidor. Nunca chame a API a partir de JavaScript de browser: o client_secret chegaria ao visitante e o CORS bloqueia qualquer origem de todo o modo.

Erros

EstadoTipoCódigo
401authentication_errorinvalid_client
401authentication_errortoken_expired
401authentication_errorinvalid_token
403permission_errorinsufficient_scope

Erros frequentes

  • O endpoint de tokens tem o seu próprio limite por IP. Um token por processo, renovado antes de expirar — não um por pedido.
  • O client_secret é guardado apenas como hash; se o perder, cria uma nova credencial e revoga a antiga.
  • Emita credenciais separadas para o ERP, a loja e os scripts internos, cada uma com scopes mínimos. Revogar uma não afeta as restantes.
  • O CORS não permite nenhuma origem de browser: a API é, por conceção, servidor a servidor.

Perguntas e respostas para desenvolvedores

O que acontece se o client_secret estiver errado?

Recebe um 401 com o código invalid_client. Um segredo demasiado curto falha mais cedo, na validação, com 422 validation_failed e param client_secret.

Existe um ambiente de testes separado?

Não. Existe um único host de produção. Teste com faturas pró-forma (document_kind proforma) e com /invoices/preview-totals, que não consome nenhum número fiscal.

Posso restringir os scopes de uma credencial existente?

Sim, a partir do painel. Os tokens já emitidos mantêm os scopes com que foram criados até expirarem, no prazo máximo de uma hora.