> ## 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. # Como o Lerian SPI funciona > Como o Lerian SPI funciona: onboarding no Pix, fluxos de envio e recebimento (pacs.008 e pacs.002), devoluções, chaves e reivindicações do DICT, cobranças BR Code, Pix Automático e MED. O Lerian SPI expõe a superfície de mensagens do Pix como um conjunto de operações tipadas. O trilho envia as mensagens destas operações como seu participante direto, o ISPB em `BACEN_SPI_PARTICIPANT_ISPB`: * o teste de conectividade; * a solicitação de relatório da Conta PI e o registro dos responsáveis; * a solicitação, o cancelamento e a resolução de mandato do Pix Automático (`pain.009`, `pain.011`, `pain.012`); * a instrução, a resolução e o cancelamento de agendamento do Pix Automático (`pain.013`, `pain.014`, `camt.055`); * o relatório de liquidação do MED 2.0. Os corpos de requisição dessas operações não recebem `participantIspb`, e um corpo que o traz recebe `422`. ## Onboarding e prontidão *** Você registra um participante indireto pelo seu ISPB. Ele entra como `PENDING`, e o trilho envia a solicitação de registro. Apenas a confirmação do BACEN o torna `ACTIVE`. Uma recusa do BACEN o torna `REGISTRATION_REJECTED`. A ação de ativação apenas reativa um participante `SUSPENDED`. A ordem de preparação recomendada antes de enviar pagamentos é: 1. **Faça upload** de um certificado Pix, apenas o `.cer` público. O trilho rejeita uma chave privada enviada. 2. Confirme que o trilho reporta **pronto**. 3. Passe em um **teste de conectividade**. 4. Envie pagamentos. A mesma superfície Core também suspende e encerra um participante ao longo do seu ciclo de vida. O encerramento de um participante direto o torna `OFFBOARDED` na hora. O encerramento de um participante indireto o move para `OFFBOARD_PENDING`, e o trilho envia ao BACEN um `reda.031`. A resposta `reda.016` do BACEN torna o participante `OFFBOARDED`, ou `ACTIVE` de novo se o BACEN recusar. Enquanto o `reda.031` aguarda essa resposta, uma nova solicitação de encerramento recebe `409` com o código `SPI-3010`. Quando o trilho sabe que o `reda.031` não chegou ao BACEN, você pode enviar a solicitação de encerramento de novo. ## Enviar um Pix *** Você cria uma ordem de pagamento. A plataforma monta a mensagem de transferência de crédito ISO 20022 (`pacs.008`), persiste a operação e a despacha. O BACEN retorna uma resposta de status assíncrona (`pacs.002`). O trilho valida e aplica a resposta, então move o pagamento para `COMPLETED` ou `REJECTED`. Você consulta um pagamento pelo seu ID fim a fim, com seu histórico e uma linha do tempo por operação. Quando o trilho não consegue abrir uma conexão com o BACEN, o arquivo regulatório recusa a gravação ou o trilho não consegue montar a mensagem, e nenhuma tentativa anterior pode ter chegado ao BACEN, o pagamento termina como `FAILED`, e a requisição recebe `503` com o código `SPI-1001`. Um pagamento Pix que terminou em `FAILED` porque a conexão com o BACEN falhou ou a verificação de segurança do transporte falhou (`503` com `SPI-1001` ou `SPI-1004`) pode ser enviado de novo. Com a mesma chave `X-Idempotency`, envie de novo a primeira requisição exatamente como ela foi. Com uma chave nova, envie a mesma requisição com o `endToEndId` do pagamento que falhou. O trilho o envia como uma nova tentativa no mesmo pagamento e publica `spi_payment.initiated` de novo. Uma devolução nos mesmos casos termina como `NAO_REALIZADO`, com a mesma resposta, e nunca é enviada de novo dessa forma. Uma devolução que o BACEN recusa com `401` ou `403` também termina como `NAO_REALIZADO`, e o trilho libera o teto de devolução dela, a menos que uma tentativa anterior possa ter chegado ao BACEN. Uma operação que precisa de atenção aparece na [lista de operações travadas](https://docs.lerian.studio/pt/reference/rails/spi/spi/list-stuck-operations.md), com as ações que ela aceita. Você [envia](https://docs.lerian.studio/pt/reference/rails/spi/spi/submit-stuck-operation-action.md) uma ação com um motivo. A [resolução manual](https://docs.lerian.studio/pt/reference/rails/spi/spi/manual-resolve-operation.md) encerra uma operação travada. Ela exige uma aprovação `APPROVED` para essa operação. Um pedido de aprovação aceita apenas o tipo de assunto `MANUAL_RESOLUTION`, e seu `subjectId` é a operação a resolver. Para um Pix enviado ou uma devolução que o BACEN não respondeu, a resolução declara o resultado em `outcome`: `SETTLED` ou `REJECTED`. A aprovação nomeia o mesmo resultado em `requestedAction`: `MANUAL_RESOLVE_SETTLED` ou `MANUAL_RESOLVE_REJECTED`. Uma declaração `SETTLED` também traz o instante de liquidação do BACEN tirado da evidência, em `settledAt`. O trilho encerra o Pix como faz um `pacs.002` e publica `spi_payment.settled` ou `spi_payment.rejected`. Uma resposta posterior do BACEN não muda o Pix. Uma devolução `SETTLED` é encerrada como `DEVOLVIDO`, e o trilho publica `spi_payment.returned` ou `spi_payment.partial_returned`. Uma devolução `REJECTED` é encerrada como `NAO_REALIZADO`, e o trilho publica `spi_payment.return_rejected` ou `spi_payment.partial_return_failed`. Uma devolução total `REJECTED` também devolve o Pix ao estado `COMPLETED`. Uma resposta posterior do BACEN não muda a devolução. Quando o BACEN não responde a um Pix enviado ou a uma devolução dentro do prazo, a linha dele oferece `RECONCILE_WITH_BACEN`. Com essa ação, o trilho pede ao BACEN o lançamento do pagamento (`camt.060`). Quando a resposta `camt.054` do BACEN informa o pagamento como liquidado ou rejeitado, o trilho o conclui ou o rejeita, como faz um `pacs.002`. Qualquer outra resposta deixa o pagamento aberto. A linha parada de uma devolução oferece apenas essa ação. A resolução manual de uma devolução roda na operação `PAYMENT_RETURN` dela. ## Receber um Pix *** O consumidor ICOM recebe mensagens assinadas do BACEN e as repassa para a ingestão interna autenticada do trilho. Para um `pacs.008` de entrada, o trilho valida a mensagem e registra o Pix como `PENDING`. Seu cliente então decide esse Pix de uma de três formas. Ele envia evidência de fundos (saldo disponível, limite disponível, score de risco) para o trilho avaliar, declara que já autorizou o crédito ou envia um motivo de recusa. O trilho responde uma recusa `FRAD` como `FRAD` apenas quando seu cliente a marca como decisão do sistema antifraude dele. Sem a marca, o trilho responde `DS04`. O trilho responde ao SPI sobre um Pix aceito, e o Pix chega a `COMPLETED` apenas quando o SPI confirma o crédito, ou a `REJECTED` se o SPI o recusar. O trilho recusa um Pix que nenhuma decisão conclui dentro da sua janela regulatória, e uma decisão posterior recebe `409`. Um pagamento de saída não pode receber financiamento como dinheiro de entrada. Você lista os Pix que recebe e os Pix que ainda aguardam uma decisão. O evento `spi_payment.received` traz o fim da janela regulatória em `decisionDeadline`. Um Pix Agendado (`PAGAGD`) tem 45 minutos e um Pix com suspeita de fraude (`PAGFRD`) tem 40 segundos, ambos a partir do recebimento pelo SPI. Qualquer outro Pix tem 40 segundos a partir do momento em que a instituição do pagador aceitou a ordem. O trilho reserva os últimos 6 segundos de cada janela para o trabalho após a decisão. ## Devolução *** Você inicia uma devolução (`pacs.004`) apenas para um Pix liquidado que o trilho recebeu do BACEN, e depois consulta o status da devolução. A devolução debita o recebedor original e credita o pagador original. Você não pode iniciar uma devolução para um Pix que seu cliente enviou. A contraparte emite uma devolução desse Pix, e ela chega ao trilho como uma mensagem de entrada. Uma devolução é o caminho de movimentação de dinheiro do MED, a forma como os fundos retornam a um pagador em uma disputa concluída ou erro. Uma devolução de entrada não é liquidada na chegada. O trilho a retém e a anuncia em um evento [`studio.lerian.br-spi.spi_payment.return_received`](https://docs.lerian.studio/pt/reference/events/spi) que carrega o `returnId` dela. Seu cliente decide a devolução por esse `returnId`: ele autoriza a devolução ou a recusa com um motivo. Uma devolução autorizada é liquidada apenas quando o SPI a confirma. O trilho recusa uma devolução que nenhuma decisão conclui dentro da sua janela, e uma decisão posterior recebe `409`. Existem duas superfícies de devolução, a solicitação de devolução e a devolução de pagamento. O trilho registra qual delas criou uma devolução em vez de inferir isso depois. Uma solicitação de devolução é sempre **parcial**, qualquer que seja o valor, e usa o `devolucaoId` que você escolhe como chave. Uma devolução de pagamento de valor menor que o do Pix também é parcial e exige um `devolucaoId`. Uma devolução de pagamento do valor inteiro é **total**: ela reverte o Pix inteiro e move o pagamento pai para fora de `COMPLETED`. Uma devolução parcial mantém o pagamento pai liquidado, e várias devoluções parciais podem coexistir para um mesmo Pix. Quando as devoluções parciais liquidadas alcançam o valor do Pix, o pagamento pai passa para `RETURNED`. Três validações se aplicam a toda devolução, nas duas superfícies: * **O pai deve ser um Pix de entrada que liquidou.** Apenas um pagamento recebido que chegou a `COMPLETED` (ou que já carrega uma devolução) pode ser devolvido. * **A janela de devolução do BACEN.** Uma devolução deve ser solicitada em até 90 dias da liquidação do Pix original. O trilho mede a janela a partir do instante de liquidação, nunca da criação ou da última atualização. Um Pix sem instante de liquidação registrado não fica bloqueado: o trilho registra a lacuna e encaminha a solicitação. * **O teto de soma.** Os valores de todas as devoluções de um Pix não podem exceder o valor do próprio Pix. Uma devolução que termina em `NAO_REALIZADO` não conta. O trilho lê apenas o valor daquele pagamento e suas próprias devoluções. Não computa nenhuma posição entre pagamentos. Uma aceitação de transporte não é uma conclusão. Uma solicitação de devolução aceita a natureza `ORIGINAL` (o padrão quando você não envia nenhuma) ou `RETIRADA`, a etapa de Pix Saque e troco. Uma devolução de pagamento aceita um motivo: `MD06`, `SL02`, `BE08` ou `FR01`. As duas naturezas do MED (falha operacional e suspeita fundada de fraude) decorrem de `BE08` e `FR01`. Você nunca as solicita como natureza. ## Ciclo de vida da chave DICT *** Você registra, atualiza e exclui chaves Pix no diretório DICT. Você também lista, pesquisa e consulta chaves, e verifica em lote se um conjunto de chaves existe. Você lê uma chave do registro do próprio trilho, sem consulta ao BACEN. O trilho lê estatísticas de chave do DICT e estatísticas antifraude do BACEN, tanto por chave quanto por pessoa. Para a sincronização do diretório, o trilho expõe as operações VSync do BACEN. Ele verifica um conjunto de CIDs, resolve um CID e lista os eventos do conjunto de CIDs. Ele também solicita e transmite um arquivo do conjunto de CIDs. ## Reivindicações do DICT *** Uma reivindicação move uma chave Pix entre participantes por portabilidade ou posse. Você inicia uma reivindicação contra um participante e depois a avança pelo seu ciclo de vida. O ciclo de vida abrange reconhecer, confirmar ou rejeitar, e concluir ou cancelar, nos lados do doador e do reivindicante. O job de prazo de reivindicação roda por padrão e avança as reivindicações dentro das janelas do BACEN. Uma reivindicação ainda pode exigir atenção. Você pode abandonar uma reivindicação aberta que o BACEN nunca registrou. A reivindicação termina em `CANCELLED`, e o trilho não envia nada ao BACEN. ## BR Code e cobranças *** Um QR dinâmico resolve para uma cobrança persistida, então você cria a cobrança primeiro e depois gera o payload que resolve a ela. Um QR estático é gerado a partir de dados de pagamento estáticos. Ele não exige nem aponta para uma cobrança. * Crie uma cobrança: **Cob** (imediata), **CobV** (com vencimento, com juros e multa), ou um **lote** de cobranças com vencimento. * Gere o payload do **QR EMV dinâmico**, que vincula à cobrança pelo seu txid ou localizador e resolve como um JWS assinado. Você também gera um QR estático, decodifica um payload, valida-o e registra um perfil de recebedor. No lado do pagador, você resolve um QR dinâmico lido para a cobrança dele. O trilho retorna a cobrança apenas depois que o certificado do site do recebedor e a assinatura do payload passam nas verificações dele. ## Pix Automático (recorrente) *** O Pix Automático autoriza pagamentos recorrentes e agendados por meio da família ISO 20022 de recorrência: * **Crie** uma autorização recorrente (recorrência) ou uma solicitação para uma. * **Solicite a confirmação** do mandato (`pain.009`), **cancele-o** (`pain.011`), ou **aceite / rejeite-o** (`pain.012`). * **Agende** uma instrução (`pain.013`) e **aceite / rejeite-a** (`pain.014`). * **Solicite o cancelamento** de uma instrução agendada (`camt.055`) e **resolva** um cancelamento recebido (`camt.029`). * **Solicite uma nova tentativa de liquidação** (retentativa) quando uma cobrança agendada falha. As requisições `pain.014`, `camt.029` e `camt.055` recebem apenas a decisão. O trilho lê os participantes, os identificadores, o `EndToEndId`, o agente credor e o CPF/CNPJ do credor do `pain.013` ou do `camt.055` que registrou. Qualquer outro campo recebe `422`. * O `pain.014` recebe `originalScheduleId`, `accepted`, `rejectReason` e um `endToEndId` opcional. * O `camt.029` recebe `cancellationCorrelationId`, `accepted` e `rejectReason`. * O `camt.055` recebe `cancellationId`, `scheduleId`, `originatorTaxId`, `reasonCode` e um `endToEndId` opcional. O trilho aceita os motivos `CCLD` e `FAIL` apenas quando sua instituição é o participante do pagador no agendamento. Apenas o participante do pagador responde a um `pain.013`, e apenas o participante que recebeu um `pain.009` ou `pain.011` o responde com um `pain.012`. Um `pain.014` para um agendamento que esta instalação enviou, e um `pain.012` para uma solicitação que esta instalação enviou, recebem `422` com o código `SPI-0003`. Uma nova tentativa de `pain.013` recebida (finalidade `NTAG` ou `RIFL`) abre o próprio agendamento ao lado do da cobrança e publica o próprio `spi_schedule.requested`. O `endToEndId` opcional no `pain.014` e no `camt.055` seleciona essa tentativa, e um valor desconhecido recebe `404`. Quando o participante do recebedor recusa um `CFDB` que o trilho enviou, o mandato passa para `AUTHORIZATION_REFUSED`, e o trilho publica `spi_mandate.resolved`. O trilho não processa de novo um `camt.055` reenviado. Quando o `camt.029` dele já chegou ao BACEN, o trilho envia esse `camt.029` de novo. Quando o trilho envia um `camt.055` e nenhum `camt.029` o responde, o trilho o envia de novo 1, 3 e 6 horas após o primeiro envio: no máximo três vezes, e nunca a partir de 11 horas. Se nenhum `camt.029` responder em até 12 horas do primeiro envio, o cancelamento tem efeito: o trilho cancela o agendamento e publica `spi_schedule.resolved`. Se o BACEN pode não ter recebido o `camt.055`, ou se a cobrança já pode ter sido liquidada, o trilho move a operação para `REQUIRES_OPERATOR_ACTION` em vez disso. Quando o trilho envia um `pain.011` e nenhum `pain.012` o responde em até 12 horas, o mandato passa a `CANCELLED`, e o trilho publica `spi_mandate.resolved`. Um `pain.011` com o motivo `PCFD` devolve o mandato a `ACTIVE`, e o trilho não publica evento. Um `pain.011` sem aceite do BACEN registrado vai para o operador. Um `pain.012` posterior não move o mandato. O trilho pode rejeitar uma solicitação de cancelamento recebida (`camt.055`) com um `camt.029`. Se o BACEN recusar esse `camt.029` e não aceitar nenhum reenvio em até 12 horas após a chegada do `camt.055`, o trilho cancela o agendamento. Se a cobrança já puder ter sido liquidada, o trilho mantém o agendamento e move sua operação para `REQUIRES_OPERATOR_ACTION`. [Liste as respostas que o BACEN recusou](https://docs.lerian.studio/pt/reference/rails/spi/spi/list-the-replies-bacen-refused.md) lista as respostas `pain.014` e `camt.029` que um `admi.002` ou uma liberação do operador deixou em `FAILED`, com o prazo mais próximo primeiro. Cada linha mostra o tempo que resta para o reenvio. A rota que enviou a resposta reenvia o mesmo veredito antes do prazo: 2 horas após a chegada do `pain.013`, ou 12 horas após a chegada do `camt.055`. Envie o reenvio com uma nova chave `X-Idempotency`: com a primeira chave, o rail repete a primeira resposta e não envia nada ao BACEN. ## Disputas MED *** Você trata os casos de fraude e erro do MED (Mecanismo Especial de Devolução) no DICT e reporta as liquidações internas no SPI: * Registre **solicitações de reembolso** do DICT, **marcadores de fraude** e solicitações de **recuperação de fundos**. Uma recuperação de fundos é rastreada por seu grafo de ciclo de vida. * Leia, reconheça, cancele, encerre e atualize **relatos de infração** do DICT. * Reporte Pix liquidados internamente por meio do relatório de liquidação do MED 2.0. ## Relatórios da Conta PI *** Você solicita um relatório de conta (`camt.060`) para o saldo (`camt.053`), o extrato (`camt.052`) ou o detalhe de lançamento (`camt.054`). O relatório sempre cobre a Conta PI do seu participante direto. Você lê o saldo e o extrato de volta pela API. Relatórios síncronos completam a superfície de relatórios: uma volumetria apenas de contagem, uma contagem de pagamentos rejeitados com uma lista paginada, e listagens de saldo e de extrato. Cada janela de relatório cobre no máximo 92 dias. Você também registra os responsáveis da Conta PI do seu participante direto (`reda.022`) e lê de volta o último registro conhecido deles. ## Arquivo regulatório *** O Lerian SPI arquiva cada envelope ICOM que envia ao BACEN ou recebe dele, e cada requisição e resposta do DICT, com seus headers. Ele também arquiva os certificados que os assinam ou verificam. Cada item traz seu prazo de retenção do Manual de Segurança do SFN, capítulo 7. Se o trilho não consegue arquivar uma mensagem de saída, ele não a envia. [`GET /api/v1/spi/regulatory-archive/{itemId}`](https://docs.lerian.studio/pt/reference/rails/spi/spi/read-one-regulatory-archive-item) retorna um item arquivado byte a byte, para que você possa verificar a assinatura dele de novo. A rota aceita apenas um usuário, não uma aplicação, com o recurso `br-spi-regulatory-archive` do Access Manager e a ação `read`. O trilho registra quem leu qual item e quando antes de retornar o conteúdo. Uma leitura que o trilho não consegue registrar não retorna nada. Você configura o armazenamento do arquivo com as [variáveis de ambiente](https://docs.lerian.studio/pt/rails/spi/spi-environment-variables.md) `REGULATORY_ARCHIVE_*`. Apenas um ambiente de desenvolvimento pode iniciar sem ele. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.