---
updatedAt: 2026-07-24T02:35:22.000Z
agentTools:
projectIndex: https://docs-parceiro.paytime.com.br/llms.txt
---
# 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
```Text CURL
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:
```json JSON
{
"amount": 1000,
"expiration": "2025-08-28",
"payment_limit_date": "2025-08-30",
"recharge": true,
"client":{
"first_name": "Antonio",
"last_name": "Francisco",
"document": "43878902077",
"email": "antonio@emaildocliente.com",
"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):**
```json JSON
{
"_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": "antonio@emaildocliente.com",
"_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](status-de-respostas)
Para mais detalhes sobre os parâmetros e funcionamento da API, acesse a [documentação oficial da Paytime](https://paytime-api-parceiro.readme.io/docs/seja-bem-vindo).