🔐 Autenticação

A API da Calculato utiliza autenticação baseada em Bearer Token.

Em todas as requisições para a API, é obrigatório enviar o header:

Authorization: Bearer <ACCESS_TOKEN>

O ponto central é que a forma de obtenção do ACCESS_TOKEN depende do tipo de integração adotado pelo integrador.

Esta página descreve:

o requisito comum de autenticação para todas as chamadas;
como escolher o tipo de autenticação correto;
os fluxos completos para cada modelo de integração suportado.

Índice

Requisito comum: Bearer Token
Como escolher o tipo de autenticação
Integração Conectada ao Cliente (OAuth2 + PKCE)
Integração White-label (Embedded Payroll) via Broker
📌 Exemplos de Código
🧩 Glossário

Requisito comum: Bearer Token

Independentemente do modelo de integração:

toda chamada à API da Calculato exige um access_token;
o token deve ser enviado no header Authorization no formato Bearer.

Exemplo:

GET https://api.calculato.com.br/v1/empregadores/{idEmpregador}/folhas
Authorization: Bearer <ACCESS_TOKEN>

Como escolher o tipo de autenticação

A Calculato suporta dois modelos de integração, cada um com um fluxo de autenticação distinto:

Modelo de integração	Quando usar	Como o token é obtido
Integração Conectada ao Cliente	Quando o cliente final é cliente da Calculato e autoriza explicitamente a integração	OAuth2 Authorization Code + PKCE
Integração White-label (Embedded Payroll)	Quando o integrador oferece folha sob sua própria marca	client_credentials (M2M) + token exchange via Broker

Integração Conectada ao Cliente (OAuth2 + PKCE)

Credenciais fornecidas ao integrador

Campo	Descrição
`client_id`	Client ID da aplicação OAuth cadastrada na Calculato
`client_secret`	Client Secret da aplicação OAuth
`redirect_uri`	URL de callback configurada na aplicação (ex: `https://oauth.pstmn.io/v1/callback`)
`auth_url`	URL de autorização OAuth (`https://auth.calculato.com.br/authorize`)
`token_url`	URL para troca de tokens (`https://auth.calculato.com.br/oauth/token`)
`audience`	Audience da API (`https://calculato.com.br/`)
`scope`	`openid profile email offline_access`

Visão geral do fluxo

Neste modelo:

O usuário final realiza login diretamente na Calculato;
O usuário autoriza explicitamente o acesso do sistema integrador;
O integrador recebe tokens para operar em nome do cliente, respeitando o escopo autorizado.

Passo a passo (OAuth2 + PKCE)

GET https://auth.calculato.com.br/authorize?
  response_type=code&
  client_id=CLIENT_ID&
  redirect_uri=https%3A%2F%2Foauth.pstmn.io%2Fv1%2Fcallback&
  scope=openid%20profile%20email%20offline_access&
  audience=https%3A%2F%2Fcalculato.com.br%2F&
  state=STATE_VALUE

▶️ Passo 2 — Receber o authorization code

GET https://app.parceiro.com/callback?
  code=AUTH_CODE&
  state=SOME_RANDOM_STRING

▶️ Passo 3 — Trocar o code por tokens

POST https://auth.calculato.com.br/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "code": "AUTH_CODE",
  "redirect_uri": "https://oauth.pstmn.io/v1/callback"
}

Resposta:

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "id_token": "ID_TOKEN",
  "token_type": "Bearer",
  "expires_in": 10800
}

▶️ Passo 4 — Chamar API da Calculato

GET https://api.calculato.com.br/v1/empregadores/{idEmpregador}/folhas
Authorization: Bearer ACCESS_TOKEN

▶️ Passo 5 — Renovar com refresh_token

POST https://auth.calculato.com.br/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "refresh_token": "REFRESH_TOKEN"
}

🟧 Integração White-label (Embedded Payroll) via Broker

Em desenvolvimento

Atenção, esse modo de autenticação está em desenvolvimento, utilize a autenticação de integração para testar as APIs e construir integrações.

Neste modelo, o integrador oferece as funcionalidades de folha de pagamento sob a sua própria experiência e marca (Embedded Payroll). O cliente final não precisa acessar diretamente a Calculato.

O backend do integrador autentica-se utilizando um token M2M (client_credentials) e, em seguida, utiliza o Broker da Calculato para realizar a troca por um token válido no contexto correto (usuário e empregador).

