Referência de cadastro
Referência completa do corpo de POST /cobranca/boleto/v1/boletos. Os campos abaixo vêm do contrato OpenAPI da API.
Headers
x-api-key (obrigatório), Authorization: Bearer (obrigatório), Content-Type: application/json (obrigatório), cooperativa (4 dígitos), posto (2 dígitos).
Campos do boleto (raiz)
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
| codigoBeneficiario | string (5 dígitos) | Sim | String, com zeros à esquerda |
| dataVencimento | date (YYYY-MM-DD) | Sim | |
| especieDocumento | enum | Sim | Ver lista de espécies abaixo |
| tipoCobranca | enum | Sim | NORMAL ou HIBRIDO |
| seuNumero | string (máx. 10) | Sim | Controle interno do beneficiário |
| idTituloEmpresa | string (máx. 25) | Não | Controle interno alternativo, mais longo |
| valor | number (2 casas) | Sim | |
| nossoNumero | string (9 dígitos) | Não | Se omitido, o Sicredi gera automaticamente (ver Nosso Número) |
| pagador | objeto | Sim | Ver objeto Pagador |
| beneficiarioFinal | objeto | Não | Destinatário final do crédito |
| diasProtestoAuto | integer (3–99) | Não | Mutuamente exclusivo com diasNegativacaoAuto |
| diasNegativacaoAuto | integer (3–99) | Não | Mutuamente exclusivo com diasProtestoAuto |
| validadeAposVencimento | integer | Não | Dias de validade do QR Code após o vencimento (híbrido) |
| informativos | array de string (máx. 80 cada) | Não | Até 5 itens |
| mensagens | array de string (máx. 80 cada) | Não | Até 4 itens |
| splitBoleto | objeto | Não | Ver Split de crédito |
O que é o Beneficiário Final:é o destinatário real do crédito quando o boleto é emitido por um intermediário (ex.: administradora de consórcio que emite em nome de uma empresa). Na maioria dos boletos, não existe Beneficiário Final, o beneficiário do boleto e o destinatário do crédito são a mesma entidade. Não envie este campo se não houver um destinatário diferente do beneficiário cadastrado.
Modalidade/Carteira, configuração fora da API:A modalidade do boleto (Simples, Caucionada, Descontada, Vinculada) não é enviada na requisição, ela é configurada no cadastro de Cobrança do beneficiário junto à cooperativa. Para a grande maioria das integrações, a modalidade correta é SIMPLES, COM REGISTRO. Se você estiver enfrentando rejeições relacionadas à carteira, verifique com sua cooperativa a modalidade cadastrada para o convênio.
Desconto (até 3 escalonados, ou 1 antecipado, mutuamente exclusivos).
tipoDesconto, valorDesconto1/dataDesconto1, valorDesconto2/dataDesconto2, valorDesconto3/dataDesconto3, descontoAntecipado.
Juros
tipoJuros, juros, dataInicioJuros, e tipoJurosPercentual (DIARIO/MENSAL, obrigatório quando o juros é percentual).
Multa
tipoMulta, multa, dataInicioMulta.
Objeto pagador
pagador| Campo | Tipo | Obrigatório |
|---|---|---|
| tipoPessoa | PESSOA_FISICA/PESSOA_JURIDICA | Sim |
| documento | string (máx. 14) | Sim |
| nome | string (máx. 40) | Sim |
| endereco | string (máx. 40) | Condicional* |
| cidade | string (máx. 40) | Condicional* |
| uf | string (2 letras) | Condicional* |
| cep | string (8 dígitos) | Condicional* |
| telefone | string (máx. 11) | Não |
| email (máx. 40) | Não |
*Condicional: os campos de endereço são opcionais por padrão, mas obrigatórios quando o beneficiário tem validação de CEP ativada, ou em pedidos de protesto/negativação.
Espécies de documento (especieDocumento)
DUPLICATA_MERCANTIL_INDICACAO, DUPLICATA_RURAL, NOTA_PROMISSORIA, NOTA_PROMISSORIA_RURAL, NOTA_SEGUROS, RECIBO, LETRA_CAMBIO, NOTA_DEBITO, DUPLICATA_SERVICO_INDICACAO, OUTROS, BOLETO_PROPOSTA, CARTAO_CREDITO, BOLETO_DEPOSITO.
Restrições por espécie:(geram 422): algumas espécies, como recibo, nota de débito, outros, boleto proposta, cartão de crédito e boleto depósito, não permitem protesto ou negativação.
BOLETO_PROPOSTAtem limitações adicionais para juros, multa e protesto. Algumas espécies permitem valor zero em condições específicas. [A VALIDAR NO GATEWAY] a lista exata de restrições por espécie deve ser confirmada contra a API.
Updated 2 days ago