API de integração Nimbus

Leia e grave os dados da sua empresa a partir de outros sistemas. Cada token pertence a uma empresa e só enxerga os dados dela.

Especificação OpenAPI: /api/v1/openapi.json

Autenticação

Crie um token em Configurações > Integrações (só administradores). O token aparece uma única vez; guarde-o num cofre de segredos e nunca o coloque em código público ou app de celular. Envie-o em todas as chamadas:

Authorization: Bearer stm_live_SEU_TOKEN

O token só enxerga e altera os dados da empresa que o criou. Token ausente, inválido, expirado ou revogado responde sempre 401. Para revogar um token comprometido, use o botão Revogar na mesma tela: vale na hora.

Escopos

Cada token recebe só as permissões que precisar. Sem o escopo do endpoint, a resposta é 403. Escrever não inclui ler.

clientes:ler: Clientes: consultar
clientes:escrever: Clientes: criar, alterar e remover
servicos:ler: Serviços: consultar
servicos:escrever: Serviços: criar, alterar e remover
mensalidades:ler: Mensalidades: consultar
mensalidades:escrever: Mensalidades: criar, alterar, remover e marcar como paga
despesas:ler: Despesas: consultar
despesas:escrever: Despesas: criar, alterar, remover e marcar como paga
notas:ler: Notas fiscais: consultar
notas:escrever: Notas fiscais: criar, alterar, remover, emitir, cancelar e reabrir
orcamentos:ler: Orçamentos: consultar
orcamentos:escrever: Orçamentos: criar, alterar e remover (e ver o link público de aprovação)
vendas:ler: Vendas: consultar (itens, parcelas e resultado)
vendas:escrever: Vendas: criar, alterar, remover, cancelar, baixar parcela e converter orçamento em venda
ordens:ler: Ordens de serviço: consultar (com lançamentos e diário)
ordens:escrever: Ordens de serviço: criar, alterar, iniciar, concluir, cancelar, lançamentos, diário, faturar adicionais e lançar gastos

Convenções

Base: https://nimbus.type77.cloud/api/v1. Corpos e respostas em JSON; instantes em ISO 8601. Datas de calendário (vencimento, data, data prevista, filtros *_de e *_ate) usam AAAA-MM-DD; "hoje" (atrasos, situação) é a data em America/Sao_Paulo.
Valores monetários são texto decimal, por exemplo "149.90".
Listas: ?limit= (1 a 100, padrão 50) e ?cursor= com o proximo_cursor da página anterior. Quando ele vier null, acabou.
Sincronização incremental: ?atualizado_desde=2026-09-28T00:00:00Z. Use uma margem de alguns minutos em relação à última sincronização e deduplique pelo id ou id_externo, pois transações longas podem gravar com data anterior.
Limite: 120 requisições por minuto por token. Ao exceder, 429 com o cabeçalho Retry-After (segundos).
Contas em modo somente leitura (pagamento pendente) continuam consultando, mas escritas retornam 403 conta_somente_leitura.
Campos desconhecidos no corpo são ignorados. id, created_at e o vínculo com a empresa nunca são aceitos do corpo.

Evitando duplicados: id_externo

Guarde no id_externo o identificador do registro no seu sistema. Com PUT /clientes/por-id-externo/{id_externo} você reenvia o mesmo registro quantas vezes precisar: ele é criado na primeira vez e atualizado nas seguintes, sem duplicar. O id_externo é único por empresa (duas empresas podem usar o mesmo valor). No PUT o nome é obrigatório e campos opcionais omitidos são preservados. Se o corpo trouxer outro id_externo, vale o da URL.

Webhooks e log de requisições

Em Configurações, Integrações, cadastre endereços https. A cada escrita bem-sucedida (POST, PUT, PATCH ou DELETE) feita pela API, enviamos um POST com { evento, metodo, caminho, status, em }, onde evento é <recurso>.escrita (ex.: vendas.escrita). O aviso não traz os dados do registro: consulte a API com atualizado_desde. O cabeçalho X-Stormm-Assinatura é o HMAC-SHA256 (hex) do corpo, calculado com o segredo mostrado uma única vez no cadastro. Há timeout de 5 s e nenhuma nova tentativa: use o atualizado_desde para recuperar avisos perdidos.

Cada requisição autenticada fica registrada (método, caminho, status e duração, sem corpo nem query string) por 30 dias e aparece em Integrações.

Erros

{ "erro": { "codigo": "validacao", "mensagem": "Dados inválidos.", "campos": { "email": "Email inválido." } } }

Códigos: json_invalido (400), nao_autenticado (401), sem_permissao e conta_somente_leitura (403), nao_encontrado (404), conflito e estado_invalido (409), validacao (422), limite_excedido (429), erro_interno (500).

Clientes

Campos: id_externo, nome (obrigatório), documento, email, telefone, endereco.

GET /clientes

Lista clientes da empresa (paginada). Escopo: clientes:ler

Filtros: limit (1 a 100. Padrão 50.) cursor (Valor de proximo_cursor da página anterior.) atualizado_desde (Data ISO 8601: só registros alterados depois dela (sincronização incremental).)

200 Página de resultados; proximo_cursor é null na última.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
422 Parâmetro inválido.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/clientes" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /clientes

Cria cliente. Escopo: clientes:escrever

