API: o que e e como integra sistemas diferentes?

O que e uma API?

Uma API e um conjunto de regras e definicoes que permite que dois sistemas de software se comuniquem entre si. Pense como um garcom em um restaurante: voce (o cliente) faz um pedido, o garcom (API) leva ate a cozinha (o sistema) e traz de volta o resultado (a comida pronta). A API e o intermediario que padroniza e gerencia essa comunicacao.

Sem uma API, cada sistema precisaria saber exatamente como o outro funciona internamente — o que seria inviavel. A API abstrai a complexidade: quem consome a API so precisa saber o que pedir (requisicao) e o que vai receber (resposta), sem se preocupar com a implementacao interna.

O que e uma API REST?

REST (Representational State Transfer) e o estilo arquitetural mais comum para APIs web. Uma API REST utiliza os metodos HTTP padrao para realizar operacoes em recursos (dados) expostos pelo servidor:

• GET — Ler/recuperar dados. Ex: GET /api/produtos retorna a lista de produtos. Nao altera o estado do servidor.
• POST — Criar um novo recurso. Ex: POST /api/usuarios com dados do novo usuario no corpo da requisicao.
• PUT — Substituir um recurso inteiro. Ex: PUT /api/usuarios/1 com os dados completos atualizados.
• PATCH — Atualizar parcialmente um recurso. Ex: PATCH /api/usuarios/1 com apenas { "nome": "Novo Nome" }.
• DELETE — Remover um recurso. Ex: DELETE /api/usuarios/1.

Uma API bem projetada segue o principio RESTful: usa URLs que representam recursos (substantivos, nao verbos), opera com metodos HTTP padrao e e stateless (cada requisicao contem toda a informacao necessaria, sem depender de estado armazenado no servidor).

Requisicoes e respostas HTTP

Toda comunicacao com uma API REST acontece via HTTP. Cada requisicao contem:

• URL — O endereco do recurso, como https://api.cloudbird.com.br/v1/produtos.
• Metodo — GET, POST, PUT, PATCH ou DELETE.
• Headers — Metadados da requisicao: tipo de conteudo (Content-Type: application/json), autenticacao (Authorization: Bearer <token>), etc.
• Body — Dados enviados (presente em POST, PUT, PATCH). Geralmente em JSON.

A resposta do servidor inclui:

• Status code — Um numero de tres digitos que indica o resultado da operacao.
• 200 OK — Requisicao bem-sucedida (GET, PUT, PATCH).
• 201 Created — Recurso criado com sucesso (POST).
• 400 Bad Request — Requisicao mal formatada ou dados invalidos.
• 401 Unauthorized — Autenticacao ausente ou invalida.
• 403 Forbidden — Autenticado mas sem permissao.
• 404 Not Found — Recurso inexistente.
• 422 Unprocessable Entity — Dados validos mas que violam regras de negocio.
• 429 Too Many Requests — Rate limit excedido.
• 500 Internal Server Error — Erro inesperado no servidor.

Body — O conteudo da resposta, normalmente em JSON, contendo os dados solicitados ou uma mensagem de erro.

JSON — O formato universal de dados

JSON (JavaScript Object Notation) e o formato padrao para troca de dados em APIs modernas. Ele e leve, legivel por humanos e facil de processar por qualquer linguagem de programacao. Um exemplo tipico:

{ "id": 1, "nome": "Site Institucional", "preco": 1490, "categoria": { "id": 2, "nome": "Sites" } }

O JSON suporta tipos basicos: strings, numeros, booleanos, arrays (listas entre colchetes) e objetos aninhados (entre chaves). Quase toda linguagem tem funcoes nativas para converter JSON em objeto e vice-versa (JSON.parse() e JSON.stringify() em JavaScript).

Embora XML ja tenha sido o padrao, o JSON o superou por ser mais simples e mais rapido de processar. Hoje, XML e usado principalmente em integracoes legadas (sistemas bancarios, NF-e).

Autenticacao em APIs

Nem toda API e publica. Quando um sistema precisa se identificar, existem tres metodos principais:

API Key

O metodo mais simples. O servico fornece uma chave unica (ex: sk_live_abc123) que deve ser enviada em toda requisicao, geralmente no header ou como parametro de URL. E usada por servicos como Mercado Pago e Google Maps. A desvantagem e que a chave e menos segura, pois e estatica.

JWT (JSON Web Token)

JWT e um padrao moderno e seguro para autenticacao stateless. O usuario faz login com email e senha e recebe um token criptografado que contem dados como ID do usuario e data de expiracao. Esse token e enviado no header Authorization: Bearer <token> em todas as requisicoes subsequentes. O servidor valida a assinatura criptografica sem precisar consultar o banco — o token em si ja e a prova de autenticidade.

JWT e amplamente usado em aplicacoes modernas por ser escalavel (nao requer sessao no servidor) e seguro (assinado digitalmente).

OAuth 2.0

OAuth 2.0 e um protocolo de autorizacao que permite que um aplicativo acesse recursos em nome de um usuario sem compartilhar a senha. Exemplo: "Faca login com o Google" — o Google nao revela sua senha para o site, apenas emite um token temporario que autoriza o acesso a dados especificos (como seu nome e email). OAuth e mais complexo de implementar, mas e o padrao para integracoes com APIs de grandes plataformas (Google, Facebook, GitHub).

Exemplos praticos de integracao com APIs

No dia a dia de um site moderno, as APIs estao em toda parte. Veja exemplos reais que implementamos na CloudBird:

Gateway de pagamento — Mercado Pago

