API de Cobrança Bancária — payloadRestService

Manual técnico oficial para desenvolvedores e integradores de ERP: registro de boletos híbridos com QR Code PIX, consulta de liquidação, cancelamento, alteração cadastral e conciliação por Webhook.

RESTful JSON Basic Auth + Tenant Token Boletos com PIX Integrado Produção & Homologação

1. Visão Geral & Arquitetura

O payloadRestService é o serviço central de mensageria financeira do Netuno Cobrança SaaS. Ele expõe uma API REST síncrona de alta performance que conecta ERPs e sistemas externos aos bancos conveniados (Bradesco, Santander, Itaú, Banco do Brasil, Sicredi, Sicoob, etc.).

POST Basic Auth (REST Key) Multi-tenant (companyToken) application/json
POST /rest?class=payloadRestService&method=Cobranca
1
Boleto Híbrido com PIX
Geração simultânea do código de barras tradicional FEBRABAN e do QR Code dinâmico PIX com liquidação instantânea.
2
Resposta Imediata
A chamada retorna a linha digitável, código de barras, EMV copia-e-cola do PIX e o PDF do título pronto em Base64.
3
Webhook de Liquidação
Assim que o pagador quita o título no banco ou no PIX, o ERP recebe a notificação instantânea com juros e multa calculados.

2. Autenticação & Segurança

A API opera sob um modelo de dupla autenticação para garantir a segurança da infraestrutura e o isolamento seguro de dados entre múltiplas empresas (Multi-Tenant):

A
1. Nível HTTP — REST Key
Enviado no header HTTP: Authorization: Basic {REST_KEY}. A chave REST autentica o cliente junto ao motor REST do Adianti Framework.
B
2. Nível Aplicação — companyToken
Enviado no corpo do JSON no campo companyToken. Identifica a unidade/filial cadastrada que possui os convênios bancários ativos.

3. Método EMITIR_COBRANCA

Registra o título de cobrança junto ao banco correspondente. Ao ser processado, o serviço cria a solicitação na API bancária, gera o QR Code PIX dinâmico e compila o PDF do boleto.

Payload JSON — Exemplo de Emissão de Cobrança
{
  "metodo": "EMITIR_COBRANCA",
  "numRecLegado": "TIT-2026-00981",
  "companyToken": "e7b92a4f6c8d102e3b4a5f6789012345",
  "bancoBacem": "033",
  "contaCorrente": "1234567-8",
  "ambiente": 2,
  "nossonumero": "0000000000123",
  "seuNumero": "DOC-981",
  "valorNominal": "250.75",
  "dataemissao": "2026-08-28",
  "dataVencimento": "2026-09-10",
  "mensagem": "Não receber após 30 dias de vencimento. Multa de 2% e juros de 1% a.m.",
  "beneficiarioFinal": {
    "cpfCnpj": "12345678000199",
    "nome": "EMPRESA CREDORA LTDA",
    "tipoPessoa": "J",
    "endereco": "Av. Paulista",
    "numero": "1000",
    "complemento": "Andar 10",
    "bairro": "Bela Vista",
    "cidade": "São Paulo",
    "cep": "01310100",
    "uf": "SP",
    "ddd": "11",
    "telefone": "33334444"
  },
  "pagador": {
    "cpfCnpj": "98765432100",
    "nome": "João da Silva",
    "tipoPessoa": "F",
    "email": "joao.silva@email.com",
    "endereco": "Rua das Flores",
    "numero": "123",
    "complemento": "Apto 12",
    "bairro": "Centro",
    "cidade": "Campinas",
    "cep": "13010000",
    "uf": "SP",
    "ddd": "19",
    "telefone": "998877665"
  }
}
Retorno de Sucesso (HTTP 200)
{
  "numRecLegado": "TIT-2026-00981",
  "status_envio": "SUCESSO_TRANSMISSAO",
  "status_pagamento": "EM_ABERTO",
  "payload_id": 4821,
  "codigo_solicitacao": "SOLIC-998231",
  "nosso_numero": "0000000000123",
  "linha_digitavel": "03399.00011 23000.000004 00000.000123 1 10660000025075",
  "codigo_barras": "03391106600000250750001230000000000123",
  "pix_txid": "e92a8310bc9447e7a88439129034",
  "qr_code": "00020101021226840014br.gov.bcb.pix2562pix.santander.com.br/qr/v2/cobv/...",
  "Status_Pdf": "Completo",
  "pdf_base64": "JVBERi0xLjQKJcTl8uXr... [PDF Codificado em Base64] ...=="
}

4. Método STATUS_COBRANCA

Consulta a situação atual do título no banco emissor. Retorna dados de pagamento quando liquidado, linha digitável e o PDF atualizado em Base64.

Requisição de Consulta de Status
{
  "metodo": "STATUS_COBRANCA",
  "numRecLegado": "TIT-2026-00981",
  "companyToken": "e7b92a4f6c8d102e3b4a5f6789012345",
  "bancoBacem": "033",
  "contaCorrente": "1234567-8",
  "ambiente": 2
}