201 Criado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
409 id_externo já existe.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/clientes" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"ERP-1042","nome":"Maria Silva","documento":"123.456.789-09","email":"maria@exemplo.com","telefone":"11999998888","endereco":"Rua das Flores, 10"}'

GET /clientes/{id}

Detalha cliente. Escopo: clientes:ler

200 Encontrado.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/clientes/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PATCH /clientes/{id}

Altera campos de cliente. Escopo: clientes:escrever

200 Alterado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 id_externo já existe.
422 Dados inválidos ou nenhum campo enviado (envie ao menos um campo).
429 Mais de 120 requisições por minuto.

curl -X PATCH "https://nimbus.type77.cloud/api/v1/clientes/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"ERP-1042","nome":"Maria Silva","documento":"123.456.789-09","email":"maria@exemplo.com","telefone":"11999998888","endereco":"Rua das Flores, 10"}'

DELETE /clientes/{id}

Remove cliente. Escopo: clientes:escrever

204 Removido.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Em uso por outros dados.
429 Mais de 120 requisições por minuto.

curl -X DELETE "https://nimbus.type77.cloud/api/v1/clientes/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PUT /clientes/por-id-externo/{id_externo}

Cria ou atualiza cliente pelo id do seu sistema (idempotente). Escopo: clientes:escrever

200 Criado ou atualizado. Campos opcionais omitidos são preservados.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X PUT "https://nimbus.type77.cloud/api/v1/clientes/por-id-externo/ID_DO_SEU_SISTEMA" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"ERP-1042","nome":"Maria Silva","documento":"123.456.789-09","email":"maria@exemplo.com","telefone":"11999998888","endereco":"Rua das Flores, 10"}'

Serviços

Campos: id_externo, nome (obrigatório), descricao, valor.

GET /servicos

Lista servicos da empresa (paginada). Escopo: servicos:ler

Filtros: limit (1 a 100. Padrão 50.) cursor (Valor de proximo_cursor da página anterior.) atualizado_desde (Data ISO 8601: só registros alterados depois dela (sincronização incremental).)

200 Página de resultados; proximo_cursor é null na última.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
422 Parâmetro inválido.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/servicos" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /servicos

Cria serviço. Escopo: servicos:escrever

201 Criado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
409 id_externo já existe.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/servicos" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"SRV-7","nome":"Instalação de ar-condicionado","descricao":"Split até 12000 BTUs","valor":"350.00"}'

GET /servicos/{id}

Detalha serviço. Escopo: servicos:ler

200 Encontrado.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/servicos/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PATCH /servicos/{id}

Altera campos de serviço. Escopo: servicos:escrever

200 Alterado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 id_externo já existe.
422 Dados inválidos ou nenhum campo enviado (envie ao menos um campo).
429 Mais de 120 requisições por minuto.

curl -X PATCH "https://nimbus.type77.cloud/api/v1/servicos/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"SRV-7","nome":"Instalação de ar-condicionado","descricao":"Split até 12000 BTUs","valor":"350.00"}'

DELETE /servicos/{id}

Remove serviço. Escopo: servicos:escrever

204 Removido.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Em uso por outros dados.
429 Mais de 120 requisições por minuto.

curl -X DELETE "https://nimbus.type77.cloud/api/v1/servicos/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PUT /servicos/por-id-externo/{id_externo}

Cria ou atualiza serviço pelo id do seu sistema (idempotente). Escopo: servicos:escrever

200 Criado ou atualizado. Campos opcionais omitidos são preservados.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X PUT "https://nimbus.type77.cloud/api/v1/servicos/por-id-externo/ID_DO_SEU_SISTEMA" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"SRV-7","nome":"Instalação de ar-condicionado","descricao":"Split até 12000 BTUs","valor":"350.00"}'

Mensalidades

Campos: id_externo, cliente_id (obrigatório), descricao (obrigatório), valor, vencimento (obrigatório).

Só mensalidade pendente pode ser alterada (PATCH ou PUT atualizam os campos do registro); depois de paga, PATCH e PUT devolvem 409 e resta a leitura e a exclusão (DELETE continua permitido).
PUT é a representação completa: numa mensalidade pendente ele pode trocar o cliente_id por outro cliente da mesma empresa (o PATCH não altera o cliente).
Pagar exige o estado pendente: repetir a chamada devolve 409 e não gera outra mensalidade.

POST /mensalidades/{id}/pagar

Marca a mensalidade como paga e gera a próxima (vencimento +1 mês). Escopo: mensalidades:escrever

200 { paga, proxima }; proxima é null com gerar_proxima=false. 409 se já não estiver pendente.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/mensalidades/ID/pagar" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"gerar_proxima":true}'

GET /mensalidades

Lista mensalidades da empresa (paginada). Escopo: mensalidades:ler

Filtros: limit (1 a 100. Padrão 50.) cursor (Valor de proximo_cursor da página anterior.) atualizado_desde (Data ISO 8601: só registros alterados depois dela (sincronização incremental).) status (pendente, pago ou atrasado (pendente com vencimento antes de hoje, em São Paulo).) cliente_id (Só mensalidades deste cliente.) vencimento_de (Vencimento a partir desta data (AAAA-MM-DD).) vencimento_ate (Vencimento até esta data (AAAA-MM-DD).)

200 Página de resultados; proximo_cursor é null na última.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
422 Parâmetro inválido.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/mensalidades" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /mensalidades

