Criar boleto (Banking)

Este endpoint permite a criação de um boleto bancário para pagamento, utilizando os dados do cliente e do pagamento.

🔼
POST {urlServidor}/v1/marketplace/billets

Obs: A palavra urlServidor deve ser substituída pela url do servidor.

Parâmetros da Requisição

Headers

Nome	Tipo	Obrigatório	Descrição
`integration-key`	string	Sim	Chave de integração.
`x-token`	string	Sim	Token de autenticação. Pode ser encontrado em nosso portal na guia de integração.
`Authorization`	Auth Type Bearer Token	Sim	Inserir o Bearer Token, gerado na rota Auth

Exemplo de header da requisição

curl--request POST \
--location '{urlServidor}v1/marketplace/billets' \
--header 'integration-key: your_integration_key' \
--header 'x-token: your_x_token
--header 'establishment_id:establishment_id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{bearer_token}}' \

Estrutura do Payload – Criar Boleto

Nome	Tipo	Obrigatório	Descrição
`amount`	number	Sim	Valor total do boleto em centavos
`expiration`	string	Sim	Data de vencimento do boleto (formato ISO 8601).
`payment_limit_date`	string	Não	Data limite para pagamento após o vencimento.
`recharge`	boolean	Não	Indica se o boleto é utilizado para recarga.
Payload Client
`first_name`	string	Sim	Nome ou razão social do cliente.
`last_name`	string	Sim	Sobrenome ou nome fantasia do cliente.
`document`	string	Sim	CPF ou CNPJ do cliente.
`email`	string	Sim	E-mail do cliente.
Payload Adrress
`street`	string	Sim	Endereço do cliente
`number`	string	Sim	Número do endereço
`complement`	string	Sim	Complemento do endereço
`neighborhood`	string	Sim	Bairro
`city`	string	Sim	Cidade
`state`	string	Sim	Estado: [ AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MS, MT, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO ]
`zip_code`	string	Sim	CEP (somente números).
instruction
`booklet`	boolean	Sim	Indica se o boleto será emitido como carnê.
`description`	string	Não	Descrição a ser exibida no boleto.
Instrução taxa de atraso Instruction.late_fee
`mode`	string	Sim	Tipo da multa (ex: PERCENTAGE).
`amount`	number	Sim	Valor da multa aplicada.
Instruction.Interest
`mode`	string	Sim	Tipo do juro (ex: MONTHLY_PERCENTAGE).
`amount`	number	Sim	Valor do juro aplicado.
Instruction.discount
`mode`	string	Sim	Tipo do juro (ex: PERCENTAGE).
`amount`	number	Sim	Valor do desconto a ser aplicado.
`limit_date`	string	Sim	Data limite para concessão do desconto.

Observações importantes:

As datas devem estar no formato ISO 8601 (ex: "2024-06-30").
O campo recharge permite que esse boleto seja usado em fluxos de recarga, como carteiras digitais ou contas pré-pagas.
As instruções (instruction) são importantes para determinar a aplicação de multas, juros e descontos.

Body da requisição

O corpo da requisição deve ser enviado no formato JSON, conforme descrito abaixo:

{
    "amount": 1000,
    "expiration": "2025-08-28",
    "payment_limit_date": "2025-08-30",
    "recharge": true,
    "client":{
        "first_name": "Antonio",
        "last_name": "Francisco",
        "document": "43878902077",
        "email": "[email protected]",
        "address": {
            "street": "Av Longe",
            "number": "10",
            "neighborhood": "Bairro distante",
            "complement": "Perto da zona",
            "city": "Goiania",
            "state": "GO",
            "zip_code": "29163321"
        }
    },
    "instruction": {
        "booklet": false,
        "description": "Venda por Boleto",
        "late_fee": {
            "mode": "PERCENTAGE",
            "amount": 1
        },
        "interest": {
            "mode": "MONTHLY_PERCENTAGE",
            "amount": 1
        },
        "discount": {
            "mode":"PERCENTAGE",
            "amount": 1,
            "limit_date":"2025-08-25"
        }
    }
}

Exemplo de Resposta (200):

{
    "_id": "689b893b59a7593764e8b0e1",
    "type": "BILLET",
    "gateway_key": "82032a9d-96e2-42a6-8fbf-58f45687361e",
    "establishment_id": "155444085",
    "establishment": {
        "id": 155085,
        "first_name": "EC Cobranças",
        "last_name": null,
        "document": "10068114001",
        "account_number": "300543394162",
        "account_check_digit": "8"
    },
    "marketplace": {
        "id": 26,
        "nickname": "Parceiro Integrações",
        "first_name": "Webhooks Integrações",
        "last_name": "API Integrações",
        "document": "60274849000185"
    },
    "representative": {
        "id": 63,
        "first_name": "EC Cobranças",
        "last_name": null,
        "document": "10068114001"
    },
    "fees_banking": {
        "name": "Pacote de Tarifa Bancária Comercial",
        "description": "Pacote de Tarifa Bancária Comercial",
        "fees": 250
    },
    "description": "Venda por Boleto",
    "amount": 750,
    "original_amount": 1000,
    "barcode": null,
    "digitable_line": null,
    "url": null,
    "status": "PROCESSING",
    "expiration_at": "2025-08-28T12:00:00.000Z",
    "payment_limit_date": "2025-08-30T00:00:00.000Z",
    "fees": 250,
    "billing_instructions": [
        {
            "name": "late_fee",
            "mode": "PERCENTAGE",
            "amount": 1,
            "_id": "689b893b59a7593764e8b0e8"
        },
        {
            "name": "interest",
            "mode": "MONTHLY_PERCENTAGE",
            "amount": 1,
            "_id": "689b893b59a7593764e8b0e9"
        },
        {
            "name": "discount",
            "mode": "PERCENTAGE",
            "amount": 1,
            "limit_date": "2025-08-25T00:00:00.000Z",
            "_id": "689b893b59a7593764e8b0ea"
        }
    ],
    "recharge": true,
    "gateway_authorization": "CELCOIN",
    "request_origin": "API",
    "created_at": "2025-08-12T18:34:35.601Z",
    "updated_at": "2025-08-12T18:34:35.601Z",
    "__v": 0,
    "client": {
        "first_name": "Antonio",
        "last_name": "Francisco",
        "document": "43878902077",
        "email": "[email protected]",
        "_id": "689b893b59a7593764e8b0e2"
    }
}

✅ Códigos de Resposta

Código	Descrição
200	Boleto criado com sucesso.
400	Requisição malformada.
401	Não autorizado.
422	Erro de validação nos dados.
500	Erro interno no servidor.

Códigos de Resposta

Consulte a página com os status: Status de respostas

Para mais detalhes sobre os parâmetros e funcionamento da API, acesse a documentação oficial da Paytime.

Updated about 1 month ago

Did this page help you?