OpenAPI

O contrato completo da API está publicado em OpenAPI 3.1, com todos os endpoints, schemas, códigos de erro e os payloads dos webhooks (na seção webhooks):

Formato	URL
YAML	https://platform.toptalking.com.br/openapi.yaml
JSON	https://platform.toptalking.com.br/openapi.json

Os dois arquivos têm o mesmo conteúdo e podem ser lidos de qualquer origem (Access-Control-Allow-Origin: *).

Importar em clientes HTTP

Ferramenta	Como
Postman	Import → cole a URL do openapi.yaml. Depois, na coleção, configure Authorization → Bearer Token com a sua chave.
Insomnia	Import → URL → cole a URL do openapi.yaml. Configure a autenticação Bearer no ambiente.
Bruno	Import Collection → OpenAPI V3 Spec → arquivo baixado do openapi.yaml.

Guarde a chave numa variável de ambiente da ferramenta, não dentro das requisições salvas, principalmente se a coleção for compartilhada.

Gerar tipos e clientes

Tipos TypeScript a partir do contrato, com openapi-typescript:

npx openapi-typescript https://platform.toptalking.com.br/openapi.yaml -o src/toptalking-api.d.ts

import type { components } from './toptalking-api';

type Contato = components['schemas']['Contact'];
type Mensagem = components['schemas']['Message'];

Para outras linguagens, use o OpenAPI Generator com a mesma URL. Lembre-se: o cliente gerado deve rodar no servidor, nunca no navegador.

Usar com IA

• ChatGPT: importe a URL do openapi.yaml nas Actions de um GPT personalizado. Passo a passo em ChatGPT.
• Outras IAs: o openapi.yaml é ótimo para a IA conferir nomes de campos e enums. Para explicações e exemplos, combine com o llms-full.txt.

Convenções do contrato

• servers: https://platform.toptalking.com.br/v1.
• Segurança: bearerAuth (Authorization: Bearer tt_live_...). O cabeçalho X-Api-Key também é aceito.
• Cada operação tem um operationId estável (ex.: sendMessage, listContacts, updateContact).
• Os eventos de webhook estão em webhooks (ex.: message.received), com o envelope EventEnvelope.