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.
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.).
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):
Authorization: Basic {REST_KEY}. A chave REST autentica o cliente junto ao motor REST do Adianti Framework.
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.
{
"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"
}
}
{
"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.
{
"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.
{
"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.
{
"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:
{
"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 -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
$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');
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();
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())
docs_md/guia_integracao_payload_rest_service.md para fácil inclusão em repositórios Git, Notion e wikis internas.