5. Método CANCELAR_COBRANCA

Solicita a baixa ou cancelamento da cobrança no banco. Apenas títulos com status SUCESSO_TRANSMISSAO podem ser cancelados.

Requisição de Cancelamento
{
  "metodo": "CANCELAR_COBRANCA",
  "numRecLegado": "TIT-2026-00981",
  "companyToken": "e7b92a4f6c8d102e3b4a5f6789012345",
  "bancoBacem": "033",
  "contaCorrente": "1234567-8",
  "motivoCancelamento": "Acordo direto com o cliente efetuado no balcão."
}

6. Método ALTERAR_COBRANCA

Permite conceder abatimento (redução do valor nominal) ou postergar a data de vencimento da cobrança já registrada no banco.

Requisição de Alteração
{
  "metodo": "ALTERAR_COBRANCA",
  "numRecLegado": "TIT-2026-00981",
  "companyToken": "e7b92a4f6c8d102e3b4a5f6789012345",
  "bancoBacem": "033",
  "contaCorrente": "1234567-8",
  "valorNominal": "200.00",
  "datavencimento": "2026-09-25"
}

7. Webhook & Baixa Automática

Quando o pagador efetua a quitação do boleto ou transfere via PIX, o banco aciona o Webhook do Netuno, que por sua vez dispara um HTTP POST para a URL cadastrada no seu ERP com os dados de conciliação:

Payload Enviado ao Webhook do ERP Integrador
{
  "Banco": "033",
  "Agencia": "1234",
  "ContaCorrente": "1234567",
  "cNumRecLegado": "TIT-2026-00981",
  "DataBaixa": "2026-09-02",
  "DataCredito": "2026-09-03",
  "ValorBaixa": 250.75,
  "Desconto": 0,
  "juros": 0.00,
  "Multa": 0.00,
  "GrpEmpresa": "MATRIZ",
  "Filial": "SP-01"
}

8. Dicionário de Parâmetros

Tabela descritiva dos campos aceitos na requisição:

Campo Tipo Obrigatório Descrição & Regras
metodo string Sim EMITIR_COBRANCA, STATUS_COBRANCA, CANCELAR_COBRANCA, ALTERAR_COBRANCA, REQPG_COBRANCA.
numRecLegado string Sim Identificador único do título no ERP integrador (chave mestre).
companyToken string Sim Token exclusivo da Unidade/Filial cadastrada no Netuno Suite.
bancoBacem string Sim Código BACEN do banco (ex: 033 Santander, 237 Bradesco, 341 Itaú).
contaCorrente string Sim Conta bancária ativa cadastrada em Cadastros > Contas Bancárias.
pagador.email string Sim E-mail válido do sacado (validado via TEmailValidator).
ambiente integer Não 1 = Produção, 2 = Homologação (Padrão: 2).
valorNominal decimal/string Sim (Emissão) Valor nominal do título com ponto decimal (ex: 150.00).

9. Códigos & Tratamento de Erros

O serviço retorna códigos de status HTTP semânticos:

HTTP Code Mensagem Exemplo Causa & Ação Corretiva
401 Unauthorized Chave REST inválida. Header Authorization: Basic ausente ou com token incorreto.
400 Bad Request ERRO! O numRecLegado deve ser informado! Campo numRecLegado nulo ou vazio no JSON.
400 Bad Request ERRO! O e-mail do pagador deve ser informado. Campo pagador.email ausente ou em formato inválido.
400 Bad Request ERRO! A Empresa nao encontrada! companyToken incorreto ou unidade inativa no sistema.
400 Bad Request ERRO! Tentativa de input de uma cobranca já transmitida! Título já emitido. Utilize STATUS_COBRANCA para consultar.

10. Exemplos Práticos de Implementação

Selecione a linguagem de sua preferência para visualizar o código de integração:

cURL CLI
curl -X POST "https://api.seunome.com.br/rest?class=payloadRestService&method=Cobranca" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic 16a4f6bdf46bfb392fbb4788bf6c3c9df3ae7fd49acb79205627d6363706" \
  -d '{
    "metodo": "EMITIR_COBRANCA",
    "numRecLegado": "TIT-2026-001",
    "companyToken": "SEU_COMPANY_TOKEN",
    "bancoBacem": "033",
    "contaCorrente": "1234567-8",
    "ambiente": 2,
    "valorNominal": "150.00",
    "dataemissao": "2026-08-28",
    "dataVencimento": "2026-09-10",
    "beneficiarioFinal": {
      "cpfCnpj": "12345678000199",
      "nome": "EMPRESA CREDORA LTDA",
      "tipoPessoa": "J",
      "endereco": "Av. Paulista, 1000",
      "bairro": "Bela Vista",
      "cidade": "São Paulo",
      "cep": "01310100",
      "uf": "SP"
    },
    "pagador": {
      "cpfCnpj": "98765432100",
      "nome": "Cliente Exemplo",
      "tipoPessoa": "F",
      "email": "cliente@email.com",
      "endereco": "Rua das Flores, 123",
      "bairro": "Centro",
      "cidade": "Campinas",
      "cep": "13010000",
      "uf": "SP"
    }
  }'
