Pular para o conteúdo

Ordens de serviço

OS do módulo de serviços. Status: QUOTE | APPROVED | IN_PROGRESS | WAITING_CUSTOMER | COMPLETED | INVOICED | CANCELLED. Concluir (COMPLETED) registra a execução; o faturamento comercial é via POST /service-orders/:id/to-sale (rascunho no PDV) e a OS só vira INVOICED ao finalizar essa venda (POST /sales/:id/finalize). Detalhe e lista incluem saleId / sale quando houver vínculo.

Base: https://api.nivesistemas.com.br · 20 endpoints

Listar ordens de serviço

Query params

Campo Tipo Obrigatório Descrição
q string não Busca
status string não Status da OS
customerId uuid não Filtrar por cliente
page integer não Página (padrão 1)
pageSize integer não Itens por página (máx. 100)
Janela do terminal
curl -X GET "https://api.nivesistemas.com.br/service-orders" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"

Agenda de OS por responsável (dia ou período)

Query params

Campo Tipo Obrigatório Descrição
date date não Dia (YYYY-MM-DD); ou use from/to
from date não Início do período (YYYY-MM-DD)
to date não Fim do período (YYYY-MM-DD)
responsibleId uuid não Filtrar por responsável
includeUnscheduled boolean não Inclui OS abertas sem horário em unscheduled
Janela do terminal
curl -X GET "https://api.nivesistemas.com.br/service-orders/agenda" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"

Criar ordem de serviço

Corpo (JSON)

Campo Tipo Obrigatório Descrição
customerId uuid sim Cliente
contactName string não Nome do contato
responsibleId uuid não Responsável
projectId uuid não Projeto
description string não Descrição
notes string não Observações
expectedAt string não Previsão (ISO datetime)
priority string não Prioridade
assetId uuid não Ativo/equipamento
checklistTemplateId uuid não Template de checklist

Resposta: 201 Created

Janela do terminal
curl -X POST "https://api.nivesistemas.com.br/service-orders" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo" \
-H "Content-Type: application/json" \
-d '{"customerId":"00000000-0000-0000-0000-000000000000","contactName":"","responsibleId":"00000000-0000-0000-0000-000000000000","projectId":"00000000-0000-0000-0000-000000000000","description":"","notes":"","expectedAt":"","priority":"","assetId":"00000000-0000-0000-0000-000000000000","checklistTemplateId":"00000000-0000-0000-0000-000000000000"}'

Detalhe da OS

Parâmetros de rota: id

Resposta: Inclui itens, recebíveis, hasIssuedNfse, nfseId, saleId e sale ({ id, orderNumber, status, completedAt }) quando vinculada a uma venda do PDV.

Janela do terminal
curl -X GET "https://api.nivesistemas.com.br/service-orders/{id}" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"

Atualizar OS

Parâmetros de rota: id

Corpo (JSON)

Campo Tipo Obrigatório Descrição
customerId uuid não Cliente
description string não Descrição
notes string não Observações
discountAmount number não Desconto
expectedAt string não Previsão
priority string não Prioridade
Janela do terminal
curl -X PATCH "https://api.nivesistemas.com.br/service-orders/{id}" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo" \
-H "Content-Type: application/json" \
-d '{"customerId":"00000000-0000-0000-0000-000000000000","description":"","notes":"","discountAmount":0,"expectedAt":"","priority":""}'

Adicionar item à OS

Parâmetros de rota: id

Corpo (JSON)

Campo Tipo Obrigatório Descrição
variantId uuid sim Variante do serviço/produto
quantity number sim Quantidade
unitPrice number não Preço unitário

Resposta: 201 Created

Janela do terminal
curl -X POST "https://api.nivesistemas.com.br/service-orders/{id}/items" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo" \
-H "Content-Type: application/json" \
-d '{"variantId":"00000000-0000-0000-0000-000000000000","quantity":0,"unitPrice":0}'

Atualizar item da OS

Parâmetros de rota: id, itemId

Corpo (JSON)

Campo Tipo Obrigatório Descrição
quantity number não Quantidade
unitPrice number não Preço unitário
description string não Descrição do item
Janela do terminal
curl -X PATCH "https://api.nivesistemas.com.br/service-orders/{id}/items/{itemId}" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo" \
-H "Content-Type: application/json" \
-d '{"quantity":0,"unitPrice":0,"description":""}'

Remover item da OS

Parâmetros de rota: id, itemId

Janela do terminal
curl -X DELETE "https://api.nivesistemas.com.br/service-orders/{id}/items/{itemId}" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"

Criar ou reabrir rascunho de venda no PDV a partir da OS

Parâmetros de rota: id

