API da Orian

Uma API JSON para pôr contato, evento, negócio e venda dentro da Orian a partir do seu site, da sua loja ou do seu sistema. Tudo o que está aqui existe e responde hoje.

São quatro recursos. Não há endpoint de campanha, de mensagem nem de relatório — quando houver, entra aqui no mesmo dia.

Autenticação

Toda chamada leva a chave da conta no cabeçalho. A chave é criada em Configurações → Chaves, e cada uma carrega os escopos que você escolheu.

curl https://SEU-TINO/api/v1/contatos \
  -H "Authorization: Bearer SUA_CHAVE"

Chave revogada ou vencida para de valer no pedido seguinte — não há intervalo de tolerância.

Escopos

Cada chave só faz o que os escopos dela permitem, e escopo de leitura não dá escrita. Esta lista vem de `TODOS_OS_ESCOPOS`, a mesma constante que o servidor consulta para decidir.

contatos:ler
contatos:escrever
negocios:ler
negocios:escrever
mensagens:enviar
vendas:escrever
eventos:escrever

Contatos

As pessoas da base. Criar um contato é a porta de entrada de quase toda integração.

GET/api/v1/contatoscontatos:ler

Lista os contatos da conta, do mais recente para o mais antigo.

POST/api/v1/contatoscontatos:escrever

Cria um contato. Se o e-mail ou o telefone já existir na conta, o contato existente é reencontrado em vez de duplicado.

Campo	Tipo	Obrigatório
nome	string	simComo a pessoa se chama.
email	string	nãoServe como identificador: é por ele que o contato é reencontrado.
telefone	string	nãoTambém identifica. Guardado só com dígitos, para casar com o WhatsApp.
origem	string	nãoDe onde veio — aparece na ficha e nos relatórios de atribuição.

Eventos

Fatos que aconteceram com uma pessoa. É o que faz os fluxos dispararem e o score se mexer.

POST/api/v1/eventoseventos:escrever

Registra um evento no histórico do contato e aciona quem escuta aquele momento — fluxos e webhooks.

Campo	Tipo	Obrigatório
tipo	string	simO nome do fato. Tipos desconhecidos são recusados, e não gravados em silêncio.
contatoId	string	simDe quem é o fato. Um evento sem dono não tem onde pousar.

Negócios

As oportunidades do funil, com valor e etapa.

GET/api/v1/negociosnegocios:ler

Lista os negócios da conta.

POST/api/v1/negociosnegocios:escrever

Cria um negócio na primeira etapa do funil.

Campo	Tipo	Obrigatório
titulo	string	simO que está sendo vendido.
contatoId	string	nãoA pessoa dona da oportunidade.
empresaId	string	nãoA empresa, quando a venda é para uma pessoa jurídica.
valorCents	inteiro	nãoEm centavos, sempre inteiro. R$ 1.250,00 é 125000 — nunca 1250.5.

Vendas

O pedido da sua loja — pago, pendente ou abandonado. É por aqui que a loja avisa a Orian, e o cliente vira contato, negócio e linha do tempo.

POST/api/v1/vendasvendas:escrever

Registra uma venda. Reentrega do mesmo pedido não vira duas vendas — o identificador externo protege.

Campo	Tipo	Obrigatório
externalId	string	simO id do pedido na SUA loja. Aceita também pedidoId ou id. É ele que impede o webhook reentregue de virar duas vendas.
totalCents	inteiro	simEm centavos, inteiro.
situacao	string	nãopaga, pendente, cancelada ou abandonada. Aceita também status; quando não vem, assume "paga". "abandonada" é o carrinho que a pessoa montou e não fechou: ele nasce como negócio ABERTO no funil e dispara o gatilho "Carrinho abandonado". Se ela voltar e pagar, reenvie o MESMO externalId com "paga" — o mesmo negócio vira ganho, sem virar dois.
comprador	objeto	simAceita também cliente. Dentro: nome (ou name), email, telefone (ou phone).

Erros

O corpo do erro traz sempre um campo erro com a frase em português, escrita para quem está integrando — não o texto interno do banco.

400 — o corpo não é JSON, ou falta um campo obrigatório.
401 — chave ausente, revogada ou vencida.
403 — a chave existe, mas não tem o escopo daquela chamada.
429 — passou do teto de chamadas. Espere e repita.

Webhooks

O caminho inverso: a Orian avisa o seu sistema quando um fato acontece. Você cadastra a URL em Configurações → Webhooks, escolhe os eventos, e cada entrega vai assinada — a assinatura amarra o corpo e o instante, então uma entrega antiga não pode ser reaproveitada.

Entrega que falha é repetida com espera crescente, e para de tentar depois de um tempo — em vez de bater no seu servidor para sempre.