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 como a sua consulta fornecedores disponíveis, cria cotações de materiais, recebe propostas dos fornecedores e gera ordens de compra — tudo via API, sem intervenção manual.
Visão geral do fluxo
1. Consultar fornecedores disponíveis
2. Consultar itens da vitrine (catálogo)
3. Criar cotação com os itens desejados
4. Apontar a cotação para fornecedores
5. Aguardar respostas via Webhook ou polling
6. Comparar propostas e escolher a melhor
7. Acompanhar o pedido até a entrega
1. Consultar fornecedores
Antes de criar uma cotação, consulte os fornecedores cadastrados na Obra Play disponíveis na região e categoria desejada.
GET /api/companies/?is_supplier=true&state=PR
Authorization: Token seu_token_aqui
Parâmetros úteis:
| Parâmetro | Tipo | Descrição |
|---|---|---|
is_supplier | boolean | Filtrar apenas fornecedores |
state | string | UF de atuação (ex: PR, SP) |
city | string | Cidade de atuação |
Resposta:
{
"count": 48,
"next": "https://api-staging.obraplay.com/api/companies/?is_supplier=true&state=PR&page=2",
"previous": null,
"results": [
{
"id": 88,
"name": "Distribuidora Construmax",
"slug": "construmax",
"city": "Curitiba",
"state": "PR"
}
]
}
Guarde os id dos fornecedores para usar na criação da cotação.
2. Consultar itens da vitrine
A vitrine é o catálogo de produtos padronizados da Obra Play. Ao usar itens da vitrine, os fornecedores identificam exatamente o produto solicitado, eliminando ambiguidades.
GET /api/items/?search=cimento
Authorization: Token seu_token_aqui
Parâmetros úteis:
| Parâmetro | Tipo | Descrição |
|---|---|---|
search | string | Busca por nome do item |
category | integer | ID da categoria |
ordering | string | Ordenação (ex: name, -name) |
Para listar as categorias disponíveis:
GET /api/item_categories/
Authorization: Token seu_token_aqui
Resposta de /api/items/:
{
"count": 12,
"results": [
{
"id": 301,
"name": "Cimento CP-II 50kg",
"category": { "id": 5, "name": "Cimento e Argamassa" },
"measurement_unit": { "id": 2, "symbol": "sc", "name": "Saco" }
}
]
}
tip
Guarde o id dos itens e o id da unidade de medida — você vai precisar de ambos na criação da cotação.
3. Criar cotação
Você tem três formas de criar uma cotação. Escolha de acordo com o seu caso de uso.
Opção A — Cotação simples (só o cabeçalho)
Cria apenas o registro da cotação. Itens, endereços e fornecedores são adicionados em chamadas separadas.
POST /api/quotations/
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",
"observations": "Entrega urgente para obra no centro",
"is_public": false,
"foreign_id": "COT-2026-001"
}
Campos obrigatórios: company, requirement_date, expires_at
Resposta:
{
"id": 1042,
"code": "OB-1042",
"company": 15,
"is_draft": true,
"created_at": "2026-04-16T14:00:00Z"
}
info
A cotação é criada como rascunho (is_draft: true). Para publicá-la com itens e fornecedores em uma chamada única, use a Opção B.
Opção B — Cotação completa com itens e fornecedores (recomendado)
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 |
own_supplier | boolean | true para fornecedores da sua própria rede; false para fornecedores da rede Obra Play |
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.
Opção C — Cotação e resposta juntas
Cria a cotação e já registra a resposta de um fornecedor específico em uma única chamada. Útil quando você sabe de antemão qual fornecedor vai responder.
POST /api/quotation_answers/nested/
Authorization: Token seu_token_aqui
Content-Type: application/json
{
"name": "Distribuidora Construmax",
"email": "cotacao@construmax.com.br",
"notify_by_email": true,
"own_supplier": false,
"quotation": {
"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",
"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"
}
]
}
]
}
}
4. Acompanhar respostas
Após publicar a cotação, os fornecedores recebem a notificação e começam a preencher suas propostas.
Via Webhook (recomendado)
Configure um webhook para o evento quotation_answer.received e seja notificado assim que um fornecedor submeter uma proposta. Veja Webhooks.
Via polling
GET /api/quotation_answers/?quotation=1042
Authorization: Token seu_token_aqui
Se precisar localizar a cotação pelo ID do seu próprio sistema antes de consultar as respostas:
GET /api/quotations/?foreign_id=COT-2026-001
Authorization: Token seu_token_aqui
5. Comparar propostas
Após o prazo da cotação, consulte o comparativo para ver todas as propostas lado a lado e decidir qual escolher:
GET /api/quotation_answers/{id}/comparative/
Authorization: Token seu_token_aqui
6. Criar o pedido
Após analisar as propostas no comparativo, crie o pedido 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 o pedido vinculado à proposta 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 pedido
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 |
|---|---|---|
| Consultar fornecedores | GET | /api/companies/?is_supplier=true |
| Consultar vitrine | GET | /api/items/ |
| Consultar categorias | GET | /api/item_categories/ |
| Criar cotação simples | POST | /api/quotations/ |
| Criar cotação completa | POST | /api/quotations/nested/ |
| Criar cotação + resposta | POST | /api/quotation_answers/nested/ |
| Consultar respostas | GET | /api/quotation_answers/?quotation={id} |
| Ver comparativo | GET | /api/quotation_answers/{id}/comparative/ |
| Criar pedido | POST | /api/orders/ |
| Ver pedido | GET | /api/orders/{id}/ |
| Ver documentos do pedido | GET | /api/orders/{id}/uploads/ |