Upsert de Cobranças

Este endpoint permite criar ou atualizar uma cobrança (billing) na plataforma Neofin.

🛠 Comportamento:
Criação:
Se o integration_identifier fornecido não corresponder a nenhuma cobrança existente na Neofin, uma nova cobrança será criada.

Atualização:
Se o integration_identifier corresponder a uma cobrança existente, a cobrança será atualizada com os novos dados enviados.

📌 Observações:
O campo integration_identifier é obrigatório e serve como identificador único para garantir a idempotência da cobrança.

O retorno não incluirá a cobrança criada/atualizada, apenas o status de sucesso ou erro do envio para a fila.

curl --location --request POST 'https://api.sandbox.neofin.services/billing/' \ --header 'api-key: ' \ --header 'secret-key: ' \ --header 'Content-Type: application/json' \ --data-raw '{ "billings": [ { "address_city": "São Paulo", "address_complement": "CJ 4", "address_neighborhood": "Jardim Paulista", "address_number": "365", "address_state": "SP", "address_street": "Rua Pamplona", "address_zip_code": "01405-000", "amount": 150, "by_mail": false, "by_whatsapp": true, "customer_document": "51491769000190", "customer_mail": "teste@company.com", "customer_name": "Company Teste LTDA", "customer_phone": "+5511987654321", "customer_secondary_phone": "", "discount_before_payment": 0, "discount_before_payment_due_date": 0, "description": "Parcela 1/2", "due_date": 1678316400, "fees": 0, "fine": 0, "installment_type": "custom", "installments": 1, "nfe_number": "2121212121212", "recipients": [], "type": "generic", "integration_identifier": "1111a", "boleto_base64": "", "code": "", "hash": "" } ] }'

Request

Header Params

api-key

string

required

Neofin API Key

Example:

secret-key

string

required

Neofin Secret Key

Example:

Body Params application/json

billings

array [object {38}]

required

Cobranças a serem cadastradas, limite de 50 por vez

customer_document

string

required

CPF ou CNPJ válido (Ex: "24166636000176")

customer_integration_identifier

string

optional

ID do seu cliente no seu sistema

customer_name

string

optional

Nome do seu cliente

customer_trade_name

string

optional

Nome fanstasia do seu cliente

customer_mail

string

optional

E-mail principal do seu cliente

customer_phone

string

optional

Telefone principal do seu cliente. Preferencialmente Whatsapp.

customer_secondary_phone

string

optional

Telefone secundário do seu cliente. Preferencialmente Whatsapp.

address_city

string

optional

Endereço do seu cliente

address_complement

string

optional

Complemento do endereço do seu cliente

address_neighborhood

string

optional

Bairro do endereço do seu cliente

address_number

string

optional

Número do endereço do seu cliente

address_state

string

optional

Estado do endereço do seu cliente

address_street

string

optional

Rua do endereço do seu cliente

address_zip_code

string

optional

CEP do seu cliente

amount

integer

required

Valor EM CENTAVOS da cobrança. Se R$100,12 deve ser cadastrado como 10012

due_date

integer

required

Data de vencimento da sua cobrança

original_due_date

integer

optional

Data de vencimento original da sua cobrança

discount_before_payment

integer

optional

Desconto aplicado antes da data de pagamento

discount_before_payment_due_date

integer

optional

Data em que o "discount_before_payment" deve ser aplicado

description

string

optional

Descrição da sua cobrança

fees

integer

optional

Taxas da cobrança

fine

integer

optional

Multa da cobrança

installment_type

enum<string>

required

Tipo da parcela

Allowed values:

weeklybiweeklymonthlycustom

installments

integer

required

Quantidade de parcelas da sua cobrança

nfe_number

string

optional

ID da sua NFe

recipients

array[string]

optional

E-mail que serão adicionados na cópia do e-mail de cobrança

type

enum<string>

required

Tipo da cobrança

Allowed values:

genericbolepixboletopix

integration_identifier

string

required

Identificador único: o ID dessa cobrança e parcela no seu sistema

boleto

object (GenericBoleto)

optional

Em caso de "type" como "generic", você pode utilizar esse boleto para criar um PDF a partir dos dados dele dentro da Neofin.

boleto_pdf

string

optional

Quando "type" for "generic", esse campo pode ser usado para salvar a URL FIXA do PDF do seu boleto. Não deve ser utilizada para URLs que possam expirar.

boleto_base64

string

optional

Base64 do boleto que você está inserindo quando "type" for "generic"

nf_url

string

optional

Esse campo pode ser usado para salvar a URL FIXA da sua NF. Não deve ser utilizada para URLs que possam expirar.

rps

string

optional

Valor do RPS da sua cobrança

code

string

optional

Código de barras válido do seu boleto a ser adicionado a cobrança

hash

string

optional

Pix Copia e Cola a ser enviado do seu boleto

ignore_existing_customer_upsert

boolean

optional

Flag para ignorar os dados de customer enviados nessa requisição caso um cliente já esteja cadastrado

by_mail

boolean

required

Obsoleto (deprecated), mas deve ser enviado um valor booleano

by_whatsapp

boolean

required

Obsoleto (deprecated), mas deve ser enviado um valor booleano

Examples

Responses

🟢202Billings successfully queued

application/json

Body

message

string

required

errors

object

required

metadata

optional

🟠400Bad Request - Upsert

🟠403Invalid API Keys

🔴500Erro do servidor