# Closer API

> Closer — Vendas Territoriais One Stone-first (back-end do app Closer)

## Aplicações internas

### [svc-leads](https://closer-app-docs.customer-platforms-prd.aws.karavela.run/docs/svc-leads)

Usamos o `svc-leads` para reconciliar documentos, enriquecer clientes e operar Leads e Journeys por Canal. O `svc-closer` continua dono da experiência e do estado transacional do app, enquanto o vocabulário de demanda comercial permanece no serviço especializado.

### [svc-identity](https://closer-app-docs.customer-platforms-prd.aws.karavela.run/docs/svc-identity)

Usamos o `svc-identity` para obter Stone Accounts, Legal Entities e o estado cadastral agregado sem acoplar o BFF a SALEM, LEA, RRA ou PandA. Essa fachada sustenta a composição de clientes e a reconciliação de identidade exibida ao Agente.

### [svc-salesforce](https://closer-app-docs.customer-platforms-prd.aws.karavela.run/docs/svc-salesforce)

Usamos o `svc-salesforce` para ler o contexto do Agente, contas e histórico de ofertas e para disparar ações administrativas sobre Leads. A fachada mantém SOQL, credenciais e particularidades do org Salesforce fora do serviço que possui o estado do Closer.

### [svc-worker](https://closer-app-docs.customer-platforms-stg.aws.karavela.run/docs/svc-worker)

Usamos o `svc-worker` para executar efeitos assíncronos como notificações, reconciliações e sincronizações territoriais. O `svc-closer` publica ou agenda o trabalho e preserva a resposta do usuário sem executar integrações demoradas no request principal.

### [MCC API](https://mundipagg.atlassian.net/wiki/x/84bueAE)

Usamos a MCC API para consultar a classificação comercial associada ao documento durante a composição de detalhes do cliente. O resultado complementa a visão de atendimento sem transferir para o Closer a manutenção do catálogo corporativo de MCCs.

Service: svc-closer
Canonical origin: https://closer-api.customer-platforms-stg.aws.karavela.run

## Machine discovery

- Native OmniServer documentation: https://closer-api.customer-platforms-stg.aws.karavela.run/docs
- Documentation/runtime state: https://closer-api.customer-platforms-stg.aws.karavela.run/docs/state.json
- OpenAPI 3.1: https://closer-api.customer-platforms-stg.aws.karavela.run/docs/openapi.json
- Universal Service Documentation: https://closer-api.customer-platforms-stg.aws.karavela.run/docs/usd.json
- Complete agent context: https://closer-api.customer-platforms-stg.aws.karavela.run/llms-full.txt
- Prometheus/OpenMetrics: https://closer-api.customer-platforms-stg.aws.karavela.run/metrics
- Health: https://closer-api.customer-platforms-stg.aws.karavela.run/health
- Authentication metadata: https://closer-api.customer-platforms-stg.aws.karavela.run/auth

## Guides

- Contrato SSE do `POST /chat`: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/CHAT_PROTOCOL
- Quick start: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/ — Choose the correct API surface, authenticate, and make the first Closer calls.
- Status de existência de documento (check-existence): https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/existence-status
- Reconciliação Identity / Salesforce no Closer: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/identity-reconciliation
- Deduplicação documental do Closer — aposentada: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/lead-document-deduplication
- Lead H3 performance proof: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/lead-h3-performance
- Fluxo de status do Lead — de `identified` até `opportunity`: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/lead-status-flow
- Runbook — Histórico de Ofertas (read-model) · ADR-0105: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/offer-history-runbook
- Leads and tasks: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/leads-and-tasks — Understand state changes, safe retries, and external synchronization.
- Solicitar Bobina: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/paper-roll-request — Formulário e abertura da OS de envio de bobinas (KIT 06) para o app-closer.
- Desinstalar Equipamento: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/uninstall-request — Formulário e abertura da OS de desinstalação de um terminal ativo para o app-closer.
- Histórico de Solicitações: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/service-order-history — Ordens de serviço de uma Stone Account nas abas Abertas, Concluídas e Canceladas para o app-closer.
- Trocar Equipamento: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/terminal-replacement-request — Formulário e abertura da OS de troca de um terminal com defeito por um modelo novo para o app-closer.
- Cancelar OS: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/service-order-cancellation — Validação e cancelamento de uma Ordem de Serviço existente pelo Agente no app-closer.
- Entregar Maquininha (POS na Mochila): https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/terminal-delivery — Validação e as etapas de entrega da maquininha e baixa da OS de instalação pelo próprio Agente no app-closer.
- Pedido de Máquina: https://closer-api.customer-platforms-stg.aws.karavela.run/docs#/machine-order-request — Formulário, simulação de mensalidade, envio e acompanhamento do pedido de terminal adicional pela oferta ativa do cliente, para o app-closer.

## Agent rules

- Read the live USD/OpenAPI contract before constructing a request; it is authoritative during rollouts.
- Follow each operation security declaration and never place credentials in URLs, logs or artifacts.
- Prefer the smallest bounded request that can prove or disprove the current hypothesis.
- Preserve response status, trace/request identifiers and evidence boundaries when reporting a result.