Pular para o conteúdo
apiwpp
Recurso

OpenAPI 3.1 e clientes TypeScript e PHP

Especificação OpenAPI 3.1 pública, referência interativa em português e clientes TypeScript e PHP gerados da especificação, com tipos de cada rota e resposta.

Atualizado em

Integrar uma API sem contrato é adivinhar: o nome de um campo, o formato de uma data, o que volta num erro. A apiwpp descreve cada rota, corpo, resposta e evento de webhook numa especificação OpenAPI 3.1 pública. É dela que saem a referência da documentação e os clientes TypeScript e PHP, então o que está escrito na documentação e o que o cliente aceita são a mesma coisa.

A especificação OpenAPI 3.1

A especificação é um arquivo JSON público, em português e em inglês, que você baixa sem conta nem chave:

curl -s https://docs.apiwpp.com/openapi.json -o openapi.json

Ela cobre as rotas de conexões, envio, templates, fila, registros e chaves de API, com o esquema de cada corpo e de cada resposta, os escopos que cada operação exige e o formato dos erros ({ error }, com code nos erros de validação e de limite). Os eventos de webhook também estão lá, na seção webhooks da especificação, com o envelope e o data de cada tipo.

Com o arquivo em mãos, você usa as ferramentas que já conhece: importa no Postman ou no Insomnia, gera um cliente na sua linguagem ou valida as suas chamadas em testes.

Referência interativa em português

A mesma especificação alimenta a referência da API, em português: cada operação com a descrição, os parâmetros, exemplos de corpo e de resposta e os códigos de erro possíveis. Ao lado dela ficam os guias, também em português: início rápido, pareamento, envio, webhooks e assinatura, idempotência, LID, erros, limites e clientes gerados. Tudo está em docs.apiwpp.com.

Cliente TypeScript com openapi-fetch

O cliente TypeScript é gerado com o openapi-typescript, que transforma a especificação em tipos, e faz as chamadas com o openapi-fetch, uma camada fina sobre o fetch. Cada caminho, parâmetro, corpo e resposta é tipado: se você errar o nome de um campo ou esquecer o id da conexão, o editor avisa antes de rodar.

Você não precisa esperar um pacote para ter isso. Gere os tipos no seu projeto e instale o openapi-fetch:

npx openapi-typescript https://docs.apiwpp.com/openapi.json -o src/apiwpp.d.ts
npm install openapi-fetch
import createClient from 'openapi-fetch'
import type { paths } from './apiwpp'

const apiwpp = createClient<paths>({
  baseUrl: 'https://api.apiwpp.com',
  headers: { Authorization: `Bearer ${process.env.APIWPP_KEY}` },
})

const { data, error, response } = await apiwpp.POST('/connections/{id}/send', {
  params: { path: { id: process.env.APIWPP_CONNECTION_ID! } },
  body: { to: '5511988887777', message: 'Olá! Seu pedido 1234 foi confirmado.', clientRef: 'pedido-1234' },
})

if (error) throw new Error(`${response.status}: ${error.error}`)
console.log(data.jobId, data.scheduledAt, data.position)

A resposta 202 já chega tipada, com o jobId, o horário previsto do envio e a posição na fila. Os tipos dos eventos de webhook vêm no mesmo arquivo, prontos para o handler que recebe as entregas depois de verificar a assinatura.

Cliente PHP com OpenAPI Generator e Guzzle

O cliente PHP é gerado com o OpenAPI Generator, sobre Guzzle: uma classe por grupo da referência (MessagesApi, ConnectionsApi…) e um modelo por corpo de requisição e de resposta. Os campos dos modelos seguem o padrão do PHP (client_ref) e voltam ao nome da API (clientRef) no JSON enviado.

Para gerar o seu, remova a seção de webhooks da especificação (o gerador a transformaria em chamadas que não existem) e escolha o namespace:

jq 'del(.webhooks)' openapi.json > openapi.api.json
docker run --rm -v "$PWD:/local" openapitools/openapi-generator-cli:v7.25.0 generate \
  -i /local/openapi.api.json -g php -o /local/apiwpp-php \
  --additional-properties=invokerPackage='Apiwpp\Client'
use Apiwpp\Client\Api\MessagesApi;
use Apiwpp\Client\Configuration;
use Apiwpp\Client\Model\SendMessageRequest;
use GuzzleHttp\Client as HttpClient;

$config = Configuration::getDefaultConfiguration()
    ->setHost('https://api.apiwpp.com')
    ->setAccessToken(getenv('APIWPP_KEY'));

$messages = new MessagesApi(new HttpClient(), $config);

$job = $messages->sendMessage(getenv('APIWPP_CONNECTION_ID'), new SendMessageRequest([
    'to' => '5511988887777',
    'message' => 'Olá! Seu pedido 1234 foi confirmado.',
    'client_ref' => 'pedido-1234',
]));

echo $job->getJobId();

Os clientes são gerados a cada mudança da API, sem código escrito à mão. Eles ainda não estão publicados no npm nem no Packagist: enquanto isso, peça o pacote pronto pelo suporte ou gere-o como acima, a partir da especificação.

Outras linguagens e ferramentas

A API é REST com JSON, então qualquer linguagem com um cliente HTTP funciona sem pacote nenhum: fetch no Node.js, requests no Python, o Http facade no Laravel, curl no terminal. E se a sua linguagem tem um gerador de OpenAPI, a especificação serve para ela também.

Os exemplos completos, com envio, tratamento de 429 e webhook com verificação da assinatura, estão nas páginas de integração com Node.js, TypeScript, PHP e Python, e nos tutoriais de Node.js, PHP e Laravel e Python. A chave que esses exemplos usam é de um projeto, com escopo: veja projetos e chaves de API.

Página de status pública

Uma integração também precisa saber quando o problema não é dela. A página de status é pública e mostra o estado de cada componente da apiwpp. Além das verificações de cada componente, um canário envia mensagens reais entre dois números a cada 10 minutos, então o status reflete o caminho completo de um envio, e não só se a API responde.

Perguntas frequentes

Existe um SDK oficial da apiwpp no npm ou no Packagist?

Ainda não. Os clientes TypeScript e PHP são gerados da especificação OpenAPI 3.1 a cada mudança da API, mas não estão publicados em registros de pacotes. Peça o pacote pronto pelo suporte ou gere-o no seu projeto com o openapi-typescript ou o OpenAPI Generator.

Preciso de um cliente gerado para usar a API?

Não. A API é REST com JSON, e um fetch, um requests ou um curl bastam. O cliente gerado só acrescenta tipos: o editor avisa quando um campo está errado, e as respostas chegam com o formato da especificação.

A especificação descreve os webhooks?

Sim. Os eventos estão na seção webhooks da especificação, com o envelope e o conteúdo de cada tipo. O cliente TypeScript exporta os tipos deles, e o cliente PHP traz um modelo por evento. Verifique a assinatura HMAC antes de confiar no conteúdo.

A documentação está em português?

Sim. A referência interativa e os guias estão em português, e a especificação existe em português e em inglês, em docs.apiwpp.com.

Todos: Recursos →

Cada projeto é um sistema ou cliente seu, com os próprios números, webhook e chaves de API. As chaves têm escopo, validade e rotação com janela de sobreposição, e todos os projetos da conta entram numa fatura só.

Cada evento do número chega no seu servidor com um POST assinado com HMAC-SHA256. A entrega é feita pelo menos uma vez, com novas tentativas, registro de cada entrega e reenvio.

POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt e position. A API resolve o endereço do destinatário, mostra o "digitando…" e avisa o resultado pelo webhook message.delivery.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.