Upsert de Cobranças

Upserts a billing
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.

Campos editáveis são restritos e seguem a regra descrita na seção Editable Fields da documentação.

O retorno não incluirá a cobrança criada/atualizada, apenas o status da operação.

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 {31}]

required

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

customer_document

string

required

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

customer_name

string

optional

Nome 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

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

optional

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

boleto_base64

string

optional

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

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