Autentica com Basic Auth e retorna um Bearer token para as demais rotas /api/v2/*.
Combine client_id e client_secret como client_id:client_secret, codifique em Base64 e envie:
Authorization: Basic <base64(client_id:client_secret)>
Use placeholders {{clientId}} e {{clientSecret}} nos exemplos; não publique segredos reais.
application/x-www-form-urlencoded)| Parâmetro | Obrigatório | Descrição |
|---|---|---|
| grant_type | Sim | Valor fixo: client_credentials. |
| scope | Sim | Scopes separados por espaço. O token recebe a interseção entre o solicitado, o cadastrado e o vinculado à aplicação. |
| Campo | Tipo | Descrição |
|---|---|---|
| access_token | string | Token para Authorization: Bearer .... |
| token_type | string | Geralmente Bearer. |
| expires_in | integer | Expiração em segundos (tipicamente 3600). |
| Grupo | Scopes |
|---|---|
| Cobranças Pix | cob.read, cob.write |
| Pagamentos Pix | pix.read, pix.write |
| Conta | contas.read, contas.saldo.read, contas.extrato.read, contas.chaves.read |
| Webhooks | webhooks.read, webhooks.write |
| KYC | kyc.background-check.natural-person, kyc.background-check.legal-person |
Lista completa e regras de interseção: Referência login. Guia: Autenticação.
Exemplos cURL e SDK: aba Examples desta operação.
Formato do corpo da requisição. Use `application/x-www-form-urlencoded`.
string"application/x-www-form-urlencoded"
Esta requisição utiliza Basic Authentication no cabeçalho Authorization. As credenciais devem ser enviadas da seguinte forma:
clientId:clientSecretAuthorization: Basic <base64(clientId:clientSecret)>Exemplo:
clientId = "meu_client_id" e clientSecret = "minha_secret""meu_client_id:minha_secret""bWV1X2NsaWVudF9pZDptaW5oYV9zZWNyZXQ="Authorization: Basic bWV1X2NsaWVudF9pZDptaW5oYV9zZWNyZXQ=| Parâmetro | Tipo | Descrição |
|---|---|---|
| grant_type | string | Deve ser "client_credentials" |
| scope | string | Lista de permissões separadas por espaço |
| Campo | Tipo | Descrição |
|---|---|---|
| access_token | string | Token de acesso para autenticação nas demais requisições |
| token_type | string | Tipo do token, geralmente Bearer |
| expires_in | int | Tempo de expiração do token em segundos (tipicamente 3600) |
Este token deve ser utilizado no cabeçalho Authorization nas requisições subsequentes.
Os scopes definem os níveis de permissão concedidos ao token de acesso. Abaixo está uma descrição dos principais scopes suportados pela API.
| Scope | Descrição |
|---|---|
kyc.background-check.natural-person | Permite verificar antecedentes de uma pessoa física. |
kyc.background-check.legal-person | Permite verificar antecedentes de uma pessoa jurídica. |
| Scope | Descrição |
|---|---|
cob.write | Permite criar novas cobranças (recebimento). |
cob.read | Permite visualizar cobranças existentes. |
pix.write | Permite iniciar e confirmar pagamentos Pix (envio). |
pix.read | Permite listar pagamentos Pix. |
| Scope | Descrição |
|---|---|
contas.read | Consultar dados da conta. |
contas.saldo.read | Consultar saldo. |
contas.extrato.read | Consultar extrato. |
contas.chaves.read | Listar chaves Pix da conta. |
| Scope | Descrição |
|---|---|
webhooks.read | Permite listar webhooks cadastrados. |
webhooks.write | Permite criar e gerenciar webhooks. |
| Scope | Descrição |
|---|---|
merchants.read | Permite consultar informações de comerciantes. |
merchants.write | Permite cadastrar e atualizar comerciantes. |
| Scope | Descrição |
|---|---|
terminals.read | Permite listar terminais de pagamento. |
terminals.write | Permite cadastrar e gerenciar terminais. |
| Scope | Descrição |
|---|---|
transactions.read | Permite consultar transações realizadas. |
transactions.write | Permite iniciar transações e criar ou atualizar documentos de comprovante (/api/v2/pagamentos/documents/...). Não existe scope documents.*. |
Os scopes devem ser enviados no parâmetro scope da requisição de autenticação, separados por espaço. O token final contém apenas a interseção entre: scopes solicitados, scopes cadastrados e scopes vinculados à aplicação. Scopes desconhecidos ou não concedidos são descartados (não geram erro no login; a rota depois pode responder 403 Insufficient scope).
Use o nome webhooks.* (plural). Não documente dict.* (órfãos). Não use cobv.* na docs até esses scopes existirem na tabela e estiverem vinculados (hoje as rotas Cobv exigem cobv.read/cobv.write, mas o seeder ainda não os cria; limitação conhecida no ambiente).
Exemplo padrão (sandbox: Cobrança + PIX + Contas + KYC):
--data-urlencode 'scope=cob.read cob.write webhooks.read webhooks.write pix.read pix.write contas.read contas.saldo.read contas.extrato.read contas.chaves.read kyc.background-check.natural-person kyc.background-check.legal-person'
Para Pagamentos via Terminais, acrescente merchants.read merchants.write terminals.read terminals.write transactions.read transactions.write. Documentos de comprovante (impressão POS) usam transactions.write; não há scope documents.* separado.
Guia: Autenticação.
curl --location 'https://api-h.nuvende.com.br/api/v2/auth/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--user '{{ clientId }}:{{ clientSecret }}' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=cob.read cob.write webhooks.read webhooks.write pix.read pix.write contas.read contas.saldo.read contas.extrato.read contas.chaves.read kyc.background-check.natural-person kyc.background-check.legal-person'
const axios = require("axios");
const qs = require("querystring");
const clientId = "{{ clientId }}";
const clientSecret = "{{ clientSecret }}";
const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
const data = qs.stringify({
grant_type: "client_credentials",
scope:
"cob.read cob.write webhooks.read webhooks.write pix.read pix.write contas.read contas.saldo.read contas.extrato.read contas.chaves.read kyc.background-check.natural-person kyc.background-check.legal-person",
});
axios({
method: "post",
url: "https://api-h.nuvende.com.br/api/v2/auth/login",
headers: {
"Content-Type": "application/x-www-form-urlencoded",
Authorization: `Basic ${credentials}`,
},
data,
})
.then((response) => console.log(JSON.stringify(response.data)))
.catch((error) => console.log(error.response?.data || error.message));
import requests
import base64
url = "https://api-h.nuvende.com.br/api/v2/auth/login"
client_id = "{{ clientId }}"
client_secret = "{{ clientSecret }}"
credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()
payload = {
"grant_type": "client_credentials",
"scope": "cob.read cob.write webhooks.read webhooks.write pix.read pix.write contas.read contas.saldo.read contas.extrato.read contas.chaves.read kyc.background-check.natural-person kyc.background-check.legal-person",
}
headers = {
"Content-Type": "application/x-www-form-urlencoded",
"Authorization": f"Basic {credentials}",
}
response = requests.post(url, headers=headers, data=payload)
print(response.text)
<?php
$clientId = "{{ clientId }}";
$clientSecret = "{{ clientSecret }}";
$credentials = base64_encode("$clientId:$clientSecret");
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-h.nuvende.com.br/api/v2/auth/login",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "grant_type=client_credentials&scope=cob.read%20cob.write%20webhooks.read%20webhooks.write%20pix.read%20pix.write%20contas.read%20contas.saldo.read%20contas.extrato.read%20contas.chaves.read%20kyc.background-check.natural-person%20kyc.background-check.legal-person",
CURLOPT_HTTPHEADER => [
"Content-Type: application/x-www-form-urlencoded",
"Authorization: Basic " . $credentials,
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
{
"access_token": "{{access_token}}",
"token_type": "Bearer",
"expires_in": 3600
}
{
"message": "Invalid token",
"error": ["invalid_credentials"]
}
{
"message": "Insufficient scope",
"error": ["insufficient_scope"]
}
Scope ausente no login pode gerar 403 Insufficient scope na rota chamada depois.