Blue Credit API

Odoo/Uncategorized · v19.0.1.2.0 · LGPL-3

API REST pública para consultas de crédito e veículos via FastAPI

Dependências

blue_credit_query, fastapi, auth_api_key_group

Documentação

Camada FastAPI do Odoo para o contrato público em https://api.conexaoazul.com/api/v1.

Endpoints

Método	Caminho	Autenticação	Uso
GET	/credit/integrations	Pública	Catálogo com preço público Essencial
GET	/credit/integrations/me	HTTP-API-KEY	Catálogo com preço real do cliente
POST	/credit/query	HTTP-API-KEY	Consulta síncrona legada
POST	/credit/query/async	HTTP-API-KEY + Idempotency-Key	Consulta durável via OCA queue_job
GET	/credit/result/{request_id}	HTTP-API-KEY	Polling autenticado do resultado

Autorização

Uma chave criptograficamente válida não concede acesso sozinha. O usuário e o parceiro precisam estar ativos, e o parceiro precisa possuir credit_api_enabled=True.

O campo credit_api_allowed_integration_ids permite limitar uma chave a produtos específicos. Se estiver vazio, o cliente pode acessar as integrações ativas disponíveis para sua empresa.

Chaves OCA continuam obrigadas a pertencer ao grupo Blue Credit API Keys. Chaves nativas do Odoo passam pela mesma autorização explícita do parceiro. Falhas 401 e 403 também devolvem X-Request-ID.

Segredos

O token do fornecedor é restrito a administradores. A máscara visual da tela não é tratada como controle de segurança.

Em produção, prefira definir no provider:

api_key_env_var = BLUE_CREDIT_PROVIDER_API_KEY

O entrypoint lê o Docker Secret blue_credit_provider_api_key e exporta essa variável. O campo api_key permanece somente como fallback de compatibilidade.

Processamento assíncrono

O endpoint /query/async:

1. valida autenticação, autorização, integração e documento;
2. calcula o preço pela lista nativa do cliente;
3. bloqueia rapidamente a linha de saldo;
4. desconta as reservas já existentes;
5. cria uma requisição idempotente no PostgreSQL;
6. agenda _job_process no canal root.blue_credit do OCA queue_job;
7. devolve 202, request_id e poll_url.

O job executa em transação própria, tenta os provedores permitidos por prioridade, cria o histórico e debita o saldo somente após uma resposta concluída. O fluxo assíncrono faz uma tentativa por provider em cada execução; o calendário de retries pertence ao OCA, evitando retries internos multiplicados por retries da fila.

Os estados terminais e reprocessamentos de queue.job são sincronizados com blue.credit.api.request. Jobs falhos liberam a reserva; jobs reenfileirados recuperam a reserva e voltam a aparecer como queued/running.

As cópias operacionais terminais expiram após 30 dias por @api.autovacuum. O histórico comercial permanece preservado.

Idempotência

Idempotency-Key deve possuir de 8 a 128 caracteres alfanuméricos ou ., _, : e -.

• mesma chave e mesmo payload: retorna a requisição existente;
• mesma chave e payload diferente: retorna 409 Conflict;
• concorrência simultânea é protegida por savepoint e restrição SQL;
• job ativo relacionado impede novo agendamento;
• retry do cliente deve sempre reutilizar a mesma chave.

Roteamento de providers

Cada integração pode possuir api_provider_ids. O campo api_priority define a ordem, com o menor número sendo tentado primeiro.

Sem vínculo explícito, somente um único provider compatível pode ser inferido. Dois ou mais providers compatíveis fazem a API falhar de forma segura até que o administrador configure o mapeamento. Integrações brasilapi_* consideram providers BrasilAPI; as demais consideram providers não BrasilAPI.

OCA queue_job 19.0

A imagem baixa OCA/queue na branch 19.0. O runtime precisa iniciar com:

server_wide_modules = base,web,blue_ops_health,queue_job

[queue_job]
channels = root:4,root.blue_credit:2

Variáveis suportadas:

ODOO_QUEUE_JOB_CHANNELS
ODOO_QUEUE_JOB_SCHEME
ODOO_QUEUE_JOB_HOST
ODOO_QUEUE_JOB_PORT

Gateway Cloudflare

O gateway não enfileira mais requests na Cloudflare e não grava API keys, headers, cookies, documentos ou corpos em KV/Queues.

A borda agora:

• identifica HTTP-API-KEY corretamente;
• deriva uma fingerprint HMAC para rate limit;
• usa o binding nativo BLUE_CREDIT_RATE_LIMITER;
• mantém KV apenas como fallback de sandbox;
• devolve 503 e Retry-After quando o origin está indisponível;
• encaminha o polling autenticado ao Odoo.

Antes do deploy do Worker:

wrangler secret put RATE_LIMIT_HMAC_SECRET

No cutover real, ORIGIN_BASE_URL deve apontar para um hostname de origem distinto da rota pública do Worker, evitando recursão de gateway.

O antigo blue-credit-consumer foi removido. As Cloudflare Queues credit-query-queue e credit-query-dlq podem ser desativadas após confirmar que nenhum deployment antigo ainda publica mensagens.

Upgrade 19.0.1.3.0

A publicação da imagem não executa instalação ou migração sozinha. Instale o OCA queue_job e atualize a API explicitamente:

odoo --config=/tmp/odoo.conf \
  -d consultas \
  --init=queue_job \
  --update=blue_credit_api \
  --stop-after-init \
  --no-http

A migração é fail-closed: habilita automaticamente apenas parceiros vinculados a chaves OCA ativas do grupo Blue Credit API Keys e o parceiro do usuário técnico blue_credit_api. Clientes que usam chave nativa precisam ser autorizados manualmente no parceiro.

Depois do upgrade, valide:

• queue_job instalado e runner iniciado;
• canal root.blue_credit disponível;
• clientes autorizados com credit_api_enabled=True;
• Docker Secret do provider montado e api_key_env_var configurado;
• /query/async devolvendo 202;
• polling rejeitando requests de outro parceiro;
• retry simultâneo com a mesma Idempotency-Key sem cobrança ou job duplicado;
• falha final do OCA refletida como error na requisição;
• Worker sem bindings de Cloudflare Queue.

Rastreamento

A API aceita e devolve X-Request-ID. Falhas internas retornam mensagens genéricas; logs devem usar IDs, integração e documento mascarado, nunca credenciais ou documentos completos.

Documentação pública

• Portal: https://docs.conexaoazul.com/
• OpenAPI: https://docs.conexaoazul.com/openapi.json