Cria mensalidade. Escopo: mensalidades:escrever

201 Criado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
409 id_externo já existe.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/mensalidades" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"MENS-2026-10","cliente_id":"11111111-1111-4111-8111-111111111111","descricao":"Mensalidade de outubro","valor":"199.90","vencimento":"2026-10-10"}'

GET /mensalidades/{id}

Detalha mensalidade. Escopo: mensalidades:ler

200 Encontrado.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/mensalidades/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PATCH /mensalidades/{id}

Altera campos de mensalidade. Escopo: mensalidades:escrever

200 Alterado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Só mensalidade pendente pode ser alterada. Registro fora do estado editável responde 409 estado_invalido; id_externo repetido responde 409 conflito.
422 Dados inválidos ou nenhum campo enviado (envie ao menos um campo).
429 Mais de 120 requisições por minuto.

curl -X PATCH "https://nimbus.type77.cloud/api/v1/mensalidades/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"descricao":"Mensalidade de outubro","valor":"199.90","vencimento":"2026-10-10"}'

DELETE /mensalidades/{id}

Remove mensalidade. Escopo: mensalidades:escrever

204 Removido.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Em uso por outros dados.
429 Mais de 120 requisições por minuto.

curl -X DELETE "https://nimbus.type77.cloud/api/v1/mensalidades/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PUT /mensalidades/por-id-externo/{id_externo}

Cria ou atualiza mensalidade pelo id do seu sistema (idempotente). Escopo: mensalidades:escrever

200 Criado ou atualizado. Campos opcionais omitidos são preservados.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
409 Só mensalidade pendente pode ser alterada. Registro fora do estado editável responde 409 estado_invalido; id_externo repetido numa corrida de criação responde 409 conflito.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X PUT "https://nimbus.type77.cloud/api/v1/mensalidades/por-id-externo/ID_DO_SEU_SISTEMA" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"MENS-2026-10","cliente_id":"11111111-1111-4111-8111-111111111111","descricao":"Mensalidade de outubro","valor":"199.90","vencimento":"2026-10-10"}'

Despesas

Campos: id_externo, descricao (obrigatório), categoria, valor, data (obrigatório), status.

POST aceita tipo: unica (padrão), recorrente (exige frequencia: semanal, mensal ou anual) ou parcelada (exige total_parcelas de 2 a 120).
Parcelada: valor é o valor de CADA parcela; as datas avançam mês a mês a partir de data (31/01, 28/02, 31/03...); nascem pendentes; o id_externo vira <id_externo>-<n>; a resposta é { dados: [...], parcelamento_id }.
Depois de criada, a despesa não muda de tipo nem de frequência; PATCH e PUT alteram descricao, categoria, valor, data e status da própria linha (não propaga para as demais parcelas).
Apagar uma despesa que nasceu de uma ordem de serviço des-lança o gasto na OS (ele volta a poder ser lançado).
Voltar o status para pendente (PATCH) e chamar pagar de novo gera outra ocorrência numa despesa recorrente.

POST /despesas/{id}/pagar

Marca a despesa como paga; se for recorrente, gera a próxima ocorrência. Escopo: despesas:escrever

200 { paga, proxima }; proxima é null quando não recorrente. 409 se já não estiver pendente.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/despesas/ID/pagar" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

GET /despesas

Lista despesas da empresa (paginada). Escopo: despesas:ler

Filtros: limit (1 a 100. Padrão 50.) cursor (Valor de proximo_cursor da página anterior.) atualizado_desde (Data ISO 8601: só registros alterados depois dela (sincronização incremental).) status (pendente ou pago.) categoria (Categoria exata.) data_de (Data a partir de (AAAA-MM-DD).) data_ate (Data até (AAAA-MM-DD).) q (Busca no texto da descrição.)

200 Página de resultados; proximo_cursor é null na última.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
422 Parâmetro inválido.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/despesas" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /despesas

Cria despesa. Escopo: despesas:escrever

201 Criada. Despesa parcelada devolve { dados: [...], parcelamento_id } com todas as parcelas.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
409 id_externo já existe.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/despesas" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"DESP-88","descricao":"Aluguel","categoria":"Fixas","valor":"1500.00","data":"2026-10-05","status":"pendente","tipo":"unica","frequencia":"mensal","total_parcelas":12}'

GET /despesas/{id}

Detalha despesa. Escopo: despesas:ler

200 Encontrado.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/despesas/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PATCH /despesas/{id}

Altera campos de despesa. Escopo: despesas:escrever

200 Alterado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 id_externo já existe.
422 Dados inválidos ou nenhum campo enviado (envie ao menos um campo).
429 Mais de 120 requisições por minuto.

curl -X PATCH "https://nimbus.type77.cloud/api/v1/despesas/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"DESP-88","descricao":"Aluguel","categoria":"Fixas","valor":"1500.00","data":"2026-10-05","status":"pendente"}'

DELETE /despesas/{id}

Remove despesa. Escopo: despesas:escrever

204 Removido.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Em uso por outros dados.
429 Mais de 120 requisições por minuto.

curl -X DELETE "https://nimbus.type77.cloud/api/v1/despesas/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PUT /despesas/por-id-externo/{id_externo}

Cria ou atualiza despesa pelo id do seu sistema (idempotente). Escopo: despesas:escrever

