> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Integrando com o Lerian CCS > A superfície da API do Lerian CCS, seu modelo de autenticação e tenancy, idempotência, contrato de erros e os eventos que ela publica. O Lerian CCS expõe uma API REST sob `/v1`. Toda rota de negócio exige um bearer token. ## Superfície da API *** | Área | Operação | Finalidade | | --------------------------- | --------------------------------------------------------------- | ----------------------------------------- | | Configuração | `GET /v1/configurations` | Lê a configuração atual. | | Configuração | `POST /v1/configurations` | Cria uma configuração. | | Configuração | `GET /v1/configurations/{id}` | Lê uma configuração. | | Configuração | `PATCH /v1/configurations/{id}` | Atualiza uma configuração. | | Configuração | `POST /v1/configs/{configId}/conglomerate-members` | Adiciona um membro. | | Configuração | `GET /v1/configs/{configId}/conglomerate-members` | Lista os membros. | | Configuração | `DELETE /v1/configs/{configId}/conglomerate-members/{memberId}` | Remove um membro. | | Lote | `POST /v1/batches` | Gera o lote de uma data de movimento. | | Lote | `GET /v1/batches` | Lista os lotes. | | Lote | `GET /v1/batches/{id}` | Lê um lote. | | Lote | `POST /v1/batches/{id}/approve` | Aprova e inicia a renderização. | | Lote | `POST /v1/batches/{id}/submit` | Alias de approve. | | Lote | `POST /v1/batches/{id}/reject` | Rejeita um lote em revisão. | | Lote | `GET /v1/batches/{id}/items` | Lista os itens de linha. | | Lote | `GET /v1/batches/{id}/items/{itemId}/errors` | Lista os erros do item. | | Lote | `POST /v1/batches/resend` | Reenvia a partir de um lote terminal. | | Lote | `POST /v1/batches/{id}/reprocess-last-event` | Admin. Dispara novamente o último evento. | | Lote | `POST /v1/batches/{id}/drain-parked-response` | Admin. Aplica um ACCS003 estacionado. | | Lote | `POST /v1/batches/reconcile-partial-applies` | Admin. Corrige um veredito contraditório. | | Lote | `POST /v1/batches/recompute-mirror` | Admin. Recalcula o espelho. | | Lote | `POST /v1/batches/backfill-sta-transfer-id` | Admin. Restaura uma identidade perdida. | | Solicitação de detalhamento | `GET /v1/detail-requests` | Lista as solicitações de detalhamento. | | Solicitação de detalhamento | `GET /v1/detail-requests/{id}` | Lê uma solicitação de detalhamento. | | Solicitação de detalhamento | `POST /v1/detail-requests/{id}/cancel` | Cancela uma solicitação de detalhamento. | | Medida judicial | `POST /v1/injunctions` | Registra um bloqueio ou desbloqueio. | | Medida judicial | `GET /v1/injunctions` | Lista as medidas judiciais. | | Medida judicial | `GET /v1/injunctions/{id}` | Lê uma medida judicial. | | Medida judicial | `POST /v1/injunctions/{id}/revoke` | Revoga uma medida judicial. | | Conciliação | `POST /v1/reconciliations` | Começa uma execução contra um ACCS004. | | Conciliação | `GET /v1/reconciliations` | Lista as execuções. | | Conciliação | `GET /v1/reconciliations/{id}` | Lê uma execução. | | Conciliação | `GET /v1/reconciliations/{id}/divergences` | Lista as divergências. | | Transferência | `POST /v1/transfers` | Cria uma transferência. | | Transferência | `GET /v1/transfers` | Lista as transferências. | | Transferência | `GET /v1/transfers/{id}` | Lê uma transferência com suas pernas. | | Auditoria | `GET /v1/audit/entries` | Lista as entradas de auditoria. | | Auditoria | `POST /v1/audit/verify-chain` | Verifica a cadeia de auditoria. | Endpoints de operador ficam fora de `/v1`. | Endpoint | Finalidade | | ------------------------- | ------------------------------------------------------ | | `GET /health` | Liveness. Responde 503 enquanto a self-probe falha. | | `GET /readyz` | Readiness de todas as dependências. | | `GET /readyz/tenant/{id}` | Readiness de uma instituição. | | `GET /version` | Versão de build. | | `GET /metrics` | Métricas de readiness, em texto Prometheus. | | `GET /streaming` | O manifesto de eventos. | | `/system/{namespace}` | Configuração em tempo de execução. | | `/swagger/*` | A especificação da API, quando `SWAGGER_ENABLED=true`. | ## Autenticação e tenancy *** Toda rota `/v1` recebe um bearer token OAuth2 do [Lerian Access Manager](/pt/platform/access-manager). Defina `PLUGIN_AUTH_ENABLED=true` e `PLUGIN_AUTH_HOST` para ativar o gate. A produção exige ambos. Cada instituição mantém seu próprio schema de banco de dados. O serviço lê a identidade da instituição a partir do token validado, nunca de um corpo de requisição, de um header ou de um parâmetro de rota. ## Idempotência *** O Lerian CCS aceita um header `Idempotency-Key`. O header é obrigatório em `POST /v1/batches` e opcional na rota de cancelamento. Um middleware armazena em cache a primeira resposta e a repete para uma repetição da mesma chave. As chaves pertencem a uma instituição, e a retenção padrão é de 7 dias. ## Erros *** Todo corpo de erro é um documento de problema RFC 9457, com o tipo de mídia `application/problem+json`. Cada corpo carrega um código de produto. Os valores de código são um contrato congelado, então um cliente compara pelo código, não pelo texto da mensagem. | Código | Status | Quando | | ---------- | ------ | -------------------------------------------------- | | `CCS-0001` | 409 | Já existe uma configuração. | | `CCS-0004` | 404 | A configuração não existe. | | `CCS-0010` | 409 | Um lote não terminal ocupa essa data de movimento. | | `CCS-0012` | 400 | A data de movimento está fora da janela. | | `CCS-0020` | 404 | O lote não existe. | | `CCS-0024` | 422 | O lote recusa essa transição. | | `CCS-0050` | 400 | A transferência nomeia a própria instituição. | | `CCS-0061` | 409 | Uma medida judicial já cobre esse documento. | | `CCS-0064` | 404 | A solicitação de detalhamento não existe. | | `CCS-0066` | 409 | A janela de cancelamento se fechou. | | `CCS-0074` | 409 | Uma conciliação já está em andamento. | | `MYS-0008` | 503 | Um upstream ou o template está indisponível. | Uma rota cujos colaboradores falharam ao ser conectados responde 501. ## Eventos *** O Lerian CCS publica um evento de negócio em seu próprio tópico, com um tópico dead-letter correspondente. O tópico e o tipo de evento seguem a [regra de nomenclatura do Streaming Hub](/pt/platform/streaming-hub/how-streaming-hub-works), com a fonte CloudEvents deste serviço como namespace. | Evento | Significado | | ------------ | ------------------------------------- | | Lote enviado | O lote ACCS001 foi para o Lerian STA. | Ele carrega a postura de entrega crítica. O serviço o grava no outbox transacional, na mesma transação da mudança de estado. O streaming vem desativado por padrão. Enquanto estiver desativado, o serviço conecta um emissor no-operation e não publica nada. O [Lerian Streaming Hub](/pt/platform/streaming-hub/what-is-streaming-hub) é a camada de entrega. O Lerian CCS também publica notificações no exchange definido por `RABBITMQ_EXCHANGE`. | Chave de roteamento | Significado | | -------------------------------------- | ------------------------------------------------------ | | `ccs.events.batch` | Um lote mudou de estado. | | `ccs.events.batch.generation_failed` | A geração do lote falhou. | | `ccs.events.detail_request.received` | Uma solicitação de detalhamento chegou. | | `ccs.events.detail_request.cancelled` | Uma solicitação de detalhamento passou para cancelada. | | `ccs.events.reconciliation.divergence` | Uma execução encontrou uma divergência. | | `ccs.outbox.dlq` | Uma mensagem do outbox esgotou suas tentativas. | Os documentos nesses payloads são mascarados. ## Convenções de integração *** * **Headers.** `CORS_ALLOWED_HEADERS` não tem valor padrão. Enquanto permanecer sem definição, uma resposta de preflight ecoa os headers que o navegador pediu. Um valor que você define substitui esse comportamento por uma lista fixa, então informe cada header que seu cliente de navegador envia. * **Paginação.** Cada rota de listagem limita seu próprio tamanho de página. Um `limit` de 100 ou menos fica dentro do limite de cada rota. * **Rate limits.** O limitador cobre apenas `/v1`. Rotas de exportação e de dispatch têm níveis mais restritos. * **Referências de arquivo.** O XML regulatório permanece no armazenamento de objetos. Apenas referências de arquivo trafegam pela rede. [Como o Lerian CCS funciona](/pt/rails/ccs/how-ccs-works) cobre esses fluxos.