Documentação da API

Como ler e gravar seus dados (serviços, produtos, clientes, vendas e usuários) pelos seus sistemas.

Para que serve: integrar o Orka com outro sistema seu — um ERP, um site, uma planilha automatizada, um e-commerce. Tudo o que você faz nas telas você também consegue fazer por aqui. Disponível no plano Business.
1. Endereço base
https://raj.tec.br/api/v1

Todas as chamadas usam esse endereço + o nome do recurso. Exemplo: https://raj.tec.br/api/v1/servicos.

2. Autenticação

Toda requisição precisa de uma chave de API no cabeçalho Authorization. Gere e gerencie suas chaves em Gestão → Integrações → API, dentro do Orka. A chave começa com rjt_live_ e só aparece uma vez — guarde num lugar seguro.

Authorization: Bearer rjt_live_xxxxxxxxxxxxxxxxxxxxxxxx

Cada chave tem escopos: <recurso>:read libera leitura (GET) e <recurso>:write libera criar, alterar e excluir (POST/PUT/DELETE). Uma chave só de leitura de clientes, por exemplo, não consegue criar pedidos.

3. Formato das respostas

Tudo é JSON. As listagens vêm paginadas — use ?per_page= (padrão 20) e ?search= para filtrar.

curl "https://raj.tec.br/api/v1/servicos?tipo=produto&per_page=50" \
  -H "Authorization: Bearer SUA_CHAVE"
4. Limite de uso

Até 600 requisições por minuto por chave (plano Business). Se passar, a resposta vem com status 429 e o cabeçalho Retry-After dizendo quantos segundos esperar. Espalhe as chamadas ao longo do tempo em vez de disparar tudo de uma vez.

5. Erros

Erro sempre volta assim: { "success": false, "message": "..." }, com um destes status:

StatusSignifica
401Chave ausente, inválida ou revogada.
402Seu plano não inclui a API. Faça upgrade para o Business.
403A chave não tem o escopo necessário para essa ação.
404Registro não encontrado (ou de outra empresa).
422Dados inválidos — a mensagem diz qual campo.
429Passou do limite de requisições por minuto.
6. Recursos
Serviços e Produtos — /servicos

Produto e serviço são o mesmo recurso. Para produto, mande "tipo": "produto" (e o estoque); para serviço, "tipo": "servico".

Criar um produto:

curl -X POST "https://raj.tec.br/api/v1/servicos" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Camiseta branca P",
    "tipo": "produto",
    "preco": 79.90,
    "estoque": 12,
    "descricao": "Algodão, gola redonda"
  }'

Resposta (201):

{ "uuid": "9f1c…", "nome": "Camiseta branca P", "tipo": "produto", "preco": 79.9, "estoque": 12 }

Listar só produtos: GET /servicos?tipo=produto · Alterar: PUT /servicos/{uuid} · Excluir: DELETE /servicos/{uuid}

Vendeu ou repôs fora do Orka? Ajuste só o estoque, sem mandar o produto inteiro: PATCH /servicos/{uuid}/estoque com { "delta": -3 } (vendeu 3) ou { "delta": 5 } (repôs 5). É seguro com vendas acontecendo ao mesmo tempo e nunca deixa o estoque negativo (responde 422).

Clientes — /clientes
curl -X POST "https://raj.tec.br/api/v1/clientes" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria Souza",
    "tipo_pessoa": "fisica",
    "cpf_cnpj": "123.456.789-00",
    "email": "[email protected]",
    "telefone": "(11) 98888-7777"
  }'

Buscar por nome/documento: GET /clientes?search=maria · Detalhe com endereços e telefones: GET /clientes/{uuid}

Vendas / OS — /pedidos

POST /pedidos cria um rascunho e já aplica o que você mandar no corpo (cliente, itens, valores). Depois use PUT /pedidos/{uuid} para atualizar.

curl -X POST "https://raj.tec.br/api/v1/pedidos" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente_uuid": "a1b2…",
    "itens": [
      { "servico_uuid": "9f1c…", "quantidade": 2, "valor_unitario": 79.90 }
    ],
    "observacoes": "Entregar até sexta"
  }'

Listar: GET /pedidos · Detalhe com itens: GET /pedidos/{uuid}

Códigos de status, pagamento e lojas — /config

Só leitura, funciona com qualquer chave. Traz os códigos (uuid) dos status da venda/OS, dos status de pagamento, das formas de pagamento e das suas redes e lojas — use no corpo do pedido em vez de copiar da tela. Se a chave estiver presa a uma loja, só ela aparece.

curl "https://raj.tec.br/api/v1/config" -H "Authorization: Bearer SUA_CHAVE"
{ "success": true, "data": {
  "status_pedido":    [{ "uuid": "…", "slug": "pedido_aberto", "label": "Venda Aberta", "ordem": 12 }],
  "status_pagamento": [{ "uuid": "…", "slug": "pendente", "label": "Pendente" }],
  "formas_pagamento": [{ "uuid": "…", "codigo": "PIX", "label": "PIX", "tipo": "pix", "prazo_dias": 0 }],
  "redes": [{ "uuid": "…", "nome": "Minha empresa", "lojas": [{ "uuid": "…", "nome": "Centro", "ativa": true }] }]
} }
Usuários — /usuarios
curl -X POST "https://raj.tec.br/api/v1/usuarios" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Vendedor",
    "email": "[email protected]",
    "password": "uma-senha-forte",
    "perfil": "vendedor"
  }'

O usuário criado entra na sua empresa, na unidade em que a chave está vinculada.

Fornecedores — /fornecedores
curl -X POST "https://raj.tec.br/api/v1/fornecedores" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Distribuidora Boa Vista",
    "cpf_cnpj": "11.222.333/0001-81",
    "email": "[email protected]",
    "telefone": "11999990000"
  }'

Listar: GET /fornecedores · Alterar: PUT /fornecedores/{uuid} · Excluir: DELETE /fornecedores/{uuid}

7. Referência completa

Todos os endpoints, gerada automaticamente (padrão OpenAPI 3.1):

Carregando…

Arquivo do contrato: /api/v1/openapi.json — importe no Postman, Insomnia ou gerador de SDK.

Testar grátis por 60 dias Ver planos