200 Criado ou atualizado. Campos opcionais omitidos são preservados.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X PUT "https://nimbus.type77.cloud/api/v1/despesas/por-id-externo/ID_DO_SEU_SISTEMA" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"DESP-88","descricao":"Aluguel","categoria":"Fixas","valor":"1500.00","data":"2026-10-05","status":"pendente"}'

Notas fiscais

Campos: id_externo, cliente_id (obrigatório), venda_id, tipo, descricao (obrigatório), valor, data_prevista (obrigatório), recorrente, observacoes.

É um controle de notas: a emissão real acontece no seu sistema fiscal e é registrada aqui com o número e a data.
status, numero e emitida_em só mudam pelas ações emitir, cancelar e reabrir. Nota emitida ou cancelada não pode ser alterada (409).
situacao é calculada: atrasada (pendente com data prevista antes de hoje), hoje, pendente, emitida ou cancelada.
DELETE é permitido em qualquer status.
Numa nota recorrente, reabrir e emitir de novo gera outra próxima nota: reabrir não remove a que já foi criada.

POST /notas/{id}/emitir

Registra a emissão (número e data) e, se recorrente, agenda a próxima nota. Escopo: notas:escrever

200 { nota, proxima }. 409 se a nota já não estiver pendente.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/notas/ID/emitir" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"numero":"1234","emitida_em":"2026-10-30"}'

POST /notas/{id}/cancelar

Cancela uma nota pendente. Escopo: notas:escrever

200 A nota cancelada. 409 se já não estiver pendente.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/notas/ID/cancelar" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /notas/{id}/reabrir

Volta uma nota emitida ou cancelada para pendente (zera número e data de emissão). Escopo: notas:escrever

200 A nota reaberta. 409 se já estiver pendente.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/notas/ID/reabrir" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

GET /notas

Lista notas da empresa (paginada). Escopo: notas:ler

Filtros: limit (1 a 100. Padrão 50.) cursor (Valor de proximo_cursor da página anterior.) atualizado_desde (Data ISO 8601: só registros alterados depois dela (sincronização incremental).) status (pendente, emitida ou cancelada. Sem filtro, a lista inclui as canceladas.) situacao (atrasada: pendente com data prevista antes de hoje (São Paulo).) cliente_id (Só notas deste cliente.) data_de (Data prevista a partir de (AAAA-MM-DD).) data_ate (Data prevista até (AAAA-MM-DD).)

200 Página de resultados; proximo_cursor é null na última.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
422 Parâmetro inválido.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/notas" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /notas

Cria nota fiscal. Escopo: notas:escrever

201 Criado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
409 id_externo já existe.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/notas" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"NF-2026-10","cliente_id":"11111111-1111-4111-8111-111111111111","venda_id":"22222222-2222-4222-8222-222222222222","tipo":"nfse","descricao":"Serviço de outubro","valor":"350.00","data_prevista":"2026-10-31","recorrente":false,"observacoes":"Enviar por email"}'

GET /notas/{id}

Detalha nota fiscal. Escopo: notas:ler

200 Encontrado.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/notas/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PATCH /notas/{id}

Altera campos de nota fiscal. Escopo: notas:escrever

200 Alterado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Só nota pendente pode ser alterada. Registro fora do estado editável responde 409 estado_invalido; id_externo repetido responde 409 conflito.
422 Dados inválidos ou nenhum campo enviado (envie ao menos um campo).
429 Mais de 120 requisições por minuto.

curl -X PATCH "https://nimbus.type77.cloud/api/v1/notas/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"NF-2026-10","cliente_id":"11111111-1111-4111-8111-111111111111","venda_id":"22222222-2222-4222-8222-222222222222","tipo":"nfse","descricao":"Serviço de outubro","valor":"350.00","data_prevista":"2026-10-31","recorrente":false,"observacoes":"Enviar por email"}'

DELETE /notas/{id}

Remove nota fiscal. Escopo: notas:escrever

204 Removido.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Em uso por outros dados.
429 Mais de 120 requisições por minuto.

curl -X DELETE "https://nimbus.type77.cloud/api/v1/notas/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PUT /notas/por-id-externo/{id_externo}

Cria ou atualiza nota fiscal pelo id do seu sistema (idempotente). Escopo: notas:escrever

200 Criado ou atualizado. Campos opcionais omitidos são preservados.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
409 Só nota pendente pode ser alterada. Registro fora do estado editável responde 409 estado_invalido; id_externo repetido numa corrida de criação responde 409 conflito.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X PUT "https://nimbus.type77.cloud/api/v1/notas/por-id-externo/ID_DO_SEU_SISTEMA" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"NF-2026-10","cliente_id":"11111111-1111-4111-8111-111111111111","venda_id":"22222222-2222-4222-8222-222222222222","tipo":"nfse","descricao":"Serviço de outubro","valor":"350.00","data_prevista":"2026-10-31","recorrente":false,"observacoes":"Enviar por email"}'

Orçamentos

Campos: id_externo, cliente_id (obrigatório), status, data_validade, tags, itens.

