Como enviar dados para uma API REST com POST em Python

Enviar dados para uma API REST com POST em Python é uma das tarefas mais comuns na integração de sistemas. Enquanto um pedido GET serve para ler informação, o método POST serve para enviar dados novos — criar um cliente, submeter um formulário ou registar uma encomenda. A boa notícia é que, com a biblioteca requests, bastam poucas linhas para o fazer de forma limpa e legível.

Pré-requisitos

• Python 3.8 ou superior instalado no teu computador.
• A biblioteca requests (instalamo-la no Passo 1).
• Um endpoint que aceite POST. Para aprender, vamos usar o serviço público de testes https://httpbin.org/post, que devolve exatamente aquilo que enviamos.
• Conhecer os dicionários de Python, pois são a base dos dados que vamos enviar.

Passo 1: Instalar e importar a biblioteca requests

A biblioteca requests não vem incluída no Python, por isso instalamo-la com o pip. No terminal, corre o seguinte comando:

pip install requests

Depois, no início do teu script, importa-a para a poderes usar:

import requests

Passo 2: Preparar os dados que vais enviar

Quase todas as APIs modernas trocam informação em formato JSON. Em Python, o mais prático é começar por um dicionário normal com os campos que queremos enviar. Vamos imaginar que estamos a criar um novo cliente:

novo_cliente = {
    "nome": "Ana Silva",
    "email": "ana.silva@exemplo.pt",
    "plano": "premium"
}

Repara que não precisas de converter este dicionário para texto JSON à mão. Como vais ver no passo seguinte, a biblioteca requests faz essa conversão por ti. Podes incluir números, texto e até listas ou dicionários dentro dele — a estrutura é convertida para JSON tal como está.

Passo 3: Enviar os dados com requests.post

Para enviar o dicionário como JSON, usamos requests.post e passamos os dados no parâmetro json=. Este parâmetro trata de duas coisas ao mesmo tempo: converte o dicionário em JSON e define o cabeçalho Content-Type: application/json automaticamente.

url = "https://httpbin.org/post"

resposta = requests.post(url, json=novo_cliente, timeout=10)

Usa sempre json= quando queres enviar JSON, e não data=. Com data=, os campos seriam enviados como um formulário (form), que é um formato diferente e a maioria das APIs de dados não espera.

Dica: o parâmetro timeout=10 evita que o teu programa fique bloqueado para sempre caso a API não responda. Envia-o sempre nos teus pedidos.

Passo 4: Ler a resposta e verificar o código de estado

Depois de enviar o pedido, a API responde com um status code (código de estado). Os códigos 200 (OK) e 201 (Created) indicam que correu tudo bem. Podemos ler esse código e o corpo da resposta assim:

print("Código:", resposta.status_code)

dados = resposta.json()
print(dados)

O método resposta.json() converte a resposta de JSON num dicionário Python, pronto a usar no resto do teu programa.

Passo 5: Tratar erros comuns

Em produção nem sempre tudo corre bem: a API pode recusar os dados ou a rede pode falhar. Para não deixar passar um erro silencioso, usamos raise_for_status(), que lança uma exceção quando o código é de erro (4xx ou 5xx), dentro de um bloco try:

try:
    resposta = requests.post(url, json=novo_cliente, timeout=10)
    resposta.raise_for_status()
    print("Cliente criado:", resposta.json())
except requests.exceptions.HTTPError as erro:
    print("A API devolveu um erro:", erro)
except requests.exceptions.RequestException as erro:
    print("Falha de ligação:", erro)

Desta forma, distingues claramente um erro devolvido pela API (por exemplo, 400 Bad Request quando faltam campos) de um problema de rede, como um timeout ou uma falha de DNS.

Verificar o resultado

Como estamos a usar o httpbin.org/post, a resposta devolve tudo o que enviámos dentro de um campo json. Se vires os teus campos (nome, email e plano) refletidos na resposta, acompanhados de um código 200, então o envio funcionou. Numa API real, confirma também que o novo registo aparece na base de dados ou no painel do serviço.

Conclusão

Com poucas linhas e a biblioteca requests, já consegues enviar dados para qualquer API REST com um pedido POST, ler a resposta e tratar os erros mais frequentes. Um bom próximo passo é aprender a autenticar os teus pedidos com um token no cabeçalho Authorization, para trabalhares com APIs privadas. Qual vai ser a primeira API a que vais enviar os teus dados?