Entidades envolvidas

Termo	Descrição
Aplicativo Whitelabel	Aplicação registrada no Developer Portal que representa a integração white-label
Auth Whitelabel	Serviço da Calculato responsável por trocar autenticação externa por token interno
ExternalUserLink	Associação entre usuário externo e usuário interno da Calculato
empregadorMap	Mapeamento entre IDs de empregadores externos e internos da Calculato

Passo 1 — Autenticação M2M (client_credentials)

Neste passo ocorre a autenticação do integrador (aplicativo com integração white label aprovada pela Calculato)

POST https://auth.calculato.com.br/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "M2M_CLIENT_ID",
  "client_secret": "M2M_CLIENT_SECRET",
  "audience": "api://whitelabel-broker"
}

Passo 2 — Token exchange via Broker

Neste passo você irá autenticar o seu usuário (empregador) para um acesso da Calculato onde ele terá acesso apenas aos seus dados.

POST https://auth-whitelabel.calculato.com.br/oauth/token
Authorization: Bearer M2M_ACCESS_TOKEN
Content-Type: application/json

{
  "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
  "whitelabelAppId": "64f8c3ab1234ef567890abcd",
  "externalUserId": "user-123",
  "externalEmployerId": "emp-999"
}

Resposta

{
  "accessToken": "ACCESS_TOKEN_CALCULATO",
  "tokenType": "Bearer",
  "expiresIn": 10800
}

📌 Exemplos de Código

Obter M2M Token (Node.js)

import axios from "axios";

async function getM2mToken() {
  const res = await axios.post(
    "https://auth.calculato.com.br/oauth/token",
    {
      grant_type: "client_credentials",
      client_id: process.env.CALCULATO_CLIENT_ID,
      client_secret: process.env.CALCULATO_CLIENT_SECRET,
      audience: "api://whitelabel-broker"
    }
  );

  return res.data.access_token;
}

Chamar o Broker (Node.js)

async function getCalculatoToken(externalUserId, externalEmployerId) {
  const m2m = await getM2mToken();

  const res = await axios.post(
    "https://auth-whitelabel.calculato.com.br/oauth/token",
    {
      grantType: "urn:ietf:params:oauth:grant-type:token-exchange",
      whitelabelAppId: process.env.WL_APP_ID,
      externalUserId,
      externalEmployerId
    },
    {
      headers: { Authorization: `Bearer ${m2m}` }
    }
  );

  return res.data.accessToken;
}

Chamar API da Calculato (Node.js)

async function getFolhas(idEmpregador, calcToken) {
  const res = await axios.get(
    `https://api.calculato.com.br/v1/empregadores/${idEmpregador}/folhas`,
    {
      headers: { Authorization: `Bearer ${calcToken}` }
    }
  );

  return res.data;
}

🧩 Glossário

Termo	Definição
Access Token	Token usado para acessar APIs
Refresh Token	Token usado para renovar tokens expirados
M2M Token	Token gerado via client_credentials para autenticação backend→backend
Broker	Serviço da Calculato que converte autenticação externa em token interno
Whitelabel	Integração onde a Calculato opera de forma invisível para o usuário
Integração Conectada ao Cliente	Modelo onde o cliente final autentica na Calculato e autoriza um sistema integrador a operar em seu nome
Embedded Payroll	Modelo de integração onde a Calculato atua como motor de folha de pagamento invisível ao usuário final
Customer-Authorized Integration	Nome em inglês para Integração Conectada ao Cliente

Índice​

Requisito comum: Bearer Token​

Como escolher o tipo de autenticação​

Integração Conectada ao Cliente (OAuth2 + PKCE)​

Credenciais fornecidas ao integrador​

Visão geral do fluxo​

Passo a passo (OAuth2 + PKCE)​

▶️ Passo 1 — Redirecionar usuário para o login da Calculato​

▶️ Passo 2 — Receber o authorization code​

▶️ Passo 3 — Trocar o code por tokens​

▶️ Passo 4 — Chamar API da Calculato​

▶️ Passo 5 — Renovar com refresh_token​

🟧 Integração White-label (Embedded Payroll) via Broker​

Entidades envolvidas​

Passo 1 — Autenticação M2M (client_credentials)​

Passo 2 — Token exchange via Broker​

Resposta​