converter cria a venda com os itens do orçamento e o valor recalculado; corpo opcional { forma_pagamento, condicao }; sem forma_pagamento a venda nasce com uma parcela pendente vencendo hoje (São Paulo). Não muda o status do orçamento e devolve 409 se o orçamento já virou venda.
valor_total é sempre a soma de quantidade x valor_unitario dos itens, calculada no servidor (nunca aceita no corpo).
POST e PUT exigem cliente_id e itens (1 a 200). PATCH aceita qualquer subconjunto de campos; quando itens vem, a lista SUBSTITUI todos os itens. tags é uma lista de até 30 textos de 1 a 50 caracteres.
Cada item: descricao (obrigatória), quantidade (maior que zero) e valor_unitario (zero ou mais), ambos obrigatórios; servico_id é opcional e precisa ser um serviço da sua empresa.
Mudar status para aprovado não cria venda. A resposta do cliente pelo link público (aprovar ou recusar) continua sendo feita pelo sistema; ela aparece em resposta (em, por, motivo_recusa) e nunca é alterada pela API.
link_publico só aparece para tokens com orcamentos:escrever (é uma credencial de acesso); sem esse escopo vem null.
DELETE devolve 409 se já existe venda gerada por este orçamento. Os itens são apagados junto.
id_externo repetido na mesma empresa devolve 409 conflito; use PUT por-id-externo para reenviar sem duplicar.

POST /orcamentos/{id}/converter

Converte o orçamento em venda (exige também vendas:escrever). Escopo: orcamentos:escrever

201 A venda criada (com itens copiados, valor recalculado dos itens e parcelas). 404 se o orçamento não existe; 409 se já virou venda; 403 sem vendas:escrever.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/orcamentos/ID/converter" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"forma_pagamento":"credito","condicao":{"parcelas":3,"primeiro_vencimento":"2026-10-30"}}'

GET /orcamentos

Lista orcamentos da empresa (paginada). Escopo: orcamentos:ler

200 Página de resultados; proximo_cursor é null na última.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
422 Parâmetro inválido.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/orcamentos" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /orcamentos

Cria orçamento. Escopo: orcamentos:escrever

201 Criado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
409 id_externo já existe.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/orcamentos" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"ORC-2026-15","cliente_id":"11111111-1111-4111-8111-111111111111","status":"rascunho","data_validade":"2026-11-30","tags":["instalação","residencial"],"itens":[{"servico_id":"22222222-2222-4222-8222-222222222222","descricao":"Instalação de ar-condicionado","quantidade":"1.00","valor_unitario":"350.00"}]}'

GET /orcamentos/{id}

Detalha orçamento. Escopo: orcamentos:ler

200 Encontrado.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/orcamentos/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PATCH /orcamentos/{id}

Altera campos de orçamento. Escopo: orcamentos:escrever

200 Alterado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 id_externo já existe.
422 Dados inválidos ou nenhum campo enviado (envie ao menos um campo).
429 Mais de 120 requisições por minuto.

curl -X PATCH "https://nimbus.type77.cloud/api/v1/orcamentos/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"ORC-2026-15","cliente_id":"11111111-1111-4111-8111-111111111111","status":"rascunho","data_validade":"2026-11-30","tags":["instalação","residencial"],"itens":[{"servico_id":"22222222-2222-4222-8222-222222222222","descricao":"Instalação de ar-condicionado","quantidade":"1.00","valor_unitario":"350.00"}]}'

DELETE /orcamentos/{id}

Remove orçamento. Escopo: orcamentos:escrever

204 Removido.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Em uso por outros dados.
429 Mais de 120 requisições por minuto.

curl -X DELETE "https://nimbus.type77.cloud/api/v1/orcamentos/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PUT /orcamentos/por-id-externo/{id_externo}

Cria ou atualiza orçamento pelo id do seu sistema (idempotente). Escopo: orcamentos:escrever

200 Criado ou atualizado. Campos opcionais omitidos são preservados.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X PUT "https://nimbus.type77.cloud/api/v1/orcamentos/por-id-externo/ID_DO_SEU_SISTEMA" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"ORC-2026-15","cliente_id":"11111111-1111-4111-8111-111111111111","status":"rascunho","data_validade":"2026-11-30","tags":["instalação","residencial"],"itens":[{"servico_id":"22222222-2222-4222-8222-222222222222","descricao":"Instalação de ar-condicionado","quantidade":"1.00","valor_unitario":"350.00"}]}'

Vendas

Campos: id_externo, cliente_id (obrigatório), forma_pagamento (obrigatório), gera_os, itens, condicao.

