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.
Outros recursos
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.