Contracts — external systems

Esta página detalha os contratos de integração com sistemas externos: payload shape, campos obrigatórios, autenticação, idempotência. A página API (Try It) cobre Bubble↔Backend; esta cobre Backend↔(HubSpot, Pagar.me, Omie).

Nota

Source canonical: Confluence 3813539856 (Mapeamento Payload — Versão Atual). Esta página é o espelho navegável e versionado no repo.

HubSpot — Webhook deal.propertyChange

HubSpot dispara webhook mínimo — só ID do deal + propriedade mudada. Backend faz call adicional pra obter dados completos.

Fluxo obrigatório

1. Receber webhook com objectId do deal
2. Validar assinatura X-HubSpot-Signature-v3
3. GET https://api.hubspot.com/crm/v3/objects/deals/{objectId}?properties=...
4. Extrair campos necessários
5. Criar pedido na Blueprintt

Payload do webhook

[
  {
    "eventId": 1234567890,
    "subscriptionId": 98765,
    "portalId": 62515,
    "appId": 123456,
    "occurredAt": 1673981400000,
    "subscriptionType": "deal.propertyChange",
    "attemptNumber": 0,
    "objectId": 67890,
    "propertyName": "dealstage",
    "propertyValue": "closedwon",
    "changeSource": "CRM"
  }
]

Campos necessários (buscar via API pós-webhook)

Campo Blueprintt	Campo interno	Campo HubSpot	Obrigatório	Observação
ID do deal	hubspot_deal_id	objectId (do webhook)	Sim	Chave de idempotência
CNPJ/CPF	cliente.cpf_cnpj	A validar (propriedade customizada)	Sim	P01 pendente
Nome / razão social	cliente.nome	dealname ou customizada	Sim	A validar
E-mail	cliente.email	A validar	Sim	Pode vir do contato associado
ID do evento	evento.id	A validar	Sim	P02 pendente
Nome do evento	evento.nome	A validar	Sim	—
Data do evento	evento.data	A validar	Sim	—
Valor	pedido.valor_total	amount	Sim	P04 — confirmar centavos vs reais
Vendedor	vendedor.email	hubspot_owner_id → buscar e-mail	Não	P05 — mapear por e-mail
Participantes	pedido.participantes	A validar	Sim	P03 pendente
Data fechamento	pedido.criado_em	closedate	Sim	—

Cuidado

hubspot_owner_id é inteiro. Segunda chamada obrigatória: GET /crm/v3/owners/{ownerId} pra resolver o e-mail.

Autenticação

Header: X-HubSpot-Signature-v3
Algoritmo: HMAC-SHA256
String assinada: {method}{URI}{body}{timestamp}
Secret: HUBSPOT_WEBHOOK_SECRET
Janela: 5 minutos

Idempotência

Chave: eventId + objectId. Reentregas duplicadas detectadas e ignoradas.

Cuidado

ADR-5: HubSpot Fase 2 está fora do escopo Versão Atual (Decisions). Contrato mantido aqui pra revisita futura.

Pagar.me — webhooks charge.*

Todos os webhooks Pagar.me seguem estrutura raiz comum.

Estrutura geral

{
  "id": "hook_XXXXXXXXX",
  "account": {
    "id": "acc_XXXXXXXXX",
    "name": "Nome da conta"
  },
  "type": "charge.paid",
  "created_at": "2024-01-01T10:00:00Z",
  "data": { ... }
}

Autenticação

Header: X-Hub-Signature
Algoritmo: HMAC-SHA256
Secret: PAGARME_WEBHOOK_SECRET
Retornar HTTP 200 imediato
Processar assíncrono

Perigo

ADR-7: Pagar.me webhook vai direto ao backend, não pelo Bubble. Ver Decisions.

charge.paid — pagamento confirmado

Campo Blueprintt	Campo interno	Campo Pagar.me	Tipo	Observação
ID da cobrança	cobranca.id_pagarme	data.id	String	Ex: ch_XXXXXXXXX
ID do pedido	pedido.id	data.metadata.blueprintt_order_id	String	P06 — backend envia no metadata ao criar cobrança
Status	—	data.status	String	Esperado: paid
Valor pago	cobranca.valor_pago	data.paid_amount	Integer	Em centavos — dividir por 100
Meio de pagamento	cobranca.meio_pagamento	data.payment_method	String	credit_card · boleto · pix
Data pagamento	cobranca.pago_em	data.paid_at	ISO 8601	—
CPF/CNPJ pagador	—	data.customer.document	String	Conferência

charge.canceled — pagamento cancelado

Campo Blueprintt	Campo interno	Campo Pagar.me	Tipo
ID cobrança	cobranca.id_pagarme	data.id	String
ID pedido	pedido.id	data.metadata.blueprintt_order_id	String
Status	—	data.status	String (esperado: canceled)
Valor cancelado	—	data.canceled_amount	Integer (centavos)
Data cancelamento	—	data.canceled_at	ISO 8601

charge.boleto_expired — boleto expirado