POST e PUT exigem cliente_id, forma_pagamento e itens (1 a 200). Formas: pix, dinheiro e debito (à vista: uma parcela já paga) e credito, boleto, transferencia e prazo (parcelável). valor_total, status e as parcelas são calculados no servidor.
Na venda à vista, parcelas é ignorado, mas primeiro_vencimento continua valendo: vira o vencimento da parcela paga e, havendo parcela paga, enviar um valor diferente é 422. PUT/PATCH de venda existente SEM condicao mantém o cronograma atual; criar sem condicao gera 1 parcela vencendo hoje (São Paulo).
condicao (opcional): parcelas de 1 a 48 (padrão 1) e primeiro_vencimento (padrão hoje em São Paulo). As parcelas são mensais, divididas em centavos com a sobra na última, e o vencimento de cada uma parte da data base (31/01, 28/02, 31/03).
PATCH aceita qualquer subconjunto de cliente_id, forma_pagamento, itens, condicao e id_externo; itens SUBSTITUI todos os itens e preserva o custo dos itens existentes. Sem parcela paga, mudar itens, forma ou condição refaz as parcelas. Com parcela paga, mudar a condição, a forma ou o valor total responde 422; reenviar os mesmos valores é permitido.
Venda cancelada não pode ser alterada nem receber baixa (409). Cancelar é definitivo e repetir devolve 409.
status é derivado das parcelas (pago quando nenhuma parcela está pendente) e do cancelamento; nunca é gravado direto.
DELETE devolve 409 se houver parcela paga (o histórico financeiro é preservado); ordens de serviço e notas da venda ficam sem vínculo.
gera_os (opcional): true grava a flag e cria a ordem de serviço da venda se ainda não existir (título Atendimento: <cliente>, endereço do cliente); exige também o escopo ordens:escrever (403 sem ele). Desmarcar (false) não apaga a ordem. Vale em POST, PATCH e PUT. A ordem ligada à venda aparece em ordem_servico_id.
resultado usa a mesma fórmula do sistema: imposto = valor_total x aliquota_imposto / 100; custo = soma de quantidade x custo do item; lucro = valor_total - imposto - custo; margem = lucro / valor_total em percentual. O custo unitário de cada item não é exposto.
Vendas criadas pelo sistema podem devolver os itens em outra ordem; as criadas pela API saem na ordem de envio.

POST /vendas/{id}/cancelar

Cancela a venda (terminal): apaga as parcelas pendentes e mantém as pagas. Escopo: vendas:escrever

200 A venda cancelada. 409 se já estiver cancelada.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/vendas/ID/cancelar" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /vendas/{id}/parcelas/{numero}/baixar

Dá baixa (ou desfaz a baixa) de uma parcela. Escopo: vendas:escrever

200 A venda com as parcelas atualizadas. 404 se a parcela não existe; 409 se a venda está cancelada; 422 se pago_em vier com recebida=false.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/vendas/ID/parcelas/1/baixar" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"recebida":true,"pago_em":"2026-10-10T15:00:00-03:00"}'

GET /vendas

Lista vendas da empresa (paginada). Escopo: vendas:ler

200 Página de resultados; proximo_cursor é null na última.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
422 Parâmetro inválido.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/vendas" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /vendas

Cria venda. Escopo: vendas:escrever

201 Criado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
409 id_externo já existe.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/vendas" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"PED-2026-77","cliente_id":"11111111-1111-4111-8111-111111111111","forma_pagamento":"credito","gera_os":false,"itens":[{"servico_id":"22222222-2222-4222-8222-222222222222","descricao":"Instalação de ar-condicionado","quantidade":"1.00","valor_unitario":"600.00"}],"condicao":{"parcelas":3,"primeiro_vencimento":"2026-10-30"}}'

GET /vendas/{id}

Detalha venda. Escopo: vendas:ler

200 Encontrado.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/vendas/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PATCH /vendas/{id}

Altera campos de venda. Escopo: vendas:escrever

200 Alterado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Venda cancelada responde 409 estado_invalido; id_externo repetido responde 409 conflito.
422 Dados inválidos ou nenhum campo enviado (envie ao menos um campo).
429 Mais de 120 requisições por minuto.

curl -X PATCH "https://nimbus.type77.cloud/api/v1/vendas/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"PED-2026-77","cliente_id":"11111111-1111-4111-8111-111111111111","forma_pagamento":"credito","gera_os":false,"itens":[{"servico_id":"22222222-2222-4222-8222-222222222222","descricao":"Instalação de ar-condicionado","quantidade":"1.00","valor_unitario":"600.00"}],"condicao":{"parcelas":3,"primeiro_vencimento":"2026-10-30"}}'

DELETE /vendas/{id}

Remove venda. Escopo: vendas:escrever

204 Removido.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Venda com parcela paga responde 409 estado_invalido.
429 Mais de 120 requisições por minuto.

curl -X DELETE "https://nimbus.type77.cloud/api/v1/vendas/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PUT /vendas/por-id-externo/{id_externo}

Cria ou atualiza venda pelo id do seu sistema (idempotente). Escopo: vendas:escrever

200 Criado ou atualizado. Campos opcionais omitidos são preservados.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
409 Venda cancelada responde 409 estado_invalido; id_externo repetido numa corrida de criação responde 409 conflito.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X PUT "https://nimbus.type77.cloud/api/v1/vendas/por-id-externo/ID_DO_SEU_SISTEMA" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"PED-2026-77","cliente_id":"11111111-1111-4111-8111-111111111111","forma_pagamento":"credito","gera_os":false,"itens":[{"servico_id":"22222222-2222-4222-8222-222222222222","descricao":"Instalação de ar-condicionado","quantidade":"1.00","valor_unitario":"600.00"}],"condicao":{"parcelas":3,"primeiro_vencimento":"2026-10-30"}}'

Ordens de serviço

Campos: id_externo, titulo (obrigatório), interna, cliente_id, venda_id, orcamento_id, tecnico_id, agendada_para, hora_inicio, duracao_min, endereco, observacoes.

