{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-cobs-rconsultadas-schema.json", "title": "Cobranças recorrentes consultadas", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/citi-cobr-api-openapi.yml#/components/schemas/CobsRConsultadas", "type": "object", "required": [ "parametros", "cobsr" ], "properties": { "parametros": { "$ref": "#/$defs/ParametrosConsultaCobR" }, "cobsr": { "type": "array", "title": "Lista de cobranças", "items": { "allOf": [ { "$ref": "#/$defs/CobRCompleta" } ] } } }, "$defs": { "CobRAtualizacao": { "type": "object", "title": "Histórico de Atualização da Cobrança Recorrente", "required": [ "atualizacao" ], "properties": { "atualizacao": { "type": "array", "title": "Histórico de Status", "description": "Histórico das mudanças de status das cobranças recorrentes.", "items": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "title": "Status da cobrança", "description": "Status da cobrança.", "enum": [ "CRIADA", "ATIVA", "CONCLUIDA", "EXPIRADA", "REJEITADA", "CANCELADA" ] }, "data": { "type": "string", "format": "date-time", "description": "Data e hora do registro de status atualizado. Respeita RFC 3339." } } } }, "encerramento": { "type": "object", "title": "Detalhamento do encerramento da cobrança.", "oneOf": [ { "type": "object", "properties": { "cancelamento": { "type": "object", "title": "Informações sobre o cancelamento da cobrança", "required": [ "solicitante", "codigo", "descricao" ], "description": "Informações sobre o cancelamento da cobrança", "properties": { "solicitante": { "type": "string", "title": "Solicitante do cancelamento", "enum": [ "PSP_PAGADOR", "USUARIO_PAGADOR", "PSP_RECEBEDOR", "USUARIO_RECEBEDOR" ] }, "codigo": { "type": "string", "title": "Código do cancelamento", "description": "Código do cancelamento. Corresponde ao código de cancelamento presente no catálogo de mensagens.", "maxLength": 4, "enum": [ "ACCT", "BLCK", "CCLD", "FAIL", "OTHR", "SLBD", "SLCR" ] }, "descricao": { "type": "string", "title": "Descricao do cancelamento", "description": "Descricao da causa do cancelamento", "maxLength": 105 } } } } }, { "type": "object", "properties": { "rejeicao": { "type": "object", "title": "Informações sobre a rejeição da cobrança", "required": [ "codigo", "descricao" ], "description": "Informações sobre a rejeição da cobrança", "properties": { "codigo": { "type": "string", "title": "Código da rejeição", "description": "Código da rejeição. Corresponde ao código de rejeição presente no catálogo de mensagens.", "maxLength": 4, "enum": [ "AB10", "AC05", "AC06", "AM02", "AM09", "DENC", "DS27", "DTED", "DTNT", "FBRD", "IRNT", "MIDI", "MSUC", "NIEC", "NIPA", "NITX", "QUNT", "RC09", "UDEI" ] }, "descricao": { "type": "string", "title": "Descricao da rejeição", "description": "Descricao da causa da rejeição", "maxLength": 105 } } } } } ] } } }, "CobRBase": { "type": "object", "title": "Cobrança Recorrente Base", "required": [ "ajusteDiaUtil" ], "description": "Atributos de cobrança recorrente", "properties": { "infoAdicional": { "type": "string", "title": "Informações adicionais da fatura.", "description": "Informações adicionais da fatura.", "minLength": 1, "maxLength": 140 }, "calendario": { "type": "object", "title": "Informações sobre calendário da cobrança", "required": [ "dataDeVencimento" ], "description": "", "properties": { "dataDeVencimento": { "type": "string", "format": "date", "title": "Data de vencimento da cobrança", "description": "Trata-se de uma data, no formato `YYYY-MM-DD`, segundo ISO 8601. É a data de vencimento da cobrança." } } }, "valor": { "type": "object", "title": "Valor da cobrança recorrente", "required": [ "original" ], "description": "Valor da cobrança recorrente", "properties": { "original": { "type": "string", "title": "Valor", "pattern": "\\d{1,10}\\.\\d{2}", "description": "Valor original da cobrança." } } }, "ajusteDiaUtil": { "type": "boolean", "title": "Ajuste data prevista para liquidação para próximo dia útil", "default": false, "description": "Campo de ativação do ajuste da data prevista para liquidação para próximo dia útil caso o vencimento corrente seja um dia não útil. O PSP Recebedor deverá considerar os feriados locais com base no código município do usuário pagador." }, "recebedor": { "title": "Recebedor", "description": "O objeto recebedor organiza as informações sobre o recebedor da cobrança.", "allOf": [ { "$ref": "#/$defs/DadosBancariosRecebedor" } ] } } }, "CobRCompleta": { "type": "object", "title": "Cobrança Recorrente Completa", "required": [ "idRec", "txid", "status", "valor", "recebedor", "calendario" ], "description": "Dados completos da cobrança recorrente via API Pix", "allOf": [ { "type": "object", "properties": { "idRec": { "$ref": "#/$defs/RecId" } } }, { "type": "object", "properties": { "txid": { "$ref": "#/$defs/TxId" } } }, { "$ref": "#/$defs/CobRBase" }, { "type": "object", "properties": { "calendario": { "type": "object", "required": [ "criacao" ], "properties": { "criacao": { "type": "string", "format": "date", "title": "Data de criação da cobrança", "description": "Trata-se de uma data, no formato `YYYY-MM-DD`, segundo ISO 8601. É a data de criação da cobrança." } } } } }, { "$ref": "#/$defs/CobRStatus" }, { "$ref": "#/$defs/CobRConfiguracao" }, { "$ref": "#/$defs/DadosDevedorRecorrencia" }, { "type": "object", "properties": { "pix": { "type": "array", "title": "Pix recebidos", "items": { "allOf": [ { "$ref": "#/$defs/PixAutomatico" }, { "type": "object", "properties": { "txid": { "allOf": [ { "$ref": "#/$defs/TxId" }, { "pattern": "[a-zA-Z0-9]{26,35}" } ] } } } ] } } } }, { "$ref": "#/$defs/CobRAtualizacao" }, { "$ref": "#/$defs/CobRTentativas" } ] }, "CobRConfiguracao": { "type": "object", "title": "Configuração da Cobrança Recorrente", "required": [ "politicaRetentativa" ], "properties": { "politicaRetentativa": { "type": "string", "title": "Política de retentativa da cobrança recorrente", "enum": [ "NAO_PERMITE", "PERMITE_3R_7D" ] } } }, "CobRStatus": { "type": "object", "title": "Status da Cobrança Recorrente", "properties": { "status": { "type": "string", "title": "Status do registro da cobrança", "enum": [ "CRIADA", "ATIVA", "CONCLUIDA", "EXPIRADA", "REJEITADA", "CANCELADA" ] } } }, "CobRTentativas": { "type": "object", "title": "Histórico de Tentativas da Cobrança Recorrente", "properties": { "tentativas": { "type": "array", "title": "Histórico de Tentativas de Cobrança", "description": "Histórico de Tentativas de Cobrança", "items": { "type": "object", "required": [ "dataLiquidacao", "tipo", "endToEndId", "status", "atualizacao" ], "properties": { "dataLiquidacao": { "type": "string", "format": "date", "description": "Data da liquidação da cobrança. Trata-se de uma data, no formato `YYYY-MM-DD`, segundo ISO 8601." }, "tipo": { "type": "string", "title": "Tipo da Tentativa", "description": "Tipo da tentativa da cobrança.", "enum": [ "AGND", "NTAG", "RIFL" ] }, "status": { "type": "string", "title": "Status da Tentativa", "description": "Status da tentativa da cobrança.", "enum": [ "SOLICITADA", "AGENDADA", "PAGA", "CANCELADA", "REJEITADA", "EXPIRADA" ] }, "endToEndId": { "$ref": "#/$defs/EndToEndId" }, "atualizacao": { "type": "array", "title": "Histórico de Status da Tentativa", "description": "Histórico das mudanças de status da tentativa de cobrança.", "items": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "title": "Status da Tentativa", "description": "Status da tentativa da cobrança.", "enum": [ "SOLICITADA", "AGENDADA", "PAGA", "CANCELADA", "REJEITADA", "EXPIRADA" ] }, "data": { "type": "string", "format": "date-time", "description": "Data e hora do registro de status atualizado. Respeita RFC 3339." } } } }, "rejeicao": { "type": "object", "title": "Informações sobre a rejeição da tentativa da cobrança", "required": [ "codigo", "descricao" ], "description": "Informações sobre a rejeição da tentativa da cobrança", "properties": { "codigo": { "type": "string", "title": "Código da rejeição da tentativa", "description": "Código da rejeição da tentativa. Corresponde ao código de rejeição presente no catálogo de mensagens. Os códigos de rejeição da tentativa `AC05`,`AM09`,`DENC`,`DS27`,`DTED`,`MIDI`,`MSUC`,`NITX`,`RC09` e `DTED` causam a rejeição da cobrança recorrente correspondente.", "maxLength": 4, "enum": [ "AB10", "AC05", "AC06", "AM02", "AM09", "DENC", "DS27", "DTED", "DTNT", "FBRD", "IRNT", "MIDI", "MSUC", "NIEC", "NIPA", "NITX", "QUNT", "RC09", "UDEI" ] }, "descricao": { "type": "string", "title": "Descricao da rejeição", "description": "Descricao da causa da rejeição", "maxLength": 105 } } } } } } } }, "DadosBancariosRecebedor": { "type": "object", "required": [ "conta", "tipoConta" ], "properties": { "conta": { "type": "string", "title": "Conta", "description": "Número da conta do usuário recebedor.", "minLength": 1, "maxLength": 20 }, "tipoConta": { "type": "string", "title": "Tipo da conta do usuário recebedor", "description": "Tipo da conta do usuário recebedor.", "enum": [ "CORRENTE", "POUPANCA", "PAGAMENTO" ] }, "agencia": { "type": "string", "title": "Agencia", "description": "Número da agência do usuário recebedor.", "minLength": 1, "maxLength": 4 } } }, "DadosComplementaresPessoa": { "type": "object", "properties": { "logradouro": { "type": "string", "title": "Logradouro", "description": "Logradouro do usuário.", "minLength": 1, "maxLength": 200 }, "cidade": { "type": "string", "title": "Cidade", "description": "Cidade do usuário.", "minLength": 1, "maxLength": 200 }, "uf": { "type": "string", "title": "UF", "description": "UF do usuário.", "minLength": 2, "maxLength": 2 }, "cep": { "type": "string", "title": "CEP", "description": "CEP do usuário.", "minLength": 8, "maxLength": 8 } } }, "DadosDevedorRecorrencia": { "type": "object", "properties": { "devedor": { "title": "Devedor", "description": "O objeto devedor organiza as informações sobre o devedor da recorrência.", "allOf": [ { "type": "object", "properties": { "email": { "type": "string", "title": "Email", "pattern": "[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,4}$", "description": "Email do usuário." } } }, { "$ref": "#/$defs/DadosComplementaresPessoa" } ] } } }, "DevolucaoId": { "type": "string", "title": "Id da Devolução", "description": "Id gerado pelo cliente para representar unicamente uma devolução.", "pattern": "[a-zA-Z0-9]{1,35}" }, "DevolucaoNaturezaPixAutomatico": { "type": "string", "title": "Natureza da Devolução", "description": "Indica qual é a natureza da devolução. Uma devolução pode ser relacionada a um Pix comum (com códigos possíveis: `MD06` e `FR01` da pacs.004 e `REFU` da pacs.008). Na ausência deste campo a natureza deve ser interpretada como \nsendo de um Pix comum (`ORIGINAL`).\n\nAs naturezas são assim definidas:\n - `ORIGINAL`: quando a devolução é solicitada pelo usuário recebedor e se refere a um Pix comum (`MD06`);\n - `MED_FRAUDE`: quando a devolução ocorre no âmbito do MED (Mecanismo Especial de Devolução) por fundada suspeita de fraude e se refere a um Pix comum (`FR01`).\n - `MED_PIX_AUTOMATICO`: reembolso total ou parcial ao participante do usuário pagador no âmbito do MED (Mecanismo Especial de Devolução) para o Pix Automático pela utilização de recursos próprios para ressarcimento do usuário pagador.(`REFU`);\n\nOs valores de devoluções são sempre limitados aos valores máximos a seguir:\n- Pix comum: o valor da devolução é limitado ao valor do próprio Pix (a natureza nesse caso pode ser: ORIGINAL, MED_PIX_AUTOMATICO ou MED_FRAUDE);\n", "enum": [ "ORIGINAL", "MED_PIX_AUTOMATICO", "MED_FRAUDE" ] }, "DevolucaoPixAutomatico": { "type": "object", "title": "Devolução", "required": [ "id", "rtrId", "valor", "horario", "status" ], "properties": { "id": { "$ref": "#/$defs/DevolucaoId" }, "rtrId": { "type": "string", "title": "RtrId", "description": "ReturnIdentification que transita na PACS004.", "pattern": "[a-zA-Z0-9]{32}", "minLength": 32, "maxLength": 32 }, "valor": { "type": "string", "title": "Valor a devolver.", "pattern": "\\d{1,10}\\.\\d{2}", "description": "Valor a devolver." }, "natureza": { "$ref": "#/$defs/DevolucaoNaturezaPixAutomatico" }, "descricao": { "type": "string", "title": "Mensagem ao pagador relativa à devolução.", "maxLength": 140, "description": "O campo `descricao`, opcional, determina um texto a ser apresentado ao pagador contendo informações sobre a devolução. Esse texto será preenchido, na pacs.004, pelo PSP do recebedor, no campo RemittanceInformation. O tamanho do campo na pacs.004 está limitado a 140 caracteres." }, "horario": { "type": "object", "properties": { "solicitacao": { "type": "string", "format": "date-time", "title": "Horário de solicitação", "description": "Horário no qual a devolução foi solicitada no PSP." }, "liquidacao": { "type": "string", "format": "date-time", "title": "Horário de liquidacao", "description": "Horário no qual a devolução foi liquidada no PSP." } } }, "status": { "type": "string", "title": "Status", "description": "Status da devolução.", "enum": [ "EM_PROCESSAMENTO", "DEVOLVIDO", "NAO_REALIZADO" ] }, "motivo": { "type": "string", "title": "Descrição do status.", "description": "# Status da Devolução\n\nCampo opcional que pode ser utilizado pelo PSP recebedor para detalhar os motivos\nde a devolução ter atingido o status em questão.\nPode ser utilizado, por exemplo, para detalhar o motivo de a devolução não ter sido realizada.\n", "maxLength": 140 } } }, "EndToEndId": { "type": "string", "title": "Id fim a fim da transação", "description": "EndToEndIdentification que transita na PACS002, PACS004 e PACS008", "pattern": "[a-zA-Z0-9]{32}", "minLength": 32, "maxLength": 32 }, "Paginacao": { "type": "object", "title": "Paginação", "required": [ "paginaAtual", "itensPorPagina", "quantidadeDePaginas", "quantidadeTotalDeItens" ], "properties": { "paginaAtual": { "type": "integer", "title": "Página atual", "description": "Número da página recuperada.", "minimum": 0 }, "itensPorPagina": { "type": "integer", "title": "Itens por página", "description": "Quantidade de registros retornado na página.", "minimum": 1 }, "quantidadeDePaginas": { "type": "integer", "title": "Quantidade de páginas", "description": "Quantidade de páginas disponíveis para consulta.", "minimum": 1 }, "quantidadeTotalDeItens": { "type": "integer", "title": "Quantidade total de itens", "description": "Quantidade total de itens disponíveis de acordo com os parâmetros informados.", "minimum": 0 } } }, "ParametrosConsultaCobR": { "type": "object", "title": "Parâmetros de Consulta de Cobrança", "description": "Parâmetros utilizados para a realização de uma consulta de cobranças.", "required": [ "inicio", "fim", "paginacao" ], "properties": { "inicio": { "type": "string", "format": "date-time", "title": "Data de Início", "description": "Data inicial utilizada na consulta. Respeita RFC 3339." }, "fim": { "type": "string", "format": "date-time", "title": "Data de Fim", "description": "Data de fim utilizada na consulta. Respeita RFC 3339." }, "idRec": { "$ref": "#/$defs/RecId" }, "cpf": { "type": "string", "title": "CPF", "pattern": "/^\\d{11}$/", "description": "Filtro pelo CPF do devedor. Não pode ser utilizado ao mesmo tempo que o CNPJ." }, "cnpj": { "type": "string", "title": "CNPJ", "pattern": "/^\\d{14}$/", "description": "Filtro pelo CNPJ do devedor. Não pode ser utilizado ao mesmo tempo que o CPF." }, "status": { "type": "string", "title": "Status do registro da cobrança", "description": "Filtro pelo status das cobranças." }, "recebedor": { "type": "object", "title": "Recebedor", "properties": { "convenio": { "type": "string", "title": "Convênio", "description": "Convênio entre usuário e participante recebedor.", "maxLength": 60 } } }, "paginacao": { "$ref": "#/$defs/Paginacao" } } }, "PixAutomatico": { "type": "object", "title": "Pix", "required": [ "txid", "endToEndId", "valor", "horario" ], "properties": { "endToEndId": { "$ref": "#/$defs/EndToEndId" }, "txid": { "allOf": [ { "$ref": "#/$defs/TxId" }, { "pattern": "[a-zA-Z0-9]{1,35}" } ] }, "valor": { "type": "string", "title": "Valor do Pix.", "pattern": "\\d{1,10}\\.\\d{2}", "description": "Valor do Pix." }, "horario": { "type": "string", "format": "date-time", "title": "Horário", "description": "Horário em que o Pix foi processado no PSP." }, "infoPagador": { "type": "string", "title": "Informação livre do pagador", "maxLength": 140 }, "devolucoes": { "type": "array", "title": "Devoluções", "items": { "$ref": "#/$defs/DevolucaoPixAutomatico" } } } }, "RecId": { "type": "string", "title": "ID Recorrência", "description": "# Identificador da Recorrência\n\nRegra de formação:\n- RAxxxxxxxxyyyyMMddkkkkkkkkkkk (29 caracteres; \"case sensitive\", isso é, diferencia letras maiúsculas e minúsculas), sendo:\n - \"R\": fixo (1 caractere). \"R\" para a recorrência criada dentro do Pix;\n - \"A\": identificação da possibilidade de novas tentativas, sendo possíveis os valores \"R\" ou \"N\" (1 caractere). \"R\" caso a recorrência permita novas tentativas de pagamento pós vencimento, ou \"N\" caso não permita novas tentativas.\n - \"xxxxxxxx\": identificação do agente que presta serviço para o usuário recebedor que gerou o , podendo ser: o ISPB do participante direto, o ISPB do participante indireto ou os 8 primeiros dígitos do CNPJ do prestador de serviço de iniciação (8 caracteres numéricos [0-9]);\n - \"yyyyMMdd\": data (8 caracteres) de criação da recorrência;\n - \"kkkkkkkkkkk\": sequencial criado pelo agente que gerou o (11 caracteres alfanuméricos [a-z|A-Z|0-9]). Deve ser único dentro de cada \"yyyyMMdd\".\n\nDessa forma, o ID da recorrência deve ser formado de acordo com um dos tipos a seguir:\n- \"RRxxxxxxxxyyyyMMddkkkkkkkkkkk\"; para recorrência criada dentro do Pix e que permite novas tentativas de pagamento pós vencimento; ou\n- \"RNxxxxxxxxyyyyMMddkkkkkkkkkkk\"; para recorrência criada dentro do Pix e que não permite novas tentativas de pagamento pós vencimento.”\n", "pattern": "[a-zA-Z0-9]{29}", "minLength": 29, "maxLength": 29 }, "TxId": { "type": "string", "title": "Id da Transação", "description": "# Identificador da transação\n\nO campo `txid` determina o identificador da transação.\nO objetivo desse campo é ser um elemento que possibilite ao PSP do recebedor apresentar ao usuário recebedor a funcionalidade de conciliação de pagamentos.\n\nNa pacs.008, é referenciado como `TransactionIdentification ` ou `idConciliacaoRecebedor`.\n\nEm termos de fluxo de funcionamento, o txid é lido pelo aplicativo do PSP do pagador e, \ndepois de confirmado o pagamento, é enviado para o SPI via pacs.008. \nUma pacs.008 também é enviada ao PSP do recebedor, contendo, além de todas as informações usuais \ndo pagamento, o txid.\nAo perceber um recebimento dotado de txid, o PSP do recebedor está apto a se comunicar com o usuário recebedor, \ninformando que um pagamento específico foi liquidado.\n\nO txid é criado exclusivamente pelo usuário recebedor e está sob sua responsabilidade.\nO txid, no contexto de representação de uma cobrança, é único por CPF/CNPJ do usuário recebedor. Cabe ao \nPSP recebedor validar essa regra na API Pix.\n", "pattern": "[a-zA-Z0-9]{26,35}", "minLength": 26, "maxLength": 35 } } }