Campo Blueprintt	Campo interno	Campo Pagar.me	Tipo
ID cobrança	cobranca.id_pagarme	data.id	String
ID pedido	pedido.id	data.metadata.blueprintt_order_id	String
Status	—	data.status	String (esperado: failed)

Criação de cobrança — Blueprintt envia

Campo	Campo Pagar.me	Obrigatório	Observação
Valor	amount	Sim	Em centavos
Meio	payment_method	Sim	credit_card · boleto · pix
ID pedido interno	metadata.blueprintt_order_id	Sim	Crítico — idempotência + rastreabilidade
Idempotency	Header Idempotency-Key	Sim	UUID único por pedido
Cliente	customer.name, customer.email, customer.document	Sim	—

Omie — contratos de API

Todas as chamadas usam app_key + app_secret no corpo da requisição. Credenciais distintas por empresa faturadora (ADR-1: AABC only na Versão Atual).

Autenticação

{
  "app_key": "{{OMIE_APP_KEY_AABC}}",
  "app_secret": "{{OMIE_APP_SECRET_AABC}}",
  "call": "NomeDoMetodo",
  "param": [{ ... }]
}

Base URL: https://app.omie.com.br/api/v1/

Cliente — IncluirCliente / ListarClientes

Busca antes de criar (idempotência):

POST /geral/clientes/
call: ListarClientes
Filtrar por: cnpj_cpf

Campos enviados na criação:

Campo Blueprintt	Campo Omie	Tipo	Obrigatório	Fonte
Razão social / Nome	razao_social	String	Sim	Cadastro Blueprintt
CNPJ ou CPF	cnpj_cpf	String	Sim	Cadastro
E-mail	email	String	Sim	Cadastro
Tipo (PF/PJ)	pessoa_fisica	String	Sim	S PF / N PJ
Telefone	telefone1_numero	String	Não	—
Endereço	endereco, cidade, estado, cep	String	Não	—
Tipo atividade	tags	Array	Não	A validar

Campos retornados (armazenar):

Campo Omie	Campo Blueprintt
codigo_cliente_omie	cliente.id_omie_aabc

Projeto — IncluirProjeto / ListarProjetos

Campos enviados:

Campo Blueprintt	Campo Omie	Tipo	Obrigatório	Fonte
Nome evento	nome	String	Sim	Evento Blueprintt
Código projeto	codigo	String	Sim	P07 — formato a definir
Descrição	descricao	String	Não	—

Cuidado

P07 pendente: codigo é o vínculo evento↔projeto. Definir formato (sugestão: ID do evento Blueprintt) antes de implementar.

Campos retornados:

Campo Omie	Campo Blueprintt
id	evento.id_projeto_omie

Ordem de Serviço — IncluirOS / ListarOS / FaturarOS

Busca antes de criar (duplicidade — regra OS duplicada em Domain · Policies):

POST /servicos/os/
call: ListarOS
Filtrar por: codigo_cliente_omie + id_projeto_omie
Status: ativo (aberto ou faturado)

Campos enviados:

Campo Blueprintt	Campo Omie	Tipo	Obrigatório	Fonte
Código cliente	codigo_cliente	Integer	Sim	Retornado em IncluirCliente
Código projeto	codigo_projeto	String	Sim	Retornado em IncluirProjeto
Tipo serviço	codigo_servico	String	Sim	P08 — cadastro cliente
Valor total	valor_total	Decimal	Sim	Pedido venda
Discriminação	descricao	String	Sim	Participantes + detalhes evento
Observações	observacoes	String	Não	Editável operador

Campos retornados:

Campo Omie	Campo Blueprintt
numero_os	pedido.numero_os_omie
codigo_os	pedido.id_os_omie

Faturamento:

POST /servicos/os/
call: FaturarOS
Param: { codigo_os: pedido.id_os_omie }

Após faturamento, Omie emite NFS-e automaticamente.

Campo Omie	Campo Blueprintt
numero_nfse	pedido.numero_nf
link_nfse	pedido.link_nf

Cuidado

P09 pendente: confirmar se Omie retorna link direto da NFS-e ou se precisa consulta separada.

Cancelamento NFS-e

P10 pendente — método exato (CancelarNFSe?) + campos necessários a confirmar com Omie.

Pendências consolidadas

#	Sistema	Item	Bloqueia
P01	HubSpot	Propriedade CNPJ/CPF no deal	Webhook handler completo
P02	HubSpot	Propriedade evento/produto	Webhook handler
P03	HubSpot	Lista participantes	Webhook handler
P04	HubSpot	Formato amount (reais vs centavos)	Mapeamento valor
P05	HubSpot	Mapping owner → e-mail interno	Atribuição vendedor
P06	Pagar.me	metadata.blueprintt_order_id round-trip	Idempotência webhook
P07	Omie	Formato codigo projeto	IncluirProjeto
P08	Omie	Mapping tipos de serviço AABC/LNG	IncluirOS
P09	Omie	Link NFS-e no retorno FaturarOS?	Writeback Bubble
P10	Omie	Método cancelamento NFS-e	cancel-nf endpoint

ADR-5 fechou HubSpot Fase 2 fora do escopo Versão Atual; P01-P05 ficam adormecidos. P06-P10 ativos.