Resposta: 201 se criou rascunho; 200 se já existia. Corpo: { saleId, orderNumber, created, serviceOrderId, serviceOrderNumber, total? }. Exige OS COMPLETED (ou INVOICED sem venda). Idempotente com rascunho DRAFT. 409 se já houver venda COMPLETED. Copia itens/preços; affectsStock=false se a OS já baixou estoque. NFS-e autorizada/pendente da OS é vinculada à venda (saleId). Abrir PDV em /pos?id={saleId}. Ao finalizar a venda, a OS vai para INVOICED.

Janela do terminal
curl -X POST "https://api.nivesistemas.com.br/service-orders/{id}/to-sale" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"

Alterar status da OS

Parâmetros de rota: id

Corpo (JSON)

Campo Tipo Obrigatório Descrição
status string sim Próximo status permitido (transições operacionais). INVOICED não é aceito aqui — use to-sale + finalize da venda. QUOTE | APPROVED | IN_PROGRESS | WAITING_CUSTOMER | COMPLETED | CANCELLED conforme o fluxo.
Janela do terminal
curl -X POST "https://api.nivesistemas.com.br/service-orders/{id}/status" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo" \
-H "Content-Type: application/json" \
-d '{"status":""}'

Cancelar OS

Parâmetros de rota: id

Resposta: Não cancela OS INVOICED. Se houver rascunho DRAFT ligado, o vínculo saleId é liberado.

Janela do terminal
curl -X POST "https://api.nivesistemas.com.br/service-orders/{id}/cancel" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"

Pedir confirmação de presença ao cliente (WhatsApp)

Parâmetros de rota: id

Janela do terminal
curl -X POST "https://api.nivesistemas.com.br/service-orders/{id}/request-confirmation" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"

Marcar presença confirmada

Parâmetros de rota: id

Janela do terminal
curl -X POST "https://api.nivesistemas.com.br/service-orders/{id}/confirm-attendance" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"

Enviar orçamento da OS por WhatsApp

Parâmetros de rota: id

Janela do terminal
curl -X POST "https://api.nivesistemas.com.br/service-orders/{id}/send-quote-whatsapp" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"

Abrir OS de garantia vinculada

Parâmetros de rota: id

Resposta: 201 Created

Janela do terminal
curl -X POST "https://api.nivesistemas.com.br/service-orders/{id}/warranty" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"

Anexar arquivo à OS (multipart, campo file)

Parâmetros de rota: id

Janela do terminal
curl -X POST "https://api.nivesistemas.com.br/service-orders/{id}/attachments" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"

PDF do orçamento/OS (application/pdf, inline)

Parâmetros de rota: id

Resposta: 404 se a OS não existe; 403 se a OS é de outra filial ou de outro mecânico (perfil mecânico).

Janela do terminal
curl -X GET "https://api.nivesistemas.com.br/service-orders/{id}/pdf" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"

Oficina: registrar a aprovação do orçamento pela equipe (cliente aprovou por telefone ou balcão)

Parâmetros de rota: id

Corpo (JSON)

Campo Tipo Obrigatório Descrição
approvedByName string não Quem aprovou (até 200; padrão: nome do cliente da OS)

Resposta: A OS atualizada. Idempotente: se já estava aprovada no valor atual, devolve a OS sem mudança. 400 se a OS está cancelada, sem itens, sem veículo (placa) ou KM de entrada no orçamento, ou não está numa fase que aceite aprovação. Exige o módulo de oficina.

Janela do terminal
curl -X POST "https://api.nivesistemas.com.br/service-orders/{id}/approve-quote" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo" \
-H "Content-Type: application/json" \
-d '{"approvedByName":""}'

Oficina: registrar a retirada do veículo (quem e quando); a garantia passa a contar da entrega

Parâmetros de rota: id

Corpo (JSON)

Campo Tipo Obrigatório Descrição
pickedUpByName string sim Quem está retirando o veículo (até 200)

Resposta: A OS atualizada. 400 se a OS não está concluída ou faturada ou se já foi entregue. Exige o módulo de oficina.

Janela do terminal
curl -X POST "https://api.nivesistemas.com.br/service-orders/{id}/deliver" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo" \
-H "Content-Type: application/json" \
-d '{"pickedUpByName":""}'

Trilha de auditoria da OS (últimos 500 eventos, do mais recente ao mais antigo)

Parâmetros de rota: id

Resposta: Lista de { id, type, message, userName, createdAt }. 404 se a OS não existe.

Janela do terminal
curl -X GET "https://api.nivesistemas.com.br/service-orders/{id}/events" \
-H "Authorization: Bearer sl_live_exemplo_abc123xyz789" \
-H "X-Store-Slug: loja-demo"