Escopos e permissões

A autorização da API tem dois eixos independentes:

1. Escopos (no padrão OAuth): controlam quais endpoints sua credencial pode chamar e quais campos aparecem na resposta. Catálogo abaixo.
2. Produtos permitidos: lista de produtos do Banqer que sua credencial enxerga. Cada resposta da API é filtrada para incluir apenas dados desses produtos. Esta lista é definida pelo seu gestor Banqer no momento da emissão da credencial e não pode ser alterada pelo seu sistema.

Catálogo de escopos

A API tem cinco escopos, todos de leitura (.read). Cada um carrega um nível de sensibilidade dos dados que libera, alinhado com os princípios da LGPD.

api.cobranca.catalogos.read

Listas de referência do CRM: credores, produtos, carteiras, situações de dívida, tipos de telefone, tipos de ocorrência de acionamento, tipos de equipe de cobrança e empresas de higienização. Não contém dados de devedor.

Endpoints liberados:

• GET /v1/credores
• GET /v1/credores/{idCredor}/produtos
• GET /v1/produtos
• GET /v1/produtos/{idProduto}/carteiras
• GET /v1/catalogos/situacoes-divida
• GET /v1/catalogos/tipos-contato-telefone
• GET /v1/catalogos/tipos-ocorrencia-acionamento
• GET /v1/catalogos/tipos-ocorrencia-contato-telefone
• GET /v1/catalogos/tipos-contato-telefone-efetuado
• GET /v1/catalogos/tipos-equipe-cobranca
• GET /v1/catalogos/empresas-higienizacao

api.cobranca.fichas.read

Fichas de cobrança: saldo, atraso, situação, indicadores analíticos e histórico de ocorrências de acionamento (registros de contato/discagem feitos pelos operadores). Não contém identidade nem contatos do titular.

Endpoints liberados:

• GET /v1/fichas
• GET /v1/fichas/{idFichaCobranca}
• GET /v1/fichas/{idFichaCobranca}/analitico
• GET /v1/fichas/{idFichaCobranca}/ocorrencias
• GET /v1/ocorrencias
• GET /v1/ocorrencias/{idOcorrenciaAcionamento}

api.cobranca.financeiro.read

Dados financeiros completos: contratos, títulos, acordos, parcelas, pagamentos e boletos em PDF. Não contém identidade nem contatos do titular.

Endpoints liberados (13):

• GET /v1/fichas/{idFichaCobranca}/contratos
• GET /v1/fichas/{idFichaCobranca}/acordos
• GET /v1/fichas/{idFichaCobranca}/pagamentos
• GET /v1/contratos/{idContrato}
• GET /v1/contratos/{idContrato}/titulos
• GET /v1/titulos/{idTitulo}
• GET /v1/acordos/{idAcordo}
• GET /v1/acordos/{idAcordo}/parcelas
• GET /v1/acordos/{idAcordo}/parcelas/{idParcela}
• GET /v1/acordos/{idAcordo}/parcelas/{idParcela}/boleto
• GET /v1/acordos/{idAcordo}/boleto-consolidado
• GET /v1/pagamentos
• GET /v1/pagamentos/{idPagamento}

api.cobranca.identidade.read

Identidade pessoal do titular: documento (CPF/CNPJ), nome, sexo, data de nascimento, filiação, profissão, estado civil.

Endpoints liberados:

• GET /v1/pessoas/{idPessoa}
• GET /v1/pessoas:porDocumento
• GET /v1/fichas/{idFichaCobranca}/pessoa

Também atua como modificador nos endpoints de ocorrências (sob fichas.read): quando presente, popula os campos dsObservacao (texto livre da ocorrência) e dsContatoObservacao (texto livre do contato telefônico). Esses textos são registrados pelos operadores e podem conter referências identificáveis ao titular, então seguem o mesmo gate da identidade. Quando ausente, esses campos vêm omitidos da resposta.

api.cobranca.contatos.read

Modificador sobre identidade.read. Combine com identidade.read para receber dados PII de telefone:

• Em endpoints de pessoa: adiciona telefones[], emails[] e enderecos[] às respostas.
• Em endpoints de ocorrências (sob fichas.read + identidade.read): adiciona ddd, numero e telefoneFormatado ao item de ocorrência quando há contato telefônico associado.

contatos.read sozinho não libera nenhum endpoint nem campo: a combinação com identidade.read é obrigatória para ambos os cenários.

Como ler o escopo de um endpoint no Swagger

A página de Referência da API mostra, em cada endpoint, o requisito de escopo no bloco Authorizations ou Security. O nome do escopo aparece dentro do esquema bearer:

GET /v1/fichas
  security:
    - bearer:
        - api.cobranca.fichas.read

A lista dentro de bearer é o conjunto de escopos exigidos. Em V1, todos os endpoints exigem exatamente um escopo.

O que acontece quando o escopo está faltando

Cenário	Resposta
Sem header Authorization ou token inválido/expirado	401 Unauthorized + WWW-Authenticate: Bearer error="invalid_token"
Token válido sem o escopo necessário	403 Forbidden + reason: MISSING_SCOPE
Token tem o escopo mas o produto não está na sua lista	404 Not Found (não revela existência)

Veja o formato detalhado dos erros em Pontos de atenção.

Princípio do menor privilégio

Peça ao seu gestor Banqer apenas os escopos que sua integração realmente precisa. Um chatbot de saldo não precisa de identidade. Um painel de BI agregado não precisa de contatos. Reduzir o conjunto de escopos limita o impacto caso a credencial seja comprometida e atende ao princípio da LGPD de tratamento mínimo necessário.