Quando um cliente finaliza uma compra, o site nao processa o cartao de credito diretamente (o que exigiria certificacao PCI DSS complexa e arriscada). Em vez disso, o front-end envia os dados para a API do Mercado Pago, que retorna um token de pagamento seguro. O servidor entao usa esse token para executar o pagamento via API de backend. O fluxo e:

1. Front-end chama POST /api/mercadopago/card_tokens com dados do cartao.
2. Mercado Pago retorna um token unico (ex: card_tok_abc123).
3. Front-end envia o token para seu servidor.
4. Servidor chama POST /v1/payments com o token, valor e descricao.
5. Mercado Pago processa e retorna status: approved, pending ou rejected.
6. Servidor atualiza o pedido no banco de dados com o status recebido.

API do Supabase

O Supabase expoe automaticamente uma API REST para cada tabela do banco PostgreSQL. Com autenticacao JWT e RLS (Row-Level Security), podemos fazer operacoes CRUD diretamente do front-end com seguranca. Exemplo: GET /rest/v1/produtos?select=nome,preco&categoria_id=eq.5&order=preco.asc retorna nome e preco dos produtos da categoria 5 ordenados por preco crescente.

Isso elimina a necessidade de escrever um backend separado para 90% das operacoes de leitura e escrita simples.

WhatsApp Business API

Para enviar notificacoes automaticas (confirmacao de pedido, lembrete de agendamento), integramos com a API do WhatsApp Business via provedores como a Z-API. Uma chamada POST /send-text com numero do destinatario e mensagem e suficiente para disparar a notificacao. O cliente recebe como se fosse uma mensagem normal do WhatsApp.

Boas praticas no consumo de APIs

Trabalhar com APIs exige atencao a detalhes importantes:

Rate limiting

APIs publicas geralmente limitam o numero de requisicoes que um cliente pode fazer em um intervalo de tempo (ex: 100 requisicoes/minuto). Isso protege o servidor contra abusos. Headers como X-RateLimit-Remaining indicam quantas requisicoes ainda podem ser feitas. Implemente retry com backoff exponencial para lidar com respostas 429.

Paginacao

APIs nunca retornam todos os registros de uma vez. Use parametros como ?page=2&limit=20 ou ?offset=20&limit=20 para navegar pelos resultados. A resposta geralmente inclui metadados como total de registros e links para proxima pagina.

Tratamento de erros

Sempre trate erros de API no front-end: mostre mensagens amigaveis, registre logs, implemente retry automatico para erros temporarios (500, 502, 503). Nunca deixe o usuario vendo uma tela branca ou erro tecnico.

Como usamos APIs na CloudBird

Na CloudBird, as APIs sao parte essencial da nossa stack. Cada projeto pode se beneficiar de integracoes sem que o cliente precise se preocupar com a complexidade tecnica:

• Supabase (database + auth) — API REST automatica sobre PostgreSQL, autenticacao JWT embutida, real-time subscriptions e armazenamento de arquivos. E a base de todos os projetos com dados dinamicos.
• Mercado Pago — Gateway de pagamento para e-commerces. Integracao com checkout transparente (o cliente paga sem sair do site) e checkout redirect (pagina externa do Mercado Pago).
• WhatsApp API (Z-API) — Notificacoes automaticas de pedidos, lembretes e suporte direto pelo WhatsApp.
• Google APIs — Google Maps para localizacao, reCAPTCHA para seguranca de formularios, Google Analytics e Search Console para metricas.
• APIs de transportadoras — Calculo de frete em tempo real com Correios, Jadlog e outras.

Cada integracao e feita com foco em seguranca: chaves armazenadas em variaveis de ambiente, tokens JWT com expiracao curta, comunicacao sempre via HTTPS e logs de auditoria para todas as chamadas.

API vs SDK vs Webhook

Esses tres conceitos sao frequentemente confundidos. Vamos diferencia-los:

• API — Interface que voce chama ativamente para obter dados ou executar acoes. Ex: GET /api/clima retorna a previsao do tempo.
• SDK (Software Development Kit) — Um conjunto de ferramentas e bibliotecas que facilitam o consumo de uma API. Em vez de fazer requisicoes HTTP manuais, voce usa funcoes da SDK. Ex: mercadopago.createPayment({ ... }).
• Webhook — O inverso da API: o servidor te chama quando algo acontece. Voce registra uma URL (endpoint) no sistema, e ele envia uma requisicao POST para essa URL sempre que um evento ocorrer. Ex: o Mercado Pago envia um webhook para seu servidor quando um pagamento e confirmado.

Webhooks sao essenciais para automatizar fluxos: ao inves de ficar perguntando (polling) se o pagamento foi aprovado, o sistema avisa automaticamente.

Documentacao de APIs

Uma API so e util se for bem documentada. Os padroes modernos de documentacao incluem:

• OpenAPI (Swagger) — Formato padrao para descrever APIs REST. Gera documentacao interativa onde voce pode testar as chamadas diretamente do navegador.
• GraphQL — Alternativa ao REST onde o cliente especifica exatamente quais dados quer, eliminando over-fetching e under-fetching. Usado por GitHub, Shopify e Netflix.

Toda API que construimos na CloudBird e documentada com OpenAPI (Swagger), permitindo que o cliente entenda exatamente como consumir seus proprios dados, caso precise de integracoes futuras.

APIs sao a cola que conecta o ecossistema moderno de tecnologia. Um site sem APIs e uma ilha; com APIs, ele se torna um hub integrado a um universo de possibilidades — pagamento, comunicacao, logistica, inteligencia artificial e muito mais.