Pular para o conteúdo principal

Passo 7 — Faturação

7.1 Pré-visualizar as linhas​

POST /gateway/service-order/invoice/preview
Content-Type: application/json
Authorization: Bearer {token}
{
  "serviceOrderGuid": "GUID-DA-ORDEM",
  "documentTypeKeyId": "FAC",
  "hoursBillingMode": "ExtraOnly"
}

Existe o equivalente para intervenção isolada em POST /gateway/intervention/invoice/preview, com interventionGuid.

As linhas da pré-visualização vêm dos details da ordem/intervenção, mais horas e km valorizados. Sem isso, a pré-visualização devolve ServiceOrderInvoice.NothingToInvoice / InterventionInvoice.NothingToInvoice.

A resposta traz os dados do cliente e a lista de linhas propostas, cada uma já com itemKeyId, itemDescription, quantity, retailPrice, netPrice, taxId, isComment e — crucialmente — originBodyGuid e relationType, que garantem a rastreabilidade até à intervenção de origem.

hoursBillingMode​

ModoComportamento
Full (0)Fatura todas as horas gastas, ignorando o plafond
ExtraOnly (1)Fatura apenas as horas acima do plafond disponível. Exige contrato associado; sem ele devolve ExtraOnlyRequiresContract
None (2)Não fatura horas nem km, só os artigos consumidos

Em ExtraOnly, o cabeçalho de agrupamento das linhas de horas muda para «horas extra-contrato». Quando se fatura uma ordem com várias intervenções ligadas ao mesmo contrato, o plafond é consumido progressivamente ao longo das intervenções (em vez de cada uma ver o plafond cheio).

7.2 Emitir​

As linhas devolvidas pela pré-visualização (depois de o utilizador as poder ajustar) são enviadas para o endpoint genérico, com a origem SAT declarada no cabeçalho:

POST /gateway/invoice/invoices
Content-Type: application/json
Authorization: Bearer {token}
{
  "documentTypeId": 1,
  "serieId": 2026,
  "entityKeyId": "C0001",
  "serviceOrderGuid": "GUID-DA-ORDEM",
  "documentBodies": [
    {
      "itemKeyId": "HORAS",
      "itemDescription": "Horas de intervenção",
      "quantity": 2.5,
      "retailPrice": 25.00,
      "taxId": 3,
      "originBodyGuid": "GUID-DA-INTERVENCAO",
      "relationType": "ServiceOrderInterventionHours"
    }
  ],
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 76.88
    }
  ]
}
KeyId vs Id do tipo de documento

O preview usa documentTypeKeyId (alfanumérico) e a emissão usa documentTypeId (numérico). Resolva sempre via GET /gateway/document-type — os IDs não são portáveis entre tenants.

Na emissão, a API valida que a origem SAT existe e é faturável, confirma que as linhas enviadas pertencem à ordem/intervenção declarada no cabeçalho, e associa o documento à ordem de serviço.

Depois de faturar​

  • GET /gateway/intervention/{guid}/billing-details
  • GET /gateway/service-order/{guid}/issued-documents
Documentos na intervenção vs na ordem

Se quem foi faturado foi a ordem de serviço, a intervenção deixa de listar essa fatura como documento próprio — só mostra os documentos que lhe pertencem de facto.

Seguinte​

RMA (fluxo paralelo) ou erros comuns.