Parceiro humano e agente no mesmo endpoint precisam do mesmo contrato: schema, versão, erro máquina-legível, idempotência em escrita e escopo de token. Se o parceiro ganha um XML “especial” e o agente ganha um JSON frouxo, vocês operam dois produtos. O incidente chega junto.

API-first sem improviso é o princípio. Este texto é o recorte de dois consumidores. Fábrica de software precisa de interface estável para os dois não virarem fila de “integração urgente”.

Um recurso, dois clientes — o que igualar

  • códigos de erro e corpo previsível;
  • paginação e limite de taxa explícitos;
  • idempotency-key em POST que o agente vai retried;
  • OAuth (ou equivalente) com escopo mínimo — o agente não herda o usuário do operador sem desenho;
  • deprecation com data, não com “aviso no Slack”.

O que pode diferir: quota, SLA comercial, onboarding. O que não pode: o significado do campo status. Campo com dois significados é bug de contrato.

Agente trata timeout com retry. Parceiro legado às vezes não. O contrato deve documentar o comportamento, não assumir boa vontade. Quadro branco de recursos — como na capa — ainda é o melhor lugar para recusar o campo mágico.

Versionamento quando o agente chega no meio

Não crie /v1/human e /v1/ai. Crie o contrato que os dois usam e um perfil de cliente (token). Se o legado do parceiro não puder mudar, a v1 fica; a v2 nasce para os dois novos consumidores. Agente não é desculpa para quebrar o parceiro no silêncio.

API-first quando o especialista entra no meio do jogo é o onboarding: a pessoa lê o contrato, não o fio do WhatsApp com o parceiro.

Aceite de fábrica

Mock contra o schema. Consumidor parceiro e consumidor agente no pipeline de contrato (teste de breaking change). Sem isso, o PR “só mais um campo” quebra o agente na sexta e o parceiro na segunda.

Não prometemos que um gateway resolve política. Gateway ajuda a aplicar. O significado continua no schema versionado no Git.

Quando o agente chega no trimestre e o parceiro já está na v1, a tentação é um endpoint “só para IA”. Isso duplica o significado e o incidente. Perfil de token e quota resolvem permissão. Campo com dois nomes não. O quadro branco da capa serve para recusar o campo mágico na hora — antes do PR, antes do Slack, antes do “depois a gente versiona”.

Como a Tech Coders fecha contrato na fábrica

Na fábrica de software, endpoint compartilhado entra no sprint de 15 dias com schema, exemplo de erro e teste de contrato. Parceiro e agente são clientes. Resgate de integração começa pelo contrato que já mente — não por um adaptador a mais.

Perguntas frequentes

Agente não deveria ter API só dele?

Só se a ação for diferente. Se a ação é a mesma do parceiro, API paralela duplica significado. Perfil de token resolve permissão; não precisa de recurso clone.

Idempotência é obrigatória?

Em escrita com retry, sim. Agente sem idempotência duplica pedido. Parceiro com retry manual também. O contrato declara o comportamento.

OpenAPI chega para o jurídico do parceiro?

Chega para o integrador. Jurídico precisa de anexo comercial. Não misture SLA de contrato jurídico com schema — mas o schema é o anexo técnico.

Campo livre “metadata” salva os dois mundos?

Adia o conflito. Metadata vira segundo schema não versionado. Prefira campo explícito ou extensão versionada.