PHP (cURL)
<?php
$url = 'https://api.seunome.com.br/rest?class=payloadRestService&method=Cobranca';
$restKey = '16a4f6bdf46bfb392fbb4788bf6c3c9df3ae7fd49acb79205627d6363706';

$payload = [
    'metodo'        => 'EMITIR_COBRANCA',
    'numRecLegado'  => 'TIT-2026-001',
    'companyToken'  => 'SEU_COMPANY_TOKEN',
    'bancoBacem'    => '033',
    'contaCorrente' => '1234567-8',
    'ambiente'      => 2,
    'valorNominal'  => '150.00',
    'dataemissao'   => date('Y-m-d'),
    'dataVencimento'=> date('Y-m-d', strtotime('+10 days')),
    'beneficiarioFinal' => [
        'cpfCnpj'   => '12345678000199',
        'nome'      => 'EMPRESA CREDORA LTDA',
        'tipoPessoa'=> 'J',
        'endereco'  => 'Av. Paulista, 1000',
        'bairro'    => 'Bela Vista',
        'cidade'    => 'São Paulo',
        'cep'       => '01310100',
        'uf'        => 'SP'
    ],
    'pagador' => [
        'cpfCnpj'   => '98765432100',
        'nome'      => 'Cliente Exemplo',
        'tipoPessoa'=> 'F',
        'email'     => 'cliente@email.com',
        'endereco'  => 'Rua das Flores, 123',
        'bairro'    => 'Centro',
        'cidade'    => 'Campinas',
        'cep'       => '13010000',
        'uf'        => 'SP'
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Basic ' . $restKey
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);
echo "Status: " . ($result['status_envio'] ?? 'ERRO');
Node.js (Axios)
const axios = require('axios');

async function emitir() {
  const url = 'https://api.seunome.com.br/rest?class=payloadRestService&method=Cobranca';
  const restKey = '16a4f6bdf46bfb392fbb4788bf6c3c9df3ae7fd49acb79205627d6363706';

  const res = await axios.post(url, {
    metodo: 'EMITIR_COBRANCA',
    numRecLegado: 'PEDIDO-9988',
    companyToken: 'SEU_COMPANY_TOKEN',
    bancoBacem: '033',
    contaCorrente: '1234567-8',
    ambiente: 2,
    valorNominal: '150.00',
    dataemissao: '2026-08-28',
    dataVencimento: '2026-09-10',
    beneficiarioFinal: {
      cpfCnpj: '12345678000199',
      nome: 'Minha Empresa',
      tipoPessoa: 'J',
      endereco: 'Rua A, 10',
      bairro: 'Centro',
      cidade: 'São Paulo',
      cep: '01001000',
      uf: 'SP'
    },
    pagador: {
      cpfCnpj: '11122233344',
      nome: 'Sacado Exemplo',
      tipoPessoa: 'F',
      email: 'sacado@email.com',
      endereco: 'Rua B, 20',
      bairro: 'Jardins',
      cidade: 'São Paulo',
      cep: '01402000',
      uf: 'SP'
    }
  }, {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Basic ${restKey}`
    }
  });

  console.log('Linha Digitável:', res.data.linha_digitavel);
  console.log('PIX Copia e Cola:', res.data.qr_code);
}

emitir();
Python (Requests)
import requests

url = "https://api.seunome.com.br/rest?class=payloadRestService&method=Cobranca"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic 16a4f6bdf46bfb392fbb4788bf6c3c9df3ae7fd49acb79205627d6363706"
}

payload = {
    "metodo": "EMITIR_COBRANCA",
    "numRecLegado": "PEDIDO-1234",
    "companyToken": "SEU_COMPANY_TOKEN",
    "bancoBacem": "033",
    "contaCorrente": "1234567-8",
    "ambiente": 2,
    "valorNominal": "150.00",
    "dataemissao": "2026-08-28",
    "dataVencimento": "2026-09-10",
    "beneficiarioFinal": {
        "cpfCnpj": "12345678000199",
        "nome": "Minha Empresa",
        "tipoPessoa": "J",
        "endereco": "Av Principal, 100",
        "bairro": "Centro",
        "cidade": "São Paulo",
        "cep": "01000000",
        "uf": "SP"
    },
    "pagador": {
        "cpfCnpj": "98765432100",
        "nome": "Cliente Exemplo",
        "tipoPessoa": "F",
        "email": "cliente@email.com",
        "endereco": "Rua Secundária, 50",
        "bairro": "Bairro B",
        "cidade": "Campinas",
        "cep": "13000000",
        "uf": "SP"
    }
}

response = requests.post(url, json=payload, headers=headers)
print("Status Code:", response.status_code)
print("Dados Retornados:", response.json())
Versão em Formato Markdown
O guia técnico completo em formato Markdown está armazenado em docs_md/guia_integracao_payload_rest_service.md para fácil inclusão em repositórios Git, Notion e wikis internas.
Abrir Arquivo Markdown