POST exige titulo e o cliente: cliente_id, interna=true (OS da própria empresa) ou uma origem (venda_id ou orcamento_id, nunca os dois; o cliente passa a ser o da origem). endereco em branco usa o do cliente (ou o da empresa, na OS interna).
Cliente, origem e interna não mudam depois de criada: PATCH com esses campos responde 422, e PUT numa OS existente com outro valor também.
PATCH (reagendar) altera só os campos enviados: titulo, tecnico_id, agendada_para, hora_inicio (HH:MM), duracao_min (1 a 1440), endereco, observacoes, id_externo. tecnico_id, agendada_para, hora_inicio, endereco e observacoes aceitam null para limpar; duracao_min não pode ser limpa.
tecnico_id precisa ser membro da empresa (papel diferente de suporte, sem acesso expirado).
status só muda pelas ações: agendada vai para em_andamento ou cancelada; em_andamento vai para concluida ou cancelada; concluir também funciona direto de agendada. concluida e cancelada são terminais (409). Nenhuma transição gera venda nem despesa.
A ordem traz lancamentos e diario. Fotos, comprovantes e a imagem da assinatura ficam fora da API. Não há DELETE: cancele a ordem.
sem_data=true lista as agendadas sem data. A busca q não encontra OS interna (sem cliente).
Lançamentos (POST /ordens/{id}/lancamentos): tipo material, gasto ou mao_de_obra; quantidade maior que zero; cobrar_cliente=true exige cliente na OS (OS interna não cobra) e usa preco_unitario (0 quando não cobra). OS concluída ou cancelada não aceita lançamento (409). Só se apaga lançamento que ainda não foi faturado nem lançado como despesa (409).
faturar-adicionais e lancar-gastos são explícitos e idempotentes: repetir devolve 409 e nunca cobra nem lança duas vezes. A venda de adicionais não vira a venda da OS.
O diário aceita só texto (1 a 2000 caracteres) e funciona em qualquer status da OS; entradas criadas pelo sistema com foto aparecem com com_foto=true.

POST /ordens/{id}/iniciar

Inicia a ordem (agendada para em andamento) e registra iniciada_em. Escopo: ordens:escrever

200 A ordem iniciada. 409 se não estiver agendada.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/ordens/ID/iniciar" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /ordens/{id}/concluir

Conclui a ordem (de agendada ou em andamento) registrando quem assinou; não gera efeito financeiro. Escopo: ordens:escrever

200 A ordem concluída (assinatura.por e assinatura.em preenchidos; a imagem da assinatura não é enviada pela API). 409 se já estiver concluída ou cancelada.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/ordens/ID/concluir" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"assinado_por":"Maria Silva"}'

POST /ordens/{id}/cancelar

Cancela a ordem (de agendada ou em andamento). Escopo: ordens:escrever

200 A ordem cancelada. 409 se já estiver concluída ou cancelada.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/ordens/ID/cancelar" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /ordens/{id}/faturar-adicionais

Cria uma venda com os lançamentos cobrar_cliente ainda sem venda (exige também vendas:escrever). Escopo: ordens:escrever

201 A venda criada (itens com o custo do lançamento e uma parcela pendente vencendo hoje). 409 se não há adicionais a faturar (inclui repetir a chamada); 422 em OS interna; 403 sem vendas:escrever.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/ordens/ID/faturar-adicionais" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /ordens/{id}/lancar-gastos

Cria uma despesa paga para cada lançamento do tipo gasto ainda sem despesa (exige também despesas:escrever). Escopo: ordens:escrever

200 { dados: [despesas criadas] } (categoria Ordens de serviço, valor = quantidade x custo). 409 se não há gastos pendentes (inclui repetir a chamada); 403 sem despesas:escrever.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Estado inválido para esta ação.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/ordens/ID/lancar-gastos" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

GET /ordens

Lista ordens da empresa (paginada). Escopo: ordens:ler

Filtros: limit (1 a 100. Padrão 50.) cursor (Valor de proximo_cursor da página anterior.) atualizado_desde (Data ISO 8601: só registros alterados depois dela (sincronização incremental).) status (agendada, em_andamento, concluida, cancelada.) cliente_id (Só deste cliente.) q (Busca no nome do cliente (considera no máximo 500 clientes que casam com o texto).) criado_de (Criado a partir desta data (AAAA-MM-DD, horário de São Paulo).) criado_ate (Criado até esta data, inclusive (AAAA-MM-DD, horário de São Paulo).) tecnico_id (Só desta pessoa (técnico).) agendada_de (Agendada a partir desta data (AAAA-MM-DD).) agendada_ate (Agendada até esta data (AAAA-MM-DD).) sem_data (true: só as agendadas que ainda não têm data (como o painel de pendências do sistema).)

200 Página de resultados; proximo_cursor é null na última.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
422 Parâmetro inválido.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/ordens" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /ordens

Cria ordem de serviço. Escopo: ordens:escrever

201 Criado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
409 id_externo já existe.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/ordens" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"OS-3021","titulo":"Instalação do sistema","interna":false,"cliente_id":"11111111-1111-4111-8111-111111111111","venda_id":"22222222-2222-4222-8222-222222222222","orcamento_id":"33333333-3333-4333-8333-333333333333","tecnico_id":"44444444-4444-4444-8444-444444444444","agendada_para":"2026-10-05","hora_inicio":"09:30","duracao_min":90,"endereco":"Rua das Flores, 10","observacoes":"Levar escada"}'

GET /ordens/{id}

Detalha ordem de serviço. Escopo: ordens:ler

200 Encontrado.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/ordens/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

PATCH /ordens/{id}

