components: schemas: AdditionalInfo: additionalProperties: false properties: nome: type: string valor: type: string required: - nome - valor type: object Amounts: additionalProperties: false properties: abatimento: type: string desconto: type: string final: type: string juros: type: string modalidadeAlteracao: format: int64 type: integer multa: type: string original: type: string retirada: $ref: "#/components/schemas/Withdrawal" type: object Calendar: additionalProperties: false properties: apresentacao: type: string criacao: type: string dataDeVencimento: type: string expiracao: format: int64 type: integer validadeAposVencimento: format: int64 type: integer required: - criacao - apresentacao type: object ChargeResponse: additionalProperties: false properties: amount: description: Original charge amount in BRL as a decimal string, scale 2. examples: - "250.00" type: string chargeType: description: "Charge type: COB (immediate), COBV (due-date), or LoteCobV batch item." examples: - COB type: string createdAt: description: Creation timestamp in RFC3339 UTC. examples: - "2025-03-07T14:30:00Z" type: string dueAt: description: Due date for due-date charges (COBV) as an RFC3339 UTC timestamp; null for immediate charges. examples: - "2025-03-15T23:59:59Z" type: string expiresAt: description: Immediate-charge (COB) expiry as an RFC3339 UTC timestamp; null when not applicable. examples: - "2025-03-08T23:59:59Z" type: string id: description: Server-assigned charge identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string merchantCity: description: Merchant city on the charge. examples: - São Paulo type: string merchantName: description: Merchant legal/trade name on the charge. examples: - Lerian Studio type: string paidAt: description: Settlement timestamp as an RFC3339 UTC timestamp; null until the charge is reconciled as paid. examples: - "2025-03-08T10:15:00Z" type: string payloadLocation: description: Payload location carried by the dynamic charge QR, without protocol prefix; resolvable over HTTPS only. Empty when unavailable. examples: - pix.example.com/qr/v2/txid-cobv-001 type: string pixKey: description: Pix key of the receiver settling the charge. examples: - "12345678901" type: string rawPayload: description: Raw EMV copy-and-paste payload string for the charge (empty when unavailable). examples: - 00020126580014br.gov.bcb.pix... type: string status: description: Charge lifecycle status (ATIVA, CONCLUIDA, REMOVIDA_PELO_USUARIO_RECEBEDOR, REMOVIDA_PELO_PSP). examples: - ATIVA type: string txId: description: Merchant transaction identifier for the charge. examples: - txid-cobv-001 type: string updatedAt: description: Last-update timestamp in RFC3339 UTC. examples: - "2025-03-07T14:30:00Z" type: string required: - id - txId - chargeType - amount - status - merchantName - merchantCity - pixKey - createdAt - updatedAt type: object CobCalendarioGerado: additionalProperties: false properties: criacao: description: Data de criação da cobrança (RFC 3339). type: string expiracao: description: Tempo de vida da cobrança em segundos a partir de criacao. format: int64 type: integer required: - criacao - expiracao type: object CobCalendarioSolicitado: additionalProperties: false properties: expiracao: description: Tempo de vida da cobrança em segundos a partir de criacao (padrão 86400). Deve ser maior que zero quando informado. examples: - 3600 format: int64 minimum: 1 type: integer type: object CobCompleta: additionalProperties: false properties: calendario: $ref: "#/components/schemas/CobCalendarioGerado" chave: description: Chave DICT do recebedor. maxLength: 77 type: string devedor: $ref: "#/components/schemas/Pessoa" infoAdicionais: items: $ref: "#/components/schemas/InfoAdicional" type: array loc: $ref: "#/components/schemas/CobLocGerada" location: description: Localização do payload. maxLength: 77 type: string pix: description: Pix recebidos vinculados à cobrança. items: $ref: "#/components/schemas/PixRecebido" type: array pixCopiaECola: description: Pix Copia e Cola (BR Code) correspondente à cobrança. maxLength: 512 type: string revisao: description: Revisão da cobrança (inicia em 0). format: int64 type: integer solicitacaoPagador: maxLength: 140 type: string status: description: Status do registro da cobrança. enum: - ATIVA - CONCLUIDA - REMOVIDA_PELO_USUARIO_RECEBEDOR - REMOVIDA_PELO_PSP type: string txid: description: Identificador da transação. pattern: "[a-zA-Z0-9]{26,35}" type: string valor: $ref: "#/components/schemas/CobValor" required: - calendario - txid - revisao - status - valor - chave type: object CobGerada: additionalProperties: false properties: calendario: $ref: "#/components/schemas/CobCalendarioGerado" chave: description: Chave DICT do recebedor. maxLength: 77 type: string devedor: $ref: "#/components/schemas/Pessoa" infoAdicionais: items: $ref: "#/components/schemas/InfoAdicional" type: array loc: $ref: "#/components/schemas/CobLocGerada" location: description: Localização do payload. maxLength: 77 type: string pixCopiaECola: description: Pix Copia e Cola (BR Code) correspondente à cobrança. maxLength: 512 type: string revisao: description: Revisão da cobrança (inicia em 0). format: int64 type: integer solicitacaoPagador: maxLength: 140 type: string status: description: Status do registro da cobrança. enum: - ATIVA - CONCLUIDA - REMOVIDA_PELO_USUARIO_RECEBEDOR - REMOVIDA_PELO_PSP type: string txid: description: Identificador da transação. pattern: "[a-zA-Z0-9]{26,35}" type: string valor: $ref: "#/components/schemas/CobValor" required: - calendario - txid - revisao - status - valor - chave type: object CobLocGerada: additionalProperties: false properties: criacao: description: Data de criação da location (RFC 3339). type: string id: description: Id da location. format: int64 type: integer location: description: Localização do payload. maxLength: 77 type: string tipoCob: description: cob | cobv. enum: - cob - cobv type: string required: - id - tipoCob - criacao type: object CobLocSolicitada: additionalProperties: false properties: id: description: Id da location previamente criada. format: int64 minimum: 1 type: integer tipoCob: description: cob | cobv. enum: - cob - cobv type: string type: object CobRAtualizacaoDTO: additionalProperties: false properties: data: description: Instante da atualização (RFC 3339). type: string status: enum: - CRIADA - ATIVA - CONCLUIDA - EXPIRADA - REJEITADA - CANCELADA type: string required: - status - data type: object CobRCalendarioCreate: additionalProperties: false properties: dataDeVencimento: description: Data de vencimento da cobrança (YYYY-MM-DD). examples: - "2025-08-15" type: string required: - dataDeVencimento type: object CobRCalendarioDTO: additionalProperties: false properties: criacao: description: Data de criação da cobrança (YYYY-MM-DD). type: string dataDeVencimento: description: Data de vencimento (YYYY-MM-DD). type: string required: - dataDeVencimento type: object CobRCancelamentoBody: additionalProperties: false properties: codigo: description: Código do cancelamento. maxLength: 4 type: string descricao: description: Descrição do cancelamento. maxLength: 400 type: string solicitante: description: Quem solicitou o cancelamento. enum: - PSP_PAGADOR - USUARIO_PAGADOR - PSP_RECEBEDOR - USUARIO_RECEBEDOR type: string required: - solicitante - codigo - descricao type: object CobRCancelamentoDTO: additionalProperties: false properties: codigo: type: string descricao: type: string solicitante: type: string required: - solicitante - codigo - descricao type: object CobRCompleta: additionalProperties: false properties: ajusteDiaUtil: type: boolean atestacaoTitularidade: $ref: "#/components/schemas/RecAtestacaoTitularidadeRegistradaDTO" atualizacao: description: Histórico das mudanças de status da cobrança recorrente. items: $ref: "#/components/schemas/CobRAtualizacaoDTO" type: array calendario: $ref: "#/components/schemas/CobRCalendarioDTO" devedor: $ref: "#/components/schemas/CobRDevedorDTO" encerramento: $ref: "#/components/schemas/CobREncerramentoDTO" idRec: pattern: ^[a-zA-Z0-9]{29}$ type: string infoAdicional: maxLength: 140 type: string politicaRetentativa: description: Política de retentativa vigente para esta cobrança (congelada da Rec na criação). enum: - NAO_PERMITE - PERMITE_3R_7D type: string recebedor: $ref: "#/components/schemas/CobRRecebedorDTO" revisao: format: int64 type: integer status: enum: - CRIADA - ATIVA - CONCLUIDA - EXPIRADA - REJEITADA - CANCELADA type: string tentativas: description: Histórico de tentativas de liquidação. items: $ref: "#/components/schemas/CobRTentativaDTO" type: array txid: pattern: ^[a-zA-Z0-9]{26,35}$ type: string valor: $ref: "#/components/schemas/CobRValorDTO" required: - atualizacao - politicaRetentativa - idRec - txid - calendario - ajusteDiaUtil - valor - recebedor - status - revisao type: object CobRDevedorDTO: additionalProperties: false properties: cep: description: CEP do devedor. maxLength: 8 type: string cidade: description: Cidade do devedor. maxLength: 200 type: string email: description: Email do devedor. type: string logradouro: description: Logradouro do devedor. maxLength: 200 type: string uf: description: UF do devedor. maxLength: 2 type: string type: object CobREncerramentoDTO: additionalProperties: false properties: cancelamento: $ref: "#/components/schemas/CobRCancelamentoDTO" rejeicao: $ref: "#/components/schemas/CobRRejeicaoDTO" type: object CobRGerada: additionalProperties: false properties: ajusteDiaUtil: type: boolean atestacaoTitularidade: $ref: "#/components/schemas/RecAtestacaoTitularidadeRegistradaDTO" atualizacao: items: $ref: "#/components/schemas/CobRAtualizacaoDTO" type: array calendario: $ref: "#/components/schemas/CobRCalendarioDTO" devedor: $ref: "#/components/schemas/CobRDevedorDTO" encerramento: $ref: "#/components/schemas/CobREncerramentoDTO" idRec: pattern: ^[a-zA-Z0-9]{29}$ type: string infoAdicional: maxLength: 140 type: string recebedor: $ref: "#/components/schemas/CobRRecebedorDTO" revisao: format: int64 type: integer status: enum: - CRIADA - ATIVA - CONCLUIDA - EXPIRADA - REJEITADA - CANCELADA type: string txid: pattern: ^[a-zA-Z0-9]{26,35}$ type: string valor: $ref: "#/components/schemas/CobRValorDTO" required: - idRec - txid - calendario - ajusteDiaUtil - valor - recebedor - status - revisao type: object CobRRecebedorBancarioDTO: additionalProperties: false properties: agencia: description: Agência do recebedor. examples: - "0001" maxLength: 4 type: string conta: description: Conta do recebedor. examples: - "1234567890" maxLength: 20 type: string tipoConta: description: Tipo de conta do recebedor. enum: - CORRENTE - POUPANCA - PAGAMENTO examples: - CORRENTE type: string required: - conta - tipoConta type: object CobRRecebedorDTO: additionalProperties: false properties: agencia: description: Agência do recebedor. maxLength: 4 type: string conta: description: Conta do recebedor. maxLength: 20 type: string tipoConta: enum: - CORRENTE - POUPANCA - PAGAMENTO type: string required: - conta - tipoConta type: object CobRRejeicaoDTO: additionalProperties: false properties: codigo: type: string descricao: type: string required: - codigo - descricao type: object CobRRetentativaCompleta: additionalProperties: false properties: ajusteDiaUtil: type: boolean atestacaoTitularidade: $ref: "#/components/schemas/RecAtestacaoTitularidadeRegistradaDTO" atualizacao: description: Histórico das mudanças de status da cobrança recorrente. items: $ref: "#/components/schemas/CobRAtualizacaoDTO" type: array calendario: $ref: "#/components/schemas/CobRCalendarioDTO" devedor: $ref: "#/components/schemas/CobRDevedorDTO" encerramento: $ref: "#/components/schemas/CobREncerramentoDTO" idRec: pattern: ^[a-zA-Z0-9]{29}$ type: string infoAdicional: maxLength: 140 type: string politicaRetentativa: description: Política de retentativa vigente para esta cobrança (congelada da Rec na criação). enum: - NAO_PERMITE - PERMITE_3R_7D type: string recebedor: $ref: "#/components/schemas/CobRRecebedorDTO" revisao: format: int64 type: integer status: enum: - CRIADA - ATIVA - CONCLUIDA - EXPIRADA - REJEITADA - CANCELADA type: string tentativas: description: Histórico de tentativas de liquidação. items: $ref: "#/components/schemas/CobRTentativaDTO" type: array txid: pattern: ^[a-zA-Z0-9]{26,35}$ type: string valor: $ref: "#/components/schemas/CobRValorDTO" required: - atualizacao - politicaRetentativa - tentativas - idRec - txid - calendario - ajusteDiaUtil - valor - recebedor - status - revisao type: object CobRRevisada: additionalProperties: false properties: cancelamento: $ref: "#/components/schemas/CobRCancelamentoBody" description: Detalhe do cancelamento (opcional). status: description: "Único valor aceito: CANCELADA." enum: - CANCELADA examples: - CANCELADA type: string required: - status type: object CobRSolicitada: additionalProperties: false properties: ajusteDiaUtil: description: Ajusta a liquidação para o próximo dia útil quando o vencimento cai em dia não-útil. type: boolean atestacaoTitularidade: $ref: "#/components/schemas/RecAtestacaoTitularidadeDTO" description: Atestação de titularidade da conta do recebedor (obrigatória quando a conta difere da conta da recorrência). calendario: $ref: "#/components/schemas/CobRCalendarioCreate" description: Controle de tempo da cobrança. devedor: $ref: "#/components/schemas/CobRDevedorDTO" description: Contato do devedor (sem identidade; a identidade está na Rec). idRec: description: Recorrência a que a cobrança pertence. examples: - RR1234567820240115abcdefghijk pattern: ^[a-zA-Z0-9]{29}$ type: string infoAdicional: description: Informação adicional (campo único, não array). maxLength: 140 type: string recebedor: $ref: "#/components/schemas/CobRRecebedorBancarioDTO" description: Conta bancária do recebedor. valor: $ref: "#/components/schemas/CobRValorCreate" description: Valor da cobrança. required: - idRec - calendario - valor - ajusteDiaUtil - recebedor type: object CobRTentativaAtualizacaoDTO: additionalProperties: false properties: data: description: Instante da atualização (RFC 3339). type: string status: enum: - SOLICITADA - AGENDADA - PAGA - CANCELADA - REJEITADA - EXPIRADA type: string required: - status - data type: object CobRTentativaDTO: additionalProperties: false properties: atualizacao: items: $ref: "#/components/schemas/CobRTentativaAtualizacaoDTO" type: array dataLiquidacao: description: Data de liquidação da tentativa (YYYY-MM-DD). type: string endToEndId: pattern: "[a-zA-Z0-9]{32}" type: string rejeicao: $ref: "#/components/schemas/CobRRejeicaoDTO" status: enum: - SOLICITADA - AGENDADA - PAGA - CANCELADA - REJEITADA - EXPIRADA type: string tipo: enum: - AGND - NTAG - RIFL type: string required: - dataLiquidacao - tipo - status - endToEndId - atualizacao type: object CobRValorCreate: additionalProperties: false properties: original: description: Valor original da cobrança recorrente (único campo monetário). examples: - "100.00" pattern: ^\d{1,10}\.\d{2}$ type: string required: - original type: object CobRValorDTO: additionalProperties: false properties: original: description: Valor original da cobrança recorrente. pattern: ^\d{1,10}\.\d{2}$ type: string required: - original type: object CobRevisada: additionalProperties: false properties: calendario: $ref: "#/components/schemas/CobCalendarioSolicitado" description: Controle de tempo da cobrança. chave: description: Chave DICT do recebedor. maxLength: 77 type: string devedor: $ref: "#/components/schemas/Pessoa" description: Devedor da cobrança. infoAdicionais: description: Informações adicionais (máx 50). items: $ref: "#/components/schemas/InfoAdicional" maxItems: 50 type: - array - "null" loc: $ref: "#/components/schemas/CobLocSolicitada" description: Referência de location. solicitacaoPagador: description: Texto livre apresentado ao pagador. maxLength: 140 type: string status: description: "Único valor aceito: REMOVIDA_PELO_USUARIO_RECEBEDOR (remove a cobrança)." enum: - REMOVIDA_PELO_USUARIO_RECEBEDOR type: string valor: $ref: "#/components/schemas/CobValorRevise" description: Valores monetários da cobrança; cada membro ausente mantém o valor armazenado. type: object CobSolicitada: additionalProperties: false properties: calendario: $ref: "#/components/schemas/CobCalendarioSolicitado" description: Controle de tempo da cobrança. chave: description: Chave DICT do recebedor. examples: - pix@lerian.studio maxLength: 77 type: string devedor: $ref: "#/components/schemas/Pessoa" description: Devedor da cobrança (PF/PJ, opcional). infoAdicionais: description: Informações adicionais (máx 50). items: $ref: "#/components/schemas/InfoAdicional" maxItems: 50 type: - array - "null" loc: $ref: "#/components/schemas/CobLocSolicitada" description: Referência de location. solicitacaoPagador: description: Texto livre apresentado ao pagador. maxLength: 140 type: string valor: $ref: "#/components/schemas/CobValorCreate" description: Valores monetários da cobrança. required: - calendario - valor - chave type: object CobVCalendarioGerado: additionalProperties: false properties: criacao: description: Data de criação da cobrança (RFC 3339). type: string dataDeVencimento: description: Data de vencimento da cobrança (YYYY-MM-DD). type: string validadeAposVencimento: description: Dias corridos após dataDeVencimento em que a cobrança pode ser paga. format: int64 minimum: 0 type: integer required: - criacao - dataDeVencimento - validadeAposVencimento type: object CobVCalendarioSolicitado: additionalProperties: false properties: dataDeVencimento: description: Data de vencimento da cobrança (YYYY-MM-DD). examples: - "2030-04-01" format: date type: string validadeAposVencimento: description: "Dias corridos após dataDeVencimento em que a cobrança pode ser paga (padrão 30). Zero é válido: a cobrança só é pagável no próprio dia de vencimento." examples: - 30 format: int64 minimum: 0 type: integer required: - dataDeVencimento type: object CobVCompleta: additionalProperties: false properties: calendario: $ref: "#/components/schemas/CobVCalendarioGerado" chave: description: Chave DICT do recebedor. maxLength: 77 type: string devedor: $ref: "#/components/schemas/Pessoa" infoAdicionais: items: $ref: "#/components/schemas/InfoAdicional" type: array loc: $ref: "#/components/schemas/CobLocGerada" location: description: Localização do payload. maxLength: 77 type: string pix: description: Pix recebidos vinculados à cobrança. items: $ref: "#/components/schemas/PixRecebido" type: array pixCopiaECola: description: Pix Copia e Cola (BR Code) correspondente à cobrança. maxLength: 512 type: string recebedor: $ref: "#/components/schemas/RecebedorDTO" revisao: description: Revisão da cobrança (inicia em 0). format: int64 type: integer solicitacaoPagador: maxLength: 140 type: string status: description: Status do registro da cobrança. enum: - ATIVA - CONCLUIDA - REMOVIDA_PELO_USUARIO_RECEBEDOR - REMOVIDA_PELO_PSP type: string txid: description: Identificador da transação. pattern: "[a-zA-Z0-9]{26,35}" type: string valor: $ref: "#/components/schemas/CobVValor" required: - calendario - txid - revisao - devedor - recebedor - status - valor - chave type: object CobVDesconto: additionalProperties: false properties: descontoDataFixa: description: "Descontos com data fixa (modalidades 1..2), até 3 entradas, no máximo uma por data: duas entradas declarando a mesma data são recusadas (422)." items: $ref: "#/components/schemas/DescontoDataFixa" maxItems: 3 type: - array - "null" modalidade: description: Modalidade de desconto (1..6), conforme tabela de domínios. format: int64 maximum: 6 minimum: 1 type: integer valorPerc: description: Desconto absoluto ou percentual (modalidades 3..6). pattern: ^\d{1,10}\.\d{2}$ type: string required: - modalidade type: object CobVGerada: additionalProperties: false properties: calendario: $ref: "#/components/schemas/CobVCalendarioGerado" chave: description: Chave DICT do recebedor. maxLength: 77 type: string devedor: $ref: "#/components/schemas/Pessoa" infoAdicionais: items: $ref: "#/components/schemas/InfoAdicional" type: array loc: $ref: "#/components/schemas/CobLocGerada" location: description: Localização do payload. maxLength: 77 type: string pixCopiaECola: description: Pix Copia e Cola (BR Code) correspondente à cobrança. maxLength: 512 type: string recebedor: $ref: "#/components/schemas/RecebedorDTO" revisao: description: Revisão da cobrança (inicia em 0). format: int64 type: integer solicitacaoPagador: maxLength: 140 type: string status: description: Status do registro da cobrança. enum: - ATIVA - CONCLUIDA - REMOVIDA_PELO_USUARIO_RECEBEDOR - REMOVIDA_PELO_PSP type: string txid: description: Identificador da transação. pattern: "[a-zA-Z0-9]{26,35}" type: string valor: $ref: "#/components/schemas/CobVValor" required: - calendario - txid - revisao - devedor - recebedor - status - valor - chave type: object CobVRevisada: additionalProperties: false properties: calendario: $ref: "#/components/schemas/CobVCalendarioSolicitado" description: Controle de tempo da cobrança. chave: description: Chave DICT do recebedor. maxLength: 77 type: string devedor: $ref: "#/components/schemas/Pessoa" description: Devedor da cobrança. infoAdicionais: description: Informações adicionais (máx 50). items: $ref: "#/components/schemas/InfoAdicional" maxItems: 50 type: - array - "null" loc: $ref: "#/components/schemas/CobLocSolicitada" description: Referência de location. solicitacaoPagador: description: Texto livre apresentado ao pagador. maxLength: 140 type: string status: description: "Único valor aceito: REMOVIDA_PELO_USUARIO_RECEBEDOR (remove a cobrança)." enum: - REMOVIDA_PELO_USUARIO_RECEBEDOR type: string valor: $ref: "#/components/schemas/CobVValor" description: Valores monetários da cobrança. type: object CobVSolicitada: additionalProperties: false properties: calendario: $ref: "#/components/schemas/CobVCalendarioSolicitado" description: Controle de tempo da cobrança. chave: description: Chave DICT do recebedor. examples: - pix@lerian.studio maxLength: 77 type: string devedor: $ref: "#/components/schemas/Pessoa" description: Devedor da cobrança (PF/PJ). Obrigatório em CobV. infoAdicionais: description: Informações adicionais (máx 50). items: $ref: "#/components/schemas/InfoAdicional" maxItems: 50 type: - array - "null" loc: $ref: "#/components/schemas/CobLocSolicitada" description: Referência de location. solicitacaoPagador: description: Texto livre apresentado ao pagador. maxLength: 140 type: string valor: $ref: "#/components/schemas/CobVValorCreate" description: Valores monetários da cobrança. required: - calendario - devedor - valor - chave type: object CobVValor: additionalProperties: false properties: abatimento: $ref: "#/components/schemas/ValorPercModalidade" description: Abatimento aplicado (modalidade 1..2). desconto: $ref: "#/components/schemas/CobVDesconto" description: Descontos aplicados (modalidade 1..6). juros: $ref: "#/components/schemas/ValorPercModalidade" description: Juros aplicados (modalidade 1..8). multa: $ref: "#/components/schemas/ValorPercModalidade" description: Multa aplicada (modalidade 1..2). original: description: Valor original da cobrança (obrigatório na criação). examples: - "250.00" pattern: ^\d{1,10}\.\d{2}$ type: string type: object CobVValorCreate: additionalProperties: false properties: abatimento: $ref: "#/components/schemas/ValorPercModalidade" description: Abatimento aplicado (modalidade 1..2). desconto: $ref: "#/components/schemas/CobVDesconto" description: Descontos aplicados (modalidade 1..6). juros: $ref: "#/components/schemas/ValorPercModalidade" description: Juros aplicados (modalidade 1..8). multa: $ref: "#/components/schemas/ValorPercModalidade" description: Multa aplicada (modalidade 1..2). original: description: Valor original da cobrança (obrigatório na criação). examples: - "250.00" pattern: ^\d{1,10}\.\d{2}$ type: string required: - original type: object CobValor: additionalProperties: false properties: modalidadeAlteracao: description: 0 = valor fixo (padrão); 1 = valor alterável pelo pagador. format: int64 maximum: 1 minimum: 0 type: integer original: description: Valor original da cobrança. examples: - "250.00" pattern: ^\d{1,10}\.\d{2}$ type: string retirada: $ref: "#/components/schemas/Retirada" description: Estrutura opcional de recebimento de numerário (Pix Saque/Troco). required: - original type: object CobValorCreate: additionalProperties: false properties: modalidadeAlteracao: description: 0 = valor fixo (padrão); 1 = valor alterável pelo pagador. format: int64 maximum: 1 minimum: 0 type: integer original: description: Valor original da cobrança (obrigatório na criação). examples: - "250.00" pattern: ^\d{1,10}\.\d{2}$ type: string retirada: $ref: "#/components/schemas/Retirada" description: Estrutura opcional de recebimento de numerário (Pix Saque/Troco). required: - original type: object CobValorRevise: additionalProperties: false properties: modalidadeAlteracao: description: 0 = valor fixo; 1 = valor alterável pelo pagador; ausente mantém a modalidade armazenada. format: int64 maximum: 1 minimum: 0 type: integer original: description: Novo valor original da cobrança; ausente mantém o valor armazenado. examples: - "250.00" pattern: ^\d{1,10}\.\d{2}$ type: string retirada: $ref: "#/components/schemas/Retirada" description: Estrutura opcional de recebimento de numerário (Pix Saque/Troco). type: object CobsConsultadas: additionalProperties: false properties: cobs: items: $ref: "#/components/schemas/CobCompleta" type: array parametros: $ref: "#/components/schemas/Parametros" required: - parametros - cobs type: object CobsRConsultadas: additionalProperties: false properties: cobsr: items: $ref: "#/components/schemas/CobRCompleta" type: array parametros: $ref: "#/components/schemas/Parametros" required: - parametros - cobsr type: object CobsVConsultadas: additionalProperties: false properties: cobs: items: $ref: "#/components/schemas/CobVCompleta" type: array parametros: $ref: "#/components/schemas/Parametros" required: - parametros - cobs type: object DecodeBRCodeRequest: additionalProperties: false properties: raw: description: "Raw EMV BR Code copy-paste string to decode into structured payload fields. The 512-character ceiling is Lerian's own cap on what this service accepts, not BACEN's: a code scanned from a third party can carry other arrangements' Merchant Account Information. It is separate from the 512-byte cap BACEN declares on a pixCopiaECola this service emits." examples: - 00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-44665544000052040000530398654041.005802BR5913Lerian Studio6009Sao Paulo62070503***6304ABCD maxLength: 512 minLength: 1 type: string required: - raw type: object DescontoDataFixa: additionalProperties: false properties: data: description: Data limite do desconto (YYYY-MM-DD). examples: - "2030-03-01" pattern: ^\d{4}-\d{2}-\d{2}$ type: string valorPerc: description: Valor absoluto ou percentual do desconto. pattern: ^\d{1,10}\.\d{2}$ type: string required: - data - valorPerc type: object Detail: additionalProperties: false properties: code: description: "Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN)." type: string correlationId: description: Request-scoped correlation identifier echoing X-Request-ID. examples: - req-7a3f9c2e type: string detail: description: A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: "#/components/schemas/ErrorDetail" type: - array - "null" instance: description: A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: "#/components/schemas/Upstream" description: "RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one." required: - correlationId type: object ErrorDetail: additionalProperties: false properties: location: description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object FileBatchDTO: additionalProperties: false properties: acceptedLines: description: Registros aceitos. format: int64 type: integer createdAt: description: Momento do upload (RFC 3339). type: string filename: description: Nome do arquivo enviado. type: string id: description: Identificador do lote (UUID). format: uuid type: string lines: description: Resultado por registro, em ordem de arquivo. items: $ref: "#/components/schemas/FileBatchLineDTO" type: array processedAt: description: Momento em que o lote foi encerrado (RFC 3339). type: string recebedorDocument: description: CNPJ do recebedor declarado no Header do arquivo. type: string rejectedLines: description: Registros recusados. format: int64 type: integer status: description: PROCESSING, PROCESSED ou REJECTED. examples: - PROCESSED type: string totalLines: description: Registros DETALHE que o arquivo continha. format: int64 type: integer required: - id - filename - recebedorDocument - status - totalLines - acceptedLines - rejectedLines - createdAt - lines type: object FileBatchLineDTO: additionalProperties: false properties: errorCode: description: Código oficial da recusa (aba CÓDIGOS DE ERRO), quando recusado. type: string errorDetail: description: Campo e regra da recusa. Nunca ecoa o valor recusado. type: string lineNumber: description: Ordem do registro na remessa (1-based, o Header é 1), a mesma que o retorno endereça. Linhas em branco são descartadas antes da numeração, então a ordem compacta e pode não coincidir com a posição absoluta no arquivo enviado. format: int64 type: integer occurrence: description: Código de ocorrência solicitado (01 emissão, 02 cancelamento, 03 alteração). examples: - "01" type: string resultId: description: Identificador gerado/afetado (idRec), quando aceito. type: string segment: description: Segmento do registro. examples: - REC type: string status: description: ACCEPTED ou REJECTED. examples: - ACCEPTED type: string required: - lineNumber - segment - occurrence - status type: object GenerateBRCodeRequest: additionalProperties: false properties: amount: description: Transaction amount in BRL as a decimal string, scale 2 (e.g. "100.00"). Empty leaves the amount open for the payer to set. examples: - "100.00" type: string arrangementType: description: Pix arrangement type governing MCC/key/amount constraints (e.g. direct_participant). Empty applies the default arrangement. examples: - direct_participant type: string fss: description: Eight-character ISPB ([0-9A-Z]{8}) of the withdrawal service facilitator (EMV subfield 26-03). Its presence marks the code as a Pix Saque QR; static codes only, and empty to omit it. examples: - "12345678" type: string infoAdicional: description: Free text shown to the payer while tracking the QR (EMV subfield 26-02). Shares the merchant account template's 99 characters with the Pix key and fss, so the accepted length depends on those; empty to omit it. examples: - Compra 042 type: string kind: description: "BR Code kind: STATIC (reusable, no expiry) or DYNAMIC (single-use, resolved via payload URL). Empty defaults to STATIC." examples: - STATIC type: string merchantCategoryCode: description: ISO 18245 four-digit Merchant Category Code; 0000 indicates no specific category. examples: - "0000" type: string merchantCity: description: Merchant city encoded into the EMV payload (EMV field 60). At most 15 characters, rejected rather than truncated, same as merchantName. examples: - São Paulo maxLength: 15 minLength: 1 type: string merchantName: description: "Merchant legal/trade name encoded into the EMV payload (EMV field 59). At most 25 characters: the encoder rejects a longer name rather than truncating it, so a caller sourcing the identity from a longer field must shorten it first." examples: - Lerian Studio maxLength: 25 minLength: 1 type: string pixKey: description: Pix key identifying the receiver (CPF/CNPJ, phone, email, or random EVP key). At most 77 characters. The service checks the shape of each key type (CPF and CNPJ check digits, a lower-case e-mail address, +55 plus a valid Brazilian area code, a version-4 UUID). Beside a withdrawal facilitator (fss), the key shares the merchant account template and its limit drops to 65 characters. examples: - "12345678901" maxLength: 77 minLength: 1 type: string txId: description: "Reference label written into EMV 62-05: at most 25 characters of a-z, A-Z or 0-9. It is the static code's own conciliation label, NOT the 26..35-character txid of an API-created cobrança. Empty for static codes that omit a transaction reference." examples: - Compra042 type: string required: - kind - merchantName - merchantCity - pixKey type: object InfoAdicional: additionalProperties: false properties: nome: description: Nome do campo. maxLength: 50 type: string valor: description: Dados do campo. maxLength: 200 type: string required: - nome - valor type: object JWK: additionalProperties: false properties: e: type: string key_ops: items: type: string type: array kid: type: string kty: type: string "n": type: string x5c: items: type: string type: array x5t: type: string x5t#S256: type: string required: - kty - "n" - e - key_ops - kid - x5t - x5t#S256 - x5c type: object JWKSet: additionalProperties: false properties: keys: items: $ref: "#/components/schemas/JWK" type: array required: - keys type: object ListPayloadsResponse: additionalProperties: false properties: correlationId: description: Request-scoped correlation identifier echoing X-Request-ID, for pivoting from response to trace. type: string items: description: Page of BR Code payloads for the requested limit/offset window. items: $ref: "#/components/schemas/PayloadResponse" type: array limit: description: Maximum number of items returned for this page (clamped to the server maximum). examples: - 25 format: int64 type: integer offset: description: Zero-based offset of the first item in this page. examples: - 0 format: int64 type: integer required: - items - limit - offset type: object LoteCobVBody: additionalProperties: false properties: cobsv: description: Solicitações de criação de cobranças com vencimento. items: $ref: "#/components/schemas/LoteCobVItemSolicitado" type: - array - "null" descricao: description: Descrição do lote. maxLength: 200 type: string required: - descricao - cobsv type: object LoteCobVBodyRevisado: additionalProperties: false properties: cobsv: description: Solicitações de alteração de cobranças com vencimento. items: $ref: "#/components/schemas/LoteCobVItemRevisado" type: - array - "null" descricao: description: Descrição do lote. type: string required: - cobsv type: object LoteCobVConsultado: additionalProperties: false properties: cobsv: description: Itens do lote com seus respectivos status. items: $ref: "#/components/schemas/LoteCobVItemConsultado" type: array criacao: description: Data de criação do lote (RFC 3339). type: string descricao: description: Descrição do lote. type: string id: description: Identificador do lote (texto). type: string required: - id - descricao - criacao - cobsv type: object LoteCobVItemConsultado: additionalProperties: false properties: criacao: description: Data e hora em que a cobrança foi criada (RFC 3339). type: string problema: $ref: "#/components/schemas/ProblemaDTO" description: Detalhe do problema (presente quando NEGADA). status: description: Status da solicitação no contexto do lote. enum: - EM_PROCESSAMENTO - CRIADA - NEGADA type: string txid: description: Identificador da transação do item. pattern: ^[a-zA-Z0-9]{26,35}$ type: string required: - txid - status type: object LoteCobVItemRevisado: additionalProperties: false properties: calendario: $ref: "#/components/schemas/CobVCalendarioSolicitado" description: Controle de tempo da cobrança. chave: description: Chave DICT do recebedor. maxLength: 77 type: string devedor: $ref: "#/components/schemas/Pessoa" description: Devedor da cobrança. infoAdicionais: description: Informações adicionais (máx 50). items: $ref: "#/components/schemas/InfoAdicional" maxItems: 50 type: - array - "null" loc: $ref: "#/components/schemas/CobLocSolicitada" description: Referência de location. solicitacaoPagador: description: Texto livre apresentado ao pagador. maxLength: 140 type: string status: description: "Único valor aceito: REMOVIDA_PELO_USUARIO_RECEBEDOR (remove a cobrança)." enum: - REMOVIDA_PELO_USUARIO_RECEBEDOR type: string txid: description: Identificador da transação do item [a-zA-Z0-9]{26,35}. pattern: ^[a-zA-Z0-9]{26,35}$ type: string valor: $ref: "#/components/schemas/CobVValor" description: Valores monetários da cobrança. required: - txid type: object LoteCobVItemSolicitado: additionalProperties: false properties: calendario: $ref: "#/components/schemas/CobVCalendarioSolicitado" description: Controle de tempo da cobrança. chave: description: Chave DICT do recebedor. examples: - pix@lerian.studio maxLength: 77 type: string devedor: $ref: "#/components/schemas/Pessoa" description: Devedor da cobrança (PF/PJ). Obrigatório em CobV. infoAdicionais: description: Informações adicionais (máx 50). items: $ref: "#/components/schemas/InfoAdicional" maxItems: 50 type: - array - "null" loc: $ref: "#/components/schemas/CobLocSolicitada" description: Referência de location. solicitacaoPagador: description: Texto livre apresentado ao pagador. maxLength: 140 type: string txid: description: Identificador da transação do item [a-zA-Z0-9]{26,35}. pattern: ^[a-zA-Z0-9]{26,35}$ type: string valor: $ref: "#/components/schemas/CobVValorCreate" description: Valores monetários da cobrança. required: - txid - calendario - devedor - valor - chave type: object LotesCobVConsultados: additionalProperties: false properties: lotes: items: $ref: "#/components/schemas/LoteCobVConsultado" type: array parametros: $ref: "#/components/schemas/Parametros" required: - parametros - lotes type: object Paginacao: additionalProperties: false properties: itensPorPagina: description: Quantidade de registros na página. format: int64 type: integer paginaAtual: description: Página recuperada (0-based). format: int64 type: integer quantidadeDePaginas: description: Quantidade de páginas disponíveis. format: int64 type: integer quantidadeTotalDeItens: description: Quantidade total de itens disponíveis. format: int64 type: integer required: - paginaAtual - itensPorPagina - quantidadeDePaginas - quantidadeTotalDeItens type: object Parametros: additionalProperties: false properties: fim: description: Fim do filtro (RFC 3339). type: string inicio: description: Início do filtro (RFC 3339). type: string paginacao: $ref: "#/components/schemas/Paginacao" required: - inicio - fim - paginacao type: object Party: additionalProperties: false properties: cep: type: string cidade: type: string cnpj: type: string cpf: type: string logradouro: type: string nome: type: string nomeFantasia: type: string uf: type: string type: object Payload: additionalProperties: false properties: amount: description: "Amount as presented: valor.original + saque + troco (cob) or valor.final (cobv). With modalidadeAlteracao 1 the payer may change it." type: string calendario: $ref: "#/components/schemas/Calendar" chave: type: string devedor: $ref: "#/components/schemas/Party" expiresAt: description: "cob only: calendario.criacao + calendario.expiracao." format: date-time type: string infoAdicionais: items: $ref: "#/components/schemas/AdditionalInfo" type: - array - "null" jws: description: The signed payload as served (JWS compact), kept as the payment's evidence. type: string kind: description: cob (immediate) or cobv (due date). type: string recebedor: $ref: "#/components/schemas/Party" revisao: format: int64 type: integer signingChain: description: "The verified JWS signing certificate chain, leaf first, each certificate base64 DER (as a JWK x5c). Keep it with the JWS: it carries the public key the signature verified against." items: contentEncoding: base64 type: string type: array solicitacaoPagador: type: string status: type: string txid: type: string valor: $ref: "#/components/schemas/Amounts" required: - kind - amount - jws - signingChain - revisao - calendario - valor - chave - txid - status type: object PayloadLocation: additionalProperties: false properties: criacao: description: Data de criação da location (RFC 3339). type: string id: description: Id da location (gerado pelo servidor). format: int64 type: integer location: description: Localização do payload (URI). maxLength: 77 type: string tipoCob: description: cob | cobv. enum: - cob - cobv type: string required: - id - location - tipoCob - criacao type: object PayloadLocationCompleta: additionalProperties: false properties: criacao: description: Data de criação da location (RFC 3339). type: string id: description: Id da location (gerado pelo servidor). format: int64 type: integer location: description: Localização do payload (URI). maxLength: 77 type: string tipoCob: description: cob | cobv. enum: - cob - cobv type: string txid: description: Identificador da transação vinculada (ausente quando desvinculada). pattern: ^[a-zA-Z0-9]{26,35}$ type: string required: - id - location - tipoCob - criacao type: object PayloadLocationConsultadas: additionalProperties: false properties: loc: items: $ref: "#/components/schemas/PayloadLocationCompleta" type: array parametros: $ref: "#/components/schemas/Parametros" required: - parametros - loc type: object PayloadLocationRecCompleta: additionalProperties: false properties: criacao: description: Data de criação da location (RFC 3339). type: string id: description: Id da location de recorrência (gerado pelo servidor). format: int64 type: integer idRec: description: Recorrência vinculada (ausente quando desvinculada). pattern: ^[a-zA-Z0-9]{29}$ type: string location: description: Localização do payload de recorrência (URI). maxLength: 77 type: string tipo: description: "Tipo fixo: rec." enum: - rec examples: - rec type: string required: - id - location - tipo - criacao type: object PayloadLocationRecConsultadas: additionalProperties: false properties: loc: items: $ref: "#/components/schemas/PayloadLocationRecCompleta" type: array parametros: $ref: "#/components/schemas/Parametros" required: - parametros - loc type: object PayloadLocationRecGerada: additionalProperties: false properties: criacao: description: Data de criação da location (RFC 3339). type: string id: description: Id da location de recorrência (gerado pelo servidor). format: int64 type: integer location: description: Localização do payload de recorrência (URI). maxLength: 77 type: string tipo: description: "Tipo fixo: rec." enum: - rec examples: - rec type: string required: - id - location - tipo - criacao type: object PayloadLocationSolicitada: additionalProperties: false properties: tipoCob: description: Tipo de cobrança que a location endereça. enum: - cob - cobv examples: - cob type: string required: - tipoCob type: object PayloadResponse: additionalProperties: false properties: amount: description: Transaction amount in BRL as a decimal string, scale 2 (empty when the amount is open). examples: - "100.00" type: string copyPaste: description: Pix copy-and-paste string (the raw EMV payload); empty when unavailable. examples: - 00020126580014br.gov.bcb.pix... type: string createdAt: description: Creation timestamp in RFC3339 UTC. examples: - "2025-03-07T14:30:00Z" type: string fss: description: "Eight-character ISPB ([0-9A-Z]{8}) of the withdrawal service facilitator (EMV subfield 26-03), and the Pix Saque marker: its presence means this IS a Pix Saque QR. Populated on static codes only; a dynamic code's merchant account template is GUI plus URL, so a 26-03 there marks nothing and is reported as ignoredFss instead, a dynamic withdrawal or troco being declared in the URL-resolved payload's retirada object. Empty when the code omits it." examples: - "12345678" type: string id: description: Server-assigned payload identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string ignoredAmount: description: Amount a non-conformant emitter wrote into EMV 54 of a dynamic code. A dynamic code's amount comes from the payload URL, so this value must NOT be paid or displayed as owed; it is reported only to diagnose the emitter. Empty otherwise. examples: - "10.00" type: string ignoredFss: description: "Value a non-conformant emitter wrote into EMV subfield 26-03 of a dynamic code, whose merchant account template is GUI plus URL alone. Like ignoredAmount it must NOT be acted on: it is NOT a Pix Saque marker and is not even guaranteed to be a valid eight-character ISPB, since a dynamic 26-03 is neither shape-checked nor charged to the template's character budget. Reported only to diagnose the emitter. Empty otherwise." examples: - "12345678" type: string ignoredInfoAdicional: description: "Free text a non-conformant emitter wrote into EMV subfield 26-02 of a dynamic code, whose merchant account template is GUI plus URL alone. It must NOT be displayed as the code's own text: a dynamic charge's real infoAdicionais come from the URL-resolved payload, and this value is neither length-checked nor charged to the template's character budget. Reported only to diagnose the emitter. Empty otherwise." examples: - Compra 042 type: string ignoredTxId: description: 'Reference label a non-conformant emitter wrote into EMV 62-05 of a dynamic code. Like ignoredAmount it must NOT be acted on: the URL-resolved payload prevails. Empty otherwise.' examples: - TXIDABCDEFGHIJKLMNOPQRSTUVWXYZ type: string infoAdicional: description: Free text the payer is shown while tracking the code (EMV subfield 26-02), and the code's own display text. Populated on static codes only; a dynamic code's merchant account template is GUI plus URL, so text there is emitter noise and is reported as ignoredInfoAdicional instead, a dynamic charge's real infoAdicionais living in the URL-resolved payload. Empty when the code omits it. examples: - Compra 042 type: string kind: description: "BR Code kind: STATIC (reusable) or DYNAMIC (single-use)." examples: - STATIC type: string merchantCity: description: Merchant city from the EMV payload (EMV field 60). examples: - São Paulo type: string merchantName: description: Merchant legal/trade name from the EMV payload (EMV field 59). examples: - Lerian Studio type: string payloadUrl: description: Payload location for dynamic codes, without protocol prefix; resolvable over HTTPS only. Empty for static codes. examples: - pix.example.com/qr/v2/550e8400 type: string pixKey: description: Pix key identifying the receiver (CPF/CNPJ, phone, email, or random EVP key). examples: - "12345678901" type: string qrPngBase64: description: QR code image rendered from the raw payload, base64-encoded PNG (only populated on generation responses). examples: - iVBORw0KGgoAAAANSUhEUgAA... type: string qrPngContentType: description: MIME content type of qrPngBase64 (image/png) when an image is present. examples: - image/png type: string raw: description: Raw EMV BR Code string; same value as copyPaste, retained for compatibility. examples: - 00020126580014br.gov.bcb.pix... type: string recurrenceUrl: description: Recurrence-parameters location of a composite BR Code (EMV subfield 80-25), without protocol prefix; resolvable over HTTPS only. Its presence means this code initiates a Pix Automático recurrence, and it may stand alongside a pixKey or a payloadUrl or, in the recurrence-only configuration, alone. Empty on a code that initiates no recurrence. examples: - pix.example.com/rec/2353c790eefb11eaadc10242ac120002 type: string status: description: Lifecycle status of the payload (e.g. ACTIVE). examples: - ACTIVE type: string txId: description: Reference label carried in EMV 62-05, at most 25 characters of a-z, A-Z or 0-9; empty when not present. examples: - Compra042 type: string updatedAt: description: Last-update timestamp in RFC3339 UTC. examples: - "2025-03-07T14:30:00Z" type: string required: - id - kind - merchantName - merchantCity - pixKey - status - createdAt - updatedAt type: object Pessoa: additionalProperties: false oneOf: - properties: cpf: type: string nome: type: string required: - cpf - nome title: Pessoa Física type: object - properties: cnpj: type: string nome: type: string required: - cnpj - nome title: Pessoa Jurídica type: object properties: cep: description: CEP do devedor. maxLength: 8 type: string cidade: description: Cidade do devedor. maxLength: 200 type: string cnpj: description: CNPJ do devedor (PJ). Mutuamente exclusivo com cpf. examples: - 12ABC34501DE35 pattern: ^[0-9A-Z]{14}$ type: string cpf: description: CPF do devedor (PF). Mutuamente exclusivo com cnpj. examples: - "12345678901" pattern: ^\d{11}$ type: string email: description: Email do devedor. type: string logradouro: description: Logradouro do devedor. maxLength: 200 type: string nome: description: Nome do devedor. examples: - Fulano de Tal maxLength: 200 type: string uf: description: UF do devedor. maxLength: 2 type: string type: object PixRecebido: additionalProperties: false properties: endToEndId: pattern: "[a-zA-Z0-9]{32}" type: string horario: description: Horário do processamento do Pix (RFC 3339). type: string txid: pattern: "[a-zA-Z0-9]{1,35}" type: string valor: pattern: ^\d{1,10}\.\d{2}$ type: string required: - endToEndId - valor - horario type: object ProblemaDTO: additionalProperties: false properties: correlationId: description: Identificador de correlação. type: string detail: description: Descrição detalhada do problema. type: string status: description: Código HTTP do problema. format: int64 type: integer title: description: Título legível do problema. type: string type: description: URI que identifica o tipo do problema. type: string violacoes: description: Violações específicas. items: $ref: "#/components/schemas/ViolacaoDTO" type: array required: - type - title - status type: object RecAtestacaoTitularidadeDTO: additionalProperties: false properties: agencia: description: Agência da conta atestada. maxLength: 4 type: string conta: description: Conta cuja titularidade é atestada. maxLength: 20 type: string tipoConta: description: Tipo da conta atestada. enum: - CORRENTE - POUPANCA - PAGAMENTO type: string required: - conta - tipoConta type: object RecAtestacaoTitularidadeRegistradaDTO: additionalProperties: false properties: agencia: type: string atestadaEm: description: Instante da atestação (RFC 3339). type: string atestadaPor: description: Ator autenticado que fez a atestação. type: string conta: type: string tipoConta: type: string required: - conta - tipoConta - atestadaPor - atestadaEm type: object RecAtivacaoDTO: additionalProperties: false properties: dadosJornada: $ref: "#/components/schemas/RecDadosJornadaDTO" description: Dados da jornada (hoje apenas txid, obrigatório na JORNADA_3). tipoJornada: description: Jornada de ativação da recorrência. enum: - JORNADA_1 - JORNADA_2 - JORNADA_3 - JORNADA_4 - AGUARDANDO_DEFINICAO type: string required: - tipoJornada type: object RecAtivacaoSolicitadaDTO: additionalProperties: false properties: dadosJornada: $ref: "#/components/schemas/RecDadosJornadaDTO" type: object RecAtualizacaoDTO: additionalProperties: false properties: data: description: Instante da atualização (RFC 3339). type: string status: description: Status da recorrência no instante. enum: - CRIADA - APROVADA - REJEITADA - EXPIRADA - CANCELADA type: string required: - status - data type: object RecCalendarioDTO: additionalProperties: false properties: dataFinal: description: Data final (apenas vigência fixa; ausente para indeterminada) (YYYY-MM-DD). Não pode ser anterior a dataInicial. type: string dataInicial: description: Data estimada do primeiro pagamento (YYYY-MM-DD). Não pode ser anterior à data de criação da recorrência. examples: - "2027-01-15" type: string periodicidade: description: Cadência da recorrência. enum: - SEMANAL - MENSAL - TRIMESTRAL - SEMESTRAL - ANUAL examples: - MENSAL type: string required: - dataInicial - periodicidade type: object RecCancelamentoDTO: additionalProperties: false properties: codigo: description: Código do cancelamento no catálogo de mensagens. enum: - ACCL - CPCL - DCSD - ERSL - FRUD - PCFD - SLCR - SLDB maxLength: 4 type: string descricao: description: Descrição do cancelamento. maxLength: 400 type: string solicitante: description: Quem solicitou o cancelamento. enum: - PSP_PAGADOR - USUARIO_PAGADOR - PSP_RECEBEDOR - USUARIO_RECEBEDOR type: string required: - solicitante - codigo - descricao type: object RecCompleta: additionalProperties: false properties: atestacaoTitularidade: $ref: "#/components/schemas/RecAtestacaoTitularidadeRegistradaDTO" ativacao: $ref: "#/components/schemas/RecAtivacaoDTO" atualizacao: items: $ref: "#/components/schemas/RecAtualizacaoDTO" type: array calendario: $ref: "#/components/schemas/RecCalendarioDTO" dadosQR: $ref: "#/components/schemas/RecDadosQRDTO" description: "QR Composto da recorrência (Pix Automático). Ausente em duas situações: enquanto a recorrência não tem locrec vinculada, e enquanto a instituição não tiver registrado, para o CNPJ do recebedor desta recorrência, um único perfil de recebedor, de onde sai a cidade obrigatória do BR Code (tag 60). Uma recorrência tem conta e CNPJ, não chave Pix, e nada no fluxo de recorrência cria esse registro: sem ele, ou com mais de um perfil para o mesmo CNPJ, o QR é OMITIDO em vez de sair com uma cidade inventada. Registrar um perfil de recebedor com o CNPJ correspondente é o que passa a servir o QR." encerramento: $ref: "#/components/schemas/RecEncerramentoDTO" idRec: description: Identificador da recorrência. pattern: ^[a-zA-Z0-9]{29}$ type: string loc: $ref: "#/components/schemas/PayloadLocationRecCompleta" pagador: $ref: "#/components/schemas/RecPagadorDTO" description: Dados do usuário pagador informados pelo PSP pagador na confirmação da recorrência. politicaRetentativa: enum: - NAO_PERMITE - PERMITE_3R_7D type: string recebedor: $ref: "#/components/schemas/RecRecebedorDTO" solicitacao: items: $ref: "#/components/schemas/SolicRecCompleta" type: array status: enum: - CRIADA - APROVADA - REJEITADA - EXPIRADA - CANCELADA type: string valor: $ref: "#/components/schemas/RecValorDTO" vinculo: $ref: "#/components/schemas/RecVinculoDTO" required: - idRec - vinculo - calendario - recebedor - politicaRetentativa - status - atualizacao type: object RecCompletaPesquisada: additionalProperties: false properties: atestacaoTitularidade: $ref: "#/components/schemas/RecAtestacaoTitularidadeRegistradaDTO" ativacao: $ref: "#/components/schemas/RecAtivacaoDTO" atualizacao: items: $ref: "#/components/schemas/RecAtualizacaoDTO" type: array calendario: $ref: "#/components/schemas/RecCalendarioDTO" encerramento: $ref: "#/components/schemas/RecEncerramentoDTO" idRec: description: Identificador da recorrência. pattern: ^[a-zA-Z0-9]{29}$ type: string loc: $ref: "#/components/schemas/PayloadLocationRecCompleta" pagador: $ref: "#/components/schemas/RecPagadorDTO" description: Dados do usuário pagador informados pelo PSP pagador na confirmação da recorrência. politicaRetentativa: enum: - NAO_PERMITE - PERMITE_3R_7D type: string recebedor: $ref: "#/components/schemas/RecRecebedorDTO" solicitacao: items: $ref: "#/components/schemas/SolicRecCompleta" type: array status: enum: - CRIADA - APROVADA - REJEITADA - EXPIRADA - CANCELADA type: string valor: $ref: "#/components/schemas/RecValorDTO" vinculo: $ref: "#/components/schemas/RecVinculoDTO" required: - idRec - vinculo - calendario - recebedor - politicaRetentativa - status - atualizacao type: object RecDadosJornadaDTO: additionalProperties: false properties: txid: description: txid da cobrança imediata paga no momento da autorização. Obrigatório na JORNADA_3; removido nas jornadas 1, 2 e 4. pattern: ^[a-zA-Z0-9]{26,35}$ type: string required: - txid type: object RecDadosQRDTO: additionalProperties: false properties: jornada: description: "Jornada do QR Composto construído. Nesta superfície sempre JORNADA_2, o QR só de recorrência. JORNADA_3/4 (composição com cobrança imediata ou com vencimento, via txid na consulta) não são servidas aqui: a consulta com txid é recusada." enum: - JORNADA_2 examples: - JORNADA_2 type: string pixCopiaECola: description: Pix Copia e Cola (BR Code) do QR Composto da recorrência. maxLength: 512 type: string required: - jornada - pixCopiaECola type: object RecDevedorDTO: additionalProperties: false properties: cnpj: description: CNPJ do devedor (PJ). Mutuamente exclusivo com cpf. examples: - 12ABC34501DE35 pattern: ^[0-9A-Z]{14}$ type: string cpf: description: CPF do devedor (PF). Mutuamente exclusivo com cnpj. examples: - "12345678901" pattern: ^\d{11}$ type: string nome: description: Nome do devedor. examples: - Fulano de Tal maxLength: 140 type: string type: object RecEncerramentoDTO: additionalProperties: false properties: cancelamento: $ref: "#/components/schemas/RecCancelamentoDTO" rejeicao: $ref: "#/components/schemas/RecRejeicaoDTO" type: object RecGerada: additionalProperties: false properties: atestacaoTitularidade: $ref: "#/components/schemas/RecAtestacaoTitularidadeRegistradaDTO" ativacao: $ref: "#/components/schemas/RecAtivacaoDTO" atualizacao: items: $ref: "#/components/schemas/RecAtualizacaoDTO" type: array calendario: $ref: "#/components/schemas/RecCalendarioDTO" encerramento: $ref: "#/components/schemas/RecEncerramentoDTO" idRec: description: Identificador da recorrência. pattern: ^[a-zA-Z0-9]{29}$ type: string loc: $ref: "#/components/schemas/PayloadLocationRecCompleta" politicaRetentativa: enum: - NAO_PERMITE - PERMITE_3R_7D type: string recebedor: $ref: "#/components/schemas/RecRecebedorDTO" solicitacao: items: $ref: "#/components/schemas/SolicRecCompleta" type: array status: enum: - CRIADA - APROVADA - REJEITADA - EXPIRADA - CANCELADA type: string valor: $ref: "#/components/schemas/RecValorDTO" vinculo: $ref: "#/components/schemas/RecVinculoDTO" required: - idRec - vinculo - calendario - recebedor - politicaRetentativa - status - atualizacao type: object RecPagadorDTO: additionalProperties: false properties: cnpj: description: CNPJ do usuário pagador, informado pelo PSP pagador na confirmação da recorrência. Exclusivo com cpf. examples: - "28333333150443" pattern: ^[0-9A-Z]{14}$ type: string codMun: description: "Código IBGE (7 dígitos) do município do usuário pagador, informado pelo PSP pagador na confirmação da recorrência. Determina os feriados locais que deslocam a data prevista para liquidação das cobranças. Ausente: assume-se que não há feriados estaduais/municipais." examples: - "3550308" pattern: ^\d{7}$ type: string cpf: description: CPF do usuário pagador, informado pelo PSP pagador na confirmação da recorrência. Exclusivo com cnpj. examples: - "23933333316" pattern: ^\d{11}$ type: string ispbParticipante: description: ISPB do participante do usuário pagador, informado pelo PSP pagador na confirmação da recorrência. examples: - "81102623" pattern: ^[0-9A-Z]{8}$ type: string type: object RecPatch: additionalProperties: false properties: ativacao: $ref: "#/components/schemas/RecAtivacaoSolicitadaDTO" description: Patch da ativação (apenas dadosJornada.txid, somente enquanto status == CRIADA). calendario: $ref: "#/components/schemas/RecPatchCalendarioDTO" description: Patch do calendário (apenas dataInicial). cancelamento: $ref: "#/components/schemas/RecCancelamentoDTO" description: Detalhe do cancelamento (registrado em encerramento.cancelamento). loc: description: Id da location (locrec) a vincular. Alterável inclusive após a confirmação. format: int64 minimum: 1 type: integer status: description: Novo status da recorrência (CANCELADA cancela o mandato — único destino de status aceito no PATCH, RecRevisada.status v2.9). enum: - CANCELADA type: string vinculo: $ref: "#/components/schemas/RecPatchVinculoDTO" description: Patch do vínculo (apenas devedor.nome). type: object RecPatchCalendarioDTO: additionalProperties: false properties: dataInicial: description: Nova data estimada do primeiro pagamento (YYYY-MM-DD). Alterável somente enquanto status == CRIADA, e não pode ser anterior à data de criação da recorrência. examples: - "2027-02-01" type: string type: object RecPatchDevedorDTO: additionalProperties: false properties: nome: description: Novo nome do devedor. Alterável inclusive após a confirmação da recorrência. maxLength: 140 type: string type: object RecPatchVinculoDTO: additionalProperties: false properties: devedor: $ref: "#/components/schemas/RecPatchDevedorDTO" type: object RecPayloadDTO: additionalProperties: false properties: atualizacao: items: $ref: "#/components/schemas/RecAtualizacaoDTO" type: array calendario: $ref: "#/components/schemas/RecCalendarioDTO" idRec: description: Identificador da recorrência. pattern: ^[a-zA-Z0-9]{29}$ type: string politicaRetentativa: enum: - NAO_PERMITE - PERMITE_3R_7D type: string recebedor: $ref: "#/components/schemas/RecPayloadRecebedorDTO" valor: $ref: "#/components/schemas/RecValorDTO" vinculo: $ref: "#/components/schemas/RecVinculoDTO" required: - idRec - vinculo - calendario - recebedor - politicaRetentativa - atualizacao type: object RecPayloadRecebedorDTO: additionalProperties: false properties: cnpj: pattern: ^[0-9A-Z]{14}$ type: string ispbParticipante: pattern: ^[0-9A-Z]{8}$ type: string nome: maxLength: 140 type: string required: - cnpj - nome - ispbParticipante type: object RecRecebedorDTO: additionalProperties: false properties: agencia: description: Agência do recebedor. examples: - "0001" maxLength: 4 type: string cnpj: description: CNPJ do usuário recebedor (identidade exigida pelo RecPayload). examples: - 12ABC34501DE35 pattern: ^[0-9A-Z]{14}$ type: string conta: description: Conta do recebedor. examples: - "1234567890" maxLength: 20 type: string convenio: description: Convênio entre usuário e participante recebedor. maxLength: 60 type: string ispbParticipante: description: ISPB do participante do usuário recebedor (definido pelo servidor). pattern: ^[0-9A-Z]{8}$ type: string nome: description: Nome do usuário recebedor (identidade exigida pelo RecPayload). examples: - Empresa Recebedora LTDA maxLength: 140 type: string tipoConta: description: Tipo de conta do recebedor. enum: - CORRENTE - POUPANCA - PAGAMENTO examples: - CORRENTE type: string required: - conta - tipoConta - cnpj - nome type: object RecRejeicaoDTO: additionalProperties: false properties: codigo: description: Código da rejeição no catálogo de mensagens. enum: - AP13 - AP14 maxLength: 4 type: string descricao: description: Descrição da causa da rejeição. maxLength: 400 type: string required: - codigo - descricao type: object RecSolicitada: additionalProperties: false properties: atestacaoTitularidade: $ref: "#/components/schemas/RecAtestacaoTitularidadeDTO" description: Atestação de titularidade da conta do recebedor (obrigatória). ativacao: $ref: "#/components/schemas/RecAtivacaoSolicitadaDTO" description: Dados de ativação informáveis na criação (apenas dadosJornada.txid, para a JORNADA_3). calendario: $ref: "#/components/schemas/RecCalendarioDTO" description: Cadência da recorrência. loc: description: Id da location (locrec) a vincular à recorrência. format: int64 minimum: 1 type: integer politicaRetentativa: description: Política de retentativa. enum: - NAO_PERMITE - PERMITE_3R_7D examples: - PERMITE_3R_7D type: string recebedor: $ref: "#/components/schemas/RecRecebedorDTO" description: "Recebedor: conta bancária + identidade (cnpj/nome)." valor: $ref: "#/components/schemas/RecValorDTO" description: Valor da recorrência (opcional; fixo ou piso). vinculo: $ref: "#/components/schemas/RecVinculoDTO" description: Vínculo (contrato + devedor). required: - vinculo - calendario - recebedor - politicaRetentativa - atestacaoTitularidade type: object RecValorDTO: additionalProperties: false properties: valorMinimoRecebedor: description: Piso do recebedor (mutuamente exclusivo com valorRec). pattern: ^\d{1,10}\.\d{2}$ type: string valorRec: description: Valor fixo da recorrência. examples: - "99.90" pattern: ^\d{1,10}\.\d{2}$ type: string type: object RecVinculoDTO: additionalProperties: false properties: contrato: description: Identificador do contrato/pedido. examples: - contrato-12345 maxLength: 35 type: string devedor: $ref: "#/components/schemas/RecDevedorDTO" description: Devedor da recorrência (PF/PJ). objeto: description: Descrição livre do objeto da recorrência. maxLength: 35 type: string required: - contrato - devedor type: object RecebedorDTO: additionalProperties: false properties: cep: description: CEP do recebedor. maxLength: 8 type: string cidade: description: Cidade do recebedor. maxLength: 200 type: string cnpj: description: CNPJ do recebedor (PJ). type: string cpf: description: CPF do recebedor (PF). type: string logradouro: description: Logradouro do recebedor. maxLength: 200 type: string nome: description: Nome/razão social do recebedor. maxLength: 200 type: string nomeFantasia: description: Nome fantasia do recebedor. maxLength: 200 type: string uf: description: UF do recebedor. maxLength: 2 type: string type: object RecebedorProfileDTO: additionalProperties: false properties: cep: description: CEP do recebedor. maxLength: 8 type: string cidade: description: Cidade do recebedor. maxLength: 200 type: string cnpj: description: CNPJ do recebedor (PJ). type: string cpf: description: CPF do recebedor (PF). type: string ispbParticipante: description: ISPB (8 dígitos ou letras maiúsculas) do participante que atende este recebedor. type: string logradouro: description: Logradouro do recebedor. maxLength: 200 type: string nome: description: Nome/razão social do recebedor. maxLength: 200 type: string nomeFantasia: description: Nome fantasia do recebedor. maxLength: 200 type: string uf: description: UF do recebedor. maxLength: 2 type: string required: - ispbParticipante type: object RecebedorProfileRequest: additionalProperties: false properties: cep: description: CEP do recebedor (8 dígitos). examples: - "01310100" maxLength: 8 type: string cidade: description: Cidade do recebedor. examples: - São Paulo maxLength: 200 type: string cnpj: description: CNPJ do recebedor (PJ). Mutuamente exclusivo com cpf. examples: - 12ABC34501DE35 type: string cpf: description: CPF do recebedor (PF). Mutuamente exclusivo com cnpj. examples: - "12345678901" type: string ispbParticipante: description: ISPB (8 dígitos ou letras maiúsculas) de um participante liquidado por este rail que atende este recebedor. examples: - "12345678" type: string logradouro: description: Logradouro do recebedor. examples: - Av. Paulista, 1000 maxLength: 200 type: string nome: description: Nome/razão social do recebedor. examples: - Lerian Studio LTDA maxLength: 200 type: string nomeFantasia: description: Nome fantasia do recebedor (PJ). examples: - Lerian maxLength: 200 type: string uf: description: UF do recebedor (2 caracteres). examples: - SP maxLength: 2 type: string required: - nome - logradouro - cidade - uf - cep - ispbParticipante type: object ReconcileChargeRequest: additionalProperties: false properties: cnpj: description: Recebedor qualifier (CNPJ), required only when txId is shared by more than one recebedor. examples: - 12ABC34501DE35 pattern: ^[0-9A-Z]{14}$ type: string cpf: description: Recebedor qualifier (CPF), required only when txId is shared by more than one recebedor. examples: - "12345678901" pattern: ^\d{11}$ type: string endToEndId: description: "End-to-end id of the settled Pix, read off the receipt being reconciled. Obligatory: a conclusion that names no payment cannot appear on the Febraban settlement statement, whose record identity is this id." examples: - E46026562202608201345ABCDEF12345 pattern: ^E[0-9A-Z]{8}\d{12}[a-zA-Z0-9]{11}$ type: string txId: description: Transaction identifier of the charge to mark as paid, shaped as BACEN's TxIdType ([a-zA-Z0-9]{1,35}). It accepts the 1..35 form, not only the 26..35 form a cobrança is created with. examples: - txid-cobv-001 pattern: ^[a-zA-Z0-9]{1,35}$ type: string valor: description: Amount that settled, in BRL as a decimal string with scale 2, as shown on the receipt. Shaped as BACEN's monetary pattern \d{1,10}\.\d{2}, with a dot separator and no thousands separator. The service checks the 0.01..9999999999.99 range. Recorded verbatim and never compared against the charge amount (any-value Pix concludes a charge). examples: - "199.90" pattern: ^[0-9]{1,10}\.[0-9]{2}$ type: string required: - txId - endToEndId - valor type: object RecsConsultadas: additionalProperties: false properties: parametros: $ref: "#/components/schemas/Parametros" recs: items: $ref: "#/components/schemas/RecCompletaPesquisada" type: array required: - parametros - recs type: object ResolveBRCodeHumaInputBody: additionalProperties: false properties: codMun: description: "cobv only: the payer's IBGE municipality code. Omit only when the account type gives the PSP no address." pattern: ^[0-9]{7}$ type: string dpp: description: "cobv only: intended payment date (YYYY-MM-DD). Omitted, the receiver assumes the due date, or today once overdue." format: date type: string raw: description: The scanned BR Code (or Pix Copia e Cola) of a dynamic QR. minLength: 1 type: string required: - raw type: object Retirada: additionalProperties: false properties: saque: $ref: "#/components/schemas/SaqueTroco" description: Informações de saque (Pix Saque). troco: $ref: "#/components/schemas/SaqueTroco" description: Informações de troco (Pix Troco). type: object SaqueTroco: additionalProperties: false properties: modalidadeAgente: description: AGTEC | AGTOT | AGPSS (saque) / AGTEC | AGTOT (troco). examples: - AGPSS type: string modalidadeAlteracao: description: 0 (padrão) ou 1. format: int64 maximum: 1 minimum: 0 type: integer prestadorDoServicoDeSaque: description: ISPB do facilitador de serviço de saque. examples: - "12345678" pattern: ^[0-9A-Z]{8}$ type: string valor: description: Valor do saque/troco. examples: - "5.00" pattern: ^\d{1,10}\.\d{2}$ type: string required: - valor - modalidadeAgente - prestadorDoServicoDeSaque type: object SolicRecAtualizacaoDTO: additionalProperties: false properties: data: description: Instante da atualização (RFC 3339). type: string status: description: Status da solicitação no instante. enum: - CRIADA - ENVIADA - RECEBIDA - REJEITADA - ACEITA - EXPIRADA - CANCELADA type: string required: - status - data type: object SolicRecBody: additionalProperties: false properties: calendario: $ref: "#/components/schemas/SolicRecCalendarioDTO" description: Calendário da solicitação. destinatario: $ref: "#/components/schemas/SolicRecDestinatarioDTO" description: Destinatário (conta + participante, CPF ou CNPJ). idRec: description: Identificador da recorrência (Rec) a confirmar. examples: - RN123456782024011577825445612 pattern: ^[a-zA-Z0-9]{29}$ type: string required: - idRec - calendario - destinatario type: object SolicRecBodyRevisada: additionalProperties: false properties: status: description: Status alvo da revisão (apenas CANCELADA). enum: - CANCELADA examples: - CANCELADA type: string required: - status type: object SolicRecCalendarioDTO: additionalProperties: false properties: dataExpiracaoSolicitacao: description: Data de expiração da solicitação enviada ao pagador (RFC 3339). examples: - "2023-12-20T12:17:11Z" format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$ type: string required: - dataExpiracaoSolicitacao type: object SolicRecCompleta: additionalProperties: false properties: atualizacao: items: $ref: "#/components/schemas/SolicRecAtualizacaoDTO" type: array calendario: $ref: "#/components/schemas/SolicRecCalendarioDTO" destinatario: $ref: "#/components/schemas/SolicRecDestinatarioDTO" idRec: pattern: ^[a-zA-Z0-9]{29}$ type: string idSolicRec: description: Identificador da solicitação. pattern: ^[a-zA-Z0-9]{29}$ type: string recPayload: $ref: "#/components/schemas/RecPayloadDTO" status: enum: - CRIADA - ENVIADA - RECEBIDA - REJEITADA - ACEITA - EXPIRADA - CANCELADA type: string required: - idSolicRec - idRec - calendario - destinatario - status - atualizacao type: object SolicRecDestinatarioDTO: additionalProperties: false properties: agencia: description: Agência do destinatário. examples: - "2569" maxLength: 4 type: string cnpj: description: CNPJ do destinatário (PJ). Mutuamente exclusivo com cpf. pattern: ^[0-9A-Z]{14}$ type: string conta: description: Conta do destinatário. examples: - "550689" maxLength: 20 type: string cpf: description: CPF do destinatário (PF). Mutuamente exclusivo com cnpj. examples: - "15231470190" pattern: ^\d{11}$ type: string ispbParticipante: description: ISPB do participante destinatário. examples: - "91193552" pattern: ^[0-9A-Z]{8}$ type: string required: - conta - ispbParticipante type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object ValidateBRCodeRequest: additionalProperties: false properties: raw: description: Raw EMV BR Code copy-paste string to validate without returning decoded data. Same Lerian-own 512-character accept ceiling as the decode surface. examples: - 00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-44665544000052040000530398654041.005802BR5913Lerian Studio6009Sao Paulo62070503***6304ABCD maxLength: 512 minLength: 1 type: string required: - raw type: object ValidateBRCodeResponse: additionalProperties: false properties: code: description: EMV validation error code when invalid (empty when valid). examples: - BRC-EMV-0009 type: string message: description: Human-readable validation failure reason when invalid (empty when valid). examples: - CRC checksum does not match payload type: string valid: description: True when the raw payload passed EMV structural and CRC validation; false otherwise. examples: - true type: boolean required: - valid type: object ValorPercModalidade: additionalProperties: false properties: modalidade: description: Modalidade do componente, conforme tabela de domínios. format: int64 type: integer valorPerc: description: Valor absoluto ou percentual conforme modalidade. pattern: ^\d{1,10}\.\d{2}$ type: string required: - modalidade - valorPerc type: object ViolacaoDTO: additionalProperties: false properties: propriedade: description: Propriedade que originou a violação. type: string razao: description: Descrição da violação. type: string valor: description: Valor que originou a violação. type: string type: object Withdrawal: additionalProperties: false properties: saque: $ref: "#/components/schemas/WithdrawalLeg" troco: $ref: "#/components/schemas/WithdrawalLeg" type: object WithdrawalLeg: additionalProperties: false properties: modalidadeAgente: type: string modalidadeAlteracao: format: int64 type: integer prestadorDoServicoDeSaque: type: string valor: type: string required: - valor type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http info: contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio description: BR Code service for QR code generation and decoding (EMV QRCPS-MPM). license: name: Lerian Studio General License title: Lerian SPI — BR Code API version: 1.0.0 openapi: 3.1.0 paths: /api/v1/brcode/: get: description: Returns a paginated list of BR Code payloads. operationId: listBRCodePayloads parameters: - description: Page size (default 25, max 100) explode: false in: query name: limit schema: default: 25 description: Page size (default 25, max 100) format: int64 maximum: 100 minimum: 1 type: integer - description: Page offset (default 0) explode: false in: query name: offset schema: default: 0 description: Page offset (default 0) format: int64 minimum: 0 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListPayloadsResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List BR Code payloads tags: - BRCode x-mint: href: /pt/reference/rails/spi/brcode/list-br-code-payloads post: description: 'Prerequisite: for a dynamic QR, the cob/cobv charge must be created first (see putCob, putCobV) — the payload links to it by txid/locator. Generates a new BR Code (QR code) payload following the EMV QRCPS-MPM standard.' operationId: generateBRCode parameters: - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/GenerateBRCodeRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/PayloadResponse" description: Created links: prerequisite: description: "Charge prerequisite: for a dynamic QR the cob/cobv charge (putCob, putCobV) must exist before the payload references it." operationId: putCob "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Generate BR Code tags: - BRCode - charge x-mint: href: /pt/reference/rails/spi/brcode/generate-br-code /api/v1/brcode/.well-known/jwks.json: get: description: Publishes the recebedor PSP's JWK Set (RFC 7517). A payer PSP resolves the JWS verification key for a public cob/cobv/rec payload by matching the payload's JWS header kid to an entry kid here. Returns 404 when JOSE payload signing is not configured. operationId: getBRCodeJWKS responses: "200": content: application/json: schema: $ref: "#/components/schemas/JWKSet" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: BR Code payload JWK Set tags: - BRCode x-mint: href: /pt/reference/rails/spi/brcode/get-br-code-jwks /api/v1/brcode/arquivos/liquidacoes: get: description: "Downloads the settlement file (Febraban CNAB 750 collection return) for the Pix received by ONE recebedor within the requested window. Exactly one of cpf OR cnpj of the recebedor is required: a window with no recebedor would name all of them, and this file aggregates settlement PII. The window selects PAYMENTS, not charges: each Pix is reported in the file of the day on which IT settled, which is the date of its own DATA DO MOVIMENTO, so a second Pix on an already completed charge goes into the file of ITS day, not the day of the first payment. No line carries a movement outside the window, and windows that do not overlap never report the same payment twice. The file is built on demand, with no 'already reported' marker: the same window over the SAME DATA returns the same bytes, in the same order. A past window is not final: a settlement fact delivered late, with an instant inside the window, enters that window's file after the file was already downloaded. Reconcile by downloading the windows again; deduplication across overlapping windows is the client's, by endToEndId. An empty window is a valid file with no detail records (200), not a 404." operationId: downloadLiquidacoes parameters: - description: Primeiro dia da janela de liquidação (AAAA-MM-DD, inclusive). explode: false in: query name: de required: true schema: description: Primeiro dia da janela de liquidação (AAAA-MM-DD, inclusive). format: date type: string - description: Último dia da janela de liquidação (AAAA-MM-DD, inclusive). explode: false in: query name: ate required: true schema: description: Último dia da janela de liquidação (AAAA-MM-DD, inclusive). format: date type: string - description: CPF do recebedor cujas liquidações o extrato cobre, 11 dígitos sem pontuação. Obrigatório informar cpf OU cnpj (exatamente um). explode: false in: query name: cpf schema: description: CPF do recebedor cujas liquidações o extrato cobre, 11 dígitos sem pontuação. Obrigatório informar cpf OU cnpj (exatamente um). pattern: ^\d{11}$ type: string - description: CNPJ do recebedor cujas liquidações o extrato cobre, 14 caracteres sem pontuação (dígitos ou letras maiúsculas). Obrigatório informar cpf OU cnpj (exatamente um). explode: false in: query name: cnpj schema: description: CNPJ do recebedor cujas liquidações o extrato cobre, 14 caracteres sem pontuação (dígitos ou letras maiúsculas). Obrigatório informar cpf OU cnpj (exatamente um). pattern: ^[0-9A-Z]{14}$ type: string responses: "200": content: text/plain: {} description: Arquivo retorno CNAB 750 (texto plano, 750 posições por linha). headers: Content-Disposition: schema: type: string Content-Type: schema: type: string "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Download the CNAB 750 settlement file tags: - Charges x-mint: href: /pt/reference/rails/spi/brcode/download-liquidacoes /api/v1/brcode/arquivos/{id}: get: description: "Returns the status of a batch submitted through the file channel (ANEXO VI, CNAB 750) and the result of each record of the remessa. The submitted content is not projected: the remessa carries the debtor's document and name." operationId: getFileBatch parameters: - description: Identificador do lote (UUID) devolvido pelo upload. in: path name: id required: true schema: description: Identificador do lote (UUID) devolvido pelo upload. format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FileBatchDTO" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get file batch status tags: - Charges x-mint: href: /pt/reference/rails/spi/brcode/get-file-batch /api/v1/brcode/arquivos/{id}/retorno: get: description: "Downloads the batch's retorno file: the CNAB 750 receipt of what the rail did with each record of the remessa. It is served byte for byte as it was generated, never re-rendered, because a retorno already downloaded is the client's only proof. 404 when the batch does not exist; 409 while the batch has not produced a retorno." operationId: downloadFileBatchRetorno parameters: - description: Identificador do lote (UUID) devolvido pelo upload. in: path name: id required: true schema: description: Identificador do lote (UUID) devolvido pelo upload. format: uuid type: string responses: "200": content: text/plain: {} description: Arquivo retorno CNAB 750 (texto plano, 750 posições por linha). headers: Content-Disposition: schema: type: string Content-Type: schema: type: string "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Download the CNAB 750 retorno tags: - Charges x-mint: href: /pt/reference/rails/spi/brcode/download-file-batch-retorno /api/v1/brcode/charges/reconcile: post: description: "Admin-only endpoint that concludes a charge from a settlement receipt the rail could not attribute on its own. The receipt's endToEndId and valor are required." operationId: reconcileCharge requestBody: content: application/json: schema: $ref: "#/components/schemas/ReconcileChargeRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ChargeResponse" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Reconcile charge tags: - Charges x-mint: href: /pt/reference/rails/spi/brcode/reconcile-charge /api/v1/brcode/cob: get: description: Lists immediate charges by start date, end date, cpf, cnpj, locationPresente, and status. Pix API v2.9 GET /cob. operationId: listCob parameters: - description: Início do filtro de criação (RFC 3339). explode: false in: query name: inicio required: true schema: description: Início do filtro de criação (RFC 3339). format: date-time type: string - description: Fim do filtro de criação (RFC 3339). explode: false in: query name: fim required: true schema: description: Fim do filtro de criação (RFC 3339). format: date-time type: string - description: Filtro pelo CPF do devedor. explode: false in: query name: cpf schema: description: Filtro pelo CPF do devedor. pattern: ^\d{11}$ type: string - description: Filtro pelo CNPJ do devedor. explode: false in: query name: cnpj schema: description: Filtro pelo CNPJ do devedor. pattern: ^[0-9A-Z]{14}$ type: string - description: Filtro pela existência de location (true/false). explode: false in: query name: locationPresente schema: description: Filtro pela existência de location (true/false). type: string - description: Filtro pelo status do registro da cobrança. explode: false in: query name: status schema: description: Filtro pelo status do registro da cobrança. type: string - description: Página a ser retornada (0-based). explode: false in: query name: paginacao.paginaAtual schema: description: Página a ser retornada (0-based). format: int64 minimum: 0 type: integer - description: Itens por página (1..1000). explode: false in: query name: paginacao.itensPorPagina schema: description: Itens por página (1..1000). format: int64 maximum: 1000 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/CobsConsultadas" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List immediate charges tags: - Cob x-mint: href: /pt/reference/rails/spi/brcode/list-cob post: description: 'Prerequisite: create this charge before generating its QR/payload (see generateBRCode and resolveCobPayload). Creates an immediate charge (Cob) with a server-generated txid. Pix API v2.9 POST /cob.' operationId: postCob parameters: - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CobSolicitada" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CobGerada" description: Created "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create immediate charge (PSP-generated txid) tags: - Cob - charge x-mint: href: /pt/reference/rails/spi/brcode/post-cob /api/v1/brcode/cob/{txid}: get: description: Retrieves an immediate charge by its txid. Pix API v2.9 GET /cob/{txid}. operationId: getCob parameters: - description: Identificador da transação [a-zA-Z0-9]{26,35}. in: path name: txid required: true schema: description: Identificador da transação [a-zA-Z0-9]{26,35}. type: string - description: Qualificador do recebedor (CPF), necessário apenas quando o txid é usado por mais de um recebedor. explode: false in: query name: cpf schema: description: Qualificador do recebedor (CPF), necessário apenas quando o txid é usado por mais de um recebedor. pattern: ^\d{11}$ type: string - description: Qualificador do recebedor (CNPJ), necessário apenas quando o txid é usado por mais de um recebedor. explode: false in: query name: cnpj schema: description: Qualificador do recebedor (CNPJ), necessário apenas quando o txid é usado por mais de um recebedor. pattern: ^[0-9A-Z]{14}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CobCompleta" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Retrieve immediate charge tags: - Cob x-mint: href: /pt/reference/rails/spi/brcode/get-cob patch: description: Revises an immediate charge. status=REMOVIDA_PELO_USUARIO_RECEBEDOR removes the charge. Pix API v2.9 PATCH /cob/{txid}. operationId: patchCob parameters: - description: Identificador da transação [a-zA-Z0-9]{26,35}. in: path name: txid required: true schema: description: Identificador da transação [a-zA-Z0-9]{26,35}. type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CobRevisada" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CobGerada" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Revise immediate charge tags: - Cob x-mint: href: /pt/reference/rails/spi/brcode/patch-cob put: description: Creates an immediate charge (Cob) identified by the path txid (idempotent). Pix API v2.9 PUT /cob/{txid}. operationId: putCob parameters: - description: Identificador da transação [a-zA-Z0-9]{26,35}. in: path name: txid required: true schema: description: Identificador da transação [a-zA-Z0-9]{26,35}. type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CobSolicitada" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CobGerada" description: Created "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create immediate charge (idempotent txid) tags: - Cob - charge x-mint: href: /pt/reference/rails/spi/brcode/put-cob /api/v1/brcode/cobr: get: description: Lists recurring charges by start date, end date, idRec, and status. Pix API GET /cobr. operationId: listCobR parameters: - description: Início do filtro de criação (RFC 3339). explode: false in: query name: inicio required: true schema: description: Início do filtro de criação (RFC 3339). format: date-time type: string - description: Fim do filtro de criação (RFC 3339). explode: false in: query name: fim required: true schema: description: Fim do filtro de criação (RFC 3339). format: date-time type: string - description: Filtro pela recorrência. explode: false in: query name: idRec schema: description: Filtro pela recorrência. pattern: ^[a-zA-Z0-9]{29}$ type: string - description: Filtro pelo status da cobrança recorrente. explode: false in: query name: status schema: description: Filtro pelo status da cobrança recorrente. type: string - description: Página a ser retornada (0-based). explode: false in: query name: paginacao.paginaAtual schema: description: Página a ser retornada (0-based). format: int64 minimum: 0 type: integer - description: Itens por página (1..1000). explode: false in: query name: paginacao.itensPorPagina schema: description: Itens por página (1..1000). format: int64 maximum: 1000 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/CobsRConsultadas" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List recurring charges tags: - CobR x-mint: href: /pt/reference/rails/spi/brcode/list-cob-r post: description: Creates a recurring charge (CobR) with a server-generated txid. Pix API POST /cobr. operationId: postCobR parameters: - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CobRSolicitada" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CobRGerada" description: Created "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create recurring charge (PSP-generated txid) tags: - CobR x-mint: href: /pt/reference/rails/spi/brcode/post-cob-r /api/v1/brcode/cobr/{txid}: get: description: Retrieves a recurring charge by its txid. Pix API GET /cobr/{txid}. operationId: getCobR parameters: - description: Identificador da transação [a-zA-Z0-9]{26,35}. in: path name: txid required: true schema: description: Identificador da transação [a-zA-Z0-9]{26,35}. pattern: ^[a-zA-Z0-9]{26,35}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CobRCompleta" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Retrieve recurring charge tags: - CobR x-mint: href: /pt/reference/rails/spi/brcode/get-cob-r patch: description: Revises a recurring charge. status=CANCELADA cancels the charge (only before the first settlement attempt). Pix API PATCH /cobr/{txid}. operationId: patchCobR parameters: - description: Identificador da transação [a-zA-Z0-9]{26,35}. in: path name: txid required: true schema: description: Identificador da transação [a-zA-Z0-9]{26,35}. pattern: ^[a-zA-Z0-9]{26,35}$ type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CobRRevisada" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CobRGerada" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Revise recurring charge (cancel) tags: - CobR x-mint: href: /pt/reference/rails/spi/brcode/patch-cob-r put: description: Creates a recurring charge (CobR) identified by the path txid (idempotent). Pix API PUT /cobr/{txid}. operationId: putCobR parameters: - description: Identificador da transação [a-zA-Z0-9]{26,35}. in: path name: txid required: true schema: description: Identificador da transação [a-zA-Z0-9]{26,35}. pattern: ^[a-zA-Z0-9]{26,35}$ type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CobRSolicitada" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CobRGerada" description: Created "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create recurring charge (idempotent txid) tags: - CobR x-mint: href: /pt/reference/rails/spi/brcode/put-cob-r /api/v1/brcode/cobr/{txid}/retentativa/{data}: post: description: Requests a new settlement attempt for the given date. Requires the PERMITE_3R_7D policy. Pix API POST /cobr/{txid}/retentativa/{data}. operationId: postCobRRetentativa parameters: - description: Identificador da transação [a-zA-Z0-9]{26,35}. in: path name: txid required: true schema: description: Identificador da transação [a-zA-Z0-9]{26,35}. pattern: ^[a-zA-Z0-9]{26,35}$ type: string - description: Data prevista de liquidação da ordem de pagamento (YYYY-MM-DD). in: path name: data required: true schema: description: Data prevista de liquidação da ordem de pagamento (YYYY-MM-DD). pattern: ^\d{4}-\d{2}-\d{2}$ type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/CobRRetentativaCompleta" description: Created "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Request settlement retry tags: - CobR x-mint: href: /pt/reference/rails/spi/brcode/post-cob-r-retentativa /api/v1/brcode/cobv: get: description: Lists due-date charges by start date, end date, cpf, cnpj, locationPresente, status, and loteCobVId. Pix API v2.9 GET /cobv. operationId: listCobV parameters: - description: Início do filtro de criação (RFC 3339). explode: false in: query name: inicio required: true schema: description: Início do filtro de criação (RFC 3339). format: date-time type: string - description: Fim do filtro de criação (RFC 3339). explode: false in: query name: fim required: true schema: description: Fim do filtro de criação (RFC 3339). format: date-time type: string - description: Filtro pelo CPF do devedor. explode: false in: query name: cpf schema: description: Filtro pelo CPF do devedor. pattern: ^\d{11}$ type: string - description: Filtro pelo CNPJ do devedor. explode: false in: query name: cnpj schema: description: Filtro pelo CNPJ do devedor. pattern: ^[0-9A-Z]{14}$ type: string - description: Filtro pela existência de location (true/false). explode: false in: query name: locationPresente schema: description: Filtro pela existência de location (true/false). type: string - description: Filtro pelo status do registro da cobrança. explode: false in: query name: status schema: description: Filtro pelo status do registro da cobrança. type: string - description: Id do lote de cobrança com vencimento. explode: false in: query name: loteCobVId schema: description: Id do lote de cobrança com vencimento. format: int64 type: integer - description: Página a ser retornada (0-based). explode: false in: query name: paginacao.paginaAtual schema: description: Página a ser retornada (0-based). format: int64 minimum: 0 type: integer - description: Itens por página (1..1000). explode: false in: query name: paginacao.itensPorPagina schema: description: Itens por página (1..1000). format: int64 maximum: 1000 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/CobsVConsultadas" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List due-date charges tags: - CobV x-mint: href: /pt/reference/rails/spi/brcode/list-cob-v /api/v1/brcode/cobv/{txid}: get: description: Retrieves a due-date charge by its txid. Pix API v2.9 GET /cobv/{txid}. operationId: getCobV parameters: - description: Identificador da transação [a-zA-Z0-9]{26,35}. in: path name: txid required: true schema: description: Identificador da transação [a-zA-Z0-9]{26,35}. type: string - description: Qualificador do recebedor (CPF), necessário apenas quando o txid é usado por mais de um recebedor. explode: false in: query name: cpf schema: description: Qualificador do recebedor (CPF), necessário apenas quando o txid é usado por mais de um recebedor. pattern: ^\d{11}$ type: string - description: Qualificador do recebedor (CNPJ), necessário apenas quando o txid é usado por mais de um recebedor. explode: false in: query name: cnpj schema: description: Qualificador do recebedor (CNPJ), necessário apenas quando o txid é usado por mais de um recebedor. pattern: ^[0-9A-Z]{14}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CobVCompleta" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Retrieve due-date charge tags: - CobV x-mint: href: /pt/reference/rails/spi/brcode/get-cob-v patch: description: Revises a due-date charge. status=REMOVIDA_PELO_USUARIO_RECEBEDOR removes the charge. Pix API v2.9 PATCH /cobv/{txid}. operationId: patchCobV parameters: - description: Identificador da transação [a-zA-Z0-9]{26,35}. in: path name: txid required: true schema: description: Identificador da transação [a-zA-Z0-9]{26,35}. type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CobVRevisada" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CobVGerada" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Revise due-date charge tags: - CobV x-mint: href: /pt/reference/rails/spi/brcode/patch-cob-v put: description: 'Prerequisite: create this charge before generating its QR/payload (see generateBRCode and resolveCobVPayload). Creates a due-date charge (CobV) identified by the path txid (idempotent). Pix API v2.9 PUT /cobv/{txid}.' operationId: putCobV parameters: - description: Identificador da transação [a-zA-Z0-9]{26,35}. in: path name: txid required: true schema: description: Identificador da transação [a-zA-Z0-9]{26,35}. type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CobVSolicitada" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CobVGerada" description: Created "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create due-date charge (idempotent txid) tags: - CobV - charge x-mint: href: /pt/reference/rails/spi/brcode/put-cob-v /api/v1/brcode/decode: post: description: Decodes a raw BR Code string into its structured payload components. operationId: decodeBRCode requestBody: content: application/json: schema: $ref: "#/components/schemas/DecodeBRCodeRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/PayloadResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Decode BR Code tags: - BRCode x-mint: href: /pt/reference/rails/spi/brcode/decode-br-code /api/v1/brcode/info/{payload}: get: description: Returns structured metadata for a raw BR Code payload. operationId: getBRCodeInfo parameters: - description: Raw BR Code payload in: path name: payload required: true schema: description: Raw BR Code payload type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PayloadResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get BR Code info tags: - BRCode x-mint: href: /pt/reference/rails/spi/brcode/get-br-code-info /api/v1/brcode/loc: get: description: Lists locations by start date, end date, txIdPresente, and tipoCob. Pix API GET /loc. operationId: listLocation parameters: - description: Início do filtro de criação (RFC 3339). explode: false in: query name: inicio required: true schema: description: Início do filtro de criação (RFC 3339). format: date-time type: string - description: Fim do filtro de criação (RFC 3339). explode: false in: query name: fim required: true schema: description: Fim do filtro de criação (RFC 3339). format: date-time type: string - description: Filtra por locations com (ou sem) txid vinculado (true/false). explode: false in: query name: txIdPresente schema: description: Filtra por locations com (ou sem) txid vinculado (true/false). type: string - description: Filtra pelo tipo de cobrança. explode: false in: query name: tipoCob schema: description: Filtra pelo tipo de cobrança. enum: - cob - cobv type: string - description: Página a ser retornada (0-based). explode: false in: query name: paginacao.paginaAtual schema: description: Página a ser retornada (0-based). format: int64 minimum: 0 type: integer - description: Itens por página (1..1000). explode: false in: query name: paginacao.itensPorPagina schema: description: Itens por página (1..1000). format: int64 maximum: 1000 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/PayloadLocationConsultadas" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List locations tags: - Location x-mint: href: /pt/reference/rails/spi/brcode/list-location post: description: Creates a location (loc) for a cob- or cobv-type charge. Pix API POST /loc. operationId: createLocation parameters: - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/PayloadLocationSolicitada" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/PayloadLocation" description: Created headers: Location: schema: description: URI da location criada. type: string "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create payload location tags: - Location x-mint: href: /pt/reference/rails/spi/brcode/create-location /api/v1/brcode/loc/{id}: get: description: Retrieves a location by its id. Pix API GET /loc/{id}. operationId: getLocation parameters: - description: Id da location. in: path name: id required: true schema: description: Id da location. pattern: ^[0-9]+$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PayloadLocationCompleta" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Retrieve location tags: - Location x-mint: href: /pt/reference/rails/spi/brcode/get-location /api/v1/brcode/loc/{id}/txid: delete: description: Unlinks the charge (txid) from a location. The charge loses its location; the status remains unchanged. Pix API DELETE /loc/{id}/txid. operationId: deleteLocationTxID parameters: - description: Id da location. in: path name: id required: true schema: description: Id da location. pattern: ^[0-9]+$ type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PayloadLocationCompleta" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Unlink charge from a location tags: - Location x-mint: href: /pt/reference/rails/spi/brcode/delete-location-tx-id /api/v1/brcode/locrec: get: description: Lists recurrence locations by start date, end date, and idRecPresente. Pix API GET /locrec. operationId: listLocationRec parameters: - description: Início do filtro de criação (RFC 3339). explode: false in: query name: inicio required: true schema: description: Início do filtro de criação (RFC 3339). format: date-time type: string - description: Fim do filtro de criação (RFC 3339). explode: false in: query name: fim required: true schema: description: Fim do filtro de criação (RFC 3339). format: date-time type: string - description: Filtra por locations com (ou sem) idRec vinculado (true/false). explode: false in: query name: idRecPresente schema: description: Filtra por locations com (ou sem) idRec vinculado (true/false). type: string - description: Página a ser retornada (0-based). explode: false in: query name: paginacao.paginaAtual schema: description: Página a ser retornada (0-based). format: int64 minimum: 0 type: integer - description: Itens por página (1..1000). explode: false in: query name: paginacao.itensPorPagina schema: description: Itens por página (1..1000). format: int64 maximum: 1000 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/PayloadLocationRecConsultadas" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List recurrence locations tags: - Location x-mint: href: /pt/reference/rails/spi/brcode/list-location-rec post: description: Creates a recurrence location (locrec). The request has no body. Pix API POST /locrec. operationId: createLocationRec parameters: - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/PayloadLocationRecGerada" description: Created headers: Location: schema: description: URI da location de recorrência criada. type: string "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create recurrence location tags: - Location x-mint: href: /pt/reference/rails/spi/brcode/create-location-rec /api/v1/brcode/locrec/{id}: get: description: Retrieves a recurrence location by its id. Pix API GET /locrec/{id}. operationId: getLocationRec parameters: - description: Id da location de recorrência. in: path name: id required: true schema: description: Id da location de recorrência. pattern: ^[0-9]+$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PayloadLocationRecCompleta" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Retrieve recurrence location tags: - Location x-mint: href: /pt/reference/rails/spi/brcode/get-location-rec /api/v1/brcode/locrec/{id}/idRec: delete: description: Unlinks the recurrence (idRec) from a recurrence location. Pix API DELETE /locrec/{id}/idRec. operationId: deleteLocationRecIdRec parameters: - description: Id da location de recorrência. in: path name: id required: true schema: description: Id da location de recorrência. pattern: ^[0-9]+$ type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PayloadLocationRecCompleta" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Unlink recurrence from a location tags: - Location x-mint: href: /pt/reference/rails/spi/brcode/delete-location-rec-id-rec /api/v1/brcode/lotecobv: get: description: Lists due-date charge batches by start date and end date. Pix API GET /lotecobv. operationId: listLoteCobV parameters: - description: Início do filtro de criação (RFC 3339). explode: false in: query name: inicio required: true schema: description: Início do filtro de criação (RFC 3339). format: date-time type: string - description: Fim do filtro de criação (RFC 3339). explode: false in: query name: fim required: true schema: description: Fim do filtro de criação (RFC 3339). format: date-time type: string - description: Página a ser retornada (0-based). explode: false in: query name: paginacao.paginaAtual schema: description: Página a ser retornada (0-based). format: int64 minimum: 0 type: integer - description: Itens por página (1..1000). explode: false in: query name: paginacao.itensPorPagina schema: description: Itens por página (1..1000). format: int64 maximum: 1000 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/LotesCobVConsultados" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List due-date charge batches tags: - LoteCobV x-mint: href: /pt/reference/rails/spi/brcode/list-lote-cob-v /api/v1/brcode/lotecobv/{id}: get: description: Retrieves a due-date charge batch by its id. Pix API GET /lotecobv/{id}. operationId: getLoteCobV parameters: - description: Identificador do lote (texto). in: path name: id required: true schema: description: Identificador do lote (texto). pattern: ^[A-Za-z0-9-]{1,35}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/LoteCobVConsultado" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Retrieve due-date charge batch tags: - LoteCobV x-mint: href: /pt/reference/rails/spi/brcode/get-lote-cob-v patch: description: Revises specific charges within a batch. The cobsv array may contain fewer items than the originating batch, but it cannot add or remove charges. Pix API PATCH /lotecobv/{id}. operationId: patchLoteCobV parameters: - description: Identificador do lote (texto). in: path name: id required: true schema: description: Identificador do lote (texto). pattern: ^[A-Za-z0-9-]{1,35}$ type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LoteCobVBodyRevisado" required: true responses: "202": description: Accepted "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Revise due-date charge batch tags: - LoteCobV x-mint: href: /pt/reference/rails/spi/brcode/patch-lote-cob-v put: description: 'Prerequisite: create the batch charges before generating their QR/payloads (see generateBRCode and resolveCobVPayload). Creates a due-date charge batch identified by the path id. Items are processed synchronously: each results in CRIADA or NEGADA. Pix API PUT /lotecobv/{id}.' operationId: putLoteCobV parameters: - description: Identificador do lote (texto). in: path name: id required: true schema: description: Identificador do lote (texto). pattern: ^[A-Za-z0-9-]{1,35}$ type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/LoteCobVBody" required: true responses: "202": description: Accepted "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create due-date charge batch tags: - LoteCobV - charge x-mint: href: /pt/reference/rails/spi/brcode/put-lote-cob-v /api/v1/brcode/payload/cobv/{locator}: get: description: "Resolves, by the opaque access token, the signed JSON payload (JWS, application/jose) of a due-date charge (CobVPayload). valor.final is calculated (fine/interest/rebate/discount) for the expected payment date (DPP). The verification key is published at /.well-known/jwks.json." operationId: resolveCobVPayload parameters: - description: Token de acesso opaco do payload (capability URL). in: path name: locator required: true schema: description: Token de acesso opaco do payload (capability URL). type: string - description: "Data de pagamento prevista (YYYY-MM-DD) para o cálculo do valor final. Deve estar entre o dia corrente (calendário brasileiro) e o último dia pagável da cobrança (calendario.dataDeVencimento prorrogado + calendario.validadeAposVencimento); uma data anterior ao momento presente ou superior à validade da cobrança é recusada com 400 (CobPayloadOperacaoInvalida)." explode: false in: query name: DPP schema: description: "Data de pagamento prevista (YYYY-MM-DD) para o cálculo do valor final. Deve estar entre o dia corrente (calendário brasileiro) e o último dia pagável da cobrança (calendario.dataDeVencimento prorrogado + calendario.validadeAposVencimento); uma data anterior ao momento presente ou superior à validade da cobrança é recusada com 400 (CobPayloadOperacaoInvalida)." type: string - description: "Código IBGE (7 dígitos) do município do pagador, usado para os feriados estaduais e municipais que deslocam o vencimento e a contagem de juros/multa/desconto. Os dois primeiros dígitos são o código da UF, que é um conjunto fechado (11-17, 21-29, 31-33, 35, 41-43, 50-53); um prefixo fora dele não é município algum e é recusado aqui. Ausente: assume-se que não há feriados estaduais/municipais no período." explode: false in: query name: codMun schema: description: "Código IBGE (7 dígitos) do município do pagador, usado para os feriados estaduais e municipais que deslocam o vencimento e a contagem de juros/multa/desconto. Os dois primeiros dígitos são o código da UF, que é um conjunto fechado (11-17, 21-29, 31-33, 35, 41-43, 50-53); um prefixo fora dele não é município algum e é recusado aqui. Ausente: assume-se que não há feriados estaduais/municipais no período." pattern: ^(1[1-7]|2[1-9]|3[1235]|4[1-3]|5[0-3])[0-9]{5}$ type: string responses: "200": content: application/jose: {} description: Compact JWS (RFC 7515) signed payload. headers: Content-Type: schema: type: string "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: [] summary: Resolve CobV payload (JWS) tags: - CobVPayload x-mint: href: /pt/reference/rails/spi/brcode/resolve-cob-v-payload /api/v1/brcode/payload/rec/{recUrlAccessToken}: get: description: Resolves, by the opaque access token of the recurrence location (recUrlAccessToken), the signed JSON payload (JWS, application/jose) of a recurrence (RecPayload). The recurrence configuration is projected verbatim. A terminal recurrence (REJEITADA/EXPIRADA/CANCELADA) returns 410 Gone (location permanently exhausted). The verification key is published at /.well-known/jwks.json. operationId: resolveRecPayload parameters: - description: Token de acesso opaco da location de recorrência (capability URL). in: path name: recUrlAccessToken required: true schema: description: Token de acesso opaco da location de recorrência (capability URL). type: string responses: "200": content: application/jose: {} description: Compact JWS (RFC 7515) signed payload. headers: Content-Type: schema: type: string "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "410": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gone "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: [] summary: Resolve Rec payload (JWS) tags: - RecPayload x-mint: href: /pt/reference/rails/spi/brcode/resolve-rec-payload /api/v1/brcode/payload/{locator}: get: description: 'Prerequisite: the referenced Cob charge must already exist (see postCob). Resolves, by the opaque access token, the signed JSON payload (JWS, application/jose) of an immediate charge (CobPayload). valor.original is projected verbatim. The verification key is published at /.well-known/jwks.json.' operationId: resolveCobPayload parameters: - description: Token de acesso opaco do payload (capability URL). in: path name: locator required: true schema: description: Token de acesso opaco do payload (capability URL). type: string responses: "200": content: application/jose: {} description: Compact JWS (RFC 7515) signed payload. headers: Content-Type: schema: type: string "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: [] summary: Resolve Cob payload (JWS) tags: - CobPayload - charge x-mint: href: /pt/reference/rails/spi/brcode/resolve-cob-payload /api/v1/brcode/rec: get: description: Lists recurrences by start date, end date, cpf, cnpj, convênio, and status. Pix API GET /rec. operationId: listRec parameters: - description: Início do filtro de criação (RFC 3339). explode: false in: query name: inicio required: true schema: description: Início do filtro de criação (RFC 3339). format: date-time type: string - description: Fim do filtro de criação (RFC 3339). explode: false in: query name: fim required: true schema: description: Fim do filtro de criação (RFC 3339). format: date-time type: string - description: Filtro pelo CPF do devedor. Mutuamente exclusivo com cnpj. explode: false in: query name: cpf schema: description: Filtro pelo CPF do devedor. Mutuamente exclusivo com cnpj. pattern: ^\d{11}$ type: string - description: Filtro pelo CNPJ do devedor. Mutuamente exclusivo com cpf. explode: false in: query name: cnpj schema: description: Filtro pelo CNPJ do devedor. Mutuamente exclusivo com cpf. pattern: ^[0-9A-Z]{14}$ type: string - description: Filtro pelo convênio associado. explode: false in: query name: convenio schema: description: Filtro pelo convênio associado. maxLength: 60 type: string - description: Filtro pelo status da recorrência. explode: false in: query name: status schema: description: Filtro pelo status da recorrência. type: string - description: Página a ser retornada (0-based). explode: false in: query name: paginacao.paginaAtual schema: description: Página a ser retornada (0-based). format: int64 minimum: 0 type: integer - description: Itens por página (1..1000). explode: false in: query name: paginacao.itensPorPagina schema: description: Itens por página (1..1000). format: int64 maximum: 1000 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecsConsultadas" description: OK "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: List recurrences (Pix Automático) tags: - Rec x-mint: href: /pt/reference/rails/spi/brcode/list-rec post: description: Creates a recebedor-side recurrence (Rec) with a server-generated idRec. Pix API POST /rec. operationId: postRec parameters: - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RecSolicitada" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/RecGerada" description: Created "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create recurrence (Pix Automático) tags: - Rec x-mint: href: /pt/reference/rails/spi/brcode/post-rec /api/v1/brcode/rec/{idRec}: get: description: Retrieves a recurrence by its idRec. Pix API GET /rec/{idRec}. Projects the stored Rec fields verbatim, including recebedor.convenio. An unknown idRec returns 404 (canonical Problem envelope). operationId: getRec parameters: - description: Identificador da recorrência [a-zA-Z0-9]{29}. in: path name: idRec required: true schema: description: Identificador da recorrência [a-zA-Z0-9]{29}. pattern: ^[a-zA-Z0-9]{29}$ type: string - description: "txid de uma cobrança a compor com a recorrência (JORNADA_3/4). NÃO SERVIDO nesta superfície: informar txid resulta em 422." explode: false in: query name: txid schema: description: "txid de uma cobrança a compor com a recorrência (JORNADA_3/4). NÃO SERVIDO nesta superfície: informar txid resulta em 422." pattern: ^[a-zA-Z0-9]{26,35}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecCompleta" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Retrieve recurrence (Pix Automático) tags: - Rec x-mint: href: /pt/reference/rails/spi/brcode/get-rec patch: description: 'Partially revises a recurrence (Rec) by its idRec: changes calendario.dataInicial and ativacao.dadosJornada.txid (only while status == CRIADA), vinculo.devedor.nome and loc (links a locrec; both can change after confirmation too), and/or the status (CANCELADA cancels the mandate). Pix API PATCH /rec/{idRec}. Rejects any change when the recurrence is EXPIRADA/CANCELADA/REJEITADA (422). An unknown idRec returns 404 (canonical Problem envelope).' operationId: patchRec parameters: - description: Identificador da recorrência [a-zA-Z0-9]{29}. in: path name: idRec required: true schema: description: Identificador da recorrência [a-zA-Z0-9]{29}. pattern: ^[a-zA-Z0-9]{29}$ type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RecPatch" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecGerada" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Revise recurrence (Pix Automático) tags: - Rec x-mint: href: /pt/reference/rails/spi/brcode/patch-rec /api/v1/brcode/recebedores/{chave}: get: description: Returns the FI-registered recebedor identity for a Pix key, or 404 when no profile is registered. operationId: getRecebedorProfile parameters: - description: Chave Pix (DICT) do recebedor, percent-encoded; até 77 caracteres após a decodificação. in: path name: chave required: true schema: description: Chave Pix (DICT) do recebedor, percent-encoded; até 77 caracteres após a decodificação. maxLength: 231 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecebedorProfileDTO" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get recebedor profile tags: - Charges x-mint: href: /pt/reference/rails/spi/brcode/get-recebedor-profile put: description: "FI-admin surface (not a BACEN endpoint): upsert the FI-registered recebedor identity for a Pix key. CobV responses require a recebedor with a postal address (DadosRecebedor), which DICT cannot supply; the FI registers it here. Idempotent by nature." operationId: upsertRecebedorProfile parameters: - description: Chave Pix (DICT) do recebedor, percent-encoded; até 77 caracteres após a decodificação. in: path name: chave required: true schema: description: Chave Pix (DICT) do recebedor, percent-encoded; até 77 caracteres após a decodificação. maxLength: 231 type: string - description: Idempotency key, max 255 characters in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RecebedorProfileRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecebedorProfileDTO" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Register recebedor profile tags: - Charges x-mint: href: /pt/reference/rails/spi/brcode/upsert-recebedor-profile /api/v1/brcode/resolve: post: description: "Fetches the payload at the dynamic QR's location over HTTPS and returns the charge only after the site certificate is on the BC list of authorised QR certificates (certqrc), is EV and unrevoked, the JWS signing certificate chain is valid and unrevoked, and the signature verifies. 422: the QR is invalid or not dynamic, its location is not an acceptable HTTPS URL, the receiver refused the request (charge gone, codMun/DPP refused), the signed payload does not follow the API Pix layout, or the charge cannot take a payment (status other than ATIVA, or a cob past calendario.expiracao; the detail names which). 502: the receiver gave no verdict: the location, its JWK Set or a revocation status could not be read (unreachable, 5xx, or a receiver that throttled, timed out or blocked the request: 401, 403, 408, 429), the caller's X-Caller-Budget-Ms ran out, or the site certificate, the signing certificate or the signature fails the checks above. 503: the feature is off or the certificate list is unreadable." operationId: resolveBRCode parameters: - description: Milliseconds the whole resolve may take (location, JWK Set and revocation reads); once spent, the route answers 502 (no verdict). Omitted, each fetch is bounded at 5 s. in: header name: X-Caller-Budget-Ms schema: description: Milliseconds the whole resolve may take (location, JWK Set and revocation reads); once spent, the route answers 502 (no verdict). Omitted, each fetch is bounded at 5 s. format: int64 maximum: 15000 minimum: 100 type: integer requestBody: content: application/json: schema: $ref: "#/components/schemas/ResolveBRCodeHumaInputBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/Payload" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Resolve a dynamic BR Code (payer side) tags: - BRCode x-mint: href: /pt/reference/rails/spi/brcode/resolve-a-dynamic-br-code-payer-side /api/v1/brcode/solicrec: post: description: "Creates a recurrence confirmation request (SolicRec) with a server-generated idSolicRec. Pix API POST /solicrec. The rail sends the request to the payer's PSP (pain.009) asynchronously. It stays CRIADA until it is sent, becomes ENVIADA when BACEN accepts the message and RECEBIDA when the payer's PSP confirms receipt, then ACEITA or REJEITADA by the payer's answer." operationId: postSolicRec parameters: - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SolicRecBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/SolicRecCompleta" description: Created "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Create recurrence request (Pix Automático) tags: - SolicRec x-mint: href: /pt/reference/rails/spi/brcode/post-solic-rec /api/v1/brcode/solicrec/{idSolicRec}: get: description: "Retrieves a request by its idSolicRec. Pix API GET /solicrec/{idSolicRec}. Projects the stored fields verbatim. An unknown idSolicRec returns 404 (canonical Problem envelope)." operationId: getSolicRec parameters: - description: Identificador da solicitação [a-zA-Z0-9]{29}. in: path name: idSolicRec required: true schema: description: Identificador da solicitação [a-zA-Z0-9]{29}. pattern: ^[a-zA-Z0-9]{29}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SolicRecCompleta" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Retrieve recurrence request (Pix Automático) tags: - SolicRec x-mint: href: /pt/reference/rails/spi/brcode/get-solic-rec patch: description: Cancels a request by its idSolicRec (target status CANCELADA). Pix API PATCH /solicrec/{idSolicRec}. operationId: patchSolicRec parameters: - description: Identificador da solicitação [a-zA-Z0-9]{29}. in: path name: idSolicRec required: true schema: description: Identificador da solicitação [a-zA-Z0-9]{29}. pattern: ^[a-zA-Z0-9]{29}$ type: string - description: Idempotency key, max 255 characters. in: header name: X-Idempotency required: true schema: description: Idempotency key, max 255 characters. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SolicRecBodyRevisada" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/SolicRecCompleta" description: Created "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Revise (cancel) recurrence request (Pix Automático) tags: - SolicRec x-mint: href: /pt/reference/rails/spi/brcode/patch-solic-rec /api/v1/brcode/validate: post: description: "Validates a raw BR Code payload and returns stable EMV validation codes." operationId: validateBRCode requestBody: content: application/json: schema: $ref: "#/components/schemas/ValidateBRCodeRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ValidateBRCodeResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Validate BR Code tags: - BRCode x-mint: href: /pt/reference/rails/spi/brcode/validate-br-code /api/v1/brcode/{id}: get: description: Retrieves a single BR Code payload by its UUID. operationId: getBRCodePayload parameters: - description: Payload UUID in: path name: id required: true schema: description: Payload UUID format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PayloadResponse" description: OK "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error security: - BearerAuth: [] summary: Get BR Code payload tags: - BRCode x-mint: href: /pt/reference/rails/spi/brcode/get-br-code-payload servers: - url: https://api.example.com description: Replace the example host with the URL provided during environment onboarding. tags: - description: EMV BR Code payload generation, decoding, validation, info, and lookup. name: BRCode - description: "Pix charges (Cob/CobV/LoteCobV): create, retrieve by TxID, list, cancel, reconcile, and resolve public payloads." name: Charges - description: "Flow (mandatory order): create cob/cobv → generate QR/payload. A dynamic BR Code payload references a charge, so the cob/cobv charge MUST be created first; the payload links to it by txid/locator." name: charge