📖 SGP API — Documentação

Visão Geral

A SGP API (Sistema de Gestão de Proteção) permite que sistemas terceiros consultem e gerenciem registros de inadimplentes de forma programática. A API segue os princípios REST, utiliza JSON para payloads e suporta autenticação via token.

Autenticação

Todas as requisições devem incluir o token de acesso no header Authorization. O token é gerado por cliente na página Configurações da API dentro da Central do Cliente.

# Formato do header
Authorization: {seu_token_aqui}

Restrição por IP

É recomendado configurar os IPs permitidos na página de configurações da API. Quando configurado, apenas requisições originadas dos IPs cadastrados serão aceitas.

Formatos

O formato de entrada e saída é JSON (application/json). Para requisições POST, envie o corpo como JSON e o header Content-Type: application/json.

Tratamento de Erros

A API utiliza códigos HTTP padrão para indicar o resultado das operações:

Código	Descrição
200	Requisição bem-sucedida
201	Recurso criado com sucesso
400	Parâmetro obrigatório ausente ou inválido
401	API key inválida ou não fornecida
403	Acesso negado (token sem permissão para o endpoint)
404	Recurso não encontrado
405	Método HTTP não permitido para o endpoint

Erros retornam um JSON no formato: {"error": "mensagem de erro"}

---

Consultar Inadimplentes por Documento

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
documento	string	URL	Obrigatório	CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita com ou sem pontuação.
Authorization	string	Header	Obrigatório	Token de autenticação do cliente.

Exemplo de requisição

# Consultar CPF
GET https://confiaisp.com.br/api/v1/consulta/000.000.000-00
Authorization: seu_token_aqui

Exemplo de resposta

{
  "documento": "000.000.000-00",
  "total": 2,
  "registros": [
    {
      "id": 1,
      "nome": "João da Silva",
      "documento": "000.000.000-00",
      "valor_divida": "1500.00",
      "data_vencimento": "2026-06-15",
      "status": "ativo"
    }
  ]
}

---

Inadimplentes

Gerenciamento completo dos registros de inadimplentes do cliente.

Listar Inadimplentes

Exemplo de resposta

[
  {
    "id": 1,
    "nome": "João da Silva",
    "documento": "000.000.000-00",
    "telefone": "11999999999",
    "email": "joao@email.com",
    "valor_divida": "1500.00",
    "data_vencimento": "2026-06-15",
    "score": 825,
    "status": "ativo",
    "cidade": "São Paulo",
    "uf": "SP",
    "created_at": "2026-07-25 12:00:00"
  }
]

Obter Inadimplente por ID

Parâmetro	Tipo	Local	Obrigatório	Descrição
id	int	URL	Obrigatório	ID do registro de inadimplente.

Cadastrar Inadimplente

Parâmetros do corpo (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
documento	string	Sim	CPF ou CNPJ do devedor.
nome	string	Sim	Nome completo do devedor.
valor_divida	float	Sim	Valor da dívida em reais.
data_nascimento	string	Não	Data de nascimento (formato YYYY-MM-DD).
telefone	string	Não	Telefone de contato.
email	string	Não	Email de contato.
endereco	string	Não	Endereço completo.
cidade	string	Não	Cidade.
uf	string	Não	UF (2 letras).
data_vencimento	string	Não	Data de vencimento da dívida (YYYY-MM-DD).
descricao	string	Não	Descrição ou observação sobre a dívida.

Exemplo de requisição

POST https://confiaisp.com.br/api/v1/inadimplentes
Authorization: seu_token_aqui
Content-Type: application/json

{
  "documento": "000.000.000-00",
  "nome": "João da Silva",
  "valor_divida": 1500.00,
  "data_vencimento": "2026-08-15",
  "telefone": "11999999999",
  "email": "joao@email.com",
  "cidade": "São Paulo",
  "uf": "SP"
}

Exemplo de resposta

{
  "id": 42
}

Excluir Inadimplente

Parâmetro	Tipo	Local	Obrigatório	Descrição
id	int	URL	Obrigatório	ID do registro a ser excluído.

Exemplo de resposta

{ "ok": true }

---

Webhook de Notificação

A SGP API pode notificar seu sistema sempre que houver atualizações. Configure a URL do webhook na página Configurações da API.

Formato do Payload

Quando ativado, o webhook enviará uma requisição POST com o seguinte JSON:

{
  "evento": "inadimplente.criado",
  "data": {
    "id": 42,
    "documento": "000.000.000-00",
    "nome": "João da Silva",
    "valor_divida": 1500.00
  },
  "timestamp": "2026-07-27T12:00:00Z"
}

Eventos Suportados

Evento	Descrição
inadimplente.criado	Um novo registro de inadimplente foi criado
inadimplente.atualizado	Um registro existente foi atualizado
inadimplente.excluido	Um registro foi removido

---

Exemplos de Código

cURL

# Consultar CPF
curl -s -H "Authorization: SEU_TOKEN" \
  https://confiaisp.com.br/api/v1/consulta/000.000.000-00

# Cadastrar inadimplente
curl -s -X POST \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documento":"000.000.000-00","nome":"João","valor_divida":1500}' \
  https://confiaisp.com.br/api/v1/inadimplentes

# Listar inadimplentes
curl -s -H "Authorization: SEU_TOKEN" \
  https://confiaisp.com.br/api/v1/inadimplentes

# Excluir inadimplente
curl -s -X DELETE \
  -H "Authorization: SEU_TOKEN" \
  https://confiaisp.com.br/api/v1/inadimplentes/42

PHP

// Consultar inadimplentes por documento
$token = 'SEU_TOKEN_AQUI';
$documento = '000.000.000-00';

$ch = curl_init("https://confiaisp.com.br/api/v1/consulta/$documento");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: $token"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

JavaScript (Fetch)

// Consultar inadimplentes
const token = 'SEU_TOKEN_AQUI';
const documento = '000.000.000-00';

fetch(`https://confiaisp.com.br/api/v1/consulta/${documento}`, {
  headers: { 'Authorization': token }
})
  .then(res => res.json())
  .then(data => console.log(data));

// Cadastrar inadimplente
fetch('https://confiaisp.com.br/api/v1/inadimplentes', {
  method: 'POST',
  headers: {
    'Authorization': token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    documento: '000.000.000-00',
    nome: 'João da Silva',
    valor_divida: 1500.00
  })
})
  .then(res => res.json())
  .then(data => console.log(data));

Python

# Consultar inadimplentes
import requests

token = 'SEU_TOKEN_AQUI'
documento = '000.000.000-00'
headers = {'Authorization': token}

response = requests.get(
    f'https://confiaisp.com.br/api/v1/consulta/{documento}',
    headers=headers
)
print(response.json())

# Cadastrar inadimplente
payload = {
    'documento': '000.000.000-00',
    'nome': 'João da Silva',
    'valor_divida': 1500.00
}
response = requests.post(
    'https://confiaisp.com.br/api/v1/inadimplentes',
    headers=headers,
    json=payload
)
print(response.json())