Como integrar API de CPF em aplicações 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 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:

#!/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

    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:

#!/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 retorna JSON com os dados cadastrais do CPF consultado:

{
    "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:

#!/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.

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 — 50 consultas mensais gratuitas, sem cartão de crédito.