# Como integrar API de CPF em aplicações COBOL via wrapper HTTP

> Aprenda a integrar uma API de consulta de CPF em aplicações COBOL usando wrappers HTTP em Python e shell script. Guia para mainframes e legados.

**Publicado:** 05/07/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-api-de-cpf-em-aplicacoes-cobol-via-wrapper-http

---


Para integrar uma API de CPF a aplicações COBOL, use um wrapper HTTP — um programa intermediário em Python ou shell script que recebe o CPF do COBOL, consulta a API REST e devolve os dados em registro de tamanho fixo. O COBOL não precisa fazer chamadas HTTP diretamente: ele invoca o wrapper via `CALL 'SYSTEM'` e lê o resultado de um arquivo de texto estruturado. A [OWASP](https://owasp.org) recomenda que chaves de API sejam armazenadas em variáveis de ambiente, nunca embutidas no código-fonte.

## Introdução

O **COBOL** continua sendo a espinha dorsal de muitos sistemas críticos no Brasil, especialmente em bancos, seguradoras, órgãos governamentais e grandes corporações. Estima-se que mais de 200 bilhões de linhas de código COBOL ainda estejam em produção no mundo, processando trilhões de transações diariamente.

Embora o COBOL não possua suporte nativo a requisições HTTP modernas, é perfeitamente possível integrar uma **API de consulta de CPF** a essas aplicações utilizando **wrappers HTTP** — programas intermediários escritos em linguagens como Python, Shell Script ou Java que fazem a ponte entre o COBOL e a API REST.

---

## 1. Estratégias de integração

Existem três abordagens principais para conectar aplicações COBOL a APIs REST:

* **Wrapper via shell script** — O programa COBOL invoca um script Bash que executa a requisição HTTP com cURL e retorna o resultado em um arquivo intermediário.

* **Wrapper via Python** — Similar ao shell script, mas utilizando Python para maior controle sobre o parsing de JSON e tratamento de erros.

* **Wrapper via Java (JNI ou CICS)** — Em mainframes IBM, é possível usar Java via CICS Transaction Gateway ou JNI para fazer chamadas HTTP.

---

## 2. Abordagem 1 — Wrapper em Shell Script com cURL

### O script de wrapper

Crie um shell script que recebe o CPF como parâmetro e retorna os dados em um arquivo de texto formatado para leitura pelo COBOL:

```bash
#!/bin/bash
# cpfhub_wrapper.sh - Wrapper HTTP para consulta de CPF
# Uso: ./cpfhub_wrapper.sh <CPF> <ARQUIVO_SAIDA>

CPF="$1"
SAIDA="$2"
API_KEY="SUA_CHAVE_DE_API"
URL="https://api.cpfhub.io/cpf/${CPF}"

# Consultar a API com timeout de 30 segundos
RESPOSTA=$(curl -s -X GET "$URL" \
 -H "x-api-key: ${API_KEY}" \
 -H "Accept: application/json" \
 --max-time 30)

# Verificar se a consulta foi bem-sucedida
SUCESSO=$(echo "$RESPOSTA" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('success','false'))" 2>/dev/null)

if [ "$SUCESSO" = "True" ] || [ "$SUCESSO" = "true" ]; then
 # Extrair campos e formatar para COBOL (campos de tamanho fixo)
 echo "$RESPOSTA" | python3 -c "
import sys, json
d = json.load(sys.stdin)['data']
# Formato: CPF(11) | NOME(60) | GENERO(1) | NASCIMENTO(10) | STATUS(2)
cpf = d['cpf'].ljust(11)
nome = d['nameUpper'][:60].ljust(60)
genero = d['gender'].ljust(1)
nascimento = d['birthDate'].ljust(10)
status = 'OK'
print(f'{cpf}{nome}{genero}{nascimento}{status}')
" > "$SAIDA"
else
 # Registro de erro com campos vazios
 printf '%-11s%-60s%-1s%-10s%-2s\n' "$CPF" '' '' '' 'ER' > "$SAIDA"
fi

exit 0
```

### O programa COBOL

```cobol
 IDENTIFICATION DIVISION.
 PROGRAM-ID. CONSULTA-CPF.
 ENVIRONMENT DIVISION.
 INPUT-OUTPUT SECTION.
 FILE-CONTROL.
 SELECT RESULTADO-API ASSIGN TO 'cpf_resultado.txt'
 ORGANIZATION IS LINE SEQUENTIAL.
 DATA DIVISION.
 FILE SECTION.
 FD RESULTADO-API.
 01 REG-RESULTADO.
 05 API-CPF PIC X(11).
 05 API-NOME PIC X(60).
 05 API-GENERO PIC X(1).
 05 API-NASCIMENTO PIC X(10).
 05 API-STATUS PIC X(2).

 WORKING-STORAGE SECTION.
 01 WS-CPF PIC X(11).
 01 WS-COMANDO PIC X(200).

 PROCEDURE DIVISION.
 INICIO.
 MOVE '12345678900' TO WS-CPF
 STRING './cpfhub_wrapper.sh '
 WS-CPF ' cpf_resultado.txt'
 DELIMITED BY SIZE INTO WS-COMANDO
 END-STRING

 CALL 'SYSTEM' USING WS-COMANDO

 OPEN INPUT RESULTADO-API
 READ RESULTADO-API INTO REG-RESULTADO
 AT END
 DISPLAY 'Erro: arquivo vazio'
 NOT AT END
 IF API-STATUS = 'OK'
 DISPLAY 'Nome: ' API-NOME
 DISPLAY 'CPF: ' API-CPF
 DISPLAY 'Genero: ' API-GENERO
 DISPLAY 'Nascimento: ' API-NASCIMENTO
 ELSE
 DISPLAY 'Erro na consulta do CPF'
 END-IF
 END-READ
 CLOSE RESULTADO-API
 STOP RUN.
```

---

## 3. Abordagem 2 — Wrapper em Python

O wrapper em Python oferece melhor tratamento de erros e mais flexibilidade no parsing:

```python
#!/usr/bin/env python3
# cpfhub_wrapper.py - Wrapper HTTP para integração COBOL
# Uso: python3 cpfhub_wrapper.py <CPF> <ARQUIVO_SAIDA>

import sys
import requests
import json

def consultar_cpf(cpf, arquivo_saida):
 api_key = 'SUA_CHAVE_DE_API'
 url = f'https://api.cpfhub.io/cpf/{cpf}'

 headers = {
 'x-api-key': api_key,
 'Accept': 'application/json',
 }

 try:
 response = requests.get(url, headers=headers, timeout=30)
 data = response.json()

 if response.status_code == 200 and data.get('success'):
 info = data['data']
 # Formato de registro fixo para COBOL
 registro = (
 f"{info['cpf']:<11}"
 f"{info['nameUpper'][:60]:<60}"
 f"{info['gender']:<1}"
 f"{info['birthDate']:<10}"
 f"{'OK':<2}"
 )
 else:
 registro = f"{cpf:<11}{'':<60}{'':<1}{'':<10}{'ER':<2}"

 except Exception as e:
 registro = f"{cpf:<11}{'':<60}{'':<1}{'':<10}{'ER':<2}"
 print(f"Erro: {e}", file=sys.stderr)

 with open(arquivo_saida, 'w') as f:
 f.write(registro + '\n')

if __name__ == '__main__':
 if len(sys.argv) != 3:
 print("Uso: python3 cpfhub_wrapper.py <CPF> <ARQUIVO_SAIDA>")
 sys.exit(1)

 consultar_cpf(sys.argv[1], sys.argv[2])
```

---

## 4. Exemplo de resposta da API

A API da [**CPFHub.io**](https://www.cpfhub.io/) retorna JSON com os dados cadastrais do CPF consultado:

```json
{
 "success": true,
 "data": {
 "cpf": "12345678900",
 "name": "Joao da Silva",
 "nameUpper": "JOAO DA SILVA",
 "gender": "M",
 "birthDate": "15/06/1990",
 "day": 15,
 "month": 6,
 "year": 1990
 }
}
```

O wrapper converte esses dados JSON em registros de tamanho fixo que o COBOL consegue ler facilmente, respeitando a forma como a linguagem manipula dados.

---

## 5. Processamento em lote

Para processar múltiplos CPFs de uma vez, use um script de lote com intervalo entre chamadas para economizar cota:

```bash
#!/bin/bash
# batch_cpf.sh - Processamento em lote de CPFs
# Uso: ./batch_cpf.sh cpfs_entrada.txt resultados_saida.txt

ENTRADA="$1"
SAIDA="$2"

> "$SAIDA"

while IFS= read -r CPF; do
 CPF_LIMPO=$(echo "$CPF" | tr -dc '0-9')
 if [ ${#CPF_LIMPO} -eq 11 ]; then
 ./cpfhub_wrapper.sh "$CPF_LIMPO" temp_resultado.txt
 cat temp_resultado.txt >> "$SAIDA"
 sleep 1 # Pausa entre consultas para economizar cota
 fi
done < "$ENTRADA"

rm -f temp_resultado.txt
echo "Processamento concluido. Resultados em $SAIDA"
```

---

## 6. Considerações de segurança e infraestrutura

Ao integrar APIs externas em ambientes COBOL, considere os seguintes pontos:

* **Armazenamento da chave de API** — Em mainframes, armazene a chave em variáveis de ambiente protegidas ou em arquivos com permissões restritas. Nunca inclua a chave diretamente no código COBOL.

* **Conectividade de rede** — Mainframes podem ter restrições de firewall para conexões HTTPS externas. Valide a conectividade com a URL `https://api.cpfhub.io` antes de iniciar a integração.

* **Logging e auditoria** — Registre todas as consultas realizadas para fins de auditoria e conformidade com a LGPD.

* **Planos adequados** — O plano gratuito (50 consultas/mês) é ideal para testes. Para produção em sistemas bancários, considere o plano Corporativo com SLA de 99,9% e suporte prioritário.

---

## 7. Alternativas para mainframes IBM

Em ambientes IBM z/OS, existem alternativas adicionais:

* **CICS Web Services** — O CICS permite fazer chamadas HTTP diretamente, sem a necessidade de wrappers externos.

* **IBM z/OS Connect** — Fornece uma camada de APIs que pode intermediar a comunicação entre o COBOL e serviços REST.

* **Java via JNI** — É possível chamar código Java a partir do COBOL para executar requisições HTTP.

Essas abordagens são mais complexas, mas oferecem melhor integração com o ecossistema do mainframe.

---

## Perguntas frequentes

### O COBOL consegue fazer chamadas HTTP diretamente para uma API REST?

Na maioria dos ambientes, não. O COBOL padrão não possui bibliotecas nativas para HTTP. A solução é usar um wrapper externo — script shell com cURL ou programa Python — invocado via `CALL 'SYSTEM'`. Em mainframes IBM com CICS ou z/OS Connect, há alternativas que permitem chamadas HTTP sem sair do ambiente COBOL.

### Como o wrapper passa os dados de volta para o programa COBOL?

O wrapper grava um arquivo de texto com registros de tamanho fixo — o formato que o COBOL lê de forma nativa. Cada campo ocupa um número fixo de caracteres (CPF: 11, nome: 60, gênero: 1, nascimento: 10, status: 2). O COBOL define a estrutura via `PIC X(n)` e lê o arquivo sequencialmente.

### A API da CPFHub.io bloqueia chamadas em lote do COBOL?

Não. A API da CPFHub.io não bloqueia chamadas ao atingir o limite do plano — consultas excedentes são cobradas a R$0,15 cada. Para processamento em lote com COBOL, adicione uma pausa de 1 segundo entre consultas para gerenciar o ritmo de consumo de cota, não por restrição da API.

### Como proteger a chave de API em um ambiente mainframe?

Nunca embutir a chave no código-fonte COBOL ou no script wrapper. Use variáveis de ambiente do sistema operacional (shell) ou um arquivo de configuração com permissões restritas (chmod 600). Em ambientes IBM z/OS, o RACF pode ser usado para controlar o acesso ao arquivo que contém a chave.

### Leia também

- [SLA de API de CPF: níveis de disponibilidade que você precisa conhecer](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [API de consulta de CPF vs. consulta manual: qual é a melhor opção?](https://cpfhub.io/blog/api-de-consulta-de-cpf-vs-consulta-manual-qual-e-a-melhor-opcao)

---

## Conclusão

Integrar uma API de consulta de CPF em aplicações COBOL é viável e prático quando utilizamos wrappers HTTP como intermediários. Seja por meio de shell scripts com cURL ou programas Python, é possível modernizar sistemas legados sem a necessidade de reescrevê-los completamente.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito.