Appearance
Apêndice 1 - Configurações de Segurança
1. Visão Geral Rápida
| Etapa | O que acontece (visão simples) | Você recebe | Para que serve |
|---|---|---|---|
| 1 | Você solicita uma chave de acesso | Chave temporária | Permite usar a API |
| 2 | A chave fica válida por curto período | Texto longo | Usar em suas ações |
| 3 | Você faz as consultas ou registros informando o token | Dados / Confirmação | Executar o que precisa |
| 4 | Ao expirar, basta gerar outra chave | Nova chave | Permite usar a API |
Passo a Passo Rápido
- Peça à equipe técnica suas credenciais iniciais (se ainda não tiver).
- Gere a chave de acesso (exemplo ilustrativo mais abaixo) usando a ferramenta indicada internamente.
- Copie somente o valor chamado access_token (é uma sequência longa de caracteres).
- Use essa chave nas consultas ou registros (a ferramenta ou exemplo pedirá que informe como "Bearer ").
- Se receber mensagem de acesso expirado, gere novamente. É normal expirar em pouco tempo.
Entendendo os Placeholders dos Exemplos
Nos comandos de exemplo aparecem palavras entre chaves {} ou nomes em MAIÚSCULAS. Elas não devem ser usadas literalmente; substitua conforme abaixo:
| Placeholder | O que representa | Onde obter / Como preencher |
|---|---|---|
| url-ambiente | Endereço base do ambiente (ex: domínio de teste ou produção) | Consulte a tabela de ambientes (Parte 5) |
| rota | Caminho específico do recurso que deseja acessar (ex: pedidos, relatorios) | Definido pelo catálogo de APIs disponível |
| TOKEN | A chave de acesso retornada após gerar o token | Gerada pelo processo da Parte 2 Como Obter a Chave (Visão Simples) |
| CLIENT_ID | Identificador da sua aplicação | Fornecido pela equipe técnica |
| CLIENT_SECRET | Código confidencial associado ao CLIENT_ID | Fornecido pela equipe técnica (não compartilhar) |
| API_BASE_URL | Versão em variável de ambiente de | Preenchida conforme ambiente (Parte 5) |
| ITEM_ID | Identificador de um item específico | Obtido ao listar ou previamente cadastrado |
Sempre que vir {url-ambiente}, pense: “qual ambiente estou usando agora?” (DEV / HOMOLOG / PRE-PROD/ PROD). Use a linha correspondente da tabela da parte 5. Observação: Se você copiar e colar um exemplo sem substituir os placeholders, a chamada falhará.
2. Como Obter a Chave (Visão Simples)
O fluxo visual de como obter essa chave deve ser visualizado através da Parte 3 deste documento. Se a chave expirar, basta repetir o processo para gerar uma nova. Você precisará apenas da URL fornecida internamente e das credenciais que recebeu. A parte técnica (formato, campos) é específica da ferramenta utilizada e definida pela equipe.
Exemplo Ilustrativo de Solicitação da chave utilizando curl
bash
curl -X POST "https://{url-ambiente}/v1/keycloak/oidc/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=${CLIENT_ID}" \
-d "client_secret=${CLIENT_SECRET}"Nota: Substitua {url-ambiente} conforme tabela da Seção 6.
Exemplo de Resposta
json
{
"access_token": "{TOKEN}",
"expires_in": 60,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "profile email"
}Observação: expires_in = 60 significa que o token expira em 60 segundos. Programe a renovação ou trate respostas 401.
Exemplo Ilustrativo de Solicitação da chave utilizando Insomnia
Na imagem acima está sendo acessada a url: https://{url-ambiente}/v1/keycloak/oidc/token e o token está sendo devolvido no elemento JSON “access_token”.
3. Usando a Chave nas Ações
Em qualquer operação realizada para API (consultar, incluir, alterar, remover), a chave deve acompanhar a solicitação. Normalmente há um campo de autorização onde você informa: Bearer <sua_chave>.
Exemplo de Consulta usando curl
A requisição abaixo busca o token e guarda na variável TOKEN
bash
TOKEN=$(curl -s -X POST "https://{url-ambiente}/v1/keycloak/oidc/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=${CLIENT_ID}" \
-d "client_secret=${CLIENT_SECRET}" | jq -r '.access_token')Usa a variável token armazenada acima para realizar uma requisição de consulta na API do CADURB
bash
curl -X GET "https://{url-ambiente}/api/v1/{rota}" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Accept: application/json"Substitua {rota} pelo recurso desejado (ex: {codigoIbge}/uis) e {url-ambiente} conforme Parte 5.
Exemplo de Inclusão de Dados através do curl usando a variável TOKEN armazenada
bash
curl -X POST "https://{url-ambiente}/api/v1/{rota}" \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{"campo":"valor"}'Use a tabela de ambientes (Parte 5) para preencher {url-ambiente}.
Exemplo de Inclusão de Dados através do Insomnia
Nesse caso específico, a ferramenta Insomnia permite configurar a URL de busca de token (no campo ACCESS TOKEN URL na figura) de forma que além da busca, se o token estiver expirado, já será substituído automaticamente pelo novo.
Principais Retornos (como interpretar)
| Código | Significa que... | O que fazer |
|---|---|---|
| 200/201 | Deu certo | Usar resultado normalmente |
| 400 | Pedido com dado faltando ou incorreto | Rever informação enviada |
| 401 | Chave expirada ou inválida | Gerar nova chave |
| 403 | Você não tem permissão | Solicitar acesso à equipe |
| 404 | Endereço não existe | Confirmar endereço usado |
| 500 | Falha interna do sistema | Avisar a equipe de suporte |
4. Orientações Simples
• Trate a chave como algo confidencial (não repasse em e-mails abertos). • Gere nova chave apenas quando a anterior expirar. • Anote internamente quem está usando (para controle interno se necessário).
4.1 Uso de Ferramentas que Automatizam a Chave
Algumas ferramentas podem facilitar sua rotina ao gerar e renovar a chave automaticamente:
| Ferramenta | Como ajuda | O que você informa uma vez |
|---|---|---|
| Postman | Pode executar uma requisição prévia para URL do token, buscar a chave e armazená-la em variável de ambiente | CLIENT_ID, CLIENT_SECRET |
| Insomnia | Suporta requisições encadeadas: primeiro gera a chave, depois usa nas demais | Mesmos dados do Postman |
| Scripts internos (planilhas conectadas, integrações RPA) | Podem programar nova solicitação quando expira | Parâmetros de geração fornecidos pela equipe |
Funcionamento típico: a ferramenta faz a chamada de geração antes da chamada principal; ao receber a resposta, guarda o access_token e insere automaticamente em "Bearer " nas chamadas seguintes. Quando vence, repete o processo sem você precisar copiar e colar manualmente. Se você notar que está copiando a chave manualmente muitas vezes, vale solicitar à equipe técnica a configuração de automação em uma dessas ferramentas.
5. Tabela de Ambientes
| Ambiente | URL Base ({url-ambiente}) | Endpoint Token | Método Token |
|---|---|---|---|
| TESTE | https://api.receitafederal.gov.br/prr-sinter/ | /v1/keycloak/oidc/token | POST |
| PRODUÇÃO | https://api.sinter.receitafederal.gov.br | /v1/keycloak/oidc/token | POST |
Glossário Simplificado
| Termo | Significado simples |
|---|---|
| Chave (token) | Código temporário que permite usar a API |
| Validade | Tempo que a chave funciona antes de precisar gerar outra |
| Rota (endpoint) | Endereço usado para pedir algo ou registrar informação |
| Consultar | Ver informações |
| Criar | Registrar nova informação |
| Atualizar | Alterar informação existente |
| Remover | Excluir informação |
6. Ajuda Rápida
| Situação | O que significa | Ação sugerida |
|---|---|---|
| Acesso negado (401) | Chave venceu | Gerar nova chave |
| Sem permissão (403) | Perfil sem acesso | Pedir liberação à equipe |
| Não encontra (404) | Endereço errado | Confirmar rota usada |
| Erro interno (500) | Problema no sistema | Informar suporte |
Se alguma dificuldade persistir, anote: data, horário, operação que tentou e código retornado para facilitar o suporte.