# API de retorno MyPainel → documentação para MULTISUP

Contrato 1.6. Base HTTPS de homologação: `https://homolog.mypainel.site`. Ambiente isolado, somente dados fictícios.
OpenAPI pública: `https://homolog.mypainel.site/openapi.json`. Publicação de homologação autorizada posteriormente pelo usuário; produção permanece sem esta integração.

OpenAPI: `multisup-return-openapi.json`.

## Autenticação e escopo

Bearer privado próprio da API, distinto da chave HMAC de envio. Configuração servidor: `MULTISUP_RETURN_API=homolog`, `MULTISUP_RETURN_CONNECTION` (identidade local da conexão) e `MULTISUP_RETURN_TOKEN`. Sem configuração válida retorna 503. Nenhum segredo em documentação ou URL.

Toda rota exige `projectCode=worbit|zzbroker|binova|general`. O ID do path é o ID externo opaco enviado no webhook. Somente tickets explicitamente vinculados à conexão são acessíveis; não há vinculação automática de dados existentes por email, telefone ou número do chamado.

## Respostas

`POST /api/integrations/v1/tickets/{id}/responses?projectCode=general`

Headers: `Authorization: Bearer <credencial privada>`, `Content-Type: application/json`, `Idempotency-Key: operacao-ficticia-001`.

```json
{"clientOperationId":"operacao-ficticia-001","expectedTicketRevision":3,"audience":"CALLCENTER","text":"Resposta fictícia ao atendente."}
```

Sem `resolution`, mantém aberto. Para resposta final acrescentar `"resolution":"RESOLVED"`. Não é concessão de saldo/depósito; nenhum registro financeiro é criado ou alterado. Texto, fechamento, recibo, auditoria e evento pendente são gravados em uma transação.

HTTP 200:
```json
{"clientOperationId":"operacao-ficticia-001","status":"APPLIED","ticketId":"ticket-ficticio","messageId":"id-da-mensagem","revision":4}
```

Mesma chave e corpo: recibo original, mesmo se a revisão já avançou ou o chamado já fechou. Mesma chave e corpo/ticket diferente: 409. Chave é única por conexão + projectCode. Revisão antiga ou chamado encerrado: 409. Corpo limitado a 32 KiB; texto até 4000 caracteres. A confirmação indica gravação durável, não que um atendente leu a resposta.

## Confirmação de entrega

`GET /api/integrations/v1/tickets/{id}/operations/{clientOperationId}?projectCode=general`

Retorna HTTP 200 com o mesmo recibo APPLIED. A implementação é síncrona e não publica PROCESSING: uma operação ainda não confirmada pode retornar 404 enquanto sua transação está em andamento. 404 significa desconhecida/não confirmada, nunca confirmação de não entrega. Após timeout, consultar e repetir apenas a mesma chave/corpo; o bloqueio transacional impede duplicação mesmo com requisições simultâneas.

Não há expurgo de recibos nesta versão, atendendo ao mínimo proposto de 30 dias. Preservar estes registros em rollback. Falha 500/timeout deve permanecer incerta até consulta/repetição; 401/400/409 exigem corrigir a causa.

## Preparação e limites

- SQL aditivo: `prisma/migrations-manual/2026-09-25-multisup-return-api.sql`; não executar em produção nesta fase.
- Teste descartável local: `node local-preview/test-multisup-return.cjs` a partir da pasta MyPainel. Não lê dados de produção.
- `node local-preview/setup-multisup.cjs` prepara tabelas e token privado da prévia local; não revela o token.
- Worker ativo: verifica eventos pendentes a cada 5 segundos, envia imediatamente quando encontra um item e confirma somente após resposta válida. Timeout/429/5xx usam backoff de até 5 minutos; erros de contrato/autenticação bloqueiam o evento e os posteriores do mesmo ticket até intervenção. Corpo e eventId preservados, timestamp/assinatura novos. Lease de 60 segundos recupera interrupções do processo. Ainda faltam criação/vinculação pelo formulário, APIs de recuperação/anexos e homologação conjunta completa.
- Piloto HTTPS validou resposta intermediária, repetição, consulta e envio do evento pelo worker ao receptor MULTISUP com HTTP 200. Não é liberação para produção. Respostas finais foram testadas em PostgreSQL descartável, mas ainda devem ser homologadas conjuntamente.

## Ticket disponível para o teste conjunto

- projectCode: `general`
- ticketId: `mypainel-ficticio-a3ce7a21-7e41-46b8-a6fa-6c82ad113e34-ticket`
- Revisão após teste intermediário: **4** (25/09/2026, 16:38 UTC).
- Está aberto. Usar expectedTicketRevision=4 na próxima resposta, com nova clientOperationId. Após resposta, usar a revisão devolvida no recibo.
- Confirmar na MULTISUP o recebimento do evento `c6ec568e-a82c-4ef0-8185-529ff689fa24` (HTTP 200 confirmado pelo worker).
- Bearer separado do HMAC; entregar pelo cofre/canal privado combinado, nunca neste documento.