API de Webhook — Documentação Técnica

O módulo bitconn_webhook expõe uma API JSON REST genérica para integração com sistemas externos.

Autenticação

A API aceita dois métodos de autenticação:

API Key (Header)

curl -H "X-API-Key: sua-chave-aqui" https://odoo/webhook/...

Bearer Token

curl -H "Authorization: Bearer seu-token" https://odoo/webhook/...

A chave/token é configurada por endpoint no Odoo. Cada endpoint pode ter seu próprio token.

Endpoints

search_read — Buscar registros

GET /webhook/bitconn/search_read

Parâmetros:

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | model | string | Sim | Modelo Odoo (ex: res.partner, account.move) | | domain | JSON array | Não | Domain filter Odoo | | fields | JSON array | Não | Campos a retornar | | limit | int | Não | Limite de resultados (default: 100) | | offset | int | Não | Offset de paginação |

Exemplo:

curl -X GET \
  "https://odoo.seudominio.com/webhook/bitconn/search_read?model=account.move&domain=[['state','=','posted']]&fields=['name','amount_total','partner_id']&limit=50" \
  -H "Authorization: Bearer seu-token"

Resposta:

{
  "jsonrpc": "2.0",
  "id": null,
  "result": [
    {
      "id": 42,
      "name": "FAT/2024/001",
      "amount_total": 99.90,
      "partner_id": [15, "Cliente Exemplo Ltda"]
    }
  ]
}

create — Criar registro

POST /webhook/bitconn/create

Body:

{
  "model": "res.partner",
  "values": {
    "name": "Novo Cliente",
    "email": "cliente@exemplo.com",
    "phone": "+55 11 99999-9999"
  }
}

Resposta:

{
  "jsonrpc": "2.0",
  "id": null,
  "result": {"id": 101, "name": "Novo Cliente"}
}

write — Atualizar registro

PUT /webhook/bitconn/write

Body:

{
  "model": "res.partner",
  "ids": [101],
  "values": {
    "phone": "+55 11 88888-8888"
  }
}

unlink — Remover registro

DELETE /webhook/bitconn/unlink

Body:

{
  "model": "res.partner",
  "ids": [101]
}

Extração de Dados Aninhados (Relation Specs)

A API suporta busca de dados em registros relacionados usando relation specs. Especifique um dicionário no lugar do nome do campo:

{
  "fields": [
    "name",
    "amount_total",
    {
      "partner_id": [
        "name",
        "email",
        "phone",
        {"category_id": ["name"]}
      ]
    }
  ]
}

Isso retorna os dados do parceiro e sua categoria aninhados na resposta, sem precisar de múltiplas chamadas.

Log de Requisições

Cada chamada à API é registrada com:

Acesse o log em Webhook → Log de Requisições no Odoo.

Rate Limiting

Por padrão, cada endpoint aceita até 100 requisições por minuto por IP. Excedido o limite, retorna HTTP 429.

O limite é configurável por endpoint.