Neofin V1
latest
  • latest
  • english
  1. Upsert de Cobranças
Neofin V1
latest
  • latest
  • english
  • Inicie sua jornada na Neofin
  • Preparando seus ambientes
  • Versão 1
    • API de Cobranças
      • Upsert de Cobranças
        • Como realizar o upsert de uma cobrança
        • Upsert de Cobranças
          POST
      • Buscando uma cobrança
        • Como buscar uma única cobrança
        • Buscando pelo Integration Identifier
          GET
        • Buscando pelo Billing Number
          GET
      • Marcando uma cobrança como paga
        • Como marcar uma cobrança como paga
        • Marcando como paga
          PUT
      • Cancelando uma cobrança
        • Como cancelar uma cobrança
        • Cancelando uma cobrança
          PUT
      • Listando suas cobranças
        • Como listar suas cobranças
        • Todas as cobranças
          GET
        • Cobranças por status
          GET
        • Cobranças por cliente
          GET
        • Cobranças por data de atualização
          GET
        • Eventos de cobranças
          GET
        • Eventos de uma uma cobrança por Integration Identifier
          GET
        • Cobranças por data de pagamento
          GET
      • Enviando anexos
        • Como enviar anexos
        • Anexando outros arquivos
          POST
        • Anexando uma NF a uma cobrança pelo Integration Identifier
          PUT
        • Anexando um Boleto a uma cobrança pelo Integration Identifier
          PUT
    • API de Clientes
      • Upsert de um cliente
        • Como realizar o upsert de um cliente
        • Upsert de clientes
          POST
      • Buscando um cliente
        • Buscando um cliente por Integration Identifier
          GET
        • Buscando um cliente pelo documento
          GET
    • Webhooks
      • Como preparar seus webhooks
    • FAQ
      • Dúvidas frequentes
  1. Upsert de Cobranças

Upsert de Cobranças

Sandbox
https://api.sandbox.neofin.services
Sandbox
https://api.sandbox.neofin.services
POST
https://api.sandbox.neofin.services
/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.
O retorno não incluirá a cobrança criada/atualizada, apenas o status de sucesso ou erro do envio para a fila.
Request Request Example
Shell
JavaScript
Java
Swift
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": ""
        }
    ]
}'
Response Response Example
202 - Example 1
{
    "message": "Billings successfully queued.",
    "errors": {}
}

Request

Header Params
api-key
string 
required
Neofin API Key
Example:
{{API_KEY}}
secret-key
string 
required
Neofin Secret Key
Example:
{{SECRET_KEY}}
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
string  | integer  | boolean  | array  | object  | number  | null 
optional
🟠400Bad Request - Upsert
🟠403Invalid API Keys
🔴500Erro do servidor
Previous
Como realizar o upsert de uma cobrança
Next
Como buscar uma única cobrança
Built with