> ## 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 o Lerian CCS 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. | | Requisição | `POST /v1/pending-requisition-queries` | Pergunta ao BACEN quais requisições estão sem resposta. | | Requisição | `GET /v1/pending-requisition-queries/gaps` | Lista as requisições sem resposta. | | 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. | | Transferência | `GET /v1/transfers-in` | Lista as transferências recebidas. | | Transferência | `GET /v1/transfers-in/{id}` | Lê uma transferência recebida. | | Transferência | `POST /v1/transfers-in/{id}/confirm` | Confirma uma transferência recebida. | | Auditoria | `GET /v1/audit/entries` | Lista as entradas de auditoria. | | Auditoria | `POST /v1/audit/verify-chain` | Verifica a cadeia de auditoria. | | Streaming | `GET /v1/streaming/manifest` | Lê o manifesto de eventos. Com o streaming desligado, a rota não é montada. | Endpoints de operador ficam fora de `/v1`. | Endpoint | Finalidade | | - | - | | `GET /health` | Liveness. | | `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. | | `/swagger/*` | A especificação da API, quando `SWAGGER_ENABLED=true` fora de produção. | ## Autenticação e tenancy *** Toda rota `/v1` recebe um bearer token OAuth2 do [Lerian Access Manager](https://docs.lerian.studio/pt/platform/access-manager.md). Com `PLUGIN_AUTH_ENABLED=true` e `PLUGIN_AUTH_HOST`, o Lerian Access Manager autoriza cada requisição. Só um `ENV_NAME` de desenvolvimento fora de `saas` aceita `false`. Cada instituição mantém seu próprio schema de banco de dados. ## Idempotência *** O Lerian CCS aceita um header `X-Idempotency` opcional na maioria das rotas que alteram estado. Um middleware armazena em cache a primeira resposta e a repete para uma repetição da mesma chave. Uma repetição com outro corpo responde 422, e uma repetição enquanto a primeira requisição executa responde 409. As chaves pertencem a uma instituição, e a retenção padrão é de 7 dias. ## Erros *** Um erro de negócio responde com um documento de problema RFC 9457, com o tipo de mídia `application/problem+json` e 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-0074` | 409 | Uma conciliação já está em andamento. | | `MYS-0008` | 503 | Um upstream ou o template está indisponível. | ## 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](https://docs.lerian.studio/pt/platform/streaming-hub/how-streaming-hub-works.md), 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](https://docs.lerian.studio/pt/platform/streaming-hub/what-is-streaming-hub.md) é a camada de entrega. Com `RABBITMQ_ENABLED=true`, o Lerian CCS também publica notificações no exchange definido por `RABBITMQ_EXCHANGE`. | Chave de roteamento | Significado | | - | - | | `ccs.events.batch` | Um lote terminou a criação e aguarda revisão. | | `ccs.events.batch.generation_failed` | A geração do lote falhou. | | `ccs.events.reconciliation.divergence` | Uma execução encontrou uma divergência. | Os documentos nesses payloads são mascarados. ## Convenções de integração *** * **Headers.** Enquanto `CORS_ALLOWED_HEADERS` permanecer sem definição, vale uma lista padrão fixa, e ela não inclui `X-Idempotency`. Um valor que você define substitui essa lista, 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 tamanho de página de 100 ou menos fica dentro do limite de cada rota. * **Rate limits.** O limitador cobre apenas `/v1`. Requisições que alteram estado e leituras pesadas, como consultas de auditoria, têm níveis mais restritos. * **Referências de arquivo.** O XML regulatório permanece no armazenamento de objetos. A API e as mensagens do broker carregam apenas referências de arquivo. [Como o Lerian CCS funciona](https://docs.lerian.studio/pt/rails/ccs/how-ccs-works.md) cobre esses fluxos. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.