Guia de Integração

Fluxo completo e prático para integrar sua plataforma à Obra Play. Este guia é voltado para sistemas de gestão de obras e construtoras que desejam automatizar o processo de cotação e compra de materiais.

Caso de uso típico

Uma plataforma cria cotações de materiais/serviços, recebe respostas dos fornecedores e gera ordens de compra — tudo via API, sem intervenção manual.

---

Visão geral do fluxo

1. Criar cotação com os materiais/serviços desejados e endereços de entrega
2. Criar respostas de cotação para os fornecedores
3. Aguardar respostas via Webhook
4. Criar ordem de compra

---

1. Criar cotação

Cria a cotação, endereços de entrega, itens e já aponta para os fornecedores desejados — tudo em uma única chamada. A cotação é publicada imediatamente e os fornecedores são notificados.

POST /api/quotations/nested/
Authorization: Token seu_token_aqui
Content-Type: application/json

{
  "company": 15,
  "requirement_date": "2026-05-10T00:00:00Z",
  "expires_at": "2026-04-25T23:59:00Z",
  "name": "João Silva",
  "email": "joao@construtora.com",
  "phone": "+5541999990000",
  "foreign_id": "COT-2026-001",
  "is_public": false,
  "is_draft": false,
  "shipping_addresses": [
    {
      "construction_name": "Obra Centro",
      "street": "Rua das Flores",
      "number": "100",
      "city": "Curitiba",
      "state": "PR",
      "zipcode": "80000-000",
      "neighbourhood": "Centro",
      "items": [
        {
          "item": 301,
          "name": "Cimento CP-II 50kg",
          "quantity": 100,
          "total_quantity_micros": 100000000,
          "measurement_unit": 2,
          "type": "catalog"
        },
        {
          "name": "Areia média",
          "quantity": 5,
          "total_quantity_micros": 5000000,
          "measurement_unit": 3,
          "type": "custom"
        }
      ]
    }
  ],
  "answers": [
    {
      "name": "Distribuidora Construmax",
      "email": "cotacao@construmax.com.br",
      "notify_by_email": true,
      "own_supplier": false,
      "supplier_foreign_id": "FORNEC-088"
    },
    {
      "name": "Material Bom",
      "phone": "+5541988880000",
      "notify_by_whatsapp": true,
      "own_supplier": false
    }
  ]
}

Campos dos itens:

Campo	Tipo	Descrição
item	integer	ID do item da vitrine — use para itens do catálogo
name	string	Nome do item — obrigatório se não usar vitrine
quantity	decimal	Quantidade
total_quantity_micros	integer	Quantidade × 1.000.000 (ex: 100 → 100000000)
measurement_unit	integer	ID da unidade de medida
type	string	catalog (item da vitrine) ou custom (item livre)

Campos dos fornecedores (answers):

Campo	Tipo	Descrição
name	string	Nome do contato do fornecedor
email	string	E-mail (obrigatório se notify_by_email: true)
phone	string	Telefone no formato E.164 (obrigatório se notify_by_whatsapp: true)
notify_by_email	boolean	Notificar por e-mail
notify_by_whatsapp	boolean	Notificar por WhatsApp
supplier_foreign_id	string	ID do fornecedor no seu sistema — útil para cruzar dados

Campos do cabeçalho:

Campo	Tipo	Descrição
foreign_id	string	ID da cotação no seu sistema — para cruzar com seus registros internos
is_public	boolean	true para que qualquer fornecedor da plataforma veja a cotação; false para notificar apenas os fornecedores listados em answers
is_draft	boolean	false para publicar imediatamente; true para salvar como rascunho

Sobre total_quantity_micros

A API armazena quantidades em micros (valores × 1.000.000) para evitar problemas de ponto flutuante. Exemplos: 100 sacos → 100000000 · 2,5 m³ → 2500000.

---

4. Acompanhar respostas

Após publicar a cotação, os fornecedores recebem a notificação e começam a preencher suas respostas.

Via Webhook (recomendado)

Configure um webhook para o evento quotation_answer.received e seja notificado assim que um fornecedor submeter uma proposta. Veja Webhooks.

---

6. Criar a ordem de compra

Após analisar as respostas, crie a ordem de compra referenciando a quotation_answer escolhida:

POST /api/orders/
Authorization: Token seu_token_aqui
Content-Type: application/json

{
  "quotation_answer": 8821
}

A Obra Play então:

• Cria a ordem vinculado à resposta selecionada
• Notifica o fornecedor pelo evento order.created

A resposta inclui o id do pedido que você vai usar para acompanhar a entrega.

tip

Para os campos completos aceitos na criação do pedido, consulte o Swagger de Staging.

---

7. Acompanhar o ordem de compra

Após a escolha, o pedido fica aguardando o fornecedor processar e confirmar a entrega. Você pode consultar o status a qualquer momento:

GET /api/orders/{id}/
Authorization: Token seu_token_aqui

Estados possíveis do pedido:

Status	Descrição
pending	Pedido criado, aguardando o fornecedor processar
processing	Fornecedor confirmou e está preparando o pedido
finalized	Entrega confirmada, pedido encerrado
canceled	Pedido cancelado
refused	Pedido recusado pelo fornecedor

Documentos anexados pelo fornecedor (nota fiscal, comprovante de entrega):

GET /api/orders/{id}/uploads/
Authorization: Token seu_token_aqui

Via Webhook

Evento	Quando ocorre
order.created	Pedido gerado após escolha da proposta
order.canceled	Pedido cancelado pelo construtor
order.finalized	Entrega confirmada pelo fornecedor

---

Resumo das rotas deste guia

Passo	Método	Rota
Criar cotação completa	POST	/api/quotations/nested/
Consultar respostas	GET	/api/quotations/{quotation_id}/answers/
Criar pedido	POST	/api/orders/nested/
Ver pedido	GET	/api/orders/{id}/