API v1

Documentação da API urbOS

Receba e envie dados do urbOS para qualquer plataforma. Integre seu sistema, QR Code, landing page ou automação com o CRM imobiliário da sua empresa.

Autenticação segura

API Keys com hash SHA-256 e permissões granulares

Webhooks em tempo real

Receba eventos do sistema instantaneamente

CORS habilitado

Integre de qualquer origem e plataforma

Base URL

https://seu-dominio.com.br/api/v1

Início Rápido

Em 3 passos simples você integra seu sistema com o urbOS:

Gere uma chave de API

Acesse Configurações → Integrações → Chaves da API no painel do urbOS e clique em "Gerar nova chave". Copie a chave gerada.

Envie sua primeira requisição

Use a chave no header Authorization para cadastrar um lead via POST /api/v1/leads.

Configure webhooks (opcional)

Em Configurações → Integrações → Webhooks, crie gatilhos para receber dados quando eventos acontecem no urbOS.

Teste rápido — cURL

curl -X POST https://seu-dominio.com.br/api/v1/leads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer urbos_SUA_CHAVE_AQUI" \
  -d '{
    "name": "Maria Silva",
    "phone": "(45) 99999-1234",
    "email": "maria@email.com",
    "source": "Quires"
  }'

Autenticação

Todas as requisições à API devem incluir uma chave de API válida. As chaves são geradas no painel do urbOS em Configurações → Integrações → Chaves da API.

A chave é exibida apenas uma vez no momento da criação. Se perdida, gere uma nova chave. Cada chave tem permissões configuráveis (ex: leads:write).

Headers de Autenticação

Você pode enviar a chave de duas formas:

Opção 1 — Authorization Bearer (recomendado)

Authorization: Bearer urbos_sua_chave_aqui

Opção 2 — Header X-Api-Key

X-Api-Key: urbos_sua_chave_aqui

Importante: Nunca exponha sua chave de API no código frontend (HTML, JavaScript do navegador). Use-a apenas no backend do seu servidor ou em ferramentas server-side como Make, n8n, Zapier.

Criar Lead

POST/api/v1/leads

Cadastra um novo lead/contato no sistema. O lead será automaticamente direcionado para o rodízio de corretores e os webhooks configurados serão disparados.

Parâmetros do body (JSON)

namestring

obrigatórioNome completo do cliente

phonestring

obrigatórioTelefone com DDD. Ex: (45) 99999-1234

sourcestring

obrigatórioMídia de origem do lead. Ex: "Quires", "Google Ads", "Site"

emailstring

E-mail do cliente

propertyIdstring

ID do imóvel relacionado (se aplicável)

messagestring

Mensagem ou observação do cliente

metadataobject

Dados extras em formato livre (JSON)

Resposta de sucesso (201)

Resposta — 201 Created

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Maria Silva",
    "phone": "(45) 99999-1234",
    "email": "maria@email.com",
    "source": "Quires",
    "status": "new",
    "createdAt": "2025-03-06T18:30:00.000Z"
  },
  "message": "Lead cadastrado com sucesso"
}

Webhooks

Webhooks permitem que o urbOS envie dados automaticamente para o seu sistema quando determinados eventos acontecem. Configure os webhooks em Configurações → Integrações → Webhooks.

O urbOS faz uma requisição POST para a URL configurada com o payload do evento. Se o endpoint não responder com status 2xx, o urbOS contabiliza como falha (visível no painel).

Eventos Disponíveis

Evento	Descrição
`lead.created`	Quando um novo lead é cadastrado no sistema
`lead.updated`	Quando um lead é atualizado
`contact.created`	Quando um novo contato é cadastrado
`contact.updated`	Quando um contato é atualizado
`deal.created`	Quando um novo negócio entra no funil
`deal.stage_changed`	Quando um deal muda de etapa no funil
`deal.won`	Quando um negócio é marcado como ganho
`deal.lost`	Quando um negócio é marcado como perdido
`property.created`	Quando um novo imóvel é cadastrado
`property.updated`	Quando um imóvel é atualizado
`property.sold`	Quando um imóvel é marcado como vendido
`visit.scheduled`	Quando uma visita é agendada
`contract.created`	Quando um contrato é gerado
`contract.signed`	Quando um contrato é assinado digitalmente
`capture.received`	Quando uma captação do site é recebida

Formato do Payload

Cada evento envia um POST com o seguinte formato:

Payload do webhook

{
  "event": "lead.created",
  "timestamp": "2025-03-06T18:30:00.000Z",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Maria Silva",
    "phone": "(45) 99999-1234",
    "email": "maria@email.com",
    "source": "Quires",
    "status": "new",
    "createdAt": "2025-03-06T18:30:00.000Z"
  }
}

Headers enviados pelo urbOS:

Content-Type: application/json

X-urbOS-Event: lead.created

X-urbOS-Delivery: uuid-unico-do-envio

Authorization: seu-header-de-autorizacao (se configurado)

Exemplos de Integração

cURL

curl -X POST https://seu-dominio.com.br/api/v1/leads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer urbos_SUA_CHAVE" \
  -d '{
    "name": "João Santos",
    "phone": "(45) 98888-7777",
    "email": "joao@email.com",
    "source": "Quires",
    "message": "Interessado no imóvel próximo ao parque"
  }'

JavaScript / Node.js

Node.js (fetch)

const response = await fetch('https://seu-dominio.com.br/api/v1/leads', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer urbos_SUA_CHAVE',
  },
  body: JSON.stringify({
    name: 'João Santos',
    phone: '(45) 98888-7777',
    email: 'joao@email.com',
    source: 'Quires',
  }),
});

const data = await response.json();
console.log(data);
// { success: true, data: { id: "...", name: "João Santos", ... } }

Python

Python (requests)

import requests

response = requests.post(
    'https://seu-dominio.com.br/api/v1/leads',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer urbos_SUA_CHAVE',
    },
    json={
        'name': 'João Santos',
        'phone': '(45) 98888-7777',
        'email': 'joao@email.com',
        'source': 'Quires',
    }
)

print(response.json())
# {'success': True, 'data': {'id': '...', 'name': 'João Santos', ...}}

PHP

PHP (cURL)

<?php
$ch = curl_init('https://seu-dominio.com.br/api/v1/leads');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer urbos_SUA_CHAVE',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name'   => 'João Santos',
        'phone'  => '(45) 98888-7777',
        'email'  => 'joao@email.com',
        'source' => 'Quires',
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
// ['success' => true, 'data' => ['id' => '...', 'name' => 'João Santos', ...]]

Códigos de Erro

Status	Significado	Como resolver
`201`	Criado com sucesso	Tudo certo! O recurso foi criado.
`400`	Requisição inválida	Verifique se os campos obrigatórios (name, phone, source) estão presentes.
`401`	Não autorizado	Verifique se a chave de API está correta e ativa.
`403`	Sem permissão	A chave não tem a permissão necessária. Edite as permissões no painel.
`429`	Muitas requisições	Aguarde um momento e tente novamente.
`500`	Erro interno	Erro no servidor. Se persistir, entre em contato com o suporte.

Limites de Uso

Requisições por minuto: 60 por chave de API

Requisições por hora: 1.000 por chave de API

Tamanho máximo do body: 1 MB

Timeout de webhook: 10 segundos

Se precisar de limites maiores, entre em contato conosco.

Suporte

Precisa de ajuda com a integração? Entre em contato:

E-mail: dev@urbos.com.br

WhatsApp: (45) 99999-0000

Envie o nome da sua empresa, a chave de API (mascarada) e a descrição do problema.

urbOS API v1 — Documentação para desenvolvedores