Altera campos de ordem de serviço. Escopo: ordens:escrever

200 Alterado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
404 Não encontrado.
409 Ordem concluída ou cancelada não pode ser alterada (409 estado_invalido); id_externo repetido responde 409 conflito.
422 Dados inválidos ou nenhum campo enviado (envie ao menos um campo).
429 Mais de 120 requisições por minuto.

curl -X PATCH "https://nimbus.type77.cloud/api/v1/ordens/ID" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"titulo":"Instalação do sistema","tecnico_id":"44444444-4444-4444-8444-444444444444","agendada_para":"2026-10-05","hora_inicio":"09:30","duracao_min":90,"endereco":"Rua das Flores, 10","observacoes":"Levar escada","id_externo":"OS-3021"}'

PUT /ordens/por-id-externo/{id_externo}

Cria ou atualiza ordem de serviço pelo id do seu sistema (idempotente). Escopo: ordens:escrever

200 Criado ou atualizado. Campos opcionais omitidos são preservados.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário ou conta somente leitura.
409 Ordem concluída ou cancelada não pode ser alterada (409 estado_invalido); id_externo repetido numa corrida de criação responde 409 conflito. Cliente, origem e interna não mudam depois de criada (422).
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X PUT "https://nimbus.type77.cloud/api/v1/ordens/por-id-externo/ID_DO_SEU_SISTEMA" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id_externo":"OS-3021","titulo":"Instalação do sistema","interna":false,"cliente_id":"11111111-1111-4111-8111-111111111111","venda_id":"22222222-2222-4222-8222-222222222222","orcamento_id":"33333333-3333-4333-8333-333333333333","tecnico_id":"44444444-4444-4444-8444-444444444444","agendada_para":"2026-10-05","hora_inicio":"09:30","duracao_min":90,"endereco":"Rua das Flores, 10","observacoes":"Levar escada"}'

GET /ordens/{id}/lancamentos

Lista os lançamentos (material, gasto e mão de obra) da ordem, em ordem de criação. Escopo: ordens:ler

200 Lançamentos da ordem.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário.
404 Ordem não encontrada.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/ordens/ID/lancamentos" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /ordens/{id}/lancamentos

Lança material, gasto ou mão de obra na ordem. Escopo: ordens:escrever

201 Lançamento criado.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário.
404 Ordem não encontrada.
409 Ordem concluída ou cancelada não aceita lançamento (estado_invalido).
422 Dados inválidos, ou cobrar_cliente em OS interna.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/ordens/ID/lancamentos" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tipo":"material","descricao":"Cabo de rede 20 m","quantidade":"2.00","custo_unitario":"10.00","cobrar_cliente":true,"preco_unitario":"25.00"}'

DELETE /ordens/{id}/lancamentos/{lancamento_id}

Apaga um lançamento que ainda não foi faturado nem lançado como despesa. Escopo: ordens:escrever

204 Apagado.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário.
404 Ordem ou lançamento não encontrado.
409 Lançamento já faturado ou lançado como despesa (estado_invalido).
429 Mais de 120 requisições por minuto.

curl -X DELETE "https://nimbus.type77.cloud/api/v1/ordens/ID/lancamentos/ID_DO_LANCAMENTO" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

GET /ordens/{id}/diario

Lista as entradas do diário da ordem, em ordem de criação. Escopo: ordens:ler

200 Entradas do diário.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário.
404 Ordem não encontrada.
429 Mais de 120 requisições por minuto.

curl -X GET "https://nimbus.type77.cloud/api/v1/ordens/ID/diario" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

POST /ordens/{id}/diario

Registra uma entrada de texto no diário da ordem (qualquer status). Escopo: ordens:escrever

201 Entrada criada.
400 Corpo não é um JSON válido (json_invalido).
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário.
404 Ordem não encontrada.
422 Dados inválidos.
429 Mais de 120 requisições por minuto.

curl -X POST "https://nimbus.type77.cloud/api/v1/ordens/ID/diario" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"texto":"Cliente aprovou o serviço."}'

DELETE /ordens/{id}/diario/{entrada_id}

Apaga uma entrada do diário. Escopo: ordens:escrever

204 Apagada.
401 Token ausente, inválido, expirado ou revogado.
403 Token sem o escopo necessário.
404 Ordem ou entrada não encontrada.
429 Mais de 120 requisições por minuto.

curl -X DELETE "https://nimbus.type77.cloud/api/v1/ordens/ID/diario/ID_DA_ENTRADA" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"

A receber

Tudo que a empresa tem para receber, por vencimento: parcelas de vendas e, se o token tiver também mensalidades:ler, mensalidades pendentes. Como no sistema, os filtros hoje e 7dias incluem as atrasadas.

GET /a-receber

Lista o que a empresa tem para receber: parcelas de vendas e, com mensalidades:ler, mensalidades pendentes (por vencimento). Escopo: vendas:ler

Filtros: filtro (atrasadas (vencimento antes de hoje), hoje ou 7dias. Como no sistema, hoje e 7dias incluem as atrasadas. Datas em São Paulo.) limit (1 a 100. Padrão 50.) cursor (Valor de proximo_cursor da página anterior.)

curl -X GET "https://nimbus.type77.cloud/api/v1/a-receber?filtro=atrasadas" \
  -H "Authorization: Bearer stm_live_SEU_TOKEN"